From 0fb386a1a5b5089bfa70cfe1a589fb1acbe00b42 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@collabora.com>
Date: Tue, 12 Dec 2017 13:10:11 +0000
Subject: [PATCH 7/9] 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>
---
 doc/dbus-specification.xml | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 30f59dee..a3aa04ef 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -2203,6 +2203,31 @@
       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. Any other authorization
+      identity represents a login name as found in the
+      <literal>pw_name</literal> field of POSIX
+      <literal>struct passwd</literal>, for example
+      <literal>root</literal>, and will be 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
-- 
2.15.1