Package co.ankatech.ankasecure.sdk.operations

Class EncryptionOperations

java.lang.Object

co.ankatech.ankasecure.sdk.operations.EncryptionOperations

public final class EncryptionOperations
extends Object

Encryption and decryption operations facade.

Public facade for encryption/decryption operations. All methods are exposed via AuthenticatedSdk.

Constructor Summary

Constructors

Constructor	Description
EncryptionOperations(InternalServiceFactory svc, TokenSource tokenSource, BooleanSupplier timingMetricsEnabled, org.slf4j.Logger userLogger)

Method Summary

Modifier and Type	Method	Description
DecryptResult	decrypt(String recipientKid, String ciphertextJwe)	Decrypts a JWE token string, Compact or General JSON.
DecryptResultMetadata	decryptFileCompact(String recipientKid, Path input, Path output)	Decrypts a file containing a JWE token, Compact or General JSON.
DecryptResultMetadata	decryptFileStream(String recipientKid, Path input, Path output)	Decrypts a file in streaming mode (designed for large files >100 MB).
EncryptResult	encrypt(String kid, byte[] plaintext)	Encrypts raw bytes using the key identified by kid.
EncryptResult	encryptFileCompact(String kid, Path input, Path output)	Encrypts a file using the key identified by kid.
EncryptResult	encryptFileStream(String kid, Path input, Path output)	Encrypts a file in streaming mode (designed for large files >100 MB).

Methods inherited from class java.lang.Object

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

Constructor Details

EncryptionOperations

public EncryptionOperations(InternalServiceFactory svc,
 TokenSource tokenSource,
 BooleanSupplier timingMetricsEnabled,
 org.slf4j.Logger userLogger)

Method Details

encrypt

public EncryptResult encrypt(String kid,
 byte[] plaintext)
                      throws AnkaSecureSdkException

Encrypts raw bytes using the key identified by kid.

The key type determines the algorithm automatically: asymmetric keys (ML-KEM, RSA, ECC) perform key encapsulation + symmetric encryption; symmetric keys (AES) encrypt directly. The result is a JWE string containing the ciphertext and all metadata needed for decryption: Compact (RFC 7516 §7.1) for a single-recipient key, General JSON (§7.2) for a composite KEM key, whose one recipient per component Compact Serialization cannot hold.

This method is suitable for in-memory payloads up to ~100 MB. For larger files, use encryptFileStream(String, Path, Path) to avoid loading the entire payload into memory.

Parameters:

kid - key identifier referencing a key stored in ANKASecure©; must not be null

plaintext - the raw bytes to encrypt; must not be null

Returns:

encryption result containing the JWE token and operation metadata; never null

Throws:

AnkaSecureSdkException - if the key identified by kid does not exist, does not support encryption, the authenticated client lacks permission, or the server returns an error

NullPointerException - if kid or plaintext is null

encryptFileCompact

public EncryptResult encryptFileCompact(String kid,
 Path input,
 Path output)
                                 throws AnkaSecureSdkException

Encrypts a file using the key identified by kid.

The entire file is loaded into memory, encrypted, and the resulting JWE is written to the output file (Compact (RFC 7516 §7.1) for a single-recipient key, General JSON (§7.2) for a composite KEM key, whose one recipient per component Compact Serialization cannot hold). This method is suitable for files up to ~100 MB. For larger files, use encryptFileStream(String, Path, Path) which processes files in chunks without loading them entirely into memory.

The output file contains a complete single-line JWE string, in either serialization, that can be decrypted using decryptFile(Path, Path).

Parameters:

kid - key identifier referencing a key stored in ANKASecure©; must not be null

input - path to plaintext file; must not be null and file must exist

output - path where JWE will be written; must not be null

Returns:

encryption result containing the JWE token and operation metadata; never null

Throws:

AnkaSecureSdkException - if the key identified by kid does not exist, does not support encryption, the input file cannot be read, the output file cannot be written, or the server returns an error

NullPointerException - if kid, input, or output is null

encryptFileStream

public EncryptResult encryptFileStream(String kid,
 Path input,
 Path output)
                                throws AnkaSecureSdkException

Encrypts a file in streaming mode (designed for large files >100 MB).

Streaming variant that processes the file in chunks using multipart upload, minimizing memory consumption. Unlike encryptFile(String, Path, Path), this method produces a detached JWE (General-JSON header + raw ciphertext stream) instead of a compact JWE string.

