SoftHSMv2¶

SoftHSM is a software cryptographic store accessible through a PKCS#11 interface. It is an emulator of a Hardware Security Module (HSM) that runs on the main CPU.

TeskaLabs SeaCat PKI supports SoftHSMv2.

More at: http://www.softhsm.org

Tip

SoftHSMv2 is available in the TeskaLabs SeaCat PKI Container image.

SoftHSM2 preparation¶

1) Prepare a SoftHSM2 configuration file

softhsm2.conf:

directories.tokendir = ...softhsm/tokens/
objectstore.backend = file
log.level = INFO

Note

directories.tokendir is a location of where SoftHSM2 stores private keys and other objects.

2) Specify the location of the SoftHSM2 configuration file

export SOFTHSM2_CONF=.../softhsm2.conf

Note

SOFTHSM2_CONF environment variable must be set also for TeskaLabs SeaCat PKI microservice runtime.

3) Initialize token

% softhsm2-util --init-token --free --label "MySoftHSMToken"
Slot 0 has a free/uninitialized token.
=== SO PIN (4-255 characters) ===
Please enter SO PIN: ********
Please reenter SO PIN: ********
=== User PIN (4-255 characters) ===
Please enter user PIN: ******
Please reenter user PIN: ******
The token has been initialized and is reassigned to slot 1735718982

--free means that the first free/uninitialized token in SoftHSM2 instance will be used.

The User PIN is used in the configuration of the token in secatpki.conf.

Danger

label has to be a unique token label in the SoftHSM2 instance.

Running softhsm2-util in the Docker container

$ docker exec -it softhsm2-util --init-token --free --label "MySoftHSMToken"

4) Add a SoftHSM2 modeule in SeaCat PKI configuration

secatpki.conf:

[seacatpki:pkcs11:softhsm2]
path=.../libsofthsm2.so
tokens=
    MySoftHSMToken,<pin>,mytenant

The token "MySoftHSMToken" will be made available to the tenant "mytenant".

Tip

softhsm2 is an internal name of provider and can be chosen freely.

4) Restart SeaCat PKI microservice

Generation of the private key¶

Private keys can be generated from SeaCat PKI web interface or using pkcs11-tool command line tool. The later approach is described here.

Generate EC private key¶

pkcs11-tool --module .../libsofthsm2.so --login --token-label "MySoftHSMToken" --keypairgen --label "ECKey" --id 100001 --key-type EC:brainpoolP384r1

Generate RSA private key¶

pkcs11-tool --module .../libsofthsm2.so --login --token-label "MySoftHSMToken" --keypairgen --label "RSAKey" --id 100002 --key-type RSA:2048

Danger

--id is a unique identifier of the private key in the token and must be provided.

Add a SoftHSM2 private key explicitly¶

You may want to add a private key explicitly into SeaCat PKI configuration.

secatpki.conf:

[seacatpki:private_key:softhsm2_key]
provider=pkcs11:softhsm2
tenants=tenant1,tenant2
token_label=MySoftHSMToken
pin=<PIN>
cka_id=100001

Random Number Generator¶

SoftHSM2 can be used as random number generator (RNG) in TeskaLabs SeaCat PKI. It is not practical but possible.

Initialize a dedicated token for RNG:

$ softhsm2-util --init-token --free --label "MyRandomNumberGenerator"

secatpki.conf:

[seacatpki:random]
provider=pkcs11:softhsm2
pin=<PIN>
token_label=MyRandomNumberGenerator

Troubleshooting¶

RuntimeError: Initialisation error (not initialized). Should never see this.

You need to set SOFTHSM2_CONF environment variable properly.