PKCS#11 Module

The Infisical PKCS#11 module implements the PKCS#11 v2.40 standard, allowing tools like jarsigner, openssl, cosign, osslsigncode, apksigner, and gpg to use Infisical signers without code changes.

Installation

Download the pre-built binary for your platform from the releases page:

Place the binary in a known location, for example /usr/local/lib/:

# Linux
sudo cp libinfisical-pkcs11.so /usr/local/lib/
sudo chmod 755 /usr/local/lib/libinfisical-pkcs11.so

# macOS
sudo cp libinfisical-pkcs11.dylib /usr/local/lib/
sudo chmod 755 /usr/local/lib/libinfisical-pkcs11.dylib

Building from Source

If you prefer to build from source, you need Go 1.24+ and a C compiler:

git clone https://github.com/Infisical/infisical-pkcs-11.git
cd infisical-pkcs-11
make build

The output binary will be in the current directory.

Configuration

Create a JSON configuration file at /etc/infisical/pkcs11.conf (or any path you prefer):

{
  "server_url": "https://app.infisical.com",
  "project_id": "<your-project-id>",
  "log_level": "info"
}

Then set the authentication credentials via environment variables:

export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID="<your-machine-identity-client-id>"
export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET="<your-machine-identity-client-secret>"

If using a non-default config path, set:

export INFISICAL_PKCS11_CONFIG=/path/to/your/pkcs11.conf

Configuration Reference

Environment Variable Reference

Verifying the Module

Use pkcs11-tool (from OpenSC) to verify the module is working:

# List available slots (one per signer)
pkcs11-tool --module /usr/local/lib/libinfisical-pkcs11.so --list-slots

The output lists one slot per signer in your project:

Available slots:
Slot 0 (0x0): release-signer
  token label        : release-signer
  token manufacturer : Infisical
  ...

To list the objects (private key, certificate, public key) in a slot:

pkcs11-tool --module /usr/local/lib/libinfisical-pkcs11.so --slot 0 --list-objects

Automatic Signing Access Requests

If a signer has a signing policy attached, the module can automatically create a signing request when a sign operation is denied due to a missing grant. This removes the need to manually create requests via the UI or API before signing.

To enable this, add the approval section to your config file with at least one of the following:

{
  "approval": {
    "signing_duration": "8h",
    "signing_count": 10
  }
}

• signing_duration: Requests a time-window grant of the specified duration (e.g. "30m", "8h", "2d"). Valid range: 1 minute to 30 days.
• signing_count: Requests a grant for a fixed number of signing operations.

You can set one or both depending on the constraints defined in the signing policy.

Example Workflow

1. A CI/CD pipeline attempts to sign an artifact
2. The module detects that no active grant exists for the signer
3. It automatically creates a signing request with the configured duration/count
4. An approver reviews and approves the request
5. The pipeline retries and the sign operation succeeds

Troubleshooting

For any issue, start by enabling debug logging in your config file to get detailed output:

{
  "log_level": "debug",
  "log_file": "/tmp/infisical-pkcs11.log"
}