AnkaSecure SDK - Overview

Version: 3.4.0 Language: Java 17 Artifact: ankasecure-sdk-3.4.0.jar Coordinate: co.ankatech:ankasecure-sdk:3.4.0 (Maven Central) Distribution: Maven Central, and a standalone JAR download

The AnkaSecure SDK is a Java-based library that provides a high-level interface to the remote AnkaSecure Core API for cryptographic operations. It sits on top of the auto-generated OpenAPI client (AnkaSecureOpenApiClient) and exposes user-friendly methods for file encryption/decryption, signing/verifying, re-encryption/re-signing, PKCS#7/JOSE interop, and read-only key discovery.

Key characteristics:

• Client library: Wraps REST API calls to AnkaSecure Core API
• Data-plane only: Performs cryptographic operations on pre-provisioned keys; key provisioning is a control-plane task (Admin Console / Key Management SDK and CLI)
• High-level abstraction: Simplifies integration vs raw HTTP requests
• Multi-authentication: Supports user credentials and application credentials
• Crypto-agile: Classical and post-quantum algorithms
• Streaming support: For files of any size the path to the API accepts; a proxy in front of the deployment may cap uploads; see Behind a buffering proxy

1. Purpose

The SDK provides a simplified interface to the AnkaSecure platform with the following benefits:

Bridge to the Core API:

Instead of manually constructing HTTP requests or working with OpenAPI model classes, developers can call straightforward methods like encrypt(kid, data) or sign(kid, data) on an AuthenticatedSdk instance returned by the factory's authentication methods. The SDK handles request serialization, response parsing, and error mapping.

Centralized Authentication:

Create an AnkaSecureSdk factory, authenticate once as a cryptographic actor — authenticate(), which resolves the configured credential, or authenticateApplication() — to obtain an immutable AuthenticatedSdk instance, then share that authenticated instance across thousands of concurrent threads for all cryptographic operations. The factory manages JWT tokens and the authenticated SDK is fully thread-safe.

Consistent Error Handling:

All SDK methods throw AnkaSecureSdkException on failures, providing uniform error handling across all operations. Error messages include correlation IDs for troubleshooting.

Crypto-Agility:

Supports both classical (RSA, ECC, AES) and post-quantum (ML-KEM, ML-DSA, Falcon, SLH-DSA) algorithms. Methods accept algorithm parameters in a flexible manner, allowing seamless transitions between cryptographic families.

Supported algorithms:

• Key Encapsulation: ML-KEM-512/768/1024, RSA-2048/3072/4096, EC-P256/P384/P521
• Digital Signatures: ML-DSA-44/65/87, Falcon-512/1024, SLH-DSA variants, RSA-PSS, ECDSA
• Symmetric Encryption: AES-128/192/256-GCM/CCM, ChaCha20-Poly1305

Composite Hybrid Keys:

Supports 41 validated composite key combinations pairing classical algorithms (X25519, Ed25519, P-curves) with post-quantum algorithms (ML-KEM, ML-DSA, HQC) for defense-in-depth security. Composite keys use COMPOSITE_KEM_COMBINE mode for encryption (27 combinations) and COMPOSITE_SIGNATURE mode for signatures (14 combinations), providing quantum-resistant protection against "Harvest Now, Decrypt Later" attacks while maintaining backward compatibility.

Streaming or Non-Streaming:

Offers both in-memory operations (for small to medium files) and streaming-based operations (for large files or limited memory environments), covering encryption, decryption, signing, re-encryption, and re-signing.

2. Architecture & Relationship to Other Components

Internally, the AnkaSecure SDK:

1. Uses the AnkaSecureOpenApiClient to configure and make the actual REST calls:

   • The OpenAPI client sets up OkHttp, handles timeouts, proxy configs, SSL, etc.
   • Returns data or file streams from the remote server.

2. Exposes simpler, domain-focused methods (e.g., encrypt(...), sign(...), encryptFileStream(...)).

3. Handles:

   • Parsing of parameters
   • Logging via devLogger and userLogger
   • Exception wrapping (converting ApiException into AnkaSecureSdkException)

The AnkaSecure CLI is effectively one consumer of this SDK. Other applications—command-line, desktop, web backends—can similarly instantiate AnkaSecureSdk to leverage the same cryptographic operations without needing to replicate logic or manage raw REST calls.

Technology Stack:

• Language: Java 17 (for broad compatibility)
• Build Tool: Maven 3.9+
• HTTP Client: OkHttp (from SDK transitive dependencies)
• JSON Processing: Gson + Jackson 2 (com.fasterxml.jackson, from SDK transitive dependencies). The SDK resolves Jackson 2 only; the platform's Jackson 3 (tools.jackson) half is confined to three server-side mappers the SDK never links — see The Jackson Major Split^*
• Cryptography: Bouncy Castle 1.86 (bcprov/bcpkix/bcutil, declared directly by the SDK) on top of the standard JCA
• Artifact: ankasecure-sdk-3.4.0.jar (co.ankatech:ankasecure-sdk on Maven Central)

