Skip to content

AnkaSecure CLI – Command Reference

This document provides a comprehensive reference for all commands available in the AnkaSecure CLI.
Each command ultimately communicates with the AnkaSecure API, so no sensitive operations are performed locally.

Table of Contents

  1. Overview
  2. General Usage
  3. Key Management Commands
  4. File Encryption & Decryption
  5. File Signing & Verification
  6. Re-Encrypt & Re-Sign (Non-Streaming)
  7. Streaming File Encryption & Decryption
  8. Streaming File Signing & Verification
  9. Re-Encrypt & Re-Sign (Streaming)
  10. Public Key-Only Streaming Operations
  11. License Management
  12. Help Command

Overview

  • CLI Name: AnkaSecureCLI
  • Invocation:
    java -jar AnkaSecureCLI.jar <command> [options]
  • Purpose: Offers direct command-line access to cryptographic operations and key management via the AnkaSecure API.

General Usage

java -jar AnkaSecureCLI.jar <command> [options]

  • command: One of the available commands (see list below).
  • options: Arguments specific to each command (e.g., --kid <keyId>, --input-file <path>).

Example:

java -jar AnkaSecureCLI.jar generate-key --kid myKeyId --kty RSA --alg RSA-2048

Note: You may need to set environment variables or pass configuration flags for authentication (e.g., -Danka.api.token=<token>), depending on your deployment.

Key Management Commands

1. generate-key

Usage:

generate-key --kid <kid> --kty <kty> --alg <alg> [--key-ops <commaSeparatedKeyOps>] [--exportable <true|false>] [--expires-at <ISO8601DateTime>] [--soft-limit-expiration <ISO8601DateTime>] [--max-usage-limit <integer>] [--soft-usage-limit <integer>] [--validity-days <days>]

Description: Generates a new cryptographic key (classical, PQC, or symmetric) with optional constraints (usage limits, expiration).

  • Parameters:
    • --kid <kid>: Unique key identifier.
    • --kty <kty>: Key type (e.g., RSA, EC, oct, ML-KEM, DILITHIUM, etc.).
    • --alg <alg>: Algorithm parameter set (e.g., RSA-2048, ES256, AES-256).
    • --key-ops <commaSeparatedKeyOps>: Key operations (e.g., encrypt,decrypt).
    • --exportable <true|false>: Whether the key can be exported.
    • --expires-at <ISO8601DateTime> or --validity-days: Key expiration.
    • --soft-limit-expiration <ISO8601DateTime>: Warn before hard expiration.
    • --max-usage-limit <integer>: Maximum operations permitted on key.
    • --soft-usage-limit <integer>: Soft usage threshold.

2. import-key

Usage:

import-key --json-file <pathToJsonFile>

Description:\ Imports a key from a JSON file that includes kid, kty, alg, keyOps, and optionally publicKey/privateKey in Base64.

  • Example JSON:
{
    "kid": "myKeyId",
    "kty": "RSA",
    "alg": "RSA-2048",
    "keyOps": ["encrypt", "verify"],
    "publicKey": "BASE64_ENCODED_PUBLIC_KEY",
    "privateKey": "BASE64_ENCODED_PRIVATE_KEY"  // optional
}

3. import-key-pkcs12

Usage:

import-key-pkcs12 --kid <kid> --p12-base64 <base64Pkcs12> [--p12-password <password>]

Description:\ Imports a private key from a PKCS#12 (.p12 or .pfx) file in Base64 format.

  • Parameters:
    • --kid <kid>: Key identifier.
    • --p12-base64 <base64Pkcs12>: Base64-encoded PKCS#12 file contents.
    • --p12-password <password>: Optional password if the PKCS#12 is protected.

4. list-keys

Usage:

list-keys

Description:\ Lists all keys in the keystore, without revealing private key material.

5. export-key

Usage:

export-key --kid <kid> --output-file <filePath>

Description:\ Exports the key metadata and, if asymmetric, the public key to a JSON file.\ No private material is exposed.

6. remove-key

Usage:

remove-key --kid <kid>

Description:\ Permanently removes a key from the keystore.

7. revoke-key

Usage:

revoke-key --kid <kid>

Description:\ Marks a key as REVOKED, preventing any future usage. Irreversible.

8. get-supported-algorithms

Usage:

get-supported-algorithms

Description:\ Retrieves a dynamic list of supported (kty, alg) combinations, reflecting the system's crypto-agility.

File Encryption & Decryption

9. encrypt-file

Usage:

encrypt-file --kid <kid> --input-file <filePath> --output-file <filePath>

Description:\ Encrypts a file (base64-encoded internally) using the public key of the specified kid.

10. decrypt-file

Usage:

decrypt-file --kid <kid> --input-file <filePath> --output-file <filePath>

Description:\ Decrypts a file (base64-encoded) using the private key of the specified kid.

File Signing & Verification

11. sign-file

Usage:

