Package co.ankatech.ankasecure.sdk.util

Class PqcClientCryptoUtil

java.lang.Object

co.ankatech.ankasecure.sdk.util.PqcClientCryptoUtil

public final class PqcClientCryptoUtil
extends Object

PqcClientCryptoUtil

Provides client-side cryptographic utilities for hybrid or post-quantum schemes. It includes:

• Generating key pairs for PQC algorithms and classical algorithms (mirroring server-side registry logic if needed).
• AES-GCM encryption/decryption with ephemeral IV usage, ensuring no IV reuse.
• KEM decapsulation to recover a symmetric key from a ML-KEM ciphertext.

This class emphasizes strong security practices, using the NIST SP 800-90A compliant DRBG via CryptoRandomProvider and never reusing ephemeral data. All methods log important steps and errors using devLogger for development-level detail and userLogger for user-facing issues. Additionally, messages are internationalized via a ResourceBundle.

Example usage (pseudocode only, not provided in final code):

• Generate a key pair with generateKeyPair(String) (e.g. "ML-KEM-512").
• Send the public key to the server for encryption or KEM encapsulation.
• Receive the ciphertext from the server, call decapsulateKem(PrivateKey, String, byte[]) to recover the AES key, and use that key with encryptDataRaw(byte[], byte[]) or decryptDataRaw(byte[], byte[]).

Designed to integrate with standard Java 17+ runtimes and Spring Boot 3.x.

Version:

1.0

Author:

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	PqcClientCryptoUtil.GeneratedKeyPair	A record containing both raw key objects (public, private) and their Base64-encoded forms.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	CIPHER_INPUT_STREAM_BUFFER_SIZE

Method Summary

Modifier and Type	Method	Description
static byte[]	decapsulateKem(PrivateKey privateKey, String kemAlgorithm, byte[] ciphertext)	Decapsulates and decrypts a ciphertext using the provided PrivateKey.
static byte[]	decryptDataRaw(byte[] aesKeyBytes, byte[] ciphertext)
static byte[]	decryptDataRaw(SecretBuffer aesKeyBuf, byte[] ciphertext)	SecretBuffer overload of decryptDataRaw(byte[], byte[]).
static byte[]	encryptDataRaw(byte[] aesKeyBytes, byte[] plaintext)
static byte[]	encryptDataRaw(SecretBuffer aesKeyBuf, byte[] plaintext)	SecretBuffer overload of encryptDataRaw(byte[], byte[]).
static PqcClientCryptoUtil.GeneratedKeyPair	generateKeyPair(String algorithm)	Generates an asymmetric key pair for a specified algorithm, potentially referencing PQC or classical algorithms.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CIPHER_INPUT_STREAM_BUFFER_SIZE

public static final int CIPHER_INPUT_STREAM_BUFFER_SIZE

See Also:

• Constant Field Values

Method Details

generateKeyPair

public static PqcClientCryptoUtil.GeneratedKeyPair generateKeyPair(String algorithm)
                                                            throws CryptoOperationException

Generates an asymmetric key pair for a specified algorithm, potentially referencing PQC or classical algorithms. The actual logic to map algorithm to a provider or parameter set is omitted in this minimal example. Replace with your registry-based approach if needed.

Parameters:

algorithm - the name of the algorithm (e.g. "ML-KEM-512", "RSA-2048")

Returns:

a PqcClientCryptoUtil.GeneratedKeyPair with both raw objects and Base64-encoded strings

Throws:

CryptoOperationException - if any unexpected error occurs

encryptDataRaw

public static byte[] encryptDataRaw(SecretBuffer aesKeyBuf,
 byte[] plaintext)
                             throws CryptoOperationException

SecretBuffer overload of encryptDataRaw(byte[], byte[]).

Closes follow-up SDK-012 (zeroization-cutover-completion Slice 3 / FR-10). The caller passes a SecretBuffer wrapping the AES key bytes; this method forwards to the byte[]-key implementation. The SecretBuffer's lifecycle is owned by the caller (typically via try-with-resources at the call site, e.g., PqcTransportInterceptor). The byte[]-key overload is preserved for callers who own their own key bytes (caller-owned semantics per FR-10).

Parameters:

aesKeyBuf - SecretBuffer wrapping the AES key bytes

plaintext - data to be encrypted (can be null or empty)

Returns:

the ciphertext including IV metadata

Throws:

CryptoOperationException - if encryption fails

encryptDataRaw

public static byte[] encryptDataRaw(byte[] aesKeyBytes,
 byte[] plaintext)
                             throws CryptoOperationException

Throws:

CryptoOperationException

decryptDataRaw

public static byte[] decryptDataRaw(SecretBuffer aesKeyBuf,
 byte[] ciphertext)
                             throws CryptoOperationException

SecretBuffer overload of decryptDataRaw(byte[], byte[]).

Closes follow-up SDK-012 (zeroization-cutover-completion Slice 3 / FR-10). Mirrors the encryptDataRaw SecretBuffer overload; caller owns the SecretBuffer lifecycle.

Parameters:

aesKeyBuf - SecretBuffer wrapping the AES key bytes

ciphertext - the ciphertext blob including IV and tag

Returns:

decrypted plaintext

Throws:

CryptoOperationException - if decryption fails

decryptDataRaw

public static byte[] decryptDataRaw(byte[] aesKeyBytes,
 byte[] ciphertext)
                             throws CryptoOperationException

Throws:

CryptoOperationException

decapsulateKem

public static byte[] decapsulateKem(PrivateKey privateKey,
 String kemAlgorithm,
 byte[] ciphertext)
                             throws CryptoOperationException

Decapsulates and decrypts a ciphertext using the provided PrivateKey. Instead of merely extracting the AES key, this method:

• Reads wrappedKey + IV from the ciphertext.
• Unwraps the AES key with the private key.
• Performs AES-GCM decryption on the remaining data.
• Returns the fully decrypted plaintext bytes.

Parameters:

privateKey - the private key used to unwrap the AES key

kemAlgorithm - a string identifier (e.g. "ML-KEM-512") for logging or future use

ciphertext - the full ciphertext (containing [wrappedKey, IV, and encrypted data]) as a single byte array

Returns:

the decrypted plaintext bytes

Throws:

CryptoOperationException - if any cryptographic or I/O error occurs