Distribution:

The SDK is published to Maven Central as co.ankatech:ankasecure-sdk, and the same JAR (ankasecure-sdk-3.4.0.jar) is offered on the downloads page for builds that cannot reach Central. It can be consumed by:

• Java applications - Add as a Maven/Gradle dependency resolved from Maven Central
• AnkaSecure Crypto CLI - Command-line interface built on top of the SDK (uses Java 25 runtime)
• Custom integrations - Any Java-based system requiring cryptographic operations

The Crypto CLI (ankasecure-cli-crypto) is a separate project that depends on the SDK and provides 40 command-line operations using Picocli 4.7.7 framework.

3. Data-Plane Features

All SDK operations run against pre-provisioned keys, identified by kid. The actor the SDK authenticates as must hold the matching capability grant on the target key (see the operation → capability grant matrix). Key creation, import, rotation, revocation, and deletion are control-plane tasks — perform them in the Admin Console or with the Key Management SDK or CLI (see Before You Integrate).

Read-Only Key Access & Algorithm Catalog

Discover the keys and algorithms already provisioned for your tenant.

Methods:

• listKeys(KeyFilters, page, size) - Fetch one page of keys as a KeyPage (content, totalElements, totalPages, number); the KeyFilters carrier (origin, restricted, kty, status) is applied server-side before pagination. origin, kty and status each take the same token the corresponding KeyMetadata getter returns — a hybrid key is selected with kty = COMPOSITE, and its construction is read from getCompositeMode()
• listAllKeys(KeyFilters) - Auto-paginate ALL matching keys client-side (200-element pages); throws PaginationCeilingExceededException beyond the 10,000-page hard cap instead of truncating silently. Without a status filter both listings hold every key the tenant still holds; destroyed keys are returned only with status = deleted_logical, as rows carrying getKid(), getUuid() (the member that tells apart rows sharing a kid), getStatus(), getCreatedAt() and getDeletedAt(), with no shape, material or usage member
• getKeyMetadata(kid) - Fetch one key's metadata
• getSupportedAlgorithms() / getSupportedAlgorithms(AlgorithmFilter) - Query available algorithms from the server

These are read-only. The SDK exposes no key-lifecycle write methods — no key creation, import, rotation, revocation, deletion, or export — those live in the control plane.

File Encryption/Decryption

Encrypt and decrypt using JWE (JSON Web Encryption) format. Requires an ENCRYPT grant to encrypt and a DECRYPT grant to decrypt.

In-memory:

• encrypt(kid, byte[]) / decrypt(ciphertextJwe)

Non-streaming file methods (auto-select compact vs streaming by size):

• encryptFile(kid, inputPath, outputPath) / decryptFile(inputPath, outputPath)
• encryptFileCompact(...) / decryptFileCompact(...) - force the non-streaming path

Non-streaming output is a Compact JWE for a single-recipient key and a General JSON JWE (RFC 7516 §7.2) for a composite KEM key, which has one recipient per component. Every decrypt and re-encrypt method accepts both, detected by content.

Streaming file methods (large files):

• encryptFileStream(kid, inputPath, outputPath) / decryptFileStream(inputPath, outputPath)

Digital Signatures

Sign and verify using JWS (JSON Web Signature) format. Requires a SIGN grant to sign and a VERIFY grant to verify.

In-memory:

• sign(kid, byte[]) / verifySignature(jws)

File methods:

• signFile(kid, inputPath, outputPath) (auto-select), signFileCompact(...), signFileStream(...)
• verifySignature(jws), verifySignatureStream(dataFile, signatureFile)

Supported signature algorithms:

• Post-quantum: ML-DSA-44/65/87, Falcon-512/1024, SLH-DSA variants
• Classical: RSA-PSS, ECDSA (P-256/P-384/P-521)

Re-encrypt & Re-sign (Zero-Exposure Rotation)

Transition encrypted or signed data to a new key without exposing plaintext. Cross-kid operations require the capability on both the source and target key.

Re-encryption (REENCRYPT on both kids):

• reencrypt(newKid, jweToken), reencrypt(newKid, sourceKid, jweToken), reencryptFile(...), reencryptFileCompact(...), reencryptFileStream(newKid, sourceKid, in, out) — sourceKid names the ONE recipient replaced in a JWE addressed to several keys

Re-signing (RESIGN on both kids):

• resign(newKid, jws), resign(newKid, sourceKid, jws), resignFileCompact(...), resignFileStream(oldJwsHeader, newKid, in, out), resignFileStream(oldJwsHeader, newKid, sourceKid, in, out) — sourceKid names the ONE signer replaced in a JWS signed by several keys

Use cases:

