path: root/trust-assertions.xml

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<article>
	<title>Storing Trust Assertions in PKCS#11 Modules</title>

	<articleinfo>
		<releaseinfo>Rough "rougher than burlap underwear" draft</releaseinfo>
		<date>December 2010</date>
		<authorgroup>
			<author>
				<firstname>Stef</firstname>
				<surname>Walter</surname>
				<affiliation>
					<orgname>Collabora Ltd</orgname>
					<address>
						<email>stefw@collabora.co.uk</email>
					</address>
				</affiliation>
			</author>
		</authorgroup>
	</articleinfo>

	<section id="introduction">
		<title>Introduction</title>

		<para>Trust assertions are represent bits of trust information used by an
			application to make trust decisions. For example, trust assertions can
			represent certificate authority anchors, pinned certificate exceptions, or
			revocation lists. Trust assertions do not represent the trust decision
			itself. They are merely one factor in the trust decision. However by using
			trust assertions applications (and libraries) can make consistent trust
			decisions and interoperate with one another. This is a building block
			toward a usable crypto experience for the user of such applications.</para>

		<para><ulink url="http://www.cryptsoft.com/pkcs11doc/">PKCS#11</ulink> is a useful
			and widely supported standard for storage and use of keys and certificates.
			It is often used with smart cards.</para>

		<para>This specification outlines how to store and lookup trust assertions via the
			PKCS#11 API. We detail an extension which accomplishes this.</para>

		<para>A word on terminology. We use the word <emphasis>trust</emphasis> quite a bit
			in this document. This is a highly overloaded and subjective term, and its use
			in this specification is unfortunate. An unambiguous term is desirable.
			The author cringes every time the word <emphasis>trust</emphasis> is used.
			The author cringes a lot.</para>

		<para>In this specification we deal only with trust assertions related to certificates.
			In theory, trust assertions can relate to secret keys, and other subjects
			as well. Future versions of this specification may specify trust assertions
			for these other subjects.</para>
	</section>

	<section id="trust-assertions">
		<title>Trust Assertions</title>

		<para>A trust assertion is a generic concept. Each trust assertion describes a level
			of trust in a certain subject for a given purpose. Conceptually each trust
			assertion is a triple containing the following:</para>

		<itemizedlist>
			<listitem><para><link linkend='trust-subject'>Reference to the subject</link></para></listitem>
			<listitem><para><link linkend='trust-purpose'>Purpose</link></para></listitem>
			<listitem><para><link linkend='trust-level'>Level of trust</link></para></listitem>
		</itemizedlist>

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

		<section id='trust-level'>
			<title>Level of Trust</title>

			<para>This describes the level of trust represented by the trust assertion.</para>

			<variablelist>
				<varlistentry>
					<term>Distrusted</term>
					<listitem><para>The trust assertion marks the subject as explicitly
						distrusted. This overrides other trust.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term>Trusted</term>
					<listitem><para>The trust assertion marks the subject as explicitly
						trusted.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term>Anchor</term>
					<listitem><para>The trust assertion marks the subject as trusted to
						confer its trust (eg: via signatures) on other subjects
						(eg: via a certificate chain).</para></listitem>
				</varlistentry>
			</variablelist>

			<para>We can call trust assertions which establish trust <emphasis>positive trust
				assertions</emphasis>. In essence these trust assertions build up trust in
				a subject. These have a level of trust of <emphasis>trusted</emphasis>
				or <emphasis>anchor</emphasis>. Examples of this kind of trust assertion
				are certificate authority trust anchors.</para>

			<para>Trust assertions that falsify trust can be called <emphasis>negative trust
				assertions</emphasis>. These trust assertions tear down trust in a subject. They
				assume the subject is already trusted, and want to revoke or falsify
				that trust. These have a level of trust of <emphasis>distrusted</emphasis>.
				Examples of this kind of trust assertion are certificate revocation lists.</para>

			<para>Negative trust assertions always override positive trust assertions.</para>
		</section>

		<section id='trust-purpose'>
			<title>Purpose</title>

			<para>A trust assertion always refers to a specific purpose or usage. This is
				the thing that the subject is trusted to do. For example a certificate
				may be trusted for purposes like: email, code signing, or authenticating
				a remote host.</para>

			<para>In addition, the purpose can contain a peer, which further narrows what the
				subject is trusted to do. It is then only trusted for for the given purpose
				when the given peer is involved. For example the peer might be the host
				name of a server.</para>
		</section>


		<section id='trust-subject'>
			<title>Subject Reference</title>
			<para>Each trust assertion contains a reference to the subject. This is the thing
				that is trusted. In this specification we will deal exclusively with
				X.509 certificates as the subject of trust assertions.</para>
		</section>
	</section>

	<section id="pkcs11-objects">
		<title>PKCS#11 Trust Assertion Objects</title>

		<para>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.</para>

		<para>When represented as PKCS#11 objects, trust assertions become less elegant
			than the reference + purpose + trust-level triple described above. This is done
			because of limitations in the PKCS#11 API and also to minimizing the number
			of PKCS#11 lookups required to use trust assertions.</para>

		<para>There are two ways that a trust assertion refers to a certificate. Certificates
			used in 'positive' trust assertions are referred to by the complete DER encoding
			 of the certificate. Certificates used in 'negative' trust assertions are referred
			to by the DER value of the certificate's issuer field and its serial number.</para>

		<para>Unfortunately, we cannot have a single way to refer to certificates used
			in both positive and negative trust assertions. For example, referring
			to a certificate authority trust anchor by its issuer and serial number
			would be meaningless. And using a full DER value to refer to negative
			trust assertions would preclude uses such as certificate revocation
			lists. Therefore different methods must be used to refer to certificates in
			these different situations. The objects below reflect this.</para>

		<section id="common-attributes">
			<title>Common Trust Assertion Object Attributes</title>

			<para>First we describe the attributes that all trust assertion objects have in
				common. All trust assertions are of the class
				<literal>CKO_X_TRUST_ASSERTION</literal>.</para>

			<para>In addition to the following trust assertion attributes, all the stardard
				PKCS#11 storage object attributes of <literal>CKA_TOKEN</literal>,
				<literal>CKA_PRIVATE</literal>, <literal>CKA_MODIFIABLE</literal> and
				<literal>CKA_LABEL</literal> may be present.</para>

			<table id='assertion-attributes'>
				<title>General trust assertion attributes</title>
				<tgroup cols="3">
					<thead>
						<row>
							<entry>Attribute</entry>
							<entry>Data Type</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry><literal>CKA_CLASS</literal></entry>
							<entry><literal>CK_OBJECT_CLASS</literal></entry>
							<entry><literal>CKO_X_TRUST_ASSERTION</literal></entry>
						</row>
						<row>
							<entry><literal>CKA_X_ASSERTION_TYPE</literal></entry>
							<entry><literal>CK_X_ASSERTION_TYPE</literal></entry>
							<entry>The type of trust assertion. This represents
								the <link linkend='trust-level'>level of trust</link>.
								See the various
								<link linkend='assertion-types'>assertion types</link>.</entry>
						</row>
						<row>
							<entry><literal>CKA_X_PURPOSE</literal></entry>
							<entry><literal>CK_UTF8_CHAR</literal> array</entry>
							<entry>The string representation of
								<link linkend='trust-purpose'>the purpose</link>,
								usually an OID, and often one of the
								<link linkend='defined-purposes'>predefined purposes</link>.</entry>
						</row>
					</tbody>
				</tgroup>
			</table>

			<para>The <literal>CKA_X_PURPOSE</literal> attribute contains a string which represents
				the <link linkend='trust-purpose'>purpose of the trust assertion</link>. These are
				generally OIDs. The following predefined values match those of the
				<ulink url='http://www.ietf.org/rfc/rfc5280.txt'>Extended Key Usage X.509 extension</ulink>.
				Other values may be used when interoperability of the trust assertion between multiple
				applications is not required.</para>

			<para>Applications should ignore trust assertions whose <literal>CKA_X_PURPOSE</literal> attribute
				they do not understand. They should not treat them as negative assertions.</para>

			<table id='defined-purposes'>
				<title>Predefined Purposes</title>
				<tgroup cols="2">
					<thead>
						<row>
							<entry>Value</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry><literal>1.3.6.1.5.5.7.3.1</literal></entry>
							<entry>TLS Server Authentication</entry>
						</row>
						<row>
							<entry><literal>1.3.6.1.5.5.7.3.2</literal></entry>
							<entry>TLS Client Authentication</entry>
						</row>
						<row>
							<entry><literal>1.3.6.1.5.5.7.3.3</literal></entry>
							<entry>Code Signing</entry>
						</row>
						<row>
							<entry><literal>1.3.6.1.5.5.7.3.4</literal></entry>
							<entry>Email Protection</entry>
						</row>
						<row>
							<entry><literal>1.3.6.1.5.5.7.3.8</literal></entry>
							<entry>Time Stamping</entry>
						</row>
					</tbody>
				</tgroup>
			</table>

			<para>Each different type of trust assertion is represented by a different
				<literal>CK_X_ASSERTION_TYPE</literal> value. These represent the
				<link linkend='trust-level'>level of trust</link>. Each type of trust
				assertion has additional attributes and is a distinctly different type
				of PKCS#11 object. The following types are defined.</para>

			<table id='assertion-types'>
				<title>Trust assertion types</title>
				<tgroup cols="2">
					<thead>
						<row>
							<entry>Trust Type</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry><literal>CKT_X_ANCHORED_CERTIFICATE</literal></entry>
							<entry>A positive trust assertion that represents a trust
								anchor which is used as the anchor of a certificate
								chain.</entry>
						</row>
						<row>
							<entry><literal>CKT_X_PINNED_CERTIFICATE</literal></entry>
							<entry>A positive trust assertion that represents an
								explicit trust in a certificate.</entry>
						</row>
						<row>
							<entry><literal>CKT_X_DISTRUSTED_CERTIFICATE</literal></entry>
							<entry>A negative trust assertion that represents an
								explicit distrust in a certificate.</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
		</section>

		<section id="anchored-attributes">
			<title>Anchored Certificate Assertion</title>

			<para>An anchored certificate is a trust assertion which is to be used with a
				certificate authority that has signed other trusted certificates. It
				is to be used as the anchor in a
				<ulink url='http://www.ietf.org/rfc/rfc5280.txt'>certificate chain</ulink>.</para>

			<para>Because it is a positive trust assertion, the certificate is referenced by
				using the entire DER encoding of the certificate.</para>

			<para>In addition to the following attributes, all the
				<link linkend='assertion-attributes'>general trust assertion attributes</link>
				are present on a anchored certificate trust assertion.</para>

			<table>
				<title>Anchored Certificate Assertion Attributes</title>
				<tgroup cols="3">
					<thead>
						<row>
							<entry>Attribute</entry>
							<entry>Data Type</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry><literal>CKA_X_ASSERTION_TYPE</literal></entry>
							<entry><literal>CK_X_ASSERTION_TYPE</literal></entry>
							<entry><literal>CKT_X_CERTIFICATE_TRUST_ANCHOR</literal></entry>
						</row>
						<row>
							<entry><literal>CKA_X_CERTIFICATE_VALUE</literal></entry>
							<entry>Byte array</entry>
							<entry>The DER encoding of the certificate.</entry>
						</row>
					</tbody>
				</tgroup>
			</table>

		</section>

		<section id="pinned-attributes">
			<title>Pinned Certificate Assertion</title>

			<para>A pinned certificate is an endpoint certificate (not an authority) which is
				trusted explicitly. The expectation is that all other trust validation
				is overridden by this pinned trust.</para>

			<para>Because it is a positive trust assertion, the certificate is referenced by
				using the entire DER encoding of the certificate.</para>

			<para>All pinned certificate trust assertions have a designated peer with which
				the pinned certificate assertion is relevant. In the case of the TLS
				authentication purpose, this is the host name of the peer that is being
				communicated with. In the case of the email protection purpose this is the
				email address this certificate is to being used with.</para>

			<para>In addition to the following, all the
				<link linkend='assertion-attributes'>general trust assertion attributes</link>
				are present on a pinned certificate trust assertion.</para>

			<table>
				<title>Pinned Certificate Assertion Attributes</title>
					<tgroup cols="3">
					<thead>
						<row>
							<entry>Attribute</entry>
							<entry>Data Type</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry><literal>CKA_X_ASSERTION_TYPE</literal></entry>
							<entry><literal>CK_X_ASSERTION_TYPE</literal></entry>
							<entry><literal>CKT_X_PINNED_CERTIFICATE</literal></entry>
						</row>
						<row>
							<entry><literal>CKA_X_PEER</literal></entry>
							<entry><literal>CK_UTF8_CHAR</literal> array</entry>
							<entry>The peer part of the purpose.</entry>
						</row>
						<row>
							<entry><literal>CKA_X_CERTIFICATE_VALUE</literal></entry>
							<entry>Byte array</entry>
							<entry>The DER encoding of the certificate.</entry>
						</row>
					</tbody>
				</tgroup>
			</table>

		</section>

		<section id="distrusted-attributes">
			<title>Distrusted Certificate Assertion</title>

			<para>An distrusted certificate is a trust assertion which signifies the explicit
				lack of	trust in a certificate. An example of this is an item in a CRL
				or a certificate explicitly marked as distrusted by a user.</para>

			<para>Because it is a negative trust assertion, the certificate is referenced by
				a using the issuer and serial number of the certificate in question.</para>

			<para>In addition to the following, all the
				<link linkend='assertion-attributes'>general trust assertion attributes</link>
				are present on a distrusted certificate assertion.</para>

			<table>
				<title>Distrusted Certificate Assertion Attributes</title>
				<tgroup cols="3">
					<thead>
						<row>
							<entry>Attribute</entry>
							<entry>Data Type</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry><literal>CKA_X_ASSERTION_TYPE</literal></entry>
							<entry><literal>CK_X_ASSERTION_TYPE</literal></entry>
							<entry><literal>CKT_X_DISTRUSTED_CERTIFICATE</literal></entry>
						</row>
						<row>
							<entry><literal>CKA_ISSUER</literal></entry>
							<entry>Byte array</entry>
							<entry>DER-encoding of the certificate issuer name</entry>
						</row>
						<row>
							<entry><literal>CKA_SERIAL_NUMBER</literal></entry>
							<entry>Byte array</entry>
							<entry>DER-encoding of the certificate serial number</entry>
						</row>
					</tbody>
				</tgroup>
			</table>

		</section>
	</section>

	<section id="operations">
		<title>Operations</title>

		<section id="operation-build-chain">
			<title>Building a Certificate Chain</title>

			<para>During TLS or other certificate verification operations, a
				<ulink url='http://www.ietf.org/rfc/rfc5280.txt'>certificate chain</ulink>
				must be built. The certificate chain starts with a endpoint certificate for
				the peer, and usually ends with a certificate explicitly trusted in some
				way, such as a certificate authority trust anchor. The certificates in the
				chain are each in turn signed by the next certificate in the chain.</para>

			<para>Conceptually building a certificate chain has two parts 1) building the chain
				based on positive trust assertions, and 2) allowing then allowing falsification
				of all or part of the chain based on negative trust assertions.</para>

			<para>Here is how this is accomplished. For interoperability it is important to perform
				the following lookups using the attributes described:</para>

			<orderedlist>
				<listitem>

					<para>Check if the endpoint certificate has a pinned certificate
						for the given purpose and peer. If a pinned certificate is found
						then the certificate chain consists of one certificate and is
						considered valid at this point.</para>

					<para>To check for pinned certificates, perform a
						<literal>C_FindObject</literal> operation with the following
						attributes:</para>

        <programlisting>
	CKA_CLASS: CKO_X_ASSERTION_TYPE
	CKA_X_ASSERTION_TYPE: CKT_X_PINNED_CERTIFICATE
	CKA_X_CERTIFICATE_VALUE: <emphasis>DER encoding of certificate</emphasis>
	CKA_X_PURPOSE: <emphasis>purpose string</emphasis>
	CKA_X_PEER: <emphasis>peer string</emphasis>
	</programlisting>
					</listitem>

				<listitem>
					<para>Use PKCS#11 to find all the certificates necessary for the
						certificate chain. Often a peer will not send a complete chain
						and only send its own certificate. Build up the chain using the
						certificate issuer of each certificate to search for issuing
						certificates. This is done until a self-signed issuing certificate
						is found, or an issuing certificate is not found.</para>

					<para>To lookup issuing certificates, perform a
						<literal>C_FindObject</literal> operation with the following
						attributes:</para>

        <programlisting>
	CKA_CLASS: CKO_CERTIFICATE
	CKA_CERTIFICATE_TYPE: CKC_X_509
	CKA_SUBJECT: <emphasis>Der encoding of subject of issued certificate</emphasis>
	</programlisting>

				</listitem>

				<listitem>
					<para>Check for an anchored certificate assertion for each certificate
						in the chain starting from the certificate that signed the
						endpoint certificate. The endpoint certificate is not considered
						for a possible anchor. When a anchor is found then the certificate
						chain is truncated at that point. Certificates past the trust anchor
						are ignored.</para>

					<para>To check for anchored certificates, perform a
						<literal>C_FindObject</literal> operation with the following
						attributes:</para>

        <programlisting>
	CKA_CLASS: CKO_X_ASSERTION_TYPE
	CKA_X_ASSERTION_TYPE: CKT_X_ANCHORED_CERTIFICATE
	CKA_X_CERTIFICATE_VALUE: <emphasis>DER encoding of certificate</emphasis>
	CKA_X_PURPOSE: <emphasis>purpose string</emphasis>
	</programlisting>
				</listitem>

				<listitem>
					<para>Allow falsification for each certificate in the resulting
						certificate chain by checking whether each certificate has
						an distrusted certificate assertion. If at any point an distrusted
						assertion is found (eg: a certificate listed on a certificate
						revocation list) then the certificate chain is considered invalid.</para>

					<para>To check for distrusted certificates, perform a
						<literal>C_FindObject</literal> operation with the following
						attributes:</para>

        <programlisting>
	CKA_CLASS: CKO_X_ASSERTION_TYPE
	CKA_X_ASSERTION_TYPE: CKT_X_DISTRUSTED_CERTIFICATE
	CKA_X_CERTIFICATE_VALUE: <emphasis>DER encoding of certificate</emphasis>
	CKA_X_PURPOSE: <emphasis>purpose string</emphasis>
	</programlisting>
				</listitem>

				<listitem>
					<para>Pass the resulting certificate chain to the crypto library for
						further validation of signers, identity matching, etc.</para>
				</listitem>
			</orderedlist>
		</section>
	</section>

	<section id="justifications">
		<title>Justifications</title>

		<para>Some answers to why this spec was designed as it is.</para>

		<section id="justification-why-no-hash">
			<title>Why use a complete certificate DER encoding for positive trust assertions?</title>
			<para>Conceivably we could use a hash of the certificate instead of the
				<literal>CKA_X_CERTIFICATE_VALUE</literal>.
				<ulink url='https://developer.mozilla.org/en/NSS/PKCS_%2311_Netscape_Trust'>
				NSS Trust Objects</ulink> use hashes in this way.</para>

			<para>In the current climate where many hash algorithms are broken in various ways
				it seems prudent to avoid the hashing of the certificate and just use the
				complete certificate DER encoding for lookups. This allows a robust standard
				that is not dependent on the long term viability of a specific hash algorithm.</para>
		</section>

		<section id="justification-why-issuer-serial">
			<title>Why refer to certificates in negative trust assertions by issuer and serial number?</title>

			<para><ulink url='http://www.ietf.org/rfc/rfc5280.txt'>Certificate revocation lists</ulink>
				do not generally contain the full value of the certificate or a hash thereof.
				They simply contain serial numbers, which when combined with the issuer of the
				certificate revocation list, are meant to uniquely identify a given certificate.</para>

			<para>In order to support CRLs exposed as distrusted certificate assertions (which is one
				of the design goals of this specification) we must limit ourselves to this method
				of referencing certificates in negative trust assertions.</para>
		</section>

		<section id="justification-why-not-nss">
			<title>Why not use NSS Trust Objects?</title>

			<para>NSS contains an implementation of storing trust information via PKCS#11.
				This has not been completely documented, but an
				<ulink url='https://developer.mozilla.org/en/NSS/PKCS_%2311_Netscape_Trust'>
				overview is available</ulink>. This method of storing trust information
				has been in use by NSS for many years.</para>

			<para>However the NSS method is starting to show its age. After study of NSS's
				method of storing trust information, and discussion with others, the
				following inherent problems are apparent.</para>

			<itemizedlist>
				<listitem><para>Mandates the use SHA1 and MD5 hashes both of which are
					cryptographically broken in various way. Neither
					<ulink url='http://tools.ietf.org/html/draft-turner-md5-seccon-update-07'>
					MD5</ulink> or
					<ulink url='https://tools.ietf.org/html/draft-turner-sha0-sha1-seccon-00'>
					SHA1</ulink> are currently recommended for use in specifications.</para></listitem>

				<listitem><para>Only supports a distinct set of purposes, new purposes are
					not supported.</para></listitem>

				<listitem><para>Does not support a storage of a peer along with the purpose, which
					precludes storage of pinned certificate assertions.</para></listitem>

				<listitem><para>Objects represent a number of trust assertions stored in a single PKCS#11
					object leading to more complex lookup and modification operations.</para></listitem>
			</itemizedlist>
		</section>

		<section id="justification-why-not-uris">
			<title>Why not use PKCS#11 URIs?</title>

			<para>The <ulink url='http://tools.ietf.org/html/draft-pechanec-pkcs11uri-03'>PKCS#11 URI Scheme</ulink>
				is a useful draft standard which can be used to identify objects stored on a PKCS#11
				token. It has been suggested that a list of PKCS#11 URIs could be used to identify
				which certificates are useful as certificate anchors.</para>

			<para>As outlined above, positive trust assertions build up trust. Certificates used in positive
				trust assertions must be identified by the certificate value or a hash thereof. PKCS#11
				URIs do not have the ability to uniquely identify a certificate by its DER encoding or a
				hash thereof.</para>
		</section>

		<section id="justification-why-cka-trusted">
			<title>How is this related to CKA_TRUSTED?</title>

			<para>Later versions of the PKCS#11 spec contain an attribute called <literal>CKA_TRUSTED</literal>.
				This attribute can be set on public keys, secret keys, and certificates by an application
				as a flag indicating trust in some form. <literal>CKA_TRUSTED</literal> can be used as a
				crude form of marking which certificates can be used as a certificate authority trust
				anchor.</para>

			<para>We see this specification as complementary to <literal>CKA_TRUSTED</literal>. This specification
				defines a fine grained method for representing all sorts of positive and negative trust
				assertions, and not just anchored certificates.</para>
		</section>

	</section>

</article>