sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget3/translations/zh_CN/security/keys/trusted-encryptedmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/zh_TW/security/keys/trusted-encryptedmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/it_IT/security/keys/trusted-encryptedmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/ja_JP/security/keys/trusted-encryptedmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/ko_KR/security/keys/trusted-encryptedmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget3/translations/sp_SP/security/keys/trusted-encryptedmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hTrusted and Encrypted Keysh]hTrusted and Encrypted Keys}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhM/var/lib/git/docbuild/linux/Documentation/security/keys/trusted-encrypted.rsthKubh paragraph)}(hXTrusted and Encrypted Keys are two new key types added to the existing kernel key ring service. Both of these new types are variable length symmetric keys, and in both cases all keys are created in the kernel, and user space sees, stores, and loads only encrypted blobs. Trusted Keys require the availability of a Trust Source for greater security, while Encrypted Keys can be used on any system. All user level blobs, are displayed and loaded in hex ASCII for convenience, and are integrity verified.h]hXTrusted and Encrypted Keys are two new key types added to the existing kernel key ring service. Both of these new types are variable length symmetric keys, and in both cases all keys are created in the kernel, and user space sees, stores, and loads only encrypted blobs. Trusted Keys require the availability of a Trust Source for greater security, while Encrypted Keys can be used on any system. All user level blobs, are displayed and loaded in hex ASCII for convenience, and are integrity verified.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h Trust Sourceh]h Trust Source}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hXA trust source provides the source of security for Trusted Keys. This section lists currently supported trust sources, along with their security considerations. Whether or not a trust source is sufficiently safe depends on the strength and correctness of its implementation, as well as the threat environment for a specific use case. Since the kernel doesn't know what the environment is, and there is no metric of trust, it is dependent on the consumer of the Trusted Keys to determine if the trust source is sufficiently safe.h]hXA trust source provides the source of security for Trusted Keys. This section lists currently supported trust sources, along with their security considerations. Whether or not a trust source is sufficiently safe depends on the strength and correctness of its implementation, as well as the threat environment for a specific use case. Since the kernel doesn’t know what the environment is, and there is no metric of trust, it is dependent on the consumer of the Trusted Keys to determine if the trust source is sufficiently safe.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh block_quote)}(hX% * Root of trust for storage (1) TPM (Trusted Platform Module: hardware device) Rooted to Storage Root Key (SRK) which never leaves the TPM that provides crypto operation to establish root of trust for storage. (2) TEE (Trusted Execution Environment: OP-TEE based on Arm TrustZone) Rooted to Hardware Unique Key (HUK) which is generally burnt in on-chip fuses and is accessible to TEE only. (3) CAAM (Cryptographic Acceleration and Assurance Module: IP on NXP SoCs) When High Assurance Boot (HAB) is enabled and the CAAM is in secure mode, trust is rooted to the OTPMK, a never-disclosed 256-bit key randomly generated and fused into each SoC at manufacturing time. Otherwise, a common fixed test key is used instead. (4) DCP (Data Co-Processor: crypto accelerator of various i.MX SoCs) Rooted to a one-time programmable key (OTP) that is generally burnt in the on-chip fuses and is accessible to the DCP encryption engine only. DCP provides two keys that can be used as root of trust: the OTP key and the UNIQUE key. Default is to use the UNIQUE key, but selecting the OTP key can be done via a module parameter (dcp_use_otp_key). * Execution isolation (1) TPM Fixed set of operations running in isolated execution environment. (2) TEE Customizable set of operations running in isolated execution environment verified via Secure/Trusted boot process. (3) CAAM Fixed set of operations running in isolated execution environment. (4) DCP Fixed set of cryptographic operations running in isolated execution environment. Only basic blob key encryption is executed there. The actual key sealing/unsealing is done on main processor/kernel space. * Optional binding to platform integrity state (1) TPM Keys can be optionally sealed to specified PCR (integrity measurement) values, and only unsealed by the TPM, if PCRs and blob integrity verifications match. A loaded Trusted Key can be updated with new (future) PCR values, so keys are easily migrated to new PCR values, such as when the kernel and initramfs are updated. The same key can have many saved blobs under different PCR values, so multiple boots are easily supported. (2) TEE Relies on Secure/Trusted boot process for platform integrity. It can be extended with TEE based measured boot process. (3) CAAM Relies on the High Assurance Boot (HAB) mechanism of NXP SoCs for platform integrity. (4) DCP Relies on Secure/Trusted boot process (called HAB by vendor) for platform integrity. * Interfaces and APIs (1) TPM TPMs have well-documented, standardized interfaces and APIs. (2) TEE TEEs have well-documented, standardized client interface and APIs. For more details refer to ``Documentation/driver-api/tee.rst``. (3) CAAM Interface is specific to silicon vendor. (4) DCP Vendor-specific API that is implemented as part of the DCP crypto driver in ``drivers/crypto/mxs-dcp.c``. * Threat model The strength and appropriateness of a particular trust source for a given purpose must be assessed when using them to protect security-relevant data. h]h bullet_list)}(hhh](h list_item)}(hXRoot of trust for storage (1) TPM (Trusted Platform Module: hardware device) Rooted to Storage Root Key (SRK) which never leaves the TPM that provides crypto operation to establish root of trust for storage. (2) TEE (Trusted Execution Environment: OP-TEE based on Arm TrustZone) Rooted to Hardware Unique Key (HUK) which is generally burnt in on-chip fuses and is accessible to TEE only. (3) CAAM (Cryptographic Acceleration and Assurance Module: IP on NXP SoCs) When High Assurance Boot (HAB) is enabled and the CAAM is in secure mode, trust is rooted to the OTPMK, a never-disclosed 256-bit key randomly generated and fused into each SoC at manufacturing time. Otherwise, a common fixed test key is used instead. (4) DCP (Data Co-Processor: crypto accelerator of various i.MX SoCs) Rooted to a one-time programmable key (OTP) that is generally burnt in the on-chip fuses and is accessible to the DCP encryption engine only. DCP provides two keys that can be used as root of trust: the OTP key and the UNIQUE key. Default is to use the UNIQUE key, but selecting the OTP key can be done via a module parameter (dcp_use_otp_key). h](h)}(hRoot of trust for storageh]hRoot of trust for storage}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhubhenumerated_list)}(hhh](h)}(hTPM (Trusted Platform Module: hardware device) Rooted to Storage Root Key (SRK) which never leaves the TPM that provides crypto operation to establish root of trust for storage. h](h)}(h.TPM (Trusted Platform Module: hardware device)h]h.TPM (Trusted Platform Module: hardware device)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubh)}(hRooted to Storage Root Key (SRK) which never leaves the TPM that provides crypto operation to establish root of trust for storage.h]hRooted to Storage Root Key (SRK) which never leaves the TPM that provides crypto operation to establish root of trust for storage.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubeh}(h]h ]h"]h$]h&]uh1hhjubh)}(hTEE (Trusted Execution Environment: OP-TEE based on Arm TrustZone) Rooted to Hardware Unique Key (HUK) which is generally burnt in on-chip fuses and is accessible to TEE only. h](h)}(hBTEE (Trusted Execution Environment: OP-TEE based on Arm TrustZone)h]hBTEE (Trusted Execution Environment: OP-TEE based on Arm TrustZone)}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK!hj0ubh)}(hlRooted to Hardware Unique Key (HUK) which is generally burnt in on-chip fuses and is accessible to TEE only.h]hlRooted to Hardware Unique Key (HUK) which is generally burnt in on-chip fuses and is accessible to TEE only.}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK#hj0ubeh}(h]h ]h"]h$]h&]uh1hhjubh)}(hXDCAAM (Cryptographic Acceleration and Assurance Module: IP on NXP SoCs) When High Assurance Boot (HAB) is enabled and the CAAM is in secure mode, trust is rooted to the OTPMK, a never-disclosed 256-bit key randomly generated and fused into each SoC at manufacturing time. Otherwise, a common fixed test key is used instead. h](h)}(hFCAAM (Cryptographic Acceleration and Assurance Module: IP on NXP SoCs)h]hFCAAM (Cryptographic Acceleration and Assurance Module: IP on NXP SoCs)}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK&hjVubh)}(hWhen High Assurance Boot (HAB) is enabled and the CAAM is in secure mode, trust is rooted to the OTPMK, a never-disclosed 256-bit key randomly generated and fused into each SoC at manufacturing time. Otherwise, a common fixed test key is used instead.h]hWhen High Assurance Boot (HAB) is enabled and the CAAM is in secure mode, trust is rooted to the OTPMK, a never-disclosed 256-bit key randomly generated and fused into each SoC at manufacturing time. Otherwise, a common fixed test key is used instead.}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hjVubeh}(h]h ]h"]h$]h&]uh1hhjubh)}(hXDCP (Data Co-Processor: crypto accelerator of various i.MX SoCs) Rooted to a one-time programmable key (OTP) that is generally burnt in the on-chip fuses and is accessible to the DCP encryption engine only. DCP provides two keys that can be used as root of trust: the OTP key and the UNIQUE key. Default is to use the UNIQUE key, but selecting the OTP key can be done via a module parameter (dcp_use_otp_key). h](h)}(h@DCP (Data Co-Processor: crypto accelerator of various i.MX SoCs)h]h@DCP (Data Co-Processor: crypto accelerator of various i.MX SoCs)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK-hj|ubh)}(hXXRooted to a one-time programmable key (OTP) that is generally burnt in the on-chip fuses and is accessible to the DCP encryption engine only. DCP provides two keys that can be used as root of trust: the OTP key and the UNIQUE key. Default is to use the UNIQUE key, but selecting the OTP key can be done via a module parameter (dcp_use_otp_key).h]hXXRooted to a one-time programmable key (OTP) that is generally burnt in the on-chip fuses and is accessible to the DCP encryption engine only. DCP provides two keys that can be used as root of trust: the OTP key and the UNIQUE key. Default is to use the UNIQUE key, but selecting the OTP key can be done via a module parameter (dcp_use_otp_key).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK/hj|ubeh}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]enumtypearabicprefix(suffix)uh1jhhubeh}(h]h ]h"]h$]h&]uh1hhhubh)}(hXExecution isolation (1) TPM Fixed set of operations running in isolated execution environment. (2) TEE Customizable set of operations running in isolated execution environment verified via Secure/Trusted boot process. (3) CAAM Fixed set of operations running in isolated execution environment. (4) DCP Fixed set of cryptographic operations running in isolated execution environment. Only basic blob key encryption is executed there. The actual key sealing/unsealing is done on main processor/kernel space. h](h)}(hExecution isolationh]hExecution isolation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK5hjubj)}(hhh](h)}(hHTPM Fixed set of operations running in isolated execution environment. h](h)}(hTPMh]hTPM}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK7hjubh)}(hBFixed set of operations running in isolated execution environment.h]hBFixed set of operations running in isolated execution environment.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK9hjubeh}(h]h ]h"]h$]h&]uh1hhjubh)}(hxTEE Customizable set of operations running in isolated execution environment verified via Secure/Trusted boot process. h](h)}(hTEEh]hTEE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK;hjubh)}(hrCustomizable set of operations running in isolated execution environment verified via Secure/Trusted boot process.h]hrCustomizable set of operations running in isolated execution environment verified via Secure/Trusted boot process.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK=hjubeh}(h]h ]h"]h$]h&]uh1hhjubh)}(hICAAM Fixed set of operations running in isolated execution environment. h](h)}(hCAAMh]hCAAM}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hjubh)}(hBFixed set of operations running in isolated execution environment.h]hBFixed set of operations running in isolated execution environment.}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKBhjubeh}(h]h ]h"]h$]h&]uh1hhjubh)}(hDCP Fixed set of cryptographic operations running in isolated execution environment. Only basic blob key encryption is executed there. The actual key sealing/unsealing is done on main processor/kernel space. h](h)}(hDCPh]hDCP}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKDhj;ubh)}(hFixed set of cryptographic operations running in isolated execution environment. Only basic blob key encryption is executed there. The actual key sealing/unsealing is done on main processor/kernel space.h]hFixed set of cryptographic operations running in isolated execution environment. Only basic blob key encryption is executed there. The actual key sealing/unsealing is done on main processor/kernel space.}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKFhj;ubeh}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]jjjjjjuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhubh)}(hXiOptional binding to platform integrity state (1) TPM Keys can be optionally sealed to specified PCR (integrity measurement) values, and only unsealed by the TPM, if PCRs and blob integrity verifications match. A loaded Trusted Key can be updated with new (future) PCR values, so keys are easily migrated to new PCR values, such as when the kernel and initramfs are updated. The same key can have many saved blobs under different PCR values, so multiple boots are easily supported. (2) TEE Relies on Secure/Trusted boot process for platform integrity. It can be extended with TEE based measured boot process. (3) CAAM Relies on the High Assurance Boot (HAB) mechanism of NXP SoCs for platform integrity. (4) DCP Relies on Secure/Trusted boot process (called HAB by vendor) for platform integrity. h](h)}(h,Optional binding to platform integrity stateh]h,Optional binding to platform integrity state}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKJhjmubh)}(hX*(1) TPM Keys can be optionally sealed to specified PCR (integrity measurement) values, and only unsealed by the TPM, if PCRs and blob integrity verifications match. A loaded Trusted Key can be updated with new (future) PCR values, so keys are easily migrated to new PCR values, such as when the kernel and initramfs are updated. The same key can have many saved blobs under different PCR values, so multiple boots are easily supported. (2) TEE Relies on Secure/Trusted boot process for platform integrity. It can be extended with TEE based measured boot process. (3) CAAM Relies on the High Assurance Boot (HAB) mechanism of NXP SoCs for platform integrity. (4) DCP Relies on Secure/Trusted boot process (called HAB by vendor) for platform integrity. h]j)}(hhh](h)}(hXTPM Keys can be optionally sealed to specified PCR (integrity measurement) values, and only unsealed by the TPM, if PCRs and blob integrity verifications match. A loaded Trusted Key can be updated with new (future) PCR values, so keys are easily migrated to new PCR values, such as when the kernel and initramfs are updated. The same key can have many saved blobs under different PCR values, so multiple boots are easily supported. h](h)}(hTPMh]hTPM}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKLhjubh)}(hXKeys can be optionally sealed to specified PCR (integrity measurement) values, and only unsealed by the TPM, if PCRs and blob integrity verifications match. A loaded Trusted Key can be updated with new (future) PCR values, so keys are easily migrated to new PCR values, such as when the kernel and initramfs are updated. The same key can have many saved blobs under different PCR values, so multiple boots are easily supported.h]hXKeys can be optionally sealed to specified PCR (integrity measurement) values, and only unsealed by the TPM, if PCRs and blob integrity verifications match. A loaded Trusted Key can be updated with new (future) PCR values, so keys are easily migrated to new PCR values, such as when the kernel and initramfs are updated. The same key can have many saved blobs under different PCR values, so multiple boots are easily supported.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKNhjubeh}(h]h ]h"]h$]h&]uh1hhjubh)}(h|TEE Relies on Secure/Trusted boot process for platform integrity. It can be extended with TEE based measured boot process. h](h)}(hTEEh]hTEE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKVhjubh)}(hvRelies on Secure/Trusted boot process for platform integrity. It can be extended with TEE based measured boot process.h]hvRelies on Secure/Trusted boot process for platform integrity. It can be extended with TEE based measured boot process.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKXhjubeh}(h]h ]h"]h$]h&]uh1hhjubh)}(h\CAAM Relies on the High Assurance Boot (HAB) mechanism of NXP SoCs for platform integrity. h](h)}(hCAAMh]hCAAM}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK[hjubh)}(hURelies on the High Assurance Boot (HAB) mechanism of NXP SoCs for platform integrity.h]hURelies on the High Assurance Boot (HAB) mechanism of NXP SoCs for platform integrity.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK]hjubeh}(h]h ]h"]h$]h&]uh1hhjubh)}(hZDCP Relies on Secure/Trusted boot process (called HAB by vendor) for platform integrity. h](h)}(hDCPh]hDCP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK`hjubh)}(hTRelies on Secure/Trusted boot process (called HAB by vendor) for platform integrity.h]hTRelies on Secure/Trusted boot process (called HAB by vendor) for platform integrity.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKbhjubeh}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]jjjjjjuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKLhjmubeh}(h]h ]h"]h$]h&]uh1hhhubh)}(hXInterfaces and APIs (1) TPM TPMs have well-documented, standardized interfaces and APIs. (2) TEE TEEs have well-documented, standardized client interface and APIs. For more details refer to ``Documentation/driver-api/tee.rst``. (3) CAAM Interface is specific to silicon vendor. (4) DCP Vendor-specific API that is implemented as part of the DCP crypto driver in ``drivers/crypto/mxs-dcp.c``. h](h)}(hInterfaces and APIsh]hInterfaces and APIs}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKehj0ubj)}(hhh](h)}(hBTPM TPMs have well-documented, standardized interfaces and APIs. h](h)}(hTPMh]hTPM}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKghjEubh)}(h tsscreateprimary -hi o -st Handle 80000000 #> tssevictcontrol -hi o -ho 80000000 -hp 81000001h]h`#> tsscreateprimary -hi o -st Handle 80000000 #> tssevictcontrol -hi o -ho 80000000 -hp 81000001}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jhhhKhjhhubh)}(hOr with the Intel TSS 2 stack::h]hOr with the Intel TSS 2 stack:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h#> tpm2_createprimary --hierarchy o -G rsa2048 -c key.ctxt [...] #> tpm2_evictcontrol -c key.ctxt 0x81000001 persistentHandle: 0x81000001h]h#> tpm2_createprimary --hierarchy o -G rsa2048 -c key.ctxt [...] #> tpm2_evictcontrol -c key.ctxt 0x81000001 persistentHandle: 0x81000001}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hUsage::h]hUsage:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hXFkeyctl add trusted name "new keylen [options]" ring keyctl add trusted name "load hex_blob [pcrlock=pcrnum]" ring keyctl update key "update [options]" keyctl print keyid options: keyhandle= ascii hex value of sealing key TPM 1.2: default 0x40000000 (SRK) TPM 2.0: no default; must be passed every time keyauth= ascii hex auth for sealing key default 0x00...i (40 ascii zeros) blobauth= ascii hex auth for sealed data default 0x00... (40 ascii zeros) pcrinfo= ascii hex of PCR_INFO or PCR_INFO_LONG (no default) pcrlock= pcr number to be extended to "lock" blob migratable= 0|1 indicating permission to reseal to new PCR values, default 1 (resealing allowed) hash= hash algorithm name as a string. For TPM 1.x the only allowed value is sha1. For TPM 2.x the allowed values are sha1, sha256, sha384, sha512 and sm3-256. policydigest= digest for the authorization policy. must be calculated with the same hash algorithm as specified by the 'hash=' option. policyhandle= handle to an authorization policy session that defines the same policy and with the same hash algorithm as was used to seal the key.h]hXFkeyctl add trusted name "new keylen [options]" ring keyctl add trusted name "load hex_blob [pcrlock=pcrnum]" ring keyctl update key "update [options]" keyctl print keyid options: keyhandle= ascii hex value of sealing key TPM 1.2: default 0x40000000 (SRK) TPM 2.0: no default; must be passed every time keyauth= ascii hex auth for sealing key default 0x00...i (40 ascii zeros) blobauth= ascii hex auth for sealed data default 0x00... (40 ascii zeros) pcrinfo= ascii hex of PCR_INFO or PCR_INFO_LONG (no default) pcrlock= pcr number to be extended to "lock" blob migratable= 0|1 indicating permission to reseal to new PCR values, default 1 (resealing allowed) hash= hash algorithm name as a string. For TPM 1.x the only allowed value is sha1. For TPM 2.x the allowed values are sha1, sha256, sha384, sha512 and sm3-256. policydigest= digest for the authorization policy. must be calculated with the same hash algorithm as specified by the 'hash=' option. policyhandle= handle to an authorization policy session that defines the same policy and with the same hash algorithm as was used to seal the key.}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hX9"keyctl print" returns an ascii hex copy of the sealed key, which is in standard TPM_STORED_DATA format. The key length for new keys are always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits), the upper limit is to fit within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding.h]hX=“keyctl print” returns an ascii hex copy of the sealed key, which is in standard TPM_STORED_DATA format. The key length for new keys are always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits), the upper limit is to fit within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]trusted-keys-usage-tpmah ]h"]trusted keys usage: tpmah$]h&]uh1hhj}hhhhhKubh)}(hhh](h)}(hTrusted Keys usage: TEEh]hTrusted Keys usage: TEE}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj)hhhhhKubh)}(hUsage::h]hUsage:}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj)hhubj)}(hikeyctl add trusted name "new keylen" ring keyctl add trusted name "load hex_blob" ring keyctl print keyidh]hikeyctl add trusted name "new keylen" ring keyctl add trusted name "load hex_blob" ring keyctl print keyid}hjHsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhj)hhubh)}(h"keyctl print" returns an ASCII hex copy of the sealed key, which is in format specific to TEE device implementation. The key length for new keys is always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).h]h“keyctl print” returns an ASCII hex copy of the sealed key, which is in format specific to TEE device implementation. The key length for new keys is always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj)hhubeh}(h]trusted-keys-usage-teeah ]h"]trusted keys usage: teeah$]h&]uh1hhj}hhhhhKubh)}(hhh](h)}(hTrusted Keys usage: CAAMh]hTrusted Keys usage: CAAM}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhjlhhhhhKubh)}(hUsage::h]hUsage:}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjlhhubj)}(hikeyctl add trusted name "new keylen" ring keyctl add trusted name "load hex_blob" ring keyctl print keyidh]hikeyctl add trusted name "new keylen" ring keyctl add trusted name "load hex_blob" ring keyctl print keyid}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjlhhubh)}(h"keyctl print" returns an ASCII hex copy of the sealed key, which is in a CAAM-specific format. The key length for new keys is always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).h]h“keyctl print” returns an ASCII hex copy of the sealed key, which is in a CAAM-specific format. The key length for new keys is always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjlhhubeh}(h]trusted-keys-usage-caamah ]h"]trusted keys usage: caamah$]h&]uh1hhj}hhhhhKubh)}(hhh](h)}(hTrusted Keys usage: DCPh]hTrusted Keys usage: DCP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM ubh)}(hUsage::h]hUsage:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubj)}(hikeyctl add trusted name "new keylen" ring keyctl add trusted name "load hex_blob" ring keyctl print keyidh]hikeyctl add trusted name "new keylen" ring keyctl add trusted name "load hex_blob" ring keyctl print keyid}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(h"keyctl print" returns an ASCII hex copy of the sealed key, which is in format specific to this DCP key-blob implementation. The key length for new keys is always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).h]h“keyctl print” returns an ASCII hex copy of the sealed key, which is in format specific to this DCP key-blob implementation. The key length for new keys is always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]trusted-keys-usage-dcpah ]h"]trusted keys usage: dcpah$]h&]uh1hhj}hhhhhM ubh)}(hhh](h)}(hEncrypted Keys usageh]hEncrypted Keys usage}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hThe decrypted portion of encrypted keys can contain either a simple symmetric key or a more complex structure. The format of the more complex structure is application specific, which is identified by 'format'.h]hThe decrypted portion of encrypted keys can contain either a simple symmetric key or a more complex structure. The format of the more complex structure is application specific, which is identified by ‘format’.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hUsage::h]hUsage:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hXkeyctl add encrypted name "new [format] key-type:master-key-name keylen" ring keyctl add encrypted name "new [format] key-type:master-key-name keylen decrypted-data" ring keyctl add encrypted name "load hex_blob" ring keyctl update keyid "update key-type:master-key-name"h]hXkeyctl add encrypted name "new [format] key-type:master-key-name keylen" ring keyctl add encrypted name "new [format] key-type:master-key-name keylen decrypted-data" ring keyctl add encrypted name "load hex_blob" ring keyctl update keyid "update key-type:master-key-name"}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(hWhere::h]hWhere:}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM&hjhhubj)}(hCformat:= 'default | ecryptfs | enc32' key-type:= 'trusted' | 'user'h]hCformat:= 'default | ecryptfs | enc32' key-type:= 'trusted' | 'user'}hj;sbah}(h]h ]h"]h$]h&]jjuh1jhhhM(hjhhubeh}(h]encrypted-keys-usageah ]h"]encrypted keys usageah$]h&]uh1hhj}hhhhhMubh)}(hhh](h)}(h+Examples of trusted and encrypted key usageh]h+Examples of trusted and encrypted key usage}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhjQhhhhhM,ubh)}(h=Create and save a trusted key named "kmk" of length 32 bytes.h]hACreate and save a trusted key named “kmk” of length 32 bytes.}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM.hjQhhubh)}(hNote: When using a TPM 2.0 with a persistent key with handle 0x81000001, append 'keyhandle=0x81000001' to statements between quotes, such as "new 32 keyhandle=0x81000001".h]hNote: When using a TPM 2.0 with a persistent key with handle 0x81000001, append ‘keyhandle=0x81000001’ to statements between quotes, such as “new 32 keyhandle=0x81000001”.}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM0hjQhhubj)}(hXG$ keyctl add trusted kmk "new 32" @u 440502848 $ keyctl show Session Keyring -3 --alswrv 500 500 keyring: _ses 97833714 --alswrv 500 -1 \_ keyring: _uid.500 440502848 --alswrv 500 500 \_ trusted: kmk $ keyctl print 440502848 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b e4a8aea2b607ec96931e6f4d4fe563ba $ keyctl pipe 440502848 > kmk.blobh]hXG$ keyctl add trusted kmk "new 32" @u 440502848 $ keyctl show Session Keyring -3 --alswrv 500 500 keyring: _ses 97833714 --alswrv 500 -1 \_ keyring: _uid.500 440502848 --alswrv 500 500 \_ trusted: kmk $ keyctl print 440502848 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b e4a8aea2b607ec96931e6f4d4fe563ba $ keyctl pipe 440502848 > kmk.blob}hj~sbah}(h]h ]h"]h$]h&]jjuh1jhhhM6hjQhhubh)}(h(Load a trusted key from the saved blob::h]h'Load a trusted key from the saved blob:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhjQhhubj)}(hXu$ keyctl add trusted kmk "load `cat kmk.blob`" @u 268728824 $ keyctl print 268728824 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b e4a8aea2b607ec96931e6f4d4fe563bah]hXu$ keyctl add trusted kmk "load `cat kmk.blob`" @u 268728824 $ keyctl print 268728824 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722 a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0 f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b e4a8aea2b607ec96931e6f4d4fe563ba}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMMhjQhhubh)}(h:Reseal (TPM specific) a trusted key under new PCR values::h]h9Reseal (TPM specific) a trusted key under new PCR values:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMZhjQhhubj)}(hX$ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`" $ keyctl print 268728824 010100000000002c0002800093c35a09b70fff26e7a98ae786c641e678ec6ffb6b46d805 77c8a6377aed9d3219c6dfec4b23ffe3000001005d37d472ac8a44023fbb3d18583a4f73 d3a076c0858f6f1dcaa39ea0f119911ff03f5406df4f7f27f41da8d7194f45c9f4e00f2e df449f266253aa3f52e55c53de147773e00f0f9aca86c64d94c95382265968c354c5eab4 9638c5ae99c89de1e0997242edfb0b501744e11ff9762dfd951cffd93227cc513384e7e6 e782c29435c7ec2edafaa2f4c1fe6e7a781b59549ff5296371b42133777dcc5b8b971610 94bc67ede19e43ddb9dc2baacad374a36feaf0314d700af0a65c164b7082401740e489c9 7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8h]hX$ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`" $ keyctl print 268728824 010100000000002c0002800093c35a09b70fff26e7a98ae786c641e678ec6ffb6b46d805 77c8a6377aed9d3219c6dfec4b23ffe3000001005d37d472ac8a44023fbb3d18583a4f73 d3a076c0858f6f1dcaa39ea0f119911ff03f5406df4f7f27f41da8d7194f45c9f4e00f2e df449f266253aa3f52e55c53de147773e00f0f9aca86c64d94c95382265968c354c5eab4 9638c5ae99c89de1e0997242edfb0b501744e11ff9762dfd951cffd93227cc513384e7e6 e782c29435c7ec2edafaa2f4c1fe6e7a781b59549ff5296371b42133777dcc5b8b971610 94bc67ede19e43ddb9dc2baacad374a36feaf0314d700af0a65c164b7082401740e489c9 7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhM\hjQhhubh)}(hXThe initial consumer of trusted keys is EVM, which at boot time needs a high quality symmetric key for HMAC protection of file metadata. The use of a trusted key provides strong guarantees that the EVM key has not been compromised by a user level problem, and when sealed to a platform integrity state, protects against boot and offline attacks. Create and save an encrypted key "evm" using the above trusted key "kmk":h]hXThe initial consumer of trusted keys is EVM, which at boot time needs a high quality symmetric key for HMAC protection of file metadata. The use of a trusted key provides strong guarantees that the EVM key has not been compromised by a user level problem, and when sealed to a platform integrity state, protects against boot and offline attacks. Create and save an encrypted key “evm” using the above trusted key “kmk”:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMihjQhhubh)}(hoption 1: omitting 'format'::h]h option 1: omitting ‘format’:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMphjQhhubj)}(h<$ keyctl add encrypted evm "new trusted:kmk 32" @u 159771175h]h<$ keyctl add encrypted evm "new trusted:kmk 32" @u 159771175}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMrhjQhhubh)}(h5option 2: explicitly defining 'format' as 'default'::h]h