HSM PKCS#11 Module

The HSM PKCS#11 module is a native Cryptoki library for tools that expect a loadable PKCS#11 provider. It connects to the same HSM appliance as the Java SDKs and keeps the appliance stateless by storing token objects in a local client-side object store.

Library path

Use the native library produced for your platform:

• macOS: libtitaniumguard_hsm_pkcs11.dylib
• Linux: libtitaniumguard_hsm_pkcs11.so

Configuration

The module looks for JSON configuration at:

/etc/titaniumguard/hsm-pkcs11.json

User-level configuration can also be placed at:

~/.config/titaniumguard/hsm-pkcs11/config.json

Example:

{
  "target": "localhost:50051",
  "partition_id": "alpha",
  "partition_secret": "partition-secret",
  "plaintext": true,
  "object_store": "/var/lib/titaniumguard/hsm-pkcs11/objects.json"
}

Optional settings:

• bearer_token sends OAuth2 bearer authentication instead of a partition secret.
• object_store overrides the local object-store file.

If no object-store path is provided, the module uses:

$XDG_CONFIG_HOME/titaniumguard/hsm-pkcs11/objects.json

The object store contains public attributes, object labels, key ids, public key bytes, and encrypted HSM key envelopes. It does not store plaintext private or secret key material.

Mechanisms

The first compatibility surface includes:

Mechanism	Use
CKM_AES_KEY_GEN	AES key generation
CKM_AES_GCM	AES-GCM encrypt and decrypt
CKM_RSA_PKCS_KEY_PAIR_GEN	RSA key-pair generation
CKM_RSA_PKCS	RSA PKCS#1 v1.5 encrypt, decrypt, sign, and verify
CKM_EC_KEY_PAIR_GEN	P-256, P-384, and P-521 key-pair generation
CKM_ECDSA	ECDSA sign and verify
CKM_EDDSA	EdDSA mechanism advertisement for compatible clients
CKM_SHA224, CKM_SHA256, CKM_SHA384, CKM_SHA512	SHA-2 digests
CKM_SHA3_256, CKM_SHA3_384, CKM_SHA3_512	SHA-3 digests
CKM_SM3	SM3 digest

Unsupported optional PKCS#11 calls return CKR_FUNCTION_NOT_SUPPORTED.

OpenSSL

Point your PKCS#11 provider or engine configuration at the native library and use a token URI that identifies the key label or id stored by the module.

openssl pkeyutl \
  -engine pkcs11 \
  -keyform engine \
  -inkey "pkcs11:token=TitaniumGuard%20HSM;object=signing-key;type=private" \
  -sign \
  -in digest.bin \
  -out signature.bin

Java SunPKCS11

Create a SunPKCS11 config file that points to the native library:

name = TitaniumGuardHSM
library = /absolute/path/to/libtitaniumguard_hsm_pkcs11.dylib
slotListIndex = 0

Register the provider from Java:

import java.security.KeyPairGenerator;
import java.security.Provider;
import java.security.Security;

Provider provider = Security.getProvider("SunPKCS11").configure("/path/to/tg-hsm-pkcs11.cfg");
Security.addProvider(provider);

KeyPairGenerator generator = KeyPairGenerator.getInstance("RSA", provider);
generator.initialize(2048);
var keyPair = generator.generateKeyPair();