Skip to content

Hardware Security Modules (HSM)

TeskaLabs SeaCat PKI supports hardware security modules (HSM) with PKCS#11 interface.

Specifically, HSMs are used for private key generation and management and also for random number generation.

Warning

TeskaLabs SeaCat PKI currently supports only one configured PKCS#11 module, you cannot configure multiple modules in the one PKI instance. You can use multiple tokens of the same module.

Configuration

seacatpki.conf:

[seacatpki:pkcs11:<identification>]
path=/path/to/pkcs11module.so
  • identification is the internal name of the PKCS#11 provider (e.g. softhsm2)

  • path is the location of the PKCS#11 module in the file system

  • session_persistence is a boolean flag that indicates whether the PKCS#11 session should be kept open after use (default is true). Some tokens closes the session after use, so this flag should be set to false for such tokens. Setting this flag to false will impact the performance of the HSM.

Autoscan configuration

This approach means that the PKI will automatically scan the PKCS#11 tokens for available private keys.

seacatpki.conf:

[seacatpki:pkcs11:<identification>]
path=/path/to/pkcs11module.so
tokens=
    SoftHSMToken1,PIN1,tenant1
    SoftHSMToken2,PIN2,tenant2
    SoftHSMToken3,PIN2,tenant3
    ...
  • tokens is the list of tokens in the HSM

Each token is defined by:

  • token_name is the name of the token (e.g. SoftHSMToken1)
  • pin is the PIN of the token (e.g. PIN1)
  • tenant is the name of the tenant that has access to the token (e.g. tenant1)

Explicit configuration

This approach means that the PKI will use only the private keys that are explicitly configured in the seacatpki.conf file.

[seacatpki:pkcs11:<identification>]
path=/path/to/pkcs11module.so

[seacatpki:private_key:<keyname>]
provider=pkcs11:<identification>
tenants=tenant1,tenant2
token_label=SoftHSMToken1
pin=PIN
cka_id=100002
  • keyname is the internal name of the private key (e.g. my_rsa_key)
  • provider is the internal name of the PKCS#11 module (e.g. softhsm2)
  • tenants is the list of tenants that has access to the token (e.g. tenant1,tenant2)
  • token_label is the label of the token (e.g. SoftHSMToken1)
  • pin is the PIN of the token (e.g. PIN)
  • cka_id is the ID of the private key (e.g. 100002)

Private key requirements

Private keys located at PKCS#11 tokens must have the following requirements:

  • CKA_CLASS must be CKO_PRIVATE_KEY
  • CKA_LABEL must be set
  • CKA_ID must be set and unique for each private key
  • There must be an exportable public key (CKA_CLASS must be CKO_PUBLIC_KEY) with the same CKA_ID