AnkaSecureOpenApiClient

Component: AnkaSecureOpenApiClient Purpose: HTTP client layer for AnkaSecure Core API HTTP Library: OkHttp 4.x Part of: AnkaSecure SDK

This page describes how the AnkaSecureOpenApiClient configures the OkHttp client, manages authentication tokens, and handles streaming for large file operations. It also covers advanced aspects like SSL trust, optional proxy usage, progress bars, and property-based configuration.

Technical Documentation with Code Examples

This page contains Java code examples showing how the OpenAPI client works. The code demonstrates:

Configuration patterns: How to set up the HTTP client
Usage examples: How to call API methods
Not implementation code: This is documentation of the SDK's public API

Developers using the SDK may refer to these examples for integration guidance.

1. Introduction

The AnkaSecureOpenApiClient class is the low-level HTTP client driver for all REST calls made by the AnkaSecure Crypto CLI and AnkaSecure SDK. Internally, it wraps an OkHttp-based OpenAPI ApiClient to communicate with the AnkaSecure Core API. All configuration (host, port, timeouts, proxy, etc.) comes from cli.properties or any equivalent Properties object.

Key features:

Centralized authentication: JWT Bearer token management
Configurable HTTP client: Custom interceptors, SSL settings, debugging/logging
Streaming support: Large file operations via multipart form-data with optional progress bar
PQC transport layer: Optional quantum-resistant payload encryption
Auto-generated: Built on OpenAPI-generated code from AnkaSecureAPI.json specification

Used by:

AnkaSecure Crypto CLI (31 commands)
AnkaSecure SDK (programmatic API)
Integration flows (21 example scenarios)

2. Properties and Configuration

Most of the configuration happens automatically inside the constructor, using values from cli.properties or ~/.ankasecure-crypto/config.properties:

# Example configuration
# Application credentials (from Tenant CLI)
clientId=f23aa3b4-5c36-45e0-bfd5-730d1dfddad3
clientSecret=Cr1_xY9zAb2CdE4fGh5IjK6lMn7OpQ8rSt0U

# Server connection
openapi.scheme=https
openapi.host=demo.ankatech.co
openapi.port=443

# TLS settings
openapi.insecureSkipTlsVerify=false

# Timeouts (milliseconds)
openapi.connectTimeoutMs=10000
openapi.readTimeoutMs=30000
openapi.writeTimeoutMs=30000

# Proxy settings (optional)
#openapi.proxyHost=proxy.company.com
#openapi.proxyPort=8080
#openapi.proxyUser=username
#openapi.proxyPassword=password

# PQC Transport Layer (optional)
pqc.transport.enabled=false
# ML-KEM-512/768/1024, HQC-128/192/256 or FRODO-976/1344
pqc.kem.algorithm=ML-KEM-768

# Progress bar for streaming uploads
openapi.enableProgressBar=false

2.1 Server Variables

openapi.scheme: http or https
openapi.host: e.g. demo.ankatech.co
openapi.port: e.g. 443

These are mapped to the @OpenAPIDefinition-based server settings. The client sets them with:

Map<String, String> vars = new HashMap<>();
vars.put("scheme", scheme);
vars.put("host", host);
vars.put("port", port);
apiClient.setServerVariables(vars);

2.2 Timeouts and Debugging

openapi.connectTimeoutMs: Socket connect timeout in milliseconds (default 10s).
openapi.readTimeoutMs: Read timeout (default 30s).
openapi.writeTimeoutMs: Write timeout (default 30s).
openapi.debugging: Boolean to enable low-level OkHttp logging in the ApiClient.

2.3 Proxy Settings

openapi.proxyHost, openapi.proxyPort: If set, the client creates a Proxy(Type.HTTP, InetSocketAddress).
openapi.proxyUser, openapi.proxyPassword: Used for basic proxy authentication (Proxy-Authorization header).

2.4 Insecure Skip TLS Verify

openapi.insecureSkipTlsVerify=true: Disables certificate validation, accepting all SSL certificates.

