Table of Contents
A cornerstone in the development of zlevis is simplicity, the zlevis package contains essentially only 2 commands and can be used with or without a ZFS root pool.
Usage with ZFS root pool
When we consider the decryption of a ZFS root pool with zlevis the first step is to write the encryption key to the TPM. Often this encryption key is created in the provisioning phase of the installation of a system, particularly when we are still in the live ISO environment. It is common practice to write the randomly generated key to /tmp/rpool.key on the live ISO. After creation of the pool we may write the encryption key to the TPM by:
# zlevis encrypt rpool '{"propery":"value"}' < /tmp/rpool.key
Under "property" we can set the hash, key, pcr_bank, pcr_ids and pcr_digest. See the configuration properties section for all the options.
This command writes a JWE (JSON Web Encryption) token to the tpm:jwe property of the ZFS root dataset of the root pool. This JWE token can be interpreted as the public key. You can obtain the JWE by performing:
# zfs get tpm:jwe rpool/root/<distro>
In the now installed and configured system the encryption key of the root pool can be obtained by performing:
# zlevis decrypt rpool
This command will fetch the JWE from tpm:jwe and use it to obtain the encryption key.
Usage without ZFS root pool
We can also use zlevis to plainly store keys in TPM and fetch keys from TPM. This requires us to store the JWE locally in file.jwe, we can write a key file.key to TPM with:
# zlevis-encrypt '{"propery":"value"}' < file.key > file.jwe
Under "property" we can set the hash, key, pcr_bank, pcr_ids and pcr_digest. See the configuration properties section for all the options.
You can fetch the key with the locally stored file.jwe by performing:
# zlevis-decrypt < file.jwe
Marking the end of the functionality outline of zlevis.
Configuration properties
The table of configuration properties is given below.
| Property | Possible values | Explanation |
|---|---|---|
| Hash | sha1, sha256, sha384, sha512, sm3_256 |
Hash algorithm used in the computation of the object name. |
| Key | rsa, keyedhash , ecc, symcipher |
Algorithm type for the generated key. |
| PCR Bank | sha1, sha256, ... |
PCR algorithm bank to use for policy. |
| PCR IDs | 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 23 |
Comma separated list of PCR used for policy. If not present, no policy is used. |
| PCR Digest | ... |
Binary PCR hashes encoded in base64. If not present, the hash values are looked up. |
For the full list of algorithms supported by the TPM chip check the output of
# tpm2_getcap pcrs
and use the the algorithm which shows a non-empty list of PCR IDs.
The table describing each PCR ID is given below.
A detailed explanation of the TPM implementation is available at Trusted Computing Group's website.
| PCR | TCG Description | Notes |
|---|---|---|
| 0 | SRTM, BIOS, host platform extensions, embedded option, ROMs and PI drivers | Stores firmware, may change if the UEFI/BIOS is updated. Acts as the root for the chain of trust. Some implementations record CPU microcode measurements here. |
| 1 | Host platform configuration | The UEFI configuration itself, such as settings. This typically contains the entire contents of the CMOS/NVRAM, minus any dynamic or security-sensitive data. |
| 2 | UEFI driver and application code | Option ROMs. |
| 3 | UEFI driver and application configuration and data | Option ROM configuration. |
| 4 | UEFI boot manager code (usually the MBR) and boot attempts | Measures manager code itself, and that a use was attempted. |
| 5 | Boot manager code configuration and data (for use by the boot-manager code) and GPT/partition table | Measures the configuration of the boot device, including the GPT partition table of the device. |
| 6 | Host platform manufacturer specific | May be used for S4 and S5 Power State Events. |
| 7 | Secure-boot policy | Measures contents of secure-boot keys and certificates used to verify boot applications. |
| 8-15 | Defined for use by the static OS | See the documentation of the OS for more details. |
| 16 | Debug | Optional, and sometimes unused PCR. |
| 23 | Application support | Can be set and reset by the OS. |