Skip to content

AnkaSecure SDK v2.1 – Overview

The AnkaSecure SDK is a Java 21+ library that provides a high-level façade over the remote Anka Secure REST API, hiding every OpenAPI model and HTTP detail behind concise, developer-friendly methods.

1. Purpose

  • Single entry point – call generateKey(...), encryptFile(...), sign(...), etc., instead of building HTTP requests yourself.
  • Centralised authentication – authenticate once using
    • authenticateApplication(clientId, clientSecret) or
    • authenticateUser(username, password, tenantId) and reuse the same AnkaSecureSdk instance.
  • Uniform error handling – all checked exceptions are AnkaSecureSdkException.
  • Crypto-agility – seamlessly mixes classical (RSA, ECC, AES) and post-quantum (ML-KEM, ML-DSA, Falcon, SLH-DSA) algorithms.
  • Adaptive I/O – every crypto operation is offered in in-memory, file, and streaming variants so you never run out of RAM.

2. Architecture

flowchart LR
    A[Your Java App] -->|SDK calls| B[AnkaSecureSdk]
    B -->|delegates| C[AnkaSecureOpenApiClient]
    C -->|HTTPS| D[Anka Secure API]

3. Key Features & Top-Level API

Capability In-memory File-based Streaming Notes
Encrypt / Decrypt encrypt(kid, bytes) / decrypt(kid, jwe) encryptFile(kid, in, out) / decryptFile(kid, in, out) encryptFileStream(kid, in, out) / decryptFileStream(kid, in, out) AnkaSecureSdk Uses detached-ciphertext JWET for large payloads
Sign / Verify sign(kid, bytes) / verifySignature(jws) signFile(kid, in, sig) / verifySignature(sigFile) AnkaSecureSdk signFileStream(kid, in, sigOut) / verifySignatureStream(in, sigFile) AnkaSecureSdk Detached Compact JWS
Re-encrypt / Re-sign reencrypt(newKid, jwet) / resign(newKid, jws) reencryptFile(...) / resignFile(...) reencryptFileStream(...) AnkaSecureSdk / resignFileStream(...) Zero-exposure rotation flows
Key lifecycle generateKey(spec), importKey(spec), importPrivateKeyPkcs12(spec) AnkaSecureSdk, patchKey(kid, patch), exportKey(...), removeKey(kid), revokeKey(kid)
Utility (no keystore) encryptFileUtilityStream(...), verifySignatureUtilityStream(...) AnkaSecureSdk Supply external public keys/signatures

Tip: every streaming method keeps memory usage < 10 MiB even for multi-GB files.

4. Typical Workflow

// 1. Bootstrap
Properties cfg = new Properties();
cfg.load(Files.newInputStream(Path.of("cli.properties")));
AnkaSecureSdk sdk = new AnkaSecureSdk(cfg);

// 2. Authenticate (choose one)
sdk.authenticateApplication("clientId", "clientSecret");
sdk.authenticateUser("[email protected]", "P@ssw0rd!", "tenantId123");

// 3. Crypto operations
GenerateKeySpec spec = new GenerateKeySpec()
.kid("myFalconKey")
.kty("ML-DSA")
.alg("FALCON-1024");
sdk.generateKey(spec);

sdk.encryptFile("myFalconKey", Path.of("report.txt"), Path.of("report.jwe"));
sdk.decryptFile("myFalconKey", Path.of("report.jwe"), Path.of("report.dec"));

SignResult sig = sdk.signFile("myFalconKey", Path.of("contract.pdf"), Path.of("contract.sig"));
boolean ok = sdk.verifySignature(Path.of("contract.sig")).isValid();

All calls throw AnkaSecureSdkException; catch it once at your boundary layer for consistent logging.

5. When to Choose Each Variant

Size / Scenario Recommended Method(s)
< 5 MB kept entirely in memory encrypt(...), decrypt(...), sign(...), verifySignature(...)
File up to ≈ 200 MB encryptFile(...), decryptFile(...), signFile(...), verifySignature(...)
Multi-GB archives / video streams encryptFileStream(...), decryptFileStream(...), signFileStream(...), verifySignatureStream(...)
Migration RSA/ECC → PQC (any size) • In-memory – reencrypt(...), resign(...)
• File-based – reencryptFile(...), resignFile(...)
• Streaming – reencryptFileStream(...), resignFileStream(...)

Note: Select a variant based on payload size and available RAM—not on the type of migration. All migration paths keep plaintext exclusively on the server and return audit-ready dual-key metadata.

6. Next Steps

Document updated 14 Jun 2025 against AnkaSecure SDK 2.2.0.