AES utility

AES encryption/decryption command-line utility (ECB, CBC, CTR, CFB, OFB, XTS, GCM).

Command-line tool for AES encrypt/decrypt. Requires algorithm (128, 192, 256), key and optional IV/tweak depending on mode. Parameters: command (encrypt/decrypt), algorithm, key, mode, IV as needed, input data. Options: -k <hex_key> Encryption key in hex (required). 128: 32 hex chars, 192: 48, 256: 64. -m <mode> ecb, cbc, ctr, cfb, ofb, xts, gcm (default: ecb). -i <hex_iv> IV/tweak in hex (required for cbc, ctr, cfb, ofb, xts; gcm uses 12-byte nonce). -d Debug mode. -h Interpret input as hex string. -v Version.

NOXTLS AES Utility - Command-line tool for AES cryptographic operations.

Version

v0.1.4

Building

The AES utility is built as part of the main NoxTLS project using CMake and Ninja.

Prerequisites

• CMake (version 3.10 or higher)
• Ninja build system
• C compiler (GCC, Clang, or MSVC)

Build Instructions

From the project root directory:

cd build
ninja aes

The executable will be generated at: build/applications/aes/aes.exe (Windows) or build/applications/aes/aes (Linux/macOS)

Usage

Basic Syntax

aes [algorithm] [options] [data...]

Supported Algorithms

The utility supports three AES key sizes:

• 128 - AES-128 (128-bit key)
• 192 - AES-192 (192-bit key)
• 256 - AES-256 (256-bit key)

Command-Line Options

Option	Description
-k <hex_key>	Required. Encryption key in hexadecimal format. Key length must match the algorithm: AES-128 requires 16 bytes (32 hex chars), AES-192 requires 24 bytes (48 hex chars), AES-256 requires 32 bytes (64 hex chars)
-m <mode>	Cipher mode: ecb, cbc, ctr, cfb, ofb (default: ecb)
-i <hex_iv>	Initialization Vector in hexadecimal format. Required for cbc, ctr, cfb, ofb modes. Must be 16 bytes (32 hex characters)
-d	Enable debug mode (prints additional diagnostic information)
-h	Interpret input data as hexadecimal string

Input Data Types

The utility supports two input data formats:

1. String Input (Default): Plain text strings provided as command-line arguments

   • Multiple arguments are concatenated with spaces
   • Maximum input size: 4096 bytes

2. Hexadecimal Input: Binary data provided as a hexadecimal string (use -h flag)

   • The hex string is converted to binary before processing

Key Requirements

The encryption key must be provided using the -k option. The key must be specified as a hexadecimal string, and the length must match the selected algorithm:

• AES-128: 16 bytes = 32 hexadecimal characters
• AES-192: 24 bytes = 48 hexadecimal characters
• AES-256: 32 bytes = 64 hexadecimal characters

Cipher Modes

The utility supports multiple cipher block modes:

• ECB (Electronic Codebook) - Default mode. Each block is encrypted independently. No IV required.
• CBC (Cipher Block Chaining) - Each block is XORed with the previous ciphertext before encryption. IV required.
• CTR (Counter Mode) - A counter is encrypted to produce a keystream, which is XORed with the plaintext. IV required. Supports arbitrary-length data without padding.
• CFB (Cipher Feedback) - The previous ciphertext block is encrypted to produce a keystream. IV required. Supports arbitrary-length data without padding.
• OFB (Output Feedback) - The keystream is generated by repeatedly encrypting the IV/previous keystream. IV required. Supports arbitrary-length data without padding.

Note: For modes requiring an IV (CBC, CTR, CFB, OFB), the IV must be exactly 16 bytes (32 hexadecimal characters).

Examples

Example 1: Encrypt string data with AES-128 (ECB mode, default)

aes 128 -k 2b7e151628aed2a6abf7158809cf4f3c Hello World

This encrypts the string "Hello World" using AES-128 in ECB mode with the key 2b7e151628aed2a6abf7158809cf4f3c (16 bytes = 32 hex characters).

Example 2: Encrypt with AES-128 in CBC mode

aes 128 -k 2b7e151628aed2a6abf7158809cf4f3c -m cbc -i 00000000000000000000000000000000 Hello World

This encrypts "Hello World" using AES-128 in CBC mode. The IV is all zeros (16 bytes = 32 hex characters).

Example 3: Encrypt with AES-128 in CTR mode

aes 128 -k 2b7e151628aed2a6abf7158809cf4f3c -m ctr -i 00000000000000000000000000000000 Hello

This encrypts "Hello" using AES-128 in CTR mode. CTR mode supports arbitrary-length data without padding.

Example 4: Encrypt with AES-256 in CFB mode

aes 256 -k 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f -m cfb -i 00000000000000000000000000000000 This is a test message

This encrypts "This is a test message" using AES-256 in CFB mode with debug information enabled.

Example 5: Encrypt with AES-192 in OFB mode

