path: root/specs/draft-pkcs11-trust-assertions.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>

<rfc category="bcp" docName="draft-walter-pkcs11-trust" ipr="full3978">

	<front>
		<title abbrev="PKCS#11 Trust Assertions">Storing Trust Assertions in PKCS#11 Modules</title>

		<author fullname="Stef Walter" initials="S.W." role="editor" surname="Walter">
			<organization>GNOME</organization>

			<address>
				<!--<postal>
					<street></street>
					<city>Karlsruhe</city>
					<region></region>
					<code></code>
					<country>Germany</country>
				</postal>-->

				<phone>+1 505 926 1827</phone>
				<email>stefw@gnome.org</email>

			</address>
		</author>

		<date month="September" year="2010" />
		
		<area>General</area>

		<workgroup>Internet Engineering Task Force</workgroup>

		<keyword>security</keyword>
		<keyword>pkcs11</keyword>
		<keyword>trust</keyword>
		<keyword>x509</keyword>
		<keyword>certificate</keyword>
		<keyword>pki</keyword>

		<abstract>
			<t>PKCS#11 is a standard that defines ways to store certificates, keys
			and perform crypto operations. It does not specify a way to store trust
			assertions.</t>

			<t>Trust assertions are used to assign an explicit level of trust to a
			certificate. Examples of trust assertions are certificate authority
			root certificates, certificate revocation lists, and certificate
			trust exceptions.</t>

			<t>This document outlines a way to store trust assertions with PKCS#11.
			This is not a new design, but documentation of the method already in use
			by libraries such as NSS.</t>
		</abstract>
	</front>

	<middle>
		<section title="Introduction">
			<t>PKCS#11 is a useful and widely supported standard for storage and use
			of keys and certificates. It is often used with smart cards.</t>

			<section title="PKCS#11 Primer">
				<t>Xxxx</t>
			</section>

			<section title="Terminology">
				<t>Xxxxx</t>

				<t>Xxxx 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 RFC 2119.</t>
			</section>

		</section>

		<section title="Trust Assertions">
			<t>A trust assertion describes a level of trust in an object for a given usage
			or purpose. Conceptually each trust assertion is a triple containing:</t>

			<t><list style="symbols">
				<t>Certificate Reference</t>

				<t>Usage or Purpose</t>

				<t>Level of Trust</t>
			</list></t>

			<t>We examine each of these parts of the triple in further detail below.</t>

			<section title="Level of Trust">
				<t>A trust assertion ultimately denotes a level of trust. These are:
				<list style="symbols">
					<t>Untrusted: The certificate is explicitly untrusted.</t>

					<t>Unknown: The trust is not known and should be determined elsewhere.</t>

					<t>Trusted: The certificate itself is explicitly trusted.</t>

					<t>Trusted Delegator: The certificate is trusted as a certificate
					authority trust root. Trust is confers to certificates that this
					certificate has signed, or signed certificates have signed, and so on.</t>
				</list></t>
			</section>

			<section title="Usage or Purpose">
				<t>A trust assertion always refers to a specific purpose or usage.
				A certificate may be trusted for purposes like: email, code signing,
				authenticating a server.</t>
			</section>

			<section title="Certificate Reference">
				<t>Each trust assertion contains a reference to a certificate.</t>

				<t>There are two ways to refer to a certificate depending on whether
				that certificate is self-signed (like a certificate authority) or signed
				by another trusted certificate.</t>

				<t>Self-signed certificates are referred to by their 
				complete hash of the DER value of the certificate.</t>

				<t>Certificates signed by another certificate are referred to by
				the DER value of the issuer field, and the serial number.</t>

				<t>Referring to a self-signed certificate by its issuer and serial number
				is meaningless.</t>

				<t>Referring to a signed certificate by its hash, would preclude uses
				such as certificate relocation lists, which do not contain certificates
				or enough information to generate a hash.</t>

				<t>Therefore different methods MUST be used to refer to self-signed
				and issuer-signed certificates.</t>
			</section>
		</section>

		<section title="PKCS#11 Trust Assertion Objects">

			<t>Trust assertions are stored as objects on a PKCS#11 token. Although these are
			specific to a certificate, they do not need to be stored on the same token as
			the certificate. Trust assertions objects are of the class CKO_NETSCAPE_TRUST
			and have the following attributes.</t>

			<texttable anchor="trust_attributes" title="Trust Object Attributes" style="all">
				<preamble>Trust object attributes.</preamble>
	
				<ttcol align="left">Attribute</ttcol>
				<ttcol align="left">Type</ttcol>
				<ttcol align="left">Description</ttcol>
	
				<c>CKA_CLASS</c>
				<c>CK_OBJECT_CLASS</c>
				<c>CKO_NETSCAPE_TRUST</c>
	
				<c>CKA_ISSUER</c>
				<c>Byte array</c>
				<c>DER-encoding of the certificate issuer name</c>
	
				<c>CKA_SUBJECT</c>
				<c>Byte array</c>
				<c>DER-encoding of the certificate subject name. Optional, default empty</c>

				<c>CKA_SERIAL_NUMBER</c>
				<c>Byte array</c>
				<c>DER-encoding of the certificate serial number</c>

				<c>CKA_CERT_SHA1_HASH</c>
				<c>Byte array</c>
				<c>SHA1 hash of the the DER-encoding of certificate. Required for
				self-signed certificates.</c>

				<c>CKA_CERT_MD5_HASH</c>
				<c>Byte array</c>
				<c>MD5 hash of the the DER-encoding of certificate. Required for
				self-signed certificates.</c>

				<c>CKA_TRUST_SERVER_AUTH</c>
				<c>CK_TRUST</c>
				<c>Level of trust for server authentication extended usage.</c>

				<c>CKA_TRUST_CLIENT_AUTH</c>
				<c>CK_TRUST</c>
				<c>Level of trust for client authentication extended usage.</c>
	
				<c>CKA_TRUST_CODE_SIGNING</c>
				<c>CK_TRUST</c>
				<c>Level of trust for code signing extended usage.</c>
	
				<c>CKA_TRUST_EMAIL_PROTECTION</c>
				<c>CK_TRUST</c>
				<c>Level of trust for email protection extended usage.</c>
	
				<c>CKA_TRUST_IPSEC_END_SYSTEM</c>
				<c>CK_TRUST</c>
				<c>Level of trust for IPSEC end system extended usage.</c>
	
				<c>CKA_TRUST_IPSEC_TUNNEL</c>
				<c>CK_TRUST</c>
				<c>Level of trust for IPSEC tunnel extended usage.</c>

				<c>CKA_TRUST_IPSEC_USER</c>
				<c>CK_TRUST</c>
				<c>Level of trust for IPSEC user extended usage.</c>
	
				<c>CKA_TRUST_TIME_STAMPING</c>
				<c>CK_TRUST</c>
				<c>Level of trust for IPSEC time stamping extended usage.</c>

				<c>CKA_TRUST_DIGITAL_SIGNATURE</c>
				<c>CK_TRUST</c>
				<c>Level of trust for digital signature key usage.</c>

				<c>CKA_TRUST_NON_REPUDIATION</c>
				<c>CK_TRUST</c>
				<c>Level of trust for non-repudiation key usage.</c>

				<c>CKA_TRUST_KEY_ENCIPHERMENT</c>
				<c>CK_TRUST</c>
				<c>Level of trust for key-encipherment key usage.</c>

				<c>CKA_TRUST_DATA_ENCIPHERMENT</c>
				<c>CK_TRUST</c>
				<c>Level of trust for data-encipherment key usage.</c>

				<c>CKA_TRUST_KEY_AGREEMENT</c>
				<c>CK_TRUST</c>
				<c>Level of trust for key-agreement key usage.</c>

				<c>CKA_TRUST_KEY_CERT_SIGN</c>
				<c>CK_TRUST</c>
				<c>Level of trust for certificate signing key usage.</c>

				<c>CKA_TRUST_KEY_CRL_SIGN</c>
				<c>CK_TRUST</c>
				<c>Level of trust for crl signing key usage.</c>

				<postamble>Xxxx: Possible additional attributes: CKA_TRUST_TYPE
				(CKT_CERTIFICATE_SELF_SIGNED, CKT_CERTIFICATE_SIGNED),
				CKA_CERT_SHA256_HASH</postamble>
			</texttable>

			<texttable anchor="trust_values" title="CK_TRUST values">
				<preamble>CK_TRUST represenst a level of trust.</preamble>
	
				<ttcol align="left">Value</ttcol>
				<ttcol align="left">Description</ttcol>
	
				<c>CKT_UNTRUSTED</c>
				<c>Explicitly untrusted.</c>
	
				<c>CKT_UNKNOWN</c>
				<c>Trust is unknown and should be determined elsewhere.</c>
	
				<c>CKT_TRUSTED</c>
				<c>Explicitly trusts the certificate in the assertion.</c>

				<c>CKT_TRUSTED_DELEGATOR</c>
				<c>Trusts the certificate as a certificate authority.</c>
			</texttable>
		</section>

		<section title="Operations">
			<section title="Checking Trust Assertions">
				<t>Trust assertions are checked using a PKCS#11 C_FindObjects operation.</t>

				<t>Because trust is involved and presence/lack of results is important, this
				operation MUST be done with a specific set of lookup attributes. The
				attributes used differ depending on whether the certificate is self-signed
				or is signed by an issuer.</t>

				<t>Checking of trust assertions is always done for a specific purpose.</t>

				<section title="Checking a Root Certificate Authority">
					<t>A C_FindObjects operation is done using the following attributes.</t>

					<texttable>
						<ttcol align="left">Attribute</ttcol>
						<ttcol align="left">Value</ttcol>
	
						<c>CKA_CLASS</c>
						<c>CKO_NETSCAPE_TRUST</c>
	
						<c>CKA_CERT_SHA1_HASH</c>
						<c>20 byte value of hash of certificate.</c>

						<c>Purpose attribute</c>
						<c>CKT_TRUSTED_DELEGATOR</c>
					</texttable>
				</section>

				<section title="Checking a Self-Signed Certificate">
					<t>A C_FindObjects operation is done using the following attributes.</t>

					<texttable>
						<ttcol align="left">Attribute</ttcol>
						<ttcol align="left">Value</ttcol>
	
						<c>CKA_CLASS</c>
						<c>CKO_NETSCAPE_TRUST</c>
	
						<c>CKA_CERT_SHA1_HASH</c>
						<c>20 byte value of hash of certificate.</c>

						<c>Purpose attribute</c>
						<c>CKT_TRUSTED</c>
					</texttable>
				</section>

				<section title="Checking an otherwise Trusted Certificate">
					<t>A C_FindObjects operation is done using the following attributes.</t>

					<texttable>
						<ttcol align="left">Attribute</ttcol>
						<ttcol align="left">Value</ttcol>
	
						<c>CKA_CLASS</c>
						<c>CKO_NETSCAPE_TRUST</c>

						<c>CKA_ISSUER</c>
						<c>DER encoding of certificate issuer.</c>

						<c>CKA_SERIAL_NUMBER</c>
						<c>DER encoding of certificate serial number.</c>

						<c>Purpose attribute</c>
						<c>CKT_UNTRUSTED</c>
					</texttable>
				</section>

			</section>

			<section title="Storing Trust Assertions">
				<t>Xxxx</t>
			</section>

			<section title="Reading Trust Assertions">
				<t>Xxxx</t>
			</section>
		</section>
	
    <section anchor="Acknowledgements" title="Acknowledgements">
	<t>NSS: Who?</t>
    </section>

    <section title="Further Considerations">
	<t>xxxx</t>
    </section>

    <section anchor="Security" title="Security Considerations">
	<t>Xxxx: Use of multiple PKCS#11 modules</t>
	<t>Not using just any module.</t>
    </section>

  </middle>

  <!--  *****BACK MATTER ***** -->

  <back>
    <!-- References split into informative and normative -->

    <!-- There are 2 ways to insert reference entries from the citation libraries:
     1. define an ENTITY at the top, and use "ampersand character"RFC2629; here (as shown)
     2. simply use a PI "less than character"?rfc include="reference.RFC.2119.xml"?> here
        (for I-Ds: include="reference.I-D.narten-iana-considerations-rfc2434bis.xml")

     Both are cited textually in the same manner: by using xref elements.
     If you use the PI option, xml2rfc will, by default, try to find included files in the same
     directory as the including file. You can also define the XML_LIBRARY environment variable
     with a value containing a set of directories to search.  These can be either in the local
     filing system or remote ones accessed by http (http://domain/dir/... ).-->

    <references title="Normative References">
      <reference anchor="min_ref">
        <!-- the following is the minimum to make xml2rfc happy -->

        <front>
          <title>Minimal Reference</title>

          <author initials="authInitials" surname="authSurName">
            <organization></organization>
          </author>

          <date year="2006" />
        </front>
      </reference>
    </references>

    <references title="Informative References">
      <!-- A reference written by by an organization not a person. -->

      <reference anchor="DOMINATION"
                 target="http://www.example.com/dominator.html">
        <front>
          <title>Ultimate Plan for Taking Over the World</title>

          <author>
            <organization>Mad Dominators, Inc.</organization>
          </author>

          <date year="1984" />
        </front>
      </reference>
    </references>

    <section anchor="app-additional" title="Additional Stuff">
      <t>This becomes an Appendix.</t>
    </section>
  </back>
</rfc>