diff options
Diffstat (limited to 'trust-assertions.xml')
-rw-r--r-- | trust-assertions.xml | 314 |
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> |