man: document new user-scoped credentials

diff --git a/man/systemd-creds.xml b/man/systemd-creds.xml
index 5f52540e84e8728a0dd73ed470e2f0b1186f1e67..2650dddd7ea13fc80bc22d7eb21640a2e9a6572e 100644 (file)
--- 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 42e6ff8fd751433b2754d92e42d93cce66e1c6a5..ca20e6e308130b007288d77e84e88b7ed33c12ec 100644 (file)
--- 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