0001 ==========================================
0002 Encrypted keys for the eCryptfs filesystem
0003 ==========================================
0004
0005 ECryptfs is a stacked filesystem which transparently encrypts and decrypts each
0006 file using a randomly generated File Encryption Key (FEK).
0007
0008 Each FEK is in turn encrypted with a File Encryption Key Encryption Key (FEKEK)
0009 either in kernel space or in user space with a daemon called 'ecryptfsd'. In
0010 the former case the operation is performed directly by the kernel CryptoAPI
0011 using a key, the FEKEK, derived from a user prompted passphrase; in the latter
0012 the FEK is encrypted by 'ecryptfsd' with the help of external libraries in order
0013 to support other mechanisms like public key cryptography, PKCS#11 and TPM based
0014 operations.
0015
0016 The data structure defined by eCryptfs to contain information required for the
0017 FEK decryption is called authentication token and, currently, can be stored in a
0018 kernel key of the 'user' type, inserted in the user's session specific keyring
0019 by the userspace utility 'mount.ecryptfs' shipped with the package
0020 'ecryptfs-utils'.
0021
0022 The 'encrypted' key type has been extended with the introduction of the new
0023 format 'ecryptfs' in order to be used in conjunction with the eCryptfs
0024 filesystem. Encrypted keys of the newly introduced format store an
0025 authentication token in its payload with a FEKEK randomly generated by the
0026 kernel and protected by the parent master key.
0027
0028 In order to avoid known-plaintext attacks, the datablob obtained through
0029 commands 'keyctl print' or 'keyctl pipe' does not contain the overall
0030 authentication token, which content is well known, but only the FEKEK in
0031 encrypted form.
0032
0033 The eCryptfs filesystem may really benefit from using encrypted keys in that the
0034 required key can be securely generated by an Administrator and provided at boot
0035 time after the unsealing of a 'trusted' key in order to perform the mount in a
0036 controlled environment. Another advantage is that the key is not exposed to
0037 threats of malicious software, because it is available in clear form only at
0038 kernel level.
0039
0040 Usage::
0041
0042 keyctl add encrypted name "new ecryptfs key-type:master-key-name keylen" ring
0043 keyctl add encrypted name "load hex_blob" ring
0044 keyctl update keyid "update key-type:master-key-name"
0045
0046 Where::
0047
0048 name:= '<16 hexadecimal characters>'
0049 key-type:= 'trusted' | 'user'
0050 keylen:= 64
0051
0052
0053 Example of encrypted key usage with the eCryptfs filesystem:
0054
0055 Create an encrypted key "1000100010001000" of length 64 bytes with format
0056 'ecryptfs' and save it using a previously loaded user key "test"::
0057
0058 $ keyctl add encrypted 1000100010001000 "new ecryptfs user:test 64" @u
0059 19184530
0060
0061 $ keyctl print 19184530
0062 ecryptfs user:test 64 490045d4bfe48c99f0d465fbbbb79e7500da954178e2de0697
0063 dd85091f5450a0511219e9f7cd70dcd498038181466f78ac8d4c19504fcc72402bfc41c2
0064 f253a41b7507ccaa4b2b03fff19a69d1cc0b16e71746473f023a95488b6edfd86f7fdd40
0065 9d292e4bacded1258880122dd553a661
0066
0067 $ keyctl pipe 19184530 > ecryptfs.blob
0068
0069 Mount an eCryptfs filesystem using the created encrypted key "1000100010001000"
0070 into the '/secret' directory::
0071
0072 $ mount -i -t ecryptfs -oecryptfs_sig=1000100010001000,\
0073 ecryptfs_cipher=aes,ecryptfs_key_bytes=32 /secret /secret
