Skip to main content

Encryption

Configure encrypted volumes of underlying disk partitions or software RAID arrays.

CharacteristicValue
Typeobject

Properties​

pcrs (required)​

List of PCRs in the TPM 2.0 device to seal encrypted volumes to in the target OS. This field is required, and at least one PCR must be provided. Each PCR may be specified either as a digit or as a string.

Grub Target OS​

When doing a clean install of a grub target OS image, the following options are valid:

  • 7, or secure-boot-policy

UKI Target OS​

When doing a clean install of a UKI target OS image, the following options are valid:

  • 4, or boot-loader-code

  • 7, or secure-boot-policy

  • 11, or kernel-boot

  • 4 and 7

  • 4 and 11

  • 7 and 11

  • 4, 7, and 11

However, due to the limitations of systemd-pcrlock, which is used internally for encryption in UKI OS, PCR 7 CANNOT be used if:

  • SecureBoot is disabled,

  • Trident is running inside a container.

To use PCR 7 for encryption in a target UKI OS, Trident must be running in a non-containerized environment, with SecureBoot enabled.

More encryption flows, with additional PCR options, will be added in the future.

CharacteristicValue
Typearray

  • Items of the array must have the type:

    CharacteristicValue
    TypePcr
    LinkPcr

volumes (required)​

The list of LUKS2-encrypted volumes to create.

This parameter is required and must not be empty. Each item is an object that will contain the configuration for a given partition or RAID array.

CharacteristicValue
Typearray

  • Items of the array must have the type:

    CharacteristicValue
    TypeEncryptedVolume
    LinkEncryptedVolume

clearTpmOnInstall (optional)​

Optional parameter that determines whether the TPM 2.0 device will be cleared on clean install. By default, it is set to false. If set to true, Trident will clear the TPM 2.0 device on install. TPM cannot be cleared on A/B updates.

Clearing the TPM 2.0 device will remove all keys and data from the TPM 2.0 device. This operation is irreversible and could result in data loss. However, this option might be needed to ensure that the TPM 2.0 is in a known state; to avoid entering the DA (Direct Attack) lockout mode on repetitive provisioning attempts, e.g. during testing and development.

CharacteristicValue
Typeboolean

recoveryKeyUrl (optional)​

A URL to read the recovery key from.

This parameter allows specifying a local file path to a recovery key file via a file:// URL scheme. The recovery key file serves as an essential fallback to recover data should TPM 2.0 automatic decryption fail. If not specified, only the TPM 2.0 device will be enrolled.

The URL must be non-empty if provided. Other URL schemes are not supported at this time.

It is strongly advised to configure a recovery key file, as it plays a pivotal role in data recovery.

File Format Expectations​

The recovery key file must be a binary file without any encoding. This direct format ensures compatibility with cryptsetup and systemd APIs. Be mindful that all file content, including any potential whitespace or newline characters, is considered part of the recovery key.

Security Considerations​

Ensuring the recovery key's confidentiality and integrity is paramount. Employ secure storage and rigorous access control measures. Specifically:

  • The file containing the key should only be accessible by the root user and have 0400 permissions set.

  • The recovery key should be a minimum of 32 bytes long and should be generated with a high enough entropy to defend against brute force or cryptographic attacks targeting on-disk hash values.

Generating a Recovery Key​

One way to create a recovery key file on Linux systems is using the dd utility:

Note: The following example is for illustration purposes only. Be sure to generate > recovery keys with diligence and attention to security principles. Please adjust the > following example according to your own security policies and operational environment to > fit your specific security requirements and constraints.

sh touch ./recovery.key chmod 0400 ./recovery.key dd if=/dev/random of=./recovery.key bs=1 count=256

This command generates 256 bytes of random data for the recovery key, sourcing entropy from /dev/random. Be aware, in environments with limited entropy sources, such as certain embedded systems, /dev/random may not provide sufficient data promptly. Alternative entropy sources or methods may be required.

CharacteristicValue
Typestring
Formaturi