Split the document into several articles

 * This simplifies context a bit and makes things easier to understand.
 * At the same time use the theme 'storing' instead of 'sharing, again
   for clarity on the scope.

8 files changed, 429 insertions, 350 deletions

diff --git a/.gitignore b/.gitignore
index 6d6e63c..ef9979a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,5 @@
 junk
 html
-specs/*.html
+specs/storing-trust
 .project
 .cproject
diff --git a/Makefile b/Makefile
index a08f175..111aa35 100644
--- a/Makefile
+++ b/Makefile
@@ -14,7 +14,7 @@ upload: all
 	rsync -Hvax --exclude doc --exclude releases \
 		html/./* anarchy.freedesktop.org:/srv/p11-glue.freedesktop.org/www/./
 	rsync -v --progress \
-		specs/sharing-trust-policy.html \
-		anarchy.freedesktop.org:/srv/p11-glue.freedesktop.org/www/doc/sharing-trust-policy/index.html
+		specs/storing-trust/./ \
+		anarchy.freedesktop.org:/srv/p11-glue.freedesktop.org/www/doc/sharing-trust-policy/./
 
 .PHONY: html specs
diff --git a/specs/Makefile b/specs/Makefile
index 346df90..c063696 100644
--- a/specs/Makefile
+++ b/specs/Makefile
@@ -1,7 +1,22 @@
-all: html/index.html
+NULL =
 
-html/index.html: docbook-params.xsl sharing-trust-anchors.xml Makefile
-	xmlto -vv -m docbook-params.xsl html-nochunks sharing-trust-anchors.xml
+STORING_TRUST_FILES = \
+	storing-trust-basics.xml \
+	storing-trust-existing.xml \
+	storing-trust-pkcs11.xml \
+	storing-trust-policy.xml \
+	$(NULL)
 
--include Makefile.local
+STORING_TRUST_DIR = storing-trust
+
+all: $(STORING_TRUST_DIR)/index.html
+
+clean:
+	rm -rf $(STORING_TRUST_DIR)
 
+$(STORING_TRUST_DIR)/index.html: docbook-params.xsl Makefile $(STORING_TRUST_FILES)
+	mkdir -vp $(STORING_TRUST_DIR)/
+	rm -vf $(STORING_TRUST_DIR)/*
+	xmlto -vv -m docbook-params.xsl -o $(STORING_TRUST_DIR) html storing-trust-policy.xml
+
+-include Makefile.local
diff --git a/specs/docbook-params.xsl b/specs/docbook-params.xsl
index 58e50e5..7690bc2 100644
--- a/specs/docbook-params.xsl
+++ b/specs/docbook-params.xsl
@@ -21,17 +21,19 @@
     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 -->
 
-<!--	<xsl:param name="generate.toc">
+	<xsl:param name="generate.toc">
 		book     toc
 		part     nop
 		chapter  toc
-		sect1    toc
-		sect2    toc
-		sect3    toc
-	</xsl:param>-->
+		article  toc
+	</xsl:param>
+
 	<xsl:param name="html.stylesheet">style.css</xsl:param>
 	<xsl:param name="refentry.generate.name">0</xsl:param>
 	<xsl:param name="refentry.generate.title">1</xsl:param>
 	<xsl:param name="section.autolabel">1</xsl:param>
-
+	<xsl:param name="chunk.section.depth" select="0"></xsl:param>
+	<xsl:param name="tox.max.depth" select="0"></xsl:param>
+	<xsl:param name="toc.section.depth" select="1"></xsl:param>
+	<xsl:param name="use.id.as.filename" select="1"></xsl:param>
 </xsl:stylesheet>
diff --git a/specs/sharing-trust-anchors.xml b/specs/storing-trust-basics.xml
index 8751e26..674e93b 100644
--- a/specs/sharing-trust-anchors.xml
+++ b/specs/storing-trust-basics.xml
@@ -1,8 +1,8 @@
 <?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>Sharing Trust Anchors and Blacklists aka. Stapled Certificate Extensions</title>
+<article id="storing-trust-basics">
+<title>Storing Trust Anchors and Blacklists</title>
 
 <articleinfo>
 	<releaseinfo>Take two draft</releaseinfo>
@@ -70,7 +70,7 @@
 			the scope of this document. This document does not conflict with such a
 			theoretical effort.</para>
 
-		<para>This document attempts to represent basic trust policy information for X.509
+		<para>This document attempts to represent basic local trust policy information for X.509
 			certificate validation. It does not attempt to tackle the theoretical
 			problem of representing all possible forms of digital trust. There are
 			many possible inputs to certificate validation which are not represented.
@@ -165,282 +165,6 @@
 
 </sect1>
 
-<sect1 id="existing">
-	<title>Existing Representations of Trust Policy</title>
-
-	<para>Obviously if a comprehensive, future-proof and realistic standard
-		representation of out-of-band trust policy exists, we should not define a
-		new representation for Linux. Instead we should gather around it. So let's
-		examine	the various representations in use, and why they are insufficient
-		to provide such a comprehensive standard.</para>
-
-	<sect2 id="nss-trust-objects">
-		<title>NSS Trust Objects</title>
-
-		<para>Internally NSS represents out-of-band trust policy using PKCS#11
-		trust objects. These are not well documented
-			<footnote><para>Although one can see them in the NSS source code
-				<ulink url="http://mxr.mozilla.org/seamonkey/source//security/nss/lib/ckfw/builtins/certdata.txt?raw=1">certdata.txt</ulink> file in all their glory.</para></footnote>
-		so an attempt will be made to describe them here.</para>
-
-		<para>Each NSS trust object contains the following attributes
-			<footnote><para>In addition to standard PKCS#11 object attributes</para></footnote>
-			used to find the the trust object that applies to a given X.509
-			certificate:</para>
-
-		<variablelist>
-		<varlistentry>
-			<term>CKA_CLASS</term>
-			<listitem><para>CKO_NETSCAPE_TRUST.</para></listitem>
-		</varlistentry>
-		<varlistentry>
-			<term>CKA_CERT_SHA1_HASH</term>
-			<listitem><para>A SHA1 hash of the DER encoded X.509
-				certificate to which this trust object's policy
-				applies.</para></listitem>
-		</varlistentry>
-		<varlistentry>
-			<term>CKA_CERT_MD5_HASH</term>
-			<listitem><para>An MD5 hash of the DER encoded X.509
-				certificate to which this trust object's policy
-				applies.</para></listitem>
-		</varlistentry>
-		<varlistentry>
-			<term>CKA_ISSUER</term>
-			<listitem><para>The DER encoding of the issuer of the
-				X.509 certificate to which trust object's policy
-				applies.</para></listitem>
-		</varlistentry>
-		<varlistentry>
-			<term>CKA_SUBJECT</term>
-			<listitem><para>The DER encoding of the subject of the
-				X.509 certificate to which trust object's policy
-				applies.</para></listitem>
-		</varlistentry>
-		<varlistentry>
-			<term>CKA_SERIAL_NUMBER</term>
-			<listitem><para>The DER encoding of the serial number of the
-				X.509 certificate to which trust object's policy
-				applies.</para></listitem>
-		</varlistentry>
-		</variablelist>
-			<para>The NSS trust object then contains the following usage attributes.
-			Together these roughly represent the KeyUsage and ExtendedKeyUsage
-			certificate extensions, as out-of-band trust policy. The names should be
-			self explanatory for readers familiar with those certifiacte
-			extensions.</para>
-			<itemizedlist>
-		<listitem><para>CKA_TRUST_DIGITAL_SIGNATURE</para></listitem>
-		<listitem><para>CKA_TRUST_NON_REPUDIATION</para></listitem>
-		<listitem><para>CKA_TRUST_KEY_ENCIPHERMENT</para></listitem>
-		<listitem><para>CKA_TRUST_DATA_ENCIPHERMENT</para></listitem>
-		<listitem><para>CKA_TRUST_KEY_AGREEMENT</para></listitem>
-		<listitem><para>CKA_TRUST_KEY_CERT_SIGN</para></listitem>
-		<listitem><para>CKA_TRUST_CRL_SIGN</para></listitem>
-		<listitem><para>CKA_TRUST_SERVER_AUTH</para></listitem>
-		<listitem><para>CKA_TRUST_CLIENT_AUTH</para></listitem>
-		<listitem><para>CKA_TRUST_CODE_SIGNING</para></listitem>
-		<listitem><para>CKA_TRUST_EMAIL_PROTECTION</para></listitem>
-		<listitem><para>CKA_TRUST_IPSEC_END_SYSTEM</para></listitem>
-		<listitem><para>CKA_TRUST_IPSEC_TUNNEL</para></listitem>
-		<listitem><para>CKA_TRUST_IPSEC_USER</para></listitem>
-		<listitem><para>CKA_TRUST_TIME_STAMPING</para></listitem>
-		</itemizedlist>
-		
-		<para>The above usage attributes each can contain a trust setting, one of the
-			following:</para>
-
-		<variablelist>
-		<varlistentry>
-			<term>CKT_NETSCAPE_TRUSTED</term>
-			<listitem><para>The certificate is trusted for this
-				usage.</para></listitem>
-		</varlistentry>
-		<varlistentry>
-			<term>CKT_NETSCAPE_TRUSTED_DELEGATOR</term>
-			<listitem><para>The certificate is trusted as a certificate
-					authority for this usage.</para></listitem>
-		</varlistentry>
-		<varlistentry>
-			<term>CKT_NETSCAPE_UNTRUSTED</term>
-			<listitem><para>The certificate is explicitly distrusted for
-				this usage.</para></listitem>
-		</varlistentry>
-		<varlistentry>
-			<term>CKT_NETSCAPE_MUST_VERIFY</term>
-			<listitem><para>TODO: Unclear what this means.</para></listitem>
-		</varlistentry>
-		<varlistentry>
-			<term>CKT_NETSCAPE_TRUST_UNKNOWN</term>
-			<listitem><para>The certificate trust is unknown for this usage
-				and should come from another source.</para></listitem>
-		</varlistentry>
-		</variablelist>
-
-		<sect3 id="nss-trust-problems">
-			<title>Deficiencies</title>
-			<para>NSS trust objects have been around for nearly two decades. They may
-				have been sufficient in the past but are showing their age.</para>
-
-			<para>These trust objects do not seem to be designed as a comprehensive
-				representation of out-of-band trust policy. They are insufficient
-				in the following ways:</para>
-
-			<itemizedlist>
-			<listitem><para>Mandates the use SHA1 and MD5 hashes both of which are
-				cryptographically broken in various ways
-					<footnote><para>Neither
-						<ulink url='http://tools.ietf.org/html/draft-turner-md5-seccon-update-07'>MD5</ulink>
-						nor <ulink url='https://tools.ietf.org/html/draft-turner-sha0-sha1-seccon-00'>SHA1</ulink>
-						are currently recommended for use in specifications.</para></footnote>
-				.</para></listitem>
-			<listitem><para>Trust objects only support trust policy related to
-				the KeyUsage, ExtendedKeyUsage and parts of the BasicConstraints
-				certificate extensions.</para></listitem>
-			<listitem><para>Even though the ExtendedKeyUsage certificate extension
-				can support arbitrary usages, the set of usages represented by
-				these trust objects is limited to those defined above. Trust
-				policy for additional usages is awkward to add.</para></listitem>
-			<listitem><para>Blacklisting is done by marking a certificate as untrusted
-				for specific usages. This works in practice but does not correctly
-				model the reality of having a certificate blacklisted completely
-				and for any usage.</para></listitem>
-			<listitem><para>Trust objects are a PKCS#11 specific. While PKCS#11 is one
-				acceptable object model for representing out-of-band trust policy,
-				for a standard representation it cannot be the only one.</para></listitem>
-			</itemizedlist>
-		</sect3>
-	</sect2>
-
-	<sect2 id="openssl-trusted">
-		<title>OpenSSL Trusted Certificates</title>
-		<para>OpenSSL contains a representation of out-of-band trust policy in its 
-			<emphasis>TRUSTED CERTIFICATE</emphasis> PEM blocks aka. CertAux.
-			Files containing this information can be manipulated using 
-			its <command>openssl x509</command> tool.</para>
-
-		<para>It appears that this format is undocumented, so an attempt will be made
-			to document it here.</para>
-
-		<para>PEM files contain a header and footer containing the words
-			<emphasis>TRUSTED CERTIFICATE</emphasis>. Contained in the PEM
-			data are two DER sequences. The first is an X.509 certificate,
-			and the latter is a structure known internally as <literal>X509_CERT_AUX</literal>.</para>
-
-		<para>The X509_CERT_AUX DER sequence may be defined as follows:
-<programlisting>
-CertAux ::= SEQUENCE {
-      trust      SEQUENCE OF OBJECT IDENTIFIER OPTIONAL,
-      reject     [0] SEQUENCE OF OBJECT IDENTIFIER OPTIONAL,
-      alias      UTF8String OPTIONAL,
-      keyid      OCTET STRING OPTIONAL,
-      other      [1] SEQUENCE OF AlgorithmIdentifier OPTIONAL
-}
-</programlisting>
-		</para>
-
-		<para>The <literal>trust</literal> and <literal>reject</literal> fields
-			contain sequences of ExtendedKeyUsage object identifiers to
-			trust the certificate to be used for, or to reject usage of the
-			certificate for.</para>
-
-		<para>Together <literal>trust</literal> and <literal>reject</literal>
-		fields represent out-of-band trust policy representing the
-			ExtendedKeyUsage certificate extension. The other fields are
-			not related to trust policy.</para>
-
-		<sect3 id="openssl-trusted-problems">
-			<title>Deficiencies</title>
-
-			<para>This representation seems to be designed to solve a specific use
-				case, and not designed as a comprehensive way to represent
-				out-of-band trust policy.  It is insufficient in the following
-				ways:</para>
-
-			<itemizedlist>
-			<listitem><para>This format only supports trust policy related to
-				the ExtendedKeyUsage certificate extension.</para></listitem>
-			<listitem><para>Blacklisting is done by rejecting a certificate for
-				specific usages. This works in practice but does not correctly
-				model the reality of having a certificate blacklisted completely
-				and for any usage.</para></listitem>
-			<listitem><para>This format has OpenSSL implementation specific traits.
-				The PEM contents are the concatenation of two DER structures,
-				and though trivially parseable with the OpenSSL DER parser, it
-				is awkward to parse especially when using other and/or strict
-				DER parsers.</para></listitem>
-			</itemizedlist>
-		</sect3>
-	</sect2>
-
-
-	<sect2 id="trust-assertions">
-		<title>Trust Assertions</title>
-
-		<para>Trust Assertions are the author's previous attempt to solve the problem of sharing
-			trust policy information. Details about this are available online
-				<footnote><para><ulink url="http://p11-glue.freedesktop.org/doc/pkcs11-trust-assertions/">Storing Trust Assertions in PKCS#11 Modules</ulink></para></footnote>.</para>
-
-		<sect3 id="trust-assertion-problems">
-			<title>Deficiencies</title>
-
-			<para>Although claiming to solve the problem of out-of-band trust policy
-				in a general way, closer inspection and application to the
-				real world exposed the following problems:</para>
-
-			<itemizedlist>
-			<listitem><para>This concept only supports trust policy related to
-				the ExtendedKeyUsage certificate extension.</para></listitem>
-			<listitem><para>Blacklisting is done by rejecting a certificate for
-				specific usages. This works in practice but does not correctly
-				model the reality of having a certificate blacklisted completely
-				and for any usage.</para></listitem>
-			<listitem><para>Although they claim to be general trust assertions were
-				thought out as a PKCS#11 specific concept. While PKCS#11 is one
-				acceptable object model for representing out-of-band trust policy,
-				for a standard representation it cannot be the only one.</para></listitem>
-			</itemizedlist>
-
-			<para>In addition claims of extensibility and generality proved hard
-				to implement in the real world, and trust assertions ended up
-				as a far more constrained concept that initially envisioned.</para>
-		</sect3>
-	</sect2>
-
-	<sect2 id="ca-bundles">
-		<title>Certificate Authority Bundles</title>
-
-		<para>A bundle is either a file or directory containing one or more X.509
-			certificate authorities. These have been used to represent the possible
-			anchors on a system. These are widely used today.</para>
-
-		<para>They are usually stored in the OpenSSL PEM format, but may also be
-			seen in the Java Keystore format, and others.</para>
-
-		<sect3 id="ca-bundle-problems">
-			<title>Deficiencies</title>
-
-			<para>Although widely used today certificate authority bundles have
-				the following deficiencies as a standard representation of
-				trust policy:</para>
-
-			<itemizedlist>
-			<listitem><para>There is no standard way to represent out-of-band
-				trust policy in addition to the policy contained in the
-				certificate extensions. In theory one could create different
-				bundles for certificate authorities trusted for different
-				usages and circumstances, but this quickly gets out of
-				hand.</para></listitem>
-			<listitem><para>There is no concept of blacklisting in a such a bundle
-				bundle. One can remove a certificate from the bundle, but if
-				that certificate is used in the middle of a certificate chain
-				rather than as an anchor, the certificate validation will
-				not respect such a removal.</para></listitem>
-			</itemizedlist>
-		</sect3>
-	</sect2>
-</sect1>
-
 <sect1 id="stapled-certificate-extensions">
 	<title>Stapled Certificate Extensions</title>
 
@@ -569,64 +293,6 @@ CertAux ::= SEQUENCE {
 	</sect2>
 </sect1>
 
-<sect1 id="pkcs11">
-	<title>PKCS#11 Extensions for Stapled Certificate Extensions</title>
-
-	<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>Here we outline how to use PKCS#11 as a store of stapled certificate extensions,
-		anchors	and blacklisted certificates. We do this in the stardard PKCS#11
-		object model, by defining a few extra attributes.</para>
-
-	<para>To make it clear which attributes are defined here and which are standard,
-		all new attributes and values are prefixed by the letters <literal>_X_</literal>. Once
-		standardized they would lose this tag.</para>
-
-	<para>The standard CKA_TRUSTED boolean attribute is used on an object with the 
-		class CKO_CERTIFICATE to mark it as an anchor. The presence of a
-		BasicConstraints certificate extension marks it as a certificate
-		authority anchor, capable of anchoring a certificate chain, and not just
-		itself.</para>
-
-	<para>We define a new boolean attribute CKA_X_DISTRUSTED. If this is present and
-		set to CK_TRUE on an object with the class CKO_CERTIFICATE, it marks that
-		certificate as being on the blacklist.</para>
-
-	<para>A new object class is defined of type CKO_X_CERTIFICATE_EXTENSION. Each 
-		object of this class represents one stapled certificate extension. It
-		contains the following (standard and newly defined) attributes (in addition
-		to the standard data storage attributes):</para>
-
-	<variablelist>
-	<varlistentry>
-		<term>CKA_ID</term>
-		<listitem><para>The arbitrary byte string identifier of a
-			CKO_X_CERTIFICATE_EXTENSION must match the CKA_ID of the
-			CKO_CERTIFICATE which it is stapled to. This reflects the
-			customary PKCS#11 method of associating certificates and
-			keys. Must be set.</para></listitem>
-	</varlistentry>
-	<varlistentry>
-		<term>CKA_OBJECT_ID</term>
-		<listitem><para>The DER-encoded OID of the stapled certificate
-			extension. Must be set.</para></listitem>
-	</varlistentry>
-	<varlistentry>
-		<term>CKA_X_CRITICAL</term>
-		<listitem><para>A CK_BBOOL value indicating whether the extension
-			is critical or not. Defaults to CK_FALSE if not set.</para></listitem>
-	</varlistentry>
-	<varlistentry>
-		<term>CKA_VALUE</term>
-		<listitem><para>The DER encoded value of the certificate extension.
-			Must be set.</para></listitem>
-	</varlistentry>
-	</variablelist>
-
-</sect1>
-
 <sect1 id="using">
 	<title>Validation using Stapled Certificate Extensions</title>
 
diff --git a/specs/storing-trust-existing.xml b/specs/storing-trust-existing.xml
new file mode 100644
index 0000000..7394f34
--- /dev/null
+++ b/specs/storing-trust-existing.xml
@@ -0,0 +1,300 @@
+<?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 id="storing-trust-existing">
+<title>Existing Trust Storage Implementations</title>
+
+<articleinfo>
+	<releaseinfo>Take two draft</releaseinfo>
+	<date>June 2013</date>
+	<authorgroup>
+		<author>
+			<firstname>Stef</firstname>
+			<surname>Walter</surname>
+			<affiliation>
+				<orgname>Red Hat Inc.</orgname>
+				<address>
+					<email>stefw@redhat.com</email>
+				</address>
+			</affiliation>
+		</author>
+	</authorgroup>
+</articleinfo>
+
+<sect1 id="existing">
+	<title>Existing Representations of Trust Policy</title>
+
+	<para>Obviously if a comprehensive, future-proof and realistic standard
+		representation of out-of-band trust policy exists, we should not define a
+		new representation for Linux. Instead we should gather around it. So let's
+		examine	the various representations in use, and why they are insufficient
+		to provide such a comprehensive standard.</para>
+
+	<sect2 id="nss-trust-objects">
+		<title>NSS Trust Objects</title>
+
+		<para>Internally NSS represents out-of-band trust policy using PKCS#11
+		trust objects. These are not well documented
+			<footnote><para>Although one can see them in the NSS source code
+				<ulink url="http://mxr.mozilla.org/seamonkey/source//security/nss/lib/ckfw/builtins/certdata.txt?raw=1">certdata.txt</ulink> file in all their glory.</para></footnote>
+		so an attempt will be made to describe them here.</para>
+
+		<para>Each NSS trust object contains the following attributes
+			<footnote><para>In addition to standard PKCS#11 object attributes</para></footnote>
+			used to find the the trust object that applies to a given X.509
+			certificate:</para>
+
+		<variablelist>
+		<varlistentry>
+			<term>CKA_CLASS</term>
+			<listitem><para>CKO_NETSCAPE_TRUST.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term>CKA_CERT_SHA1_HASH</term>
+			<listitem><para>A SHA1 hash of the DER encoded X.509
+				certificate to which this trust object's policy
+				applies.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term>CKA_CERT_MD5_HASH</term>
+			<listitem><para>An MD5 hash of the DER encoded X.509
+				certificate to which this trust object's policy
+				applies.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term>CKA_ISSUER</term>
+			<listitem><para>The DER encoding of the issuer of the
+				X.509 certificate to which trust object's policy
+				applies.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term>CKA_SUBJECT</term>
+			<listitem><para>The DER encoding of the subject of the
+				X.509 certificate to which trust object's policy
+				applies.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term>CKA_SERIAL_NUMBER</term>
+			<listitem><para>The DER encoding of the serial number of the
+				X.509 certificate to which trust object's policy
+				applies.</para></listitem>
+		</varlistentry>
+		</variablelist>
+			<para>The NSS trust object then contains the following usage attributes.
+			Together these roughly represent the KeyUsage and ExtendedKeyUsage
+			certificate extensions, as out-of-band trust policy. The names should be
+			self explanatory for readers familiar with those certifiacte
+			extensions.</para>
+			<itemizedlist>
+		<listitem><para>CKA_TRUST_DIGITAL_SIGNATURE</para></listitem>
+		<listitem><para>CKA_TRUST_NON_REPUDIATION</para></listitem>
+		<listitem><para>CKA_TRUST_KEY_ENCIPHERMENT</para></listitem>
+		<listitem><para>CKA_TRUST_DATA_ENCIPHERMENT</para></listitem>
+		<listitem><para>CKA_TRUST_KEY_AGREEMENT</para></listitem>
+		<listitem><para>CKA_TRUST_KEY_CERT_SIGN</para></listitem>
+		<listitem><para>CKA_TRUST_CRL_SIGN</para></listitem>
+		<listitem><para>CKA_TRUST_SERVER_AUTH</para></listitem>
+		<listitem><para>CKA_TRUST_CLIENT_AUTH</para></listitem>
+		<listitem><para>CKA_TRUST_CODE_SIGNING</para></listitem>
+		<listitem><para>CKA_TRUST_EMAIL_PROTECTION</para></listitem>
+		<listitem><para>CKA_TRUST_IPSEC_END_SYSTEM</para></listitem>
+		<listitem><para>CKA_TRUST_IPSEC_TUNNEL</para></listitem>
+		<listitem><para>CKA_TRUST_IPSEC_USER</para></listitem>
+		<listitem><para>CKA_TRUST_TIME_STAMPING</para></listitem>
+		</itemizedlist>
+		
+		<para>The above usage attributes each can contain a trust setting, one of the
+			following:</para>
+
+		<variablelist>
+		<varlistentry>
+			<term>CKT_NETSCAPE_TRUSTED</term>
+			<listitem><para>The certificate is trusted for this
+				usage.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term>CKT_NETSCAPE_TRUSTED_DELEGATOR</term>
+			<listitem><para>The certificate is trusted as a certificate
+					authority for this usage.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term>CKT_NETSCAPE_UNTRUSTED</term>
+			<listitem><para>The certificate is explicitly distrusted for
+				this usage.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term>CKT_NETSCAPE_MUST_VERIFY</term>
+			<listitem><para>TODO: Unclear what this means.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term>CKT_NETSCAPE_TRUST_UNKNOWN</term>
+			<listitem><para>The certificate trust is unknown for this usage
+				and should come from another source.</para></listitem>
+		</varlistentry>
+		</variablelist>
+
+		<sect3 id="nss-trust-problems">
+			<title>Deficiencies</title>
+			<para>NSS trust objects have been around for nearly two decades. They may
+				have been sufficient in the past but are showing their age.</para>
+
+			<para>These trust objects do not seem to be designed as a comprehensive
+				representation of out-of-band trust policy. They are insufficient
+				in the following ways:</para>
+
+			<itemizedlist>
+			<listitem><para>Mandates the use SHA1 and MD5 hashes both of which are
+				cryptographically broken in various ways
+					<footnote><para>Neither
+						<ulink url='http://tools.ietf.org/html/draft-turner-md5-seccon-update-07'>MD5</ulink>
+						nor <ulink url='https://tools.ietf.org/html/draft-turner-sha0-sha1-seccon-00'>SHA1</ulink>
+						are currently recommended for use in specifications.</para></footnote>
+				.</para></listitem>
+			<listitem><para>Trust objects only support trust policy related to
+				the KeyUsage, ExtendedKeyUsage and parts of the BasicConstraints
+				certificate extensions.</para></listitem>
+			<listitem><para>Even though the ExtendedKeyUsage certificate extension
+				can support arbitrary usages, the set of usages represented by
+				these trust objects is limited to those defined above. Trust
+				policy for additional usages is awkward to add.</para></listitem>
+			<listitem><para>Blacklisting is done by marking a certificate as untrusted
+				for specific usages. This works in practice but does not correctly
+				model the reality of having a certificate blacklisted completely
+				and for any usage.</para></listitem>
+			<listitem><para>Trust objects are a PKCS#11 specific. While PKCS#11 is one
+				acceptable object model for representing out-of-band trust policy,
+				for a standard representation it cannot be the only one.</para></listitem>
+			</itemizedlist>
+		</sect3>
+	</sect2>
+
+	<sect2 id="openssl-trusted">
+		<title>OpenSSL Trusted Certificates</title>
+		<para>OpenSSL contains a representation of out-of-band trust policy in its 
+			<emphasis>TRUSTED CERTIFICATE</emphasis> PEM blocks aka. CertAux.
+			Files containing this information can be manipulated using 
+			its <command>openssl x509</command> tool.</para>
+
+		<para>It appears that this format is undocumented, so an attempt will be made
+			to document it here.</para>
+
+		<para>PEM files contain a header and footer containing the words
+			<emphasis>TRUSTED CERTIFICATE</emphasis>. Contained in the PEM
+			data are two DER sequences. The first is an X.509 certificate,
+			and the latter is a structure known internally as <literal>X509_CERT_AUX</literal>.</para>
+
+		<para>The X509_CERT_AUX DER sequence may be defined as follows:
+<programlisting>
+CertAux ::= SEQUENCE {
+      trust      SEQUENCE OF OBJECT IDENTIFIER OPTIONAL,
+      reject     [0] SEQUENCE OF OBJECT IDENTIFIER OPTIONAL,
+      alias      UTF8String OPTIONAL,
+      keyid      OCTET STRING OPTIONAL,
+      other      [1] SEQUENCE OF AlgorithmIdentifier OPTIONAL
+}
+</programlisting>
+		</para>
+
+		<para>The <literal>trust</literal> and <literal>reject</literal> fields
+			contain sequences of ExtendedKeyUsage object identifiers to
+			trust the certificate to be used for, or to reject usage of the
+			certificate for.</para>
+
+		<para>Together <literal>trust</literal> and <literal>reject</literal>
+		fields represent out-of-band trust policy representing the
+			ExtendedKeyUsage certificate extension. The other fields are
+			not related to trust policy.</para>
+
+		<sect3 id="openssl-trusted-problems">
+			<title>Deficiencies</title>
+
+			<para>This representation seems to be designed to solve a specific use
+				case, and not designed as a comprehensive way to represent
+				out-of-band trust policy.  It is insufficient in the following
+				ways:</para>
+
+			<itemizedlist>
+			<listitem><para>This format only supports trust policy related to
+				the ExtendedKeyUsage certificate extension.</para></listitem>
+			<listitem><para>Blacklisting is done by rejecting a certificate for
+				specific usages. This works in practice but does not correctly
+				model the reality of having a certificate blacklisted completely
+				and for any usage.</para></listitem>
+			<listitem><para>This format has OpenSSL implementation specific traits.
+				The PEM contents are the concatenation of two DER structures,
+				and though trivially parseable with the OpenSSL DER parser, it
+				is awkward to parse especially when using other and/or strict
+				DER parsers.</para></listitem>
+			</itemizedlist>
+		</sect3>
+	</sect2>
+
+
+	<sect2 id="trust-assertions">
+		<title>Trust Assertions</title>
+
+		<para>Trust Assertions are the author's previous attempt to solve the problem of sharing
+			trust policy information. Details about this are available online
+				<footnote><para><ulink url="http://p11-glue.freedesktop.org/doc/pkcs11-trust-assertions/">Storing Trust Assertions in PKCS#11 Modules</ulink></para></footnote>.</para>
+
+		<sect3 id="trust-assertion-problems">
+			<title>Deficiencies</title>
+
+			<para>Although claiming to solve the problem of out-of-band trust policy
+				in a general way, closer inspection and application to the
+				real world exposed the following problems:</para>
+
+			<itemizedlist>
+			<listitem><para>This concept only supports trust policy related to
+				the ExtendedKeyUsage certificate extension.</para></listitem>
+			<listitem><para>Blacklisting is done by rejecting a certificate for
+				specific usages. This works in practice but does not correctly
+				model the reality of having a certificate blacklisted completely
+				and for any usage.</para></listitem>
+			<listitem><para>Although they claim to be general trust assertions were
+				thought out as a PKCS#11 specific concept. While PKCS#11 is one
+				acceptable object model for representing out-of-band trust policy,
+				for a standard representation it cannot be the only one.</para></listitem>
+			</itemizedlist>
+
+			<para>In addition claims of extensibility and generality proved hard
+				to implement in the real world, and trust assertions ended up
+				as a far more constrained concept that initially envisioned.</para>
+		</sect3>
+	</sect2>
+
+	<sect2 id="ca-bundles">
+		<title>Certificate Authority Bundles</title>
+
+		<para>A bundle is either a file or directory containing one or more X.509
+			certificate authorities. These have been used to represent the possible
+			anchors on a system. These are widely used today.</para>
+
+		<para>They are usually stored in the OpenSSL PEM format, but may also be
+			seen in the Java Keystore format, and others.</para>
+
+		<sect3 id="ca-bundle-problems">
+			<title>Deficiencies</title>
+
+			<para>Although widely used today certificate authority bundles have
+				the following deficiencies as a standard representation of
+				trust policy:</para>
+
+			<itemizedlist>
+			<listitem><para>There is no standard way to represent out-of-band
+				trust policy in addition to the policy contained in the
+				certificate extensions. In theory one could create different
+				bundles for certificate authorities trusted for different
+				usages and circumstances, but this quickly gets out of
+				hand.</para></listitem>
+			<listitem><para>There is no concept of blacklisting in a such a bundle
+				bundle. One can remove a certificate from the bundle, but if
+				that certificate is used in the middle of a certificate chain
+				rather than as an anchor, the certificate validation will
+				not respect such a removal.</para></listitem>
+			</itemizedlist>
+		</sect3>
+	</sect2>
+</sect1>
+
+</article>
diff --git a/specs/storing-trust-pkcs11.xml b/specs/storing-trust-pkcs11.xml
new file mode 100644
index 0000000..7d07d4e
--- /dev/null
+++ b/specs/storing-trust-pkcs11.xml
@@ -0,0 +1,82 @@
+<?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 id="storing-trust-pkcs11">
+<title>PKCS#11 Extensions for Storing Trust Information</title>
+
+<articleinfo>
+	<releaseinfo>Take two draft</releaseinfo>
+	<date>June 2013</date>
+	<authorgroup>
+		<author>
+			<firstname>Stef</firstname>
+			<surname>Walter</surname>
+			<affiliation>
+				<orgname>Red Hat Inc.</orgname>
+				<address>
+					<email>stefw@redhat.com</email>
+				</address>
+			</affiliation>
+		</author>
+	</authorgroup>
+</articleinfo>
+
+<sect1 id="pkcs11">
+	<title>PKCS#11 Extensions for Stapled Certificate Extensions</title>
+
+	<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>Here we outline how to use PKCS#11 as a store of stapled certificate extensions,
+		anchors	and blacklisted certificates. We do this in the stardard PKCS#11
+		object model, by defining a few extra attributes.</para>
+
+	<para>To make it clear which attributes are defined here and which are standard,
+		all new attributes and values are prefixed by the letters <literal>_X_</literal>. Once
+		standardized they would lose this tag.</para>
+
+	<para>The standard CKA_TRUSTED boolean attribute is used on an object with the 
+		class CKO_CERTIFICATE to mark it as an anchor. The presence of a
+		BasicConstraints certificate extension marks it as a certificate
+		authority anchor, capable of anchoring a certificate chain, and not just
+		itself.</para>
+
+	<para>We define a new boolean attribute CKA_X_DISTRUSTED. If this is present and
+		set to CK_TRUE on an object with the class CKO_CERTIFICATE, it marks that
+		certificate as being on the blacklist.</para>
+
+	<para>A new object class is defined of type CKO_X_CERTIFICATE_EXTENSION. Each 
+		object of this class represents one stapled certificate extension. It
+		contains the following (standard and newly defined) attributes (in addition
+		to the standard data storage attributes):</para>
+
+	<variablelist>
+	<varlistentry>
+		<term>CKA_ID</term>
+		<listitem><para>The arbitrary byte string identifier of a
+			CKO_X_CERTIFICATE_EXTENSION must match the CKA_ID of the
+			CKO_CERTIFICATE which it is stapled to. This reflects the
+			customary PKCS#11 method of associating certificates and
+			keys. Must be set.</para></listitem>
+	</varlistentry>
+	<varlistentry>
+		<term>CKA_OBJECT_ID</term>
+		<listitem><para>The DER-encoded OID of the stapled certificate
+			extension. Must be set.</para></listitem>
+	</varlistentry>
+	<varlistentry>
+		<term>CKA_X_CRITICAL</term>
+		<listitem><para>A CK_BBOOL value indicating whether the extension
+			is critical or not. Defaults to CK_FALSE if not set.</para></listitem>
+	</varlistentry>
+	<varlistentry>
+		<term>CKA_VALUE</term>
+		<listitem><para>The DER encoded value of the certificate extension.
+			Must be set.</para></listitem>
+	</varlistentry>
+	</variablelist>
+
+</sect1>
+
+</article>
diff --git a/specs/storing-trust-policy.xml b/specs/storing-trust-policy.xml
new file mode 100644
index 0000000..36b27a0
--- /dev/null
+++ b/specs/storing-trust-policy.xml
@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<book>
+	<title>Storing Trust Policy</title>
+
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+		href="storing-trust-basics.xml"/>
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+		href="storing-trust-existing.xml"/>
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+		href="storing-trust-pkcs11.xml"/>
+
+</book>