On Sat, May 22, 2021 at 11:15:47AM -0700, James Bottomley wrote: > Note: this is a patch for openssl_tpm2_engine, not the kernel. > > This is the text of the draft RFC for comments (although patches to > the xml would be preferred): > > ====== Did not go through with an eyeglass but looks overally great! > Network Working Group J. Bottomley > Internet-Draft Linux Kernel > Intended status: Informational May 2021 > Expires: 23 November 2021 > > > ASN.1 Specification for TPM 2.0 Key Files > draft-bottomley-tpm-keys-00 > > Abstract > > This specification is designed ot be an extension to the ASN.1 > (defined in [X.680]) specification of PKCS #1 [RFC8017] to define the > file format of private keys that need to be loaded into a TPM 2 > device to operate. > > Status of This Memo > > This Internet-Draft is submitted in full conformance with the > provisions of BCP 78 and BCP 79. > > Internet-Drafts are working documents of the Internet Engineering > Task Force (IETF). Note that other groups may also distribute > working documents as Internet-Drafts. The list of current Internet- > Drafts is at https://datatracker.ietf.org/drafts/current/. > > Internet-Drafts are draft documents valid for a maximum of six months > and may be updated, replaced, or obsoleted by other documents at any > time. It is inappropriate to use Internet-Drafts as reference > material or to cite them other than as "work in progress." > > This Internet-Draft will expire on 2 November 2021. > > Copyright Notice > > Copyright (c) 2021 IETF Trust and the persons identified as the > document authors. All rights reserved. > > This document is subject to BCP 78 and the IETF Trust's Legal > Provisions Relating to IETF Documents (https://trustee.ietf.org/ > license-info) in effect on the date of publication of this document. > Please review these documents carefully, as they describe your rights > and restrictions with respect to this document. Code Components > extracted from this document must include Simplified BSD License text > as described in Section 4.e of the Trust Legal Provisions and are > provided without warranty as described in the Simplified BSD License. > > > > > > Bottomley Expires 23 November 2021 [Page 1] > > Internet-Draft TPM 2 Key Format May 2021 > > > Table of Contents > > 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 > 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 > 2.1. Notation . . . . . . . . . . . . . . . . . . . . . . . . 2 > 3. Key Representation . . . . . . . . . . . . . . . . . . . . . 3 > 3.1. TPMkey Syntax . . . . . . . . . . . . . . . . . . . . . . 3 > 3.1.1. type . . . . . . . . . . . . . . . . . . . . . . . . 4 > 3.1.2. emptyAuth . . . . . . . . . . . . . . . . . . . . . . 4 > 3.1.3. policy . . . . . . . . . . . . . . . . . . . . . . . 4 > 3.1.4. secret . . . . . . . . . . . . . . . . . . . . . . . 4 > 3.1.5. parent . . . . . . . . . . . . . . . . . . . . . . . 5 > 3.1.6. pubkey . . . . . . . . . . . . . . . . . . . . . . . 5 > 3.1.7. privkey . . . . . . . . . . . . . . . . . . . . . . . 5 > 4. Key Policy Specification . . . . . . . . . . . . . . . . . . 5 > 4.1. TPMPolicy Syntax . . . . . . . . . . . . . . . . . . . . 6 > 4.1.1. CommandCode . . . . . . . . . . . . . . . . . . . . . 6 > 4.1.2. CommandPolicy . . . . . . . . . . . . . . . . . . . . 6 > 4.2. Policy Implementation Considerations . . . . . . . . . . 6 > 4.2.1. Authorization Policy . . . . . . . . . . . . . . . . 6 > 5. Normative References . . . . . . . . . . . . . . . . . . . . 7 > Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 > > 1. Introduction > > The Security of private keys has long been a concern and the ability > of ubiquitous devices like TPMs has made it useful to use them for > secure private key storage. With the advent of TPM 2.0, private key > storage inside the TPM (acting as a token which could be referred to > by PKCS #11) has been discouraged, and instead key files which are > loaded and evicted as necessary is the encouraged format. This > standard defines an interoperable ASN.1 representation for such key > files, so that a key created by one tool should be loadable by a > different one. > > 2. Terminology > > The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", > "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this > document are to be interpreted as described in [RFC2119]. > > 2.1. Notation > > ASN.1 Abstract Syntax Notatition defined in [X.680] > > DER Distinguished Encoding Rules. Basically a defined binary > representation for ASN.1 > > > > > Bottomley Expires 23 November 2021 [Page 2] > > Internet-Draft TPM 2 Key Format May 2021 > > > MSO Most Significant Octet (the highest order byte of an integer) > > PEM Privacy enhanced Electronic Mail. An ASCII compatible > representation of DER > > TCG Trusted Computing Group > > TPM Trusted Platform Module > > 3. Key Representation > > All TPM 2.0 keys consist of two binary pieces, a public part, which > can be parsed according to the TPM specification for TPM2B_PUBLIC > [TPM2.0] and a private part, which is cryptographically sealed in > such a way as to be only readable on the TPM that created it. The > purpose of this specification is to specify a format by which the > public and private pieces of a TPM key can be loaded. > > The design of the TPMkey ASN.1 format is that it should have a > distinguishing OID at the beginning so the DER/BER form of the key > can be easily recognized. In PEM form, the key MUST have "-----BEGIN > TSS2 PRIVATE KEY-----" and "-----END TSS2 PRIVATE KEY-----" as the > PEM guards. All additional information that may be needed to load > the key is specified as optional explicit elements, which can be > extended by later specifications, which is why the TPMkey is not > versioned. > > 3.1. TPMkey Syntax > > TPMKey ::= SEQUENCE { > type OBJECT IDENTIFIER > emptyAuth [0] EXPLICIT BOOLEAN OPTIONAL > policy [1] EXPLICIT SEQUENCE OF TPMPolicy OPTIONAL > secret [2] EXPLICIT OCTET STRING OPTIONAL > parent INTEGER > pubkey OCTET STRING > privkey OCTET STRING > } > > The fields of type TPMKey have the following meanings: > > > > > > > > > > > > Bottomley Expires 23 November 2021 [Page 3] > > Internet-Draft TPM 2 Key Format May 2021 > > > 3.1.1. type > > A unique OID specifying the key type. This standard currently > defines three types of keys: a loadable key, specified by id- > loadablekey, (to be loaded with TPM2_Load), an importable key, > specified by id-importablekey, (to be loaded with TPM2_Import) and a > sealed data key, specified by id-sealedkey, (to be extracted with > TPM2_Unseal). The TCG has reserved the following OID prefix for > this: > > id-tpmkey OBJECT IDENTIFIER ::= > {joint-iso-itu-t(2) international-organizations(23) 133 10} > > And the three key types are: > > id-loadablekey OBJECT IDENTIFIER ::= > {id-tpmkey 3} > > id-importablekey OBJECT IDENTIFIER ::= > {id-tpmkey 4} > > id-sealedkey OBJECT IDENTIFIER ::= > {id-tpmkey 5} > > 3.1.2. emptyAuth > > An implementation needs to know as it formulates the > TPM2_Load/Import/Unseal command whether it must also send down an > authorization, so this parameter gives that indication. emptyAuth > MUST be true if authorization is NOT required and MUST BE either > false or absent if authorization is required. Since this element has > three states (one representing true and two representing false) it is > RECOMMENDED that implementations emitting TPMkey representations use > absence of the tag to represent false. However, implementations > reading TPMKey MUST be able to process all three possible states. > > 3.1.3. policy > > This MUST be present if the TPM key has a policy hash because it > describes to the implementation how to construct the policy. The > forms of the policy statement are described in section Section 4. > > 3.1.4. secret > > This section describes the additional cryptographic secret used to > specify the outer wrapping of an importable key. It MUST be present > for key type id-importablekey and MUST NOT be present for any other > key type. > > > > Bottomley Expires 23 November 2021 [Page 4] > > Internet-Draft TPM 2 Key Format May 2021 > > > 3.1.5. parent > > This MUST be present for all keys and specifies the parent key. The > parent key SHOULD be either a persistent handle (MSO 0x81) or a > permanent handle (MSO 0x40). Since volatile handle numbering can > change unexpectedly depending on key load order, the parent SHOULD > NOT be a volatile handle (MSO 0x80). The parent MAY NOT be any other > MSO. > > If a permanent handle (MSO 0x40) is specified then the implementation > MUST run TPM2_CreatePrimary on the handle using the TCG specified > Elliptic Curve template for the NIST P-256 curve and use the primary > key so generated as the parent. > > 3.1.6. pubkey > > This MUST be present and MUST correspond to the fully marshalled > TPM2B_PUBLIC structure of the TPM Key with the exception that the > leading U16 parameter specifying size MUST BE omitted (it is > redundant, since all ASN.1 structures are length specified). > > 3.1.7. privkey > > This MUST be present and MUST correspond to the fully marshalled > TPM2B_PRIVATE structure of the TPM Key with the exception that the > leading U16 parameter specifying size MUST BE omitted (it is > redundant, since all ASN.1 structures are length specified). > > 4. Key Policy Specification > > Policy is constructed on a TPM by executing a sequence of policy > statements. This specification currently only defines a limited > subset of the allowed policy statements. The policy is specified by > a hash, which the execution of the policy statements must reach in > order for the policy to be validated (See [TPM2.0] Part 1 for a > detailed description. > > The TPMPolicy ASN.1 MUST be a sequence of policy statements which > correspond exactly to TPM policy instructions in the order they > should be executed and additionally from which the ultimate policy > hash can be constructed. > > The current policy specification is strictly for AND based policy > only and may be extended at a later date with OR policy. However, > the ASN.1 for policy is fomulated as CONS elements, leaving the > possibility of adding additional but optional elements for policy > statements which are not supported by this standard (such as > TPM2_PolicyAuthorize). > > > > Bottomley Expires 23 November 2021 [Page 5] > > Internet-Draft TPM 2 Key Format May 2021 > > > 4.1. TPMPolicy Syntax > > TPMPolicy ::= SEQUENCE { > CommandCode [0] EXPLICIT INTEGER > CommandPolicy [1] EXPLICIT OCTET STRING > } > > The Fields of type TPMPolicy have the following meanings: > > 4.1.1. CommandCode > > This is the integer representation of the TPM command code for the > policy statement. > > 4.1.2. CommandPolicy > > This is a binary string representing a fully marshalled, TPM ordered, > command body for the TPM policy command. Therefore to send the > command, the implementation simply marshalls the command code and > appends this octet string as the body. > > Commands which have no body, such as TPM2_AuthVal, MUST be specified > as a zero length OCTET STRING > > 4.2. Policy Implementation Considerations > > The policy hash for AND based policies is constructed by extension of > the prior policy hash > > newHash = HASH ( oldHash || policyHash ) > > where policyHash is usually simply the hash of the fully marshalled > policy command (including the CommandCode). However, this isn't true > for TPM2_PolicyCounterTimer() so always consult the [TPM2.0] > specifications for how to construct the policyHash. > > 4.2.1. Authorization Policy > > When Authorization (Passing in a password) is required, the emptyAuth > parameter MUST be absent or set to false and additionally the > TPM_CC_PolicyAuthValue MUST be specified as the command code for one > entry in the TPMPolicy sequence. However, the implementation MAY > choose to execute either TPM2_PolicyPassword for TPM_RS_PW or > TPM2_PolicyAuthValue for HMAC based authorization depending on > whether the command being authorized is using sessions or not. If > the policy does not require an authorization then the emptyAuth > parameter MUST be set to true. > > > > > Bottomley Expires 23 November 2021 [Page 6] > > Internet-Draft TPM 2 Key Format May 2021 > > > 5. Normative References > > [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate > Requirement Levels", BCP 14, RFC 2119, > DOI 10.17487/RFC2119, March 1997, > <https://www.rfc-editor.org/info/rfc2119>. > > [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, > "PKCS #1: RSA Cryptography Specifications Version 2.2", > RFC 8017, DOI 10.17487/RFC8017, November 2016, > <https://www.rfc-editor.org/info/rfc8017>. > > [TPM2.0] TCG, ., "TPM 2.0 Library Specification", 15 March 2013, > <https://trustedcomputinggroup.org/resource/tpm-library- > specification/>. > > [X.680] ITU, "ITU-T Recommendation X.680, Information technology - > Abstract Syntax Notation One (ASN.1): Specification of > basic notation.", August 2015, > <https://www.itu.int/rec/T-REC-X.680-201508-I/en>. > > Author's Address > > James E.J. Bottomley > Linux Kernel > United States of America > > Email: James.Bottomley@xxxxxxxxxxxxxxxxxxxxx > > > > > > > > > > > > > > > > > > > > > > > > Bottomley Expires 23 November 2021 [Page 7] > > ====== > > James > > --- > > James Bottomley (1): > doc: add draft RFC for TPM Key format > > Makefile.am | 2 +- > configure.ac | 4 +- > doc/Makefile.am | 15 ++ > doc/draft-bottomley-tpm2-keys.xml | 329 ++++++++++++++++++++++++++++++ > 4 files changed, 348 insertions(+), 2 deletions(-) > create mode 100644 doc/Makefile.am > create mode 100644 doc/draft-bottomley-tpm2-keys.xml > > -- > 2.26.2 > > /Jarkko
