Storing Trust Assertions in PKCS#11 Modules
GNOME
+1 505 926 1827
stefw@gnome.org
General
Internet Engineering Task Force
security
pkcs11
trust
x509
certificate
pki
PKCS#11 is a standard that defines ways to store certificates, keys
and perform crypto operations. It does not specify a way to store trust
assertions.
Trust assertions are used to assign an explicit level of trust to a
certificate. Examples of trust assertions are certificate authority
root certificates, certificate revocation lists, and certificate
trust exceptions.
This document outlines a way to store trust assertions with PKCS#11.
This is not a new design, but documentation of the method already in use
by libraries such as NSS.
PKCS#11 is a useful and widely supported standard for storage and use
of keys and certificates. It is often used with smart cards.
Xxxxx
Xxxx The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119.
A trust assertion describes a level of trust in an object for a given usage
or purpose. Conceptually each trust assertion is a triple containing:
Certificate Reference
Usage or Purpose
Level of Trust
We examine each of these parts of the triple in further detail below.
A trust assertion ultimately denotes a level of trust. These are:
Untrusted: The certificate is explicitly untrusted.
Unknown: The trust is not known and should be determined elsewhere.
Trusted: The certificate itself is explicitly trusted.
Trusted Delegator: The certificate is trusted as a certificate
authority trust root. Trust is confers to certificates that this
certificate has signed, or signed certificates have signed, and so on.
A trust assertion always refers to a specific purpose or usage.
A certificate may be trusted for purposes like: email, code signing,
authenticating a server.
Each trust assertion contains a reference to a certificate.
There are two ways to refer to a certificate depending on whether
that certificate is self-signed (like a certificate authority) or signed
by another trusted certificate.
Self-signed certificates are referred to by their
complete hash of the DER value of the certificate.
Certificates signed by another certificate are referred to by
the DER value of the issuer field, and the serial number.
Referring to a self-signed certificate by its issuer and serial number
is meaningless.
Referring to a signed certificate by its hash, would preclude uses
such as certificate relocation lists, which do not contain certificates
or enough information to generate a hash.
Therefore different methods MUST be used to refer to self-signed
and issuer-signed certificates.
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_NETSCAPE_TRUST
and have the following attributes.
Trust object attributes.
Attribute
Type
Description
CKA_CLASS
CK_OBJECT_CLASS
CKO_NETSCAPE_TRUST
CKA_ISSUER
Byte array
DER-encoding of the certificate issuer name
CKA_SUBJECT
Byte array
DER-encoding of the certificate subject name. Optional, default empty
CKA_SERIAL_NUMBER
Byte array
DER-encoding of the certificate serial number
CKA_CERT_SHA1_HASH
Byte array
SHA1 hash of the the DER-encoding of certificate. Required for
self-signed certificates.
CKA_CERT_MD5_HASH
Byte array
MD5 hash of the the DER-encoding of certificate. Required for
self-signed certificates.
CKA_TRUST_SERVER_AUTH
CK_TRUST
Level of trust for server authentication extended usage.
CKA_TRUST_CLIENT_AUTH
CK_TRUST
Level of trust for client authentication extended usage.
CKA_TRUST_CODE_SIGNING
CK_TRUST
Level of trust for code signing extended usage.
CKA_TRUST_EMAIL_PROTECTION
CK_TRUST
Level of trust for email protection extended usage.
CKA_TRUST_IPSEC_END_SYSTEM
CK_TRUST
Level of trust for IPSEC end system extended usage.
CKA_TRUST_IPSEC_TUNNEL
CK_TRUST
Level of trust for IPSEC tunnel extended usage.
CKA_TRUST_IPSEC_USER
CK_TRUST
Level of trust for IPSEC user extended usage.
CKA_TRUST_TIME_STAMPING
CK_TRUST
Level of trust for IPSEC time stamping extended usage.
CKA_TRUST_DIGITAL_SIGNATURE
CK_TRUST
Level of trust for digital signature key usage.
CKA_TRUST_NON_REPUDIATION
CK_TRUST
Level of trust for non-repudiation key usage.
CKA_TRUST_KEY_ENCIPHERMENT
CK_TRUST
Level of trust for key-encipherment key usage.
CKA_TRUST_DATA_ENCIPHERMENT
CK_TRUST
Level of trust for data-encipherment key usage.
CKA_TRUST_KEY_AGREEMENT
CK_TRUST
Level of trust for key-agreement key usage.
CKA_TRUST_KEY_CERT_SIGN
CK_TRUST
Level of trust for certificate signing key usage.
CKA_TRUST_KEY_CRL_SIGN
CK_TRUST
Level of trust for crl signing key usage.
Xxxx: Possible additional attributes: CKA_TRUST_TYPE
(CKT_CERTIFICATE_SELF_SIGNED, CKT_CERTIFICATE_SIGNED),
CKA_CERT_SHA256_HASH
CK_TRUST represenst a level of trust.
Value
Description
CKT_UNTRUSTED
Explicitly untrusted.
CKT_UNKNOWN
Trust is unknown and should be determined elsewhere.
CKT_TRUSTED
Explicitly trusts the certificate in the assertion.
CKT_TRUSTED_DELEGATOR
Trusts the certificate as a certificate authority.
Trust assertions are checked using a PKCS#11 C_FindObjects operation.
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.
Checking of trust assertions is always done for a specific purpose.
A C_FindObjects operation is done using the following attributes.
Attribute
Value
CKA_CLASS
CKO_NETSCAPE_TRUST
CKA_CERT_SHA1_HASH
20 byte value of hash of certificate.
Purpose attribute
CKT_TRUSTED_DELEGATOR
A C_FindObjects operation is done using the following attributes.
Attribute
Value
CKA_CLASS
CKO_NETSCAPE_TRUST
CKA_CERT_SHA1_HASH
20 byte value of hash of certificate.
Purpose attribute
CKT_TRUSTED
A C_FindObjects operation is done using the following attributes.
Attribute
Value
CKA_CLASS
CKO_NETSCAPE_TRUST
CKA_ISSUER
DER encoding of certificate issuer.
CKA_SERIAL_NUMBER
DER encoding of certificate serial number.
Purpose attribute
CKT_UNTRUSTED
Xxxx: Use of multiple PKCS#11 modules
Not using just any module.
Minimal Reference
Ultimate Plan for Taking Over the World
Mad Dominators, Inc.
This becomes an Appendix.