• Algorithm upgrades (RSA → ML-KEM)
• Key expiration handling
• Compromised key recovery
• Compliance-driven migrations

Combined Operations

Nested sign-then-encrypt and decrypt-then-verify in a single call.

• signThenEncrypt(signKid, encryptKid, byte[]) / signThenEncryptFileCompact(...) - requires SIGN on the sign kid and ENCRYPT on the encrypt kid
• decryptThenVerify(jweToken) / decryptThenVerify(recipientKid, jweToken) / decryptThenVerifyFileCompact(...) - requires DECRYPT on the decrypting key and VERIFY on every inner signer

PKCS#7 / CMS Interop & Migration

Analyze legacy PKCS#7/CMS artifacts and convert them to modern JOSE (JWE/JWS).

• analyzePkcs7(...) / analyzePkcs7Stream(...) - keyless structural analysis (no grant)
• convertPkcs7ToJose(...) / convertPkcs7ToJoseStream(...) - convert to JOSE
• performMigrationWorkflow(pkcs7File, request, out) - end-to-end EnvelopedData → JWE

Recipient key is control-plane provisioned. Converting EnvelopedData requires the platform to decrypt it with the recipient's private key. That key is imported in the control plane (Admin Console Import Keystore tab), matched by issuer DN + serial number, and the actor needs a DECRYPT grant on it. Its kid is passed explicitly on the request. Import itself is an Admin API operation, POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore.

Utility (caller-supplied public key) operations — no stored key, no grant:

• encryptFileUtilityStream(kty, alg, publicKeyB64, in, out)
• verifySignatureUtilityStream(kty, alg, publicKeyB64, signatureB64, dataFile)

Note: The parameter kid (Key ID) is used throughout the SDK for key identification. This replaced the previous "alias" terminology in version 3.0.0.

4. Who Should Use the SDK?

Java Developers

Java developers who need a direct, object-oriented way to invoke the AnkaSecure Core API for cryptographic operations. The SDK eliminates the need to manually construct HTTP requests or parse JSON responses.

Typical use cases:

• Spring Boot microservices requiring encryption/decryption
• Batch processing applications signing large file sets
• Document management systems with PQC requirements

Enterprise Integrations

Organizations needing secure file handling or key management within existing Java applications.

Integration scenarios:

• Legacy application modernization (PKCS#7 → JOSE migration)
• Multi-cloud deployments requiring centralized key management
• Compliance-driven cryptographic upgrades (classical → post-quantum)
• Secure data pipelines with encryption at rest

CLI Tool Developers

The AnkaSecure Crypto CLI itself is built on top of this SDK, demonstrating how to leverage AnkaSecureSdk for user-facing command-line tools.

Reference implementation:

• See ankasecure-cli-crypto project for 25 working command examples
• Shows authentication patterns, error handling, streaming operations
• Demonstrates interactive wizards and guided flows

5. SDK vs Crypto CLI

AnkaSecure SDK:

• Java library (JAR artifact)
• Programmatic API for Java applications
• Requires Maven/Gradle integration
• Used by: Custom applications, integrations, services

Crypto CLI:

• Command-line tool built on top of the SDK
• 25 commands for terminal/script usage
• Standalone executable (bundled JAR)
• Used by: DevOps, automation scripts, manual operations

Example comparison:

// SDK usage (programmatic - v3.0.0 factory pattern)
// The key "my-key" and the actor's ENCRYPT grant are provisioned beforehand
// in the control plane (Admin Console / ankasecure-km).
AnkaSecureSdk factory = new AnkaSecureSdk(apiConfig);
AuthenticatedSdk sdk = factory.authenticateApplication(clientId, clientSecret);
EncryptResult result = sdk.encrypt("my-key", "Hello World".getBytes());

# Crypto CLI usage (command-line) — also data-plane, same pre-provisioned key
AnkaSecureCLI init  # Configure credentials
AnkaSecureCLI encrypt-file --kid my-key --input-file ./plaintext.txt --output-file ./ciphertext.jwe

Both perform the same data-plane operation, but the SDK offers programmatic control while the Crypto CLI offers terminal convenience. Neither creates the key — that is a control-plane task.

6. Next Steps

SDK Integration:

• Using the SDK in Java: Learn how to set up your project to consume the SDK, authenticate, and call the principal methods.
• Integration Examples: Real-world integration scenarios
• Integration Flows: 21 detailed flows covering all SDK operations
• Composite Key Flows: Quantum-resistant hybrid cryptography examples

Crypto CLI:

• Crypto CLI Overview: Command-line interface built on the SDK
• Crypto CLI Commands: All 40 commands reference
• Crypto CLI Installation: Installation guide

Technical Details:

• OpenAPI Client: Underlying REST client implementation
• SDK & CLI Overview^*: Architectural overview

© 2025 AnkaTech. All rights reserved.