]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/systemd-creds.xml
Merge pull request #24555 from medhefgo/bootctl
[thirdparty/systemd.git] / man / systemd-creds.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6 <refentry id="systemd-creds"
7 xmlns:xi="http://www.w3.org/2001/XInclude">
8
9 <refentryinfo>
10 <title>systemd-creds</title>
11 <productname>systemd</productname>
12 </refentryinfo>
13
14 <refmeta>
15 <refentrytitle>systemd-creds</refentrytitle>
16 <manvolnum>1</manvolnum>
17 </refmeta>
18
19 <refnamediv>
20 <refname>systemd-creds</refname>
21 <refpurpose>Lists, shows, encrypts and decrypts service credentials</refpurpose>
22 </refnamediv>
23
24 <refsynopsisdiv>
25 <cmdsynopsis>
26 <command>systemd-creds</command>
27 <arg choice="opt" rep="repeat">OPTIONS</arg>
28 <arg choice="plain">COMMAND</arg>
29 <arg choice="opt" rep="repeat">ARGS</arg>
30 </cmdsynopsis>
31 </refsynopsisdiv>
32
33 <refsect1>
34 <title>Description</title>
35
36 <para><command>systemd-creds</command> is a tool for listing, showing, encrypting and decrypting unit
37 credentials. Credentials are limited-size binary or textual objects that may be passed to unit
38 processes. They are primarily used for passing cryptographic keys (both public and private) or
39 certificates, user account information or identity information from the host to services.</para>
40
41 <para>Credentials are configured in unit files via the <varname>LoadCredential=</varname>,
42 <varname>SetCredential=</varname>, <varname>LoadCredentialEncrypted=</varname> and
43 <varname>SetCredentialEncrypted=</varname> settings, see
44 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
45 details.</para>
46
47 <para>For further information see <ulink url="https://systemd.io/CREDENTIALS">System and Service
48 Credentials</ulink> documentation.</para>
49 </refsect1>
50
51 <refsect1>
52 <title>Commands</title>
53
54 <para>The following commands are understood:</para>
55
56 <variablelist>
57 <varlistentry>
58 <term><command>list</command></term>
59
60 <listitem><para>Show a list of credentials passed into the current execution context. This command
61 shows the files in the directory referenced by the <varname>$CREDENTIALS_DIRECTORY</varname>
62 environment variable, and is intended to be executed from within service context.</para>
63
64 <para>Along with each credential name, the size and security state is shown. The latter is one of
65 <literal>secure</literal> (in case the credential is backed by unswappable memory,
66 i.e. <literal>ramfs</literal>), <literal>weak</literal> (in case it is backed by any other type of
67 memory), or <literal>insecure</literal> (if having any access mode that is not 0400, i.e. if readable
68 by anyone but the owner).</para></listitem>
69 </varlistentry>
70
71 <varlistentry>
72 <term><command>cat</command> <replaceable>credential...</replaceable></term>
73
74 <listitem><para>Show contents of specified credentials passed into the current execution
75 context. Takes one or more credential names, whose contents shall be written to standard
76 output.</para>
77
78 <para>When combined with <option>--json=</option> or <option>--transcode=</option> the output is
79 transcoded in simple ways before outputting.</para></listitem>
80 </varlistentry>
81
82 <varlistentry>
83 <term><command>setup</command></term>
84
85 <listitem><para>Generates a host encryption key for credentials, if one has not been generated
86 already. This ensures the <filename>/var/lib/systemd/credential.secret</filename> file is initialized
87 with a random secret key if it doesn't exist yet. This secret key is used when encrypting/decrypting
88 credentials with <command>encrypt</command> or <command>decrypt</command>, and is only accessible to
89 the root user. Note that there's typically no need to invoke this command explicitly as it is
90 implicitly called when <command>encrypt</command> is invoked, and credential host key encryption
91 selected.</para></listitem>
92 </varlistentry>
93
94 <varlistentry>
95 <term><command>encrypt</command> <replaceable>input|-</replaceable> <replaceable>output|-</replaceable></term>
96
97 <listitem><para>Loads the specified (unencrypted plaintext) input credential file, encrypts it and
98 writes the (encrypted ciphertext) output to the specified target credential file. The resulting file
99 may be referenced in the <varname>LoadCredentialEncrypted=</varname> setting in unit files, or its
100 contents used literally in <varname>SetCredentialEncrypted=</varname> settings.</para>
101
102 <para>Takes two file system paths. The file name part of the output path is embedded as name in the
103 encrypted credential, to ensure encrypted credentials cannot be renamed and reused for different
104 purposes without this being noticed. The credential name to embed may be overridden with the
105 <option>--name=</option> setting. The input or output paths may be specified as <literal>-</literal>,
106 in which case the credential data is read from/written to standard input and standard output. If the
107 output path is specified as <literal>-</literal> the credential name cannot be derived from the file
108 system path, and thus should be specified explicitly via the <option>--name=</option> switch.</para>
109
110 <para>The credential data is encrypted and authenticated symmetrically with one of the following
111 encryption keys:</para>
112
113 <orderedlist>
114 <listitem><para>A secret key automatically derived from the system's TPM2 chip. This encryption key
115 is not stored on the host system and thus decryption is only possible with access to the original
116 TPM2 chip. Or in other words, the credential secured in this way can only be decrypted again by the
117 local machine.</para></listitem>
118
119 <listitem><para>A secret key stored in the <filename>/var/lib/systemd/credential.secret</filename>
120 file which is only accessible to the root user. This "host" encryption key is stored on the host
121 file system, and thus decryption is possible with access to the host file system and sufficient
122 privileges. The key is automatically generated when needed, but can also be created explicitly with
123 the <command>setup</command> command, see above.</para></listitem>
124
125 <listitem><para>A combination of the above: an encryption key derived from both the TPM2 chip and
126 the host file system. This means decryption requires both access to the original TPM2 chip and the
127 OS installation. This is the default mode of operation if a TPM2 chip is available and
128 <filename>/var/lib/systemd/</filename> resides on persistent media.</para></listitem>
129 </orderedlist>
130
131 <para>Which of the three keys shall be used for encryption may be configured with the
132 <option>--with-key=</option> switch. Depending on the use-case for the encrypted credential the key
133 to use may differ. For example, for credentials that shall be accessible from the initrd, encryption
134 with the host key is not appropriate, since access to the host key is typically not available from
135 the initrd. Thus, for such credentials only the TPM2 key should be used.</para>
136
137 <para>Encrypted credentials are always encoded in Base64.</para>
138
139 <para>Use <command>decrypt</command> (see below) to undo the encryption operation, and acquire the
140 decrypted plaintext credential from the encrypted ciphertext credential.</para>
141
142 <para>The credential data is encrypted using AES256-GCM, i.e. providing both confidentiality and
143 integrity, keyed by a SHA256 hash of one or both of the secret keys described above.</para>
144 </listitem>
145 </varlistentry>
146
147 <varlistentry>
148 <term><command>decrypt</command> <replaceable>input|-</replaceable>
149 <optional><replaceable>output|-</replaceable></optional></term>
150
151 <listitem><para>Undoes the effect of the <command>encrypt</command> operation: loads the specified
152 (encrypted ciphertext) input credential file, decrypts and authenticates it and writes the (decrypted
153 plaintext) output to the specified target credential file.</para>
154
155 <para>Takes one or two file system paths. The file name part of the input path is compared with the
156 credential name embedded in the encrypted file. If it does not match decryption fails. This is done
157 in order to ensure that encrypted credentials are not re-purposed without this being detected. The
158 credential name to compare with the embedded credential name may also be overridden with the
159 <option>--name=</option> switch. If the input path is specified as <literal>-</literal>, the
160 encrypted credential is read from standard input. If only one path is specified or the output path
161 specified as <literal>-</literal>, the decrypted credential is written to standard output. In this
162 mode, the expected name embedded in the credential cannot be derived from the path and should be
163 specified explicitly with <option>--name=</option>.</para>
164
165 <para>Decrypting credentials requires access to the original TPM2 chip and/or credentials host key,
166 see above. Information about which keys are required is embedded in the encrypted credential data,
167 and thus decryption is entirely automatic.</para></listitem>
168 </varlistentry>
169
170 <varlistentry>
171 <term><command>has-tpm2</command></term>
172
173 <listitem><para>Reports whether the system is equipped with a TPM2 device usable for protecting
174 credentials. If a TPM2 device has been discovered, is supported, and is being used by firmware,
175 by the OS kernel drivers and by userspace (i.e. systemd) this prints <literal>yes</literal> and exits
176 with exit status zero. If no such device is discovered/supported/used, prints
177 <literal>no</literal>. Otherwise prints <literal>partial</literal>. In either of these two cases
178 exits with non-zero exit status. It also shows four lines indicating separately whether firmware,
179 drivers, the system and the kernel discovered/support/use TPM2.</para>
180
181 <para>Combine with <option>--quiet</option> to suppress the output.</para></listitem>
182 </varlistentry>
183
184 <xi:include href="standard-options.xml" xpointer="help" />
185 <xi:include href="standard-options.xml" xpointer="version" />
186 </variablelist>
187 </refsect1>
188
189 <refsect1>
190 <title>Options</title>
191
192 <variablelist>
193
194 <varlistentry>
195 <term><option>--system</option></term>
196
197 <listitem><para>When specified with the <command>list</command> and <command>cat</command> commands
198 operates on the credentials passed to system as a whole instead of on those passed to the current
199 execution context. This is useful in container environments where credentials may be passed in from
200 the container manager.</para></listitem>
201 </varlistentry>
202
203 <varlistentry>
204 <term><option>--transcode=</option></term>
205
206 <listitem><para>When specified with the <command>cat</command> or <command>decrypt</command>
207 commands, transcodes the output before showing it. Takes one of <literal>base64</literal>,
208 <literal>unbase64</literal>, <literal>hex</literal> or <literal>unhex</literal> as argument, in order
209 to encode/decode the credential data with Base64 or as series of hexadecimal values.</para>
210
211 <para>Note that this has no effect on the <command>encrypt</command> command, as encrypted
212 credentials are unconditionally encoded in Base64.</para></listitem>
213 </varlistentry>
214
215 <varlistentry>
216 <term><option>--newline=</option></term>
217
218 <listitem><para>When specified with <command>cat</command> or <command>decrypt</command> controls
219 whether to add a trailing newline character to the end of the output if it doesn't end in one,
220 anyway. Takes one of <literal>auto</literal>, <literal>yes</literal> or <literal>no</literal>. The
221 default mode of <literal>auto</literal> will suffix the output with a single newline character only
222 when writing credential data to a TTY.</para></listitem>
223 </varlistentry>
224
225 <varlistentry>
226 <term><option>--pretty</option></term>
227 <term><option>-p</option></term>
228
229 <listitem><para>When specified with <command>encrypt</command> controls whether to show the encrypted
230 credential as <varname>SetCredentialEncrypted=</varname> setting that may be pasted directly into a
231 unit file.</para></listitem>
232 </varlistentry>
233
234 <varlistentry>
235 <term><option>--name=</option><replaceable>name</replaceable></term>
236
237 <listitem><para>When specified with the <command>encrypt</command> command controls the credential
238 name to embed in the encrypted credential data. If not specified the name is chosen automatically
239 from the filename component of the specified output path. If specified as empty string no
240 credential name is embedded in the encrypted credential, and no verification of credential name is
241 done when the credential is decrypted.</para>
242
243 <para>When specified with the <command>decrypt</command> command control the credential name to
244 validate the credential name embedded in the encrypted credential with. If not specified the name is
245 chosen automatically from the filename component of the specified input path. If no credential name
246 is embedded in the encrypted credential file (i.e. the <option>--name=</option> with an empty string
247 was used when encrypted) the specified name has no effect as no credential name validation is
248 done.</para>
249
250 <para>Embedding the credential name in the encrypted credential is done in order to protect against
251 reuse of credentials for purposes they weren't originally intended for, under the assumption the
252 credential name is chosen carefully to encode its intended purpose.</para></listitem>
253 </varlistentry>
254
255 <varlistentry>
256 <term><option>--timestamp=</option><replaceable>timestamp</replaceable></term>
257
258 <listitem><para>When specified with the <command>encrypt</command> command controls the timestamp to
259 embed into the encrypted credential. Defaults to the current time. Takes a timestamp specification in
260 the format described in
261 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
262
263 <para>When specified with the <command>decrypt</command> command controls the timestamp to use to
264 validate the "not-after" timestamp that was configured with <option>--not-after=</option> during
265 encryption. If not specified defaults to the current system time.</para></listitem>
266 </varlistentry>
267
268 <varlistentry>
269 <term><option>--not-after=</option><replaceable>timestamp</replaceable></term>
270
271 <listitem><para>When specified with the <command>encrypt</command> command controls the time when the
272 credential shall not be used anymore. This embeds the specified timestamp in the encrypted
273 credential. During decryption the timestamp is checked against the current system clock, and if the
274 timestamp is in the past the decryption will fail. By default no such timestamp is set. Takes a
275 timestamp specification in the format described in
276 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
277 </varlistentry>
278
279 <varlistentry>
280 <term><option>--with-key=</option></term>
281 <term><option>-H</option></term>
282 <term><option>-T</option></term>
283
284 <listitem><para>When specified with the <command>encrypt</command> command controls the
285 encryption/signature key to use. Takes one of <literal>host</literal>, <literal>tpm2</literal>,
286 <literal>host+tpm2</literal>, <literal>tpm2-absent</literal>, <literal>auto</literal>,
287 <literal>auto-initrd</literal>. See above for details on the three key types. If set to
288 <literal>auto</literal> (which is the default) the TPM2 key is used if a TPM2 device is found and not
289 running in a container. The host key is used if <filename>/var/lib/systemd/</filename> is on
290 persistent media. This means on typical systems the encryption is by default bound to both the TPM2
291 chip and the OS installation, and both need to be available to decrypt the credential again. If
292 <literal>auto</literal> is selected but neither TPM2 is available (or running in container) nor
293 <filename>/var/lib/systemd/</filename> is on persistent media, encryption will fail. If set to
294 <literal>tpm2-absent</literal> a fixed zero length key is used (thus, in this mode no confidentiality
295 nor authenticity are provided!). This logic is useful to cover for systems that lack a TPM2 chip but
296 where credentials shall be generated. Note that decryption of such credentials is refused on systems
297 that have a TPM2 chip and where UEFI SecureBoot is enabled (this is done so that such a locked down
298 system cannot be tricked into loading a credential generated this way that lacks authentication
299 information). If set to <literal>auto-initrd</literal> a TPM2 key is used if a TPM2 is found. If not
300 a fixed zero length key is used, equivalent to <literal>tpm2-absent</literal> mode. This option is
301 particularly useful to generate credentials files that are encrypted/authenticated against TPM2 where
302 available but still work on systems lacking support for this.</para>
303
304 <para>The <option>-H</option> switch is a shortcut for <option>--with-key=host</option>. Similar,
305 <option>-T</option> is a shortcut for <option>--with-key=tpm2</option>.</para>
306
307 <para>When encrypting credentials that shall be used in the initrd (where
308 <filename>/var/lib/systemd/</filename> is typically not available) make sure to use
309 <option>--with-key=auto-initrd</option> mode, to disable binding against the host secret.</para>
310
311 <para>This switch has no effect on the <command>decrypt</command> command, as information on which
312 key to use for decryption is included in the encrypted credential already.</para></listitem>
313 </varlistentry>
314
315 <varlistentry>
316 <term><option>--tpm2-device=</option><replaceable>PATH</replaceable></term>
317
318 <listitem><para>Controls the TPM2 device to use. Expects a device node path referring to the TPM2
319 chip (e.g. <filename>/dev/tpmrm0</filename>). Alternatively the special value <literal>auto</literal>
320 may be specified, in order to automatically determine the device node of a suitable TPM2 device (of
321 which there must be exactly one). The special value <literal>list</literal> may be used to enumerate
322 all suitable TPM2 devices currently discovered.</para></listitem>
323 </varlistentry>
324
325 <varlistentry>
326 <term><option>--tpm2-pcrs=</option><arg rep="repeat">PCR</arg></term>
327
328 <listitem><para>Configures the TPM2 PCRs (Platform Configuration Registers) to bind the encryption
329 key to. Takes a <literal>+</literal> separated list of numeric PCR indexes in the range 023. If not
330 used, defaults to PCR 7 only. If an empty string is specified, binds the encryption key to no PCRs at
331 all. For details about the PCRs available, see the documentation of the switch of the same name for
332 <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
333 </varlistentry>
334
335 <varlistentry>
336 <term><option>--tpm2-public-key=</option><arg>PATH</arg></term>
337 <term><option>--tpm2-public-key-pcrs=</option><arg rep="repeat">PCR</arg></term>
338
339 <listitem><para>Configures a TPM2 signed PCR policy to bind encryption to, for use with the
340 <command>encrypt</command> command. The <option>--tpm2-public-key=</option> option accepts a path to
341 a PEM encoded RSA public key, to bind the encryption to. If this is not specified explicitly, but a
342 file <filename>tpm2-pcr-public-key.pem</filename> exists in one of the directories
343 <filename>/etc/systemd/</filename>, <filename>/run/systemd/</filename>,
344 <filename>/usr/lib/systemd/</filename> (searched in this order), it is automatically used. The
345 <option>--tpm2-public-key-pcrs=</option> option takes a list of TPM2 PCR indexes to bind to (same
346 syntax as <option>--tpm2-pcrs=</option> described above). If not specified defaults to 11 (i.e. this
347 binds the policy to any unified kernel image for which a PCR signature can be provided).</para>
348
349 <para>Note the difference between <option>--tpm2-pcrs=</option> and
350 <option>--tpm2-public-key-pcrs=</option>: the former binds decryption to the current, specific PCR
351 values; the latter binds decryption to any set of PCR values for which a signature by the specified
352 public key can be provided. The latter is hence more useful in scenarios where software updates shall
353 be possible without losing access to all previously encrypted secrets.</para></listitem>
354 </varlistentry>
355
356 <varlistentry>
357 <term><option>--tpm2-signature=</option><arg>PATH</arg></term>
358
359 <listitem><para>Takes a path to a TPM2 PCR signature file as generated by the
360 <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
361 tool and that may be used to allow the <command>decrypt</command> command to decrypt credentials that
362 are bound to specific signed PCR values. If this this is not specified explicitly, and a credential
363 with a signed PCR policy is attempted to be decrypted, a suitable signature file
364 <filename>tpm2-pcr-signature.json</filename> is searched for in <filename>/etc/systemd/</filename>,
365 <filename>/run/systemd/</filename>, <filename>/usr/lib/systemd/</filename> (in this order) and
366 used.</para></listitem>
367 </varlistentry>
368
369 <varlistentry>
370 <term><option>--quiet</option></term>
371 <term><option>-q</option></term>
372
373 <listitem><para>When used with <command>has-tpm2</command> suppresses the output, and only returns an
374 exit status indicating support for TPM2.</para></listitem>
375 </varlistentry>
376
377 <xi:include href="standard-options.xml" xpointer="no-pager" />
378 <xi:include href="standard-options.xml" xpointer="no-legend" />
379 <xi:include href="standard-options.xml" xpointer="json" />
380 </variablelist>
381 </refsect1>
382
383 <refsect1>
384 <title>Exit status</title>
385
386 <para>On success, 0 is returned.</para>
387
388 <para>In case of the <command>has-tpm2</command> command returns 0 if a TPM2 device is discovered,
389 supported and used by firmware, driver, and userspace (i.e. systemd). Otherwise returns the OR
390 combination of the value 1 (in case firmware support is missing), 2 (in case driver support is missing)
391 and 4 (in case userspace support is missing). If no TPM2 support is available at all, value 7 is hence
392 returned.</para>
393 </refsect1>
394
395 <refsect1>
396 <title>Examples</title>
397
398 <example>
399 <title>Encrypt a password for use as credential</title>
400
401 <para>The following command line encrypts the specified password <literal>hunter2</literal>, writing the result
402 to a file <filename>password.cred</filename>.</para>
403
404 <programlisting># echo -n hunter2 | systemd-creds encrypt - password.cred</programlisting>
405
406 <para>This decrypts the file <filename>password.cred</filename> again, revealing the literal password:</para>
407
408 <programlisting># systemd-creds decrypt password.cred
409 hunter2</programlisting>
410 </example>
411
412 <example>
413 <title>Encrypt a password and include it in a unit file</title>
414
415 <para>The following command line prompts the user for a password and generates a
416 <varname>SetCredentialEncrypted=</varname> line from it for a credential named
417 <literal>mysql-password</literal>, suitable for inclusion in a unit file.</para>
418
419 <programlisting># systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - -
420 🔐 Password: ****
421 SetCredentialEncrypted=mysql-password: \
422 k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAASfFsBoPLIm/dlDoGAAAAAAAAAA \
423 NAAAAAgAAAAAH4AILIOZ3w6rTzYsBy9G7liaCAd4i+Kpvs8mAgArzwuKxd0ABDjgSeO5k \
424 mKQc58zM94ZffyRmuNeX1lVHE+9e2YD87KfRFNoDLS7F3YmCb347gCiSk2an9egZ7Y0Xs \
425 700Kr6heqQswQEemNEc62k9RJnEl2q7SbcEYguegnPQUATgAIAAsAAAASACA/B90W7E+6 \
426 yAR9NgiIJvxr9bpElztwzB5lUJAxtMBHIgAQACCaSV9DradOZz4EvO/LSaRyRSq2Hj0ym \
427 gVJk/dVzE8Uxj8H3RbsT7rIBH02CIgm/Gv1ukSXO3DMHmVQkDG0wEciyageTfrVEer8z5 \
428 9cUQfM5ynSaV2UjeUWEHuz4fwDsXGLB9eELXLztzUU9nsAyLvs3ZRR+eEK/A==</programlisting>
429
430 <para>The generated line can be pasted 1:1 into a unit file, and will ensure the acquired password will
431 be made available in the <varname>$CREDENTIALS_DIRECTORY</varname><filename>/mysql-password</filename>
432 credential file for the started service.</para>
433
434 <para>Utilizing the unit file drop-in logic this can be used to securely pass a password credential to
435 a unit. A similar, more comprehensive set of commands to insert a password into a service
436 <filename>xyz.service</filename>:</para>
437
438 <programlisting># mkdir -p /etc/systemd/system/xyz.service.d
439 # systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - - > /etc/systemd/system/xyz.service.d/50-password.conf
440 # systemctl daemon-reload
441 # systemctl restart xyz.service</programlisting>
442 </example>
443 </refsect1>
444
445 <refsect1>
446 <title>See Also</title>
447 <para>
448 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
449 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
450 <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
451 </para>
452 </refsect1>
453
454 </refentry>