PKCS#11 is a useful and widely supported standard for storage and use of keys and certificates. It is often used with smart cards.
Here we outline how to use PKCS#11 as a store for trust policy, containing sets for anchors, blacklist, and attached extensions.
We define a trust store using the standard PKCS#11 object model, with a few new attributes.
Each PKCS#11 token is a store.
Sets are implemented by using certain PKCS#11 attributes to differentiate between items in various sets.
Items in the sets are represented by PKCS#11 objects.
Fields are implemented as various PKCS#11 CK_ATTRIBUTE
attributes, and the field identifiers are the CK_ATTRIBUTE_TYPE type
of the attribute.
Some fields are standard PKCS#11 attributes, and others are
implemented by defining a few extension vendor attributes in the PKCS#11
defined fashion. To make it clear which attributes are defined here
and which are standard, all new attributes and values are
prefixed by the letters _X_. Once standardized
they would lose this tag.
In PKCS#11 any field can be used as a lookup field. For speedy lookups it is recommended that implementations internally index the attributes that will be used to lookup trust policy.
Optional fields are implemented as an empty zero-length
CK value when the field is not present.
A lookup operation is implemented using the
C_FindObjectsInit() C_FindObjects()
PKCS#11 functions.
The set to lookup is specified by passing certain set specific
attributes, defined below, as part of the C_FindObjectsInit()
find template.
The fields to lookup are also passed as part of the
C_FindObjectsInit() find template.
If there are fields for which values need to be retrieved, the
C_GetAttributeValue() function should be used to retrieve
them on each of the objects matched by C_FindObjects().
A remove operation is implemented using the
C_FindObjectsInit() C_FindObjects()
PKCS#11 functions, in the same way as a in the lookup operation described
above.
The C_DestroyObject() function should be used to
remove the objects matched by the C_FindObjects()
function.
Another concurrent operation may have also removed an item. Do not
propagate CKR_OBJECT_HANDLE_INVALID return codes from
the C_DestroyObject() function.
Callers may consult the standard PKCS#11 CK_TOKEN_INFO
CKF_TOKEN_WRITE_PROTECTED flag, and object
CKA_MODIFIABLE attribute to determine whether items
may be removed.
A store operation is implemented using the C_CreateObject()
PKCS#11 function.
The set to store the item in is specified by passing certain
set specific attributes, defined below, as part of the
C_CreteObject() attribute template.
The fields to store are also passed as part of the
C_CreateObject() attribute template.
Implementors of the C_CreateObject() function should
check for another item that matches the relevant fields for the set in question.
If one exists the existing handle should be returned, rather than storing a
duplicate object.
Callers may consult the standard PKCS#11 CK_TOKEN_INFO
CKF_TOKEN_WRITE_PROTECTED flag to determine whether items
may be stored.
The standard CKA_TRUSTED boolean attribute is used
to define a certificate or public key as an anchor.
The following attribute is set on items that are part of the set of anchors:
CKA_TRUSTEDValue: CK_TRUE
Items in the set of anchors contain the following fields:
CKA_PUBLIC_KEY_INFOThe public key of the anchor, always present. A DER encoded SubjectPublicKeyInfo sequence as defined in X.509.
CKA_SUBJECTThe subject DN of the anchor. Contents as defined in PKCS#11: a DER encoded Name sequence defined in X.509.
CKA_CLASSSet to CKO_CERTIFICATE when the
stored item is a certificate, and CKO_PUBLIC_KEY
when it doesn't.
CKA_VALUEWhen the stored item is a certificate
(it has a CKA_CLASS of CKO_CERTIFICATE,
see above) this attribute stores the DER encoded Certificate
sequence defined in X.509.
Other standard PKCS#11 fields should be present on the objects as per
the CKA_CLASS attribute.
Note that the presence of a BasicConstraints extension marks it as a certificate authority anchor, capable of anchoring a certificate chain, and not just itself.
We define a new boolean attribute CKA_X_DISTRUSTED to indicate blacklist status.
The following attribute is set on items that are part of the blacklist set:
CKA_X_DISTRUSTEDValue: CK_TRUE
Items in the blacklist set contain the following fields:
CKA_PUBLIC_KEY_INFOThe public key of the anchor. A DER encoded SubjectPublicKeyInfo sequence as defined in X.509. When this value is not present, set to a zero length value.
CKA_ISSUERThe DN of the issuer. Contents as defined in PKCS#11: a DER encoded Name sequence defined in X.509.
CKA_SERIAL_NUMBERThe serial number assigned by the issuer. Contents as defined in PKCS#11: a DER encoded Name sequence defined in X.509.
CKA_CLASSSet to CKO_CERTIFICATE when the
CKA_ISSUER and CKA_SERIAL_NUMBER are
present. Otherwise may be set to either CKO_PUBLIC_KEY
or CKO_CERTIFICATE as appropriate.
Other standard PKCS#11 fields should be present on the objects as per
the CKA_CLASS attribute.
A new object class is defined of type CKO_X_CERTIFICATE_EXTENSION. Each
object of this class represents one attached certificate extension. It
contains the following (standard and newly defined) attributes (in addition
to the standard data storage attributes):
The following attribute is set on items that are part of the set of attached extensions:
CKA_CLASSValue: CKO_X_CERTIFICATE_EXTENSION
Items in the set of attached extensions set contain the following fields:
CKA_PUBLIC_KEY_INFOThe public key associated with the attached extension. A DER encoded SubjectPublicKeyInfo sequence as defined in X.509.
CKA_VALUEThe DER encoded value of the Extension sequence as defined in X.509. Note that this is the entire Extension sequence and not just the extnValue field.
CKA_OBJECT_IDThe DER-encoded OID of the attached certificate extension. This is the exact contents of the extnID field in the Extension sequence.
In addition the PKCS#11 Common Storage Object Attributes may
be present, as well as the CKA_ID attribute.