aes 192 -k 000102030405060708090a0b0c0d0e0f1011121314151617 -m ofb -i 00000000000000000000000000000000 Hello World

This encrypts "Hello World" using AES-192 in OFB mode.

Example 6: Encrypt hexadecimal input with AES-128 (CBC mode)

aes 128 -h -k 2b7e151628aed2a6abf7158809cf4f3c -m cbc -i 00000000000000000000000000000000 48656c6c6f20576f726c64

This encrypts the hexadecimal string "48656c6c6f20576f726c64" (which represents "Hello World" in ASCII) using AES-128 in CBC mode.

Example 7: Encrypt with a test vector (AES-128, ECB mode)

aes 128 -k 2b7e151628aed2a6abf7158809cf4f3c -h 3243f6a8885a308d313198a2e0370734

This encrypts the test vector data using the standard AES-128 test key in ECB mode. The expected output is 3925841d02dc09fbdc118597196a0b32.

Output

The utility outputs the encrypted data in hexadecimal format.

• ECB and CBC modes: The output length will be a multiple of 16 bytes (AES block size), as the input data is padded to the nearest block boundary.
• CTR, CFB, and OFB modes: The output length equals the input length (no padding required).

Example output:

Encrypted data:
3925841d02dc09fbdc118597196a0b32

The encrypted data is displayed as a hexadecimal string, with each byte represented by two hex characters.

Error Handling

• If no algorithm is specified, the utility will display: No algorithm specified and exit with code -1
• If no key is specified, the utility will display: Error: Key not specified. Use -k <hex_key> to provide the encryption key. and exit with code -1
• If the key length doesn't match the algorithm, the utility will display an error message indicating the expected key length and exit with code -1
• If an IV/tweak is required but not provided (for CBC, CTR, CFB, OFB, XTS, GCM modes), the utility will display: Error: IV/tweak required for mode. Use -i <hex_iv> to provide the IV. and exit with code -1
• If GCM nonce length is incorrect (not 12 bytes), the utility will display: Error: GCM nonce must be 12 bytes (24 hex characters), got X bytes and exit with code -1
• If the IV/tweak length is incorrect (not 16 bytes), the utility will display: Error: IV must be 16 bytes (32 hex characters), got X bytes and exit with code -1
• If an unknown mode is specified, the utility will display: Error: Unknown mode 'X'. Supported modes: ecb, cbc, ctr, cfb, ofb, xts and exit with code -1
• If memory allocation fails, the utility will display: Error: Memory allocation failed and exit with code -1
• If AES encryption fails, the utility will display: Error: AES encryption failed and exit with code -1

Debug Mode

When debug mode is enabled (-d flag), the utility prints:

• Debug level information
• Function names and data lengths
• Argument parsing details
• String length information

Implementation Notes

Current Status

The utility now performs actual AES encryption using the NOXTLS_aes library. It supports:

• AES encryption with AES-128, AES-192, and AES-256
• Multiple cipher modes: ECB, CBC, CTR, CFB, OFB, XTS, and GCM
• Key validation - ensures key length matches the selected algorithm (16/24/32 bytes)
• IV/tweak support - Initialization Vector support for CBC, CTR, CFB, OFB, XTS, and GCM modes
• Automatic padding - input data is padded with zeros to AES block boundaries (16 bytes) for ECB and CBC modes
• Stream modes - CTR, CFB, OFB, XTS, and GCM support arbitrary-length data without padding
• Hex key/IV input - keys and IVs must be provided as hexadecimal strings via the -k and -i options
• Multiple input formats - supports both plain text strings and hexadecimal data input

Future Enhancements

Potential future improvements could include:

• AES decryption functionality
• PKCS#7 padding instead of zero padding for ECB and CBC modes
• GCM (Galois/Counter Mode) support for authenticated encryption
• Standardized XTS key splitting (current XTS uses single key material for both halves)
• GCM decryption and AAD support for the CLI
• Support for reading input from files
• Support for writing output to files
• Support for key derivation functions (PBKDF2, etc.)

Integration with NoxTLS Library

The utility links against the following NoxTLS libraries:

• NOXTLS_common - Common utilities and string functions
• NOXTLS_hash - Hash functions (MD5, SHA variants)
• NOXTLS_encryption - AES encryption implementation

Copyright

Copyright (c) 2019-2026 Argenox Technologies LLC. All Rights Reserved.

Contact

For questions or support, contact: info@argenox.com

Examples

AES-128 ECB encrypt (key and plaintext in hex): aes -k 2b7e151628aed2a6abf7158809cf4f3c -m ecb -h 6bc1bee22e409f96e93d7e117393172a AES-256 CBC with IV: aes -k 603deb1015ca71be2b73aef0857d77811f352c073b6108d72d9810a30914dff4 -m cbc -i 000102030405060708090a0b0c0d0e0f -h <hex_plaintext> Show usage: aes