Skip to content

AnkaSecure SDK – Overview

The AnkaSecure SDK is a Java-based library offering a high-level interface to the remote Anka Secure API for cryptographic operations. It wraps and simplifies the auto-generated OpenAPI client (AnkaSecureOpenApiClient), exposing user-friendly methods for key management, file encryption/decryption, signing/verifying, license checks, and more.

1. Purpose

  • Bridge to the Anka Secure API
    Rather than manually handling HTTP requests or dealing with low-level OpenAPI model classes, developers can invoke straightforward SDK methods such as generateKey(...) or encryptFile(...).

  • Centralized Authentication
    Authenticate once (using authenticateApplication or authenticateUser) and reuse a single AnkaSecureSdk instance for all subsequent cryptographic operations.

  • Consistent Error Handling
    Specialized exceptions (AnkaSecureSdkException) ensure uniform handling of HTTP errors, parsing issues, and network failures.

  • Crypto-Agility
    Supports classical algorithms (RSA, ECC, AES) and post-quantum algorithms (Kyber, Dilithium, Falcon, SPHINCS+). Methods accept flexible parameters (e.g., "Kyber512", "RSA-2048", "AES").

  • Streaming or Non-Streaming
    Offers in-memory operations (for small/medium files) and streaming-based operations (for very large files), covering encryption, decryption, signing, re-encryption, and more.

2. Architecture & Relationship to Other Components

Below is a Mermaid diagram illustrating how a Java application calls into the AnkaSecureSdk, which then leverages the AnkaSecureOpenApiClient to communicate with the Anka Secure API:

flowchart LR
    A[Your Java Application] -->|API Calls| B[AnkaSecureSdk]
    B -->|Method Wrappers| C[AnkaSecureOpenApiClient]
    C -->|HTTP/REST| D[Anka Secure API]
  • Your Java Application: Instantiates and uses AnkaSecureSdk methods (e.g., generateKey, encryptFileStream) for cryptographic tasks.
  • AnkaSecureSdk: Translates high-level requests into OpenAPI calls. Manages parameters, logging, and exception handling.
  • AnkaSecureOpenApiClient: Handles low-level HTTP communication (via OkHttp). Applies configuration like timeouts, proxy settings, TLS verification. Returns responses or streams to the SDK.
  • Anka Secure API: Receives, processes, and executes cryptographic operations on the server side.

3. Key Features

  1. Key Generation

    • Supports both classical and post-quantum.
    • Example:
    GenerateKeySpec spec = new GenerateKeySpec();
spec.setKid("myKeyId");
spec.setKty("RSA");
spec.setAlg("RSA-2048");
sdk.generateKey(spec);

  2. Import / Export / Remove / Revoke Keys

    • Import an existing key (importKey(...)) or a PKCS#12 file (importPrivateKeyPkcs12(...)).
    • Export keys either to a file (exportKey(kid, outputFile)) or return them as objects (exportKey(kid)).
    • Remove or revoke a key with removeKey(kid) or revokeKey(kid).

  3. File Encryption & Decryption

    • Non-Streaming: Simple read-all-bytes, convert to Base64, send to the server, then decode the response. Ideal for smaller files.
    • Streaming: encryptFileStream(...) / decryptFileStream(...) handle large files chunk by chunk, preventing excessive memory use.

  4. Signing / Verification

    • Non-streaming: signFile(...), verifySignature(...).
    • Streaming: signFileStream(...), verifySignatureStream(...).

  5. Re-Encryption / Re-Signing

    • Rotate data from an old RSA or ECC key to a new post-quantum key, or re-sign from an old classical key to a PQC signing key, without exposing plaintext on the client.
    • Non-streaming methods (reencryptFile, resignFile) and streaming methods (reencryptFileStream, resignFileStream) are available.

  6. Utility Methods

    • encryptFileUtilityStream(...), verifySignatureUtilityStream(...) for operations with ephemeral or external public keys not stored in the keystore.

  7. License Checks

    • Check usage limits, plan info, and expiration with getLicenseInfo(clientId).

4. Who Should Use It?

  • Java Developers integrating cryptographic operations into enterprise apps, command-line tools, or microservices.
  • Organizations needing to unify classical and post-quantum security in a single library.
  • CI/CD Pipelines that can embed Java-based steps to manage keys and secure artifacts with consistent error handling.

5. Example Workflow

  1. Initialize the SDK with cli.properties:

    Properties props = new Properties();
props.load(new FileInputStream("cli.properties"));
AnkaSecureSdk sdk = new AnkaSecureSdk(props);`

  2. Authenticate (application or user-based):

    sdk.authenticateApplication("myClientId", "myClientSecret");

    or

    sdk.authenticateUser("[email protected]", "mypassword123");

  3. Perform Operations:

    • Generate a new key: 

          GenerateKeySpec spec = new GenerateKeySpec();
    spec.setKid("myRSAKey");
    spec.setKty("RSA");
    spec.setAlg("RSA-2048");
    sdk.generateKey(spec);

    • Encrypt/Decrypt a file:

        sdk.encryptFile("myRSAKey", "plaintext.txt", "ciphertext.bin");
    sdk.decryptFile("myRSAKey", "ciphertext.bin", "decrypted.txt");

    • Sign a file:

      sdk.signFile("myRSAKey", "document.pdf", "document.sig");

    • Verify signature:

      boolean valid = sdk.verifySignature("myRSAKey", "document.pdf", "document.sig");

    • And more (e.g., reencryptFile, resignFile, streaming variants).

    • Catch Errors
    try {
    sdk.encryptFileStream("myKyberKey", "largeVideo.mov", "video.enc");
} catch(AnkaSecureSdkException e) {
    // Handle error consistently
}

6. Next Steps

  • Using the SDK in Java

    Learn how to add the SDK to your project (Maven/Gradle), set up authentication, and call advanced features.

  • SDK API Integration Examples

    Explore real-world flows (e.g., re-encrypt + rotate keys, large-file streaming encryption).

Using the SDK in Java