Skip to content

AnkaSecure SDK - Overview

Version: 3.0.0 Language: Java 17 Artifact: AnkaSecureSDK-3.0.0.jar Distribution: Standalone JAR library

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 key management, file encryption/decryption, signing/verifying, license checks, and more.

Key characteristics:

  • Client library: Wraps REST API calls to AnkaSecure Core API
  • High-level abstraction: Simplifies integration vs raw HTTP requests
  • Multi-authentication: Supports user credentials, application credentials, JWT, mTLS
  • Crypto-agile: Classical and post-quantum algorithms
  • Streaming support: For files of any size

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 generateKey(spec) or encrypt(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 using authenticateApplication() or authenticateUser() 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 35 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 (24 combinations) and COMPOSITE_SIGNATURE mode for signatures (11 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., generateKey(...), deleteKey(...), 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 (from SDK transitive dependencies)
  • Cryptography: Bouncy Castle 1.83+ (PQC provider)
  • Artifact: AnkaSecureSDK-3.0.0.jar

Distribution:

The SDK is distributed as a standalone JAR library (AnkaSecureSDK-3.0.0.jar) that can be consumed by:

  • Java applications - Add as Maven/Gradle dependency
  • 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. Key Features

Key Generation

Generate cryptographic keys for various algorithms and operations.

Methods:

  • generateKey(KeyRequest) - Supports symmetric, classical, and post-quantum algorithms

Supported key types:

  • Asymmetric: ML-KEM, ML-DSA, Falcon, SLH-DSA, RSA, EC
  • Symmetric: AES, ChaCha20-Poly1305, HMAC

File Encryption/Decryption

Encrypt and decrypt files using JWE (JSON Web Encryption) format.

Non-streaming methods (for files < 100MB):

  • encryptFile(kid, inputPath, outputPath) - Compact JWE encryption
  • decryptFile(kid, inputPath, outputPath) - Compact JWE decryption

Streaming methods (for large files):

  • encryptFileStream(kid, inputPath, outputPath) - Streaming JWE encryption
  • decryptFileStream(kid, inputPath, outputPath) - Streaming JWE decryption

Public key operations (caller-supplied keys):

  • encryptFilePublicKeyStream(publicKey, inputPath, outputPath) - Encrypt without storing key

Digital Signatures

Sign and verify files using JWS (JSON Web Signature) format.

Non-streaming methods:

  • signFile(kid, inputPath, signaturePath) - Compact or detached JWS
  • verifySignature(kid, inputPath, signaturePath) - JWS verification

Streaming methods (for large files):

  • signFileStream(kid, inputPath, signaturePath) - Streaming detached JWS
  • verifySignatureStream(kid, inputPath, signaturePath) - Streaming verification

Public key operations (caller-supplied keys):

  • verifySignaturePublicKeyStream(publicKey, inputPath, signaturePath) - Verify without stored key

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)

Key Import/Export

Import keys from external sources and export for backup or sharing.

Import methods:

  • importKey(ImportKeySpec) - Import key from JSON (JWK format)
  • importPrivateKeyPkcs12(Pkcs12ImportSpec) - Import from PKCS#12 bundle with certificate validation

Export methods:

  • exportKey(kid, outputPath) - Export public key metadata to JSON

Key Lifecycle Management

Manage the full lifecycle of cryptographic keys.

Listing and discovery:

  • listKeys() - List all keys with metadata (ID, algorithm, status, creation date)
  • viewSupportedAlgorithms() - Query available algorithms from server

Key operations:

  • deleteKey(kid) - Permanently delete a key
  • revokeKey(kid) - Revoke a key (marks as unusable, prevents operations)
  • patchKey(kid, PatchKeySpec) - Update key metadata (tags, limits, lifetime)
  • rotateKey(String baseKid, KeyRequest successor, boolean acknowledgeCapabilityReduction) - Initiate key rotation (algorithm transition)

Key states:

  • ACTIVE → PENDING_ROTATION → ROTATED → REVOKED → ARCHIVED → DELETED_LOGICAL

Key Rotation Operations

Seamlessly transition encrypted/signed data to new keys.

Re-encryption:

  • reencryptFileStream(oldKid, newKid, inputPath, outputPath) - Rotate encryption keys
  • Decrypts with old key, re-encrypts with new key in single operation

Re-signing:

  • resignFileStream(oldKid, newKid, inputPath, oldSigPath, newSigPath) - Rotate signature keys
  • Verifies with old key, re-signs with new key in single operation

Use cases:

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

Interoperability Operations

Cryptographic operations using caller-supplied keys (NOT stored in keystore).

Methods:

  • verifySignatureExternal(VerifyExternalSpec) - Verify signatures with external public keys
  • encryptFileExternal(EncryptExternalSpec) - Encrypt for external recipients

Characteristics:

  • Keys are NOT persisted to keystore
  • Suitable for continuous cross-platform operations
  • Prevents keystore pollution with one-time keys
  • Public keys provided in JWK format

Use case: Verify signatures from external systems or encrypt data for external recipients without importing their keys permanently.

Migration Operations

One-time migration from legacy cryptographic systems.

PKCS#12 Import:

  • importPkcs12(Pkcs12ImportSpec) - Import PKCS#12 bundles with certificate validation
  • Validates certificate chains
  • Stores private keys in AnkaSecure keystore

PKCS#7/CMS Analysis and Conversion:

  • analyzePkcs7(Pkcs7AnalysisSpec) - Analyze PKCS#7/CMS structure
  • analyzePkcs7Stream(Pkcs7AnalysisSpec) - Streaming analysis for large files
  • convertPkcs7ToJose(Pkcs7ConversionSpec) - Convert PKCS#7 to JOSE format
  • convertPkcs7ToJoseStream(Pkcs7ConversionSpec) - Streaming conversion

Use case: Migrate from legacy PKCS#7 encrypted/signed data to modern JOSE (JWE/JWS) format while preserving cryptographic properties.

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)
AnkaSecureSdk factory = new AnkaSecureSdk(apiConfig);
AuthenticatedSdk sdk = factory.authenticateApplication(clientId, clientSecret);
sdk.generateKey(new KeyRequest()
    .kid("my-key")
    .kty("ML-KEM")
    .alg("ML-KEM-768"));

# CLI usage (command-line)
AnkaSecureCLI init  # Configure credentials
AnkaSecureCLI generate-key --kid my-key --kty ML-KEM --alg ML-KEM-768

Both perform the same operation, but SDK offers programmatic control while CLI offers terminal convenience.

6. Next Steps

SDK Integration:

Crypto CLI:

© 2025 AnkaTech. All rights reserved.