SSH access to the Discoverer and Discoverer+ login nodes using PKCS#11 HSM and PIV devices (smart cards)

Important

This document does not provide information about how to use HSM and PIV devices for SSH authentication on Windows systems. This is due to problematic HSM and PIV support on Windows systems - different abstraction layers and frequent driver compatibility issues that can break functionality after system updates. This guide is specifically designed for Linux and macOS users.

Introduction

What HSM and PIV devices are

HSM (Hardware Security Module) is a physical device that provides secure cryptographic operations and key storage. HSM devices are designed to protect sensitive cryptographic material from unauthorized access and tampering. HSM devices are more expensive, but they are more powerful and can be used for other purposes like key management, data encryption, etc. Some HSM devices support FIPS/NIST standartisations. Here we are particularly interested in HSM devices that support PKCS#11 interface and operations with assymetric key pairs (RSA, ECDSA).

PIV (Personal Identity Verification) devices are smart card-based authentication tokens that make use of the FIPS 201 standard, originally developed for U.S. federal government employee identification. Note that some PIV devices do not strictly follow FIPS 201 standard (always check the device specifications). PIV devices are designed as multi-purpose identity tokens for authentication, digital signing, and secure communication. PIV devices are cheaper, but they are less powerful and rarely be used for other purposes than authentication and digital signing. For instance, it is rare to find a PIV device that provides data encryption. Here we are particularly interested in PIV devices that support PKCS#11 interface and operations with assymetric key pairs (RSA, ECDSA).

Warning

Limited or no support for ED25519 curve: Although most HSM and PIV devices currently available in the market support operations with public key algorithms, this support is typically restricted to RSA and NIST-P elliptic curves. The vendors’ attempt to conform to FIPS or other standards is the reason for that limitation. Some devices, like the SmartCard HSM, can support a wider variety of elliptic curves, including Brainpool curves. However, it is exceedingly uncommon to acquire an HSM or PIV device that validates the ED25519 curve. A contributing factor to the absence of support is the fact that X.509v3 certificates are incompatible with the ED25519 keys. Given that post-quantum cryptography has already entered the market, it is improbable that the companies that manufacture HSM and PIV devices will allocate resources to the implementation of ED25519 support in the cryptographic protocol. As they move forward with the adoption of post-quantum algorithms for digital signing and key exchange, they intend to cease improving the implementation of traditional public key algorithms.

Both HSM and PIV devices typically consist of:

  1. Smart card: A credit card-sized or SIM-sized device containing:
    • Secure microprocessor with tamper-resistant protection
    • Protected memory for storing private keys and certificates (it may supports different slots for storing private keys and certificates that can be used for different purposes)
    • Cryptographic engine for performing signing and encryption operations (PIV devices may not support data encryption operations)
  2. USB card reader: Provides the interface between the smart card and the computer system

Note

Many modern HSM and PIV devices combine both components into a single monolithic USB device for convenience and security. Also note that it is very rare to obtain HSM devices that do not support PKCS#11 interface. While some PIV devices may not support PKCS#11 interfaces. Always check the device documentation to ensure it supports assymetric key pair generation and signing operations through PKCS#11 interface.

Key differences between HSM and PIV devices

Aspect HSM Devices PIV Devices
Primary purpose Cryptographic operations and key storage Identity verification and authentication
Security focus High-security crypto operations Multi-purpose identity management
Key storage Protected memory with tamper-resistant design Standard smart card storage with basic protection
Cryptographic engine Dedicated secure processor Standard smart card processor
Use cases Document signing, SSH authentication, encryption System login, physical access, document signing, SSH auth
Standards compliance PKCS#11, various crypto standards FIPS 201, PIV standard

HSM or PIV backed SSH authentication using PKCS#11 as a key provider

Important

PKCS#11 is a standardized interface that allows applications (like SSH clients and SSH agents) to use the keys stored on the HSM and PIV devices. Therefore PKCS#11 acts as a formal SSH key provider. Its presence is necessary because without it neither the SSH agent nor the SSH client can list and utilize for signing operations the private keys residing in the HSM and PIV devices protected memory.

Keeping the SSH private keys on HSM and PIV devices and using PKCS#11 as a key provider is safer than storing the key files on the local filesystem:

Aspect
Traditional private key file storage
(~/.ssh/id_rsa, ~/.ssh/id_ecdsa)
 HSM/PIV device storage
