ironcrypt 0.1.2

Library-first crypto toolkit: Argon2 password hashing, AES-256-GCM / XChaCha20 streaming, RSA/ECC hybrid encryption, and optional CLI/daemon.
Documentation

IronCrypt

IronCrypt is a Command-Line Interface (CLI) tool and Rust library dedicated to secure password and data encryption. By combining the Argon2 hashing algorithm, AES-256-GCM or XChaCha20-Poly1305 for symmetric encryption, and modern asymmetric cryptography like RSA or Elliptic Curve Cryptography (ECC), IronCrypt provides a robust, flexible solution to ensure your application’s data confidentiality and password security.

Features

  • Modern, Hybrid Encryption: IronCrypt uses a robust hybrid encryption model. It encrypts data with a high-performance symmetric cipher (AES-256-GCM or XChaCha20-Poly1305) and protects the symmetric key using state-of-the-art asymmetric cryptography. This "envelope encryption" provides the best of both worlds: the speed of symmetric ciphers and the secure key management of public-key cryptography.
  • Flexible Asymmetric Cryptography: Choose between RSA for broad compatibility or Elliptic Curve Cryptography (ECC) for higher performance and smaller key sizes, offering equivalent security with less overhead. Both are fully supported for encryption and digital signatures.
  • Multi-Recipient Encryption: Natively supports encrypting a single file or directory for multiple users, even with different key types (e.g., some recipients using RSA, others ECC). Each user can decrypt the data with their own unique private key, without needing to share secrets.
  • Passphrase-Encrypted Keys: Private keys can be optionally encrypted with a user-provided passphrase for an added layer of security, protecting them even if the key files are exposed.
  • State-of-the-Art Password Hashing: For passwords, IronCrypt uses Argon2, currently considered one of the most secure hashing algorithms in the world. It is specifically designed to resist modern GPU-based brute-force attacks, providing much greater security than older algorithms.
  • Advanced Key Management: The built-in key versioning system (-v v1, -v v2) and the dedicated rotate-key command allow you to update your encryption keys over time. This automates the process of migrating to a new key without having to manually decrypt and re-encrypt all your data. IronCrypt can load both modern PKCS#8 keys and legacy PKCS#1 keys, ensuring broad compatibility.
  • Flexible Configuration: You can finely tune security parameters via the ironcrypt.toml file, environment variables, or the IronCryptConfig struct in code. This includes RSA key size and the computational "costs" of the Argon2 algorithm, allowing you to balance security and performance to fit your needs.
  • Streaming Encryption: For AES-256-GCM without signatures, IronCrypt encrypts and decrypts in chunks without loading the whole file into memory. Limits: (1) XChaCha20-Poly1305 is one-shot (plaintext is buffered); (2) a signature in the header also requires pre-buffering the content for hashing. Prefer unsigned AES for very large files.
  • Comprehensive Data Encryption: IronCrypt is built to handle more than just passwords. It can encrypt any file (images, PDFs, documents), entire directories (by archiving them first), or any other data that can be represented as a stream of bytes.
  • Dual Use (CLI and Library): IronCrypt is designed from the ground up to be dual-purpose. You can use it as a quick command-line tool for simple tasks, or integrate it as a library (crate) directly into your own Rust applications for more complex logic.

Quick start

Copy-paste examples aligned with the current code.

1. Prepare a local lab

git clone https://github.com/teamflp/ironcrypt.git
cd ironcrypt

cargo build --release --features full

# Copy example fixtures (never commit real keys)
make bootstrap-lab
# → keys.json, ironcrypt.toml, keys/private_key_v1.pem, keys/public_key_v1.pem

2. CLI — keys, file, password

./target/release/ironcrypt generate -v v1 -d keys -s 2048

./target/release/ironcrypt encrypt-file \
  -i report.pdf -o report.enc -d keys -v v1

./target/release/ironcrypt decrypt-file \
  -i report.enc -o report.out.pdf -k keys -v v1

# Password (Argon2id hash sealed in JSON — never stored in cleartext)
./target/release/ironcrypt encrypt -w 'Str0ngP@ssw0rd42!' -d keys -v v1 > secret.json
./target/release/ironcrypt decrypt -w 'Str0ngP@ssw0rd42!' -k keys -f secret.json

3. HTTP daemon (ironcryptd)

API permissions: read, write, delete, update, full.
Endpoints: POST /write (encrypt) and POST /read (decrypt).

./target/release/ironcrypt generate-api-key
# → note the secret API key (base64) and the Hash (SHA-512 hex)

# keys.json uses camelCase, e.g.:
# { "description": "lab", "keyHash": "<HASH_HEX>", "permissions": ["write", "read"] }

./target/release/ironcryptd \
  --host 127.0.0.1 --port 3000 \
  --key-directory keys --key-version v1 \
  --api-keys-file keys.json \
  --config ironcrypt.toml \
  --rate-limit-per-sec 20 --rate-limit-burst 40

export API_KEY='<SECRET_API_KEY_BASE64>'

echo 'hello ironcrypt' | curl -sS --request POST \
  --header "Authorization: Bearer ${API_KEY}" \
  --data-binary @- \
  http://127.0.0.1:3000/write > payload.enc

curl -sS --request POST \
  --header "Authorization: Bearer ${API_KEY}" \
  --data-binary @payload.enc \
  http://127.0.0.1:3000/read

# Optional Argon2 gate: -H "X-Password: Str0ngP@ssw0rd42!"

In-process HTTPS:

./target/release/ironcryptd \
  --host 0.0.0.0 --port 3443 \
  --tls-cert cert.pem --tls-key key.pem \
  --key-directory keys --key-version v1 \
  --api-keys-file keys.json --config ironcrypt.toml

