path: root/Documentation/security
diff options
authorJames Bottomley <>2021-01-27 11:06:16 -0800
committerJarkko Sakkinen <>2021-04-14 16:30:30 +0300
commitf2219745250f388edacabe6cca73654131c67d0a (patch)
tree051936ef02a33f9a08ab24994178b7cff3d6b946 /Documentation/security
parentde66514d934d70ce73c302ce0644b54970fc7196 (diff)
security: keys: trusted: use ASN.1 TPM2 key format for the blobs
Modify the TPM2 key format blob output to export and import in the ASN.1 form for TPM2 sealed object keys. For compatibility with prior trusted keys, the importer will also accept two TPM2B quantities representing the public and private parts of the key. However, the export via keyctl pipe will only output the ASN.1 format. The benefit of the ASN.1 format is that it's a standard and thus the exported key can be used by userspace tools (openssl_tpm2_engine, openconnect and tpm2-tss-engine). The format includes policy specifications, thus it gets us out of having to construct policy handles in userspace and the format includes the parent meaning you don't have to keep passing it in each time. This patch only implements basic handling for the ASN.1 format, so keys with passwords but no policy. Signed-off-by: James Bottomley <> Tested-by: Jarkko Sakkinen <> Signed-off-by: Jarkko Sakkinen <>
Diffstat (limited to 'Documentation/security')
1 files changed, 58 insertions, 0 deletions
diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst
index 1da879a68640..549aa1308949 100644
--- a/Documentation/security/keys/trusted-encrypted.rst
+++ b/Documentation/security/keys/trusted-encrypted.rst
@@ -207,3 +207,61 @@ about the usage can be found in the file
Another new format 'enc32' has been defined in order to support encrypted keys
with payload size of 32 bytes. This will initially be used for nvdimm security
but may expand to other usages that require 32 bytes payload.
+TPM 2.0 ASN.1 Key Format
+The TPM 2.0 ASN.1 key format is designed to be easily recognisable,
+even in binary form (fixing a problem we had with the TPM 1.2 ASN.1
+format) and to be extensible for additions like importable keys and
+ parent INTEGER
+ privkey OCTET STRING
+ }
+type is what distinguishes the key even in binary form since the OID
+is provided by the TCG to be unique and thus forms a recognizable
+binary pattern at offset 3 in the key. The OIDs currently made
+available are::
+ TPM Loadable key. This is an asymmetric key (Usually
+ RSA2048 or Elliptic Curve) which can be imported by a
+ TPM2_Load() operation.
+ TPM Importable Key. This is an asymmetric key (Usually
+ RSA2048 or Elliptic Curve) which can be imported by a
+ TPM2_Import() operation.
+ TPM Sealed Data. This is a set of data (up to 128
+ bytes) which is sealed by the TPM. It usually
+ represents a symmetric key and must be unsealed before
+ use.
+The trusted key code only uses the TPM Sealed Data OID.
+emptyAuth is true if the key has well known authorization "". If it
+is false or not present, the key requires an explicit authorization
+phrase. This is used by most user space consumers to decide whether
+to prompt for a password.
+parent represents the parent key handle, either in the 0x81 MSO space,
+like 0x81000001 for the RSA primary storage key. Userspace programmes
+also support specifying the primary handle in the 0x40 MSO space. If
+this happens the Elliptic Curve variant of the primary key using the
+TCG defined template will be generated on the fly into a volatile
+object and used as the parent. The current kernel code only supports
+the 0x81 MSO form.
+pubkey is the binary representation of TPM2B_PRIVATE excluding the
+initial TPM2B header, which can be reconstructed from the ASN.1 octet
+string length.
+privkey is the binary representation of TPM2B_PUBLIC excluding the
+initial TPM2B header which can be reconstructed from the ASN.1 octed
+string length.