private key location Stored as files on filesystem Stored in protected memory, never leaves device
key access Direct file access by applications Through PKCS#11 interface only
security risk Vulnerable to file system attacks, cold boot attacks Protected by tamper-resistant hardware
key operations Performed in system memory Performed inside secure processor
portability Keys can be copied, backed up, moved Keys may not be extracted or copied
compromise risk High - keys accessible to malware, unauthorized users Low - keys protected protected even on compromised systems

PKCS#11 interface can be accessed through the OpenSC library, which is supported on Linux, macOS, and other operating systems, or based on vendor-provided drivers.

Important

Only HSM and PIV devices that support public key cryptography (RSA, ECDSA) and provide PKCS#11 interfaces can be employed for SSH authentication on Linux and macOS. These are essential requirements for the SSH client to communicate with and utilize the smart card device for authentication operations. Note that the private keys are stored in protected memory within the device and never leave this secure environment. All cryptographic operations (signing, encryption) are performed by the secure processor inside the device, ensuring that private keys remain protected even when the device is connected to potentially compromised systems. The later does not mean that the use of HSM and PIV devices on a compromised system can proted your data - it just protects the private key stored in the device.

SSH authentication works by having the SSH client perform digital signing operations using the private key from the asymmetric key pair stored in the protected memory of the HSM or PIV device (the SSH agent facilitates the communication between the SSH client and the HSM or PIV device). The SSH server then validates these signatures using the corresponding public key that has been registered in the server-side authorized keys file.

HSM and PIV devices that store X.509v3 certificates, and can perform digital signing operations through their PKCS#11 interface, can also be used for key-based SSH authentication. This is possible because both digital signing and SSH authentication use the same underlying asymmetric key pair - the private key for signing operations and the public key (which is embedded in the X.509v3 certificate) for verification. Therefore, any smart card device that contains a private key corresponding to a public key in its stored X.509v3 certificate, and provides a PKCS#11 interface, can be used for SSH authentication.

Warning

Discoverer and Discoverer+ setup: The SSH servers running on Discoverer and Discoverer+ login nodes are configured to use key-based authentication only. We do not validate X.509v3 certificates on the SSH servers, and therefore we do not intercept, check, or store any X.509v3 metadata (subject, subject alternative names, etc.). This ensures user privacy by not collecting any personal information from the certificates.

Using PKCS#11 HSM and PIV devices provided by the EU-Recognized PKI certificate authorities for qualified document signing

Note

This part of the document provides implementation guidelines for using HSM and PIV devices with PKCS#11 interface, sold and supported by any of the EU-recognised PKI certificate authorities for qualified document signing, for performing SSH authentication on the Discoverer and Discoverer+ login nodes.

The EU regulation No 910/2014 of the European Parliament and of the Council of Europe requires the private keys to the qualified X.509v3 certificates for creating Qualified Electronic Signatures (QCQES) to be stored on devices with secure memory and cryptographic capabilities (processing and storing private keys and certificates). Both HSM and PIV devices satisfy those technical requirements.

HSM and PIV devices for qualified digital signing

In most cases the EU-recognized PKI certificate authorities for qualified document signing provide PIV devices for their customers (it is rare to receive full featured HSM devices from them). That practice exists because the PIV devices are more general-purpose identity tokens, and they are cheaper, while HSM devices are specialized cryptographic security modules. Very few users need HSM devices for their purposes. On the other side, the HSM devices are more expensive. Also, the goal of those devices is to provide secure authentication (login) and signing capabilities, while the HSM devices are more general-purpose and can be used for other purposes like key management, encryption, etc. Therefore, in most cases the term “smart card” used by those PKI services vendors refers to PIV devices. Good example of such devices are the widely spread IDEMIA PIV smart cards, provided by TS-CNS for accessing health services in Italy. Such PIV devices are also provided by PKI certificate authorites in Bulgaria, Latvia, Lithuania, and other member countries of the European Union.

Users who can sign contract with EU-recognized PKI certificate authorities for qualified digital signing of documents usually receive ready-to-use PIV or HSM devices that contain:

  • Asymmetric key pairs (RSA or ECDSA) generated and stored within the device (usually in a slot dedicated for signing operations)
  • Stored X.509v3 certificates for qualified digital document signing, based on the generated asymmetric private and public keys (also in the same slot)

Warning

