Using the AnkaSecure SDK in Java

This guide explains how to integrate the AnkaSecure SDK into your Java applications. From configuring Maven/Gradle dependencies to instantiating the SDK and calling high-level cryptographic methods, you’ll learn the essential steps to get started.

For a detailed API reference, please also check our Javadocs.

1. Adding the SDK to Your Project

1.1 Maven Dependency

If the AnkaSecure SDK is published to a Maven repository (public or private), add it to your pom.xml:

<dependencies>
  <dependency>
    <groupId>co.ankatech</groupId>
    <artifactId>ankasecure-sdk</artifactId>
    <version>1.0.0</version> <!-- or the appropriate version -->
  </dependency>
</dependencies>

<repositories>
  <repository>
    <id>anka-maven-repo</id>
    <name>Anka Maven Repo</name>
    <url>https://repo.ankatech.co/maven</url> <!-- Example URL -->
  </repository>
</repositories>

Note: If the SDK is not in a remote repo, you can install the JAR locally via:
   mvn install:install-file -Dfile=AnkaSecureSdk-1.0.0.jar\
   -DgroupId=co.ankatech\
   -DartifactId=ankasecure-sdk\
   -Dversion=1.0.0\
   -Dpackaging=jar
Then add it as a dependency in your POM.

1.2 Gradle Dependency

For Gradle, update your build.gradle:

repositories {
    maven {
        url "https://repo.ankatech.co/maven"
        // credentials, if needed...
    }
    // or mavenLocal() if installed locally
}

dependencies {
    implementation 'co.ankatech:ankasecure-sdk:1.0.0'
}

2. Project Setup & Configuration

2.1 Load Your `cli.properties`

The SDK typically relies on Properties that mirror the config used by the AnkaSecure CLI. This includes server details, timeouts, TLS settings, and more.

Properties props = new Properties();
try (FileInputStream fis = new FileInputStream("cli.properties")) {
    props.load(fis);
} catch (IOException e) {
    // handle exception
}

Make sure cli.properties includes the correct clientId, clientSecret, and openapi settings (host, port, scheme, etc.). For reference:

clientId=allApp
clientSecret=demoAppPass!
openapi.scheme=https
openapi.host=demo.ankatech.co
openapi.port=443
openapi.insecureSkipTlsVerify=false
...

3. Instantiating the SDK

Once you have the Properties object ready, construct an AnkaSecureSdk:

import co.ankatech.ankasecure.sdk.AnkaSecureSdk;

AnkaSecureSdk sdk = new AnkaSecureSdk(props);

This initializes:

AnkaSecureOpenApiClient internally, respecting proxy, timeouts, and TLS configurations.
Logging via SLF4J (with user logger and dev logger).
A resource bundle for localized error messages.

4. Authentication

4.1 Application-Level Authentication

Use authenticateApplication(clientId, clientSecret) if your Java service or CI/CD process has application credentials:

sdk.authenticateApplication("myCiCdApp", "mySuperSecret");

4.2 User-Level Authentication

If your scenario requires user-based roles/permissions, call authenticateUser(username, password):

sdk.authenticateUser("[email protected]", "P@ssw0rd");

Important: After authentication, the SDK automatically injects the bearer token into future requests.

5. Basic Usage

Once authenticated, you can call any key management or crypto method. Below are common examples:

5.1 Generate a Key

import co.ankatech.ankasecure.sdk.model.GenerateKeySpec;
...
GenerateKeySpec spec = new GenerateKeySpec();
spec.setKid("myNewRsaKey");
spec.setKty("RSA");
spec.setAlg("RSA-2048");
spec.setExportable(true);

sdk.generateKey(spec);

5.2 Encrypt/Decrypt a File

// Encrypt
sdk.encryptFile("myNewRsaKey", "plain.txt", "encrypted.bin");

// Decrypt
sdk.decryptFile("myNewRsaKey", "encrypted.bin", "decrypted.txt");

5.3 Sign/Verify

// Sign
sdk.signFile("mySignKey", "document.pdf", "document.sig");

// Verify
boolean isValid = sdk.verifySignature("mySignKey", "document.pdf", "document.sig");
System.out.println("Signature valid? " + isValid);

5.4 Streaming Large Files

// Streaming Encryption
sdk.encryptFileStream("myKeyId", "bigVideo.mp4", "bigVideo.enc");

// Streaming Decryption
sdk.decryptFileStream("myKeyId", "bigVideo.enc", "bigVideo.dec");

6. Error Handling

Most SDK methods throw AnkaSecureSdkException on failure. This centralizes:

HTTP Errors (4xx, 5xx)
Network Issues (timeouts, unreachable hosts)
Validation Problems (invalid parameters, expired tokens)

try {
    sdk.encryptFile("myKeyId", "plain.txt", "enc.bin");
} catch (AnkaSecureSdkException e) {
    System.err.println("Failed to encrypt file: " + e.getMessage());
    // e.getHttpStatus() or e.getResponseBody() might also be useful
}

7. Advanced Features

Importing Keys
- sdk.importKey(ImportKeySpec keyData) to load an existing key from Base64 or PEM.
- sdk.importPrivateKeyPkcs12(Pkcs12ImportSpec p12spec) for .p12/.pfx with optional password.
Re-encrypting / Re-signing
- sdk.reencryptFile(oldKid, newKid, input, output) rotates ciphertext from oldKid to newKid.
- sdk.resignFile(oldKid, newKid, dataFile, oldSig, newSig) verifies the old signature, then signs with the new key.
License Info
- String licenseDetails = sdk.getLicenseInfo("someClientId");
- Great for checking usage stats or expiry dates.
Utility Methods (Ephemeral Keys)
- encryptFileUtilityStream(kty, alg, publicKeyBase64, input, output)
- verifySignatureUtilityStream(kty, alg, publicKeyBase64, signatureBase64, inputFile)

8. Logging

By default, the SDK uses SLF4J with two named loggers:

co.ankatech.cli.user: High-level or user-facing logs (INFO-level recommended).
co.ankatech.cli.dev: Developer logs for debugging (DEBUG-level recommended).

Configure your logging framework (e.g., Logback, Log4j2) to capture these appropriately.

9. Where to Go Next?

SDK API Integration Examples

Real-world flows such as multi-step re-encryption, rotating keys mid-deployment, or combining streaming operations.
SDK Overview

High-level architecture and concept summary.

10. Troubleshooting & Support

Common Errors:
- 401 Unauthorized: Check your clientId, clientSecret, or user credentials.
- 404 Not Found: Validate the kid or resource ID exists.
- 500 Internal Server Error: Often indicates server-side issues---check logs or contact support.
SLF4J Logging: Enable DEBUG or TRACE in the dev logger to see raw request/response details.
AnkaTech Support: For further assistance, contact us at [email protected].