From 7704c3474d0f3176f5d84efee5f44f9d815e615f Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 16 Jan 2024 16:56:12 +0100
Subject: [PATCH] man: document new user-scoped credentials

---
 man/systemd-creds.xml | 30 ++++++++++++++++++++++++++++++
 man/systemd.exec.xml  |  6 ++++++
 2 files changed, 36 insertions(+)

diff --git a/man/systemd-creds.xml b/man/systemd-creds.xml
index 5f52540e84e..2650dddd7ea 100644
--- a/man/systemd-creds.xml
+++ b/man/systemd-creds.xml
@@ -214,6 +214,36 @@
         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--user</option></term>
+
+        <listitem><para>When specified with the <command>encrypt</command> and <command>decrypt</command>
+        commands encrypts a user-scoped (rather than a system-scoped) credential. Use <option>--uid=</option>
+        to select which user the credential is from. Such credentials may only be decrypted from the
+        specified user's context, except if privileges can be acquired. Generally, when an encrypted
+        credential shall be used in the per-user service manager it should be encrypted with this option set,
+        when it shall be used in the system service manager it should be encypted without.</para>
+
+        <para>Internally, this ensures that the selected user's numeric UID and username, as well as the
+        system's
+        <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> are
+        incorporated into the encryption key.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--uid=</option></term>
+
+        <listitem><para>Specifies the user to encrypt the credential for. Takes a user name or numeric
+        UID. If set, implies <option>--user</option>. If set to the special string <literal>self</literal>
+        sets the user to the user of the calling process. If <option>--user</option> is used without
+        <option>--uid=</option> then <option>--uid=self</option> is implied, i.e. the credential is encrypted
+        for the calling user.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><option>--transcode=</option></term>
 
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 42e6ff8fd75..ca20e6e3081 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -3396,6 +3396,12 @@ StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZX
         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
         for the details about <varname>DevicePolicy=</varname> or <varname>DeviceAllow=</varname>.</para>
 
+        <para>Note that encrypted credentials targeted for services of the per-user service manager must be
+        encrypted with <command>systemd-creds encrypt --user</command>, and those for the system service
+        manager without the <option>--user</option> switch. Encrypted credentials are always targeted to a
+        specific user or the system as a whole, and it is ensured that per-user service managers cannot
+        decrypt secrets intended for the system or for other users.</para>
+
         <para>The credential files/IPC sockets must be accessible to the service manager, but don't have to
         be directly accessible to the unit's processes: the credential data is read and copied into separate,
         read-only copies for the unit that are accessible to appropriately privileged processes. This is