Installation of PKCS#11/OpenSSL with Script

Securosys provides a script with a convenient step-by-step installation wizard. The wizard:

• Guides you through the installation and configuration of the Primus PKCS#11 Provider.
• Optionally: Installs and configures OpenSSL so that it integrates with the Primus PKCS#11 Provider.

This simplifies the installation and removes the need to manually run commands and edit config files. For full control over the installation process, please follow the manual installation guide.

Compatibility

The installer script is tested on the following platforms:

• Debian 12 (PKCS#11 Provider only, no OpenSSL integration)
• Debian 13
• Ubuntu 24.04, 26.04
• Fedora 44
• CentOS Stream 10
• AlmaLinux 10
• Rocky Linux 9

More generally: For the Primus PKCS#11 Provider, the script works on the supported Linux platforms. For the OpenSSL integration, the script works on Linux distributions that provide packages for OpenSSL and the OpenSSL pkcs11-provider.

Step 1: Prepare the HSM

You still need to configure the HSM and your Partition for use with PKCS#11. Follow the configuration instructions from the manual installation guide. In CloudHSM, the Partition has already been configured for you.

Make sure that you have the following values/credentials:

• HSM URL/IP
• HSM PKCS#11 port (default: 2310)
• Partition name
• Setup Password
• PKCS#11 Password

Step 2: Download the script

Download the script.

Step 3: Download the Primus PKCS#11 Provider

Download the ZIP file of the latest Primus PKCS#11 Provider release. Move the ZIP file into the same directory as the script and extract it.

unzip PrimusAPI_PKCS11-v2.8.2.zip

Step 4: Run the script

Run the script to start the installation wizard:

sudo bash install-pkcs11.sh

This will install and configure both the Primus PKCS#11 Provider and the integration with OpenSSL via PKCS#11. The wizard prompts you for all necessary settings, such as your HSM hostname, port, Partition name, Setup Password, and PKCS#11 Password.

For more fine-grained control, the following subcommands are available:

Usage: install-pkcs11.sh <subcommand>

Subcommands:
  install            everything: install-pkcs11, configure-pkcs11, install-openssl, configure-openssl (default)
  install-pkcs11     install/reinstall the Primus PKCS#11 Provider
  install-openssl    install OpenSSL + pkcs11-provider and clear any old openssl.cnf pkcs11 block
  configure-pkcs11   write /etc/primus/primus.cfg and .secrets.cfg
  configure-openssl  write the openssl.cnf pkcs11 block (needs the packages + primus.cfg)
  uninstall          full removal: config (primus.cfg + .secrets.cfg + openssl.cnf pkcs11 block),
                     and packages (Primus PKCS#11 Provider, OpenSSL, pkcs11-provider).
  remove-config      remove primus.cfg + .secrets.cfg and the openssl.cnf pkcs11 block only

Options:
  --help, -h         show this help
  --version, -V      print the installer's release version

Environment variables:
  NO_UNICODE         use ASCII glyphs instead of Unicode, if set to NO_UNICODE=1

What the installer does

The installer automates the manual installation process of both PKCS#11 and OpenSSL.

The script will place and edit files in the following locations:

• /usr/local/primus/
• /etc/primus/
• /etc/ssl/openssl.cnf (appends a pkcs11 provider block)

Additionally, the script will:

• Put /usr/local/primus/bin on PATH system-wide (via /etc/profile.d/primus.sh)
• Add the current user to the primus group (take affect at next login)

Check that it worked

For the Primus PKCS#11 Provider:

ppin --test

This should list your HSM Partition as OK.

For the OpenSSL integration:

openssl list -providers

Both default and pkcs11 should report status: active.

To test that you can use keys on Primus HSM through OpenSSL, see the OpenSSL CLI tutorial.

Troubleshooting

Please follow respective documentation for troubleshooting steps:

• PKCS#11
• OpenSSL