spec: Define what non-empty authorization identity strings mean

The SASL RFC requires that we do this. I had previously thought that
the D-Bus protocol on Unix requires the use of numeric user IDs,
but in fact the reference implementation will also accept usernames.

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

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 4dacf1bd3472f9cba9aa9f4d60cea32af2a6645d..0de43f7a15bffdbfb7471745c8c4115fc88eba1f 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -2236,6 +2236,32 @@
       directly from the SASL specification. The message encoding is
       NOT used here, only plain text messages.
     </para>
+    <para>
+      Using SASL in D-Bus requires that we define the meaning of non-empty
+      authorization identity strings. When D-Bus is used on Unix platforms,
+      a non-empty SASL authorization identity represents a Unix user. An
+      authorization identity consisting entirely of ASCII decimal digits
+      represents a numeric user ID as defined by POSIX, for example
+      <literal>0</literal> for the root user or <literal>1000</literal>
+      for the first user created on many systems. Non-numeric authorization
+      identities are not required to be accepted or supported, but if used,
+      they must be interpreted as a login name as found in the
+      <literal>pw_name</literal> field of POSIX
+      <literal>struct passwd</literal>, for example
+      <literal>root</literal>, and normalized to the corresponding
+      numeric user ID. For best interoperability, clients and servers
+      should use numeric user IDs.
+    </para>
+    <para>
+      When D-Bus is used on Windows platforms, a non-empty SASL
+      authorization identity represents a Windows security identifier
+      (SID) in its string form, 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. The user-facing usernames such as
+      <literal>Administrator</literal> or <literal>LOCAL_SYSTEM</literal>
+      are not used in the D-Bus protocol.
+    </para>
     <para>
       In examples, "C:" and "S:" indicate lines sent by the client and
       server respectively. The client sends the first line, and the