]>
Commit | Line | Data |
---|---|---|
c1017f6b LP |
1 | <?xml version='1.0'?> <!--*-nxml-*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
c1017f6b LP |
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> | |
5ad0109c AAF |
28 | <arg choice="plain">COMMAND</arg> |
29 | <arg choice="opt" rep="repeat">ARGS</arg> | |
c1017f6b LP |
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 | ||
dfb210c8 | 41 | <para>Credentials are configured in unit files via the <varname>ImportCredential=</varname>, |
bbfb25f4 | 42 | <varname>LoadCredential=</varname>, <varname>SetCredential=</varname>, |
dfb210c8 | 43 | <varname>LoadCredentialEncrypted=</varname>, and <varname>SetCredentialEncrypted=</varname> settings, see |
c1017f6b LP |
44 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for |
45 | details.</para> | |
fe672fe5 LP |
46 | |
47 | <para>For further information see <ulink url="https://systemd.io/CREDENTIALS">System and Service | |
48 | Credentials</ulink> documentation.</para> | |
c1017f6b LP |
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 | |
ec07c3c8 AK |
68 | by anyone but the owner).</para> |
69 | ||
70 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
71 | </varlistentry> |
72 | ||
73 | <varlistentry> | |
74 | <term><command>cat</command> <replaceable>credential...</replaceable></term> | |
75 | ||
76 | <listitem><para>Show contents of specified credentials passed into the current execution | |
77 | context. Takes one or more credential names, whose contents shall be written to standard | |
78 | output.</para> | |
79 | ||
80 | <para>When combined with <option>--json=</option> or <option>--transcode=</option> the output is | |
ec07c3c8 AK |
81 | transcoded in simple ways before outputting.</para> |
82 | ||
83 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
84 | </varlistentry> |
85 | ||
86 | <varlistentry> | |
87 | <term><command>setup</command></term> | |
88 | ||
ecc5d0c0 ZJS |
89 | <listitem><para>Generates a host encryption key for credentials, if one has not been generated |
90 | already. This ensures the <filename>/var/lib/systemd/credential.secret</filename> file is initialized | |
c1017f6b LP |
91 | with a random secret key if it doesn't exist yet. This secret key is used when encrypting/decrypting |
92 | credentials with <command>encrypt</command> or <command>decrypt</command>, and is only accessible to | |
93 | the root user. Note that there's typically no need to invoke this command explicitly as it is | |
94 | implicitly called when <command>encrypt</command> is invoked, and credential host key encryption | |
ec07c3c8 AK |
95 | selected.</para> |
96 | ||
97 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
98 | </varlistentry> |
99 | ||
100 | <varlistentry> | |
ecc5d0c0 | 101 | <term><command>encrypt</command> <replaceable>input|-</replaceable> <replaceable>output|-</replaceable></term> |
c1017f6b LP |
102 | |
103 | <listitem><para>Loads the specified (unencrypted plaintext) input credential file, encrypts it and | |
d43ea6c8 | 104 | writes the (encrypted ciphertext) output to the specified target credential file. The resulting file |
c1017f6b LP |
105 | may be referenced in the <varname>LoadCredentialEncrypted=</varname> setting in unit files, or its |
106 | contents used literally in <varname>SetCredentialEncrypted=</varname> settings.</para> | |
107 | ||
108 | <para>Takes two file system paths. The file name part of the output path is embedded as name in the | |
109 | encrypted credential, to ensure encrypted credentials cannot be renamed and reused for different | |
110 | purposes without this being noticed. The credential name to embed may be overridden with the | |
111 | <option>--name=</option> setting. The input or output paths may be specified as <literal>-</literal>, | |
112 | in which case the credential data is read from/written to standard input and standard output. If the | |
113 | output path is specified as <literal>-</literal> the credential name cannot be derived from the file | |
114 | system path, and thus should be specified explicitly via the <option>--name=</option> switch.</para> | |
115 | ||
d43ea6c8 LP |
116 | <para>The credential data is encrypted and authenticated symmetrically with one of the following |
117 | encryption keys:</para> | |
c1017f6b LP |
118 | |
119 | <orderedlist> | |
120 | <listitem><para>A secret key automatically derived from the system's TPM2 chip. This encryption key | |
121 | is not stored on the host system and thus decryption is only possible with access to the original | |
122 | TPM2 chip. Or in other words, the credential secured in this way can only be decrypted again by the | |
123 | local machine.</para></listitem> | |
124 | ||
125 | <listitem><para>A secret key stored in the <filename>/var/lib/systemd/credential.secret</filename> | |
126 | file which is only accessible to the root user. This "host" encryption key is stored on the host | |
127 | file system, and thus decryption is possible with access to the host file system and sufficient | |
128 | privileges. The key is automatically generated when needed, but can also be created explicitly with | |
129 | the <command>setup</command> command, see above.</para></listitem> | |
130 | ||
131 | <listitem><para>A combination of the above: an encryption key derived from both the TPM2 chip and | |
132 | the host file system. This means decryption requires both access to the original TPM2 chip and the | |
133 | OS installation. This is the default mode of operation if a TPM2 chip is available and | |
134 | <filename>/var/lib/systemd/</filename> resides on persistent media.</para></listitem> | |
135 | </orderedlist> | |
136 | ||
137 | <para>Which of the three keys shall be used for encryption may be configured with the | |
b66a6e1a ZJS |
138 | <option>--with-key=</option> switch. Depending on the use-case for the encrypted credential the key |
139 | to use may differ. For example, for credentials that shall be accessible from the initrd, encryption | |
140 | with the host key is not appropriate, since access to the host key is typically not available from | |
141 | the initrd. Thus, for such credentials only the TPM2 key should be used.</para> | |
c1017f6b LP |
142 | |
143 | <para>Encrypted credentials are always encoded in Base64.</para> | |
144 | ||
145 | <para>Use <command>decrypt</command> (see below) to undo the encryption operation, and acquire the | |
146 | decrypted plaintext credential from the encrypted ciphertext credential.</para> | |
147 | ||
148 | <para>The credential data is encrypted using AES256-GCM, i.e. providing both confidentiality and | |
149 | integrity, keyed by a SHA256 hash of one or both of the secret keys described above.</para> | |
ec07c3c8 AK |
150 | |
151 | <xi:include href="version-info.xml" xpointer="v250"/> | |
c1017f6b LP |
152 | </listitem> |
153 | </varlistentry> | |
154 | ||
155 | <varlistentry> | |
ecc5d0c0 ZJS |
156 | <term><command>decrypt</command> <replaceable>input|-</replaceable> |
157 | <optional><replaceable>output|-</replaceable></optional></term> | |
c1017f6b LP |
158 | |
159 | <listitem><para>Undoes the effect of the <command>encrypt</command> operation: loads the specified | |
d43ea6c8 LP |
160 | (encrypted ciphertext) input credential file, decrypts and authenticates it and writes the (decrypted |
161 | plaintext) output to the specified target credential file.</para> | |
c1017f6b LP |
162 | |
163 | <para>Takes one or two file system paths. The file name part of the input path is compared with the | |
164 | credential name embedded in the encrypted file. If it does not match decryption fails. This is done | |
165 | in order to ensure that encrypted credentials are not re-purposed without this being detected. The | |
166 | credential name to compare with the embedded credential name may also be overridden with the | |
ecc5d0c0 ZJS |
167 | <option>--name=</option> switch. If the input path is specified as <literal>-</literal>, the |
168 | encrypted credential is read from standard input. If only one path is specified or the output path | |
169 | specified as <literal>-</literal>, the decrypted credential is written to standard output. In this | |
170 | mode, the expected name embedded in the credential cannot be derived from the path and should be | |
171 | specified explicitly with <option>--name=</option>.</para> | |
c1017f6b LP |
172 | |
173 | <para>Decrypting credentials requires access to the original TPM2 chip and/or credentials host key, | |
174 | see above. Information about which keys are required is embedded in the encrypted credential data, | |
ec07c3c8 AK |
175 | and thus decryption is entirely automatic.</para> |
176 | ||
177 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
178 | </varlistentry> |
179 | ||
eb81249e LP |
180 | <varlistentry> |
181 | <term><command>has-tpm2</command></term> | |
182 | ||
183 | <listitem><para>Reports whether the system is equipped with a TPM2 device usable for protecting | |
6a1d8f11 | 184 | credentials. If a TPM2 device has been discovered, is supported, and is being used by firmware, |
eb81249e LP |
185 | by the OS kernel drivers and by userspace (i.e. systemd) this prints <literal>yes</literal> and exits |
186 | with exit status zero. If no such device is discovered/supported/used, prints | |
187 | <literal>no</literal>. Otherwise prints <literal>partial</literal>. In either of these two cases | |
300bba79 DDM |
188 | exits with non-zero exit status. It also shows four lines indicating separately whether firmware, |
189 | drivers, the system and the kernel discovered/support/use TPM2.</para> | |
eb81249e | 190 | |
ec07c3c8 AK |
191 | <para>Combine with <option>--quiet</option> to suppress the output.</para> |
192 | ||
193 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
eb81249e LP |
194 | </varlistentry> |
195 | ||
c1017f6b LP |
196 | <xi:include href="standard-options.xml" xpointer="help" /> |
197 | <xi:include href="standard-options.xml" xpointer="version" /> | |
198 | </variablelist> | |
199 | </refsect1> | |
200 | ||
201 | <refsect1> | |
202 | <title>Options</title> | |
203 | ||
204 | <variablelist> | |
205 | ||
206 | <varlistentry> | |
207 | <term><option>--system</option></term> | |
208 | ||
209 | <listitem><para>When specified with the <command>list</command> and <command>cat</command> commands | |
210 | operates on the credentials passed to system as a whole instead of on those passed to the current | |
211 | execution context. This is useful in container environments where credentials may be passed in from | |
ec07c3c8 AK |
212 | the container manager.</para> |
213 | ||
214 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
215 | </varlistentry> |
216 | ||
7704c347 LP |
217 | <varlistentry> |
218 | <term><option>--user</option></term> | |
219 | ||
220 | <listitem><para>When specified with the <command>encrypt</command> and <command>decrypt</command> | |
221 | commands encrypts a user-scoped (rather than a system-scoped) credential. Use <option>--uid=</option> | |
222 | to select which user the credential is from. Such credentials may only be decrypted from the | |
223 | specified user's context, except if privileges can be acquired. Generally, when an encrypted | |
224 | credential shall be used in the per-user service manager it should be encrypted with this option set, | |
04a75546 | 225 | when it shall be used in the system service manager it should be encrypted without.</para> |
7704c347 LP |
226 | |
227 | <para>Internally, this ensures that the selected user's numeric UID and username, as well as the | |
228 | system's | |
229 | <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> are | |
230 | incorporated into the encryption key.</para> | |
231 | ||
232 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
233 | </varlistentry> | |
234 | ||
235 | <varlistentry> | |
236 | <term><option>--uid=</option></term> | |
237 | ||
238 | <listitem><para>Specifies the user to encrypt the credential for. Takes a user name or numeric | |
239 | UID. If set, implies <option>--user</option>. If set to the special string <literal>self</literal> | |
240 | sets the user to the user of the calling process. If <option>--user</option> is used without | |
241 | <option>--uid=</option> then <option>--uid=self</option> is implied, i.e. the credential is encrypted | |
242 | for the calling user.</para> | |
243 | ||
244 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
245 | </varlistentry> | |
246 | ||
c1017f6b LP |
247 | <varlistentry> |
248 | <term><option>--transcode=</option></term> | |
249 | ||
250 | <listitem><para>When specified with the <command>cat</command> or <command>decrypt</command> | |
251 | commands, transcodes the output before showing it. Takes one of <literal>base64</literal>, | |
252 | <literal>unbase64</literal>, <literal>hex</literal> or <literal>unhex</literal> as argument, in order | |
253 | to encode/decode the credential data with Base64 or as series of hexadecimal values.</para> | |
254 | ||
255 | <para>Note that this has no effect on the <command>encrypt</command> command, as encrypted | |
ec07c3c8 AK |
256 | credentials are unconditionally encoded in Base64.</para> |
257 | ||
258 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
259 | </varlistentry> |
260 | ||
261 | <varlistentry> | |
262 | <term><option>--newline=</option></term> | |
263 | ||
264 | <listitem><para>When specified with <command>cat</command> or <command>decrypt</command> controls | |
265 | whether to add a trailing newline character to the end of the output if it doesn't end in one, | |
266 | anyway. Takes one of <literal>auto</literal>, <literal>yes</literal> or <literal>no</literal>. The | |
267 | default mode of <literal>auto</literal> will suffix the output with a single newline character only | |
ec07c3c8 AK |
268 | when writing credential data to a TTY.</para> |
269 | ||
270 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
271 | </varlistentry> |
272 | ||
273 | <varlistentry> | |
274 | <term><option>--pretty</option></term> | |
275 | <term><option>-p</option></term> | |
276 | ||
277 | <listitem><para>When specified with <command>encrypt</command> controls whether to show the encrypted | |
278 | credential as <varname>SetCredentialEncrypted=</varname> setting that may be pasted directly into a | |
c74e13a5 | 279 | unit file. Has effect only when used together with <option>--name=</option> and <literal>-</literal> |
ec07c3c8 AK |
280 | as the output file.</para> |
281 | ||
282 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
283 | </varlistentry> |
284 | ||
285 | <varlistentry> | |
9bfabe14 | 286 | <term><option>--name=<replaceable>name</replaceable></option></term> |
c1017f6b LP |
287 | |
288 | <listitem><para>When specified with the <command>encrypt</command> command controls the credential | |
289 | name to embed in the encrypted credential data. If not specified the name is chosen automatically | |
290 | from the filename component of the specified output path. If specified as empty string no | |
291 | credential name is embedded in the encrypted credential, and no verification of credential name is | |
292 | done when the credential is decrypted.</para> | |
293 | ||
294 | <para>When specified with the <command>decrypt</command> command control the credential name to | |
295 | validate the credential name embedded in the encrypted credential with. If not specified the name is | |
296 | chosen automatically from the filename component of the specified input path. If no credential name | |
297 | is embedded in the encrypted credential file (i.e. the <option>--name=</option> with an empty string | |
298 | was used when encrypted) the specified name has no effect as no credential name validation is | |
299 | done.</para> | |
300 | ||
301 | <para>Embedding the credential name in the encrypted credential is done in order to protect against | |
302 | reuse of credentials for purposes they weren't originally intended for, under the assumption the | |
ec07c3c8 AK |
303 | credential name is chosen carefully to encode its intended purpose.</para> |
304 | ||
305 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
306 | </varlistentry> |
307 | ||
308 | <varlistentry> | |
9bfabe14 | 309 | <term><option>--timestamp=<replaceable>timestamp</replaceable></option></term> |
c1017f6b LP |
310 | |
311 | <listitem><para>When specified with the <command>encrypt</command> command controls the timestamp to | |
312 | embed into the encrypted credential. Defaults to the current time. Takes a timestamp specification in | |
313 | the format described in | |
921e1bae | 314 | <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> |
c1017f6b LP |
315 | |
316 | <para>When specified with the <command>decrypt</command> command controls the timestamp to use to | |
317 | validate the "not-after" timestamp that was configured with <option>--not-after=</option> during | |
ec07c3c8 AK |
318 | encryption. If not specified defaults to the current system time.</para> |
319 | ||
320 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
321 | </varlistentry> |
322 | ||
323 | <varlistentry> | |
9bfabe14 | 324 | <term><option>--not-after=<replaceable>timestamp</replaceable></option></term> |
c1017f6b LP |
325 | |
326 | <listitem><para>When specified with the <command>encrypt</command> command controls the time when the | |
327 | credential shall not be used anymore. This embeds the specified timestamp in the encrypted | |
328 | credential. During decryption the timestamp is checked against the current system clock, and if the | |
329 | timestamp is in the past the decryption will fail. By default no such timestamp is set. Takes a | |
330 | timestamp specification in the format described in | |
ec07c3c8 AK |
331 | <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> |
332 | ||
333 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
334 | </varlistentry> |
335 | ||
336 | <varlistentry> | |
337 | <term><option>--with-key=</option></term> | |
338 | <term><option>-H</option></term> | |
339 | <term><option>-T</option></term> | |
340 | ||
b6553329 LP |
341 | <listitem><para>When specified with the <command>encrypt</command> command controls the |
342 | encryption/signature key to use. Takes one of <literal>host</literal>, <literal>tpm2</literal>, | |
6d78dc28 | 343 | <literal>host+tpm2</literal>, <literal>null</literal>, <literal>auto</literal>, |
b6553329 LP |
344 | <literal>auto-initrd</literal>. See above for details on the three key types. If set to |
345 | <literal>auto</literal> (which is the default) the TPM2 key is used if a TPM2 device is found and not | |
346 | running in a container. The host key is used if <filename>/var/lib/systemd/</filename> is on | |
347 | persistent media. This means on typical systems the encryption is by default bound to both the TPM2 | |
348 | chip and the OS installation, and both need to be available to decrypt the credential again. If | |
349 | <literal>auto</literal> is selected but neither TPM2 is available (or running in container) nor | |
350 | <filename>/var/lib/systemd/</filename> is on persistent media, encryption will fail. If set to | |
6d78dc28 | 351 | <literal>null</literal> a fixed zero length key is used (thus, in this mode no confidentiality |
b6553329 LP |
352 | nor authenticity are provided!). This logic is useful to cover for systems that lack a TPM2 chip but |
353 | where credentials shall be generated. Note that decryption of such credentials is refused on systems | |
354 | that have a TPM2 chip and where UEFI SecureBoot is enabled (this is done so that such a locked down | |
355 | system cannot be tricked into loading a credential generated this way that lacks authentication | |
356 | information). If set to <literal>auto-initrd</literal> a TPM2 key is used if a TPM2 is found. If not | |
6d78dc28 | 357 | a fixed zero length key is used, equivalent to <literal>null</literal> mode. This option is |
b6553329 LP |
358 | particularly useful to generate credentials files that are encrypted/authenticated against TPM2 where |
359 | available but still work on systems lacking support for this.</para> | |
c1017f6b LP |
360 | |
361 | <para>The <option>-H</option> switch is a shortcut for <option>--with-key=host</option>. Similar, | |
921e1bae | 362 | <option>-T</option> is a shortcut for <option>--with-key=tpm2</option>.</para> |
c1017f6b | 363 | |
55c041b4 LP |
364 | <para>When encrypting credentials that shall be used in the initrd (where |
365 | <filename>/var/lib/systemd/</filename> is typically not available) make sure to use | |
b6553329 | 366 | <option>--with-key=auto-initrd</option> mode, to disable binding against the host secret.</para> |
c1017f6b LP |
367 | |
368 | <para>This switch has no effect on the <command>decrypt</command> command, as information on which | |
ec07c3c8 AK |
369 | key to use for decryption is included in the encrypted credential already.</para> |
370 | ||
371 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
372 | </varlistentry> |
373 | ||
374 | <varlistentry> | |
9bfabe14 | 375 | <term><option>--tpm2-device=<replaceable>PATH</replaceable></option></term> |
c1017f6b LP |
376 | |
377 | <listitem><para>Controls the TPM2 device to use. Expects a device node path referring to the TPM2 | |
378 | chip (e.g. <filename>/dev/tpmrm0</filename>). Alternatively the special value <literal>auto</literal> | |
379 | may be specified, in order to automatically determine the device node of a suitable TPM2 device (of | |
380 | which there must be exactly one). The special value <literal>list</literal> may be used to enumerate | |
ec07c3c8 AK |
381 | all suitable TPM2 devices currently discovered.</para> |
382 | ||
383 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
384 | </varlistentry> |
385 | ||
386 | <varlistentry> | |
9bfabe14 | 387 | <term><option>--tpm2-pcrs=<replaceable>PCR<optional>+PCR...</optional></replaceable></option></term> |
c1017f6b LP |
388 | |
389 | <listitem><para>Configures the TPM2 PCRs (Platform Configuration Registers) to bind the encryption | |
390 | key to. Takes a <literal>+</literal> separated list of numeric PCR indexes in the range 0…23. If not | |
391 | used, defaults to PCR 7 only. If an empty string is specified, binds the encryption key to no PCRs at | |
392 | all. For details about the PCRs available, see the documentation of the switch of the same name for | |
ec07c3c8 AK |
393 | <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> |
394 | ||
395 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
c1017f6b LP |
396 | </varlistentry> |
397 | ||
75ddec93 | 398 | <varlistentry> |
9bfabe14 SL |
399 | <term><option>--tpm2-public-key=<replaceable>PATH</replaceable></option></term> |
400 | <term><option>--tpm2-public-key-pcrs=<replaceable>PCR<optional>+PCR...</optional></replaceable></option></term> | |
75ddec93 LP |
401 | |
402 | <listitem><para>Configures a TPM2 signed PCR policy to bind encryption to, for use with the | |
403 | <command>encrypt</command> command. The <option>--tpm2-public-key=</option> option accepts a path to | |
404 | a PEM encoded RSA public key, to bind the encryption to. If this is not specified explicitly, but a | |
405 | file <filename>tpm2-pcr-public-key.pem</filename> exists in one of the directories | |
406 | <filename>/etc/systemd/</filename>, <filename>/run/systemd/</filename>, | |
407 | <filename>/usr/lib/systemd/</filename> (searched in this order), it is automatically used. The | |
408 | <option>--tpm2-public-key-pcrs=</option> option takes a list of TPM2 PCR indexes to bind to (same | |
409 | syntax as <option>--tpm2-pcrs=</option> described above). If not specified defaults to 11 (i.e. this | |
410 | binds the policy to any unified kernel image for which a PCR signature can be provided).</para> | |
411 | ||
412 | <para>Note the difference between <option>--tpm2-pcrs=</option> and | |
413 | <option>--tpm2-public-key-pcrs=</option>: the former binds decryption to the current, specific PCR | |
414 | values; the latter binds decryption to any set of PCR values for which a signature by the specified | |
415 | public key can be provided. The latter is hence more useful in scenarios where software updates shall | |
ec07c3c8 AK |
416 | be possible without losing access to all previously encrypted secrets.</para> |
417 | ||
418 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
75ddec93 LP |
419 | </varlistentry> |
420 | ||
421 | <varlistentry> | |
9bfabe14 | 422 | <term><option>--tpm2-signature=<replaceable>PATH</replaceable></option></term> |
75ddec93 LP |
423 | |
424 | <listitem><para>Takes a path to a TPM2 PCR signature file as generated by the | |
425 | <citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
426 | tool and that may be used to allow the <command>decrypt</command> command to decrypt credentials that | |
8b9f0921 | 427 | are bound to specific signed PCR values. If this is not specified explicitly, and a credential |
75ddec93 LP |
428 | with a signed PCR policy is attempted to be decrypted, a suitable signature file |
429 | <filename>tpm2-pcr-signature.json</filename> is searched for in <filename>/etc/systemd/</filename>, | |
430 | <filename>/run/systemd/</filename>, <filename>/usr/lib/systemd/</filename> (in this order) and | |
ec07c3c8 AK |
431 | used.</para> |
432 | ||
433 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
75ddec93 LP |
434 | </varlistentry> |
435 | ||
aadbe559 LN |
436 | <varlistentry> |
437 | <term><option>--allow-null</option></term> | |
438 | ||
439 | <listitem><para>Allow decrypting credentials that use an empty key.</para> | |
440 | ||
441 | <xi:include href="version-info.xml" xpointer="v256"/></listitem> | |
442 | </varlistentry> | |
443 | ||
eb81249e LP |
444 | <varlistentry> |
445 | <term><option>--quiet</option></term> | |
446 | <term><option>-q</option></term> | |
447 | ||
448 | <listitem><para>When used with <command>has-tpm2</command> suppresses the output, and only returns an | |
ec07c3c8 AK |
449 | exit status indicating support for TPM2.</para> |
450 | ||
451 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
eb81249e LP |
452 | </varlistentry> |
453 | ||
c1017f6b LP |
454 | <xi:include href="standard-options.xml" xpointer="no-pager" /> |
455 | <xi:include href="standard-options.xml" xpointer="no-legend" /> | |
456 | <xi:include href="standard-options.xml" xpointer="json" /> | |
457 | </variablelist> | |
458 | </refsect1> | |
459 | ||
460 | <refsect1> | |
461 | <title>Exit status</title> | |
462 | ||
463 | <para>On success, 0 is returned.</para> | |
eb81249e LP |
464 | |
465 | <para>In case of the <command>has-tpm2</command> command returns 0 if a TPM2 device is discovered, | |
466 | supported and used by firmware, driver, and userspace (i.e. systemd). Otherwise returns the OR | |
467 | combination of the value 1 (in case firmware support is missing), 2 (in case driver support is missing) | |
468 | and 4 (in case userspace support is missing). If no TPM2 support is available at all, value 7 is hence | |
469 | returned.</para> | |
c1017f6b LP |
470 | </refsect1> |
471 | ||
472 | <refsect1> | |
473 | <title>Examples</title> | |
474 | ||
475 | <example> | |
476 | <title>Encrypt a password for use as credential</title> | |
477 | ||
478 | <para>The following command line encrypts the specified password <literal>hunter2</literal>, writing the result | |
479 | to a file <filename>password.cred</filename>.</para> | |
480 | ||
481 | <programlisting># echo -n hunter2 | systemd-creds encrypt - password.cred</programlisting> | |
482 | ||
483 | <para>This decrypts the file <filename>password.cred</filename> again, revealing the literal password:</para> | |
484 | ||
485 | <programlisting># systemd-creds decrypt password.cred | |
486 | hunter2</programlisting> | |
487 | </example> | |
488 | ||
489 | <example> | |
490 | <title>Encrypt a password and include it in a unit file</title> | |
491 | ||
492 | <para>The following command line prompts the user for a password and generates a | |
493 | <varname>SetCredentialEncrypted=</varname> line from it for a credential named | |
494 | <literal>mysql-password</literal>, suitable for inclusion in a unit file.</para> | |
495 | ||
496 | <programlisting># systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - - | |
497 | 🔐 Password: **** | |
498 | SetCredentialEncrypted=mysql-password: \ | |
499 | k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAASfFsBoPLIm/dlDoGAAAAAAAAAA \ | |
500 | NAAAAAgAAAAAH4AILIOZ3w6rTzYsBy9G7liaCAd4i+Kpvs8mAgArzwuKxd0ABDjgSeO5k \ | |
501 | mKQc58zM94ZffyRmuNeX1lVHE+9e2YD87KfRFNoDLS7F3YmCb347gCiSk2an9egZ7Y0Xs \ | |
502 | 700Kr6heqQswQEemNEc62k9RJnEl2q7SbcEYguegnPQUATgAIAAsAAAASACA/B90W7E+6 \ | |
503 | yAR9NgiIJvxr9bpElztwzB5lUJAxtMBHIgAQACCaSV9DradOZz4EvO/LSaRyRSq2Hj0ym \ | |
504 | gVJk/dVzE8Uxj8H3RbsT7rIBH02CIgm/Gv1ukSXO3DMHmVQkDG0wEciyageTfrVEer8z5 \ | |
505 | 9cUQfM5ynSaV2UjeUWEHuz4fwDsXGLB9eELXLztzUU9nsAyLvs3ZRR+eEK/A==</programlisting> | |
506 | ||
507 | <para>The generated line can be pasted 1:1 into a unit file, and will ensure the acquired password will | |
508 | be made available in the <varname>$CREDENTIALS_DIRECTORY</varname><filename>/mysql-password</filename> | |
509 | credential file for the started service.</para> | |
510 | ||
511 | <para>Utilizing the unit file drop-in logic this can be used to securely pass a password credential to | |
512 | a unit. A similar, more comprehensive set of commands to insert a password into a service | |
513 | <filename>xyz.service</filename>:</para> | |
514 | ||
515 | <programlisting># mkdir -p /etc/systemd/system/xyz.service.d | |
2e290d55 | 516 | # systemd-ask-password -n | ( echo "[Service]" && systemd-creds encrypt --name=mysql-password -p - - ) >/etc/systemd/system/xyz.service.d/50-password.conf |
c1017f6b LP |
517 | # systemctl daemon-reload |
518 | # systemctl restart xyz.service</programlisting> | |
519 | </example> | |
520 | </refsect1> | |
521 | ||
522 | <refsect1> | |
523 | <title>See Also</title> | |
13a69c12 DT |
524 | <para><simplelist type="inline"> |
525 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
526 | <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
527 | <member><citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
528 | </simplelist></para> | |
c1017f6b LP |
529 | </refsect1> |
530 | ||
531 | </refentry> |