HSM Documentation

This section contains product documentation for TitaniumGuard HSM.

The Java surface is split into two guides:

• HSM JSP provider for standard JCA/JCE usage through TgHsmProvider
• HSM JCE facade for direct module access through HsmAppliance
• HSM PKCS#11 module for native Cryptoki clients such as OpenSSL and Java SunPKCS11

Use the JSP guide if you want the provider SPI experience. Use the JCE guide if you want the lower-level facade and module APIs directly.

Run with Docker

The HSM image is published as:

• ghcr.io/titaniumguardlabs/source/hsm:latest

The process accepts config via --config <path>.

1. Create a local config file

Example ./hsm-config.json:

{
  "device_fleet_id": "fleet-1",
  "pmk_key_version": "v1",
  "partitions": [
    {
      "partition_id": "alpha",
      "auth": {
        "mechanism": "basic_header",
        "secret_hash": "$scrypt$ln=15,r=8,p=1$C6gWCn20mQ1trEUw3R0xbg$Kt/lrv3BnhuA18tvAczK0R4S3eWVuE8e7Ff7U6mJxbI",
        "secret_kdf": "scrypt"
      },
      "component_keys": [
        "636f6d706f6e656e742d6f6e65",
        "636f6d706f6e656e742d74776f",
        "636f6d706f6e656e742d7468726565"
      ]
    },
    {
      "partition_id": "beta",
      "auth": {
        "mechanism": "oauth2_eddsa",
        "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEALkMZKBtqfdsCPwMDUNig4ebqBl5lzoZ7oX0Rp/Tzbcw=\n-----END PUBLIC KEY-----\n",
        "issuer": "issuer-a",
        "audience": "aud-a",
        "clock_skew_seconds": 15
      },
      "component_keys": [
        "636f6d706f6e656e742d6f6e65",
        "636f6d706f6e656e742d74776f",
        "636f6d706f6e656e742d7468726565"
      ]
    }
  ]
}

Legacy compatibility:

• HSM still accepts legacy partition auth fields (partition_secret_hash, partition_secret_kdf) when auth is absent.
• Do not set both legacy fields and auth on the same partition.
• OAuth2 partitions require authorization: Bearer <jwt> and EdDSA signatures.

Java docs

• HSM JSP provider guide
• HSM JCE facade guide
• HSM PKCS#11 module guide

2. Run container and mount config

docker run --rm \
  -p 50051:50051 \
  -v "$PWD/hsm-config.json:/etc/titaniumguard/hsm-config.json:ro" \
  ghcr.io/titaniumguardlabs/source/hsm:latest \
  --config /etc/titaniumguard/hsm-config.json

Live reload

• When started with --config <file>, HSM watches that JSON config file for content changes.
• On valid updates, HSM reloads partition credentials and derived partition PMKs in memory.
• On invalid updates, HSM keeps the previous active config and logs the error.

Health and readiness

HSM exposes the standard gRPC health check service on the same listener as the appliance services.

• Liveness uses the default service name or liveness and reports that the process can accept gRPC requests.
• Readiness uses the readiness service name and reports that the active runtime config can serve key-bearing HSM operations.
• Readiness requires a valid active config, any configured license to be accepted, at least one partition, and derived PMK material for every partition.
• Readiness revalidates configured license material on each check.
• Health responses are coarse status values and do not expose secrets, hashes, partition identifiers, config paths, PMK material, or algorithm inventory.

Operators should treat a not-ready response as a configuration or license issue first. Check the appliance logs for the redacted failure class, fix the mounted config or license material, and wait for a successful reload before sending key-bearing traffic.

Encrypted key material

• The HSM is stateless: it does not persist or retain key material.
• Private keys, signing keys, decapsulation keys, encapsulation keys, and symmetric keys are always returned as encrypted key envelopes (never plaintext key bytes).
• Matching request fields (for sign/decrypt/decapsulate/derive operations) accept encrypted key envelopes and are unwrapped with the partition PMK selected by x-partition-id.
• No key storage exists within the HSM boundary; clients are responsible for storing returned encrypted key material.