1 ========================================== 1 ==========================================
2 Encrypted keys for the eCryptfs filesystem 2 Encrypted keys for the eCryptfs filesystem
3 ========================================== 3 ==========================================
4 4
5 ECryptfs is a stacked filesystem which transpa 5 ECryptfs is a stacked filesystem which transparently encrypts and decrypts each
6 file using a randomly generated File Encryptio 6 file using a randomly generated File Encryption Key (FEK).
7 7
8 Each FEK is in turn encrypted with a File Encr 8 Each FEK is in turn encrypted with a File Encryption Key Encryption Key (FEKEK)
9 either in kernel space or in user space with a 9 either in kernel space or in user space with a daemon called 'ecryptfsd'. In
10 the former case the operation is performed dir 10 the former case the operation is performed directly by the kernel CryptoAPI
11 using a key, the FEKEK, derived from a user pr 11 using a key, the FEKEK, derived from a user prompted passphrase; in the latter
12 the FEK is encrypted by 'ecryptfsd' with the h 12 the FEK is encrypted by 'ecryptfsd' with the help of external libraries in order
13 to support other mechanisms like public key cr 13 to support other mechanisms like public key cryptography, PKCS#11 and TPM based
14 operations. 14 operations.
15 15
16 The data structure defined by eCryptfs to cont 16 The data structure defined by eCryptfs to contain information required for the
17 FEK decryption is called authentication token 17 FEK decryption is called authentication token and, currently, can be stored in a
18 kernel key of the 'user' type, inserted in the 18 kernel key of the 'user' type, inserted in the user's session specific keyring
19 by the userspace utility 'mount.ecryptfs' ship 19 by the userspace utility 'mount.ecryptfs' shipped with the package
20 'ecryptfs-utils'. 20 'ecryptfs-utils'.
21 21
22 The 'encrypted' key type has been extended wit 22 The 'encrypted' key type has been extended with the introduction of the new
23 format 'ecryptfs' in order to be used in conju 23 format 'ecryptfs' in order to be used in conjunction with the eCryptfs
24 filesystem. Encrypted keys of the newly intro 24 filesystem. Encrypted keys of the newly introduced format store an
25 authentication token in its payload with a FEK 25 authentication token in its payload with a FEKEK randomly generated by the
26 kernel and protected by the parent master key. 26 kernel and protected by the parent master key.
27 27
28 In order to avoid known-plaintext attacks, the 28 In order to avoid known-plaintext attacks, the datablob obtained through
29 commands 'keyctl print' or 'keyctl pipe' does 29 commands 'keyctl print' or 'keyctl pipe' does not contain the overall
30 authentication token, which content is well kn 30 authentication token, which content is well known, but only the FEKEK in
31 encrypted form. 31 encrypted form.
32 32
33 The eCryptfs filesystem may really benefit fro 33 The eCryptfs filesystem may really benefit from using encrypted keys in that the
34 required key can be securely generated by an A 34 required key can be securely generated by an Administrator and provided at boot
35 time after the unsealing of a 'trusted' key in 35 time after the unsealing of a 'trusted' key in order to perform the mount in a
36 controlled environment. Another advantage is 36 controlled environment. Another advantage is that the key is not exposed to
37 threats of malicious software, because it is a 37 threats of malicious software, because it is available in clear form only at
38 kernel level. 38 kernel level.
39 39
40 Usage:: 40 Usage::
41 41
42 keyctl add encrypted name "new ecryptfs key 42 keyctl add encrypted name "new ecryptfs key-type:master-key-name keylen" ring
43 keyctl add encrypted name "load hex_blob" r 43 keyctl add encrypted name "load hex_blob" ring
44 keyctl update keyid "update key-type:master 44 keyctl update keyid "update key-type:master-key-name"
45 45
46 Where:: 46 Where::
47 47
48 name:= '<16 hexadecimal characters>' 48 name:= '<16 hexadecimal characters>'
49 key-type:= 'trusted' | 'user' 49 key-type:= 'trusted' | 'user'
50 keylen:= 64 50 keylen:= 64
51 51
52 52
53 Example of encrypted key usage with the eCrypt 53 Example of encrypted key usage with the eCryptfs filesystem:
54 54
55 Create an encrypted key "1000100010001000" of 55 Create an encrypted key "1000100010001000" of length 64 bytes with format
56 'ecryptfs' and save it using a previously load 56 'ecryptfs' and save it using a previously loaded user key "test"::
57 57
58 $ keyctl add encrypted 1000100010001000 "n 58 $ keyctl add encrypted 1000100010001000 "new ecryptfs user:test 64" @u
59 19184530 59 19184530
60 60
61 $ keyctl print 19184530 61 $ keyctl print 19184530
62 ecryptfs user:test 64 490045d4bfe48c99f0d4 62 ecryptfs user:test 64 490045d4bfe48c99f0d465fbbbb79e7500da954178e2de0697
63 dd85091f5450a0511219e9f7cd70dcd49803818146 63 dd85091f5450a0511219e9f7cd70dcd498038181466f78ac8d4c19504fcc72402bfc41c2
64 f253a41b7507ccaa4b2b03fff19a69d1cc0b16e717 64 f253a41b7507ccaa4b2b03fff19a69d1cc0b16e71746473f023a95488b6edfd86f7fdd40
65 9d292e4bacded1258880122dd553a661 65 9d292e4bacded1258880122dd553a661
66 66
67 $ keyctl pipe 19184530 > ecryptfs.blob 67 $ keyctl pipe 19184530 > ecryptfs.blob
68 68
69 Mount an eCryptfs filesystem using the created 69 Mount an eCryptfs filesystem using the created encrypted key "1000100010001000"
70 into the '/secret' directory:: 70 into the '/secret' directory::
71 71
72 $ mount -i -t ecryptfs -oecryptfs_sig=1000 72 $ mount -i -t ecryptfs -oecryptfs_sig=1000100010001000,\
73 ecryptfs_cipher=aes,ecryptfs_key_bytes=3 73 ecryptfs_cipher=aes,ecryptfs_key_bytes=32 /secret /secret
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.