AnkaSecure CLI – Configuration Guide

This document outlines how to configure and run the AnkaSecure CLI. By specifying authentication credentials, server details, and logging preferences in cli.properties, you can seamlessly connect to the AnkaSecure API and perform cryptographic operations.

Sample cli.properties

Below is an example cli.properties file with all available configuration options. This template is included with installers and automatically copied to ~/.ankasecure-crypto/config.properties on first run.

# ═══════════════════════════════════════════════════════════
# AnkaSecure Crypto CLI - Configuration Template
# ═══════════════════════════════════════════════════════════
# Documentation: https://docs.ankatech.co
# ═══════════════════════════════════════════════════════════

# ═══════════════════════════════════════════════════════════
# SERVER CONNECTION
# ═══════════════════════════════════════════════════════════

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

# TLS verification (set to true ONLY for self-signed certificates)
openapi.insecureSkipTlsVerify=false

# ═══════════════════════════════════════════════════════════
# CONNECTION TIMEOUTS
# ═══════════════════════════════════════════════════════════

# Timeout values in milliseconds
openapi.connectTimeoutMs=10000
openapi.readTimeoutMs=30000
openapi.writeTimeoutMs=30000

# ═══════════════════════════════════════════════════════════
# PROXY CONFIGURATION (Optional)
# ═══════════════════════════════════════════════════════════

# Uncomment and configure if using HTTP proxy
#openapi.proxyHost=proxy.mycompany.com
#openapi.proxyPort=8080
#openapi.proxyUser=username
#openapi.proxyPassword=password

# ═══════════════════════════════════════════════════════════
# PQC TRANSPORT ENCRYPTION
# ═══════════════════════════════════════════════════════════

# Enable ML-KEM encryption wrapper for all API communications
pqc.transport.enabled=false

# PQC session time-to-live in seconds (600 = 10 minutes)
pqc.session.ttl.seconds=600

# KEM algorithm for transport encryption (ML-KEM-512, ML-KEM-768, ML-KEM-1024)
pqc.kem.algorithm=ML-KEM-768

# ═══════════════════════════════════════════════════════════
# LOGGING CONFIGURATION
# ═══════════════════════════════════════════════════════════

# User log settings (console + file output)
user.log.level=INFO
user.log.filename=user.log
user.log.filenamePattern=user.%i.log
user.log.maxFileSize=5MB

# Development log settings (file only, detailed debug info)
dev.log.level=DEBUG
dev.log.filename=dev.log
dev.log.filenamePattern=dev.%i.log
dev.log.maxFileSize=10MB

# Root logger level (fallback for uncategorized logs)
root.log.level=WARN

# ═══════════════════════════════════════════════════════════
# DEBUG FEATURES
# ═══════════════════════════════════════════════════════════

# HTTP request/response debugging (logs headers to dev.log)
openapi.debugging=false

# Progress bar for large file uploads/downloads
openapi.enableProgressBar=false

# Timing metrics for operations
openapi.enableTimingMetrics=false

# ═══════════════════════════════════════════════════════════
# AUTHENTICATION CREDENTIALS (Encrypted)
# ═══════════════════════════════════════════════════════════
# Generated after first login via interactive mode or 'init' command
# DO NOT edit manually - use login wizard or: ankasecure-crypto init
#
# Example (after login):
# client.uuid=63cfdf0d48f9481088d08f5fd9fcdbf0
# client.salt=4313618a4a836609cbff69badccb2801
# clientIdEnc=KSv9KCpouy8VYDDr07jP7arF3ac5BDgjNBzQcW0EwPk...
# clientSecretEnc=5B3K++Fhkd7l9jgkOMnchoMnd5AcHtYnUuH7j+XWnQu...

Initialization via CLI

The AnkaSecure CLI provides two methods for secure credential initialization:

Method 1: Interactive Mode (Recommended for First-Time Users)

Launch the guided wizard for complete setup:

