[RFC PATCH 6/6] Documentation: uid_r: describe ksmbd's SID mapping

[Jan Koester]

Name the SIDs ksmbd gives classic users and groups, and describe
KSMBD_EVENT_SID_MAP_REQUEST: what user space is asked, the caching and
what happens when it can't answer.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Jan Koester <jan.koester@xxxxxxxxx>
---
 Documentation/userspace-api/uid_r.rst | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/Documentation/userspace-api/uid_r.rst b/Documentation/userspace-api/uid_r.rst
index d16d4317f5..2e887c296d 100644
--- a/Documentation/userspace-api/uid_r.rst
+++ b/Documentation/userspace-api/uid_r.rst
@@ -167,7 +167,23 @@ SMB (ksmbd)
 	groups appear in security descriptors as
 	``S-1-22-<kind>-w0-w1-w2-w3``: kind 3 and 4 for a UUID user and group,
 	5 and 6 for a GUID user and group, w0 to w3 the 16 bytes of the id as
-	big endian words.
+	big endian words; classic users as ``S-1-22-1-<uid>``, classic groups
+	as ``S-1-22-2-<gid>``.
+
+	A user space that sets ``KSMBD_GLOBAL_FLAG_SID_MAP`` at startup is
+	asked (``KSMBD_EVENT_SID_MAP_REQUEST``) for the Windows SID of every id
+	ksmbd shows as owner, group or ACL entry and for the id of every
+	domain SID (``S-1-5-21-...``) a client sets, also for accounts that
+	are not logged in. A mapped account appears with its own SID (e.g. a
+	directory's ``objectSid``), others keep the SIDs above. ksmbd caches
+	mappings for five minutes and "no mapping" for one; an answer user
+	space couldn't give is not cached: descriptors then show the SIDs
+	above, and setting an owner, group or ACL that needs a mapping fails
+	with ``STATUS_NO_LOGON_SERVERS`` instead of being applied in part. A
+	domain SID that maps to no user (as owner) or group (as group) is
+	refused with ``STATUS_INVALID_OWNER`` or ``STATUS_INVALID_PRIMARY_GROUP``
+	rather than ignored. A session's user matches ACL entries naming its
+	own or its groups' SIDs, mapped or not.
 
 NFSv4
 	Owners and ACL principals that are UUIDs or GUIDs travel as their text
-- 
2.56.0