<?xml version='1.0' encoding='utf-8'?>

<!DOCTYPE rfc  >
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs), 
please see http://xml.resource.org/authoring/README.html. -->
<rfc xmlns:xi="http://www.w3.org/2001/XInclude"
category="info"
docName="draft-stjohns-csr-attest-00"
ipr="trust200902"
obsoletes=""
updates=""
submissionType="IETF"
xml:lang="en"
tocInclude="true"
tocDepth="4"
symRefs="true"
sortRefs="true"
version="3">
<!-- xml2rfc v2v3 conversion 2.38.1 -->
<!-- category values: std, bcp, info, exp, and historic
     ipr values: trust200902, noModificationTrust200902, noDerivativesTrust200902,
     or pre5378Trust200902
     you can add the attributes updates="NNNN" and obsoletes="NNNN" 
     they will automatically be output with "(if approved)" -->

<!-- ***** FRONT MATTER ***** -->

<front>
  <!-- The abbreviated title is used in the page header - it is only necessary if the 
       full title is longer than 39 characters -->

  <title abbrev="CSR Attestation Attributes">Attestation Attributes for use with Certificate Requests</title>
  <seriesInfo name="Internet-Draft" value="draft-stjohns-csr-attest-00"/>

  <author fullname="Michael StJohns" initials="M" surname="StJohns">
    <organization>NthPermutation Security LLC</organization>
    <address>
      <postal>
        <street/>
        <city>Germantown</city>
        <region>MD</region>
        <code>20874</code>
        <country>US</country>
      </postal>
      <phone/>
      <email>msj@nthpermutation.com</email>
    </address>
  </author>
  <date year="2023"/>
  <area>Security</area>
  <workgroup>LAMPS</workgroup>
  <!--<keyword>template</keyword> -->
  <abstract>
    <t>
      This document describes two ASN.1 Attribute definitions that may
      be used to carry key attestation data in PKCS10 certificate
      requests and in other circumstances.
    </t>
  </abstract>
