Thales Data Protection on Demand (DPoD) is a cloud HSM service by Thales, which is backed by a Luna 7 "like" hardware. You can use DPoD from any EJBCA software installation where you can add and configure the Thales client.

Once you have access to DPoD and can create an HSM Service, you can find documentation on how to install and configure it in Thales HSM on Demand Services Documentation.

Create a DPoD HSM on Demand Service
- Create Service and Download Client
Configure the EJBCA Instance to Use the HSM on Demand Service
Generate Keys
List and Test Keys Used by EJBCA
Create Crypto Token and CA in EJBCA
Use Multiple DPoD Services from Same EJBCA Instance
Useful Luna Commands
Adding DPoD Drivers to a Container
- Starting the container

Create a DPoD HSM on Demand Service

The following provides a brief walk-through of setting up and connecting to a DPoD HSM on Demand Service.

Create Service and Download Client

To create the service and download the client, do the following:

Log into your DPoD account to display the Accounts main page.
To add a service, click the Services tab and then click Add New Service.
To create a new service for HSM on Demand, click Try Service to start the wizard.
Review the terms of the service and click Next.
Specify a name for the service and select Remove FIPS restrictions to allow the use of non-FIPS algorithms such as other than NIST EC curves, or Ed25519, and then click Next.
Review and click Finish.
Click Create Service Client to get the client download package, which includes the certificates needed to connect to the service.
Specify the name of the service client and click Create Service Client.
Click Download Client.

The service is now created and the DPoD service client is downloaded.

Configure the EJBCA Instance to Use the HSM on Demand Service

The steps for configuring the EJBCA instance to use the HSM on Demand service consist of installing the client package and initializing the partition on the HSM service.

Install HSM Client

The following covers installing the HSM client.

Except for the DPoD client, it is also possible to use the standard Luna HSM client. The following section describes the DPoD client.

To install the DPoD client:

Copy the downloaded service client zip file to the AWS instance.

scp setup-my_dpod_service.zip user@ejbca-host:.
Log in to the instance with SSH.

ssh user@ejbca-host
Unzip the downloaded client archive in /opt/thales/dpodclient.
You can use another location but the PKCS#11 driver in this directory will be automatically detected in EJBCA version 7.5.0 and later.

sudo mkdir -p /opt/thales/dpodclient

sudo unzip -d /opt/thales/dpodclient/ setup-my_dpod_service.zip

cd /opt/thales/dpodclient/

sudo tar -xvf cvclient-min.tar

You do not have to be root to run the Luna client, but installing the driver as root prevents other OS users to modify files. You however have to be able to write temporary files where you run to command source ./setenv below.
Check the connectivity with the HSM:

sudo su

source ./setenv

./bin/64/lunacm

lunacm (64-bit) v10.2.0-111. Copyright (c) 2020 SafeNet. All rights reserved.

Available HSMs:

Slot Id -> 3

Label -> my_dpod_service

Serial Number -> 1392941677399

Model -> Cryptovisor7

Firmware Version -> 7.3.0

CV Firmware Version -> 1.4.0

Configuration -> Luna User Partition With SO (PW) Signing With Cloning Mode

Slot Description -> Net Token Slot

FM HW Status -> FM Not Supported

Current Slot Id: 3

Initialize Partition

Before using the HSM, you need to initialize the partition to create the access credentials that are later used to access the HSM from EJBCA.

The slot used in the example below is slot number 3, which is the number presented above when running the lunacm command. Use the slot number of your HSM. To use the partition, you need to create a Security Officer and a Crypto Officer. The Crypto Officer is the user in the HSM that can create objects and use them, i.e. an R/W User. Luna also defines a Crypto User which is a Read-Only User. This is typically not used from EJBCA as it does not allow to generate keys and no Crypto User is therefore created in the example below.

Do not reuse the random passwords below, create your own random passwords.

Although it does not sound like a secret, the domain is also a secret and you should use your own random value for domain name. According to Thales documentation:

"The security domain, or cloning domain, is a special-purpose secret that is attached to a partition on an HSM."

Ensure to store your secrets securely (best practice for production is under multi-person control). If you forget the secrets you may have to delete the service completely and lose all your keys.

To initialize the partition to create the access credentials:

