From af18b157b92a7a5408c17290ef19615f59c9a3a3 Mon Sep 17 00:00:00 2001 From: Luc Bijl Date: Sun, 2 Mar 2025 21:27:33 +0100 Subject: [PATCH] Update functionality --- functionality.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/functionality.md b/functionality.md index 8318c86..245cf13 100644 --- a/functionality.md +++ b/functionality.md @@ -1 +1,36 @@ -Test \ No newline at end of file +One of the cornerstones of the development of `zlevis` is simplicity. The `zlevis` package only contains four commands, two for usage with a ZFS root pool and two for usage without a ZFS root pool. + +## Usage with ZFS root pool + +When considering the decryption of a ZFS root pool with `zlevis` we have two commands.The first should be performed 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 general 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 wrote a JWE (JSON Web Encryption) token to (created) `tpm:jwe` property of the ZFS root dataset of the root pool. This JWE token can be interpreted as the public key to the key stored in TPM. You can obtain the JWE by performing: + +``` shell-session +# zfs get tpm:jwe rpool/root/ +``` + +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` ... + +## Usage without ZFS root pool + +## Configuration properties + +Table of configuration properties. + +| Property | Possible values | Explanation | +| ------------- | -------------------------- | ------------------- | +| Hash | SHA256 (Default), SHA512 | Hash algorithm used in the computation of the object name. | +| Key | ECC (default), | Algorithm type for the generated key. |