Upon receiving the HSM or PIV device, ensure it has PKCS#11 Linux and macOS support that works (or insist of having that kind of device). If there is a lack of direct OpenSC support, those devices should come with third-party PKCS#11 interface libraries (drivers) supported on various operating systems to support the cryptographic operations with the stored keys and certificates. Those libraries are the most important component in our case, because without a properly installed PKCS#11 library, the SSH agent and SSH client cannot request digital signing on the HSM or PIV device.

The users usually receive their HSM or PIV devices along with a key pair (generated on spot in the office of the PKI certificate authority) and at least one X.509v3 certificate installed in the device, after successfully complete the following process:

  1. Initial application: The user visits the office of the chosen PKI certificate authority (CA)
  2. Contract signing: The user signs a contract for PKI services
  3. Payment: The user pays for the PKI services and the provided PIV (or HSM) device
  4. Device initialization: The operator of the PKI certificate authority initializes the HSM or PIV device (in person, usually right after signing the contract)
  5. Key pair generation: The operator connects the device to the corresponding service in the PKI infrastructure and a new key pair (private key + public key) is generated and stored in the protected memory of the device (RSA or ECDSA algorithm (NIST-P) is used for the key pair generation)
  6. CSR generation: On completion, the generated private (signing) key is used to generate a Certificate Signing Request (CSR)
  7. Certificate issuance: The generated CSR is sent to the PKI signing authority system
  8. Certificate installation: After the CSR is approved (usually that is done automatically), the issued X.509v3 certificate is sent back and installed in the protected memory of the device.

Note

Any HSM or PIV device that has successfully finished the previously mentioned process and has the necessary PKCS#11 support on Linux and macOS can be used to remotely access the Discoverer and Discoverer+ login nodes via the SSH protocol after a successful SSH public key registration in our user database.

Installation of the software components

This is the most specific part of the document. In most cases, the vendor of PKI services provides the customers with cheap PIV devices that usually lack OpenSC support and therefore cannot be used as PKCS#11 provider without installing specific libraries (drivers). Ask for receiving a copy of those software components and then install them following the instrictions provided by the vendor.

In case your device is one with proper OpenSC support, or you successfully installed the third-party PKCS#11 library (driver) on your system and tested that it works, you can proceed with the next step. Otherwise, call the PKI services vendor support and solve the problem.

Here we can give an example with the installation of the software components for the IDEMIA PIV devices.

  1. Get the software components from the vendor.

Visit the vendor’s website and download the software components for your operating system:

Select the package for your operating system and download it. In my case that is the RPM package file:

  1. Install the software components.
sudo dnf install ./libbit4xpki-1.4.10-647-idemia.x86_64.rpm
  1. Test the token and the PKCS#11 library installation.
pkcs11-tool --module  /usr/lib/libbit4xpki.so --list-objects --login

In case the installation is successful, and the device is properly pluggged and detected, you should be able to list the objects stored in the device:

Using slot 0 with a present token (0x0)
Logging in to "FLZ-Anstalt".
Please enter User PIN:
Public Key Object; RSA 2048 bits
  label:      {39d04780-26bb-4960-bda9-5c77746a8343}
  ID:         ab7bf450812e5aec64fb93e4b14bc5e128ab0ef9
  Usage:      encrypt, verify, wrap
  Access:     local
  uri:        pkcs11:model=COSMO%20v9.1;manufacturer=IDEMIA;serial=1040000000280321;token=FLZ-Anstalt;id=%ab7bf450812e5aec64fb93e4b14bc5e128ab0ef9;object={39d04780-26bb-4960-bda9-5c77746a8343};type=public
Certificate Object; type = X.509 cert
  label:      {39d04780-26bb-4960-bda9-5c77746a8343}
  ID:         ab7bf450812e5aec64fb93e4b14bc5e128ab0ef9
  uri:        pkcs11:model=COSMO%20v9.1;manufacturer=IDEMIA;serial=1040000000280321;token=FLZ-Anstalt;id=%ab7bf450812e5aec64fb93e4b14bc5e128ab0ef9;object={39d04780-26bb-4960-bda9-5c77746a8343};type=cert