lunacm:>slot set -slot 3
	Current Slot Id: 3 (Luna User Slot 7.3.0 (PW) Signing With Cloning Mode)
Command Result : No Error
 
lunacm:>partition init -label my_dpod_service
 
	Enter password for Partition SO: W3nDwUr9TQQeZq4G
	Re-enter password for Partition SO: W3nDwUr9TQQeZq4G
 
	You are about to initialize the partition.
	All contents of the partition will be destroyed.
	Are you sure you wish to continue?
 
	Type 'proceed' to continue, or 'quit' to quit now ->proceed
 
	Option -domain was not specified. It is required.
 
	Enter the domain name: LWVjU8hqjwZBM5M4
	Re-enter the domain name: LWVjU8hqjwZBM5M4
 
Command Result : No Error
 
lunacm:>role login -name Partition SO
 
	enter password: W3nDwUr9TQQeZq4G
 
Command Result : No Error 
 
lunacm:>role init -name Crypto Officer
 
	enter new password: RmKSPD7ec8uEZYB7
	re-enter new password: RmKSPD7ec8uEZYB7
 
Command Result : No Error
 
lunacm:>role logout
 
lunacm:>role login -name Crypto Officer
 
	enter password: RmKSPD7ec8uEZYB7
 
Command Result : No Error 
 
lunacm:>role changepw -name Crypto Officer
 
	enter existing password: RmKSPD7ec8uEZYB7
	enter new password: vpvTWX2pws4LkpuF
	re-enter new password: vpvTWX2pws4LkpuF
 
Command Result : No Error

No need to add a Crypto User as the Crypto Officer is used to generate keys in the slot.

Export Client Path

When using the DPoD client on a machine, you need to export a setting to point to where the DPoD client is installed.

export ChrystokiConfigurationPath=/opt/thales/dpodclient

This needs to be executed before any of the CLI commands below can be run, or you will get error messages that the client cannot be located.

Restart EJBCA

As you have added a new PKCS#11 provider, and set a new environment variable, EJBCA needs to be restarted in order to find the new provider.

Generate Keys

You can generate keys using either the UI or the CLI. Using the CLI is a quick way to test the functionality of the HSM.

The following displays an example for generating keys, one RSA and one ECDSA, on a slot using the password of the Crypto Officer from above.

$ ./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/thales/dpodclient/libs/64/libCryptoki2.so 2048 rsa2048Key 3
Using Slot Reference Type: Slot Number.
PKCS11 Token [SunPKCS11-libCryptoki2.so-slot3] Password: 
2020-11-24 11:10:29,535 INFO  [org.cesecore.keys.util.SignWithWorkingAlgorithm] Signature algorithm 'SHA256WithRSA' working for provider 'SunPKCS11-libCryptoki2.so-slot3 version 1.8'.
Created certificate with entry rsa2048Key.
 
$ ./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/thales/dpodclient/libs/64/libCryptoki2.so secp256r1 secp256r1Key 3
Using Slot Reference Type: Slot Number.
PKCS11 Token [SunPKCS11-libCryptoki2.so-slot3] Password: 
2020-11-24 11:15:24,722 INFO  [org.cesecore.keys.util.SignWithWorkingAlgorithm] Signature algorithm 'SHA224withECDSA' working for provider 'SunPKCS11-libCryptoki2.so-slot3 version 1.8'.
Created certificate with entry secp256r1Key.

If using P11-NG you can also use this CLI. Note this must only be used if you also use P11-NG from your EJBCA instance.

./p11ng-cli.sh generatekeypair --lib-file /opt/thales/dpodclient/libs/64/libCryptoki2.so --slot-ref SLOT_NUMBER --slot 3 --alias ed25519_1 --key-spec Ed25519

List and Test Keys Used by EJBCA

The following displays an example of listing and testing all keys that could be used by EJBCA:

$ ./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /opt/thales/dpodclient/libs/64/libCryptoki2.so 3
Test of keystore with ID 3.
PKCS11 Token [SunPKCS11-libCryptoki2.so-slot3] Password: 
 
