Breadcrumbs

Generic PKCS#11 Provider

EJBCA supports two mechanisms for connecting to Hardware Security Modules (HSMs) via the PKCS#11 interface: the Java PKCS#11 Provider and PKCS#11 NG (P11NG). The configuration options described in this section apply to both implementations unless explicitly stated otherwise: some parameters are shared, while others are specific to a single provider.

The Java PKCS#11 Provider is a wrapper included in Java that implements support for tokens with PKCS#11 libraries. It has been tested with a variety of HSMs and firmware versions, but compatibility is ultimately dependent on the Java runtime implementation and the specific HSM vendor. Updates to the Java PKCS#11 implementation may introduce behavioral changes that are outside the control of EJBCA.

A known limitation of the Java PKCS#11 Provider is its handling of session caching. If the connection to the HSM is lost, sessions cannot always be re-established, and a restart of the application server is typically required. PKCS#11 NG provides improved handling of session recovery and is generally more robust in this regard.

Crypto Token Configuration Properties

In addition to the standard keys described in Hardware Security Modules (HSM), the Crypto Token property field (as shown in the EJBCA Administration GUI) should contain the following properties:

  • sharedLibrary: Path to the HSM PKCS#11 library (/etc/utimaco/libcs2_pkcs11.so, /usr/safenet/lunaclient/lib/libCryptoki2_64.so etc)

  • slotLabelType: Type of slot reference, see below

  • slotLabelValue: Value of the slot reference (1, myslot etc).

Slot label types

The slot label type can be one of the following

  • SLOT_NUMBER: Any positive integer, can be used to refer to slots in any HSM with consecutive slot numbering.

  • SLOT_INDEX: Any positive integer, prefaced by an 'i'.

  • SLOT_LABEL: The PKCS#11 standard allows for using strings for labeling slots. This label may also be an integer or an 'i' followed by an integer (like a number or an index)

  • SUN_FILE: The slot specified by a SUN config file. The slot label can be left blank.

Optional properties

The following optional properties can be configured:

  • attributesFile: A file specifying PKCS#11 attributes (used mainly for key generation).

  • keyspec: Key specification used when generating new HSM keys from within the EJBCA Admin GUI. Keyspec that is used as first choice when generating new keys in the GUI of form "1024" for RSA keys, "DSA1024" for DSA keys and secp256r1 for EC keys. If keyspec is not given EJBCA tries to generate a key with the same specification as the current cert signing key.

PKCS#11 attributes file

An attributes file follows the format specified in the Oracle JavaTM PKCS#11 Reference Guide.

If no attributesFile is configured, EJBCA uses a built-in default configuration. In general, using the default is strongly recommended. Custom attribute files should only be used when required for compatibility with specific or non-standard HSM configurations.

A minimal example (for reference only) is shown below:

Bash
name=SafeNet
library=/opt/PTK/lib/libcryptoki.so
slot=1
attributes(*, CKO_PUBLIC_KEY, *) = {
  CKA_TOKEN = false
  CKA_ENCRYPT = true
  CKA_VERIFY = true
  CKA_WRAP = true
}
attributes(*, CKO_PRIVATE_KEY, *) = {
  CKA_TOKEN = true
  CKA_PRIVATE = true
  CKA_SENSITIVE = true
  CKA_EXTRACTABLE = false
  CKA_DECRYPT = true
  CKA_SIGN = true
  CKA_UNWRAP = true
  CKA_DERIVE = false
}
disabledMechanisms = {
  CKM_SHA1_RSA_PKCS
  CKM_SHA256_RSA_PKCS
  CKM_SHA384_RSA_PKCS
  CKM_SHA512_RSA_PKCS
  CKM_MD2_RSA_PKCS
  CKM_MD5_RSA_PKCS
  CKM_DSA_SHA1
  CKM_ECDSA_SHA1
}

This type of configuration is rarely required. One known exception is the module-protected slot in Thales/nCipher HSMs, where CKA_PRIVATE may need to be set differently.

Default attribute behavior

The default attributes that are applied to each key generated by EJBCA ensures that:

  • All needed operations could be done.

  • The private part of the key is stored in the HSM but not the public part (which is in a certificate that is stored on the HSM).

  • It will be impossible to read the private part of the key from the HSM.

