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.

Since:
3.0.0
Author:
ANKATech Solutions Inc.

  • Constructor Details

    • EncryptionOperations

      public EncryptionOperations(InternalServiceFactory svc, co.ankatech.ankasecure.openapi.client.AnkaSecureOpenApiClient openApiClient, 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 compact JWE (RFC 7516) string containing the ciphertext and all metadata needed for decryption.

      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
      Since:
      3.0.0

    • 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 compact JWE (RFC 7516) is written to the output file. 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 compact JWE string 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
      Since:
      3.0.0

    • 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
      Since:
      3.0.0

    • decrypt

      public DecryptResult decrypt(String ciphertextJwe) throws AnkaSecureSdkException
      Decrypts a compact JWE token string.

      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 compact JWE (RFC 7516) as produced by ANKASecure© encryption operations.

      Parameters:
      ciphertextJwe - the compact JWE token string (five Base64URL segments separated by dots); 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
      Since:
      3.0.0

    • decryptFileCompact

      public DecryptResultMetadata decryptFileCompact(Path input, Path output) throws AnkaSecureSdkException
      Decrypts a file containing a compact JWE token.

      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 compact JWE string as produced by ANKASecure© encryption operations.

      Parameters:
      input - path to file containing compact 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
      Since:
      3.0.0

    • decryptFileStream

      public DecryptResultMetadata decryptFileStream(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:
      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
      Since:
      3.0.0