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 objects.
Trust objects are used to assign an explicit level of trust to a certificate. Examples of trust assertions are certificate authority root certificates. This document outlines the way in which NSS stores trust objects via PKCS#11. This is not a new design, but documentation of the method already in use.
Trust Objects
A trust object describes a level of trust in a certificate for a given usage or purpose. Conceptually a trust object contains the following:
- Certificate Reference
- Purpose + Level of trust (multiple)
Purpose + Level of Trust
A trust object ultimately denotes a level of trust in a certificate. The trust is expressed for a specific purpose (or usage). A trust object contains multiple purposes and the level of trust for each one. Examples of purposes are: email, code signing, authenticating a server.
The levels of trust 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, and confers its trust to other certificates.
Certificate Reference
Each trust object 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.
Certificates used as a root of trust are referred to by the complete hash of the DER value of the certificate. Certificates in a trust chain whose issuer is trusted are referred to by the DER value of the issuer field, and the serial number.
PKCS#11 Representation
Trust objects 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 objects are of the class CKO_NETSCAPE_TRUST and have the following attributes.
| Attribute | Type | Description |
|---|---|---|
| CKA_CLASS | CK_OBJECT_CLASS | CKO_NETSCAPE_TRUST |
| CKA_ISSUER | Byte array |
DER-encoding of the certificate issuer name. Required for non-trust anchor objects. |
| CKA_SUBJECT | Byte array | DER-encoding of the certificate subject name. Optional. |
| CKA_SERIAL_NUMBER | Byte array | DER-encoding of the certificate serial number. Required for non-trust anchor objects. |
| CKA_CERT_SHA1_HASH | Byte array | SHA1 hash of the DER-encoding of the certificate. Required for trust anchor objects. |
| CKA_CERT_MD5_HASH | Byte array | MD5 hash of the DER-encoding of the certificate. Required for trust anchor objects. |
| CKA_TRUST_SERVER_AUTH | CK_TRUST | Level of trust for server authentication purpose. |
| CKA_TRUST_CLIENT_AUTH | CK_TRUST | Level of trust for client authentication purpose. |
| CKA_TRUST_CODE_SIGNING | CK_TRUST | Level of trust for code signing purpose. |
| CKA_TRUST_EMAIL_PROTECTION | CK_TRUST |
Level of trust for email protection purpose. |
| CKA_TRUST_IPSEC_END_SYSTEM | CK_TRUST | Level of trust for IPSec end system purpose. |
| CKA_TRUST_IPSEC_TUNNEL | CK_TRUST | Level of trust for IPSec tunnel purpose. |
| CKA_TRUST_IPSEC_USER | CK_TRUST | Level of trust for IPSec user purpose. |
| CKA_TRUST_TIME_STAMPING | CK_TRUST | Level of trust for time stamping purpose. |
| CKA_TRUST_DIGITAL_SIGNATURE | CK_TRUST | Level of trust for digital signature key usage purpose. |
| CKA_TRUST_NON_REPUDIATION | CK_TRUST | Level of trust for non-repudiation key usage purpose. |
| CKA_TRUST_KEY_ENCIPHERMENT | CK_TRUST | Level of trust for key-encipherment key usage purpose. |
| CKA_TRUST_KEY_AGREEMENT | CK_TRUST |
Level of trust for key-agreement key usage purpose. |
| CKA_TRUST_KEY_CERT_SIGN | CK_TRUST | Level of trust for certificate signing key usage purpose. |
| CKA_TRUST_KEY_CRL_SIGN | CK_TRUST | Level of trust for CRL signing key usage purpose. |
CK_TRUST is a CK_ULONG which can contain one several values. It represents the level of trust.
| Value | Description |
|---|---|
| CK_UNTRUSTED | Explicitly untrusted. |
| CK_UNKNOWN | Trust is unknown and should be determined elsewhere. |
| CK_TRUSTED | Explicitly trusts the certificate referred to in the trust object. |
| CKT_TRUSTED_DELEGATOR | Trusts the certificate as a certificate authority, and delegates trust (for the purpose) to other signed certificates. |
Definitions
Definitions for all of the above values are defined in pkcs11n.h in the NSS source.