sign-file --kid <kid> --input-file <filePath> --output-signature-file <filePath>

Description:\ Signs the contents of input-file (base64-encoded internally) with the private key associated with kid.\ The generated signature is saved in output-signature-file.

12. verify-signature

Usage:

verify-signature --kid <kid> --input-file <filePath> --input-signature-file <filePath>

Description:\ Verifies the signature of a file using the public key associated with kid.\ If verification fails, an error is returned.

Re-Encrypt & Re-Sign (Non-Streaming)

13. reencrypt-file

Usage:

reencrypt-file --old-kid <kid1> --new-kid <kid2> --input-file <filePath> --output-file <filePath>

Description:\ Decrypts data with oldKid (private key) and encrypts it again with newKid (public key).\ Useful for migrating ciphertext from RSA to a post-quantum key, etc.

14. resign-file

Usage:

resign-file --old-kid <kid1> --new-kid <kid2> --input-file <filePath> --old-signature-file <filePath> --new-signature-file <filePath>

Description:\ Verifies the file with oldKid (public key) and re-signs it using newKid (private key).\ Helps migrate signatures from classical to post-quantum algorithms.

Streaming File Encryption & Decryption

15. encrypt-file-stream

Usage:

encrypt-file-stream --kid <kid> --input-file <filePath> --output-file <filePath>

Description:\ Encrypts a file in streaming mode. Large files are handled chunk by chunk, reducing memory usage.

16. decrypt-file-stream

Usage:

decrypt-file-stream --kid <kid> --input-file <filePath> --output-file <filePath>

Description:\ Decrypts a file streaming chunk by chunk, using kid (private key).\ Ideal for very large ciphertext.

Streaming File Signing & Verification

17. sign-file-stream

Usage:

sign-file-stream --kid <kid> --input-file <filePath> --output-signature-file <filePath>

Description:\ Signs a file in streaming mode, reading chunks of data and generating a final signature.\ Suitable for large files (GB+).

18. verify-signature-stream

Usage:

verify-signature-stream --kid <kid> --input-file <filePath> --input-signature-file <filePath>

Description:\ Verifies a signature in streaming mode, using the public key of kid.\ Never loads the entire file into memory at once.

Re-Encrypt & Re-Sign (Streaming)

19. resign-file-stream

Usage:

resign-file-stream --old-kid <kid1> --new-kid <kid2> --old-signature-file <filePath> --input-file <filePath> --new-signature-file <filePath>

Description:\ Stream-based re-signing: verifies the file chunk by chunk with oldKid (public) and re-signs each chunk with newKid (private).

20. reencrypt-file-stream

Usage:

reencrypt-file-stream --old-kid <kid1> --new-kid <kid2> --input-file <filePath> --output-file <filePath>

Description:\ Stream-based re-encryption from oldKid (private) to newKid (public).\ Ensures plaintext never resides fully in memory.

Public Key-Only Streaming Operations

21. encrypt-file-publickey-stream

Usage:

encrypt-file-publickey-stream --alg <alg> --public-key <base64PublicKey> --input-file <filePath> --output-file <filePath>

Description:\ Streaming encryption using a provided public key (in base64) without storing it in the keystore.\ Useful for temporary or ephemeral encryption tasks.

22. verify-signature-publickey-stream

Usage:

verify-signature-publickey-stream --kty <kty> --alg <alg> --public-key <base64PublicKey> --input-signature-file <filePath> --input-file <filePath>

Description:\ Streaming signature verification using a provided public key (base64) without referencing a stored key.

License Management

23. get-license-info

Usage:

get-license-info --client <clientId>

Description:\ Retrieves license details (plan tier, expiry date) and usage info (operation counts, data usage, etc.) for the specified clientId.

Help Command

24. --help

Usage:

--help

Description:\ Displays the full help information, including all commands and their parameters.

Tips & Best Practices

  1. Authentication:

    • Typically, you must set environment variables or pass flags to include a Bearer token or API key.

    • For example:

      bash

      CopiarEditar

      java -Danka.api.token=YOUR_ACCESS_TOKEN -jar AnkaSecureCLI.jar list-keys

  2. Error Handling:

    • All commands return non-zero exit codes on failure. Capture these in scripts for error detection.
  3. Scripting:
    • Integrate these CLI commands into CI/CD pipelines or shell scripts for automated cryptographic workflows (key rotation, secure backups, signing releases, etc.).
  4. Large Files:
    • Use streaming commands (*-stream) to handle files that do not fit into memory.
  5. Key Rotation:
    • Combine generate-key, reencrypt-file, and resign-file (or streaming variants) to migrate to new keys regularly.

Conclusion

The AnkaSecure CLI provides a broad set of key management and crypto commands that integrate seamlessly with the AnkaSecure API. Whether you need simple encryption, complex re-encryption for post-quantum upgrades, or signing large artifacts in a continuous pipeline, these commands offer a flexible, script-friendly approach to modern cryptographic workflows.