Skip to main content

Troubleshooting

This guide contains common troubleshooting steps to resolve problems with the Primus PKCS#11 Provider.

Overview​

For basic troubleshooting, please do the following:

  1. Group Concept: Check that your application/user is part of the "primus" group.
  2. Network Connectivity: Use telnet and ppin --test to check that network-layer access works.
  3. Log analysis: Review the log file for details about the problem.
  4. Error codes: Check the list of error codes.
  5. Update to the latest version of the PKCS#11 provider to rule out bugs that have already been fixed.

Additionally, review your configuration:

  1. PKCS#11 Provider configuration: Check that the primus.cfg contains the correct values.
  2. Application configuration: Check that your application uses the correct parameters. For example, the slot id or token label should match the primus.cfg.

Group Concept​

By default, the PKCS#11 provider files (libraries, executables, configuration) are assigned to the "primus" group. Any user or application account intending to use the provider must be added to this group to access the necessary files.

$ ls -la /etc/primus/
total 28
drwxr-xr-x   2 root   root   4096 Jul  9 16:52 .
drwxr-xr-x 110 root   root   4096 Jul 22 14:48 ..
-rw-r-----   1 primus primus  916 Jun 30 14:34 .secrets.cfg
-rw-rw----   1 primus primus 4172 Jul  7 14:01 primus.cfg

Check whether the user account is part of the "primus" group, using the groups command. If the account is not a member, add it by executing:

sudo usermod -a -G primus app-user

Adding a user to a new group may require logout/login or reboot to update permissions (as temporary workaround you may use newgrp primus or sudo login -f <user>).

Connectivity Test​

Test basic network connectivity with telnet (press Ctrl+C to exit):

$ telnet ch01-api.cloudshsm.com 2310
Trying 31.10.228.252...
Connected to ch01-api.cloudshsm.com.
Escape character is '^]'.
tip

In CloudHSM, the IP allowlist may block network-level access.

If network access works, use the ppin tool to check that you can authenticate to the HSM partitions:

$ ppin --test [--hsm hsm] [--user HSM_USERNAME]
Load config file: '/etc/primus/primus.cfg'

hsm0: Connect to '82.197.162.10' on port 2411 with priority 0, firmware: RP-3.2.4-T 
    slot0 (id=2), user=DEMO-TEST: OK

Number of tested HSMs: 1 (number of partitions: 1)
Number of failures: 0

To test that your application user can access the provider, run ppin as that user:

sudo -u app-user /usr/local/primus/bin/ppin --test

If telnet is working but ppin -t reports an error, check that the login credentials are valid.

pkcs11-tool (from OpenSC package)​

The pkcs11-tool from the OpenSC package (v0.19 or newer) allows to list PKCS#11 slots, manage keys and many other operations on the HSM partition (see man pages).

The following example lists all PKCS#11 slots, showing partition slot/token information:

pkcs11-tool --module /usr/local/primus/lib/libprimusP11.so -L
Available slots:
Slot 0 (0x2): DEMO-TEST                  Slot number (index), Partition name
  token label        : DEMO-TEST         Partition name
  token manufacturer : Securosys SA
  token model        : PRIMUS HSM
  token flags        : login required, rng, token initialized, PIN initialized, 
                       other flags=0x860
  hardware version   : 3.2               HSM version
  firmware version   : 2.37              Provider version
  serial num         : a7176edc3c192207  Partition serial number (within cluster)
  pin min/max        : 0/32

Login and list objects in slot 0:

pkcs11-tool --module /usr/local/primus/lib/libprimusP11.so --slot 0 -l -p '<pkcs#11_pwd>' -O
Certificate Object; type = X.509 cert
  label:      MS-PrimusByokECP384
Secret Key Object; AES length 16
  VALUE:      1d84346b4daa61c15bc040892aaaa79e
  label:      MS-PrimusByokAES128
  Usage:      encrypt, decrypt, verify, wrap, unwrap
Public Key Object; EC  EC_POINT 384 bits
...
info

The pkcs11-tool test function (-t) is not recommended and may fail due to incompatibilities.

p11tool (GnuTLS package)​

The p11tool from the GnuTLS package also allows similar operations as pkcs11-tool on PKCS#11 tokens (see man pages). The following example lists the available tokens:

p11tool --list-tokens
Token 0:
  URL: pkcs11:model=Primus%20HSM;manufacturer=Securosys%20SA;serial=a7176edc3c192207;
            token=DEMO-TEST
  Label: DEMO-TEST
  Type: Hardware token
  Manufacturer: Securosys SA
  Model: Primus HSM
  Serial: a7176edc3c192207
...

The following example lists all objects on partition DEMO-TEST:

p11tool --login --list-all "pkcs11:token=DEMO-TEST"
Token 'DEMO-TEST' with URL 'pkcs11:model=Primus%20HSM;manufacturer=Securosys%20SA;serial=a7176edc3c192207;token=DEMO-TEST' requires user PIN
Enter PIN: <PKCS#11 password>
Object 0:
  URL: pkcs11:model=Primus%20HSM;manufacturer=Securosys%20SA;serial=a7176edc3c192207;
            token=DEMO-TEST;object=MS-PrimusByokECP384;type=cert
  Type: X.509 Certificate
  Label: MS-PrimusByokECP384
  Flags: CKA_TRUSTED; 
  ID: 35:69

