Vendor Extensions

Securosys defines a number of vendor extensions to the PKCS#11 API. These are features (mechanisms, attributes, functions) that the Primus PKCS#11 Provider exposes, but that are not part of the PKCS#11 standard.

These extensions are defined in the pkcs11.h header file that ships with the Primus PKCS#11 Provider. To use these extensions, you need to include this Securosys-provided header file in your application, and dynamically or statically link against the Primus PKCS#11 Provider shared library. For details see Building Your Own Applications.

Attestation

Primus HSM supports key attestation. Attestations are signed statements attesting to the attributes of a key, with a certificate chain that leads up to the Securosys Root CA.

This extension consists of:

• Proprietary mechanisms CKM_RKS_RSA_PKCS_KEY_PAIR_GEN and CKM_RKS_EC_KEY_PAIR_GEN. They are used to generate an attestation key pair with the standard C_GenerateKeyPair function.
• A proprietary C_RKSAttestKey function that obtains a key attestation signed by a previously generated attestation key.
• A proprietary key attribute CKA_RKS_ATTESTATION_SIGN that marks a key as an attestation key.

A code sample showing how to use attestation via PKCS#11 is available on GitHub.

ECIES

The Elliptic Curve Integrated Encryption Scheme (ECIES) is a hybrid public key encryption scheme. The Primus PKCS#11 Provider implements the proprietary CKM_ECIES mechanism. This convenience mechanism allows using ECIES through the standard C_Encrypt and C_Decrypt functions. For details, see the ECIES tutorial.

Key Split

CKM_KEY_SPLIT is a proprietary mechanism for the standard C_DeriveKey function. It allows the creation of a new key from a substring of a GENERIC_SECRET value. For example, this is useful to split a single long symmetric key into two shorter keys (for example, an encryption key and a MAC key). For details, see the Key Split tutorial.

Smart Key Attributes

Smart Key Attributes (SKA) bring fine-grained authorization and usage rules to private keys stored on Securosys HSMs. SKA allows defining policies of which approvers must approve an action before a key can be used.

• API reference
• Code samples

tip

Using SKA via the PKCS#11 API means that you need to implement workflow management yourself. This is why the recommended way to use SKA is via the TSB. The TSB provides a ready-made workflow engine for you, meaning less implementation work and shorter time-to-market. The TSB exposes a REST API, making it easy to use from any programming language.