Skip to main content

Troubleshooting

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

Guidance​

  • Check that your application/user is part of the "primus" group.
  • Ensure the PKCS#11 library is correctly installed and configured.
  • Check that the PKCS#11 provider configuration file (primus.cfg) is correctly set up with the proper parameters.
  • Check that the slot id or token label (in your application config) matches the definition in the primus.cfg.
  • In case telnet is working but a Connectivity Test with ppin -t reports an error, clarify the validity of login credentials.
  • Update to the latest version of the PKCS#11 provider to ensure compatibility and bug fixes.
  • Check the Error Codes below to narrow down the problem.
  • Consult the PKCS#11 provider documentation for specific troubleshooting steps.

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 myuser

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​

The ppin tool allows to test connectivity to all defined HSMs and partitions (version 1.8.1+):

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

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 table below lists some error codes of the Securosys provider (in the log file) or the ppin tool:

Error CodeDescription
0x0nnnnnnnDefault PKCS#11 failure (see OASIS PKCS#11 standard or pkcs11.h file)
0x8nnnnnnnSecurosys specific errors
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 withCloudHSM for free.
Other questions?Ask Sales.
Last updated on
Feedback
Need help?