4. Docker Compose (lab vs prod)

make bootstrap-lab
make lab    # Vault -dev + lab token (never for production)
# make prod

5. Rust library (AES streaming)

use ironcrypt::{
    algorithms::SymmetricAlgorithm,
    decrypt_stream, encrypt_stream, generate_rsa_keys,
    keys::{PrivateKey, PublicKey},
    Argon2Config, PasswordCriteria,
};
use std::io::Cursor;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (sk, pk) = generate_rsa_keys(2048)?;
    let public_key = PublicKey::Rsa(pk);
    let private_key = PrivateKey::Rsa(sk);

    let original = b"secret streamed message";
    let mut src = Cursor::new(original.as_slice());
    let mut enc = Cursor::new(Vec::new());
    let mut password = String::new();

    encrypt_stream(
        &mut src,
        &mut enc,
        &mut password,
        [(&public_key, "v1")],
        None, // no signature → real AES streaming
        &PasswordCriteria::default(),
        Argon2Config::default(),
        false,
        SymmetricAlgorithm::Aes256Gcm,
    )?;

    enc.set_position(0);
    let mut out = Cursor::new(Vec::new());
    decrypt_stream(&mut enc, &mut out, &private_key, "v1", "", None)?;
    assert_eq!(out.into_inner(), original);
    Ok(())
}

Using IronCrypt from PHP

PHP applications do not link the Rust crate. They talk to the ironcryptd HTTP daemon with the small client in sdks/php (IronCryptClient).

PHP app  --POST /write|/read + Bearer-->  ironcryptd  (holds PEM keys)

Why this model?

  • One crypto service shared by PHP, Python, curl, etc.
  • API keys with fine-grained permissions (write, read, …)
  • No need to ship private keys inside every PHP container

Setup

# 1) Daemon (from repo root)
cargo build --release --features full && make bootstrap-lab
./target/release/ironcrypt generate-api-key   # secret (base64) + hash → keys.json
./target/release/ironcryptd \
  --host 127.0.0.1 --port 3000 \
  --key-directory keys --key-version v1 \
  --api-keys-file keys.json --config ironcrypt.toml

# 2) PHP SDK
cd sdks/php && composer install

keys.json must use camelCase (keyHash) and permissions such as ["write", "read"].
Send the secret API key as Authorization: Bearer … without re-encoding it.

Minimal PHP example

<?php
require_once __DIR__ . '/vendor/autoload.php';

use IronCrypt\Sdk\IronCryptClient;

$client = new IronCryptClient(getenv('IRONCRYPT_URL') ?: 'http://127.0.0.1:3000');
$apiKey = getenv('IRONCRYPT_API_KEY'); // base64 secret from generate-api-key

$ciphertext = $client->encrypt('sensitive payload', $apiKey); // POST /write
$plaintext  = $client->decrypt($ciphertext, $apiKey);        // POST /read

// Optional Argon2 gate:
// $client->encrypt($data, $apiKey, 'Str0ngP@ssw0rd42!');

Store ciphertext as a DB BLOB or base64_encode($ciphertext) for text columns.

Full walkthrough (Composer path repo, cURL without SDK, errors 401/403/429, alternatives CLI/FFI): see sdks/php/README.md.
Python HTTP client: sdks/python.

Using IronCrypt via FFI (C ABI)

For in-process use (no HTTP daemon), link or load the dynamic library built by Cargo (cdylib) and call the C API declared in ironcrypt.h.

Python / Java / C# / C / PHP-FFI  --native calls-->  libironcrypt (.so / .dylib / .dll)

FFI vs daemon

FFI (libironcrypt) HTTP (ironcryptd + SDKs)
Process Same process as your app Separate service
Auth You pass PEM material yourself API key Bearer + permissions
Best for Native apps, JVM/.NET, low latency PHP/web, multi-language microservices
C API scope today Password workflow (Argon2 + RSA envelope) Files/streams via /write /read, secrets, …

Build the library

cargo build --release
# Linux:  target/release/libironcrypt.so
# macOS:  target/release/libironcrypt.dylib
# Windows: target/release/ironcrypt.dll

API surface

Function Success Role
ironcrypt_generate_rsa_keys 0 Allocate PEM private/public strings
ironcrypt_password_encrypt 0 Password → sealed JSON
ironcrypt_password_verify 1 / 0 / -1 Valid / invalid / error
ironcrypt_free_string — Must free every string Rust allocated

Minimal idea (Python ctypes)

import ctypes
lib = ctypes.CDLL("target/release/libironcrypt.dylib")  # .so on Linux

lib.ironcrypt_generate_rsa_keys.restype = ctypes.c_int32
# … set argtypes, call encrypt/verify, then:
# lib.ironcrypt_free_string(ptr)