ankasecure-crypto interactive

Then select: Authentication & Setup > Login

The wizard will guide you through: 1. Server configuration (URL, TLS settings) 2. API credentials entry (Client ID and Secret) 3. Configuration review and confirmation 4. Automatic credential encryption and storage

Method 2: Command-Line Init

For quick setup or automation, use the init command:

# Basic initialization
ankasecure-crypto init

# Force overwrite existing credentials
ankasecure-crypto init --force

# Silent mode for automation (no interactive prompts)
ankasecure-crypto init --force --silent

# Custom configuration file location
ankasecure-crypto init --config-path=/path/to/custom.properties

Security Features

Upon successful initialization, the CLI will:

1. Generate unique encryption key material (client.uuid and client.salt)
2. Derive a 256-bit AES key using PBKDF2 with 150,000 iterations
3. Encrypt your credentials using AES-256-GCM
4. Store encrypted values in config.properties:

client.uuid=63cfdf0d48f9481088d08f5fd9fcdbf0
client.salt=4313618a4a836609cbff69badccb2801
clientIdEnc=KSv9KCpouy8VYDDr07jP7arF3ac5BDgjNBzQcW0EwPk...
clientSecretEnc=5B3K++Fhkd7l9jgkOMnchoMnd5AcHtYnUuH7j+XWnQu...

Important:

✅ Always use ankasecure-crypto init or interactive mode for credential management

❌ Do not manually edit the encrypted properties (clientIdEnc, clientSecretEnc, client.uuid, client.salt)

🔄 To update credentials, use ankasecure-crypto init --force

Key Sections

1. Server Connection

Defines how the CLI connects to the AnkaSecure API server:

• openapi.scheme - Protocol (https recommended)
• openapi.host - Server hostname (e.g., demo.ankatech.co)
• openapi.port - Server port (default: 443 for HTTPS)
• openapi.insecureSkipTlsVerify - Skip TLS certificate validation
  • ⚠️ Set to true ONLY for development with self-signed certificates
  • ✅ Always use false in production environments

2. Connection Timeouts

Control HTTP connection behavior for network resilience:

• openapi.connectTimeoutMs - Initial connection timeout (default: 10,000ms = 10 seconds)
• openapi.readTimeoutMs - Read timeout for receiving data (default: 30,000ms = 30 seconds)
• openapi.writeTimeoutMs - Write timeout for sending data (default: 30,000ms = 30 seconds)

💡 Tip: Increase timeouts if experiencing slow network connections or working with large files.

3. Proxy Configuration (Optional)

Configure HTTP proxy for corporate networks:

• openapi.proxyHost - Proxy server hostname
• openapi.proxyPort - Proxy server port (e.g., 8080)
• openapi.proxyUser - Username for proxy authentication
• openapi.proxyPassword - Password for proxy authentication

All proxy settings are commented out by default. Uncomment and configure as needed.

4. PQC Transport Encryption

Add quantum-resistant encryption layer over HTTPS:

• pqc.transport.enabled - Enable/disable PQC transport wrapper (default: false)
  • Provides ML-KEM encryption for all API communications
  • Adds overhead but ensures quantum resistance
• pqc.session.ttl.seconds - Session lifetime before re-handshake (default: 600 = 10 minutes)
• pqc.kem.algorithm - KEM algorithm selection
  • Options: ML-KEM-512, ML-KEM-768, ML-KEM-1024
  • Higher numbers = stronger security, slower performance

💡 Note: HTTPS alone provides sufficient security for most use cases. Enable PQC transport only if your security policy requires quantum-resistant protection at the transport layer.

5. Logging Configuration

Complete control over CLI logging behavior:

User Logs (console + file)

• user.log.level - Log level for user-facing messages
  • Options: TRACE, DEBUG, INFO, WARN, ERROR
  • Default: INFO (recommended for production)
