LinuxCommandLibrary

ssh-pkcs11-helper

Use PKCS#11 tokens for SSH authentication

SYNOPSIS

ssh-pkcs11-helper [options]

PARAMETERS

-l
    List all keys available on the PKCS#11 token(s) and print their corresponding SSH public key strings.

-s
    Add all keys on PKCS#11 tokens to ssh-agent.

-S
    Only add certificates that are signed with a key that can authenticate with pkcs11.

-e
    Remove all keys from ssh-agent that were originally added by this tool.

-v
    Enable verbose output for debugging.

-D
    Run in daemon mode.

-a
    Path to ssh-agent socket

-t
    Set lifetime for agent keys in seconds (default: 1 day)

-c
    Specify PKCS#11 module path

-d
    Allow insecure key exchange with ssh-agent.

-h
    Display help message and exit.

DESCRIPTION

ssh-pkcs11-helper is a helper program designed to facilitate the use of PKCS#11 smart cards and Hardware Security Modules (HSMs) with OpenSSH. It automates the process of adding and managing keys stored on these devices, eliminating the need to manually specify PKCS#11 providers and PINs for each SSH operation. The program simplifies the authentication process by caching PINs securely and providing them to ssh-agent when needed. This allows users to seamlessly use SSH keys stored on PKCS#11 tokens without constantly being prompted for their PIN. It also provides a convenient way to list available keys and automatically register them with the ssh-agent. The helper significantly improves the user experience when working with PKCS#11-based SSH authentication, especially in environments where security policies mandate the use of hardware-backed key storage. It also supports automatic reloading of pkcs11 modules and token hotplugging, handling PIN caching and re-authentication as needed.

ssh-pkcs11-helper is a valuable tool for users who prioritize the enhanced security offered by PKCS#11 devices for SSH authentication. It streamlines the authentication process, improving usability without compromising security.

CAVEATS

Ensure that the PKCS#11 module is correctly configured and accessible by the user running ssh-pkcs11-helper. Incorrect module paths or permissions can lead to authentication failures. Proper PIN caching configuration is critical to security.

PIN CACHING

The tool manages PIN caching to avoid repeated prompts. Consider security implications of caching. Using -d for insecure exchange might weaken security.

MODULE LOADING

The tool supports the dynamic loading and reloading of PKCS#11 modules. This is important for handling situations where the module path changes or the module needs to be updated. This feature is available when running in daemon mode.

HISTORY

The ssh-pkcs11-helper utility was developed to simplify the integration of PKCS#11 devices with OpenSSH. Its primary goal was to automate the process of accessing and managing keys stored on smart cards and HSMs, reducing the manual configuration required for each SSH session. It has evolved over time to include features such as PIN caching, automatic key registration, and support for multiple PKCS#11 modules. The command has become increasingly popular as security best practices push for hardware-backed key storage for SSH authentication.

SEE ALSO

Copied to clipboard