PKCS#11 (HSM) Support

This project supports integration with PKCS#11-compatible Hardware Security Modules (HSMs) and software tokens. This enables cryptographic signing using certificates and private keys stored in secure hardware, such as Amazon CloudHSM or Google Cloud HSM.

PKCS#11 integration is useful for organizations that require high-assurance key management and want to keep private keys out of software memory.

Cargo Feature

PKCS#11 integration requires the optional and disabled-by-default pkcs11 Cargo feature to be enabled:

cargo build --features pkcs11

Supported Devices

Any device or software that provides a PKCS#11 interface should work. This includes:

  • Amazon CloudHSM

  • Google Cloud HSM

  • SoftHSM (for testing)

You will need the vendor’s PKCS#11 library (e.g., /opt/cloudhsm/lib/libcloudhsm_pkcs11.so for Amazon, or the path provided by Google for Cloud HSM).

Amazon CloudHSM Example

  1. Ensure your CloudHSM cluster is initialized and you have a user and key/certificate loaded.

  2. Set up the CloudHSM client.

  3. Install the PKCS#11 library, and note the path to the PKCS#11 library (usually /opt/cloudhsm/lib/libcloudhsm_pkcs11.so).

  4. Sign a file using the certificate file issued by Apple:

rcodesign sign \
    --pkcs11-library /opt/cloudhsm/lib/libcloudhsm_pkcs11.so \
    --pkcs11-pin <USER:PASS> \
    --pkcs11-certificate-file /path/to/cert.pem \
    --pkcs11-key-label <KEY_LABEL> \
    --code-signature-flags runtime \
    <file-to-sign>

Google Cloud HSM Example

  1. Set up your Google Cloud HSM and install the PKCS#11 library.

  2. Ensure your key and certificate are loaded and note their labels or IDs.

  3. Configure the YAML file.

  4. Set up environment variables to point to your Google credentials and configuration file. For example:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/google-credentials.json
export KMS_PKCS11_CONFIG=/path/to/config.yaml

  1. Sign a file using the certificate file issued by Apple:

rcodesign sign \
    --pkcs11-library /path/to/google/pkcs11.so \
    --pkcs11-pin <USER_PIN> \
    --pkcs11-certificate-file /path/to/cert.pem \
    --pkcs11-key-label <KEY_LABEL> \
    --code-signature-flags runtime \
    <file-to-sign>

Testing with SoftHSM

For development and testing, you can use SoftHSM:

  1. Install the required packages. On Ubuntu or Debian systems:

apt update && apt install -y softhsm2 openssl opensc

  1. Configure SoftHSM:

# Arbitrary PIN values
export PKCS11_SO_PIN=123456
export PKCS11_PIN=123456

# Initialize token
softhsm2-util --init-token --slot 0 --label "CodeSigning" --so-pin $PKCS11_SO_PIN --pin $PKCS11_PIN

# List tokens to verify setup
softhsm2-util --show-slots

# Get the slot ID of the initialized token (with label "CodeSigning")
export SLOT_ID=$(softhsm2-util --show-slots | awk '/^Slot [0-9]/ {slot=$2} /Label:.*CodeSigning/ {print slot; exit}')
echo "Using slot ID: $SLOT_ID"

  1. Create test certificate and private key:

# Arbitrary name for the key in SoftHSM
export KEY_LABEL=mykey

# Generate a private key
openssl genrsa -out private_key.pem 2048

# Create a self-signed certificate (for testing)
openssl req -new -x509 -key private_key.pem -out test_cert.pem -days 365 -subj "/CN=Test Code Signing/O=Test Organization/C=US"

# Convert certificate to DER format (what PKCS#11 expects)
openssl x509 -in test_cert.pem -outform DER -out developerID_application.cer

# Import certificate
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
    --login --pin $PKCS11_PIN \
    --slot $SLOT_ID \
    --write-object developerID_application.cer \
    --type cert \
    --label "cert"

# Import private key
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
    --login --pin $PKCS11_PIN \
    --slot $SLOT_ID \
    --write-object private_key.pem \
    --type privkey \
    --label $KEY_LABEL

  1. Sign a file using the test certificate:

# Use rcodesign with SoftHSM's PKCS#11 library
rcodesign sign \
    --pkcs11-library /usr/lib/softhsm/libsofthsm2.so \
    --pkcs11-certificate-file developerID_application.cer \
    --pkcs11-key-label $KEY_LABEL \
    --pkcs11-slot-id $SLOT_ID \
    --pkcs11-pin $PKCS11_PIN \
    --code-signature-flags runtime \
    <file-to-sign>

Limitations

  • You must know the correct label or ID for your key in the HSM, and have the certificate file available (unless you have imported the certificate into the HSM, which is uncommon).

  • Some HSMs require additional configuration or environment variables.

  • Only signing is supported; key generation and import must be done using vendor tools.