PKCS#11 Sensor User Guide

The PKCS#11 Sensor User Guide provides instructions for deploying and operating the PKCS#11 Sensor within the Keyfactor AgileSec Platform. This guide covers supported authentication methods, execution methods, configuration options, and troubleshooting.

Refer to Sensors Architecture and Overview for additional details on sensor architecture, data flows, incremental scanning, and auto-resolution.

Overview

The PKCS#11 Sensor accesses local HSM via PKCS#11 API with Keyfactor AgileSec Platform.
This sensor allows you to discover, inventory, and analyze cryptographic assets across HSM devices.

Key Features

• Standard API Support: Works with any HSM that supports PKCS#11

• Cryptographic Discovery: Identifies certificates and keys stored in the HSM

What Gets Scanned

The sensor connects to HSM and queries for:

• X.509 Certificates: SSL/TLS certificates

• Keys: RSA, DSA, EC, and symmetric keys

Prerequisites

Remote Execution Requirements

If running the unified sensor remotely using CLI:

Running the Sensor

The HSM Sensor can be executed using the following method:

1. Remote Scan Execution: Deploy and run the sensor via CLI on customer-managed infrastructure for scenarios such as:

   1. Scanning air-gapped or internal instances the platform cannot directly reach

   2. Customers wanting to manage their own scheduling and execution environment.

Refer to Sensors Architecture and Overview: Running the Sensor for additional execution and flow details.

Remote Scan Execution

Remote Execution Flow allows you to run the sensor on a host using the Unified Sensor binary.

Remote Scan Execution Configuration

Step 1: Download Unified Sensor

1.1 Navigate to AgileSec Platform UI → Sensors → Remote Scan.

1.2 Download the sensor binary for your operating system.

Step 2: Generate Remote Sensor Token

2.1 In the Remote Scan UI, click "Generate Token".

2.2 Copy the generated token.

2.3 Store the token securely in an environment variable or set it in the sensor config:

  export SENSOR_TOKEN="your-generated-token"

Step 3: Create Configuration File

Create a YAML configuration file (e.g., pkcs11-config.yml) with your scan settings. An example configuration can be found in config/sample-configs/pkcs11.yml.

Step 4: Run the Sensor

Execute the sensor with your configuration file:

• Linux/macOS

  BASH

  # Set environment variables
  export SENSOR_TOKEN="your-sensor-token"
  
  # Run sensor
  ./unified_sensor_linux -c pkcs11-config.yml

• Windows (PowerShell)

  POWERSHELL

  # Set environment variables
  $env:SENSOR_TOKEN = "your-sensor-token"
  
  # Run sensor
  .\\unified_sensor_windows.exe -c .\\pkcs11-config.yml

Remote Scan Execution Configuration Examples

• Query multiple HSM (Public)

  YAML

  scan_config:
    plugins:
      - pkcs11_import
      - export
    config:
      pkcs11_import:
        name: pkcs11
        plugin_config:
          module:
             - /path/to/hsm1/pkcs11-api-library/pkcs11.so
             - /path/to/hsm2/pkcs11-api-library/pkcs11.so

• Query HSM (With user or so role)

  YAML

  scan_config:
    plugins:
      - pkcs11_import
      - export
    config:
      pkcs11_import:
        name: pkcs11
        plugin_config:
          module:
             - /path/to/hsm1/pkcs11-api-library/pkcs11.so
          user: "so"
          pin: "so pin value"

• Query HSM with label filter (Public)

  YAML

  scan_config:
    plugins:
      - pkcs11_import
      - export
    config:
      pkcs11_import:
        name: pkcs11
        plugin_config:
          module:
             - /path/to/hsm1/pkcs11-api-library/pkcs11.so
          label:
             - label_1
             - label_2

Troubleshooting

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact tokens)

• Log output

• HSM details (type, PKCS#11 library, version)

Contact Support:

• Portal: https://support.keyfactor.com