Initial version of trust assertion docbook.

5 files changed, 361 insertions, 1 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..10ada4b
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+junk
+*.tmp
+*.pdf
diff --git a/Makefile b/Makefile
index e19e697..ddaa252 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,7 @@
+all: draft-pkcs11-trust-assertions.txt html/index.html
+
 draft-pkcs11-trust-assertions.txt: draft-pkcs11-trust-assertions.xml
 	xml2rfc $<
 
-all: draft-pkcs11-trust-assertions.txt
+html/index.html: docbook-params.xsl trust-assertions.xml
+	xmlto --skip-validation -o html/ -x docbook-params.xsl xhtml trust-assertions.xml
diff --git a/docbook-params.xsl b/docbook-params.xsl
new file mode 100644
index 0000000..5d8591a
--- /dev/null
+++ b/docbook-params.xsl
@@ -0,0 +1,39 @@
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+<!--
+    Parameters for DocBook transformation.
+
+    Copyright (C) 2009 Michael Leupold <lemma@confuego.org>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+-->
+
+    <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
+
+    <xsl:param name="toc.max.depth">3</xsl:param>
+    <xsl:param name="generate.section.toc.level">0</xsl:param>
+    <xsl:param name="generate.toc">
+        book     toc
+        part     nop
+        chapter  toc
+    </xsl:param>
+    <xsl:param name="html.stylesheet">style.css</xsl:param>
+    <xsl:param name="funcsynopsis.style">ansi</xsl:param>
+    <xsl:param name="funcsynopsis.decoration">1</xsl:param>
+    <xsl:param name="refentry.generate.name">0</xsl:param>
+    <xsl:param name="refentry.generate.title">1</xsl:param>
+
+</xsl:stylesheet>
diff --git a/html/.gitignore b/html/.gitignore
new file mode 100644
index 0000000..2d19fc7
--- /dev/null
+++ b/html/.gitignore
@@ -0,0 +1 @@
+*.html
diff --git a/trust-assertions.xml b/trust-assertions.xml
new file mode 100644
index 0000000..2b9fd10
--- /dev/null
+++ b/trust-assertions.xml
@@ -0,0 +1,314 @@
+<?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>
+	<section>
+		<title>Introduction</title>
+		<para>PKCS#11 is a useful and widely supported standard for storage and use
+			of keys and certificates. It is often used with smart cards.</para>
+
+		<para>XXX</para>
+	</section>
+
+	<section>
+		<title>Trust Assertions</title>
+		<para>A 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>Reference to the Subject</para></listitem>
+			<listitem><para>Purpose</para></listitem>
+			<listitem><para>Level of Trust</para></listitem>
+		</itemizedlist>
+
+		<para>We examine each of these parts of the triple in further detail below.</para>
+
+		<section>
+			<title>Level of Trust</title>
+
+			<para>XXX</para>
+
+			<itemizedlist>
+				<listitem><para>Untrusted: Explicitly untrusted. Override other
+					trust.</para></listitem>
+				<listitem><para>Unknown: The trust is not known and should be
+					determined elsewhere.</para></listitem>
+				<listitem><para>Trusted: Explicitly trusted. Override other
+					trust</para></listitem>
+			</itemizedlist>
+		</section>
+
+		<section>
+			<title>Purpose</title>
+
+			<para>A trust assertion refers to a specific purpose or usage. A
+				certificate may be trusted for purposes like: email, code signing,
+				authenticating a server.</para>
+
+			<para>In addition to the usage, the purpose can contain a more specific
+				designation, such as the hostname of a server.</para>
+
+			<para>The purpose can be a wildcard which matches any purpose. This is
+				especially useful for untrusted assertions.</para>
+		</section>
+
+
+		<section>
+			<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
+				certificates as the subject. However .</para>
+
+			<para>There are two ways to refer to a certificate depending on whether
+				that certificate is being referred to as a trust root (like a certificate
+				authority) or referred to by another trusted certificate.</para>
+
+			<para>Certificates used as trust roots are referred to by the complete DER
+				encoding of the certificate.</para>
+
+			<para>Certificates verified by another certificate (signed as part
+				of a certificate chain) are referred to by the DER value of the issuer
+				field and the serial number.</para>
+
+			<para>Referring to a trust root certificate by its issuer and serial number
+				is meaningless.</para>
+
+			<para>Referring to a certificates signed by another certificate would preclude uses
+				such as certificate revocation lists.</para>
+
+			<para>Therefore different methods MUST be used to refer certificates in these
+				different situations.</para>
+		</section>
+	</section>
+
+	<section>
+		<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. Trust assertions objects are of the class CKO_G_TRUST_ASSERTION
+			and have the following attributes.</para>
+
+		<table>
+			<title>Trust root assertion</title>
+			<tgroup cols="3">
+				<thead>
+					<row>
+						<entry>Attribute</entry>
+						<entry>Data Type</entry>
+						<entry>Description</entry>
+					</row>
+				</thead>
+				<tbody>
+					<row>
+						<entry>CKA_CLASS</entry>
+						<entry>CK_OBJECT_CLASS</entry>
+						<entry>CKO_G_TRUST_ASSERTION</entry>
+					</row>
+					<row>
+						<entry>CKA_G_TRUST_TYPE</entry>
+						<entry>CK_TRUST_TYPE</entry>
+						<entry>CKT_G_TRUST_ROOT</entry>
+					</row>
+					<row>
+						<entry>CKA_G_CERTIFICATE_VALUE</entry>
+						<entry>Byte array</entry>
+						<entry>DER SHA1 hash of the the DER-encoding of certificate. Required for
+							self-signed certificates.</entry>
+					</row>
+					<row>
+						<entry>CKA_G_PURPOSE</entry>
+						<entry>CK_UTF8_CHAR array</entry>
+						<entry>XXX</entry>
+					</row>
+					<row>
+						<entry>CKA_G_LEVEL</entry>
+						<entry>CK_TRUST_LEVEL</entry>
+						<entry>The trust level of this assertion</entry>
+					</row>
+				</tbody>
+			</tgroup>
+		</table>
+
+		<table>
+			<title>Trust exception assertion</title>
+			<tgroup cols="3">
+				<thead>
+					<row>
+						<entry>Attribute</entry>
+						<entry>Data Type</entry>
+						<entry>Description</entry>
+					</row>
+				</thead>
+				<tbody>
+					<row>
+						<entry>CKA_CLASS</entry>
+						<entry>CK_OBJECT_CLASS</entry>
+						<entry>CKO_G_TRUST_ASSERTION</entry>
+					</row>
+					<row>
+						<entry>CKA_G_TRUST_TYPE</entry>
+						<entry>CK_TRUST_TYPE</entry>
+						<entry>CKT_G_TRUST_EXCEPTION</entry>
+					</row>
+					<row>
+						<entry>CKA_ISSUER</entry>
+						<entry>Byte array</entry>
+						<entry>DER-encoding of the certificate issuer name</entry>
+					</row>
+					<row>
+						<entry>CKA_SERIAL_NUMBER</entry>
+						<entry>Byte array</entry>
+						<entry>DER-encoding of the certificate serial number</entry>
+					</row>
+					<row>
+						<entry>CKA_G_PURPOSE</entry>
+						<entry>CK_UTF8_CHAR array</entry>
+						<entry>XXX</entry>
+					</row>
+					<row>
+						<entry>CKA_G_LEVEL</entry>
+						<entry>CK_TRUST_LEVEL</entry>
+						<entry>The trust level of this assertion</entry>
+					</row>
+				</tbody>
+			</tgroup>
+		</table>
+
+		<table>
+			<title>CK_TRUST_LEVEL represenst a level of trust.</title>
+			<tgroup cols="2">
+				<thead>
+					<row>
+						<entry>Value</entry>
+						<entry>Description</entry>
+					</row>
+				</thead>
+				<tbody>
+					<row>
+						<entry>CKT_G_UNTRUSTED</entry>
+						<entry>Explicitly untrusted. Overrides trust determined elsewhere.</entry>
+					</row>
+					<row>
+						<entry>CKT_G_UNKNOWN</entry>
+						<entry>Trust is unknown and should be determined elsewhere.</entry>
+					</row>
+					<row>
+						<entry>CKT_G_TRUSTED</entry>
+						<entry>Explicitly trusts the certificate in the assertion.</entry>
+					</row>
+				</tbody>
+			</tgroup>
+		</table>
+	</section>
+
+	<section>
+		<title>Operations</title>
+
+		<section>
+			<title>Checking Trust Assertions</title>
+			<para>Trust assertions are checked using a PKCS#11 C_FindObjects operation.</para>
+
+			<para>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.</para>
+
+			<para>Checking of trust assertions is always done for a specific purpose.</para>
+
+			<section>
+				<title>Checking a Trust Root</title>
+				<para>A C_FindObjects operation is done using the following attributes.</para>
+
+				<table>
+					<title>Values for checking a root certificate authority.</title>
+					<tgroup cols="2">
+						<thead>
+							<row>
+								<entry>Attribute</entry>
+								<entry>Value</entry>
+							</row>
+						</thead>
+						<tbody>
+							<row>
+								<entry>CKA_CLASS</entry>
+								<entry>CKO_G_TRUST_ASSERTION</entry>
+							</row>
+							<row>
+								<entry>CKA_G_TRUST_TYPE</entry>
+								<entry>CKT_G_TRUST_ROOT</entry>
+							</row>
+							<row>
+								<entry>CKA_G_CERTIFICATE_VALUE</entry>
+								<entry>XXX</entry>
+							</row>
+							<row>
+								<entry>CKA_G_PURPOSE</entry>
+								<entry>XXX</entry>
+							</row>
+							<row>
+								<entry>CKA_G_TRUST_LEVEL</entry>
+								<entry>CKL_G_TRUSTED</entry>
+							</row>
+						</tbody>
+					</tgroup>
+				</table>
+			</section>
+
+			<section>
+				<title>Checking a Trust Exception</title>
+				<para>A C_FindObjects operation is done using the following attributes.</para>
+
+				<table>
+					<title>Values for checking a self-signed certificate.</title>
+					<tgroup cols="2">
+						<thead>
+							<row>
+								<entry>Attribute</entry>
+								<entry>Value</entry>
+							</row>
+						</thead>
+						<tbody>
+							<row>
+								<entry>CKA_CLASS</entry>
+								<entry>CKO_NETSCAPE_TRUST</entry>
+							</row>
+							<row>
+								<entry>CKA_G_TRUST_TYPE</entry>
+								<entry>CKT_G_TRUST_EXCEPTION</entry>
+							</row>
+							<row>
+								<entry>CKA_ISSUER</entry>
+								<entry>XXX</entry>
+							</row>
+							<row>
+								<entry>CKA_SERIAL_NUMBER</entry>
+								<entry>XXX</entry>
+							</row>
+							<row>
+								<entry>CKA_G_PURPOSE</entry>
+								<entry>XXX</entry>
+							</row>
+							<row>
+								<entry>CKA_G_TRUST_LEVEL</entry>
+								<entry>CKL_G_UNTRUSTED</entry>
+							</row>
+						</tbody>
+					</tgroup>
+				</table>
+			</section>
+		</section>
+	</section>
+
+	<section>
+		<title>Acknowledgements</title>
+		<para>NSS: Who?</para>
+	</section>
+
+	<section>
+		<title>Problems</title>
+		<para>xxxx</para>
+	</section>
+</article>