Skip to main content
Version: 7.2402.x.x RR

Securosys support

This chapter describes how to set up a cloud-based Securosys HSM using the PrimusAPI_PKCS11 library version 1.7.32.

Experimental

Support for Securosys cloud-based HSM is still experimental.

For performance reasons, we recommend increasing the 'keep alive' timeout to at least ten seconds. This may avoid too many cryptographic calls to the HSM. For this, set the KeepAliveTimeout parameter in the navajo.xml configuration file to at least "10". See also the performance measures in chapter Performance measurements for the cloud-based Securosys HSM.

note

The procedure may change in a future release of the HSM, so always see the vendor's documentation to set up the HSM.

Set up a cloud-based Securosys HSM

Step 1: Acquire the PrimusAPI

  • Download the PrimusAPI for PKCS#11 from support.securosys.ch.

  • Navigate to the downloaded .tar file:

    sudo tar -xvzf PrimusAPI_PKCS11-xxx.tar.gz -C /
    export PRIMUS_HOME=/usr/local/primus
    export PATH=$PRIMUS_HOME/bin:$PATH
    export LD_LIBRARY_PATH=$PRIMUS_HOME/lib:$LD_LIBRARY_PATH
    sudo groupadd primus
    cd /usr/local
    sudo chgrp -R primus primus
    sudo usermod -a -G primus <user>
  • For easier usage, put the exports into ~/.bashrc.

Step 2: Configure logging and primus.cfg

  • Add this line to /etc/rsyslog.conf:

    # Save primus messages also to primus.log
    syslog.* /var/log/primus.log
  • Then, add the following line to /etc/logrotate.d/syslog:

    /var/log/primus
  • After that, edit the global settings in the file primus.cfg, under /usr/local/primus/etc. For example:

    Editing the global settings
    /* This is the global configuration section */
    primus:
    {
    wait_delay = 250; /* in ms*/
    wait_max_tries = 5;
    /* This is the hsm configuration section */
    hsms:
    {
    hsm0:
    {
    host = "a-api.cloudshsm.com";
    port = "2310";
    slots:
    {
    slot0:
    {
    client_id = "julia_smith";
    user_name = "GIULIA";
    proxy_user = "the_proxy_user"; /* or remove if no proxy needed */
    id = 0;
    }; /* end slot0 */
    }; /* end slots */
    }; /* end hsm0 */

    hsm1:
    {
    host = "b-api.cloudshsm.com";
    port = "2310";
    slots:
    {
    slot0:
    {
    client_id = "julia_smith";
    user_name = "GIULIA"
    proxy_user = "the_proxy_user"; /* or remove if no proxy needed */
    id = 0;
    }; /* end slot0 */

    }; /* end slots */
    }; /* end hsm1 */
    }; /* end hsms */

    /* This is the log configuration section */
    log:
    {
    file = "/tmp/primus.log"; /* optional for unix, logs to LOCAL1 syslog*/
    trace_linenumber = true;
    trace_function = true;
    trace_inout = true;
    trace_filename = true;
    trace_mask = 0x01;
    trace_level = 7; /* 0-7 log level details */
    }; /* end log */

    /* This is the openssl configuration section */
    openssl:
    {
    slotId = 0;
    lib = "/usr/local/primus/lib/libprimusP11.so";
    user_pin = "<PKCS11_PIN>";
    deferredInit = false;
    enableDigest = true;
    enableRand = true;
    enableRSA = true;
    enableSSLv3 = true;
    enableTrcLvl = true;
    }; /* end openssl */
    }
    }

Step 3: Add a service proxy password

If you plan to use a HSM that has been set up already, you can skip this section and the next two. In this case,

  • Proceed with placing the file .secrets under /usr/local/primus/etc.
  • Test whether it has been successful with the command ppin -l.

After editing the file primus.cfg, you have to configure the secrets. Proceed as follows:

  • Navigate to the folder /usr/local/primus.

  • Configure the secret for the proxy_user:

    Configuring the secret for the proxy user
    [@localhost primus]$ ppin -p -e the_proxy_user

    ********************
    Primus Permanent PIN
    ********************
    Provide proxy password for 'the_proxy_user' :

    ********************
    Primus Permanent PIN
    ********************
    [01] user 'GIULIA' has no permanent secret configured
    [02] user 'GIULIA' has no permanent secret configured
    [01] proxy user 'the_proxy_user' has permanent secret configured
    [02] proxy user 'the_proxy_user' has permanent secret configured

    -BYE

Step 4: Add the PKCS#11 password

