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 LoadCredential=,
20 SetCredential=, LoadCredentialEncrypted= and SetCredentialEncrypted=
21 settings, see systemd.exec(5) for details.
22
24 The following commands are understood:
25 list
27 Show a list of credentials passed into the current execution
28 context. This command shows the files in the directory referenced
29 by the $CREDENTIALS_DIRECTORY environment variable, and is intended
30 to be executed from within service context.
31 Along with each credential name, the size and security state is
33 shown. The latter is one of "secure" (in case the credential is
34 backed by unswappable memory, i.e. "ramfs"), "weak" (in case it is
35 backed by any other type of memory), or "insecure" (if having any
36 access mode that is not 0400, i.e. if readable by anyone but the
37 owner).
38 cat credential...
40 Show contents of specified credentials passed into the current
41 execution context. Takes one or more credential names, whose
42 contents shall be written to standard output.
43 When combined with --json= or --transcode= the output is transcoded
45 in simple ways before outputting.
46 setup
48 Generates a host encryption key for credentials, if one has not
49 been generated already. This ensures the
50 /var/lib/systemd/credential.secret file is initialized with a
51 random secret key if it doesn't exist yet. This secret key is used
52 when encrypting/decrypting credentials with encrypt or decrypt, and
53 is only accessible to the root user. Note that there's typically no
54 need to invoke this command explicitly as it is implicitly called
55 when encrypt is invoked, and credential host key encryption
56 selected.
57 encrypt input|- output|-
59 Loads the specified (unencrypted plaintext) input credential file,
60 encrypts it and writes the (encrypted ciphertext) version to the
61 specified output credential file. The resulting file may be
62 referenced in the LoadCredentialEncrypted= setting in unit files,
63 or its contents used literally in SetCredentialEncrypted= settings.
64 Takes two file system paths. The file name part of the output path
66 is embedded as name in the encrypted credential, to ensure
67 encrypted credentials cannot be renamed and reused for different
68 purposes without this being noticed. The credential name to embed
69 may be overridden with the --name= setting. The input or output
70 paths may be specified as "-", in which case the credential data is
71 read from/written to standard input and standard output. If the
72 output path is specified as "-" the credential name cannot be
73 derived from the file system path, and thus should be specified
74 explicitly via the --name= switch.
75 The credential data is encrypted symmetrically with one of the
77 following encryption keys:
78 1. A secret key automatically derived from the system's TPM2 chip.
80 This encryption key is not stored on the host system and thus
81 decryption is only possible with access to the original TPM2
82 chip. Or in other words, the credential secured in this way can
83 only be decrypted again by the local machine.
84 2. A secret key stored in the /var/lib/systemd/credential.secret
86 file which is only accessible to the root user. This "host"
87 encryption key is stored on the host file system, and thus
88 decryption is possible with access to the host file system and
89 sufficient privileges. The key is automatically generated when
90 needed, but can also be created explicitly with the setup
91 command, see above.
92 3. A combination of the above: an encryption key derived from both
94 the TPM2 chip and the host file system. This means decryption
95 requires both access to the original TPM2 chip and the OS
96 installation. This is the default mode of operation if a TPM2
97 chip is available and /var/lib/systemd/ resides on persistent
98 media.
99 Which of the three keys shall be used for encryption may be
101 configured with the --with-key= switch. Depending on the use-case
102 for the encrypted credential the key to use may differ. For
103 example, for credentials that shall be accessible from the initial
104 RAM disk (initrd) of the system encryption with the host key is not
105 appropriate since access to the host key is typically not available
106 from the initrd. Thus, for such credentials only the TPM2 key
107 should be used.
108 Encrypted credentials are always encoded in Base64.
110 Use decrypt (see below) to undo the encryption operation, and
112 acquire the decrypted plaintext credential from the encrypted
113 ciphertext credential.
114 The credential data is encrypted using AES256-GCM, i.e. providing
116 both confidentiality and integrity, keyed by a SHA256 hash of one
117 or both of the secret keys described above.
118 decrypt input|- [output|-]
120 Undoes the effect of the encrypt operation: loads the specified
121 (encrypted ciphertext) input credential file, decrypts it and
122 writes the (decrypted plaintext) version to the specified output
123 credential file.
124 Takes one or two file system paths. The file name part of the input
126 path is compared with the credential name embedded in the encrypted
127 file. If it does not match decryption fails. This is done in order
128 to ensure that encrypted credentials are not re-purposed without
129 this being detected. The credential name to compare with the
130 embedded credential name may also be overridden with the --name=
131 switch. If the input path is specified as "-", the encrypted
132 credential is read from standard input. If only one path is
133 specified or the output path specified as "-", the decrypted
134 credential is written to standard output. In this mode, the
135 expected name embedded in the credential cannot be derived from the
136 path and should be specified explicitly with --name=.
137 Decrypting credentials requires access to the original TPM2 chip
139 and/or credentials host key, see above. Information about which
140 keys are required is embedded in the encrypted credential data, and
141 thus decryption is entirely automatic.
142 -h, --help
144 Print a short help text and exit.
145 --version
147 Print a short version string and exit.
148
150 --system
151 When specified with the list and cat commands operates on the
152 credentials passed to system as a whole instead of on those passed
153 to the current execution context. This is useful in container
154 environments where credentials may be passed in from the container
155 manager.
156 --transcode=
158 When specified with the cat or decrypt commands, transcodes the
159 output before showing it. Takes one of "base64", "unbase64", "hex"
160 or "unhex" as argument, in order to encode/decode the credential
161 data with Base64 or as series of hexadecimal values.
162 Note that this has no effect on the encrypt command, as encrypted
164 credentials are unconditionally encoded in Base64.
165 --newline=
167 When specified with cat or decrypt controls whether to add a
168 trailing newline character to the end of the output if it doesn't
169 end in one, anyway. Takes one of "auto", "yes" or "no". The default
170 mode of "auto" will suffix the output with a single newline
171 character only when writing credential data to a TTY.
172 --pretty, -p
174 When specified with encrypt controls whether to show the encrypted
175 credential as SetCredentialEncrypted= setting that may be pasted
176 directly into a unit file.
177 --name=name
179 When specified with the encrypt command controls the credential
180 name to embed in the encrypted credential data. If not specified
181 the name is chosen automatically from the filename component of the
182 specified output path. If specified as empty string no credential
183 name is embedded in the encrypted credential, and no verification
184 of credential name is done when the credential is decrypted.
185 When specified with the decrypt command control the credential name
187 to validate the credential name embedded in the encrypted
188 credential with. If not specified the name is chosen automatically
189 from the filename component of the specified input path. If no
190 credential name is embedded in the encrypted credential file (i.e.
191 the --name= with an empty string was used when encrypted) the
192 specified name has no effect as no credential name validation is
193 done.
194 Embedding the credential name in the encrypted credential is done
196 in order to protect against reuse of credentials for purposes they
197 weren't originally intended for, under the assumption the
198 credential name is chosen carefully to encode its intended purpose.
199 --timestamp=timestamp
201 When specified with the encrypt command controls the timestamp to
202 embed into the encrypted credential. Defaults to the current time.
203 Takes a timestamp specification in the format described in
204 systemd.time(5).
205 When specified with the decrypt command controls the timestamp to
207 use to validate the "not-after" timestamp that was configured with
208 --not-after= during encryption. If not specified defaults to the
209 current system time.
210 --not-after=timestamp
212 When specified with the encrypt command controls the time when the
213 credential shall not be used anymore. This embeds the specified
214 timestamp in the encrypted credential. During decryption the
215 timestamp is checked against the current system clock, and if the
216 timestamp is in the past the decryption will fail. By default no
217 such timestamp is set. Takes a timestamp specification in the
218 format described in systemd.time(5).
219 --with-key=, -H, -T
221 When specified with the encrypt command controls the encryption key
222 to use. Takes one of "host", "tpm2", "host+tpm2" or "auto". See
223 above for details on the three key types. If set to "auto" (which
224 is the default) the TPM2 key is used if a TPM2 device is found and
225 not running in a container. The host key is used if
226 /var/lib/systemd/ is on persistent media. This means on typical
227 systems the encryption is by default bound to both the TPM2 chip
228 and the OS installation, and both need to be available to decrypt
229 the credential again. If "auto" is selected but neither TPM2 is
230 available (or running in container) nor /var/lib/systemd/ is on
231 persistent media, encryption will fail.
232 The -H switch is a shortcut for --with-key=host. Similar, -T is a
234 shortcut for -with-key=tpm2.
235 When encrypting credentials that shall be used in the initial RAM
237 disk (initrd) where /var/lib/systemd/ is typically not available
238 make sure to use --with-key=tpm2 mode, to disable binding against
239 the host secret.
240 This switch has no effect on the decrypt command, as information on
242 which key to use for decryption is included in the encrypted
243 credential already.
244 --tpm2-device=PATH
246 Controls the TPM2 device to use. Expects a device node path
247 referring to the TPM2 chip (e.g. /dev/tpmrm0). Alternatively the
248 special value "auto" may be specified, in order to automatically
249 determine the device node of a suitable TPM2 device (of which there
250 must be exactly one). The special value "list" may be used to
251 enumerate all suitable TPM2 devices currently discovered.
252 --tpm2-pcrs= [PCR...]
254 Configures the TPM2 PCRs (Platform Configuration Registers) to bind
255 the encryption key to. Takes a "+" separated list of numeric PCR
256 indexes in the range 0...23. If not used, defaults to PCR 7 only.
257 If an empty string is specified, binds the encryption key to no
258 PCRs at all. For details about the PCRs available, see the
259 documentation of the switch of the same name for systemd-
260 cryptenroll(1).
261 --no-pager
263 Do not pipe output into a pager.
264 --no-legend
266 Do not print the legend, i.e. column headers and the footer with
267 hints.
268 --json=MODE
270 Shows output formatted as JSON. Expects one of "short" (for the
271 shortest possible output without any redundant whitespace or line
272 breaks), "pretty" (for a pretty version of the same, with
273 indentation and line breaks) or "off" (to turn off JSON output, the
274 default).
275
277 On success, 0 is returned.
278
280 Example 1. Encrypt a password for use as credential
281 The following command line encrypts the specified password "hunter2",
283 writing the result to a file password.cred.
284 # echo -n hunter2 | systemd-creds encrypt - password.cred
286 This decrypts the file password.cred again, revealing the literal
288 password:
289 # systemd-creds decrypt password.cred
291 hunter2
292 Example 2. Encrypt a password and include it in a unit file
294 The following command line prompts the user for a password and
296 generates a SetCredentialEncrypted= line from it for a credential named
297 "mysql-password", suitable for inclusion in a unit file.
298 # systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - -
300 🔐 Password: ****
301 SetCredentialEncrypted=mysql-password: \
302 k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAASfFsBoPLIm/dlDoGAAAAAAAAAA \
303 NAAAAAgAAAAAH4AILIOZ3w6rTzYsBy9G7liaCAd4i+Kpvs8mAgArzwuKxd0ABDjgSeO5k \
304 mKQc58zM94ZffyRmuNeX1lVHE+9e2YD87KfRFNoDLS7F3YmCb347gCiSk2an9egZ7Y0Xs \
305 700Kr6heqQswQEemNEc62k9RJnEl2q7SbcEYguegnPQUATgAIAAsAAAASACA/B90W7E+6 \
306 yAR9NgiIJvxr9bpElztwzB5lUJAxtMBHIgAQACCaSV9DradOZz4EvO/LSaRyRSq2Hj0ym \
307 gVJk/dVzE8Uxj8H3RbsT7rIBH02CIgm/Gv1ukSXO3DMHmVQkDG0wEciyageTfrVEer8z5 \
308 9cUQfM5ynSaV2UjeUWEHuz4fwDsXGLB9eELXLztzUU9nsAyLvs3ZRR+eEK/A==
309 The generated line can be pasted 1:1 into a unit file, and will ensure
311 the acquired password will be made available in the
312 $CREDENTIALS_DIRECTORY/mysql-password credential file for the started
313 service.
314 Utilizing the unit file drop-in logic this can be used to securely pass
316 a password credential to a unit. A similar, more comprehensive set of
317 commands to insert a password into a service xyz.service:
318 # mkdir -p /etc/systemd/system/xyz.service.d
320 # systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - - > /etc/systemd/system/xyz.service.d/50-password.conf
321 # systemctl daemon-reload
322 # systemctl restart xyz.service
323
325 systemd(1), systemd.exec(5)
326systemd 250 SYSTEMD-CREDS(1)