The detached format separates the JWE header from the ciphertext payload, enabling efficient streaming decryption of large files using decryptFileStream(Path, Path).

Parameters:

kid - key identifier referencing a key stored in ANKASecure©; must not be null

input - path to plaintext file; must not be null and file must exist

output - path where encrypted file will be written (detached JWE format); must not be null

Returns:

encryption result with operation metadata (JWE token field may be null in streaming mode); never null

Throws:

AnkaSecureSdkException - if the key identified by kid does not exist, does not support encryption, the input file cannot be read, the output file cannot be written, or the server returns an error

NullPointerException - if kid, input, or output is null

decrypt

public DecryptResult decrypt(String recipientKid,
 String ciphertextJwe)
                      throws AnkaSecureSdkException

Decrypts a JWE token string, Compact or General JSON.

Extracts the key identifier from the JWE header, retrieves the corresponding private key, and decrypts the ciphertext using the appropriate algorithm. Supports both asymmetric (ML-KEM, RSA, ECC) and symmetric (AES) encryption.

This method is the inverse of encrypt(String, byte[]). The JWE token must be a valid RFC 7516 JWE as produced by ANKASecure© encryption operations: Compact (§7.1) or General JSON (§7.2), detected from the content.

Parameters:

recipientKid - the recipient of the JWE to decrypt with, or null when the JWE names one key; required by the server when the JWE is addressed to several keys (HTTP 400 naming recipientKid otherwise)

ciphertextJwe - the JWE token string: Compact (five Base64URL segments separated by dots) or General JSON (a JSON object); must not be null

Returns:

decryption result containing the plaintext bytes and operation metadata; never null

Throws:

AnkaSecureSdkException - if the JWE is malformed, the key does not exist, the authenticated client lacks permission to use the key, or decryption fails due to tampering

NullPointerException - if ciphertextJwe is null

decryptFileCompact

public DecryptResultMetadata decryptFileCompact(String recipientKid,
 Path input,
 Path output)
                                         throws AnkaSecureSdkException

Decrypts a file containing a JWE token, Compact or General JSON.

Reads the entire JWE file, decrypts its contents, and writes the plaintext to the output file. This method is the inverse of encryptFile(String, Path, Path) and is suitable for files up to ~100 MB. For larger files, use decryptFileStream(Path, Path).

The input file must contain a valid JWE string as produced by ANKASecure© encryption operations: Compact (RFC 7516 §7.1) or General JSON (§7.2, written for a composite KEM key), detected from the content.

Parameters:

recipientKid - the recipient of the JWE to decrypt with, or null when the JWE names one key; required by the server when the JWE is addressed to several keys (HTTP 400 naming recipientKid otherwise)

input - path to file containing a Compact or General JSON JWE token; must not be null and file must exist

output - path where plaintext will be written; must not be null

Returns:

decryption metadata including key used, algorithm, and warnings; never null

Throws:

AnkaSecureSdkException - if the input file cannot be read, the JWE is malformed, the key does not exist, the authenticated client lacks permission, decryption fails, or the output file cannot be written

NullPointerException - if input or output is null

decryptFileStream

public DecryptResultMetadata decryptFileStream(String recipientKid,
 Path input,
 Path output)
                                        throws AnkaSecureSdkException

Decrypts a file in streaming mode (designed for large files >100 MB).

Streaming variant that processes the file in chunks using multipart download, minimizing memory consumption. This method is the inverse of encryptFileStream(String, Path, Path) and expects a detached JWE format (General-JSON header + raw ciphertext stream).

Unlike decryptFile(Path, Path), this method does not load the entire encrypted file into memory, making it suitable for very large files.

Parameters:

recipientKid - the recipient of the JWE to decrypt with, or null when the JWE names one key; required by the server when the JWE is addressed to several keys (HTTP 400 naming recipientKid otherwise)

input - path to encrypted file (detached JWE format); must not be null and file must exist

output - path where plaintext will be written; must not be null

Returns:

decryption metadata including key used, algorithm, and warnings; never null

Throws:

AnkaSecureSdkException - if the input file cannot be read, the JWE is malformed, the key does not exist, the authenticated client lacks permission, decryption fails, or the output file cannot be written

NullPointerException - if input or output is null