1 files changed, 68 insertions, 0 deletions
diff --git a/modules.d/97masterkey/README b/modules.d/97masterkey/README
new file mode 100644
index 0000000..524ccfc
--- /dev/null
+++ b/modules.d/97masterkey/README
@@ -0,0 +1,68 @@
+# 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/