Skip to main content

PKCS#11 Provider Connection Setup

"ppin" Command Line Tool​

The ppin1 command line tool allows

Below is an overview of the different command parameters:

********************
Primus Permanent PIN
********************
parameters:
	-c: optional path to the primus.cfg configuration file.
	-s: optional path to the .secrets.cfg file.
commands:
	ppin -h: 	this message.
	ppin -v: 	PKCS#11 provider version.
	ppin -l: 	list all Primus HSM hosts.
	ppin -a -e <user name> [<setup pwd> <pkcs11 pwd>]: 
 		add permanent secret for user <user name>.
	ppin -u -e <user name> [<setup pwd> <pkcs11 pwd>]: 
 		update permanent secret for user <user name>
	ppin -r -e <user name>: 	remove permanent secret for user <user name>.
	ppin -p -e <user name> [proxy pwd]: 	add proxy password for user <user name>.
	ppin -x -e <user name>: 	remove proxy password for user <user name>.
 	ppin --fetchlog --user <user name> --hsm <hsm or host name> [--reverse] 
 	     [--since YYYY-MM-DD] [--out <file>]: 
 		Dump the HSM log to stdout or a file.
 	ppin {-t | --test} [--user <user name>] [--hsm <hsm or host name>] 
 	     [--slot <slot name>] [--slotid <slot ID>]:
		Test connectivity to all HSMs and partitions 
		in the config file (performs a login).
		Optionally filter by HSM name, user name, 
		slot name, slot ID.
	ppin --fortinet --user <user> [<setup pwd> [<pkcs11 pwd>]] 
		 [--proxyuser <proxy user> [--proxypwd <proxy pwd>]]: 
		 encode secrets config for Fortinet product in base64

The list of possible ppin error codes can be found in the testing and trouble shooting section.

Show Installed Provider Version​

The following command lists the currently installed provider version:

ppin -v
Primus HSM PKCS#11 2.2.4

Overview of Configured HSM Slots, Service Proxies and Status of their Credentials​

The following command lists the defined HSM slots and service proxies, together with their credential status. The example shows

  • two redundant HSM clusters (2 HSMs per Partition-1 and Partition-2), already having fetched the permanent secret and

  • one redundant CloudHSM partition (CLOUDHSMPAR, Service User 'eqabxrfnqqos'), not yet configured at all.

ppin -l
********************
Primus Permanent PIN
********************
[01] slot-id 0:    user 'Partition-1'   permanent secret: Configured
[02] slot-id 1:    user 'Partition-2'   permanent secret: Configured
[03] slot-id 5:    user 'CLOUDHSMPAR'  permanent secret: MISSING
[04] slot-id 0:    user 'Partition-1'   permanent secret: Configured
[05] slot-id 1:    user 'Partition-2'   permanent secret: Configured
[06] slot-id 5:    user 'CLOUDHSMPAR'  permanent secret: MISSING
[01] service/proxy user 'eqabxrfnqqos'  permanent secret: MISSING
[02] service/proxy user 'eqabxrfnqqos'  permanent secret: MISSING

Fetch Partition Log​

Get the HSM user log of a specific partition and HSM as configured in primus.cfg configuration file since specified date:

ppin --fetchlog --user HSM_USERNAME --hsm hsm1 --since 2021-04-01
Dump log starting from 2021-04-01 00:00 UTC
Fetching log from HSM.
Number of slots: 1
2021 Apr  1 09:31:28 UTC NUFENEN notice MSCNG Process: Login request: User: DEMO-TEST Client: SecurosysKspCfg@W10C-TESTCLIENT@192.168.76.76@00:0c:29:73:e6:7b with setup password over TCP connection 536870926 (IP 178.198.217.194:31550)
2021 Apr  1 09:31:28 UTC NUFENEN info MSCNG Process: Login successful: User: DEMO-TEST Client: SecurosysKspCfg@W10C-TESTCLIENT@192.168.76.76@00:0c:29:73:e6:7b over TCP connection 0x2000000e (IP 178.198.217.194:31550)
2021 Apr  1 09:31:29 UTC NUFENEN notice Crypto Process: Interaction: User: DEMO-TEST, Client: SecurosysKspCfg@W10C-TESTCLIENT@192.168.76.76@00:0c:29:73:e6:7b, Protocol: mscng, Retrieved permanent login credentials
2021 Apr  1 09:31:29 UTC NUFENEN notice MSCNG Process: Disconnect: User: DEMO-TEST Client: SecurosysKspCfg@W10C-TESTCLIENT@192.168.76.76@00:0c:29:73:e6:7b over TCP connection 536870926 (IP 178.198.217.194:31550)
2021 Apr  1 09:31:29 UTC NUFENEN info Crypto Process: Usage statistics: User: DEMO-TEST, Client: SecurosysKspCfg@W10C-TESTCLIENT@192.168.76.76@00:0c:29:73:e6:7b, Protocol: mscng, Total key usage count: 0
...
2021 Apr  1 09:35:47 UTC NUFENEN err Crypto Process: Error: Command: CommandGetKeyFlag, User: DEMO-TEST, Client: hsmcons@W10C-TESTCLIENT@192.168.76.76@00:0c:29:73:e6:7b, Protocol: mscng, 0x12 (C_GetAttributeValue: Requested attribute type is not valid)
2021 Apr  1 09:35:48 UTC NUFENEN err Crypto message repeated 11 times: [ Process: Error: Command: CommandGetKeyFlag, User: DEMO-TEST, Client: hsmcons@W10C-TESTCLIENT@192.168.76.76@00:0c:29:73:e6:7b, Protocol: mscng, 0x12 (C_GetAttributeValue: Requested attribute type is not valid)]

As --hsm <hsm or host name> parameter you can use hsmx (x=0...n) reference, or the host name, exactly as configured in primus.cfg. The HSM configuration must allow log fetching via API. Please note that the log ring buffer could overwrite old entries. Consult the HSM User Guide for description of the different log entries.

Connection Test​

The ppin tool allows to test connectivity to all defined HSMs and partitions, and optional arguments help to select a specific HSM or partition (provider 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, firmware: RP-2.10.0-T 
    slot0 (id=2), user=DEMO-TEST: OK

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

FortiGate Secret String​

The FortiGate firewall with built-in PKCS#11 provider v2.2.4+ requires the secrets file as base-64 encoded string, fetched on a client PC using the following command:

ppin --fortinet --user <username> [<setupPassword> <PKCS11Password>] [--proxyuser <proxyUserName> [--proxypassword <proxyPassword>]]
# Fortinet secret to be loaded:
dmVyc2lvbiA9ICIxLjAiOwpwcmltdXMgOiAKewogIHVzZXJzIDogCiAgewogICAgdXNlcjAgOiAKICAgIHsKICAgICAgbmFtZSA9ICJQUklNVVNERVYzNjgiOwogICAgICBdpY3MgPSAiMzcwYzJj
... 
GUwY2Y4ZjNhNTkwMzE2ZjE4MGI4YWZlNDdiMzY1Nzg1ZWQ3NyI7CiAgICB9OwogIH07Cn07Cg==

For details consult the FortiGate Integration Guide.

Footnotes​

  1. On Windows platforms called ppin.exe ↩