]>
Commit | Line | Data |
---|---|---|
d00a1c72 MZ |
1 | Trusted and Encrypted Keys |
2 | ||
3 | Trusted and Encrypted Keys are two new key types added to the existing kernel | |
40e47125 | 4 | key ring service. Both of these new types are variable length symmetric keys, |
d00a1c72 MZ |
5 | and in both cases all keys are created in the kernel, and user space sees, |
6 | stores, and loads only encrypted blobs. Trusted Keys require the availability | |
7 | of a Trusted Platform Module (TPM) chip for greater security, while Encrypted | |
8 | Keys can be used on any system. All user level blobs, are displayed and loaded | |
9 | in hex ascii for convenience, and are integrity verified. | |
10 | ||
11 | Trusted Keys use a TPM both to generate and to seal the keys. Keys are sealed | |
12 | under a 2048 bit RSA key in the TPM, and optionally sealed to specified PCR | |
13 | (integrity measurement) values, and only unsealed by the TPM, if PCRs and blob | |
14 | integrity verifications match. A loaded Trusted Key can be updated with new | |
15 | (future) PCR values, so keys are easily migrated to new pcr values, such as | |
16 | when the kernel and initramfs are updated. The same key can have many saved | |
17 | blobs under different PCR values, so multiple boots are easily supported. | |
18 | ||
19 | By default, trusted keys are sealed under the SRK, which has the default | |
20 | authorization value (20 zeros). This can be set at takeownership time with the | |
21 | trouser's utility: "tpm_takeownership -u -z". | |
22 | ||
23 | Usage: | |
24 | keyctl add trusted name "new keylen [options]" ring | |
25 | keyctl add trusted name "load hex_blob [pcrlock=pcrnum]" ring | |
26 | keyctl update key "update [options]" | |
27 | keyctl print keyid | |
28 | ||
29 | options: | |
5beb0c43 JS |
30 | keyhandle= ascii hex value of sealing key default 0x40000000 (SRK) |
31 | keyauth= ascii hex auth for sealing key default 0x00...i | |
32 | (40 ascii zeros) | |
33 | blobauth= ascii hex auth for sealed data default 0x00... | |
34 | (40 ascii zeros) | |
5beb0c43 JS |
35 | pcrinfo= ascii hex of PCR_INFO or PCR_INFO_LONG (no default) |
36 | pcrlock= pcr number to be extended to "lock" blob | |
37 | migratable= 0|1 indicating permission to reseal to new PCR values, | |
38 | default 1 (resealing allowed) | |
39 | hash= hash algorithm name as a string. For TPM 1.x the only | |
40 | allowed value is sha1. For TPM 2.x the allowed values | |
41 | are sha1, sha256, sha384, sha512 and sm3-256. | |
42 | policydigest= digest for the authorization policy. must be calculated | |
43 | with the same hash algorithm as specified by the 'hash=' | |
44 | option. | |
45 | policyhandle= handle to an authorization policy session that defines the | |
46 | same policy and with the same hash algorithm as was used to | |
47 | seal the key. | |
d00a1c72 MZ |
48 | |
49 | "keyctl print" returns an ascii hex copy of the sealed key, which is in standard | |
50 | TPM_STORED_DATA format. The key length for new keys are always in bytes. | |
51 | Trusted Keys can be 32 - 128 bytes (256 - 1024 bits), the upper limit is to fit | |
52 | within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding. | |
53 | ||
54 | Encrypted keys do not depend on a TPM, and are faster, as they use AES for | |
55 | encryption/decryption. New keys are created from kernel generated random | |
56 | numbers, and are encrypted/decrypted using a specified 'master' key. The | |
57 | 'master' key can either be a trusted-key or user-key type. The main | |
58 | disadvantage of encrypted keys is that if they are not rooted in a trusted key, | |
59 | they are only as secure as the user key encrypting them. The master user key | |
60 | should therefore be loaded in as secure a way as possible, preferably early in | |
61 | boot. | |
62 | ||
4e561d38 RS |
63 | The decrypted portion of encrypted keys can contain either a simple symmetric |
64 | key or a more complex structure. The format of the more complex structure is | |
65 | application specific, which is identified by 'format'. | |
66 | ||
d00a1c72 | 67 | Usage: |
4e561d38 RS |
68 | keyctl add encrypted name "new [format] key-type:master-key-name keylen" |
69 | ring | |
70 | keyctl add encrypted name "load hex_blob" ring | |
71 | keyctl update keyid "update key-type:master-key-name" | |
72 | ||
79a73d18 | 73 | format:= 'default | ecryptfs' |
4e561d38 | 74 | key-type:= 'trusted' | 'user' |
d00a1c72 | 75 | |
d00a1c72 MZ |
76 | |
77 | Examples of trusted and encrypted key usage: | |
78 | ||
79 | Create and save a trusted key named "kmk" of length 32 bytes: | |
80 | ||
81 | $ keyctl add trusted kmk "new 32" @u | |
82 | 440502848 | |
83 | ||
84 | $ keyctl show | |
85 | Session Keyring | |
86 | -3 --alswrv 500 500 keyring: _ses | |
87 | 97833714 --alswrv 500 -1 \_ keyring: _uid.500 | |
88 | 440502848 --alswrv 500 500 \_ trusted: kmk | |
89 | ||
90 | $ keyctl print 440502848 | |
91 | 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 | |
92 | 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b | |
93 | 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 | |
94 | a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec | |
95 | d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d | |
96 | dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 | |
97 | f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b | |
98 | e4a8aea2b607ec96931e6f4d4fe563ba | |
99 | ||
100 | $ keyctl pipe 440502848 > kmk.blob | |
101 | ||
102 | Load a trusted key from the saved blob: | |
103 | ||
104 | $ keyctl add trusted kmk "load `cat kmk.blob`" @u | |
105 | 268728824 | |
106 | ||
107 | $ keyctl print 268728824 | |
108 | 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 | |
109 | 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b | |
110 | 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 | |
111 | a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec | |
112 | d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d | |
113 | dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 | |
114 | f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b | |
115 | e4a8aea2b607ec96931e6f4d4fe563ba | |
116 | ||
117 | Reseal a trusted key under new pcr values: | |
118 | ||
119 | $ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`" | |
120 | $ keyctl print 268728824 | |
121 | 010100000000002c0002800093c35a09b70fff26e7a98ae786c641e678ec6ffb6b46d805 | |
122 | 77c8a6377aed9d3219c6dfec4b23ffe3000001005d37d472ac8a44023fbb3d18583a4f73 | |
123 | d3a076c0858f6f1dcaa39ea0f119911ff03f5406df4f7f27f41da8d7194f45c9f4e00f2e | |
124 | df449f266253aa3f52e55c53de147773e00f0f9aca86c64d94c95382265968c354c5eab4 | |
125 | 9638c5ae99c89de1e0997242edfb0b501744e11ff9762dfd951cffd93227cc513384e7e6 | |
126 | e782c29435c7ec2edafaa2f4c1fe6e7a781b59549ff5296371b42133777dcc5b8b971610 | |
127 | 94bc67ede19e43ddb9dc2baacad374a36feaf0314d700af0a65c164b7082401740e489c9 | |
128 | 7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef | |
129 | df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8 | |
130 | ||
4e561d38 RS |
131 | The initial consumer of trusted keys is EVM, which at boot time needs a high |
132 | quality symmetric key for HMAC protection of file metadata. The use of a | |
133 | trusted key provides strong guarantees that the EVM key has not been | |
134 | compromised by a user level problem, and when sealed to specific boot PCR | |
135 | values, protects against boot and offline attacks. Create and save an | |
136 | encrypted key "evm" using the above trusted key "kmk": | |
d00a1c72 | 137 | |
4e561d38 | 138 | option 1: omitting 'format' |
d00a1c72 MZ |
139 | $ keyctl add encrypted evm "new trusted:kmk 32" @u |
140 | 159771175 | |
141 | ||
4e561d38 RS |
142 | option 2: explicitly defining 'format' as 'default' |
143 | $ keyctl add encrypted evm "new default trusted:kmk 32" @u | |
144 | 159771175 | |
145 | ||
d00a1c72 | 146 | $ keyctl print 159771175 |
4e561d38 RS |
147 | default trusted:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b3 |
148 | 82dbbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0 | |
149 | 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc | |
d00a1c72 MZ |
150 | |
151 | $ keyctl pipe 159771175 > evm.blob | |
152 | ||
153 | Load an encrypted key "evm" from saved blob: | |
154 | ||
155 | $ keyctl add encrypted evm "load `cat evm.blob`" @u | |
156 | 831684262 | |
157 | ||
158 | $ keyctl print 831684262 | |
4e561d38 RS |
159 | default trusted:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b3 |
160 | 82dbbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0 | |
161 | 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc | |
d00a1c72 | 162 | |
4e561d38 | 163 | Other uses for trusted and encrypted keys, such as for disk and file encryption |
79a73d18 RS |
164 | are anticipated. In particular the new format 'ecryptfs' has been defined in |
165 | in order to use encrypted keys to mount an eCryptfs filesystem. More details | |
395cf969 PB |
166 | about the usage can be found in the file |
167 | 'Documentation/security/keys-ecryptfs.txt'. |