From patchwork Mon May 24 22:20:11 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: James Bottomley X-Patchwork-Id: 12277073 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-23.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id B69B8C04FF3 for ; Mon, 24 May 2021 22:20:54 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 93E30613D8 for ; Mon, 24 May 2021 22:20:54 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229586AbhEXWWW (ORCPT ); Mon, 24 May 2021 18:22:22 -0400 Received: from bedivere.hansenpartnership.com ([96.44.175.130]:34718 "EHLO bedivere.hansenpartnership.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229610AbhEXWWW (ORCPT ); Mon, 24 May 2021 18:22:22 -0400 Received: from localhost (localhost [127.0.0.1]) by bedivere.hansenpartnership.com (Postfix) with ESMTP id A97F612802B1; Mon, 24 May 2021 15:20:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=hansenpartnership.com; s=20151216; t=1621894853; bh=640M06xr+9CtCzlqcM9Gps1qTuEwI1bzhyzyhngux/I=; h=From:To:Subject:Date:Message-Id:In-Reply-To:References:From; b=qlEfo/JcovIJYt8g7pSkK7rdosr9XM90mW4lRutXCMhyV8oDRzfsunNnOdV5MdvrX ytAcJxWYRQ4zqCvORz1U9ylvqdOHrhVasBdID5o83teSP5ULezeJC/ozU4+77iVvfS 2inzOx6lAs907D0R/DUWHuhZXVqi7sBiEi/t49jw= Received: from bedivere.hansenpartnership.com ([127.0.0.1]) by localhost (bedivere.hansenpartnership.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id JvnGDgs-Kru2; Mon, 24 May 2021 15:20:53 -0700 (PDT) Received: from jarvis.int.hansenpartnership.com (jarvis.ext.hansenpartnership.com [153.66.160.226]) by bedivere.hansenpartnership.com (Postfix) with ESMTP id 2F9F7128029D; Mon, 24 May 2021 15:20:53 -0700 (PDT) From: James Bottomley To: openssl-tpm2-engine@groups.io Cc: linux-integrity@vger.kernel.org, Mimi Zohar , Jarkko Sakkinen , David Woodhouse , keyrings@vger.kernel.org, David Howells Subject: [PATCH v2 1/1] doc: add draft RFC for TPM Key format Date: Mon, 24 May 2021 15:20:11 -0700 Message-Id: <20210524222011.24313-2-James.Bottomley@HansenPartnership.com> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20210524222011.24313-1-James.Bottomley@HansenPartnership.com> References: <20210524222011.24313-1-James.Bottomley@HansenPartnership.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: keyrings@vger.kernel.org Adds the xml file for the draft RFC and builds text and html versions if the xml2rfc program is found. Signed-off-by: James Bottomley --- v2: Add missing sections plus minor updates --- Makefile.am | 2 +- configure.ac | 4 +- doc/Makefile.am | 15 + doc/draft-bottomley-tpm2-keys.xml | 465 ++++++++++++++++++++++++++++++ 4 files changed, 484 insertions(+), 2 deletions(-) create mode 100644 doc/Makefile.am create mode 100644 doc/draft-bottomley-tpm2-keys.xml diff --git a/Makefile.am b/Makefile.am index 33de0d9..787ba29 100644 --- a/Makefile.am +++ b/Makefile.am @@ -41,4 +41,4 @@ $(builddir)/%.1: $(srcdir)/%.1.in $(top_builddir)/% install-data-hook: cd $(DESTDIR)$(openssl_enginedir) && $(LN_S) -f libtpm2@SHREXT@ tpm2@SHREXT@ -SUBDIRS = tests +SUBDIRS = tests doc diff --git a/configure.ac b/configure.ac index 6efa7a5..e102dd2 100644 --- a/configure.ac +++ b/configure.ac @@ -128,6 +128,8 @@ fi AC_PATH_PROG(TPMSERVER, tpm_server,,/bin:/usr/bin:/usr/lib/ibmtss:/usr/libexec/ibmtss) AC_PATH_PROG(SWTPM, swtpm,,/bin:/usr/bin:/usr/lib/ibmtss:/usr/libexec/ibmtss) AC_PATH_PROG(SWTPM_IOCTL, swtpm_ioctl,,/bin:/usr/bin:/usr/lib/ibmtss:/usr/libexec/ibmtss) +AC_CHECK_PROG(XML2RFC, xml2rfc, xml2rfc) +AM_CONDITIONAL(HAVE_XML2RFC, test -n "${XML2RFC}") CFLAGS="$CFLAGS -Wall" SHREXT=$shrext_cmds AC_SUBST(CFLAGS) @@ -147,7 +149,7 @@ fi AC_SUBST(testtpm) -AC_OUTPUT([Makefile tests/Makefile]) +AC_OUTPUT([Makefile tests/Makefile doc/Makefile]) cat < + + + +]> + + + + ASN.1 Specification for TPM 2.0 Key Files + + Linux Kernel +
+ + + + + USA + + James.Bottomley@HansenPartnership.com +
+ + + Security + I-D + Internet-Draft + X.509 + + + This specification is designed to be an extension to the ASN.1 + (defined in ) specification of PKCS #1 + to define the file format of private + keys that need to be loaded into a TPM 2 device to operate. + + + + +
+ + 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. + +
+
+ + 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 + . + +
+
+
ASN.1
+
Abstract Syntax Notation defined in +
+
DER
+
Distinguished Encoding Rules. Basically a defined binary + representation for ASN.1
+
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
+
+
+
+
+ + 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 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 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. + +
+
+ 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: + +
+ + 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} +
+
+
+ + 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. + +
+
+ + 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 . + +
+
+ + 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. + + + Importable keys (designed to be processed by TPM2_Import) + MUST have an unencrypted inner wrapper (symmetricAlg MUST + be TPM_ALG_NULL and encryptionKey MUST be empty) and an + outer wrapper encrypted to the parent key using + inSymSeed. The secret parameter is the fully marshalled + TPM2B_ENCRYPTED_SECRET form of inSymSeed. + +
+
+ + This MUST be present for all keys and specifies the handle + of 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 MUST + NOT have 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. + +
+
+ + This MUST be present and MUST correspond to the fully + marshalled TPM2B_PUBLIC structure of the TPM Key. + +
+
+ + This MUST be present and MUST correspond to the fully + marshalled TPM2B_PRIVATE structure of the TPM Key. For + importable keys, this must be the duplicate parameter that + would be input to TPM2_Import. + +
+
+
+
+ + 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 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 formulated 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). + +
+
+ TPMPolicy ::= SEQUENCE { + CommandCode [0] EXPLICIT INTEGER + CommandPolicy [1] EXPLICIT OCTET STRING + } +
+ + The Fields of type TPMPolicy have the following meanings: + +
+ + This is the integer representation of the TPM command code + for the policy statement. + +
+
+ + 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 + +
+
+
+ + 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 specifications + for how to construct the policyHash. + + + The implementation should fail fast for policy problems, so + if an individual policy command returns a failure (which + usually indicates a particular policy requirement cannot be + met), that failure should be reported in as much detail as + possible and processing of the key should fail at that + point. + +
+ + 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. + +
+
+
+
+ + Implementations SHOULD support all TCG mandated algorithms, + but MAY omit those deemed insecure, such as the SHA1 hash. + + + TPM2_Import transforms the privKey into a TPM2B_PRIVATE which + can then be used as a source to TPM2_Load, making the loading + of importable keys is necessarily a two stage process, which + can be time consuming on some TPMs. Since the TPM2B_PRIVATE + structure emitted by TPM2_Import is fully secure, + Implementations SHOULD minimize the number of TPM2_Import + operations by caching the emitted TPM2B_PRIVATE. + +
+
+ + The TPM 2.0 supports a variety of algorithms, the most common + being SHA1 and SHA256 for hashing and RSA2048 and NIST P-256 + for asymmetric keys. Implementors SHOULD NOT use deprecated + algorithms, such as SHA1, for any TPM operation. In + particular, the algorithm used for the policy hash SHOULD NOT + be SHA1 and this means that SHA1 SHOULD NOT be used as the + name algorithm hash for any TPM key. + + + TPM 2.0 supports a session mode (TPM_RS_PW) where + authorizations are passed to the TPM in clear text over the + TPM connection. Implementations SHOULD consider the + possibility of snooping on the wire between the implementation + and the TPM, such as , and SHOULD + use HMAC session authorizations as best practice for all TPM + keys. + + + In addition to snooping authorizations, snooping may also + occur when key material is being exchanged between the TPM and + the implementation, such as wrapping of private keys and the + sealing and unsealing operations for sealed keys. + Implementations SHOULD always use HMAC sessions with + TPMA_SESSION_DECRYPT when sensitive information is passed in + to the TPM and HMAC sessions with TPMA_SESSION_ENCRYPT when + sensitive information is received from the TPM. + + + The easiest way to get the TPM to wrap an external private key + is to use TPM2_Import. However, since TPMA_SESSION_DECRYPT + only protects the first parameter (which is encryptionKey), + the duplicate should use inner symmetric encryption with a + randomly generated ephemeral key, which is then presented to + the TPM via the protected encryptionKey parameter. + + + The TPM has a mode where it can generate private key material + internally (using TPM2_Create) such that the private part of + the key can never leave the TPM. Implementations SHOULD + support this mode but should be aware that while keys created + like this may be more secure than wrapped keys, they can also + be used only while access to the TPM that created them is + available, so implementations SHOULD also support wrapping for + keys that are expected to outlive the TPM that's using them. + Clients can then develop best practices around TPM wrapped + identity keys, possibly with TPM created sub keys, which can + only be used on the device they were wrapped for. + + + Since TPM keys can only be used by the specific TPM that + created them, which is usually embedded in a piece of + hardware, they are secure against exfiltration attacks. + However, consideration should be given to an attacker gaining + access to the system containing the TPM. TPM keys are most + secure when used as part of an operating system that has + guaranteed trust properties, such as secure and measured boot. + Implementations SHOULD assist users in constructing key + policies that ensure the key can be used only when the + operating system is within its trusted parameters to minimize + threats from co-located attackers. + +
+
+ + None. + +
+
+ + Comments on this document should be addressed to the author + (James.Bottomley@HansenPartnership.com) but should also CC the + email lists of the two projects implementing this + specification: + + + The OpenSSL engine: openssl_tpm2_engine@groups.io + + + The Linux Kernel: linux-integrity@vger.kernel.org + + + The OpenSSL TPM2 engine + is currently the only implementation of this full + specification, so enhancements should be proposed after + patches implementing the enhancement have been accepted by + openssl_tpm2_engine or another full specification + implementation. + +
+ + + + + &RFC2119; + &RFC8017; + + + TPM 2.0 Library Specification + + Trusted Computing Group + + + + + + + ITU-T Recommendation X.680, + Information technology - Abstract Syntax Notation One + (ASN.1): Specification of basic notation. + International Telecommunication Union + + + + + + + + TPM Genie: Interposer Attacks Against the Trusted + Platform Module Serial Bus + + NCC Group + + + + + + + OpenSSL TPM2 Engine + Open Source Project + + + + +