<cmdsynopsis>
<command>systemd-creds</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
+ <arg choice="plain">COMMAND</arg>
+ <arg choice="opt" rep="repeat">ARGS</arg>
</cmdsynopsis>
</refsynopsisdiv>
processes. They are primarily used for passing cryptographic keys (both public and private) or
certificates, user account information or identity information from the host to services.</para>
- <para>Credentials are configured in unit files via the <varname>LoadCredential=</varname>,
- <varname>SetCredential=</varname>, <varname>LoadCredentialEncrypted=</varname> and
- <varname>SetCredentialEncrypted=</varname> settings, see
+ <para>Credentials are configured in unit files via the <varname>ImportCredential></varname>,
+ <varname>LoadCredential=</varname>, <varname>SetCredential=</varname>,
+ <varname>LoadCredentialEncrypted=</varname> and <varname>SetCredentialEncrypted=</varname> settings, see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details.</para>
+
+ <para>For further information see <ulink url="https://systemd.io/CREDENTIALS">System and Service
+ Credentials</ulink> documentation.</para>
</refsect1>
<refsect1>
<varlistentry>
<term><command>setup</command></term>
- <listitem><para>Generates a host encryption key for credentials, if none has been generated
- before. This ensures the <filename>/var/lib/systemd/credential.secret</filename> file is initialized
+ <listitem><para>Generates a host encryption key for credentials, if one has not been generated
+ already. This ensures the <filename>/var/lib/systemd/credential.secret</filename> file is initialized
with a random secret key if it doesn't exist yet. This secret key is used when encrypting/decrypting
credentials with <command>encrypt</command> or <command>decrypt</command>, and is only accessible to
the root user. Note that there's typically no need to invoke this command explicitly as it is
</varlistentry>
<varlistentry>
- <term><command>encrypt</command> <replaceable>input</replaceable> <replaceable>output</replaceable></term>
+ <term><command>encrypt</command> <replaceable>input|-</replaceable> <replaceable>output|-</replaceable></term>
<listitem><para>Loads the specified (unencrypted plaintext) input credential file, encrypts it and
- writes the (encrypted ciphertext) version to the specified output credential file. The resulting file
+ writes the (encrypted ciphertext) output to the specified target credential file. The resulting file
may be referenced in the <varname>LoadCredentialEncrypted=</varname> setting in unit files, or its
contents used literally in <varname>SetCredentialEncrypted=</varname> settings.</para>
output path is specified as <literal>-</literal> the credential name cannot be derived from the file
system path, and thus should be specified explicitly via the <option>--name=</option> switch.</para>
- <para>The credential data is encrypted symmetrically with one of the following encryption
- keys:</para>
+ <para>The credential data is encrypted and authenticated symmetrically with one of the following
+ encryption keys:</para>
<orderedlist>
<listitem><para>A secret key automatically derived from the system's TPM2 chip. This encryption key
</orderedlist>
<para>Which of the three keys shall be used for encryption may be configured with the
- <option>--with-key=</option> switch. Depending on the use-case for the encrypted credential the key to
- use may differ. For example, for credentials that shall be accessible from the initial RAM disk
- (initrd) of the system encryption with the host key is not appropriate since access to the host key
- is typically not available from the initrd. Thus, for such credentials only the TPM2 key should be
- used.</para>
+ <option>--with-key=</option> switch. Depending on the use-case for the encrypted credential the key
+ to use may differ. For example, for credentials that shall be accessible from the initrd, encryption
+ with the host key is not appropriate, since access to the host key is typically not available from
+ the initrd. Thus, for such credentials only the TPM2 key should be used.</para>
<para>Encrypted credentials are always encoded in Base64.</para>
</varlistentry>
<varlistentry>
- <term><command>decrypt</command> <replaceable>input</replaceable>
- <optional><replaceable>output</replaceable></optional></term>
+ <term><command>decrypt</command> <replaceable>input|-</replaceable>
+ <optional><replaceable>output|-</replaceable></optional></term>
<listitem><para>Undoes the effect of the <command>encrypt</command> operation: loads the specified
- (encrypted ciphertext) input credential file, decrypts it and writes the (decrypted plaintext)
- version to the specified output credential file.</para>
+ (encrypted ciphertext) input credential file, decrypts and authenticates it and writes the (decrypted
+ plaintext) output to the specified target credential file.</para>
<para>Takes one or two file system paths. The file name part of the input path is compared with the
credential name embedded in the encrypted file. If it does not match decryption fails. This is done
in order to ensure that encrypted credentials are not re-purposed without this being detected. The
credential name to compare with the embedded credential name may also be overridden with the
- <option>--name=</option> switch. If only one path is specified (or the output path specified as
- <literal>-</literal>) it is taken as input path and the decrypted credential is written to standard
- output. If the input path is specified as <literal>-</literal> the encrypted credential is read from
- standard input. In this mode, the expected name embedded in the credential cannot be derived from the
- path and should be specified explicitly with <option>--name=</option>.</para>
+ <option>--name=</option> switch. If the input path is specified as <literal>-</literal>, the
+ encrypted credential is read from standard input. If only one path is specified or the output path
+ specified as <literal>-</literal>, the decrypted credential is written to standard output. In this
+ mode, the expected name embedded in the credential cannot be derived from the path and should be
+ specified explicitly with <option>--name=</option>.</para>
<para>Decrypting credentials requires access to the original TPM2 chip and/or credentials host key,
see above. Information about which keys are required is embedded in the encrypted credential data,
and thus decryption is entirely automatic.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><command>has-tpm2</command></term>
+
+ <listitem><para>Reports whether the system is equipped with a TPM2 device usable for protecting
+ credentials. If a TPM2 device has been discovered, is supported, and is being used by firmware,
+ by the OS kernel drivers and by userspace (i.e. systemd) this prints <literal>yes</literal> and exits
+ with exit status zero. If no such device is discovered/supported/used, prints
+ <literal>no</literal>. Otherwise prints <literal>partial</literal>. In either of these two cases
+ exits with non-zero exit status. It also shows four lines indicating separately whether firmware,
+ drivers, the system and the kernel discovered/support/use TPM2.</para>
+
+ <para>Combine with <option>--quiet</option> to suppress the output.</para></listitem>
+ </varlistentry>
+
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
<listitem><para>When specified with <command>encrypt</command> controls whether to show the encrypted
credential as <varname>SetCredentialEncrypted=</varname> setting that may be pasted directly into a
- unit file.</para></listitem>
+ unit file. Has effect only when used together with <option>--name=</option> and <literal>-</literal>
+ as the output file.</para></listitem>
</varlistentry>
<varlistentry>
<listitem><para>When specified with the <command>encrypt</command> command controls the timestamp to
embed into the encrypted credential. Defaults to the current time. Takes a timestamp specification in
the format described in
- <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+ <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
<para>When specified with the <command>decrypt</command> command controls the timestamp to use to
validate the "not-after" timestamp that was configured with <option>--not-after=</option> during
credential. During decryption the timestamp is checked against the current system clock, and if the
timestamp is in the past the decryption will fail. By default no such timestamp is set. Takes a
timestamp specification in the format described in
- <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+ <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-H</option></term>
<term><option>-T</option></term>
- <listitem><para>When specified with the <command>encrypt</command> command controls the encryption
- key to use. Takes one of <literal>host</literal>, <literal>tpm2</literal>,
- <literal>host+tpm2</literal> or <literal>auto</literal>. See above for details on the three key
- types. If set to <literal>auto</literal> (which is the default) the TPM2 key is used if a TPM2 device
- is found and not running in a container. The host key is used if
- <filename>/var/lib/systemd/</filename> is on persistent media. This means on typical systems the
- encryption is by default bound to both the TPM2 chip and the OS installation, and both need to be
- available to decrypt the credential again. If <literal>auto</literal> is selected but neither TPM2 is
- available (or running in container) nor <filename>/var/lib/systemd/</filename> is on persistent
- media, encryption will fail.</para>
+ <listitem><para>When specified with the <command>encrypt</command> command controls the
+ encryption/signature key to use. Takes one of <literal>host</literal>, <literal>tpm2</literal>,
+ <literal>host+tpm2</literal>, <literal>tpm2-absent</literal>, <literal>auto</literal>,
+ <literal>auto-initrd</literal>. See above for details on the three key types. If set to
+ <literal>auto</literal> (which is the default) the TPM2 key is used if a TPM2 device is found and not
+ running in a container. The host key is used if <filename>/var/lib/systemd/</filename> is on
+ persistent media. This means on typical systems the encryption is by default bound to both the TPM2
+ chip and the OS installation, and both need to be available to decrypt the credential again. If
+ <literal>auto</literal> is selected but neither TPM2 is available (or running in container) nor
+ <filename>/var/lib/systemd/</filename> is on persistent media, encryption will fail. If set to
+ <literal>tpm2-absent</literal> a fixed zero length key is used (thus, in this mode no confidentiality
+ nor authenticity are provided!). This logic is useful to cover for systems that lack a TPM2 chip but
+ where credentials shall be generated. Note that decryption of such credentials is refused on systems
+ that have a TPM2 chip and where UEFI SecureBoot is enabled (this is done so that such a locked down
+ system cannot be tricked into loading a credential generated this way that lacks authentication
+ information). If set to <literal>auto-initrd</literal> a TPM2 key is used if a TPM2 is found. If not
+ a fixed zero length key is used, equivalent to <literal>tpm2-absent</literal> mode. This option is
+ particularly useful to generate credentials files that are encrypted/authenticated against TPM2 where
+ available but still work on systems lacking support for this.</para>
<para>The <option>-H</option> switch is a shortcut for <option>--with-key=host</option>. Similar,
- <option>-T</option> is a shortcut for <option>-with-key=tpm2</option>.</para>
+ <option>-T</option> is a shortcut for <option>--with-key=tpm2</option>.</para>
- <para>When encrypting credentials that shall be used in the initial RAM disk (initrd) where
- <filename>/var/lib/systemd/</filename> is typically not available make sure to use
- <option>--with-key=tpm2</option> mode, to disable binding against the host secret.</para>
+ <para>When encrypting credentials that shall be used in the initrd (where
+ <filename>/var/lib/systemd/</filename> is typically not available) make sure to use
+ <option>--with-key=auto-initrd</option> mode, to disable binding against the host secret.</para>
<para>This switch has no effect on the <command>decrypt</command> command, as information on which
key to use for decryption is included in the encrypted credential already.</para></listitem>
<citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--tpm2-public-key=</option><arg>PATH</arg></term>
+ <term><option>--tpm2-public-key-pcrs=</option><arg rep="repeat">PCR</arg></term>
+
+ <listitem><para>Configures a TPM2 signed PCR policy to bind encryption to, for use with the
+ <command>encrypt</command> command. The <option>--tpm2-public-key=</option> option accepts a path to
+ a PEM encoded RSA public key, to bind the encryption to. If this is not specified explicitly, but a
+ file <filename>tpm2-pcr-public-key.pem</filename> exists in one of the directories
+ <filename>/etc/systemd/</filename>, <filename>/run/systemd/</filename>,
+ <filename>/usr/lib/systemd/</filename> (searched in this order), it is automatically used. The
+ <option>--tpm2-public-key-pcrs=</option> option takes a list of TPM2 PCR indexes to bind to (same
+ syntax as <option>--tpm2-pcrs=</option> described above). If not specified defaults to 11 (i.e. this
+ binds the policy to any unified kernel image for which a PCR signature can be provided).</para>
+
+ <para>Note the difference between <option>--tpm2-pcrs=</option> and
+ <option>--tpm2-public-key-pcrs=</option>: the former binds decryption to the current, specific PCR
+ values; the latter binds decryption to any set of PCR values for which a signature by the specified
+ public key can be provided. The latter is hence more useful in scenarios where software updates shall
+ be possible without losing access to all previously encrypted secrets.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--tpm2-signature=</option><arg>PATH</arg></term>
+
+ <listitem><para>Takes a path to a TPM2 PCR signature file as generated by the
+ <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ tool and that may be used to allow the <command>decrypt</command> command to decrypt credentials that
+ are bound to specific signed PCR values. If this is not specified explicitly, and a credential
+ with a signed PCR policy is attempted to be decrypted, a suitable signature file
+ <filename>tpm2-pcr-signature.json</filename> is searched for in <filename>/etc/systemd/</filename>,
+ <filename>/run/systemd/</filename>, <filename>/usr/lib/systemd/</filename> (in this order) and
+ used.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--quiet</option></term>
+ <term><option>-q</option></term>
+
+ <listitem><para>When used with <command>has-tpm2</command> suppresses the output, and only returns an
+ exit status indicating support for TPM2.</para></listitem>
+ </varlistentry>
+
<xi:include href="standard-options.xml" xpointer="no-pager" />
<xi:include href="standard-options.xml" xpointer="no-legend" />
<xi:include href="standard-options.xml" xpointer="json" />
<title>Exit status</title>
<para>On success, 0 is returned.</para>
+
+ <para>In case of the <command>has-tpm2</command> command returns 0 if a TPM2 device is discovered,
+ supported and used by firmware, driver, and userspace (i.e. systemd). Otherwise returns the OR
+ combination of the value 1 (in case firmware support is missing), 2 (in case driver support is missing)
+ and 4 (in case userspace support is missing). If no TPM2 support is available at all, value 7 is hence
+ returned.</para>
</refsect1>
<refsect1>
<filename>xyz.service</filename>:</para>
<programlisting># mkdir -p /etc/systemd/system/xyz.service.d
-# systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - - > /etc/systemd/system/xyz.service.d/50-password.conf
+# systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - - >/etc/systemd/system/xyz.service.d/50-password.conf
# systemctl daemon-reload
# systemctl restart xyz.service</programlisting>
</example>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
projects / thirdparty / systemd.git / blobdiff