Private Key Object; RSA
  label:      {39d04780-26bb-4960-bda9-5c77746a8343}
  ID:         ab7bf450812e5aec64fb93e4b14bc5e128ab0ef9
  Usage:      decrypt, sign, unwrap
  Access:     sensitive, always sensitive, never extractable, local
  uri:        pkcs11:model=COSMO%20v9.1;manufacturer=IDEMIA;serial=1040000000280321;token=FLZ-Anstalt;id=%ab7bf450812e5aec64fb93e4b14bc5e128ab0ef9;object={39d04780-26bb-4960-bda9-5c77746a8343};type=private
  1. Try loading the public key into the SSH agent.

First, connect the PKCS#11 interace to the SSH agent:

ssh-add -s /usr/lib/libbit4xpki.so

You should be asked for the User PIN of the device. And if you provide the correct PIN, the following output should be displayed:

Enter passphrase for PKCS#11:
Card added: /usr/lib/libbit4xpki.so

Second, list the keys accessible through the PKCS#11 interface:

ssh-add -L

In the generated list you should see the public key of the device in SSH public key format:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDNNAou+DVekns+rlnLxY9oOdzsvIdiWc74THCpMPI47ljvDwmLt6p8TJUi9uuOfqofc7W2DNGAEAiOKSMEa32W09BAfAOjUg4eDGCHxwTmr4dFOGN2QKxUxknFqbLlK2uQulx+ylYdPi31WXAcVFUcH+a14NGk31PB71UkKEd8HC385KTSkWGT3jbs5ln8FPbJ+9620aTqsTbssQaqvyP87FvIRhpcdrb1/8nQ3VuHMXdP4fIyn0gLebkNWgMOfEkO0jLR0NkH45ofV8JQvwsUMGhbAFl8zf53AIpzwCmVkUBJ4GexATIqiVCZx5jURNp7Aq/bxMU1UBbO7CJiYW1Z {39d04780-26bb-4960-bda9-5c77746a8343}

Extracting the public key for registering

See Loading the identities from PKCS#11 provider into the SSH agent. Exporting the public SSH key below for understanding how to obtain copy of the public key that should be sent to us for registration.

Using your own PKCS#11 HSM or PIV devices

Warning

This part of the document covers the “bring your own HSM or PIV device” cases, where users can use their own HSM or PIV devices for SSH authentication. Therefore, these devices are not obtained through a contract with EU-recognized PKI certificate authorities.

Security considerations

Warning

Before purchasing any HSM or PIV device, verify its OpenSC compatibility by checking the OpenSC supported cards list and testing on your target operating systems.

Important

Consider the device’s country of origin and vendor reputation. Avoid devices produced by vendors in jurisdictions that may require implementing backdoors or compromise device security.

Installation of the software components

Most probably, you have some or most of the components, which installation is recommended below. Anyway, run the suggested commands to ensure everything needed is already in your system:

Linux systems

# RHEL/Rocky Linux/Fedora
sudo dnf install opensc openssh-clients
# Debian/Ubuntu
sudo apt-get install opensc opensc-pkcs11 libp11-3 openssh-client

macOS systems

# Using Homebrew
brew install opensc openssh

Generate key pair directly on the HSM or PIV device

First, check if the HSM or PIV device supports at least RSA keys (≥2048 bits) and ECDSA (≥384 bits):

# You may need to change the full path to the module to match your OpenSC installation
pkcs11-tool --module /usr/lib64/opensc-pkcs11.so --list-mechanisms

The output that verifies the necessary support is available will include the following:

ECDSA-SHA384, keySize={192,521}, sign, verify
ECDSA-SHA512, keySize={192,521}, sign, verify
...
RSA-X-509, keySize={1024,4096}, hw, decrypt, sign, verify
RSA-PKCS, keySize={1024,4096}, hw, decrypt, sign, verify

If the examined HSM or PIV device does not support those key sizes, we recommend obtaining a more modern (up-to-date) one.

Limit the number of key pairs available in the HSM or PIV device

Warning

The fewer private keys on your HSM or PIV device, the better for SSH authentication. When the SSH agent loads the PKCS#11 provider, it discovers ALL private keys on the device. The SSH client then attempts authentication with each key sequentially until one succeeds.

Here is an example. If your HSM or PIV device contains 4 private keys, but only 1 is registered for your user on the SSH server, the authentication process will fail 3 times before succeeding. Most SSH servers (including our login nodes) have rate limiting that bans IP addresses after a certain number of consecutive failed attempts.