Warning: This is not recommended for production usage, as it makes the client trust any certificate presented by the server.

2.5 Progress Bar

openapi.enableProgressBar=true: Adds a custom ProgressInterceptor for multipart uploads, printing a console-based progress bar whenever large files are streamed to the server.

3. Authentication Flow

3.1 Application Authentication (Client Credentials)

A typical scenario is application-level authentication via:

// The generated client is internal. Call the facade, which owns the grant plumbing:
SecretChars clientSecret = new SecretChars(rawSecretChars);
String accessToken = client.authenticateApplication(clientId, clientSecret);

Internally the facade invokes the single OAuth 2.0 token operation with the client_credentials grant and stores the result:

TokenResponse resp = tokenManagementApi.createToken(
        "client_credentials", null, null, null,
        UUID.fromString(clientId), secretAsString,
        null, null, null, null, null, null, null, null);
this.currentAccessToken = resp.getAccessToken();
applyBearerToken(this.currentAccessToken);

The generated createToken takes the full RFC 6749 parameter list positionally, and the credential is held as a SecretChars (co.ankatech.ankasecure.sdk.security.SecretChars) at the facade boundary — the facade materializes it as a transient String only for the form-POST body. Do not call the generated client directly.

3.2 No User Authentication

The client authenticates a cryptographic actor only. It has no user sign-in and sends no password: the token endpoint has no password grant, and the crypto CLI is a workload even when a person types the command.

3.3 Bearer Token Application

Once the token is obtained, applyBearerToken(token) sets it in the ApiClient:

co.ankatech.secure.client.invoker.auth.HttpBearerAuth bearerAuth
   = (HttpBearerAuth) apiClient.getAuthentication("bearerAuth");
bearerAuth.setBearerToken(token);

All subsequent requests automatically include Authorization: Bearer <token> in the HTTP headers.

4. Streaming File Operations

The AnkaSecureOpenApiClient is designed to handle large file uploads/downloads in a streaming manner:

Encryption/Decryption (Asymmetric and Symmetric)
Signing/Verification
Re-encryption/Re-signing

4.1 Multipart Form-Data

OkHttp's MultipartBody is used to send the file in chunks. The server response is also streamed. Example (simplified):

File fileToEncrypt = new File(inputFile);
okhttp3.Call call = streamingApi.encryptDataAsymmetricStreamCall(metadata, fileToEncrypt, null);

Response response = okClient.newCall(call.request()).execute();
// read response body as stream...

4.2 Progress Interceptor

When openapi.enableProgressBar=true, a custom ProgressInterceptor is inserted into the OkHttp client pipeline:

It identifies the file part in the multipart request.
Wraps the file in a ProgressTrackingRequestBody.
Prints a textual progress bar (e.g., "Uploading... 33% (3333/10000 bytes)").

Note: This interceptor only affects uploads. Download streaming can still be monitored by reading the response body in a loop.

5. Class Overview

5.1 Fields and APIs

private final ApiClient apiClient: The underlying OpenAPI ApiClient.
private final TokenManagementApi tokenManagementApi: For authentication calls. Both the user and the application flow go through the single OAuth 2.0 token endpoint (createToken), differing only in the grant_type they pass.
private final KeyManagementApi keyManagementApi: For key generation, listing, removal, imports/exports.
private final SecureApi secureApi: For non-streaming encrypt/decrypt/sign/verify.
private final SecureStreamingApi streamingApi: For all streaming-based operations.
private final LicenseManagementApi licenseApi: For retrieving license data.
private String currentAccessToken: The in-memory JWT token used for subsequent requests.

5.2 Initialization Sequence

this.apiClient = Configuration.getDefaultApiClient();
applyServerVariables(): Sets scheme, host, port.
configureHttpClient():
- Timeouts, SSL, proxy settings, debug logging
- progressBarEnabled → if true, add ProgressInterceptor
Instantiate tokenManagementApi, keyManagementApi, secureApi, streamingApi, licenseApi using apiClient.
currentAccessToken = null; until authenticateApplication(...) is called.

