Securosys support
This chapter describes how to set up a cloud-based Securosys HSM using the PrimusAPI_PKCS11 library version 1.8.6.
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.
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.logThen, add the following line to /etc/logrotate.d/syslog:
/var/log/primusAfter 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.
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:InfoThen test the library itself, by executing the following code snippet:
testPrimus --pin=<PKCS#11 password> --datafile=</path/to/file>infoThe 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.SignVerifyIf 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
OPENSSL_ENGINES=/opt/nevisproxy/lib/engines
export OPENSSL_ENGINESYou can now restart the proxy.