Example bad scenario:

  • Your HSM or PIV device has 4 private keys (IDs 01, 02, 03, 04)
  • Only key #04 is registered for your user on the SSH server running on our login nodes
  • SSH client tries key #01 → FAIL (1st failure)
  • SSH client tries key #02 → FAIL (2nd failure)
  • SSH client tries key #03 → FAIL (3rd failure)
  • SSH client tries key #04 → SUCCESS (but server may have already banned your IP)

Therefore, use HSM or PIV devices with no more than 3 private keys for SSH authentication to avoid triggering rate limits on the SSH servers running on the login nodes.

Key-pair generation process

Warning

At this point, you must know at least the User PIN of the device to unlock its protected memory and utilize the key generation process. It is recommended to also know the SO-PIN in case you lock the device by entering a wrong PIN too many times.

Important

Knowing the SO-PIN does not necessarily mean you can unblock the User PIN if it is blocked. If the HSM or PIV device was initialized with a policy where the SO-PIN can only be used only for device initialization and cannot reset the User PIN, then the only remaining option is to reset the device completely. This would result in the loss of all stored keys and certificates, which could be catastrophic for your SSH access and other services.

First, check if your HSM or PIV device already contains key pairs (you may need to change the full path to the module to match your OpenSC installation):

# List private keys (requires PIN)
pkcs11-tool --module /usr/lib64/opensc-pkcs11.so --list-objects --type privkey --login

This check is necessary to verify you have at least one usable key pair on the examined device. For the same reason, you can list the installed public keys with --type pubkey. However, keep in mind that public keys can be stored in the device’s memory without their corresponding private keys, which can create a false impression. Therefore, to make sure you have the entire list of key pairs that might be appropriate for SSH authentication, always list the private keys. Also mind the presence of --login in the command line. In order to use the private keys, the PIN must be provided.

In case you already have private keys usable for authentication on the device, go to Loading the identities from PKCS#11 provider into the SSH agent. Exporting the public SSH key and learn how to extract the public keys and communicate them with us, so we can register them with your POSIX account you have with us on Discoverer and Discoverer+. Otherwise continue with the instructions given below.

If your HSM or PIV device does not already contain a key pair, or if the existing key pairs use weak algorithms (RSA < 2048 bits, ECDSA < 384 bits), you can generate a new one directly on the device using pkcs11-tool. This ensures the private key is generated within the secure environment of the device and never leaves the device.

Note

The --id parameter must reference a slot that is not already occupied (that is why we recommend listing the private keys first before starting a new key pair generation) - this does not work on SmartCard HSM and Nitrokey HSM 2 (read below):

# Generate ECDSA key pair on HSM or PIV device (384 bits minimum, requires PIN)
pkcs11-tool --module /usr/lib64/opensc-pkcs11.so \
    --login --keypairgen --key-type ec:secp384r1 \
    --id 01 --label "SSH-Key-ECDSA"

# Generate RSA key pair on HSM or PIV device (2048 bits minimum, requires PIN), only if you cannot generate or use ECDSA keys
pkcs11-tool --module /usr/lib64/opensc-pkcs11.so \
    --login --keypairgen --key-type rsa:2048 \
    --id 02 --label "SSH-Key-RSA"

Warning

DKEK-provisioned HSM restriction (may affect the use of Smart Card HSM and Nitrokey HSM 2): If your SmartCard HSM is already provisioned with DKEK shares, the keys generated using pkcs11-tool will be stored in the HSM protected memory, but may not be displayed or selectable for use. In such cases, users must rely on the SmartCard HSM documentation to add keys using PKCS#12 files using the saved as files DKEK share. Therefore, before attempting to generate new keys, verify if your SmartCard HSM device has DKEK shares configured.

See Loading the identities from PKCS#11 provider into the SSH agent. Exporting the public SSH key below for understanding how to obtain copy of the public key that should be sent to us for registration.

Bring your existing SSH key to the HSM or PIV device

Warning

As previously mentioned, the majority of HSM and PIV devices do not support the ED25519 curve. Consequently, we will not be discussing importing private keys from ~/.ssh/id_ed25519 here.

Here we consider the situation when you already have your SSH private key, saved as ~/.ssh/id_ecdsa, ~/.ssh/id_rsa, or stored as a part of a PKCS#12 file. For that purpose, be sure your HSM or PIV device supports the import of private keys. Some devices may not provide such a functionality, or you need to use tools different than those provided by OpenSC.

Important