</front>
<middle>
  <section numbered="true" toc="default">
    <name>Introduction</name>
    <t>
      This document is intentionally incomplete as it is a
      counter-offer to two other Internet Drafts currently being
      considered by LAMPS for adoption or progression. 
    </t>
    <t>
      Unlike the other proposals, this document attempts to describe
      an encoding that may be used regardless of the actual format and
      mechanisms used by an given type of attestation.  To do that it
      defines two Attributess: the first to carry the attribution
      statement, any ancillary or externally provided information for
      the statement (e.g. a freshness nonce), and the signature over
      the attestation statement; the second to carry one or more
      certificates which may be used in the validation of the
      attestation statement.
    </t>
    <t>
      For the purposes of this document, a "certificate" is a signed
      binding of a public key and some identifying or use
      information.  An X.509 Certificate is one example, but the
      structures described below allow for the specification of pretty
      much any type of certificate imaginable.
    </t>
    <section numbered="true" toc="default">
      <name>Requirements Language</name>
      <t>
	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 <xref target="RFC2119" format="default">RFC 2119</xref>.
      </t>
    </section>
  </section>
  <section anchor="asn1elements" numbered="true" toc="default">
    <name>ASN.1 Elements</name>
    <section anchor="oidDefs" numbered="true" toc="default">
      <name>Object Identifiers</name>
      <t>
	This is a place holder for actual assignments. It's possible
	there's already a pkace for the attribute OID assignments. 
      </t>
      <sourcecode>
	id-pkix OBJECT IDENTIFIER ::= { iso(1) identified-organization(3)
	  dod(6) internet(1) security(5) mechanisms(5) pkix(7) }

	-- Branch for CSR and related attributes - IETF version of id-at
	id-pkix-at OBJECT IDENTIFIER ::= { id-pkix (tbd) }

	-- Branch for attestation statement types
	id-ata OBJECT IDENTIFIER ::= { id-pkix (tbd) }


      </sourcecode>
    </section>
    <section anchor="certchoice" numbered="true" toc="default">
      <name>CertificateChoice</name>
      <t>
	This is an ASN.1 CHOICE construct used to represent an
	encoding of a broad variety of certificate types.
      </t>
      <sourcecode>
	CertificateChoice ::=
	  CHOICE {
	    cert Certificate, -- typical X.509 cert
	    opaqueCert [0] IMPLICIT OCTET STRING, -- format implictly known
	    typedCert [1] IMPLICIT TypedCert, -- non-X.509 but ASN1 cert
	    typedFlatCert [2] IMPLICIT TypedFlatCert -- non-ASN1 cert
	}
      </sourcecode>
      <t>
	"Certificate" is a more or less standard X.509 certificate.
	"opaqueCert" should be used sparingly as it requires the
	receiving party to implictly know its format.  It is encoded
	as an OCTET STRING
      </t>
      <t>
	"TypedCert" is an ASN.1 construct that has the charateristics
	of a certificate, but is not encoded as an X.509 certificate.
	The certTypeField indicates how to interpret the content
	field.  Note that it is possible to use this field to convey a
	bare public key as well.
      </t>
      <sourcecode>
	TYPED-CERT ::= TYPE-IDENTIFIER -- basically an object id and a matching ASN1
                               -- structure encoded as a sequence
        CertType ::= TYPED-CERT.&amp;id   

	TypedCert ::= SEQUENCE {
	  certType     TYPED-CERT.&amp;id({TypedCertSet}),
	  content      TYPED-CERT.&amp;Type ({TypedCertSet}{@certType})
	}

	TypedCertSet TYPED-CERT ::=
	  ... -- Empty for now, 
	}
      </sourcecode>
      <t>
	"TypedFlatCert" is a certificate that does not have a valid
	ASN.1 encoding. Think compact or implicit certificates as
	might be used with smart cards.  certType indcates the format
	of the data in the content field.
      </t>
      <sourcecode>
	TypedFlatCert ::= SEQUENCE {
	  certType OBJECT IDENTIFIER,
	  certBody OCTET STRING
	}  
      </sourcecode>
    </section>
    <section anchor="attestAttribute" numbered="true" toc="default">
      <name>AttestAttribute</name>
      <t>
	By definition, Attributes within a Certificate Signing Request
	are typed as ATTRIBUTE. This attribute is used to contain
	exactly one attestation statement of a particular type.
      </t>
      <sourcecode>
	id-pkix-at-attestStatement OBJECT IDENTIFIER ::= { id-pkix-at 1 }
	
	attestAttribute ATTRIBUTE ::= {
	  TYPE AttestStatement
	  COUNTS MAX 1 -- tentative, maybe delete
	  IDENTIFIED BY id-pkix-at-attestStatement
	}
      </sourcecode>
    </section>
    <section anchor="attestCertsAttribute" numbered="true"
	     toc="default">
      <name>AttestCertsAttribute</name>
      <t>
	The "attestCertChainAttribute" contains a sequence of certificates
	that may be used to validate the contents of an attestation
	statement contained in an attestAttribute.  By convention, the
	first element of the SEQUENCE should contain the object that
	contains the public key needed to directly validate the
	attestAttribute.  The remaining elements should chain that
	data back to an agreed upon root of trust for the attestation.
      </t>
      <sourcecode>
	id-pkix-at-attestCertChain OBJECT IDENTIFIER ::= { id-pkix-at 2 }
	
	attestCertChainAttribute ATTRIBUTE ::= {
	  TYPE SEQUENCE OF CertificateChoice
	  COUNTS MAX 1
	  IDENTIFIED BY id-pkix-at-attestCertChain
	}
      </sourcecode>

    </section>
    <section anchor="attestStatement" numbered="true" toc="default">
      <name>AttestStatement</name>
      <t>
	An AttestStatement is an object of class ATTEST-STATEMENT
	encoded as a sequence fields, of which the type of the "value"
	field is controlled by the value of the "type" field, similar
	to an Attribute definition.
      </t>
      <sourcecode>
	ATTEST-STATEMENT ::= CLASS {
	  &amp;id    OBJECT IDENTIFIER UNIQUE,
	  &amp;Type      -- NOT optional        
	} WITH SYNTAX { 
          TYPE  &amp;Type 
          IDENTIFIED BY &amp;id 
        }

	AttestStatement { ATTEST-STATEMENT:IOSet}  ::= SEQUENCE
	{
	  type ATTEST-STATEMENT.&amp;id({IOSet}),
	  value ATTEST-STATEMENT.&amp;Type({IOSet}{@type}),
	  algId [0] IMPLICIT  OPTIONAL AlgorithmIdentifier,
	  signature [1] SignatureChoice OPTIONAL -- note NOT implicit
	  ancillaryData [2] IMPLICIT  OCTET STRING OPTIONAL
	}
      </sourcecode>
      <t>
	Depending on whether the "value" field contains an entire signed
	attestation, or only the toBeSigned portion, the algId field
	may or may not be present.  If present it contains the
	AlgorithmIdentifier of the signature algorithm used to sign
	the attestation statement. If absent, either the value field
	contains an indication of the signature algorithm, or the
	signature algorithm is fixed for that specific type of AttestStatement.
      </t>
      <t>
	Similarly for the signature field, if the value field contains
	only the toBeSigned portion of the attestation statement, this
	field should be present.  In the case of an attestation with
	the signature present, it's desirable but not mandatory that
	the signature is over the DER encoding of the value field.
      </t>
      <t>
	The ancillaryData field contains data provided externally to
	the attestation engine, and whose content and format is not under
	the control of the attestation engine.  For example, this
	field might contain a freshness nonce generated by the relying
	party, a signed time stamp, or even a hash of protocol data or
	nonce data.  See below for a few different examples.
      </t>
      <t>
	An example of how to define an AttestStatement object might
	be: (Note - confirm "WITH COMPONENTS syntax is usable here")
      </t>
      <sourcecode>
	id-mikes-attest-attribute OBJECT IDENTIFIER ::=  { enterprise  nthperm(50924) attest(999) }

	MikesAttest ATTEST-STATEMENT ::= { TYPE OCTET STRING
	  IDENTIFIED BY id-mikes-attest-attribute }
	  (WITH COMPONENTS algId, signature, ancillaryData)
	--
      </sourcecode>
      <t>
	That would define an attribute where the value field is of
	type OCTET STRING, and where all three of the optional fields
	are present.  Additional text would identify the expected
	signature algorithms and the contents of the ancillaryData
	field under various uses.
      </t>
    </section>

    <section anchor="sigType" numbered="true" toc="default">
      <name>SignatureChoice</name>
      <t>
	"SignatureChoice" allows for the encoding of the signature
	field of the attestation either in the common ASN.1 form of a
	BIT STRING or as an OCTET STRING.  While not expressed in the
	AttestStatement structure, the type of this field should be
	consistent with the "type" of the attestation statement.
      </t>
      <sourcecode>
	SignatureChoice ::= CHOICE {
	    bs BIT STRING,
	    os OCTET STRING
	}
      </sourcecode>
    
    </section>
  </section>
  <section anchor="IANA" numbered="true" toc="default">
    <name>IANA Considerations</name>
    <t>
      Placeholder - two new registries to be opened; one for general/csr
      attributes, another for attestation statement types
    </t>
    
  </section>
  <section anchor="Security" numbered="true" toc="default">
    <name>Security Considerations</name>
    <t>TBD</t>
  </section>
