Identifiers and Labels in PKCS#11

The PKCS#11 standard has multiple "id" attributes and a "label" attribute. These are often confused and mis-understood, especially with respect to their uniqueness requirements.

This table summarises the most common identifier attributes:

Attribute	Use case	Unique?	Set by	Notes
CKA_LABEL	Human-readable string.	No	Application	An array of CK_UTF8CHAR.
CKA_ID	An identifier. Often used to logically group together private keys, public keys, and certificates. For example, the ID can be the hash of the public key (the fingerprint).	No	Application	An array of CK_BYTE, thus not required to be a string.
CKA_OBJECT_ID	"Object" in the "OID" sense. Not to be confused with a PKCS#11 object. Used in data objects (CKO_DATA, storing application-defined data) for indicating the object type.	No	Application	Not supported by the Primus PKCS#11 provider.
CKA_UNIQUE_ID	Persistent, unique ID for an object on the token.	Yes	Token/HSM	Added in the PKCS#11 3.0 standard. Not supported by the Primus PKCS#11 provider.

Uniqueness

The PKCS#11 standard does not require CKA_LABEL and CKA_ID to be unique (as seen in the table).

It is up to the application to choose a scheme and manage these attributes. The application needs to make sure that its addressing scheme is able to uniquely identify objects. For example, an application might have a private key, public key, and certificate all with the same CKA_LABEL and CK_ID, and uses the CK_OBJECT_CLASS (see the CKO_xyz definitions) to distinguish the three objects.

If you are in a situation where your application has created duplicates, you need to iterate over them and manually try to find out which is the one you are looking for.

Internally, the Primus HSM requires labels to be unique. Therefore, when it encounters duplicate labels, the Primus PKCS#11 provider internally adds unique suffixes of the form label@?!<uid>. These suffixes are an implementation detail, and are not exposed via the PKCS#11 interface. However, these suffixes may be visible via other API providers (such as JCE) or in other contexts (for example, when exporting a list of invalidated keys from the HSM).

Null-termination

In PKCS#11, strings do not have null termination. This applies to both CK_CHAR and CK_UTF8CHAR.

Thus in practice, you will often find yourself specifying labels as follows:

{CKA_LABEL, label, sizeof(label)-1},

The Primus PKCS#11 provider will also remove any null-termination (\0) of labels. Still, for compliance with the PKCS#11 standard and better portability, Securosys recommends to not pass null-terminators to the PKCS#11 library.