dbus/doc TODO,1.33,1.34 dbus-specification.xml,1.3,1.4
Havoc Pennington
hp@pdx.freedesktop.org
Sat, 01 Nov 2003 10:24:34 -0800
Update of /cvs/dbus/dbus/doc
In directory pdx:/tmp/cvs-serv17819/doc
Modified Files:
TODO dbus-specification.xml
Log Message:
2003-11-01 Havoc Pennington <hp@redhat.com>
* doc/dbus-specification.xml: add state machine docs on the auth
protocol; just a first draft, I'm sure it's wrong.
Index: TODO
===================================================================
RCS file: /cvs/dbus/dbus/doc/TODO,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -d -r1.33 -r1.34
--- TODO 22 Oct 2003 16:01:08 -0000 1.33
+++ TODO 1 Nov 2003 18:24:32 -0000 1.34
@@ -102,7 +102,9 @@
dbus_message_get_args() which takes a DBusError.
Probably we need to either fully encapsulate and hide
dbus/dbus.h, or encapsulate it slightly less e.g. no
- GError.
+ GError. Or maybe it's as simple as "never return dbus_malloc()
+ memory" and just fully encapsulate the get_args() type of
+ stuff.
- need to define bus behavior if you send a message to
yourself; is it an error, or allowed? If allowed,
Index: dbus-specification.xml
===================================================================
RCS file: /cvs/dbus/dbus/doc/dbus-specification.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- dbus-specification.xml 21 Oct 2003 05:46:52 -0000 1.3
+++ dbus-specification.xml 1 Nov 2003 18:24:32 -0000 1.4
@@ -1048,8 +1048,163 @@
<title>Authentication state diagrams</title>
<para>
- WRITEME
+ This section documents the auth protocol in terms of
+ a state machine for the client and the server. This is
+ probably the most robust way to implement the protocol.
</para>
+
+ <sect3 id="auth-states-client">
+ <title>Client states</title>
+
+ <formalpara>
+ <title><emphasis>Start</emphasis></title>
+ <para>
+ <itemizedlist>
+ <listitem><para>send AUTH with initial data -> <emphasis>WaitingForData</emphasis></para></listitem>
+ <listitem><para>send AUTH with no initial data -> <emphasis>WaitingForData</emphasis> or <emphasis>NeedSendData</emphasis> (depends on mechanism)</para></listitem>
+ </itemizedlist>
+ The <emphasis>Start</emphasis> state is stateful (it has a list of
+ available mechanisms and those it has already attempted). This list
+ is used to decide which AUTH command to send. When the list is
+ exhausted, the client should give up and close the connection.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><emphasis>WaitingForData</emphasis></title>
+ <para>
+
+ <itemizedlist>
+ <listitem><para>receive OK -> <emphasis>NeedSendBegin</emphasis></para></listitem>
+ <listitem><para>receive REJECTED -> <emphasis>Start</emphasis></para></listitem>
+ <listitem><para>receive ERROR -> <emphasis>Start</emphasis></para></listitem>
+ <listitem><para>receive DATA -> <emphasis>NeedSendData</emphasis></para></listitem>
+ <listitem><para>receive anything else -> <emphasis>NeedSendError</emphasis></para></listitem>
+ </itemizedlist>
+ When going back to <emphasis>Start</emphasis>, the mechanism in
+ progress should be marked as failed and not retried (at least not
+ with the same parameters). When receiving REJECTED with a list of
+ mechanisms, the list should be recorded and used to select
+ a mechanism.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><emphasis>NeedSendData</emphasis></title>
+ <para>
+ <itemizedlist>
+ <listitem><para>send DATA -> <emphasis>WaitingForData</emphasis></para></listitem>
+ <listitem><para>send CANCEL -> <emphasis>Start</emphasis></para></listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><emphasis>NeedSendError</emphasis></title>
+ <para>
+
+ <itemizedlist>
+ <listitem><para>send ERROR -> return to previous state</para></listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><emphasis>NeedSendBegin</emphasis></title>
+ <para>
+
+ <itemizedlist>
+ <listitem><para>send BEGIN -> Authorized</para></listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><emphasis>Authorized</emphasis></title>
+ <para>
+ This is the end state, flow of messages begins.
+ </para>
+ </formalpara>
+
+ </sect3>
+
+ <sect3 id="auth-states-server">
+ <title>Server states</title>
+
+ <formalpara>
+ <title><emphasis>WaitingForAuth</emphasis></title>
+ <para>
+ <itemizedlist>
+ <listitem><para>receive AUTH with initial response -> <emphasis>NeedSendData</emphasis></para></listitem>
+ <listitem><para>receive AUTH without initial response -> <emphasis>NeedSendData</emphasis> or <emphasis>WaitingForData</emphasis> depending on mechanism</para></listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><emphasis>NeedSendData</emphasis></title>
+ <para>
+ <itemizedlist>
+ <listitem><para>send DATA -> <emphasis>WaitingForData</emphasis></para></listitem>
+ <listitem><para>send ERROR -> <emphasis>WaitingForData</emphasis></para></listitem>
+ <listitem><para>send REJECTED -> <emphasis>WaitingForAuth</emphasis></para></listitem>
+ <listitem><para>send OK -> <emphasis>WaitingForBegin</emphasis></para></listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><emphasis>WaitingForData</emphasis></title>
+ <para>
+ <itemizedlist>
+ <listitem><para>receive DATA -> <emphasis>NeedSendData</emphasis></para></listitem>
+ <listitem><para>receive CANCEL -> <emphasis>NeedSendRejected</emphasis></para></listitem>
+ <listitem><para>receive ERROR -> <emphasis>NeedSendRejected</emphasis></para></listitem>
+ <listitem><para>receive anything else -> <emphasis>NeedSendError</emphasis></para></listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><emphasis>NeedSendError</emphasis></title>
+ <para>
+
+ <itemizedlist>
+ <listitem><para>send ERROR -> return to previous state</para></listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><emphasis>NeedSendRejected</emphasis></title>
+ <para>
+
+ <itemizedlist>
+ <listitem><para>send REJECTED -> <emphasis>WaitingForAuth</emphasis></para></listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><emphasis>WaitingForBegin</emphasis></title>
+ <para>
+
+ <itemizedlist>
+ <listitem><para>receive BEGIN -> <emphasis>Authorized</emphasis></para></listitem>
+ <listitem><para>receive anything else -> <emphasis>NeedSendError</emphasis></para></listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title><emphasis>Authorized</emphasis></title>
+ <para>
+ This is the end state, flow of messages begins.
+ </para>
+ </formalpara>
+
+ </sect3>
+
</sect2>
<sect2 id="auth-mechanisms">
<title>Authentication mechanisms</title>