Testing of key: secp256r1Key
Private part:
SunPKCS11-libCryptoki2.so-slot3 EC private key, 256 bitstoken object, sensitive, unextractable)
Elliptic curve key:
  Named curve: P-256
  the affine x-coordinate: c6a961d42a2250d576114b2e9093f3f53ff101319f9542fde0e3417086e56734
  the affine y-coordinate: 6051307ab40eb9e68fb704e0599f0d69e5b27277cbfd9b88bb71f1ed7f864eb2
Signature test of key secp256r1Key: signature length 70; first byte 30; verifying true
Signings per second: 31
No encryption possible with this key.
 
Testing of key: rsa2048Key
Private part:
SunPKCS11-libCryptoki2.so-slot3 RSA private key, 2048 bitstoken object, sensitive, unextractable)
RSA key:
  modulus: 9f8aa059480e8097d7db4afb2448f12f8d529b99eb010f5c294c9cb838a848e1b99959e08037a96387a4ad52b1cdf9c9262a9f4e09c46c8aafa1ef08d78c830fdf0b90d102d0e131658d44df984d17b04034705fb737b7e5a9aa698b6722774e527aa350e9aac7b478b0d184f468345ad71fbd8afc18e10667f003174e0ff90034380a667ea0eae0978fa7673237451c92f62c49d445e95d29df767f4bb45abf2f1030186ac8e9d76dd8854a5257c28d1a0a58221f3df333c9599b606fd205ef46b3fdc6c95c5b72e8163bb861c7f1b4d7c76a00973ec17dd7239e09da7f902947125ef69e42f714ffcd00002e4958ea702059b7985e62c8bee7785baf345d33
  public exponent: 10001
Signature test of key rsa2048Key: signature length 256; first byte 11; verifying true
Signings per second: 29
Decryptions per second: 30

Or with P11-NG:

./p11ng-cli.sh listobjects --lib-file /opt/thales/dpodclient/libs/64/libCryptoki2.so --slot-ref SLOT_NUMBER --slot 3
./p11ng-cli.sh signperformancetest --lib-file /opt/thales/dpodclient/libs/64/libCryptoki2.so --slot-ref SLOT_NUMBER --slot 3 --alias ed25519_1 --sign-algorithm Ed25519

Create Crypto Token and CA in EJBCA

To create a PKCS11 Crypto Token with the DPoD HSM, first ensure that EJBCA knows the location of the PKCS#11 driver library.

As of EJBCA 7.5.0 and later versions, the below configuration is included by default.

Reference the PKCS#11 library file in conf/web.properties in EJBCA, by adding the following two lines (find a good location after lib nr 23):

cryptotoken.p11.lib.24.name=Thales DPoD

cryptotoken.p11.lib.24.file=/opt/thales/dpodclient/libs/64/libCryptoki2.so
Build and redeploy EJBCA:

ant clean deployear

After starting EJBCA, you can generate a new PKCS#11 Crypto Token utilizing the Thales DPoD library, using either the EJBCA Admin UI or the EJBCA CLI.

Create Crypto Token Using Admin UI

To create a PKCS#11 Crypto Token using the Admin UI:

In the EJBCA Admin UI, click Crypto Tokens under CA Functions, and then click Create new.
Enter the following on the New Crypto Token page:
- Type: PKCS#11
- PKCS#11 : Library: Thales DPoD
- PKCS#11 : Reference Type: Slot/Token Label
  
  Note that you may have to wait a few seconds for the token label to be listed since the labels are read from the remote HSM.
  
  Make sure the environment variable ChrystokiConfigurationPath as defined above is set for JBoss/WildFly in order for the process to be able to use the PKCS#11 connection to the DPoD service.
Enter the Crypto Officer password as Authentication Code, and click Save.
Now you should get a list of keys (which is none on a new slot), and a possibility to generate new key pairs.
Generate keys needed for a CA.

With the created crypto token, you can now go ahead and create CAs, using keys on the DPoD HSM.

Create CA Using the EJBCA Admin UI

To create a CA using the Web UI:

In the EJBCA Admin UI, click Certification Authorities under CA Functions.
In the Add CA field, specify a CA Name and click Create.
On the Create CA page, select the following:
- Crypto Token: Select the newly created Thales DPoD crypto token name.
- Signing Algorithm: Select SHA256WithRSA.
  EJBCA will recognize the key names specified in step Create Crypto Token Using Admin UI and pre-populate the key fields.
