Installation

This guide shows how to integrate OmniTrust PKI with a Securosys Primus HSM or CloudHSM.

Prerequisites

• A Securosys Primus HSM or CloudHSM.
• A Docker environment to deploy OTPKI in.
• A server to deploy the Primus PKCS#11 Provider and the OTPKI PKCS#11 Proxy on.

Step 1: Install OTPKI

Follow the OmniTrust documentation to install OTPKI into your Docker environment (Docker Compose on a local machine, Kubernetes, ...).

Step 2: Install the Primus PKCS#11 Provider

Install the Primus PKCS#11 Provider on a server of your choice. This server should be reachable from OTPKI, and it should be able to reach the HSM. Please follow this installation guide to install and configure the provider.

To test basic connectivity to the HSM:

$ /usr/local/primus/bin/ppin --test

Load config file: '/etc/primus/primus.cfg'

hsm0: Connect to 'ch01-api.cloudshsm.com' on port 2310 with priority , firmware: RE-3.2.9
    slot0 (id=0), user='MY-PARTITION': OK

Number of tested HSMs: 1 (number of partitions: 1)
Number of failures: 0

If it fails, follow the PKCS#11 Provider troubleshooting steps.

Step 3: Install the OTPKI PKCS#11 Proxy

Install the OTPKI PKCS#11 Proxy on the same machine as the Primus PKCS#11 Provider. Please follow this installation guide to install, configure, and run the proxy.

The config.yaml should look like this:

module_path: /usr/local/primus/lib/libprimusP11.so
listen_address: ":8051"

modules:
  pkcs11.base:

hsm_configs:
  - id: primus
    label: "Primus HSM"
    # slot_id: 0
    default: true

As the id, you can choose any identifier. Clients of the proxy will use this id to select the HSM. This is the id which you will enter in the OTPKI UI.

As the label, set the HSM partition name (this is the token label). As the slot_id, set the numeric id that you assigned to the partition in the /etc/primus/primus.cfg file. Setting either label or slot_id is sufficient.

You can view the currently available tokens, their slot IDs, and their token labels with either of the following commands:

pkcs11-tool --module /usr/local/primus/lib/libprimusP11.so --list-token

/usr/local/primus/bin/ppin --list

If you are running the OTPKI PKCS#11 Proxy as an unprivileged Unix user, add this user to the primus group. This ensures that the user can access the Primus PKCS#11 Provider files.

sudo usermod -aG primus otpki

Step 4: Connect OTPKI to the Proxy

Configure OTPKI to use PKCS#11 as the key storage backend. Please follow this guide.

Next Steps

Follow the OmniTrust PKI documentation for more information about operating OTPKI.