spec: Describe the EXTERNAL and ANONYMOUS auth mechanisms

These are defined by standard RFCs rather than by D-Bus. What
separates them from other standard mechanisms like PLAIN (RFC 4616)
is that in practice, D-Bus implementations support EXTERNAL,
DBUS_COOKIE_SHA1 and sometimes ANONYMOUS, but not PLAIN.

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 f5669f078121c4667d249483bbb2400fec21563f..6e42839cbe8c80af82be6feb0ef6d8802257a71c 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -3111,18 +3111,59 @@
     <sect2 id="auth-mechanisms">
       <title>Authentication mechanisms</title>
       <para>
-        This section describes some new authentication mechanisms.
-        D-Bus also allows any standard SASL mechanism of course.
-      </para>
+        This section describes some authentication mechanisms that are
+        often supported by practical D-Bus implementations. The D-Bus
+        protocol also allows any other standard SASL mechanism, although
+        implementations of D-Bus often do not.
+      </para>
+      <sect3 id="auth-mechanisms-external">
+        <title>EXTERNAL</title>
+        <para>
+          The EXTERNAL mechanism is defined in <ulink
+            url="https://tools.ietf.org/html/rfc4422#appendix-A">RFC 4422
+            "Simple Authentication and Security Layer (SASL)", appendix A
+            "The SASL EXTERNAL Mechanism"</ulink>. This is the recommended
+          authentication mechanism on platforms where credentials can be
+          transferred out-of-band, in particular Unix platforms that can
+          perform credentials-passing over the
+          <link linkend="transports-unix-domain-sockets-addresses"
+            >unix: transport</link>.
+        </para>
+        <para>
+          On Unix platforms, interoperable clients should prefer to send
+          the ASCII decimal string form of the integer Unix user ID as
+          the authorization identity, for example 1000. When encoded in
+          hex by the authentication protocol, this will typically result
+          in a line like <literal>AUTH EXTERNAL 31303030</literal> followed
+          by \r\n.
+        </para>
+        <para>
+          On Windows platforms, clients that use the EXTERNAL mechanism
+          should use the Windows security identifier in its string form
+          as the authorization identity, for example
+          <literal>S-1-5-21-3623811015-3361044348-30300820-1013</literal> for
+          a domain or local computer user or <literal>S-1-5-18</literal> for
+          the LOCAL_SYSTEM user. When encoded in hex by the authentication
+          protocol, this will typically result in a line like
+          <literal>AUTH EXTERNAL 532d312d352d3138</literal> followed by
+          \r\n.
+        </para>
+      </sect3>
       <sect3 id="auth-mechanisms-sha">
         <title>DBUS_COOKIE_SHA1</title>
         <para>
-          The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
+          DBUS_COOKIE_SHA1 is a D-Bus-specific SASL mechanism. Its
+          reference implementation is part of the reference implementation
+          of D-Bus.
+        </para>
+        <para>
+          This mechanism is designed to establish that a client
           has the ability to read a private file owned by the user being
           authenticated. If the client can prove that it has access to a secret
           cookie stored in this file, then the client is authenticated.
           Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
-          directory.
+          directory. This is the recommended authentication mechanism
+          for platforms and configurations where EXTERNAL cannot be used.
         </para>
         <para>
           Throughout this description, "hex encoding" must output the digits
@@ -3258,6 +3299,18 @@
           because servers are required to save the file atomically.
         </para>
       </sect3>
+      <sect3 id="auth-mechanisms-anonymous">
+        <title>ANONYMOUS</title>
+        <para>
+          The ANONYMOUS mechanism is defined in <ulink
+            url="https://tools.ietf.org/html/rfc4505">RFC 4505 "Anonymous
+            Simple Authentication and Security Layer (SASL)
+            Mechanism"</ulink>.
+          It does not perform any authentication at all, and should not
+          be accepted by message buses. However, it might sometimes be
+          useful for non-message-bus uses of D-Bus.
+        </para>
+      </sect3>
     </sect2>
   </sect1>
   <sect1 id="addresses">