io.systemd.Credentials¶

APIs for encrypting and decrypting service credentials.

Property	Value
Go package	`github.com/rossedman/sdvarlink/systemd/latest/credentials`
Socket	`/run/systemd/io.systemd.Credentials`
Available since	systemd v257
Methods · types · errors	2 · 2 · 10

Methods¶

Encrypt¶

Encrypts some plaintext data, returns an encrypted credential.

func (c *Client) Encrypt(ctx context.Context, in EncryptIn) (*EncryptOut, error)

Parameters

Field	Type	Description
`name`	`?string`	The name for the encrypted credential, a string suitable for inclusion in a file name. If not specified no name is encoded in the credential. Typically, if this credential is stored on disk, this is how the file should be called, and permits authentication of the filename.
`text`	`?string`	Plaintext to encrypt. Suitable only for textual data. Either this field or 'data' (below) must be provided.
`data`	`?string`	Plaintext to encrypt, encoded in Base64. Suitable for binary data. Either this field or 'text' (above) must be provided.
`timestamp`	`?int`	Timestamp to store in the credential. In µs since the UNIX epoch, i.e. Jan 1^st 1970. If not specified the current time is used.
`notAfter`	`?int`	Timestamp when to the credential should be considered invalid. In µs since the UNIX epoch. If not specified, the credential remains valid forever.
`scope`	`?Scope`	The intended scope for the credential. One of 'system' or 'user'. If not specified defaults to 'system', unless an uid is specified (see below), in which case it default to 'user'.
`withKey`	`?WithKey`	Selects the type of key to encrypt this with
`uid`	`?int`	The numeric UNIX UID of the user the credential shall be scoped to. Only relevant if 'user' scope is selected (see above). If not specified and 'user' scope is selected defaults to the UID of the calling user, if that can be determined.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.

Reply

Field	Type	Description
`blob`	`string`	Encrypted credential in Base64 encoding. This can be stored in a credential file, for consumption in LoadEncryptedCredential= and similar calls. Note that the Base64 encoding should be retained when copied into a file.

Decrypt¶

Decrypts an encrypted credential, returns plaintext data.

func (c *Client) Decrypt(ctx context.Context, in DecryptIn) (*DecryptOut, error)

Parameters

Field	Type	Description
`name`	`?string`	The name of the encrypted credential. Must the same string specified when the credential was encrypted, in order to authenticate this. If not specified authentication of the credential name is not done.
`blob`	`string`	The encrypted credential in Base64 encoding. This corresponds of the 'blob' field returned by the 'Encrypt' method.
`timestamp`	`?int`	The timestamp to use when validating the credential's time validity range. If not specified the current time is used.
`scope`	`?Scope`	The scope for this credential. If not specified no restrictions on the credential scope are made.
`uid`	`?int`	If the 'user' scope is selected, specifies the numeric UNIX UID of the user the credential is associated with. If not specified this is automatically derived from the UID of the calling user, if that can be determined.
`allowNull`	`?bool`	If true allows decryption of credentials encrypted with the null key, if false does not allow it, if unset/null the default depends on whether a TPM device exists and SecureBoot is enabled.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.

Reply

Field	Type	Description
`data`	`string`	The decrypted plaintext data in Base64 encoding.

Types¶

Scope¶

The intended scope for the credential.

Value	Description
`system`	Generate a system-bound credential
`user`	Generate a system and user bound credential

WithKey¶

Selects the key(s) to encrypt the credentials with.

Value	Description
`auto`	Automatically pick the key to bind the credential to
`auto_initrd`	Automatically pick the key to bind the credential to, but ensure it is accessible in the initrd, thus potentially leaving it unencrypted.
`host`	Bind to the host key only, i.e. not the TPM
`tpm2`	Bind to the TPM only, not the host key
`tpm2_with_public_key`	Bind to the TPM only (using a public key identifying the UKI), not the host key
`host_tpm2`	Bind to both the TPM and the host key
`host_tpm2_with_public_key`	Bind to both the TPM (using a public key identifying the UKI) and the host key
`null`	Do not bind to either host key nor the TPM, thus using null encryption (this provides no authenticity nor confidentiality guarantees)

Errors¶

Error	Go type	Description
`BadFormat`	`BadFormatError`	Indicates that a corrupt and unsupported encrypted credential was provided.
`NameMismatch`	`NameMismatchError`	The specified name does not match the name stored in the credential.
`TimeMismatch`	`TimeMismatchError`	The credential's is no longer or not yet valid.
`NoSuchUser`	`NoSuchUserError`	The specified user does not exist.
`BadScope`	`BadScopeError`	The credential does not match the selected scope.
`CantFindPCRSignature`	`CantFindPCRSignatureError`	PCR signature required for decryption, but not found.
`NullKeyNotAllowed`	`NullKeyNotAllowedError`	The key was encrypted with a null key, but that's now allowed during decryption.
`KeyBelongsToOtherTPM`	`KeyBelongsToOtherTPMError`	The TPM integrity check for this key failed, key probably belongs to another TPM, or was corrupted.
`TPMInDictionaryLockout`	`TPMInDictionaryLockoutError`	The TPM is in dictionary lockout mode, cannot operate.
`UnexpectedPCRState`	`UnexpectedPCRStateError`	Unexpected TPM PCR state of the system.