The default configuration will also disable certain signing mechanisms. The disabled mechanisms are for signing when the data to be signed is hashed by PKCS#11 before using the private key in the HSM. When these mechanisms are disabled, the sun PKCS#11 wrapper provider will do the hashing instead of the HSM. This speeds up the signing in most cases, especially when your HSM is on another host and will not have any security impacts as no secret in the HSM is used for the hashing.

However, it will be possible not to disable these hash/signing mechanisms, see the PKCS#11 section of '$EJBCA_HOME/conf/cesecore.properties'. You could try not to disable the mechanisms if you get the error CKR_FUNCTION_NOT_SUPPORTED (0x54) from PKCS#11 when signing.

If you are using an attributesFile and have more than one CA using the same slot it is very important that BOTH CA token properties configurations contain the attributesFile. This is because the attributes are applied when the provider is installed during startup. If one configuration does not have the attributesFile it cannot be applied later on by the other configuration.

Command Line Interfaces

EJBCA provides two command-line tools for PKCS#11 management:

  • p11ng-cli for PKCS#11 NG

  • clientToolBox PKCS11HSMKeyTool for Java PKCS#11

The tool EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool is used to administrate and generate keys. Use it without parameters to get all valid options. Keys are generated either using a default specified slot and PKCS#11 library or using a configuration file.

  • To generate keys using the built-in default with a specified slot and PKCS#11 library, use:

Bash
dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate hsmp11.so 2048 defaultKey 1

  • To generate keys using a configuration file, use:

Bash
dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate hsmp11.conf 2048 defaultKey

The contents of the configuration file is specified in the PKCS#11 wrapper documentation from Oracle. Generally, it is sufficient to use the default but with some HSMs, it may be necessary to define certain PKCS#11 attributes for the generated key.

Note that all keys to be used have to be generated prior to the application server is started.

The default attributes attempt to automatically set CKA_LABEL also when generating keys using the clientToolBox. You can set CKA_LABEL, which is hex encoded characters, also with an attributesFile, either by setting the CKA_LABEL value:

attributes(*, CKO_PRIVATE_KEY, *) = {
  CKA_TOKEN = true
...
  CKA_LABEL = 0h707269762d6b65796c6162656c
}

or by setting an empty CKA_LABEL string with two spaces before and nothing, not even space after. This placeholder will then be dynamically replaced with the key alias value, hex encoded:

attributes(*, CKO_PRIVATE_KEY, *) = {
  CKA_TOKEN = true
...
  CKA_LABEL
}

Generated HSM Objects

This section applies only to the Java PKCS#11 Provider (PKCS#11 Crypto Token in EJBCA), not the PKCS#11 NG Crypto Token.

When using the Java PKCS#11 provider, EJBCA typically creates two HSM objects:

  • A private key

  • A certificate, thus a holder of the public key used by Java, and not the real certificate of a CA.

A Java keystore entry has no reference to a public key pkcs#11 object, just a private key object and a certificate object, hence the public key object is not needed after the certificate object has been written to the keystore. By setting the CKA_TOKEN attribute to false for the public key its object will not be stored on the HSM. If CKA_TOKEN is true then all public keys will be on the HSM forever since no public key is deleted when a private key is deleted from the keystore. So in order not to waste memory on the HSM CKA_TOKEN must be false for the public key.

When generating keys with clientToolBox each private key has the CKA_LABEL attribute set to the alias of the key prefixed with priv-. But when generating a key in EJBCA there will normally not be a CKA_LABEL for the private key. If you want to have a label even when the key is generated by EJBCA you got to use an attribute file with a CKA_LABEL definition in your configuration. The value of the attribute is a hexadecimal string starting with "0h". These labels are normally seen only when you use the native HSM tools to list and manipulate objects. CKA_LABEL is set on the certificate object, and this is the label used as an alias in Java/EJBCA. The PKCS#11 attribute CKA_ID binds a certificate object (public key) to the private key.


The above example would then include:

Bash
attributes(*,CKO_PRIVATE_KEY,*) = {
  .
  .
  CKA_LABEL = 0h6b657931
} 

The example above gives the label key1 to the private key. You can give any label by looking up the hex codes of characters in the ascii table.