spec: Make example authentication transactions more realistic

We don't need to invent a MAGIC_COOKIE mechanism when we have a
perfectly good EXTERNAL.

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 0de43f7a15bffdbfb7471745c8c4115fc88eba1f..f5669f078121c4667d249483bbb2400fec21563f 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -2557,11 +2557,12 @@
 
       <para>
         <figure>
-          <title>Example of successful magic cookie authentication</title>
+          <title>Example of successful EXTERNAL authentication</title>
           <programlisting>
-            (MAGIC_COOKIE is a made up mechanism)
+            31303030 is ASCII decimal "1000" represented in hex, so
+            the client is authenticating as Unix uid 1000 in this example.
 
-            C: AUTH MAGIC_COOKIE 3138363935333137393635383634
+            C: AUTH EXTERNAL 31303030
             S: OK 1234deadbeef
             C: BEGIN
           </programlisting>
@@ -2581,9 +2582,13 @@
         <figure>
           <title>Example of client sends unknown command then falls back to regular auth</title>
           <programlisting>
+            532d312d352d3138 is the Windows SID "S-1-5-18" in hex,
+            so the client is authenticating as Windows SID S-1-5-18
+            in this example.
+
             C: FOOBAR
             S: ERROR
-            C: AUTH MAGIC_COOKIE 3736343435313230333039
+            C: AUTH EXTERNAL 532d312d352d3138
             S: OK 1234deadbeef
             C: BEGIN
           </programlisting>
@@ -2591,7 +2596,7 @@
         <figure>
           <title>Example of server doesn't support initial auth mechanism</title>
           <programlisting>
-            C: AUTH MAGIC_COOKIE 3736343435313230333039
+            C: AUTH EXTERNAL
             S: REJECTED KERBEROS_V4 SKEY
             C: AUTH SKEY 7ab83f32ee
             S: DATA 8799cabb2ea93e
@@ -2603,7 +2608,7 @@
         <figure>
           <title>Example of wrong password or the like followed by successful retry</title>
           <programlisting>
-            C: AUTH MAGIC_COOKIE 3736343435313230333039
+            C: AUTH EXTERNAL 736d6376
             S: REJECTED KERBEROS_V4 SKEY
             C: AUTH SKEY 7ab83f32ee
             S: DATA 8799cabb2ea93e
@@ -2619,7 +2624,7 @@
         <figure>
           <title>Example of skey cancelled and restarted</title>
           <programlisting>
-            C: AUTH MAGIC_COOKIE 3736343435313230333039
+            C: AUTH EXTERNAL 32303438
             S: REJECTED KERBEROS_V4 SKEY
             C: AUTH SKEY 7ab83f32ee
             S: DATA 8799cabb2ea93e
@@ -2633,11 +2638,9 @@
           </programlisting>
         </figure>
         <figure>
-          <title>Example of successful magic cookie authentication with successful negotiation of Unix FD passing</title>
+          <title>Example of successful EXTERNAL authentication with successful negotiation of Unix FD passing</title>
           <programlisting>
-            (MAGIC_COOKIE is a made up mechanism)
-
-            C: AUTH MAGIC_COOKIE 3138363935333137393635383634
+            C: AUTH EXTERNAL 31303030
             S: OK 1234deadbeef
             C: NEGOTIATE_UNIX_FD
             S: AGREE_UNIX_FD
@@ -2645,14 +2648,12 @@
           </programlisting>
         </figure>
         <figure>
-          <title>Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</title>
+          <title>Example of successful EXTERNAL authentication with unsuccessful negotiation of Unix FD passing</title>
           <programlisting>
-            (MAGIC_COOKIE is a made up mechanism)
-
-            C: AUTH MAGIC_COOKIE 3138363935333137393635383634
+            C: AUTH EXTERNAL 31303030
             S: OK 1234deadbeef
             C: NEGOTIATE_UNIX_FD
-            S: ERROR
+            S: ERROR Not supported on this OS
             C: BEGIN
           </programlisting>
         </figure>