Representation: PKCS#11


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.

Store representation

We define a trust store using the standard PKCS#11 object model, with a few new attributes.

Store

Each PKCS#11 token is a store.

Sets

Sets are implemented by using certain PKCS#11 attributes to differentiate between items in various sets.

Items

Items in the sets are represented by PKCS#11 objects.

Fields

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.

Lookup fields

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

Optional fields are implemented as an empty zero-length CK value when the field is not present.

Lookup operation

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

Remove operation

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.

Store operation

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.

Set: Anchors

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_TRUSTED

Value: CK_TRUE

Items in the set of anchors contain the following fields:

CKA_PUBLIC_KEY_INFO

The public key of the anchor, always present. A DER encoded SubjectPublicKeyInfo sequence as defined in X.509.

CKA_SUBJECT

The subject DN of the anchor. Contents as defined in PKCS#11: a DER encoded Name sequence defined in X.509.

CKA_CLASS

Set to CKO_CERTIFICATE when the stored item is a certificate, and CKO_PUBLIC_KEY when it doesn't.

CKA_VALUE

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

Set: Blacklist

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_DISTRUSTED

Value: CK_TRUE

Items in the blacklist set contain the following fields:

CKA_PUBLIC_KEY_INFO

The 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_ISSUER

The DN of the issuer. Contents as defined in PKCS#11: a DER encoded Name sequence defined in X.509.

CKA_SERIAL_NUMBER

The serial number assigned by the issuer. Contents as defined in PKCS#11: a DER encoded Name sequence defined in X.509.

CKA_CLASS

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

Set: Attached Extensions

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_CLASS

Value: CKO_X_CERTIFICATE_EXTENSION

Items in the set of attached extensions set contain the following fields:

CKA_PUBLIC_KEY_INFO

The public key associated with the attached extension. A DER encoded SubjectPublicKeyInfo sequence as defined in X.509.

CKA_VALUE

The 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_ID

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

Constants

The following constants are defined:


#define CKO_X_CERTIFICATE_EXTENSION   0xd84447c8UL
#define CKA_X_DISTRUSTED              0xd8444764UL

/* The following definition comes from PKCS#11 2.40
#define CKA_PUBLIC_KEY_INFO           0x00000129UL