The next step is to configure the permanent secret. Proceed as follows:

  • Navigate to the folder /usr/local/primus.

  • Provide the connection password (5x5 digit) and the PKCS#11 secret password (8 digit):

    Providing the permanent secrets
    [@localhost primus]$ ppin -a -e GIULIA

    ********************
    Primus Permanent PIN
    ********************
    Provide connection password for 'GIULIA' :
    Provide PKCS11 password for 'GIULIA' :

    ********************
    Primus Permanent PIN
    ********************
    [01] user 'the_proxy_user' has permanent secret configured
    [01] proxy user 'the_proxy_user' has permanent secret configured

Step 5: Copy the configuration files

Since version 1.7.32, the primary location lookup when initializing the PKCS#11 library has been changed.

  • Navigate to the folder /usr/local/primus/etc.

  • Copy the .secrets.cfg and primus.cfg to the folder /etc/primus/.

    Initially the directory and files do not exist. Add the directory and copy the files from the fallback location (/usr/local/primus/etc), and adjust the access rights. It is recommended to use the primary location.

caution

Do not overwrite or lose the .secrets file!

Step 6: Test the connection and library

  • First, test the connection by executing the following code snippet:

    testPrimus --pin=<PKCS#11 password> --datafile=</path/to/file> --gtest_filter=libC_GTest_P11:Info
  • Then test the library itself, by executing the following code snippet:

    testPrimus --pin=<PKCS#11 password> --datafile=</path/to/file>

    info

    The data file is a non-empty file with data to encode. It is a "must have" for the tests.

  • If everything is alright, you should see something like this:

    Successful test result
    [----------] Global test environment tear-down
    [==========] 461 tests from 16 test cases ran. (1918201 ms total)
    [ PASSED ] 432 tests.
    [ FAILED ] 29 tests, listed below:
    [ FAILED ] libC_GTest_DSA.Generate_MinSize
    [ FAILED ] libC_GTest_DSA.Sign_MinSize
    [ FAILED ] libC_GTest_DSA.Sign_MaxSize
    [ FAILED ] libC_GTest_DSA.SignSha1_MinSize
    [ FAILED ] libC_GTest_DSA.SignSha1_Chunked_MinSize
    [ FAILED ] libC_GTest_DSA.SignSha1_MaxSize
    [ FAILED ] libC_GTest_DSA.SignSha1_Chunked_MaxSize
    [ FAILED ] libC_GTest_DSA.SignSha256_MinSize
    [ FAILED ] libC_GTest_DSA.SignSha256_Chunked_MinSize
    [ FAILED ] libC_GTest_DSA.SignSha256PKCS_MaxSize
    [ FAILED ] libC_GTest_DSA.SignSha256PKCS_Chunked_MaxSize
    [ FAILED ] libC_GTest_DSA.SignSha384_MinSize
    [ FAILED ] libC_GTest_DSA.SignSha384_Chunked_MinSize
    [ FAILED ] libC_GTest_DSA.SignSha384_MaxSize
    [ FAILED ] libC_GTest_DSA.SignSha384_Chunked_MaxSize
    [ FAILED ] libC_GTest_DSA.SignSha512_MinSize
    [ FAILED ] libC_GTest_DSA.SignSha512_Chunked_MinSize
    [ FAILED ] libC_GTest_DSA.SignSha512_MaxSize
    [ FAILED ] libC_GTest_DSA.SignSha512_Chunked_MaxSize
    [ FAILED ] libC_GTest_ObjectManagement.CheckROSession
    [ FAILED ] libC_GTest_ObjectManagement.CreatePublicKeyInROSession
    [ FAILED ] libC_GTest_Sessions.PublicUserRWSession
    [ FAILED ] libC_GTest_Sessions.PublicUserROSessionAlreadyLogged
    [ FAILED ] libC_GTest_chacha20.CreateKey
    [ FAILED ] libC_GTest_chacha20.GenerateKey
    [ FAILED ] libC_GTest_chacha20.EncryptDecrypt
    [ FAILED ] libC_GTest_poly1305.CreateKey
    [ FAILED ] libC_GTest_poly1305.GenerateKey
    [ FAILED ] libC_GTest_poly1305.SignVerify

    If the tests went well, the HSM is ready to use.

Step 7: Operate the HSM

