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

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

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.

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.