SmartCard HSM and Nitrokey HSM2: Direct import of private keys into HSM devices using pkcs11-tool or pkcs15-init is not supported by SmartCard HSM and Nitrokey HSM2 devices. The recommended approach there is to use DKEK shares for importing private keys stored in PKCS#12 files.

In case you need to import ~/.ssh/id_ecdsa or ~/.ssh/id_rsa keys into such type of HSM or PIV devices, you need first to convert those keys into PKCS#12 files (generating and adding a formal X.509v3 certificate on top of each private key):

# Generate a formal self-signed X.509v3 certificate from the private key (validity is of no significance here)
openssl req -new -x509 -key ~/.ssh/id_ecdsa -out /tmp/my.crt -days 3650 -subj "/CN=SSH-ECDSA-Key"

# Create PKCS#12 container with private key and certificate (use single password!)
openssl pkcs12 -export -in /tmp/my.crt -inkey ~/.ssh/id_ecdsa -out /tmp/my.p12 -name "SSH-ECDSA-Key"

And then follow the instructions provided here:

SmartCard HSM documentation

Nitrokey HSM documentation

to import the created PKCS#12 file (/tmp/my.p12) into the HSM or PIV device using DKEK shares. The same applies to the case when you already have PKCS#12 file derived without converting ~/.ssh/id_ecdsa or ~/.ssh/id_rsa.

Important

YubiHSM 2: YubiHSM 2 devices support import of asymmetric private keys using wrapped key material. The device can import RSA and ECDSA private keys that are properly wrapped.

Here we need to convert the PKCS#12 file into YubiHSM 2 wrapped format and import the result into the protected memory:

  1. Extract private key from PKCS#12:
# Extract private key from PKCS#12 file
openssl pkcs12 -in your_key.p12 -nocerts -out private.pem
  1. Create Wrap key (if not already present):
# Create Wrap key file
echo -en '\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xaa\xbb\xcc\xdd\xee\xff' > wrap.key

# Import Wrap key into YubiHSM 2
yubihsm-shell -p password -a put-wrap-key -i 20 -c all --delegated all --informat bin --in wrap.key
  1. Wrap the private key:
# For RSA keys
yubihsm-wrap -a rsa2048 -c sign-pkcs -d 1,2,5 --id 30 --label SSH_RSA_Key --in private.pem --wrapkey wrap.key --out private.yhw

# For ECDSA keys
yubihsm-wrap -a ecp256 -c sign-ecdsa -d 1,2,5 --id 31 --label SSH_ECDSA_Key --in private.pem --wrapkey wrap.key --out private.yhw
  1. Import wrapped key:
# Import the wrapped key into YubiHSM 2
yubihsm-shell -p password -a put-wrapped --wrap-id 20 --in private.yhw

Supported asymmetric key types: - RSA keys (various key sizes: rsa2048, rsa3072, rsa4096) - ECDSA (NIST-P) keys (various curves: ecp256, ecp384, ecp521)

Note: The Wrap key must already be present on the YubiHSM 2 device before importing wrapped keys. The .yhw format is the YubiHSM 2 wrapped key format. For detailed procedures, refer to the YubiHSM 2 documentation.

DKEK vs Wrap keys: - DKEK (SmartCard HSM/Nitrokey HSM2): Establishes a logical security domain across multiple devices. Keys are encrypted with DKEK shares rather than passwords. DKEK shares are created using the device’s random number generator and encrypted with custodian passwords. - Wrap keys (YubiHSM 2): Simple 16-byte binary keys used for wrapping/unwrapping individual keys. Each wrapped key is encrypted with a specific Wrap key stored on the device.

Important

Other HSM devices: If your HSM device supports direct private key import (check vendor’s documentation), you may use this command line to import directly a private key stored inside an existing PKCS#12 file (see the example above about how to create that file):

pkcs15-init --auth-id 01 -f pkcs12 -S /tmp/my.p12

See Loading the identities from PKCS#11 provider into the SSH agent. Exporting the public SSH key below for understanding how to obtain copy of the public key that should be sent to us for registration.

SSH client side configuration

Client-side configuration (optional)

Create or modify ~/.ssh/config:

# HSM-based SSH configuration for multiple hosts
Host login.discoverer.bg
    HostName login.discoverer.bg
    Port 22
    User your-discoverer-username
    PKCS11Provider /usr/lib64/opensc-pkcs11.so
    IdentitiesOnly yes
    IdentityFile none

