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). Early testing with the Java PKCS#11 Provider (PKCS#11 Crypto Token) indicates that some functionality does not work out-of-the-box, such as EC keys.

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:

  1. Download and follow the instructions on the IBM Cloud GitHub page.

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

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:

  1. Configure the file according to instructions in the IBM Cloud HPCS documentation topic Set up the PKCS #11 configuration file.

  2. 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:

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

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

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

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:

  1. To build p11ng-cli with ant, run:

    ant p11ng-cli
    cd dist/p11ng-cli

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

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

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

  5. When confirmed working correctly, you can go ahead and create a Crypto Token in EJBCA (CA Functions>Crypto Tokens).
    images/download/attachments/181290720/ibm_hpcs.png

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