Initial version of trust assertion docbook.

1 files changed, 314 insertions, 0 deletions

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>