From 2e9c2dadef9bce562ed46b4a9f94ba23063c1e43 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@collabora.com>
Date: Tue, 12 Dec 2017 13:19:51 +0000
Subject: [PATCH 8/9] 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>

---

v2: Put a human-readable error message in one of the two uses of ERROR.
    Leave the response to FOOBAR as just a bare ERROR, to emphasize
    that both are possible.
---
 doc/dbus-specification.xml | 33 +++++++++++++++++----------------
 1 file changed, 17 insertions(+), 16 deletions(-)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index af5ad63d..77569d1d 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -2524,11 +2524,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>
@@ -2548,9 +2549,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>
@@ -2558,7 +2563,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
@@ -2570,7 +2575,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
@@ -2586,7 +2591,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
@@ -2600,11 +2605,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
@@ -2612,14 +2615,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>
-- 
2.15.1