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