<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Implementing Hardware Security Modules

## pkcs11-tool (OpenSC)

### Synopsis

```bash
pkcs11-tool --module <path> [options]
```

### Key Commands

| Command | Description |
|---|---|
| `--list-slots` | List available PKCS#11 slots |
| `--list-objects` | List objects in token (requires `--login --pin`) |
| `--list-mechanisms` | List supported cryptographic mechanisms |
| `--keypairgen --key-type rsa:2048` | Generate RSA key pair |
| `--keypairgen --key-type EC:prime256v1` | Generate ECDSA key pair |
| `--sign --mechanism SHA256-RSA-PKCS` | Sign data |
| `--encrypt` / `--decrypt` | Encrypt/decrypt operations |
| `--delete-object --type privkey --id <id>` | Delete a key |

## softhsm2-util

| Command | Description |
|---|---|
| `--init-token --slot <n> --label <name>` | Initialize token |
| `--show-slots` | Display all slots |
| `--delete-token --token <label>` | Delete a token |
| `--import <key.pem> --slot <n> --label <name>` | Import key |

## AWS CloudHSM

| Command | Description |
|---|---|
| `aws cloudhsmv2 create-cluster` | Create HSM cluster |
| `aws cloudhsmv2 create-hsm` | Add HSM to cluster |
| `aws cloudhsmv2 describe-clusters` | Cluster status |
| `/opt/cloudhsm/bin/key_mgmt_util` | Key management CLI |

### key_mgmt_util Commands

| Command | Description |
|---|---|
| `loginHSM -u CU -s <user> -p <pass>` | Login |
| `genSymKey -t 31 -s 32 -l <label>` | Generate AES-256 key |
| `genRSAKeyPair -m 4096 -e 65537 -l <label>` | Generate RSA key pair |
| `listUsers` | List HSM users |
| `findKey` | List keys |

## Agent Script

```bash
# Initialize SoftHSM2 token
node agent.js init --label dev-token --pin 1234

# List slots
node agent.js slots

# Generate RSA key pair
node agent.js keygen --type rsa:2048 --label signing-key

# List objects
node agent.js objects

# Sign data
node agent.js sign data.bin data.sig --id 01

# Health check
node agent.js health
```