Host login-plus.discoverer.bg
    HostName login-plus.discoverer.bg
    Port 22
    User your-discoverer-username
    PKCS11Provider /usr/lib64/opensc-pkcs11.so
    IdentitiesOnly yes
    IdentityFile none

Host login.bg.discoverer.bg
    HostName login.bg.discoverer.bg
    Port 2222
    User your-discoverer-username
    PKCS11Provider /usr/lib64/opensc-pkcs11.so
    IdentitiesOnly yes
    IdentityFile none

Loading the identities from PKCS#11 provider into the SSH agent. Exporting the public SSH key

# You may replace /usr/lib64/opensc-pkcs11.so with the full path to your PKCS#11 provider library
ssh-add -s /usr/lib64/opensc-pkcs11.so

At this point, entering the PIN will be requested. Afterwards, the identity will be visible when executing:

ssh-add -L

From the list of the keys provided, select those you want us to register for your Discoverer or Discoverer+ account with us. Send the copy of the selected keys following the instructions given in Extracting the public key for registering.

In case you need to list the hashes of each key accessible to the SSH agent, run:

# Test SSH key extraction (this lists the hashes of the keys!). You may replace /usr/lib64/opensc-pkcs11.so with the full path to your PKCS#11 provider library
ssh-keygen -D /usr/lib64/opensc-pkcs11.so -l

Important: Do not unplug the HSM or PIV device until you unload the PKCS#11 provider library (see below how to do that). Otherwise you may not be able to log in.

Unloading the identities from PKCS#11 provider from the SSH agent

Execute this command before unplugging HSM or PIV device:

# You may replace /usr/lib64/opensc-pkcs11.so with the full path to your PKCS#11 provider library
ssh-add -e /usr/lib64/opensc-pkcs11.so

Troubleshooting

Common issues

  1. PKCS#11 module not found

    # Check module availability
ls -la /usr/lib64/opensc-pkcs11.so

  2. Certificate not recognized

    # List certificates in HSM
pkcs11-tool --module /usr/lib64/opensc-pkcs11.so \
    --list-objects --type cert

  3. SSH connection failures

    # Enable verbose SSH debugging
ssh -v -o PKCS11Provider=/usr/lib64/opensc-pkcs11.so user@host

  4. HSM token is unplugged until the PKCS#11 provider module is loaded

    # You may replace /usr/lib64/opensc-pkcs11.so with the full path to your PKCS#11 provider library
ssh-add -e /usr/lib64/opensc-pkcs11.so

  5. Cannot SSH login due to the error “sign_and_send_pubkey: signing failed for XXXXXXX from agent: agent refused operation”

    This error occurs when the SSH agent is not configured correctly to access the private key stored on the HSM or PIV device or the connection to the device is lost.

    In many cases, the error is caused by detaching the HSM or PIV device from the USB port without prompty unloading the PKCS#11 module from the system, i.e. without executing this command before the detachment:

    # Detach the PKCS#11 module for communicating with
# the HSM or PIV device from the SSH agent:
ssh-add -e /usr/lib64/opensc-pkcs11.so

    If that situation occurs, you may need to kill the SSH agent process and start it again. This will reset the connection to the HSM or PIV device and you will be allowed to re-add the PKCS#11 provider to the SSH agent and properly connect to the device:

    killall ssh-agent; eval "$(ssh-agent)"

    Once the SSH agent is restarted, re-add the PKCS#11 provider to the SSH agent:

    ssh-add -s /usr/lib64/opensc-pkcs11.so

    and try to perform the SSH login again.

    Another aspect of the problem is that sometimes, even if the SSH agent is killed in the way shown above, the newly attached one is available only in the current terminal session (where the killing and starting took place). To make the newly started SSH agent available in all terminal sessions, you need to restart the bash session for the current user, running the window manager. One way to do that is to close the terminal window and open a new one. Then in that newly created terminal, execute:

    # Restart the bash session for the current user
exec bash

    Note

    This is a common issue when using PKCS#11 in terminal in GNOME.

  6. I re-programmed the HSM or PIV device and now even if I provide the correct credentials, the OpenSC library cannot perform

    In many cases, the OpenSC tools keep specific to the device cache information inside:

    ~/.cache/opensc/

    You may safely remove the content stored inside and try using the device again:

    rm -fr ~/.cache/opensc/*

Getting help

For technical support and implementation assistance, contact our support team. See Getting help.