# Directions for creating the kernel master key that will be used for
# encrypting/decrypting other keys.

# A trusted key is a TPM random number, which is only ever exposed to
# userspace as an encrypted datablob. A trusted key can be sealed to a
# set of PCR values. For more details on trusted keys, refer to the
# kernel keys-trusted-encrypted.txt documentation.
$ keyctl add trusted kmk-trusted "new 32" @u
801713097

# For those systems which don't have a TPM, but want to experiment with
# encrypted keys, create a user key of 32 random bytes. Unlike
# trusted/encrypted keys, user type key data is visible to userspace.
$ keyctl add user kmk-user "`dd if=/dev/urandom bs=1 count=32 2>/dev/null`" @u
144468621

# Save the kernel master key (trusted type):
$ su -c 'keyctl pipe `keyctl search @u trusted kmk-trusted` > /etc/keys/kmk-trusted.blob'

# or (user type):
$ su -c 'keyctl pipe `keyctl search @u user kmk-user` > /etc/keys/kmk-user.blob'

# A useful feature of trusted keys is that it is possible to prevent their
# unsealing at later time by providing the parameter 'pcrlock=<pcrnum>' when
# loading it, which causes the PCR #<pcrnum> to be extended with a random value.
# Actually, the <pcrnum> variable is set to '11' to let users experiment with
# this feature by using a register that is never extended during the boot,
# making the re-sealing not necessary. In the future, the kernel master key will
# be sealed to the PCR #14 which is extended, according to the TrustedGRUB
# documentation[1], to the measure of the kernel and the initial ramdisk.

# The kernel master key path name and type can be set in one of the following
# ways (specified in the order in which variables are overwritten):

1) use default values:
--------------------------------------------------------------------------
MULTIKERNELMODE="NO"
MASTERKEYTYPE="trusted"
MASTERKEY="/etc/keys/kmk-${MASTERKEYTYPE}.blob"
--------------------------------------------------------------------------

2) create the configuration file '/etc/sysconfig/masterkey' to override the
value of one or all variables;

3) specify these parameters in the kernel command line:
- masterkey=</kernel/master/key/path>, to override the MASTERKEY variable;
- masterkeytype=<kernel-master-key-type>, to override the MASTERKEYTYPE variable.

# The variable MULTIKERNELMODE has been introduced to support multi boot
# configurations, where a trusted/user key is tied to a specific kernel and
# initial ramdisk. In this case, setting MULTIKERNELMODE to 'YES' will cause the
# kernel version to be added to the default masterkey path name, so that the
# MASTERKEY variable should not be overridden each time a different kernel is
# chosen. The default value of MASTERKEY will be equal to:
--------------------------------------------------------------------------
MASTERKEY="/etc/keys/kmk-${MASTERKEYTYPE}-$(uname -r).blob"
--------------------------------------------------------------------------

# The masterkey path name also depends on the value of MASTERKEYTYPE, as reported
# in the default values for defined variables. For example, if only MASTERKEYTYPE
# is overridden by setting it to 'user' in the configuration file or from the
# kernel command line, the value of MASTERKEY will be:
--------------------------------------------------------------------------
MASTERKEY="/etc/keys/kmk-user.blob"
--------------------------------------------------------------------------


[1] https://projects.sirrix.com/trac/trustedgrub/