• user.log.filename - Main log file name (default: user.log)
• user.log.filenamePattern - Pattern for rolled files (default: user.%i.log)
• user.log.maxFileSize - Max size before rotation (default: 5MB)

Development Logs (file only)

• dev.log.level - Detailed debug logging level (default: DEBUG)
• dev.log.filename - Dev log file name (default: dev.log)
• dev.log.filenamePattern - Pattern for rolled dev logs (default: dev.%i.log)
• dev.log.maxFileSize - Max size before rotation (default: 10MB)

Root Logger

• root.log.level - Fallback level for third-party library logs (default: WARN)

📁 Log Files Generated: - user.log, user.1.log, user.2.log, user.3.log (rolling) - dev.log, dev.1.log, dev.2.log, dev.3.log (rolling)

6. Debug Features

Advanced features for troubleshooting and performance analysis:

• openapi.debugging - HTTP request/response debugging
  • Logs HTTP headers to dev.log (NOT bodies, to protect credentials)
  • Default: false
  • Enable for API communication troubleshooting
• openapi.enableProgressBar - Visual progress indicator
  • Shows upload/download progress for streaming operations
  • Default: false
  • Recommended for large files (>100MB)
• openapi.enableTimingMetrics - Operation timing logs
  • Logs execution time for each cryptographic operation
  • Default: false
  • Useful for performance profiling

7. Authentication Credentials (Encrypted Storage)

The AnkaSecure CLI uses AES-256-GCM encryption with PBKDF2 key derivation (150,000 iterations, NIST SP 800-90A compliant) to protect your credentials:

• client.uuid - Unique identifier for key derivation
• client.salt - Random salt for PBKDF2
• clientIdEnc - Encrypted Client ID (Base64-encoded)
• clientSecretEnc - Encrypted Client Secret (Base64-encoded)

⚠️ Important: These properties are automatically generated. Do NOT edit manually.

To configure credentials securely:

# Interactive mode (recommended for first-time users)
ankasecure-crypto interactive
# Select: Authentication & Setup > Login

# Command-line mode
ankasecure-crypto init

# Force re-authentication
ankasecure-crypto init --force

How to Apply cli.properties

1. Same Directory as the JAR

   If cli.properties is in the same folder as AnkaSecureCLI.jar, the CLI will auto-discover it.

2. Custom Path

   You can specify an alternate configuration file using the system property:

   java -Dcli.config=/path/to/cli.properties -jar AnkaSecureCLI.jar list-keys
   

Best Practices

1. Production TLS

✅ Always keep openapi.insecureSkipTlsVerify=false to ensure strict certificate validation.

⚠️ Never disable TLS verification in production environments.

2. Secret Handling

The configuration file contains encrypted credentials but should still be protected:

• Store config.properties with restricted file permissions (chmod 600 on Unix/Linux)
• Never commit config.properties to version control
• Use the init command or interactive login wizard - never edit credentials manually
• Rotate credentials periodically using ankasecure-crypto init --force

3. Log Management

Configure log rotation to prevent disk space issues:

• Production: Set user.log.level=INFO to balance information vs. noise
• Troubleshooting: Temporarily increase to DEBUG or TRACE
• File size: Keep maxFileSize reasonable (5-10MB) for manageable log files
• Retention: System keeps 3 rolled files automatically (configurable in logback.xml)

Log files location: - Default: Same directory as CLI executable - Can be changed via absolute path in user.log.filename property

4. Network Configuration

Timeouts

• Slow networks: Increase timeouts to 60,000ms or higher
• Fast networks: Keep defaults (10,000-30,000ms)
• Large files: Increase writeTimeoutMs for uploads, readTimeoutMs for downloads

Proxy

• Configure only if required by corporate network policy
• Verify proxy credentials and test connectivity after configuration
• Use environment variables for sensitive proxy passwords in CI/CD

5. PQC Transport Layer

