ampel/docs
2
0
Fork 0
Code Issues Pull requests Activity

docs/zlevis/functionality.md: add

Browse source
This commit is contained in:
Luc Bijl 2025-07-31 18:03:06 +02:00
parent 208c5d469f
commit 553b224e06
1 changed files with 81 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

81
docs/zlevis/functionality.md Normal file
View file

@ -0,0 +1,81 @@
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:
``` shell-session
# 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:
``` shell-session
# 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:
``` shell-session
# 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:
``` shell-session
# 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:
``` shell-session
# 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
``` shell-session
# 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](https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/).
| 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. |