modules.d/97masterkey/README

   1 # Directions for creating the kernel master key that will be used for
   2 # encrypting/decrypting other keys.
   3
   4 # A trusted key is a TPM random number, which is only ever exposed to
   5 # userspace as an encrypted datablob. A trusted key can be sealed to a
   6 # set of PCR values. For more details on trusted keys, refer to the
   7 # kernel keys-trusted-encrypted.txt documentation.
   8 $ keyctl add trusted kmk-trusted "new 32" @u
   9 801713097
  10
  11 # For those systems which don't have a TPM, but want to experiment with
  12 # encrypted keys, create a user key of 32 random bytes. Unlike
  13 # trusted/encrypted keys, user type key data is visible to userspace.
  14 $ keyctl add user kmk-user "`dd if=/dev/urandom bs=1 count=32 2>/dev/null`" @u
  15 144468621
  16
  17 # Save the kernel master key (trusted type):
  18 $ su -c 'keyctl pipe `keyctl search @u trusted kmk-trusted` > /etc/keys/kmk-trusted.blob'
  19
  20 # or (user type):
  21 $ su -c 'keyctl pipe `keyctl search @u user kmk-user` > /etc/keys/kmk-user.blob'
  22
  23 # A useful feature of trusted keys is that it is possible to prevent their
  24 # unsealing at later time by providing the parameter 'pcrlock=<pcrnum>' when
  25 # loading it, which causes the PCR #<pcrnum> to be extended with a random value.
  26 # Actually, the <pcrnum> variable is set to '11' to let users experiment with
  27 # this feature by using a register that is never extended during the boot,
  28 # making the re-sealing not necessary. In the future, the kernel master key will
  29 # be sealed to the PCR #14 which is extended, according to the TrustedGRUB
  30 # documentation[1], to the measure of the kernel and the initial ramdisk.
  31
  32 # The kernel master key path name and type can be set in one of the following
  33 # ways (specified in the order in which variables are overwritten):
  34
  35 1) use default values:
  36 --------------------------------------------------------------------------
  37 MULTIKERNELMODE="NO"
  38 MASTERKEYTYPE="trusted"
  39 MASTERKEY="/etc/keys/kmk-${MASTERKEYTYPE}.blob"
  40 --------------------------------------------------------------------------
  41
  42 2) create the configuration file '/etc/sysconfig/masterkey' to override the
  43 value of one or all variables;
  44
  45 3) specify these parameters in the kernel command line:
  46 - masterkey=</kernel/master/key/path>, to override the MASTERKEY variable;
  47 - masterkeytype=<kernel-master-key-type>, to override the MASTERKEYTYPE variable.
  48
  49 # The variable MULTIKERNELMODE has been introduced to support multi boot
  50 # configurations, where a trusted/user key is tied to a specific kernel and
  51 # initial ramdisk. In this case, setting MULTIKERNELMODE to 'YES' will cause the
  52 # kernel version to be added to the default masterkey path name, so that the
  53 # MASTERKEY variable should not be overridden each time a different kernel is
  54 # chosen. The default value of MASTERKEY will be equal to:
  55 --------------------------------------------------------------------------
  56 MASTERKEY="/etc/keys/kmk-${MASTERKEYTYPE}-$(uname -r).blob"
  57 --------------------------------------------------------------------------
  58
  59 # The masterkey path name also depends on the value of MASTERKEYTYPE, as reported
  60 # in the default values for defined variables. For example, if only MASTERKEYTYPE
  61 # is overridden by setting it to 'user' in the configuration file or from the
  62 # kernel command line, the value of MASTERKEY will be:
  63 --------------------------------------------------------------------------
  64 MASTERKEY="/etc/keys/kmk-user.blob"
  65 --------------------------------------------------------------------------
  66
  67
  68 [1] https://projects.sirrix.com/trac/trustedgrub/