</middle>
<!--  *****BACK MATTER ***** -->

<back>
  <references>
    <name>References</name>
    <references>
      <name>Normative References</name>
      <?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"?>
    </references>
    <references>
      <name>Informative References</name>
    
    </references>
  </references>
  <section anchor="examples" numbered="true" toc="default">
    <name>Examples</name>
    <section anchor="tpmattest" numbered="true" toc="default">
      <name>Sample TPM V2.0 Attestation Attribute</name>
      <t>
	What follows is a sample ATTEST-STATEMENT for a Trusted
	Platform Module (TPM) V2.0.  This is a first pass without
	validating the results.
      </t>
      <sourcecode>
	id-ata-tpmv20 OBJECT IDENTIFIER ::= { id-ata (tbd) }

	TpmV20Attest ATTEST-STATEMENT ::= {
	  TYPE OCTET STRING
	  IDENTIFIED BY id-ata-tpmv20 }
	  (WITH COMPONENTS signature)
      </sourcecode>
      <t>
	This attestation is the result of executing a TPM2_Certify
	command over a TPM key.  See [reftobeprovided] for more details.
      </t>
      <t>
	The data portion of the value field encoded as OCTET STRING is
	the attestationData from the TPM2B_ATTEST produced by the
	TPM. In other words, strip off the TPM2B_ATTEST "size" field
	and place the TPMS_ATTEST encoded structure in the OCTET
	STRING data field.
      </t>
      <t>
	The algId is absent as the signature field contains that
	information.
      </t>
      <t>
	The signature field is an OCTET STRING containing the TPM
	encoded TPMT_SIGNATURE structure.
      </t>
      <t>
	The ancillary field may be absent if no data is provided, or
	if the signing scheme is not Anonymous. In the latter case, it
	may duplicate data already in the TPMS_ATTEST structure. If
	present, this is the buffer field of the TPM2B_DATA structure
	passed to the TPM2_Certify command as the qualifyingData
	argument.
      </t>
      <t>
	An AttestCertChain attribute must be present if this attribute
	is used as part of a certificate signing request. The first
	certificate of that chain should be the TPMT_PUBLIC structure
	representing the key to be attested. If the key
	used to sign the attestation has been previously enrolled as
	an attestation key, then the next certificate of that chain
	should be the certificate containing the attestation key.
      </t>
      <t>
	If the attestation key has NOT been issued a certificate,
	... tbd.  There is a scheme to allow for a two step
	attestation process based on the TPMs endorsement key and a
	user's TPM generated Attestation key that will not require
	multiple round trips.  This requires validating the TPMs built
	in endorsement key pair, the user generated attestation key,
	and finally the user's key they are trying to get enrolled for
	what ever use is specified in the current CSR. 
      </t>
    </section>
    
  </section>
  <section anchor="asn1module" numbered="true" toc="default">
    <name>ASN.1 Module for Attestation</name>
    <sourcecode>
      Place holder for the complete and verified ASN.1
    </sourcecode>
  </section>
  
</back>
</rfc>
