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.
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.
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.
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.
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.|
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.|
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.
|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 for all of the above values are defined in pkcs11n.h in the NSS source.