Native C sample: examples/c_api_usage.c.
Full examples (Python ctypes, Java JNA, C# P/Invoke, PHP FFI, build flags, troubleshooting): FFI_EXAMPLES.md.

Workflows

Password Encryption/Decryption

workflow-password.png

This process ensures maximum security by combining robust hashing with Argon2 and hybrid encryption (called "envelope encryption") with AES and RSA.

1. Encryption Process (e.g., during user registration)

The goal here is not to encrypt the password itself, but to encrypt a unique fingerprint (a "hash") of that password. The plaintext password is never stored.

  1. Password Hashing:

    • The password provided by the user (e.g., "MyPassword123") is first passed through the Argon2 hashing algorithm.
    • Argon2 transforms it into a unique and non-reversible digital fingerprint (the "hash"). This algorithm is designed to be slow and memory-intensive, making it extremely resistant to modern brute-force attacks.

  2. Creating the Encryption Envelope:

    • A new AES-256 symmetric encryption key is randomly generated. This key is for one-time use and will only be used for this operation.
    • The Argon2 hash (created in step 1) is then encrypted using this AES key.

  3. Securing the AES Key (the "seal" of the envelope):

    • To be able to verify the password later, the AES key must be saved. Storing it in plaintext would be a security flaw.
    • Therefore, the AES key is itself encrypted, but this time with your public RSA key. Only the holder of the corresponding private RSA key will be able to decrypt this AES key.

  4. Storing the Secure Data:

    • The final result is a structured JSON object that contains all the necessary information for future verification:
      • The encrypted Argon2 hash (AES ciphertext) — the hash is never duplicated in cleartext in the JSON.
      • The AES key encrypted with RSA/ECC (envelope).
      • Public technical parameters (nonce, key version, algorithm).
    • It is this JSON object that is securely stored in your database.

2. Verification Process (e.g., during user login)

The goal here is to verify if the password provided by the user matches the stored one, without ever having to see it in plaintext.

  1. Data Retrieval:

    • The user logs in by providing their password (e.g., "MyPassword123").
    • You retrieve the corresponding JSON object for this user from your database.

  2. Opening the Envelope:

    • Using your private RSA key, you decrypt the AES key contained in the JSON.
    • Once the plaintext AES key is obtained, you use it to decrypt the original Argon2 hash.

  3. Real-time Hashing and Comparison:

    • The password just provided by the user for login is hashed in turn, using the exact same parameters (the "salt") as those stored in the JSON.
    • The two hashes—the one just generated and the one decrypted from the database—are compared.

  4. Verification Result:

    • If the two hashes are identical, it proves that the provided password is correct. Access is granted.
    • If they are different, the password is incorrect. Access is denied.

This workflow ensures that even if your database were compromised, the users' passwords would remain unusable by an attacker, as the original password is never stored there.

File Encryption/Decryption

img.png

This process also uses envelope encryption (AES + RSA) to ensure both performance and security.

1. Encryption Process

  1. Opening File Streams: IronCrypt opens the input file for reading and the output file for writing. In AES-256-GCM without a signature, content is processed in chunks (streaming). With XChaCha20 or a signature, an in-memory buffer of the content is required (see Features).
  2. Creating the Envelope Header:
    • A new one-time use AES-256 key is randomly generated.
    • This AES key is encrypted with one or more public RSA keys (one for each recipient).
    • A JSON header is created containing a list of recipients, where each entry contains the encrypted AES key for that user and their key version.
  3. Streaming Encryption:
    • The JSON header is written to the start of the output file.
    • IronCrypt then reads the input file in small chunks, encrypts each chunk with the AES key, and immediately writes the encrypted chunk to the output file.
  4. Finalizing: Once the entire file has been processed, an authentication tag is appended to the end of the output file to ensure its integrity.

2. Decryption Process

  1. Reading the Header: IronCrypt reads the JSON header from the start of the encrypted file.
  2. Opening the Envelope:
    • Your private RSA key is used to find your entry in the recipients list and decrypt the AES key.
  3. Streaming Decryption:
    • With the AES key, IronCrypt reads the rest of the encrypted file in chunks, decrypts each chunk, and writes the plaintext data to the output file.
  4. Verification and Saving: After processing all chunks, it verifies the authentication tag. If valid, the original file is fully restored.

Directory Encryption/Decryption

img.png

Encrypting an entire directory is based on the file encryption workflow, with an additional preparation step.

1. Encryption Process

  1. Archiving and Compression:
    • The target directory is first read, and all its files and subdirectories are compressed into a single .tar.gz archive, which is written to a temporary file on disk.
  2. Encrypting the archive:
    • This temporary .tar.gz archive is then encrypted using the streaming file encryption process described above.
  3. Storage: The resulting JSON is saved to a single encrypted file.

2. Decryption Process

  1. Decrypting the archive:
    • The file decryption process is used to retrieve the plaintext .tar.gz archive.
  2. Decompression and Extraction:
    • The .tar.gz archive is then decompressed, and its contents are extracted to the destination directory, thus recreating the original structure and files.

Installation

Prerequisites

  • Rust ≥ 1.88 (MSRV for the default library build — see rust-version in Cargo.toml)
  • Latest stable recommended for CLI / full / cloud features
  • Cargo (Rust's package manager)

MSRV notes

Feature set Minimum rustc (approx.) Notes
default (library) 1.88 Guaranteed / CI-tested (time etc. in the lockfile)
cli / daemon / full (no AWS bump) 1.88 Same baseline
aws / current AWS SDK in the lockfile 1.94.1+ Upstream aws-config / Smithy crates declare this

The CI job MSRV 1.88 runs cargo check/test --lib on every push.

Building and Running from Source

There are three main ways to run the ironcrypt command-line tool.

1. Using cargo run (Recommended for development)

This command compiles and runs the program in one step. Use -- to separate cargo's arguments from your program's arguments.

# Clone the repository
git clone https://github.com/teamflp/ironcrypt.git
cd ironcrypt

# Run the --help command (CLI feature required)
cargo run --features cli -- --help

2. Building and running the executable directly

You can build the executable and then run it from its path in the target directory.

# Build the optimized CLI (+ daemon) — defaults are library-only
cargo build --release --features full

# Run it from its path
./target/release/ironcrypt --help

3. Installing the binary (Recommended for usage)

This will install the ironcrypt command on your system, making it available from any directory. This is the best option for regular use.

# From the root of the project directory, run:
cargo install --path . --features full
# Or from crates.io (once published):
# cargo install ironcrypt --features full

# Now you can use the command from anywhere
ironcrypt --help

4. Building a static Linux binary (MUSL)

Build portable static binaries (no glibc required), useful for minimal containers and Alpine.

Prerequisites (choose your OS):

  • Debian/Ubuntu:
sudo apt-get update && sudo apt-get install -y musl-tools lld
rustup target add x86_64-unknown-linux-musl
  • macOS (Homebrew):
brew install FiloSottile/musl-cross/musl-cross
rustup target add x86_64-unknown-linux-musl

Build the release binaries:

cargo build --locked --release --target x86_64-unknown-linux-musl
# Binaries:
#   target/x86_64-unknown-linux-musl/release/ironcrypt
#   target/x86_64-unknown-linux-musl/release/ironcryptd

Note: The repo’s .cargo/config.toml is already configured for MUSL (musl-gcc + lld). If you see “musl-gcc not found”, install musl-tools (Linux) or musl-cross (macOS) as above.

5. Build and run with Docker

A multi-stage Dockerfile builds static binaries and ships a tiny runtime image.

CI publishes images to GitHub Container Registry on every master push:

docker pull ghcr.io/teamflp/ironcrypt:latest

Build the image locally:

docker build -t ironcrypt:latest .

Run the CLI inside the container:

docker run --rm ironcrypt:latest --help

Run the daemon (exposes port 3000, mounts host keys directory):

# Generate or place your keys in ./keys first
# Note: the daemon currently binds to 127.0.0.1 inside the container.
# It will be reachable from inside the container. To reach it from the host,
# bind the server to 0.0.0.0 in code or use an alternative networking setup.
docker run --rm -p 3000:3000 -v "$PWD/keys:/keys" ironcrypt:latest \
  ironcryptd -v v1 -d /keys -p 3000

6. Using the Makefile (Docker Compose)

Shortcuts for lab / prod stacks.

Prerequisites: Docker and Docker Compose v2 (docker compose).

make help
make bootstrap-lab   # copy *.example → local files (no overwrite)
make lab             # alias: make dev — lab stack (Vault -dev)
make prod            # prod stack (no Vault root token)
make stop
make logs
make test
make coverage

Notes:

make lab ENV_FILE=.env.local
make prod PROD_ENV_FILE=.env.prod

Default target is all -> lab.

Optimized Builds with Feature Flags

IronCrypt is library-first on crates.io: the default feature set is empty (crypto API only). Binaries and cloud backends are opt-in via features — this keeps consumer dependency trees lean.

Available Features:

  • (default): library only — password / stream / RSA-ECC crypto API.
  • cli: Builds the ironcrypt CLI.
  • daemon: Builds ironcryptd and enables the daemon CLI subcommand.
  • interactive: Progress indicators in the CLI (requires cli).
  • aws / azure / vault: secret backends (aws currently needs rustc ≥ 1.94.1).
  • gcp: Google Secret Manager (optional, pulls tonic — outside cloud / full).
  • hsm: PKCS#11 backend.
  • cloud: aws + azure + vault (no gcp).
  • full: cli + daemon + cloud + interactive (batteries-included meta feature).

As a library dependency:

# Lean (recommended for apps)
ironcrypt = "0.1"

# With optional backends
ironcrypt = { version = "0.1", features = ["vault"] }

Local Builds with cargo:

# Library only (same as crates.io default)
cargo build --release

# Minimal CLI binary
cargo build --release --features cli

# CLI with AWS support and interactive spinners
cargo build --release --features "cli,interactive,aws"

# Daemon with cloud providers
cargo build --release --features "daemon,cloud"

# Everything except gcp/hsm
cargo build --release --features full

Custom Docker Builds:

You can pass the features to the Docker build using the IRONCRYPT_FEATURES build argument.

# Build a minimal Docker image with only the CLI tool
docker build --build-arg IRONCRYPT_FEATURES="cli" -t ironcrypt:cli .

# Build a Docker image with the daemon and Azure support
docker build --build-arg IRONCRYPT_FEATURES="daemon,azure" -t ironcrypt:daemon-azure .

Usage

Command-Line Interface (CLI)

Here is a summary table of all available commands:

Command Alias Description Key Options
generate Generates a new RSA key pair. -v, --version <VERSION> -d, --directory <DIR> -s, --key-size <SIZE> [--passphrase <PASSPHRASE>]
encrypt Hashes and encrypts a password. -w, --password <PASSWORD> -d, --public-key-directory <DIR> -v, --key-version <VERSION>
decrypt Verifies an encrypted password. -w, --password <PASSWORD> -k, --private-key-directory <DIR> -f, --file <FILE> [--passphrase <PASSPHRASE>]
encrypt-file encfile, efile, ef Encrypts a binary file. -i, --input-file <INPUT> -o, --output-file <OUTPUT> -d, --public-key-directory <DIR> -v, --key-version <VERSION>... [-w, --password <PASSWORD>]
decrypt-file decfile, dfile, df Decrypts a binary file. -i, --input-file <INPUT> -o, --output-file <OUTPUT> -k, --private-key-directory <DIR> -v, --key-version <VERSION> [-w, --password <PASSWORD>] [--passphrase <PASSPHRASE>]
encrypt-dir encdir Encrypts an entire directory. -i, --input-dir <INPUT> -o, --output-file <OUTPUT> -d, --public-key-directory <DIR> -v, --key-version <VERSION>... [-w, --password <PASSWORD>]
decrypt-dir decdir Decrypts an entire directory. -i, --input-file <INPUT> -o, --output-dir <OUTPUT> -k, --private-key-directory <DIR> -v, --key-version <VERSION> [-w, --password <PASSWORD>] [--passphrase <PASSPHRASE>]
rotate-key rk Rotates encryption keys for encrypted data. --old-version <OLD_V> --new-version <NEW_V> -k, --key-directory <DIR> `[--file
sign Creates a detached signature for a file. -i, --input-file <INPUT> -o, --output-file <OUTPUT> -k, --key-directory <DIR> -v, --key-version <VERSION> [--passphrase <PASSPHRASE>]
verify Verifies a detached signature for a file. -i, --input-file <INPUT> -s, --signature-file <SIG> -d, --public-key-directory <DIR> -v, --key-version <VERSION>

A full list of commands and their arguments can be viewed by running ironcrypt --help. To get help for a specific command, run ironcrypt <command> --help.

generate

Generates a new RSA key pair (private and public).

Usage:

ironcrypt generate --version <VERSION> [--directory <DIR>] [--key-size <SIZE>] [--passphrase <PASSPHRASE>]

Example:

# Generate a new v2 key with a size of 4096 bits in the "my_keys" directory
ironcrypt generate -v v2 -d my_keys -s 4096

# Generate a new v3 key protected by a passphrase
ironcrypt generate -v v3 -d my_keys --passphrase "a-very-secret-phrase"

encrypt

Hashes and encrypts a password.

Usage:

ironcrypt encrypt --password <PASSWORD> --public-key-directory <DIR> --key-version <VERSION>

Example:

# Encrypt a password using the v1 public key
ironcrypt encrypt -w "My$trongP@ssw0rd" -d keys -v v1

decrypt

Decrypts and verifies a password.

Usage:

ironcrypt decrypt --password <PASSWORD> --private-key-directory <DIR> --file <FILE> [--passphrase <PASSPHRASE>]

Example:

# Verify a password using the v1 private key and the encrypted data from a file
ironcrypt decrypt -w "My$trongP@ssw0rd" -k keys -f encrypted_data.json

# Verify using a key protected by a passphrase
ironcrypt decrypt -w "My$trongP@ssw0rd" -k my_keys -f encrypted_data_v3.json --passphrase "a-very-secret-phrase"

encrypt-file

Encrypts a single file.

Usage:

ironcrypt encrypt-file -i <INPUT> -o <OUTPUT> -d <KEY_DIR> -v <VERSION>... [-w <PASSWORD>]

Example:

# Encrypt a file for a single user (v1)
ironcrypt encrypt-file -i my_document.pdf -o my_document.enc -d keys -v v1

# Encrypt a file for multiple users (v1 and v2)
ironcrypt encrypt-file -i my_document.pdf -o my_document.multirecipient.enc -d keys -v v1 -v v2

decrypt-file

Decrypts a single file.

Usage:

ironcrypt decrypt-file -i <INPUT> -o <OUTPUT> -k <KEY_DIR> -v <VERSION> [-w <PASSWORD>] [--passphrase <PASSPHRASE>]

Example:

# Decrypt a file with the v1 private key
ironcrypt decrypt-file -i my_document.enc -o my_document.pdf -k keys -v v1

# Decrypt a file using a key protected by a passphrase
ironcrypt decrypt-file -i my_secret.enc -o my_secret.zip -k my_keys -v v3 -w "ExtraL@yerOfS3curity" --passphrase "a-very-secret-phrase"

encrypt-dir

Encrypts an entire directory by first archiving it into a .tar.gz.

Usage:

ironcrypt encrypt-dir -i <INPUT_DIR> -o <OUTPUT_FILE> -d <KEY_DIR> -v <VERSION>... [-w <PASSWORD>]

Example:

# Encrypt the "my_project" directory for multiple users
ironcrypt encrypt-dir -i ./my_project -o my_project.enc -d keys -v v1 -v v2

decrypt-dir

Decrypts and extracts a directory.

Usage:

ironcrypt decrypt-dir -i <INPUT_FILE> -o <OUTPUT_DIR> -k <KEY_DIR> -v <VERSION> [-w <PASSWORD>] [--passphrase <PASSPHRASE>]

Example:

# Decrypt the "my_project.enc" file into the "decrypted_project" directory
ironcrypt decrypt-dir -i my_project.enc -o ./decrypted_project -k keys -v v1

rotate-key

Rotates encryption keys for a file or a directory of files.

Usage:

ironcrypt rotate-key --old-version <OLD_V> --new-version <NEW_V> --key-directory <DIR> [--file <FILE> | --directory <DIR>] [--passphrase <PASSPHRASE>]

Example:

# Rotate keys from v1 to v2 for a single file
ironcrypt rotate-key --old-version v1 --new-version v2 -k keys --file my_document.enc

sign

Creates a detached signature for a file. This can be used to prove the file's authenticity and integrity.

Usage:

ironcrypt sign --input-file <INPUT> --output-file <OUTPUT> --key-directory <DIR> --key-version <VERSION> [--passphrase <PASSPHRASE>]

Example:

# Sign a document with a v1 private key
ironcrypt sign -i my_document.pdf -o my_document.sig -k keys -v v1

# Sign a file with a passphrase-protected ECC key
ironcrypt sign -i archive.zip -o archive.sig -k ecc_keys -v v1_ecc --passphrase "my-secret-phrase"

verify

Verifies a detached signature against a file. This confirms that the file has not been tampered with since it was signed by the holder of the corresponding private key.

Usage:

ironcrypt verify --input-file <INPUT> --signature-file <SIGNATURE> --public-key-directory <DIR> --key-version <VERSION>

Example:

# Verify the signature for my_document.pdf using the v1 public key
ironcrypt verify -i my_document.pdf -s my_document.sig -d keys -v v1

As a Library (Crate)

You can also use ironcrypt as a library in your Rust projects. Add it to your Cargo.toml:

[dependencies]
ironcrypt = "0.1.2" # Replace with the desired version from crates.io

Runnable copies of the snippets below live in examples/ (cargo run --example password, cargo run --example stream_aes). They are also checked by cargo test --doc.

Encrypting and Verifying a Password

use ironcrypt::{IronCrypt, IronCryptConfig, DataType, config::KeyManagementConfig};
use std::collections::HashMap;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // 1. Use a temporary directory for keys to keep tests isolated.
    let temp_dir = tempfile::tempdir()?;
    let key_dir = temp_dir.path().to_str().unwrap();

    // 2. Configure IronCrypt to use the temporary directory.
    let mut config = IronCryptConfig::default();
    let mut data_type_config = HashMap::new();
    data_type_config.insert(
        DataType::Generic,
        KeyManagementConfig {
            key_directory: key_dir.to_string(),
            key_version: "v1".to_string(),
            passphrase: None,
        },
    );
    config.data_type_config = Some(data_type_config);

    // 3. Initialize IronCrypt.
    let crypt = IronCrypt::new(config, DataType::Generic).await?;

    // 4. Encrypt a password.
    let password = "MySecurePassword123!";
    let encrypted_json = crypt.encrypt_password(password)?;
    println!("Encrypted password: {}", encrypted_json);

    // 5. Verify the password.
    let is_valid = crypt.verify_password(&encrypted_json, password)?;
    assert!(is_valid);
    println!("Password verification successful!");

    Ok(())
}

Encrypting and Decrypting a File (Streaming)

use ironcrypt::{
    algorithms::SymmetricAlgorithm,
    decrypt_stream, encrypt_stream, generate_rsa_keys,
    keys::{PrivateKey, PublicKey},
    Argon2Config, PasswordCriteria,
};
use std::io::Cursor;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (sk, pk) = generate_rsa_keys(2048)?;
    let public_key = PublicKey::Rsa(pk);
    let private_key = PrivateKey::Rsa(sk);

    let original_data = "This is a secret message that will be streamed for encryption.";
    let mut source = Cursor::new(original_data.as_bytes());
    let mut encrypted_dest = Cursor::new(Vec::new());
    let mut password = String::new();

    encrypt_stream(
        &mut source,
        &mut encrypted_dest,
        &mut password,
        [(&public_key, "v1")],
        None, // no signature → real AES streaming
        &PasswordCriteria::default(),
        Argon2Config::default(),
        false,
        SymmetricAlgorithm::Aes256Gcm,
    )?;

    encrypted_dest.set_position(0);
    let mut decrypted_dest = Cursor::new(Vec::new());
    decrypt_stream(
        &mut encrypted_dest,
        &mut decrypted_dest,
        &private_key,
        "v1",
        "",
        None,
    )?;

    assert_eq!(original_data, String::from_utf8(decrypted_dest.into_inner())?);
    Ok(())
}

Transparent Encryption Daemon

For language-agnostic integration, ironcryptd exposes a streaming HTTP API.

Daemon Configuration

Config is a flat TOML matching IronCryptConfig (see ironcrypt.toml.example).

Minimal ironcrypt.toml:

standard = "Nist"
buffer_size = 8192
rsa_key_size = 2048
argon2_memory_cost = 65536
argon2_time_cost = 3
argon2_parallelism = 1

[password_criteria]
min_length = 12

Starting the Daemon

ironcryptd \
  --config ironcrypt.toml \
  --key-directory keys \
  --key-version v1 \
  --api-keys-file keys.json \
  --host 127.0.0.1 \
  --port 3000

Non-loopback HTTP requires TLS (--tls-cert / --tls-key) or --allow-insecure-http.

Daemon Authentication

1. Generate an API key

ironcrypt generate-api-key

You get:

  • Secret API key (base64) — send as Authorization: Bearer …
  • Hash (SHA-512 hex) — store in keys.json as keyHash

2. keys.json (camelCase)

[
  {
    "description": "Backup service (write-only)",
    "keyHash": "HASH_HEX_FROM_GENERATE_API_KEY",
    "permissions": ["write"]
  },
  {
    "description": "Read/write service",
    "keyHash": "ANOTHER_HASH_HEX",
    "permissions": ["write", "read"]
  },
  {
    "description": "AWS secrets only",
    "keyHash": "YET_ANOTHER_HASH",
    "permissions": ["read", "write"],
    "allowedServices": ["aws"]
  }
]

Valid permissions: write, read, delete, update, full.
Fixtures: keys.json.example, private_key_v1.pem.example / public_key_v1.pem.example (make bootstrap-lab).

3. Authenticated requests

export API_KEY='SECRET_API_KEY_BASE64'

echo "my secret data" | curl -sS --request POST \
  --header "Authorization: Bearer ${API_KEY}" \
  --data-binary @- \
  http://127.0.0.1:3000/write > encrypted.bin

curl -sS --request POST \
  --header "Authorization: Bearer ${API_KEY}" \
  --data-binary @encrypted.bin \
  http://127.0.0.1:3000/read

echo "secret" | curl -sS --request POST \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "X-Password: Str0ngP@ssw0rd42!" \
  --data-binary @- \
  http://127.0.0.1:3000/write > encrypted_with_pass.bin

Typical errors: 401 (missing/invalid key), 403 (permission), 429 (rate limit), 400 (crypto / bad password).

API Endpoints

Method Path Permission Role
POST /write write Encrypt request body
POST /read read Decrypt request body
GET /service/:name/secret/:key read Read cloud secret
POST /service/:name/secret/:key write Write cloud secret

CORS is off by default; whitelist with --cors-origins https://app.example.com.

High Availability

The ironcryptd daemon is designed to be stateless, meaning it does not store any session or request-specific data between requests. This architecture makes it horizontally scalable and highly available. You can run multiple instances of the daemon behind a load balancer to distribute traffic and ensure service continuity even if one of the instances fails.

Key Requirements for a High-Availability Setup:

  1. Shared Configuration: All ironcryptd instances must be started with the same configuration. This is best achieved by using a centralized ironcrypt.toml configuration file for all instances.
  2. Shared Key Storage: All instances must have access to the same set of encryption keys. This can be achieved by:
    • Placing the key directory on a shared network file system (e.g., NFS, GlusterFS).
    • Using a configuration management tool (e.g., Ansible, Puppet) to deploy the same key files to each node.
  3. Centralized Logging: To monitor and audit the cluster, the logs from all instances (both standard and audit logs) should be forwarded to a centralized logging system (e.g., ELK Stack, Splunk, Graylog).

Example: Load Balancing with Nginx

Here is a sample Nginx configuration that demonstrates how to load balance traffic between two ironcryptd instances running on localhost at ports 3000 and 3001.

# /etc/nginx/nginx.conf

http {
    # Define a group of upstream servers
    upstream ironcryptd_cluster {
        # Use a load balancing algorithm, e.g., round-robin (default) or least_conn
        # least_conn;

        server 127.0.0.1:3000;
        server 127.0.0.1:3001;
    }

    server {
        listen 80;

        location / {
            # Forward requests to the upstream cluster
            proxy_pass http://ironcryptd_cluster;

            # Set headers to pass client information to the daemon
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

With this configuration, Nginx will listen on port 80 and distribute incoming requests (/write, /read, …) between the two daemon instances, providing both load balancing and redundancy.

Database Integration Examples

Here are some examples of how to use ironcrypt with popular web frameworks and a PostgreSQL database. These examples use the sqlx crate for database interaction.

Actix-web Example

This example shows how to create a simple web service with actix-web that can register and log in users.

Dependencies:

[dependencies]
ironcrypt = "0.1.2"
actix-web = "4"
sqlx = { version = "0.7", features = ["runtime-async-std-native-tls", "postgres"] }
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

Code:

use actix_web::{web, App, HttpServer, Responder, HttpResponse};
use sqlx::postgres::PgPoolOptions;
use sqlx::PgPool;
use ironcrypt::{IronCrypt, IronCryptConfig, DataType};
use serde::Deserialize;

#[derive(Deserialize)]
struct User {
    username: String,
    password: String,
}

async fn register(user: web::Json<User>, pool: web::Data<PgPool>, crypt: web::Data<IronCrypt>) -> impl Responder {
    let encrypted_password = match crypt.encrypt_password(&user.password) {
        Ok(p) => p,
        Err(_) => return HttpResponse::InternalServerError().finish(),
    };

    let result = sqlx::query("INSERT INTO users (username, password) VALUES ($1, $2)")
        .bind(&user.username)
        .bind(&encrypted_password)
        .execute(pool.get_ref())
        .await;

    match result {
        Ok(_) => HttpResponse::Ok().body("User created"),
        Err(_) => HttpResponse::InternalServerError().finish(),
    }
}

async fn login(user: web::Json<User>, pool: web::Data<PgPool>, crypt: web::Data<IronCrypt>) -> impl Responder {
    let result: Result<(String,), sqlx::Error> = sqlx::query_as("SELECT password FROM users WHERE username = $1")
        .bind(&user.username)
        .fetch_one(pool.get_ref())
        .await;

    let stored_password = match result {
        Ok((p,)) => p,
        Err(_) => return HttpResponse::Unauthorized().finish(),
    };

    match crypt.verify_password(&stored_password, &user.password) {
        Ok(true) => HttpResponse::Ok().body("Login successful"),
        Ok(false) => HttpResponse::Unauthorized().finish(),
        Err(_) => HttpResponse::InternalServerError().finish(),
    }
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let database_url = "postgres://user:password@localhost/database";
    let pool = PgPoolOptions::new()
        .max_connections(5)
        .connect(&database_url)
        .await
        .expect("Failed to create pool.");

    let config = IronCryptConfig::default();
    let crypt = IronCrypt::new(config, DataType::Generic).await.expect("Failed to initialize IronCrypt");

    sqlx::query(
        "CREATE TABLE IF NOT EXISTS users (
            id SERIAL PRIMARY KEY,
            username TEXT NOT NULL UNIQUE,
            password TEXT NOT NULL
        )"
    )
    .execute(&pool)
    .await
    .expect("Failed to create table.");

    HttpServer::new(move || {
        App::new()
            .app_data(web::Data::new(pool.clone()))
            .app_data(web::Data::new(crypt.clone()))
            .route("/register", web::post().to(register))
            .route("/login", web::post().to(login))
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

Rocket Example

This example shows how to achieve the same functionality using the rocket framework.

Dependencies:

[dependencies]
ironcrypt = "0.1.2"
rocket = { version = "0.5.0", features = ["json"] }
sqlx = { version = "0.7", features = ["runtime-tokio-native-tls", "postgres"] }
serde = { version = "1.0", features = ["derive"] }

Code:

#[macro_use] extern crate rocket;

use rocket::serde::json::Json;
use rocket::State;
use sqlx::postgres::PgPoolOptions;
use sqlx::PgPool;
use ironcrypt::{IronCrypt, IronCryptConfig, DataType};
use serde::Deserialize;

#[derive(Deserialize)]
struct User {
    username: String,
    password: String,
}

#[post("/register", data = "<user>")]
async fn register(user: Json<User>, pool: &State<PgPool>, crypt: &State<IronCrypt>) -> Result<String, rocket::response::status::Custom<String>> {
    let encrypted_password = crypt.encrypt_password(&user.password).map_err(|e| rocket::response::status::Custom(rocket::http::Status::InternalServerError, e.to_string()))?;

    sqlx::query("INSERT INTO users (username, password) VALUES ($1, $2)")
        .bind(&user.username)
        .bind(&encrypted_password)
        .execute(&**pool)
        .await
        .map_err(|e| rocket::response::status::Custom(rocket::http::Status::InternalServerError, e.to_string()))?;

    Ok("User created".to_string())
}

#[post("/login", data = "<user>")]
async fn login(user: Json<User>, pool: &State<PgPool>, crypt: &State<IronCrypt>) -> Result<String, rocket::response::status::Custom<String>> {
    let result: (String,) = sqlx::query_as("SELECT password FROM users WHERE username = $1")
        .bind(&user.username)
        .fetch_one(&**pool)
        .await
        .map_err(|_| rocket::response::status::Custom(rocket::http::Status::Unauthorized, "User not found".to_string()))?;

    let stored_password = result.0;

    if crypt.verify_password(&stored_password, &user.password).unwrap_or(false) {
        Ok("Login successful".to_string())
    } else {
        Err(rocket::response::status::Custom(rocket::http::Status::Unauthorized, "Invalid credentials".to_string()))
    }
}

#[launch]
async fn rocket() -> _ {
    let database_url = "postgres://user:password@localhost/database";
    let pool = PgPoolOptions::new()
        .max_connections(5)
        .connect(&database_url)
        .await
        .expect("Failed to create pool.");

    let config = IronCryptConfig::default();
    let crypt = IronCrypt::new(config, DataType::Generic).await.expect("Failed to initialize IronCrypt");

    sqlx::query(
        "CREATE TABLE IF NOT EXISTS users (
            id SERIAL PRIMARY KEY,
            username TEXT NOT NULL UNIQUE,
            password TEXT NOT NULL
        )"
    )
    .execute(&pool)
    .await
    .expect("Failed to create table.");

    rocket::build()
        .manage(pool)
        .manage(crypt)
        .mount("/", routes![register, login])
}

Configuration

IronCrypt can be configured in three ways, in order of precedence:

  1. ironcrypt.toml file: Point the CLI (ironcrypt) or the daemon (ironcryptd) at it with --config ironcrypt.toml, or set IRONCRYPT_CONFIG_FILE. --config is a global flag, so it works before or after the subcommand (e.g. ironcrypt --config ironcrypt.toml encrypt-file ... or ironcrypt encrypt-file --config ironcrypt.toml ...). Without it, secure defaults are used — the file is never auto-discovered from the current directory.
  2. Environment Variables: Set variables like IRONCRYPT_KEY_DIRECTORY.
  3. Command-Line Arguments: Flags like --key-directory override all other methods.

For library usage, you can construct an IronCryptConfig struct and pass it to IronCrypt::new.

Cryptographic Algorithm Configuration

Tune algorithms via flat ironcrypt.toml fields (see ironcrypt.toml.example).

# Standards: "Nist" | "Fips140_2" | "Anssi" | "Custom"
standard = "Nist"
rsa_key_size = 2048
buffer_size = 8192
argon2_memory_cost = 65536
argon2_time_cost = 3
argon2_parallelism = 1

[password_criteria]
min_length = 12

Custom mode:

standard = "Custom"
symmetric_algorithm = "ChaCha20Poly1305"  # or "Aes256Gcm"
asymmetric_algorithm = "Ecc"              # or "Rsa"
rsa_key_size = 4096                       # ignored when Ecc

Anssi forces AES-256-GCM + RSA 3072. For ECC, use standard = "Custom" with asymmetric_algorithm = "Ecc".

Secret Management Configuration

To use IronCrypt with a secret management system like HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault, you need to enable the corresponding feature flag during compilation and configure it in your ironcrypt.toml file.

First, specify the provider you want to use:

[secrets]
provider = "vault" # or "aws", "azure"

Then, provide the specific configuration for your chosen provider.

HashiCorp Vault (vault feature)

[secrets.vault]
address = "http://127.0.0.1:8200" # Address of your Vault server
token = "YOUR_VAULT_TOKEN"        # Vault token with access to the secret engine
mount = "secret"                  # Mount path of the KVv2 secrets engine (optional, defaults to "secret")

Security and Best Practices

  • Protect Your Private Keys: Never expose your private keys. Store them in a secure, non-public location. If possible, encrypt them with a strong, unique passphrase using the --passphrase option during generation.
  • Use Strong Passwords: When using the password feature for file/directory encryption, ensure the password is strong.
  • Rotate Keys Regularly: Use the rotate-key command to update your encryption keys periodically.
  • Backup Your Keys: Keep secure backups of your keys. If you lose a private key, you will not be able to decrypt your data.

Contribution

Contributions are welcome! If you'd like to contribute, please follow these steps:

  1. Fork the repository on GitHub.
  2. Create a new branch for your feature or bug fix.
  3. Commit your changes and push them to your fork.
  4. Submit a pull request with a clear description of your changes.

License

IronCrypt is licensed under the MIT License. See the LICENSE file for details.