Mozilla's getting a new look. What do you think? https://mzl.la/brandsurvey

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.

Document Tags and Contributors

 Contributors to this page: jezdez, stefw
 Last updated by: jezdez,