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 minimal modifications needed for a production-like environment:

###############################################################################
# CLI AUTHENTICATION (SECURE INIT METHOD RECOMMENDED)
# Use 'AnkaSecureCLI init' to securely store your clientId/clientSecret
###############################################################################
clientIdEnc=U2FsdGVkX19tR4i5LXeWJqT2b59Yi1gZFpAB0ZPaz9xMftEJXa4gRmJq8Rw=
clientSecretEnc=U2FsdGVkX1+UO4+9DZr1mzTrA9f/hEqLPvWRO9XVeZZ6Bg==
client.uuid=af4b17ea-5a3e-4e0a-a3c7-d3a8e17e02d1
client.salt=ZGVtb1NhbHRIYXNoZWRTYWx0Cg==
# These credentials are encrypted and automatically injected by the `init` command.
# DO NOT edit them manually unless instructed.
###############################################################################
# OPENAPI SERVER VARIABLES
###############################################################################
openapi.scheme=https
openapi.host=demo.ankatech.co
openapi.port=443
openapi.insecureSkipTlsVerify=false

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

###############################################################################
# PROXY SETTINGS (if needed):
###############################################################################
#openapi.proxyHost=proxy.mycompany.com
#openapi.proxyPort=8080
#openapi.proxyUser=someUser
#openapi.proxyPassword=somePassword

###############################################################################
# PROGRESS BAR FOR LARGE FILE UPLOADS
###############################################################################
openapi.enableProgressBar=false

###############################################################################
# LOGGING CONFIGURATION
# Controls both user logs and developer logs. Adjust levels and file sizes 
# based on your environment.
###############################################################################
user.log.level = INFO
user.log.filename = AnkaSecureCLI.log
user.log.filenamePattern = AnkaSecureCLI.%i.log
user.log.maxFileSize = 5MB

# dev.log.level = DEBUG
# dev.log.filename = dev.log
# dev.log.filenamePattern = dev.%i.log
# dev.log.maxFileSize = 10MB

# root.log.level = WARN

Initialization via CLI (`init` command)

Instead of manually specifying clientId and clientSecret in plaintext within your cli.properties file, you must securely initialize them using the init command provided by the CLI:

AnkaSecureCLI init

This command will:

Prompt for Credentials:

You will be prompted to enter your clientId and clientSecret.

For automation, use the --silent flag to suppress interactive messages.
Force Overwrite:

If the CLI is already initialized, use the --force flag to overwrite existing credentials without further prompt.
Custom Configuration File:

Optionally, use the --config-path=<file> flag to specify an alternate configuration file.

Upon successful initialization, the CLI will encrypt your credentials using AES-GCM (with a derived key from a randomly generated UUID and salt) and update your cli.properties with secure entries:

clientIdEnc=...
clientSecretEnc=...
client.uuid=...
client.salt=...`

Important: Always use AnkaSecureCLI init (with --force if needed) when setting up or rotating credentials.

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

Key Sections

Authentication Credentials (Secure Initialization Recommended)
- The AnkaSecure CLI supports secure initialization via the init command.
- Credentials are encrypted and stored as:
```
clientIdEnc=U2FsdGVkX1+...
clientSecretEnc=U2FsdGVkX1+...
client.uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
client.salt=...
```
- To set these securely, run:
```
AnkaSecureCLI init
```
  This command will prompt you to enter your credentials and store them in encrypted form.
OpenAPI Server Variables
- openapi.scheme, openapi.host, and openapi.port define the server connection.
- openapi.insecureSkipTlsVerify=false ensures TLS certificate validation is enforced---recommended for production.
Timeouts
- openapi.connectTimeoutMs=10000 (10 seconds) for initial connection attempts.
- openapi.readTimeoutMs=30000 and openapi.writeTimeoutMs=30000 for data transfers.
Proxy Settings
- Uncomment and configure proxy settings if needed.
- Accepts openapi.proxyHost, openapi.proxyPort, openapi.proxyUser, and openapi.proxyPassword.
Progress Bar
- openapi.enableProgressBar=false by default. Set to true to display a progress indicator for large file transfers.
Logging Configuration
- user.log.level=INFO defines the verbosity of user logs (INFO is recommended in production).
- user.log.filename and user.log.filenamePattern control log rotation.
- Developer logs (dev.log.level) are available but disabled by default.
- root.log.level=WARN sets the base logging level.

How to Apply `cli.properties`

Same Directory as the JAR

If cli.properties is in the same folder as AnkaSecureCLI.jar, the CLI will auto-discover it.
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

Production TLS

Keep openapi.insecureSkipTlsVerify=false to ensure strict certificate validation.
Secret Handling

The clientSecret is sensitive. Store cli.properties securely and restrict file permissions.
Log Rotation

Ensure that user.log.filenamePattern and user.log.maxFileSize are properly configured to prevent excessive log file growth.
Proxy Settings

Configure only if necessary and verify that your network traffic is correctly routed.
Periodically Rotate Credentials

If your clientId or clientSecret changes, simply run:
```
AnkaSecureCLI init --force
```
(Use --silent for automated scripts if needed.)\ This will securely overwrite the existing encrypted credentials in cli.properties without manual editing.

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

Both approaches use the same cli.properties configuration.

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 AnkaSecureCLI.log.

Conclusion

The AnkaSecure CLI provides crypto-agility, post-quantum security, and large-file streaming in a secure command-line environment. By configuring cli.properties to your environment and using the init command to securely store your credentials, you can ensure robust, script-friendly, and secure operations. This configuration file centralizes your CLI's authentication, server settings, timeouts, proxy, and logging preferences, making integration with DevOps pipelines seamless and secure.