Object 1:
  URL: pkcs11:model=Primus%20HSM;manufacturer=Securosys%20SA;serial=a7176edc3c192207;
            token=DEMO-TEST;object=MS-PrimusByokAES128;type=secret-key
  Type: Secret key
  Label: MS-PrimusByokAES128
  Flags: CKA_WRAP/UNWRAP; CKA_PRIVATE; 
  ID: 81:15
...

Log File Analysis​

The provider log file can be found (as configured in primus.cfg) at following default locations

  • Linux: /tmp/primus.log
  • Windows: %PUBLIC%\Securosys\Primus P11\primus.log

For troubleshooting we recommend the following temporary log settings in primus.cfg log section:

    trace_linenumber    = false;
    trace_timestamp     = true;
    trace_function      = true;
    trace_inout         = false;
    trace_pid           = true;
    trace_filename      = false;
    trace_mask          = 0x01;
    trace_level         = 6;

Note, that the configuration is loaded only when initializing the library (C_Initialize()).

Below is an example of a log file snippet, showing a failure on C_GetSlotInfo(), using pkcs-11tool, due to missing HSM connectivity:

Time-stamp              - Called from      trace_level - function       - log comment

2021-04-07 21:30:20.936 - pkcs11-tool[74481:74481] - 5 - C_Initialize() - rv: 0x0
2021-04-07 21:30:20.936 - pkcs11-tool[74481:74481] - 6 - C_GetSlotInfo() - slotId: 0
2021-04-07 21:30:20.936 - pkcs11-tool[74481:74481] - 6 - C_GetSlotInfo() - pInfo: 0x5509B3C0
2021-04-07 21:30:20.936 - pkcs11-tool[74481:74481] - 6 - connectHSM() - Connecting to HSM 'hsm0'
2021-04-07 21:30:20.972 - pkcs11-tool[74481:74481] - 3 - HSM_Hello() - rv: 0x8000004e
2021-04-07 21:30:20.972 - pkcs11-tool[74481:74481] - 4 - connectHSM() - Failed to login on HSM 82.197.162.10:2415 (slot: 0)
2021-04-07 21:30:20.972 - pkcs11-tool[74481:74481] - 6 - connectHSM() - Connecting to HSM 'hsm0'
2021-04-07 21:30:31.838 - pkcs11-tool[74481:74481] - 4 - receive() - receive failed errno 104l
2021-04-07 21:30:31.839 - pkcs11-tool[74481:74481] - 4 - receiveAnswer() - rcv failed errno 104l
2021-04-07 21:30:31.839 - pkcs11-tool[74481:74481] - 3 - HSM_Hello() - rv: 0x5
2021-04-07 21:30:31.839 - pkcs11-tool[74481:74481] - 4 - connectHSM() - Failed to login on HSM 82.197.162.10:2415 (slot: 0)
2021-04-07 21:30:31.839 - pkcs11-tool[74481:74481] - 3 - C_GetSlotInfo() - rv: 0xe0

The errors are logged with trace_level 3. The PKCS#11 library functions start with C_. The library internal HSM functions start with HSM_. Return value of the functions are logged in the comment with rv: ....

In addition, you can also consult the HSM user log.

Error Codes​

The Primus PKCS#11 Provider and the ppin tool return the following sets of error codes:

  • 0x0nnnnnnn: Standard PKCS#11 return codes, defined in pkcs11t.h.
    • For example, a common error is 0x00000005, meaning CKR_GENERAL_ERROR. In this case, inspect the primus.log file as it will contain further details.
  • 0x8nnnnnnn: Securosys-specific errors codes. These are given in the table below.
Error CodeDescription
0x80000001Unexpected data type
0x80000002Buffer too small
0x80000003Duplicate entry
0x80000004No more keys
0x80000005Public key not found
0x80000006Private key not found
0x80000008Invalid block cipher
0x80000009Invalid mechanism
0x8000000AObject not found
0x8000000BLogin failed, wrong PKCS#11 PIN
0x8000000CUser not logged in
0x8000000DUser not found
0x8000000EWrong password for the key (e.g. keys created with password by JCE or CNG provider)
0x80000012Key not found
0x80000018Max Connections exceeded
0x8000002AKey import not allowed
0x80000037Password expired
0x8000003BConnect Timeout
0x80000058EC Curve Unknown
0x8000005FSession objects disabled by HSM configuration
0x80000069Access to partition disabled by HSM configuration
0x80000084DL Group unknown
0x80000085PQC mode unknown
0x8000008BLicense expired
0x80000097Queue full
0x80005001No HSM/User configured
0x80005002HSM/User configuration already exists
0x80005003Primus configuration file not found
0x80005004Primus secrets file not found
0x80005005Invalid Primus configuration file
0x80005006Invalid Primus secrets file
0x80005007No write access to Primus secrets file
0x80005008Failed to add permanent secret to secrets file
0x80005009Invalid secrets file configuration element
0x80005010Failed to update Primus secrets file
0x80005011Failed to remove permanent secret from Primus secrets file
0x80005012User not found in Primus configuration file
0x80005013Unsupported secret types
0x80005014NULL list pointer
0x80005015Connection to HSM failed (network level, IP not reachable)
0x80005017Login to HSM failed with provided credentials (Setup Password)
0x80005018Setup password expired
0x80005019Access to partition disabled by HSM configuration
0x80005020Invalid magics
0x80005021Wrong protocol version
0x80005022Invalid size
0x80005023Invalid command
0x80005024Invalid parameter
0x80005025Not enough memory
0x80005026HSM missing feature
0xCnnnnnnnHSM system errors
Get started with CloudHSM.
Other questions?Ask Sales.
Last updated on
Feedback
Need help?