Skip to main content

Tutorial: OpenSSL v1.x CLI

Securosys HSM Integration Guide​

You can use the OpenSSL command-line interface (CLI) to interact with the Primus HSM through the PKCS#11 Engine Plugin, enabling secure communication between your applications and the HSM. The OpenSSL CLI serves as a versatile tool for various cryptographic operations, including key management and certificate generation, while leveraging the security features of the Primus HSM. For a comprehensive guide on available commands and options, refer to the OpenSSL manpage, which provides a detailed overview of all supported functionalities and usage instructions.

Generating Key Pair, Certificate Signing Request (CSR), and Importing Certificate​

In this section, we will guide you through the steps of generating a key pair, creating a Certificate Signing Request (CSR), and importing a certificate into the Primus HSM. First, you will use the pkcs11-tool to generate an RSA or EC key pair within the HSM, ensuring secure key generation and storage. Next, we’ll demonstrate how to create a CSR using OpenSSL, allowing you to request a certificate from a Certificate Authority (CA) based on the generated key. Finally, you will show how to import the issued certificate back into the HSM using the pkcs11-tool, completing the process of securing your key pair and certificate within the HSM environment.

note

The following examples use the OpenSSL command-line interface with a customized configuration for the Primus HSM PKCS#11 provider, as described here. The HSM partition is mounted as slot 0.

Generate a Key Pair​

Generating a new key pair using pkcs11-tool: 2048-bit RSA, CKA_SENSITIVE set, using slot 0:

pkcs11-tool --module "C:\Program Files\Securosys\Primus P11\primusP11.dll" --slot=0 \
   -l -p <PKCS11 PIN> --keypairgen --key-type RSA:2048 \
   --id 1001 --label myrsakey --sensitive
note

Replace <PKCS11 PIN> with the PKCS#11 PIN of your HSM.

After successfully executing the command, the output will look like as follows:

Using slot 0 with a present token (0x0)
Key pair generated:
Private Key Object; RSA 
 label: myrsakey
 ID: 1001
 Usage: decrypt, sign, unwrap
Public Key Object; RSA 2048 bits
 label: myrsakey
 ID: 1001
 Usage: encrypt, verify, wrap

Create a CSR​

Generate the CSR interactively, using openssl by referencing the key ID on the HSM by the key ID:

openssl req -engine pkcs11 -new \
   -key "pkcs11:token=<partition-name>;id=%10%01;type=private" \
   -keyform engine -out rsa.hsm.csr -sha256 -verify

Replace <partition-name> with the name of your partition on your HSM.

note

Notice that pkcs11-tool writes the key id in hexadecimal notation to the HSM (e.g. %10%01)

After successfully executing the command, the output will look like as follows:

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:CH
State or Province Name (full name) []:ZH
Locality Name (eg, city) [Default City]:Zuerich
Organization Name (eg, company) [Default Company Ltd]:Securosys SA
Organizational Unit Name (eg, section) []:IT
Common Name (eg, your name or your server's hostname) []:cos8.securosys.ch
Email Address []:cos8@securosys.ch
…
verify OK

Alternatively, you can issue a self signed certificate using openssl:

openssl req -engine pkcs11 -new -x509 \
   -key "pkcs11:token=<partition-name>;id=%10%01;type=private" \
   -keyform engine -out rsa.hsm.crt -sha256 -days 365 -nodes
note

Notice that pkcs11-tool writes the key id in hexadecimal notation to the HSM (e.g. %10%01)

Import the Certificate​

If required, import the signed certificate *.hsm.crt (der format), using pkcs11-tool:

pkcs11-tool --module "C:\Program Files\Securosys\Primus P11\primusP11.dll" -l \
   -p <PKCS11 PIN> --slot=0 --write-object rsa.hsm.crt \
   --type cert --id 1001 --label myrsakey
note

Replace <PKCS11 PIN> with the PKCS#11 PIN of your HSM.

After successfully executing the command, the output will look like as follows:

Using slot with ID 0x0
Created certificate:
Certificate Object; type = X.509 cert
 label: myrsakey
 subject: DN: C=CH, O=Securosys SA, OU=IT, CN=cos8.securosys.ch
 ID: 1001