5.3 Typical Methods

Key Management:

listKeys(KeyFilters, page, size) → keyManagementApi.listKeys(...)
listKeys(origin, restricted, kty, status, page, size) → keyQueryApi.listAllKeys(...) (returns one KeyPageResponse page envelope). origin, kty and status are each a closed published vocabulary and each is the same token the response field carries; kty = COMPOSITE selects every hybrid key, whose construction is on KeySummaryResponse.compositeMode
Key removal is not on this path: deleting a key is an Admin API operation, reached through ankasecure-km or the Admin Console, not the data-plane client.
getKeyMetadata(kid) → keyManagementApi.getKeyMetadata(kid)

Non-Streaming Operations:

encryptFile(kid, inputFile, outputFile) → reads file → base64 → secureApi.encryptData(...)
decryptFile(inputFile, outputFile) → base64 → secureApi.decryptData(...)
signFile(kid, inputFile, sigFile) → base64 → secureApi.signData(...)

Streaming Operations:

encryptFileStream(kid, inputFile, outputFile) → streamingApi.encryptDataAsymmetricStreamCall(...) → multipart
decryptFileStream(inputFile, outputFile) → streamingApi.decryptDataAsymmetricStreamCall(...)
signFileStream(kid, inputFile, sigFile) → streamingApi.signDataStreamCall(...)
verifySignatureStream(inputFile, sigFile) → streamingApi.verifySignatureStreamCall(...)

Interoperability & Migration:

verifySignatureUtilityStream(...) → raw public key material inline → stream to server for verification
(PKCS#12 import is not an SDK operation — it is POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore on the Admin API)
analyzePkcs7(...) → migrationApi.analyzePkcs7Structure(...)
convertPkcs7ToJose(...) → migrationApi.convertPkcs7ToJose(...)

6. Usage Example

This example shows how to use the OpenAPI client directly (most users will use the SDK instead):

// 1. Load properties (e.g., from cli.properties)
Properties props = new Properties();
props.load(new FileInputStream("cli.properties"));

// 2. Create client
AnkaSecureOpenApiClient openApiClient = new AnkaSecureOpenApiClient(
    ResourceBundle.getBundle("messages"),
    props
);

// 3. Authenticate
openApiClient.authenticateApplication(
    "f23aa3b4-5c36-45e0-bfd5-730d1dfddad3",  // clientId
    "Cr1_xY9zAb2CdE4fGh5IjK6lMn7OpQ8rSt0U"   // clientSecret
);

// 4. The key is already provisioned in the control plane (Admin Console or
//    ankasecure-km). This client is data-plane only and creates none.

// 5. Encrypt a file in streaming mode
openApiClient.encryptFileStream("my-ml-kem-key", "plain.txt", "cipher.jwe");
System.out.println("File encrypted successfully.");

Note: Most developers should use the higher-level AnkaSecureSdk instead of calling the OpenAPI client directly. The SDK provides simplified methods and better error handling.

CLI Documentation

User Guides:

CLI Overview - High-level introduction to features and 31 commands
CLI Commands - Complete command reference
CLI Architecture - Architecture including authentication and logging
Installation Guide - Install CLI on your platform

Technical Documentation:

Maven OpenAPI Generator - Code generation from OpenAPI spec
Internationalization - Multi-language support

SDK Documentation

The OpenAPI client is used internally by the SDK:

SDK Overview - Higher-level SDK wrapping this client
SDK Usage Guide - Recommended way to use the API
Integration Flows - 21 complete code examples
PQC Transport Layer - Quantum-resistant transport encryption

Core API Documentation

Core API Overview^* - REST API specification
Core API Endpoints^* - HTTP endpoint reference
Streaming Operations^* - Large-file handling

Last Updated: December 2025
CLI Version: 3.4.0 Java Version: 25

* restricted content — see higher-tier documentation