Enter a Validity in days, for example 365d for one year validity of the CA.
Scroll down to the bottom of the page and click Create.

That completes the process of creating a Certification Authority using EJBCA in AWS, with keys from a DPoD Cloud HSM partition.

Create Crypto Token Using CLI

You can optionally create crypto tokens using the EJBCA CLI. To create the same crypto token as above, run the following:

bin/ejbca.sh cryptotoken create --token "Thales DPoD Tomas Test2" --pin null --type PKCS11CryptoToken --lib /opt/thales/dpodclient/libs/64/libCryptoki2.so --slotlabeltype SLOT_LABEL --slotlabel "tomas_ejbca_test_1" --autoactivate false

Use Multiple DPoD Services from Same EJBCA Instance

It is currently not possible to use multiple DPoD Services (HSMs) from one instance of EJBCA. Due to the required environment variable ChrystokiConfigurationPath, one process can only use one DPoD Service.

Useful Luna Commands

The following lists useful native Luna cmu commands.

To list objects and their handles (ouid):

bin/64/cmu list -display=index,class,keyType,label,ouid

If you have created keys with native commands, or imported keys, there is probably no certificate object as required by Java PKCS#11 provider. To create a self-signed certificate referencing the private handle, run:

bin/64/cmu selfSigncertificate -id=0  -CN="caSign00001" -startDate=20020101 -endDate=20451231 -serialNum=0133337f

This will list and ask for which ouid to use.

Adding DPoD Drivers to a Container

There are multiple ways to add HSM drivers to containers. You can add a file system layer with a docker-compose as described on the Keyfactor GitHub, or you can mount in the needed files as described here.

In EJBCA versions prior to 7.5.0, you need to configure EJBCA to find the driver. On the host where you will run your docker, create an updated web.properties with the additional driver entry (nr 24) according to the following:

As of EJBCA 7.5.0 and later versions, the below setting in web.properties should not be set.

sudo mkdir -p /opt/primekey/ejbca/conf
 
echo "httpserver.pubhttp=80
httpserver.pubhttps=443
httpserver.privhttps=443
httpserver.external.privhttps=443
web.reqcertindb=false
 
#cryptotoken.p11.lib.114.file=/opt/primekey/cloudhsm/lib/libliquidsec_pkcs11.so
 
cryptotoken.p11.lib.255.name=P11 Proxy
cryptotoken.p11.lib.255.file=/opt/primekey/p11proxy-client/p11proxy-client.so
cryptotoken.p11.lib.255.canGenerateKeyMsg=ClientToolBox must be used to generate keys for this HSM provider.
# Normally key generation will be allowed via the UI
cryptotoken.p11.lib.255.canGenerateKey=true
 
# Enable usage of Azure Key Vault Crypto Token in the Admin UI
keyvault.cryptotoken.enabled=true
 
# Enable usage of AWS KMS Crypto Token in the Admin UI
awskms.cryptotoken.enabled=true
web.docbaseuri=disabled
 
cryptotoken.p11.lib.24.name=Thales DPoD
cryptotoken.p11.lib.24.file=/opt/thales/dpodclient/libs/64/libCryptoki2.so
" | sudo tee -a "/opt/primekey/ejbca/conf/web.properties"

Starting the container

Assuming you have the working drivers in /opt/thales/dpodclient as described above, you can simply start a container mounting the modified configuration and the DPoD client in the container filesystem, as pointing the environment variable to it.

sudo docker run -it --rm --name thales_test -p 80:8080 -p 443:8443 -v /opt/primekey/ejbca/conf/web.properties:/etc/ejbca/conf/web.properties -v /opt/thales:/opt/thales -e ChrystokiConfigurationPath=/opt/thales/dpodclient registry.primekey.se/primekey/ejbca-ee:7.4.3-5

To verify that files are mounted, run a shell in the container:

sudo docker ps
sudo docker exec -ti thales_test /bin/bash
ls -al /opt/thales

Log into the Admin UI of EJBCA in the container instance to create a DPoD Crypto Token and use it.

You can enroll for the keysture with the URL: https://localhost/ejbca/enrol/keystore.jsp

And after installing the superadmin.p12, access the Admin UI at: https://localhost/ejbca/adminweb