AnkaSecure Crypto CLI — Overview

CLI Name: AnkaSecure Crypto CLI Binary: AnkaSecureCLI (fat JAR: ankasecure-cli-crypto-3.4.0-fat.jar) Version: 3.4.0 Language: Java 25 Total subcommands: 27

The AnkaSecure Crypto CLI is the end-user command-line tool for running cryptographic operations against the AnkaSecure Core API. It performs file-level encryption, decryption, signing, verification, combined operations, streaming for large files, and PKCS#7 → JOSE conversion. It also offers read-only key browsing so an operator can inspect the available keys before invoking a crypto command.

Administrative key write/lifecycle operations (generate, import, patch, rotate, revoke, archive, delete, export) do not live in this CLI. They belong to the Key Management CLI (ankasecure-km) and the Admin Console. The Crypto CLI's job is to use keys, not to manage them.

Key characteristics

• 27 Picocli subcommands covering crypto operations on data + read-only key browsing.
• Two invocation modes: single-shot flag CLI and a guided interactive boxed menu (--interactive).
• 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; encrypt-file and sign-file auto-switch at the server's configured compact limit — crypto.max-plaintext-bytes, default 4 MB, discovered via GET /api/v3/crypto/limits — unless PQC transport is enabled; explicit *-stream variants for predictable behaviour).
• Built on the AnkaSecure SDK and Bouncy Castle 1.86 providers.
• OAuth2 client_credentials issued during init, encrypted at rest with AES-256-GCM + PBKDF2 (150 000 iterations).

Table of contents

1. What is the Crypto CLI?
2. Command surface
3. Streaming vs non-streaming
4. Interactive mode
5. Authentication and credentials
6. Internationalization
7. Quick start
8. Related documentation

1. What is the Crypto CLI?

The Crypto CLI is a thin presentation layer on top of the AnkaSecure SDK; it does not implement cryptography directly. The layering is:

AnkaSecure Crypto CLI (27 subcommands)
    ↓ uses
AnkaSecure SDK (Java library)
    ↓ uses
AnkaSecureOpenApiClient (generated from OpenAPI spec)
    ↓ calls
AnkaSecure Core API (REST endpoints)

This separation lets the same cryptographic primitives be consumed from the CLI, from custom Java code, or from automation pipelines, while keeping the cryptographic logic and key custody on the server side.

2. Command surface

27 subcommands across five groups:

Getting started (2)

Key browsing (read-only, 3)

Administrative key writes are intentionally absent. To create, import, patch, rotate, revoke, archive or export keys, or to request their destruction, use ankasecure-km or the Admin Console.

Authorization for the key-browsing commands:

• list-keys and get-key-metadata require the CLI's actor to hold the two read-only key-management scopes key_management.listKeys and key_management.viewKeyMetadata. These return tenant-wide key metadata (no key material) and need no capability grant — the actor authorizes on its JWT scopes alone. For a SIMPLE tenant the Internal Crypto Use Case orchestrator auto-grants both scopes to the actor it provisions, so these commands work out of the box. For a STANDARD tenant a tenant administrator assigns the two scopes to the actor via the admin-console "Manage roles" dialog ("Key browsing (read-only)" group).
• get-supported-algorithms requires no scope: GET /api/v3/key-management/supported-algorithms authorizes with isAuthenticated(), so any authenticated CLI session can read the algorithm catalog. (An unauthenticated session still receives 401.)

See Authentication — Actor-Assignable Key-Management Read Scopes^*.

Crypto operations — small files (8)

Streaming — large files (10)

PKCS#7 / CMS migration (4)

See the Commands Reference for the full per-command option matrix.

Values a newer server adds. A value this release does not declare — a new key status, origin, algorithm category or composite mode — is printed as the server sent it, in every output format.

3. Streaming vs non-streaming

The CLI exposes two complementary models for crypto operations:

Four of the eight commands in the "small files" group choose streaming on their own. encrypt-file and sign-file auto-switch when the input reaches the server's configured compact limit (crypto.max-plaintext-bytes, default 4 MB, discovered via GET /api/v3/crypto/limits); if their compact call is rejected with 413, the CLI (via the SDK) transparently retries via streaming. decrypt-file and reencrypt-file choose by the input's format: a streaming artifact is processed over the streaming route. verify-signature, sign-encrypt-file, decrypt-verify-file and resign-file always use the compact endpoint. The ten *-stream commands are explicit streaming variants for callers that want deterministic behaviour regardless of size.

With PQC transport enabled (pqc.transport.enabled=true), the commands that pick streaming by file size, encrypt-file and sign-file, do not switch automatically. The streaming routes travel under TLS only, so streaming is an explicit choice: a file at or above the compact limit, or a compact upload refused as too large in a response the PQC session did not encrypt, ends the command with exit code 3 and a message naming the command to run instead with the same arguments (encrypt-file-stream, sign-file-stream). decrypt-file and reencrypt-file of a streaming artifact use the TLS-only streaming route, as at encryption time. See Excluded Endpoints.

Useful flags on encrypt-file and sign-file:

• --quiet — suppress the informational message about which mode is being used.
• --force-compact — force compact mode even for large files (may produce HTTP 413).

4. Interactive mode

The CLI ships with a guided boxed menu UX for end-user crypto sessions:

java -jar ankasecure-cli-crypto-3.4.0-fat.jar --interactive

Menu layout (post-3.0.0):