To operate the HSM, use the provided OpenSSL with the primus engine, the nevisproxy_pkcs11 tool (see: "Appendix E - Cryptoki interface and utility"), and the pkcs11 tool. Proceed as follows:

  • Navigate to the folder /usr/local/primus/openssl/1.0.2m/bin/. This folder includes the pre-configured OpenSSL version.

  • Check whether the primus engine is ready to use, by executing the following code snippet:

    [@localhost bin]$ ./openssl engine primus -t
    (primus) Primus engine support
    [ available ]
  • Create keys on the HSM with OpenSSL (and export them to our machine):

    genrsa -engine primus -out proxy.rsa.priv.key 2048

Creating a self-signed certificate with the extracted key

[@localhost bin]$ ./openssl req -x509 -engine primus -new -key proxy.rsa.priv.key -out proxy.cert.pem -days 3650
engine "primus" set.
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) [AU]:CH
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Nevis Security AG
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:localhost
Email Address []:
[badam@localhost bin]$ ll
total 652
-rwxrwxr-x. 1 5144 Feb 18 19:30 c_rehash
-rwxrwxr-x. 1 637008 Feb 18 19:30 openssl
-rw-rw-r--. 1 1204 May 14 14:59 proxy.cert.pem
-rw-rw-r--. 1 457 May 14 14:50 proxy.rsa.priv.key

Importing the signed certificate

The easiest way to import the signed certificate is via the nevisproxy_pkcs11 tool:

[@localhost bin]$ ./nevisproxy_pkcs11 -library /usr/local/primus/lib/libprimusP11.so -certimp -file proxy.cert.pem -label proxycertificate -id 1000 -verify
PKCS#11 User PIN for Slot 0 (PRIMUS X-Series):
Imported certificate: certificate object handle: 1681692777

Checking the contents of the HSM

To check the contents of the HSM, perform a login with the nevisproxy_pkcs11 tool (which is more verbose than the other tool), or with the pkcs11 tool:

[@localhost bin]$ pkcs11-tool --module /usr/local/primus/lib/libprimusP11.so -login -O

Using slot 0 with a present token (0x0)
Logging in to "PRIMUS X-Series".
Enter User PIN:
Certificate Object; type = X.509 cert
label: proxy.cert
subject: DN: C=CH, O=Nevis Security AG, CN=localhost
ID: 1001
Private Key Object; RSA
label: daa5c1252c20a5b5
Usage: decrypt, sign, unwrap
Public Key Object; RSA 2048 bits
label: daa5c1252c20a5b5
Usage: encrypt, verify, wrap

Deleting from the HSM

The following code block shows how to delete from the HSM:

[@localhost bin]$ ./nevisproxy_pkcs11 -library /usr/local/primus/lib/libprimusP11.so -login -delete -all
PKCS#11 User PIN for Slot 0 (PRIMUS X-Series):

-- Found 4 matching objects on slot 0 (PRIMUS X-Series) --

[1]
Object handle #1681692777
size: <information unavailable>
attribute LABEL (size 16): proxycertificate (70:72:6f:78:79:63:65:72:74:69:66:69:63:61:74:65)

[2]
Object handle #1714636915
size: <information unavailable>
attribute LABEL (size 10): proxy.cert (70:72:6f:78:79:2e:63:65:72:74)

[3]
Object handle #1957747793
size: <information unavailable>
attribute LABEL (size 16): daa5c1252c20a5b5 (64:61:61:35:63:31:32:35:32:63:32:30:61:35:62:35)

[4]
Object handle #424238335
size: <information unavailable>
attribute LABEL (size 16): daa5c1252c20a5b5 (64:61:61:35:63:31:32:35:32:63:32:30:61:35:62:35)

Delete which object? [1 - 4] (for exit type anything else)1

Deleted object #1 (handle #1681692777)

Step 8: Configure navajo.xml

The final step is to adjust the file navajo.xml. Proceed as follows:

  • In the SSL tag of the file navajo.xml, configure the parameters SSLCertificateFile and SSLCertificateKeyFile as follows:

    SSLCertificateFile="pkcs11:library=/usr/local/primus/lib/libprimusP11.so&dologin=true&objectlabel=proxy.cert&type=cert&pinenv=PKCS11_PIN&cache=false"
    SSLCertificateKeyFile="pkcs11:library=/usr/local/primus/lib/libprimusP11.so&dologin=true&objectlabel=daa5c1252c20a5b5&type=privkey&pinenv=PKCS11_PIN&cache=false"
  • Add the following code block to the file env.conf:

    PKCS11_PIN=...
    export PKCS11_PIN

    PKCS11_PIN_ENVIRONMENT_AHEAD=true
    export PKCS11_PIN_ENVIRONMENT_AHEAD

  • You can now restart the proxy.