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