1. Authentication & Setup
2. View Supported Algorithms (Hybrid/PQC/Classical)
3. View Keys                                 ← read-only browsing
4. Encryption & Decryption
5. Digital Signatures
6. Combined Operations (Sign+Encrypt)
7. Streaming Operations
8. PKCS#7/CMS Migration & Conversion
9. Utilities & Information
0. Exit

Option 3 — View Keys — only exposes "List All Keys" and "View Key Details". Generation, import, lifecycle management and export are not available from this menu; they live in ankasecure-km and the Admin Console.

See the Interactive Mode Guide for screenshots, navigation rules and ESC/cancel semantics.

5. Authentication and credentials

Authentication flow

Each session authenticates with OAuth2 client_credentials. The tenant administrator creates the application and its actor in the Admin Console, assigns the actor the secure.encrypt, secure.decrypt, secure.sign and secure.verifySignature roles, and issues its credential: the actor UUID is the client id, and the client secret is shown once.

Credential storage

init encrypts the credentials with AES-256-GCM, derives the key with PBKDF2 (150 000 iterations) using a machine-bound secret + 32-byte random salt, and writes the result to ~/.ankasecure-crypto/config.properties with POSIX mode 0600 on supported filesystems.

The JWT issued at runtime is held in memory only and never persisted; renewals come from the encrypted refresh credential.

Configuration resolution order

1. --config-path <file> flag on the command line.
2. Environment variable ANKASECURE_CONFIG.
3. Default: ~/.ankasecure-crypto/config.properties.
4. Fallback: cli.properties in the current working directory.

Optional PQC transport

The CLI can optionally negotiate an ML-KEM session over HTTPS, providing a quantum-resistant transport layer on top of TLS. See PQC Transport Layer^*.

6. Internationalization

The CLI's user-visible strings are externalized in resource bundles:

• English (default)
• Spanish (es)

Locale resolution follows standard Java ResourceBundle rules. Force a locale via the JVM:

java -Duser.language=es -jar ankasecure-cli-crypto-3.4.0-fat.jar list-keys

See Internationalization for the full bundle layout.

7. Quick start

Step 1 — install

Download a platform installer or fat JAR from the Installation Guide. Available media:

• Windows: .exe (x64, ARM64) + .zip portable
• macOS: .dmg (Universal, ARM64, x64)
• Linux: .sh (Universal, x64, ARM64) + tarball

Step 2 — initialize

# Interactive (prompts for client_id, client_secret, server URL)
java -jar ankasecure-cli-crypto-3.4.0-fat.jar init

# Non-interactive: --client-secret takes no value, so the secret comes from the environment
# Typed at a silent read: a value written into an export line stays in the shell history
read -rs ANKASECURE_CLIENT_SECRET
export ANKASECURE_CLIENT_SECRET
java -jar ankasecure-cli-crypto-3.4.0-fat.jar init \
    --silent \
    --client-id <CLIENT_ID> \
    --url https://api.example.com

Step 3 — inspect available keys

java -jar ankasecure-cli-crypto-3.4.0-fat.jar list-keys
java -jar ankasecure-cli-crypto-3.4.0-fat.jar get-key-metadata --kid my-mlkem-key

Step 4 — encrypt and decrypt

java -jar ankasecure-cli-crypto-3.4.0-fat.jar encrypt-file \
    --kid my-mlkem-key \
    --input-file plaintext.txt \
    --output-file ciphertext.bin

java -jar ankasecure-cli-crypto-3.4.0-fat.jar decrypt-file \
    --input-file ciphertext.bin \
    --output-file roundtrip.txt

Step 5 — sign and verify

java -jar ankasecure-cli-crypto-3.4.0-fat.jar sign-file \
    --kid my-mldsa-key \
    --input-file contract.pdf \
    --output-signature-file contract.sig

java -jar ankasecure-cli-crypto-3.4.0-fat.jar verify-signature \
    --input-signature-file contract.sig

Step 6 — re-encrypt for algorithm rotation (RSA → ML-KEM)

After a new key is created in the Admin Console or with ankasecure-km keys create:

java -jar ankasecure-cli-crypto-3.4.0-fat.jar reencrypt-file-stream \
    --new-kid my-mlkem-key \
    --input-file legacy-data.enc \
    --output-file pqc-data.enc

Step 7 — convert legacy PKCS#7 structures to JOSE

java -jar ankasecure-cli-crypto-3.4.0-fat.jar analyze-pkcs7 --input-file legacy-signed.p7s
java -jar ankasecure-cli-crypto-3.4.0-fat.jar convert-pkcs7 \
    --input-file legacy-signed.p7s \
    --output-file modern-signed.jws \
    --serialization AUTO

The CLI's actor needs REENCRYPT and RESIGN Capability Grants on the file's keys (not DECRYPT, ENCRYPT or SIGN), or the conversion is refused 403; see convert-pkcs7. The conversion changes the container (PKCS#7 to JWS / JWE) and keeps the classical algorithm; Step 6 (reencrypt-file / resign-file with a post-quantum --new-kid) is what moves the content to PQC.

8. Related documentation

Crypto CLI

• Installation
• Commands Reference
• Interactive Mode Guide
• Architecture
• Internationalization
• OpenAPI Client
• Maven OpenAPI Generator

Key Management CLI (administrative key management)

• Key Management CLI Overview
• Key Management CLI Commands
• Key Management CLI Usage Examples

SDK

• SDK Overview
• SDK Usage Guide

Cryptography

• Algorithm Catalog
• PQC Transport Architecture^*
• FIPS 140-3, Random Bit Generation and Approved Algorithms

CLI Version: 3.4.0 Java Version: 25

© 2025 ANKATech Solutions Inc. All rights reserved.