From 8decfd112b57228ca4afb13f045b87ec9909fc4e Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@collabora.com>
Date: Mon, 11 Dec 2017 17:39:31 +0000
Subject: [PATCH 5/9] spec: Document NEGOTIATE_UNIX_FD, AGREE_UNIX_FD in state
 machines

Signed-off-by: Simon McVittie <smcv@collabora.com>

---

v2:
- Previously the choice of BEGIN vs. NEGOTIATE_UNIX_FD was only
  offered in WaitingForOK state, but in fact it can also happen in
  WaitingForData state (and real D-Bus clients never reach WaitingForOK,
  because we don't implement any mechanisms where the client knows
  that it has been accepted before the server says so).
- Attempt to clarify that when the client sends BEGIN, it is
  terminating the auth conversation successfully. I deliberately
  didn't say 'authenticated' here in the WaitingForAgreeUnixFD case,
  because conceptually the client is already successfully authenticated
  *before* it sends NEGOTIATE_UNIX_FD.
---
 doc/dbus-specification.xml | 68 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 63 insertions(+), 5 deletions(-)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 3cb41dad..02d2b4ae 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -2706,9 +2706,19 @@
               </listitem>
               <listitem>
                 <para>
-                  Receive OK &rarr; send
-                  BEGIN, terminate auth
-                  conversation, authenticated
+                  Receive OK &rarr; <emphasis>authenticated</emphasis>,
+                  choose one:
+
+                  <simplelist>
+                    <member>
+                      send NEGOTIATE_UNIX_FD, goto
+                      <emphasis>WaitingForAgreeUnixFD</emphasis>
+                    </member>
+
+                    <member>
+                      send BEGIN, terminate auth conversation (successfully)
+                    </member>
+                  </simplelist>
                 </para>
               </listitem>
               <listitem>
@@ -2728,8 +2738,19 @@
             <itemizedlist>
               <listitem>
                 <para>
-                  Receive OK &rarr; send BEGIN, terminate auth
-                  conversation, <emphasis>authenticated</emphasis>
+                  Receive OK &rarr; <emphasis>authenticated</emphasis>,
+                  choose one:
+
+                  <simplelist>
+                    <member>
+                      send NEGOTIATE_UNIX_FD, goto
+                      <emphasis>WaitingForAgreeUnixFD</emphasis>
+                    </member>
+
+                    <member>
+                      send BEGIN, terminate auth conversation (successfully)
+                    </member>
+                  </simplelist>
                 </para>
               </listitem>
               <listitem>
@@ -2786,6 +2807,36 @@
           </para>
         </formalpara>
 
+        <formalpara>
+          <title><emphasis>WaitingForAgreeUnixFD</emphasis></title>
+          <para>
+            By the time this state is reached, the client has already
+            been authenticated.
+            <itemizedlist>
+              <listitem>
+                <para>
+                  Receive AGREE_UNIX_FD &rarr; enable Unix fd passing,
+                  send BEGIN, terminate auth conversation (successfully)
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  Receive ERROR &rarr; disable Unix fd passing,
+                  send BEGIN, terminate auth conversation (successfully)
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  Receive anything else &rarr; terminate auth
+                  conversation, disconnect
+                </para>
+              </listitem>
+            </itemizedlist>
+          </para>
+        </formalpara>
+
       </sect3>
 
       <sect3 id="auth-states-server">
@@ -2963,6 +3014,13 @@
                 </para>
               </listitem>
 
+              <listitem>
+                <para>
+                  Receive NEGOTIATE_UNIX_FD &rarr; send AGREE_UNIX_FD
+                  or ERROR, goto <emphasis>WaitingForBegin</emphasis>
+                </para>
+              </listitem>
+
               <listitem>
                 <para>
                   Receive CANCEL &rarr; send REJECTED [mechs], goto
-- 
2.15.1