Commit | Line | Data |
---|---|---|
5395d312 KC |
1 | ========================== |
2 | Trusted and Encrypted Keys | |
3 | ========================== | |
d00a1c72 MZ |
4 | |
5 | Trusted and Encrypted Keys are two new key types added to the existing kernel | |
40e47125 | 6 | key ring service. Both of these new types are variable length symmetric keys, |
d00a1c72 MZ |
7 | and in both cases all keys are created in the kernel, and user space sees, |
8 | stores, and loads only encrypted blobs. Trusted Keys require the availability | |
c429805f SG |
9 | of a Trust Source for greater security, while Encrypted Keys can be used on any |
10 | system. All user level blobs, are displayed and loaded in hex ASCII for | |
11 | convenience, and are integrity verified. | |
d00a1c72 | 12 | |
d00a1c72 | 13 | |
c429805f SG |
14 | Trust Source |
15 | ============ | |
4264f27a | 16 | |
c429805f SG |
17 | A trust source provides the source of security for Trusted Keys. This |
18 | section lists currently supported trust sources, along with their security | |
19 | considerations. Whether or not a trust source is sufficiently safe depends | |
20 | on the strength and correctness of its implementation, as well as the threat | |
21 | environment for a specific use case. Since the kernel doesn't know what the | |
22 | environment is, and there is no metric of trust, it is dependent on the | |
23 | consumer of the Trusted Keys to determine if the trust source is sufficiently | |
24 | safe. | |
d00a1c72 | 25 | |
c429805f | 26 | * Root of trust for storage |
4264f27a | 27 | |
c429805f SG |
28 | (1) TPM (Trusted Platform Module: hardware device) |
29 | ||
30 | Rooted to Storage Root Key (SRK) which never leaves the TPM that | |
31 | provides crypto operation to establish root of trust for storage. | |
32 | ||
33 | (2) TEE (Trusted Execution Environment: OP-TEE based on Arm TrustZone) | |
34 | ||
35 | Rooted to Hardware Unique Key (HUK) which is generally burnt in on-chip | |
36 | fuses and is accessible to TEE only. | |
37 | ||
5002426e AF |
38 | (3) CAAM (Cryptographic Acceleration and Assurance Module: IP on NXP SoCs) |
39 | ||
40 | When High Assurance Boot (HAB) is enabled and the CAAM is in secure | |
41 | mode, trust is rooted to the OTPMK, a never-disclosed 256-bit key | |
42 | randomly generated and fused into each SoC at manufacturing time. | |
43 | Otherwise, a common fixed test key is used instead. | |
44 | ||
c429805f SG |
45 | * Execution isolation |
46 | ||
47 | (1) TPM | |
48 | ||
49 | Fixed set of operations running in isolated execution environment. | |
50 | ||
51 | (2) TEE | |
52 | ||
53 | Customizable set of operations running in isolated execution | |
54 | environment verified via Secure/Trusted boot process. | |
55 | ||
5002426e AF |
56 | (3) CAAM |
57 | ||
58 | Fixed set of operations running in isolated execution environment. | |
59 | ||
c429805f SG |
60 | * Optional binding to platform integrity state |
61 | ||
62 | (1) TPM | |
63 | ||
64 | Keys can be optionally sealed to specified PCR (integrity measurement) | |
65 | values, and only unsealed by the TPM, if PCRs and blob integrity | |
66 | verifications match. A loaded Trusted Key can be updated with new | |
67 | (future) PCR values, so keys are easily migrated to new PCR values, | |
68 | such as when the kernel and initramfs are updated. The same key can | |
69 | have many saved blobs under different PCR values, so multiple boots are | |
70 | easily supported. | |
71 | ||
72 | (2) TEE | |
73 | ||
74 | Relies on Secure/Trusted boot process for platform integrity. It can | |
75 | be extended with TEE based measured boot process. | |
76 | ||
5002426e AF |
77 | (3) CAAM |
78 | ||
79 | Relies on the High Assurance Boot (HAB) mechanism of NXP SoCs | |
80 | for platform integrity. | |
81 | ||
c429805f SG |
82 | * Interfaces and APIs |
83 | ||
84 | (1) TPM | |
85 | ||
86 | TPMs have well-documented, standardized interfaces and APIs. | |
87 | ||
88 | (2) TEE | |
89 | ||
90 | TEEs have well-documented, standardized client interface and APIs. For | |
91 | more details refer to ``Documentation/staging/tee.rst``. | |
92 | ||
5002426e AF |
93 | (3) CAAM |
94 | ||
95 | Interface is specific to silicon vendor. | |
c429805f SG |
96 | |
97 | * Threat model | |
98 | ||
5002426e | 99 | The strength and appropriateness of a particular trust source for a given |
c429805f SG |
100 | purpose must be assessed when using them to protect security-relevant data. |
101 | ||
102 | ||
103 | Key Generation | |
104 | ============== | |
105 | ||
106 | Trusted Keys | |
107 | ------------ | |
108 | ||
fcd7c269 AF |
109 | New keys are created from random numbers. They are encrypted/decrypted using |
110 | a child key in the storage key hierarchy. Encryption and decryption of the | |
111 | child key must be protected by a strong access control policy within the | |
112 | trust source. The random number generator in use differs according to the | |
113 | selected trust source: | |
c429805f | 114 | |
fcd7c269 | 115 | * TPM: hardware device based RNG |
c429805f | 116 | |
fcd7c269 AF |
117 | Keys are generated within the TPM. Strength of random numbers may vary |
118 | from one device manufacturer to another. | |
c429805f | 119 | |
fcd7c269 | 120 | * TEE: OP-TEE based on Arm TrustZone based RNG |
c429805f SG |
121 | |
122 | RNG is customizable as per platform needs. It can either be direct output | |
123 | from platform specific hardware RNG or a software based Fortuna CSPRNG | |
124 | which can be seeded via multiple entropy sources. | |
125 | ||
5002426e AF |
126 | * CAAM: Kernel RNG |
127 | ||
128 | The normal kernel random number generator is used. To seed it from the | |
129 | CAAM HWRNG, enable CRYPTO_DEV_FSL_CAAM_RNG_API and ensure the device | |
130 | is probed. | |
131 | ||
fcd7c269 AF |
132 | Users may override this by specifying ``trusted.rng=kernel`` on the kernel |
133 | command-line to override the used RNG with the kernel's random number pool. | |
134 | ||
c429805f SG |
135 | Encrypted Keys |
136 | -------------- | |
137 | ||
138 | Encrypted keys do not depend on a trust source, and are faster, as they use AES | |
cd3bc044 YT |
139 | for encryption/decryption. New keys are created either from kernel-generated |
140 | random numbers or user-provided decrypted data, and are encrypted/decrypted | |
141 | using a specified ‘master’ key. The ‘master’ key can either be a trusted-key or | |
142 | user-key type. The main disadvantage of encrypted keys is that if they are not | |
143 | rooted in a trusted key, they are only as secure as the user key encrypting | |
144 | them. The master user key should therefore be loaded in as secure a way as | |
145 | possible, preferably early in boot. | |
c429805f SG |
146 | |
147 | ||
148 | Usage | |
149 | ===== | |
150 | ||
151 | Trusted Keys usage: TPM | |
152 | ----------------------- | |
153 | ||
154 | TPM 1.2: By default, trusted keys are sealed under the SRK, which has the | |
155 | default authorization value (20 bytes of 0s). This can be set at takeownership | |
156 | time with the TrouSerS utility: "tpm_takeownership -u -z". | |
157 | ||
158 | TPM 2.0: The user must first create a storage key and make it persistent, so the | |
159 | key is available after reboot. This can be done using the following commands. | |
4264f27a SB |
160 | |
161 | With the IBM TSS 2 stack:: | |
162 | ||
163 | #> tsscreateprimary -hi o -st | |
164 | Handle 80000000 | |
165 | #> tssevictcontrol -hi o -ho 80000000 -hp 81000001 | |
166 | ||
167 | Or with the Intel TSS 2 stack:: | |
168 | ||
bb84bc51 | 169 | #> tpm2_createprimary --hierarchy o -G rsa2048 -c key.ctxt |
4264f27a | 170 | [...] |
bb84bc51 | 171 | #> tpm2_evictcontrol -c key.ctxt 0x81000001 |
4264f27a SB |
172 | persistentHandle: 0x81000001 |
173 | ||
5395d312 KC |
174 | Usage:: |
175 | ||
d00a1c72 MZ |
176 | keyctl add trusted name "new keylen [options]" ring |
177 | keyctl add trusted name "load hex_blob [pcrlock=pcrnum]" ring | |
178 | keyctl update key "update [options]" | |
179 | keyctl print keyid | |
180 | ||
181 | options: | |
4264f27a SB |
182 | keyhandle= ascii hex value of sealing key |
183 | TPM 1.2: default 0x40000000 (SRK) | |
184 | TPM 2.0: no default; must be passed every time | |
5beb0c43 JS |
185 | keyauth= ascii hex auth for sealing key default 0x00...i |
186 | (40 ascii zeros) | |
187 | blobauth= ascii hex auth for sealed data default 0x00... | |
188 | (40 ascii zeros) | |
5beb0c43 JS |
189 | pcrinfo= ascii hex of PCR_INFO or PCR_INFO_LONG (no default) |
190 | pcrlock= pcr number to be extended to "lock" blob | |
191 | migratable= 0|1 indicating permission to reseal to new PCR values, | |
192 | default 1 (resealing allowed) | |
193 | hash= hash algorithm name as a string. For TPM 1.x the only | |
194 | allowed value is sha1. For TPM 2.x the allowed values | |
195 | are sha1, sha256, sha384, sha512 and sm3-256. | |
196 | policydigest= digest for the authorization policy. must be calculated | |
197 | with the same hash algorithm as specified by the 'hash=' | |
198 | option. | |
199 | policyhandle= handle to an authorization policy session that defines the | |
200 | same policy and with the same hash algorithm as was used to | |
201 | seal the key. | |
d00a1c72 MZ |
202 | |
203 | "keyctl print" returns an ascii hex copy of the sealed key, which is in standard | |
204 | TPM_STORED_DATA format. The key length for new keys are always in bytes. | |
205 | Trusted Keys can be 32 - 128 bytes (256 - 1024 bits), the upper limit is to fit | |
206 | within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding. | |
207 | ||
c429805f SG |
208 | Trusted Keys usage: TEE |
209 | ----------------------- | |
210 | ||
211 | Usage:: | |
212 | ||
213 | keyctl add trusted name "new keylen" ring | |
214 | keyctl add trusted name "load hex_blob" ring | |
215 | keyctl print keyid | |
216 | ||
217 | "keyctl print" returns an ASCII hex copy of the sealed key, which is in format | |
218 | specific to TEE device implementation. The key length for new keys is always | |
219 | in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). | |
220 | ||
5002426e AF |
221 | Trusted Keys usage: CAAM |
222 | ------------------------ | |
223 | ||
224 | Usage:: | |
225 | ||
226 | keyctl add trusted name "new keylen" ring | |
227 | keyctl add trusted name "load hex_blob" ring | |
228 | keyctl print keyid | |
229 | ||
230 | "keyctl print" returns an ASCII hex copy of the sealed key, which is in a | |
231 | CAAM-specific format. The key length for new keys is always in bytes. | |
232 | Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). | |
233 | ||
c429805f SG |
234 | Encrypted Keys usage |
235 | -------------------- | |
d00a1c72 | 236 | |
4e561d38 RS |
237 | The decrypted portion of encrypted keys can contain either a simple symmetric |
238 | key or a more complex structure. The format of the more complex structure is | |
239 | application specific, which is identified by 'format'. | |
240 | ||
5395d312 KC |
241 | Usage:: |
242 | ||
4e561d38 RS |
243 | keyctl add encrypted name "new [format] key-type:master-key-name keylen" |
244 | ring | |
cd3bc044 YT |
245 | keyctl add encrypted name "new [format] key-type:master-key-name keylen |
246 | decrypted-data" ring | |
4e561d38 RS |
247 | keyctl add encrypted name "load hex_blob" ring |
248 | keyctl update keyid "update key-type:master-key-name" | |
249 | ||
5395d312 KC |
250 | Where:: |
251 | ||
9db67581 | 252 | format:= 'default | ecryptfs | enc32' |
5395d312 | 253 | key-type:= 'trusted' | 'user' |
d00a1c72 | 254 | |
c429805f SG |
255 | Examples of trusted and encrypted key usage |
256 | ------------------------------------------- | |
d00a1c72 | 257 | |
6ad8b216 | 258 | Create and save a trusted key named "kmk" of length 32 bytes. |
d00a1c72 | 259 | |
4264f27a SB |
260 | Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, |
261 | append 'keyhandle=0x81000001' to statements between quotes, such as | |
262 | "new 32 keyhandle=0x81000001". | |
263 | ||
6ad8b216 MCC |
264 | :: |
265 | ||
d00a1c72 MZ |
266 | $ keyctl add trusted kmk "new 32" @u |
267 | 440502848 | |
268 | ||
269 | $ keyctl show | |
270 | Session Keyring | |
271 | -3 --alswrv 500 500 keyring: _ses | |
272 | 97833714 --alswrv 500 -1 \_ keyring: _uid.500 | |
273 | 440502848 --alswrv 500 500 \_ trusted: kmk | |
274 | ||
275 | $ keyctl print 440502848 | |
276 | 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 | |
277 | 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b | |
278 | 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 | |
279 | a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec | |
280 | d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d | |
281 | dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 | |
282 | f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b | |
283 | e4a8aea2b607ec96931e6f4d4fe563ba | |
284 | ||
285 | $ keyctl pipe 440502848 > kmk.blob | |
286 | ||
5395d312 | 287 | Load a trusted key from the saved blob:: |
d00a1c72 MZ |
288 | |
289 | $ keyctl add trusted kmk "load `cat kmk.blob`" @u | |
290 | 268728824 | |
291 | ||
292 | $ keyctl print 268728824 | |
293 | 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 | |
294 | 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b | |
295 | 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 | |
296 | a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec | |
297 | d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d | |
298 | dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 | |
299 | f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b | |
300 | e4a8aea2b607ec96931e6f4d4fe563ba | |
301 | ||
c429805f | 302 | Reseal (TPM specific) a trusted key under new PCR values:: |
d00a1c72 MZ |
303 | |
304 | $ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`" | |
305 | $ keyctl print 268728824 | |
306 | 010100000000002c0002800093c35a09b70fff26e7a98ae786c641e678ec6ffb6b46d805 | |
307 | 77c8a6377aed9d3219c6dfec4b23ffe3000001005d37d472ac8a44023fbb3d18583a4f73 | |
308 | d3a076c0858f6f1dcaa39ea0f119911ff03f5406df4f7f27f41da8d7194f45c9f4e00f2e | |
309 | df449f266253aa3f52e55c53de147773e00f0f9aca86c64d94c95382265968c354c5eab4 | |
310 | 9638c5ae99c89de1e0997242edfb0b501744e11ff9762dfd951cffd93227cc513384e7e6 | |
311 | e782c29435c7ec2edafaa2f4c1fe6e7a781b59549ff5296371b42133777dcc5b8b971610 | |
312 | 94bc67ede19e43ddb9dc2baacad374a36feaf0314d700af0a65c164b7082401740e489c9 | |
313 | 7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef | |
314 | df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8 | |
315 | ||
c429805f | 316 | |
4e561d38 | 317 | The initial consumer of trusted keys is EVM, which at boot time needs a high |
c429805f | 318 | quality symmetric key for HMAC protection of file metadata. The use of a |
4e561d38 | 319 | trusted key provides strong guarantees that the EVM key has not been |
c429805f SG |
320 | compromised by a user level problem, and when sealed to a platform integrity |
321 | state, protects against boot and offline attacks. Create and save an | |
4e561d38 | 322 | encrypted key "evm" using the above trusted key "kmk": |
d00a1c72 | 323 | |
5395d312 KC |
324 | option 1: omitting 'format':: |
325 | ||
d00a1c72 MZ |
326 | $ keyctl add encrypted evm "new trusted:kmk 32" @u |
327 | 159771175 | |
328 | ||
5395d312 KC |
329 | option 2: explicitly defining 'format' as 'default':: |
330 | ||
4e561d38 RS |
331 | $ keyctl add encrypted evm "new default trusted:kmk 32" @u |
332 | 159771175 | |
333 | ||
d00a1c72 | 334 | $ keyctl print 159771175 |
4e561d38 RS |
335 | default trusted:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b3 |
336 | 82dbbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0 | |
337 | 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc | |
d00a1c72 MZ |
338 | |
339 | $ keyctl pipe 159771175 > evm.blob | |
340 | ||
5395d312 | 341 | Load an encrypted key "evm" from saved blob:: |
d00a1c72 MZ |
342 | |
343 | $ keyctl add encrypted evm "load `cat evm.blob`" @u | |
344 | 831684262 | |
345 | ||
346 | $ keyctl print 831684262 | |
4e561d38 RS |
347 | default trusted:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b3 |
348 | 82dbbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0 | |
349 | 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc | |
d00a1c72 | 350 | |
cd3bc044 YT |
351 | Instantiate an encrypted key "evm" using user-provided decrypted data:: |
352 | ||
5adedd42 NV |
353 | $ evmkey=$(dd if=/dev/urandom bs=1 count=32 | xxd -c32 -p) |
354 | $ keyctl add encrypted evm "new default user:kmk 32 $evmkey" @u | |
cd3bc044 YT |
355 | 794890253 |
356 | ||
357 | $ keyctl print 794890253 | |
358 | default user:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b382d | |
359 | bbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0247 | |
360 | 17c64 5972dcb82ab2dde83376d82b2e3c09ffc | |
361 | ||
4e561d38 | 362 | Other uses for trusted and encrypted keys, such as for disk and file encryption |
b216685b | 363 | are anticipated. In particular the new format 'ecryptfs' has been defined |
79a73d18 | 364 | in order to use encrypted keys to mount an eCryptfs filesystem. More details |
395cf969 | 365 | about the usage can be found in the file |
adf31eeb | 366 | ``Documentation/security/keys/ecryptfs.rst``. |
9db67581 DJ |
367 | |
368 | Another new format 'enc32' has been defined in order to support encrypted keys | |
369 | with payload size of 32 bytes. This will initially be used for nvdimm security | |
370 | but may expand to other usages that require 32 bytes payload. | |
f2219745 JB |
371 | |
372 | ||
373 | TPM 2.0 ASN.1 Key Format | |
374 | ------------------------ | |
375 | ||
376 | The TPM 2.0 ASN.1 key format is designed to be easily recognisable, | |
377 | even in binary form (fixing a problem we had with the TPM 1.2 ASN.1 | |
378 | format) and to be extensible for additions like importable keys and | |
379 | policy:: | |
380 | ||
381 | TPMKey ::= SEQUENCE { | |
382 | type OBJECT IDENTIFIER | |
383 | emptyAuth [0] EXPLICIT BOOLEAN OPTIONAL | |
384 | parent INTEGER | |
385 | pubkey OCTET STRING | |
386 | privkey OCTET STRING | |
387 | } | |
388 | ||
389 | type is what distinguishes the key even in binary form since the OID | |
390 | is provided by the TCG to be unique and thus forms a recognizable | |
391 | binary pattern at offset 3 in the key. The OIDs currently made | |
392 | available are:: | |
393 | ||
394 | 2.23.133.10.1.3 TPM Loadable key. This is an asymmetric key (Usually | |
395 | RSA2048 or Elliptic Curve) which can be imported by a | |
396 | TPM2_Load() operation. | |
397 | ||
398 | 2.23.133.10.1.4 TPM Importable Key. This is an asymmetric key (Usually | |
399 | RSA2048 or Elliptic Curve) which can be imported by a | |
400 | TPM2_Import() operation. | |
401 | ||
402 | 2.23.133.10.1.5 TPM Sealed Data. This is a set of data (up to 128 | |
403 | bytes) which is sealed by the TPM. It usually | |
404 | represents a symmetric key and must be unsealed before | |
405 | use. | |
406 | ||
407 | The trusted key code only uses the TPM Sealed Data OID. | |
408 | ||
409 | emptyAuth is true if the key has well known authorization "". If it | |
410 | is false or not present, the key requires an explicit authorization | |
411 | phrase. This is used by most user space consumers to decide whether | |
412 | to prompt for a password. | |
413 | ||
414 | parent represents the parent key handle, either in the 0x81 MSO space, | |
415 | like 0x81000001 for the RSA primary storage key. Userspace programmes | |
416 | also support specifying the primary handle in the 0x40 MSO space. If | |
417 | this happens the Elliptic Curve variant of the primary key using the | |
418 | TCG defined template will be generated on the fly into a volatile | |
419 | object and used as the parent. The current kernel code only supports | |
420 | the 0x81 MSO form. | |
421 | ||
422 | pubkey is the binary representation of TPM2B_PRIVATE excluding the | |
423 | initial TPM2B header, which can be reconstructed from the ASN.1 octet | |
424 | string length. | |
425 | ||
426 | privkey is the binary representation of TPM2B_PUBLIC excluding the | |
427 | initial TPM2B header which can be reconstructed from the ASN.1 octed | |
428 | string length. |