IBM HPCS

IBM Hyper Protect Crypto Services (HPCS) is a dedicated key management service and hardware security module (HSM). EJBCA can integrate with IBM HPCS using the PKCS#11 API.

The integration with HPCS is tested with PKCS#11 NG (PKCS#11 NG Crypto Token in EJBCA Enterprise). Both RSA and EC works with P11NG. Some details are still to be improved, such as key generation for RSA keys need Sign and Encrypt while Sign Only gives a TEMPLATE_INCONSISTENT error.

Initial testing with the Java PKCS#11 Provider (PKCS#11 Crypto Token using in EJBCA Community) indicates that some functionality does not work out-of-the-box, such as EC key generation.

In this initial integration, full support for all functionality cannot be guaranteed. Not all PKI features have been tested, such as SCEP.

The following sections outline how to install, configure and connect to the HPCS service and provide an example of using HPCS from EJBCA.

Install PKCS #11 files

The HPCS PKCS#11 driver is available on the IBM Cloud GitHub.

To install the PKCS #11 files and move them into a folder that is accessible by EJBCA, do the following:

Download and follow the instructions on the IBM Cloud GitHub page.
Since EJBCA looks for the PCKS#11 drivers in specific locations, we recommend putting the driver in the location /opt/grep11 and creating a version-independent link. The following example uses version 2.5.8 of the driver:
```
mkdir /opt/grep11
cd /opt/grep11
<download and place the so file in this directory>
ln -s /opt/grep11/pkcs11-grep11-amd64.so.2.5.8 /opt/grep11/pkcs11-grep11-amd64.so
```
CODE

Configure PKCS #11 client configuration file

The configuration is specified in a PKCS #11 client configuration YAML file named grep11client.yaml. You need to set up the following in the configuration file:

API key
EP11 Public Endpoint
HPCS instance ID

To configure the YAML file:

Configure the file according to instructions in the IBM Cloud HPCS documentation topic Set up the PKCS #11 configuration file.
Move the grep11client.yaml configuration file to /etc/ep11client/grep11client.yaml.

Initialize and connect to HPCS

Before using the HSM, the PKCS#11 token needs to be initialized.

To initialize the token:

You need to specify the security officer API key (SO-user API-key) and use the user API key as the pin:

pkcs11-tool --module /opt/grep11/pkcs11-grep11-amd64.so --init-token --init-pin --so-pin=<SO-user API-key> --label="GREP11 Token" --pin <user API-key> -v

CODE

The token should now be functional. To verify, you can test a key generation command with the pkcs11-tool according to the following example:
```
pkcs11-tool  --module /opt/grep11/pkcs11-grep11-amd64.so --login --login-type user --keypairgen --id 1 --key-type rsa:2048
```
CODE

The output should be similar to the following:

Using slot 0 with a present token (0x0)
Logging in to "GREP11 Token".
Please enter User PIN:
Key pair generated:
Private Key Object; RSA
  label:      
  ID:         01
  Usage:      decrypt, sign, unwrap
warning: PKCS11 function C_GetAttributeValue(ALWAYS_AUTHENTICATE) failed: rv = CKR_ATTRIBUTE_TYPE_INVALID (0x12)

  Access:     sensitive, always sensitive, never extractable, local
Public Key Object; RSA 2048 bits
  label:      
  ID:         01
  Usage:      encrypt, verify, wrap
  Access:     none

CODE

Use HPCS from EJBCA

You can test HPCS using the tool p11ng-cli, a simple test tool for verifying functionality using the same code as a running EJBCA uses. For more information on the tool, see P11NG CLI.

To use p11ng-cli to test HPCS, do the following:

To build p11ng-cli with ant, run:
```
ant p11ng-cli
cd dist/p11ng-cli
```
CODE

To list all available slots on the HSM:

./p11ng-cli.sh listslots --lib-file /opt/grep11/pkcs11-grep11-amd64.so

All slots:        [0]
Slots with token: [0]
ID: 0, Label: GREP11 Token

CODE

To generate a P-256 EC signing key:

./p11ng-cli.sh generatekeypair --lib-file /opt/grep11/pkcs11-grep11-amd64.so --slot-ref SLOT_LABEL --slot "GREP11 Token" --alias ecp256nr1 --key-spec prime256v1 --key-usage SIGN

Enter slot login password:
Generated key pair with alias ecp256nr1

CODE

To run a simple test using this key to sign, for 5 seconds:

$ ./p11ng-cli.sh signperformancetest --lib-file /opt/grep11/pkcs11-grep11-amd64.so --slot 0 --alias ecp256nr1 --signature-algorithm SHA256WithECDSA --time-limit 5000

Enter slot login password:
Running signing test with 1 threads using signature algorithm SHA256WithECDSA.
Using cache for reading keys.
Starting thread 0
Number of operations for thread 0: 20
Total number of signings: 20
Signings per second: 2.907399331298154

CODE

When confirmed working correctly, you can go ahead and create a Crypto Token in EJBCA (CA Functions>Crypto Tokens).

For more information about crypto tokens, used for storing cryptographic keys in EJBCA, see Crypto Tokens Overview.