diff options
Diffstat (limited to 'doc/dbus-specification.xml')
| -rw-r--r-- | doc/dbus-specification.xml | 157 |
1 files changed, 156 insertions, 1 deletions
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> |