• Default recommendation: Keep pqc.transport.enabled=false
  • HTTPS provides sufficient security for standard use cases
  • PQC transport adds 15-30% overhead
• Enable when:
  • Organizational policy requires quantum-resistant transport
  • Handling highly sensitive data requiring defense-in-depth
  • Preparing for post-quantum threat landscape
• Algorithm selection:
  • ML-KEM-512: Fastest, adequate for most use cases
  • ML-KEM-768: NIST recommended (default)
  • ML-KEM-1024: Maximum security, slower

6. Credential Rotation

Regularly rotate API credentials for security compliance:

# Interactive re-authentication (guided wizard)
ankasecure-crypto interactive
# Then select: Authentication & Setup > Re-authenticate

# Command-line re-authentication
ankasecure-crypto init --force

# Automated scripts (non-interactive)
ankasecure-crypto init --force --silent

7. Debug Mode for Troubleshooting

When experiencing issues, enable debug features temporarily:

# Temporary debug configuration
openapi.debugging=true              # HTTP header logging
user.log.level=DEBUG                # Verbose user logs
dev.log.level=TRACE                 # Maximum detail
openapi.enableTimingMetrics=true    # Performance metrics

After troubleshooting, remember to disable debug features to reduce log volume and overhead.

Executable vs. JAR Usage

When installing the AnkaSecure CLI via the provided installers (e.g., .exe for Windows, .dmg for macOS, or .sh for Linux), the installation process typically produces two native executables in your chosen install directory:

• AnkaSecureCLI -- Standard command-line interface.

• AnkaSecureCLIDemo -- An interactive, menu-driven demo showcasing example scenarios.

These executables are convenience wrappers around AnkaSecureClient.jar. You can run them directly or run the JAR manually:

java -jar AnkaSecureClient.jar list-keys

Example Usage

Once your cli.properties is configured and you have securely initialized your credentials via init, the CLI will automatically use the specified secure credentials and server settings.

# List keys using the configured properties
java -jar AnkaSecureClient.jar list-keys

# Generate a new key
java -jar AnkaSecureClient.jar generate-key --kid myTestKey --kty RSA --alg RSA-2048

CLI operations are logged according to the user.log.level setting and saved to the configured log files (user.log by default).

Configuration Properties Reference

Complete Property List

Total: 30 configurable properties + 4 auto-generated credentials

Property Groups by Use Case

Minimal Setup (Required)

openapi.scheme=https
openapi.host=demo.ankatech.co
openapi.port=443
# Credentials set via: ankasecure-crypto init

Corporate Network

# Add to minimal setup:
openapi.proxyHost=proxy.company.com
openapi.proxyPort=8080
openapi.proxyUser=youruser
openapi.proxyPassword=yourpass

Troubleshooting

# Add to minimal setup:
openapi.debugging=true
user.log.level=DEBUG
dev.log.level=TRACE
openapi.enableTimingMetrics=true

Maximum Security

# Add to minimal setup:
pqc.transport.enabled=true
pqc.kem.algorithm=ML-KEM-1024
openapi.insecureSkipTlsVerify=false

Large File Operations

# Add to minimal setup:
openapi.enableProgressBar=true
openapi.readTimeoutMs=120000
openapi.writeTimeoutMs=120000

Conclusion

The AnkaSecure CLI provides crypto-agility, post-quantum security, and large-file streaming in a secure command-line environment. With 30+ configuration properties, you can customize every aspect of the CLI's behavior:

• 🌐 Server connection and network resilience
• 🔐 Quantum-resistant transport encryption
• 📊 Comprehensive logging for operations and debugging
• 🚀 Performance tuning with progress bars and metrics
• 🔒 Enterprise features including proxy support and credential encryption

By configuring cli.properties to your environment and using the init command to securely store your credentials, you ensure robust, script-friendly, and secure operations. This centralized configuration makes integration with DevOps pipelines, CI/CD systems, and automated workflows seamless and secure.