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, such as creating a fresh SecureRandom on each call 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[]).

All code is designed to integrate with NetBeans 24, Java 21, Spring Boot 3.4.3, and BouncyCastle 1.80.

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)	Decrypts data produced by encryptDataRaw(byte[], byte[]) with the same raw AES key.
static byte[]	encryptDataRaw(byte[] aesKeyBytes, byte[] plaintext)	Encrypts plaintext using AES-GCM with the provided raw AES key bytes.
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(byte[] aesKeyBytes,
 byte[] plaintext)
                             throws CryptoOperationException

Encrypts plaintext using AES-GCM with the provided raw AES key bytes. Produces a random 12-byte IV on every call, included at the start of the output. Format:

[1-byte IV length][IV][ciphertext + GCM tag]

Parameters:

aesKeyBytes - raw AES key bytes (32 bytes for AES-256 recommended)

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

Returns:

the ciphertext including IV metadata

Throws:

CryptoOperationException - if encryption fails

decryptDataRaw

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

Decrypts data produced by encryptDataRaw(byte[], byte[]) with the same raw AES key. The ciphertext format is:

[1-byte IV length][IV][ciphertext + GCM tag]

Parameters:

aesKeyBytes - raw AES key bytes (32 bytes recommended)

ciphertext - the ciphertext blob including IV and tag

Returns:

decrypted plaintext

Throws:

CryptoOperationException - if decryption fails

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