PKCS #11 Netscape Trust Objects

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.

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. 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.

Level of trust values.
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.