spec: Move text about the BEGIN command to documentation of BEGIN

Having the text about the message stream in the documentation
of AUTH seemed rather odd, and made it likely to get out of sync
with the rest of the spec. Move it to the BEGIN section, remove
some duplication, and make it clearer that if the client pipelines
the fd-negotiation, the server is expected to send exactly one
reply per non-BEGIN command before switching to the D-Bus wire protocol.

Signed-off-by: Simon McVittie <smcv@collabora.com>
Reviewed-by: Philip Withnall <withnall@endlessm.com>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=104224

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index a6b5e595b253042d4ac2347f9961dd27ada872ca..2852411e03f771c324078d6fb7f3ceab5e3acde2 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -2330,17 +2330,6 @@
         If authentication succeeds after exchanging DATA commands,
         an OK command must be sent to the client.
       </para>
-      <para>
-        The first octet received by the server after the \r\n of the BEGIN
-        command from the client must be the first octet of the
-        authenticated/encrypted stream of D-Bus messages.
-      </para>
-      <para>
-        If BEGIN is received by the server, the first octet received
-        by the client after the \r\n of the OK command must be the
-        first octet of the authenticated/encrypted stream of D-Bus
-        messages.
-      </para>
     </sect2>
     <sect2 id="auth-command-cancel">
       <title>CANCEL Command</title>
@@ -2367,7 +2356,8 @@
       <title>BEGIN Command</title>
       <para>
         The BEGIN command acknowledges that the client has received an
-        OK command from the server, and that the stream of messages
+        OK command from the server and completed any feature negotiation
+        that it wishes to do, and declares that the stream of messages
         is about to begin.
       </para>
       <para>
@@ -2375,6 +2365,13 @@
         command from the client must be the first octet of the
         authenticated/encrypted stream of D-Bus messages.
       </para>
+      <para>
+        Unlike all other commands, the server does not reply to
+        the BEGIN command with an authentication command of its own.
+        After the \r\n of the reply to the command before BEGIN,
+        the next octet received by the client must be the first octet
+        of the authenticated/encrypted stream of D-Bus messages.
+      </para>
     </sect2>
     <sect2 id="auth-command-rejected">
       <title>REJECTED Command</title>
@@ -2409,9 +2406,13 @@
         this protocol.
       </para>
       <para>
-        If a client sends BEGIN the first octet received by the client
+        If there is no negotiation, the first octet received by the client
         after the \r\n of the OK command must be the first octet of
-        the authenticated/encrypted stream of D-Bus messages.
+        the authenticated/encrypted stream of D-Bus messages. If the
+        client negotiates Unix file descriptor passing, the first
+        octet received by the client after the \r\n of the AGREE_UNIX_FD
+        or ERROR reply must be the first octet of the
+        authenticated/encrypted stream.
       </para>
       <para>
         The OK command has one argument, which is the GUID of the server.