diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 64dcbbedea..ccb1567900 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -2338,7 +2338,8 @@ SystemCallErrorNumber=EPERM clients via D-Bus IPC, and generally not understood as being data that requires protection. Moreover, environment variables are propagated down the process tree, including across security boundaries (such as setuid/setgid executables), and hence might leak to processes that should not have access to - the secret data. Use LoadCredential= (see below) to pass data to unit processes + the secret data. Use LoadCredential=, LoadCredentialEncrypted= + or SetCredentialEncrypted= (see below) to pass data to unit processes securely. @@ -2832,6 +2833,7 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy LoadCredential=ID:PATH + LoadCredentialEncrypted=ID:PATH Pass a credential to the unit. Credentials are limited-size binary or textual objects that may be passed to unit processes. They are primarily used for passing cryptographic keys (both @@ -2860,6 +2862,20 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy from the service manager into a service. This option may be used multiple times, each time defining an additional credential to pass to the unit. + The LoadCredentialEncrypted= setting is identical to + LoadCredential=, except that the credential data is decrypted before being passed + on to the executed processes. Specifically, the referenced path should refer to a file or socket with + an encrypted credential, as implemented by + systemd-creds1. This + credential is loaded, decrypted and then passed to the application in decrypted plaintext form, in + the same way a regular credential specified via LoadCredential= would be. A + credential configured this way may encrypted with a secret key derived from the system's TPM2 + security chip, or with a secret key stored in + /var/lib/systemd/credentials.secret, or with both. Using encrypted credentials + improves security as credentials are not stored in plaintext and only decrypted into plaintext the + moment a service requiring them is started. Moreover, credentials may be bound to the local hardware + and installations, so that they cannot easily be analyzed offline. + The credential files/IPC sockets must be accessible to the service manager, but don't have to be directly accessible to the unit's processes: the credential data is read and copied into separate, read-only copies for the unit that are accessible to appropriately privileged processes. This is @@ -2891,6 +2907,7 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy SetCredential=ID:VALUE + SetCredentialEncrypted=ID:VALUE The SetCredential= setting is similar to LoadCredential= but accepts a literal value to use as data for the credential, @@ -2901,6 +2918,14 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy C-style escaping (i.e. \n to embed a newline, or \x00 to embed a NUL byte). + The SetCredentialEncrypted= setting is identical to + SetCredential= but expects an encrypted credential in literal form as value. This + allows embedding confidential credentials securely directly in unit files. Use + systemd-creds1' + switch to generate suitable SetCredentialEncrypted= lines + directly from plaintext credentials. For further details see + LoadCredentialEncrypted= above. + If a credential of the same ID is listed in both LoadCredential= and SetCredential=, the latter will act as default if the former cannot be retrieved. In this case not being able to retrieve the credential from the path specified in