nixos/modules/system/boot/clevis.md

   1 # Clevis {#module-boot-clevis}
   2
   3 [Clevis](https://github.com/latchset/clevis)
   4 is a framework for automated decryption of resources.
   5 Clevis allows for secure unattended disk decryption during boot, using decryption policies that must be satisfied for the data to decrypt.
   6
   7
   8 ## Create a JWE file containing your secret {#module-boot-clevis-create-secret}
   9
  10 The first step is to embed your secret in a [JWE](https://en.wikipedia.org/wiki/JSON_Web_Encryption) file.
  11 JWE files have to be created through the clevis command line. 3 types of policies are supported:
  12
  13 1) TPM policies
  14
  15 Secrets are pinned against the presence of a TPM2 device, for example:
  16 ```
  17 echo -n hi | clevis encrypt tpm2 '{}' > hi.jwe
  18 ```
  19 2) Tang policies
  20
  21 Secrets are pinned against the presence of a Tang server, for example:
  22 ```
  23 echo -n hi | clevis encrypt tang '{"url": "http://tang.local"}' > hi.jwe
  24 ```
  25
  26 3) Shamir Secret Sharing
  27
  28 Using Shamir's Secret Sharing ([sss](https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing)), secrets are pinned using a combination of the two preceding policies. For example:
  29 ```
  30 echo -n hi | clevis encrypt sss \
  31 '{"t": 2, "pins": {"tpm2": {"pcr_ids": "0"}, "tang": {"url": "http://tang.local"}}}' \
  32 > hi.jwe
  33 ```
  34
  35 For more complete documentation on how to generate a secret with clevis, see the [clevis documentation](https://github.com/latchset/clevis).
  36
  37
  38 ## Activate unattended decryption of a resource at boot {#module-boot-clevis-activate}
  39
  40 In order to activate unattended decryption of a resource at boot, enable the `clevis` module:
  41
  42 ```nix
  43 {
  44   boot.initrd.clevis.enable = true;
  45 }
  46 ```
  47
  48 Then, specify the device you want to decrypt using a given clevis secret. Clevis will automatically try to decrypt the device at boot and will fallback to interactive unlocking if the decryption policy is not fulfilled.
  49 ```nix
  50 {
  51   boot.initrd.clevis.devices."/dev/nvme0n1p1".secretFile = ./nvme0n1p1.jwe;
  52 }
  53 ```
  54
  55 Only `bcachefs`, `zfs` and `luks` encrypted devices are supported at this time.