diff options
-rw-r--r-- | ChangeLog | 5 | ||||
-rw-r--r-- | doc/TODO | 4 | ||||
-rw-r--r-- | doc/dbus-specification.xml | 157 |
3 files changed, 164 insertions, 2 deletions
@@ -1,3 +1,8 @@ +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. + 2003-10-28 David Zeuthen <david@fubar.dk> * python/dbus_bindings.pyx.in: add get_dict to handle dictionaries @@ -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, diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 42bd5138..5f62cfdd 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -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> |