HSM JCE Facade

HsmAppliance gives you direct access to the HSM’s algorithm modules from Java. Use it when you want to work with the appliance at the module level instead of through the higher-level provider APIs.

Add the JAR

Maven

<dependency>
  <groupId>in.titaniumguard.hsm</groupId>
  <artifactId>jce</artifactId>
  <version>0.0.1</version>
</dependency>

Gradle

implementation("in.titaniumguard.hsm:jce:0.0.1")

Create a connection

HsmAppliance connects to a running HSM instance and exposes one module per algorithm family.

import in.titaniumguard.hsm.jce.appliance.HsmAppliance;
import in.titaniumguard.hsm.jce.types.HsmPartition;

try (var hsm = HsmAppliance.forPlaintextTarget(
    "localhost:50051",
    new HsmPartition("alpha", "partition-secret")
)) {
  // Module access lives on hsm.aes(), hsm.chacha20(), hsm.xchacha20(), and so on.
}

Module overview

Module	What it does
`hsm.aes()`	AES key generation and authenticated encryption
`hsm.chacha20()`	ChaCha20-Poly1305 key generation and authenticated encryption
`hsm.xchacha20()`	XChaCha20-Poly1305 key generation and authenticated encryption
`hsm.rsa()`	RSA key generation plus encrypt, decrypt, sign, and verify operations
`hsm.ecdsa()`	P-256, P-384, and P-521 key generation plus ECDSA signing
`hsm.curve25519()`	X25519, Ed25519, and related Curve25519-family operations
`hsm.curve448()`	X448, Ed448, and related Curve448-family operations
`hsm.sha2()` / `hsm.sha3()` / `hsm.sm3()`	Digest operations
`hsm.mldsa()`	ML-DSA key generation and signing
`hsm.mlkem()`	ML-KEM key generation, encapsulation, and decapsulation

Key wrappers

The facade returns TitaniumGuard key wrapper types instead of raw Java keys. The wrappers keep the HSM key id attached to the material and expose the encoded bytes when you need to store or move the key.

import in.titaniumguard.hsm.jce.appliance.HsmAppliance;
import in.titaniumguard.hsm.jce.types.TgKeyPair;
import in.titaniumguard.hsm.jce.types.TgSecretKey;

try (var hsm = HsmAppliance.forPlaintextTarget("localhost:50051", "alpha", "partition-secret")) {
  TgSecretKey aesKey = hsm.aes().generateKey();
  TgSecretKey chachaKey = hsm.chacha20().generateKey();
  TgSecretKey xchachaKey = hsm.xchacha20().generateKey();

  TgKeyPair rsa = hsm.rsa().generateKeyPair(3072);
  TgKeyPair ec = hsm.ecdsa().generateP256R1Key();
  TgKeyPair x25519 = hsm.curve25519().generateX25519Key();
  TgKeyPair ed25519 = hsm.curve25519().generateEd25519Key();
  TgKeyPair x448 = hsm.curve448().generateX448Key();
  TgKeyPair ed448 = hsm.curve448().generateEd448Key();
  TgKeyPair mlkem = hsm.mlkem().generateMLKEM512Key();

  byte[] keyBytes = aesKey.getEncoded();
  String keyId = aesKey.id();
  TgKeyPair standardJavaKeyPair = rsa.asKeyPair();
}

Common algorithm families

AES, ChaCha20, and XChaCha20

hsm.aes() generates AES keys and supports authenticated encryption.
hsm.chacha20() generates ChaCha20 keys for the ChaCha20-Poly1305 algorithm family.
hsm.xchacha20() generates XChaCha20 keys for the XChaCha20-Poly1305 algorithm family.
Use the JSP provider guide if you want the standard Cipher API instead of the direct facade.

RSA

Generate RSA key pairs with hsm.rsa().generateKeyPair(bits).
Use the returned key pair for encrypt/decrypt or sign/verify operations supported by the module.

ECDSA and curves

hsm.ecdsa() generates P-256, P-384, and P-521 keys.
hsm.curve25519() generates X25519 and Ed25519 keys.
hsm.curve448() generates X448 and Ed448 keys.

Digests

hsm.sha2(), hsm.sha3(), and hsm.sm3() cover the digest algorithms exposed by the appliance.
These modules let you hash data with the HSM-backed implementations instead of local software primitives.

ML-DSA and ML-KEM

hsm.mldsa() covers ML-DSA key generation and signing.
hsm.mlkem() covers ML-KEM key generation, encapsulation, and decapsulation.

When to use this page

Choose the JCE facade when you want direct access to the algorithm modules.
Choose the JSP provider guide when you want the standard Java security provider experience.
Both guides reach the same appliance and the same algorithm surface.