aescrypt-rs

Fast, safe, streaming Rust implementation of the AES Crypt file format

• Read: Full compatibility with all versions — v0, v1, v2, and v3
• Write: Modern v3 only (PBKDF2-HMAC-SHA512, PKCS#7 padding, proper session-key encryption)
• Detect: read_version() — header-only version check in <1 μs (ideal for batch tools)
• AES-256-CBC with HMAC-SHA256 (payload) + HMAC-SHA512 (session) authentication
• Constant-memory streaming (64-byte ring buffer)
• Zero-cost secure memory & cryptographically secure RNG via secure-gate v0.7.0-rc.1 (enabled by default)
• Constant-time security: All HMAC comparisons and padding validation use constant-time operations
• No unsafe in the core decryption path when zeroize is enabled
• Pure Rust, #![no_std]-compatible core
• 100% bit-perfect round-trip verified against all 63 official v0–v3 test vectors

Support the Original Author

AES Crypt was created and maintained for over two decades by Paul E. Jones. If you find AES Crypt (or this Rust port) useful, please consider supporting Paul directly:

• Official apps & licenses: https://www.aescrypt.com/download/
• Business/enterprise licensing: https://www.aescrypt.com/license.html

Version Support Summary

Why v3-only on write? Version 3 is the only secure, future-proof variant. Producing legacy formats today would be a security downgrade.

Cryptographic Primitives (v3)

Security Features

• Constant-time operations: All HMAC verifications and PKCS#7 padding validation use constant-time comparisons to prevent timing attacks
• Secure memory management: All sensitive data (keys, passwords, IVs) wrapped in secure-gate types with automatic zeroization
• Streaming architecture: Constant-memory decryption using 64-byte ring buffer (no full-file buffering)

Thread Safety

All public functions are thread-safe (Send + Sync). The library has no shared mutable state, making all operations safe for:

• Concurrent execution: Call functions from multiple threads simultaneously
• Async runtimes: Use with tokio::task::spawn_blocking or similar
• Custom cancellation: Spawn operations in threads and implement your own cancellation via channels or thread handles

Example: Threaded Usage

use aescrypt_rs::{encrypt, PasswordString, constants::DEFAULT_PBKDF2_ITERATIONS};
use std::io::Cursor;
use std::thread;

let password = PasswordString::new("secret".to_string());
let data = b"large file data...";

// Spawn encryption in a thread
let handle = thread::spawn(move || {
    let mut encrypted = Vec::new();
    encrypt(
        Cursor::new(data),
        &mut encrypted,
        &password,
        DEFAULT_PBKDF2_ITERATIONS,
    )
});

// Wait for completion or implement cancellation
let result = handle.join().unwrap()?;
# Ok::<(), aescrypt_rs::AescryptError>(())

For large files, operations may take significant time. Users requiring cancellation should spawn functions in threads and implement their own cancellation mechanism.

Core API

The library provides a minimal, focused API at the root level: High-level functions (99% of use cases):

• encrypt() - Encrypt data to AES Crypt v3 format
• decrypt() - Decrypt AES Crypt files (v0-v3)
• read_version() - Quick version detection without full decryption Key derivation:
• Pbkdf2Builder - Fluent builder for PBKDF2 key derivation
• derive_ackdf_key() - Low-level ACKDF for v0-v2 files
• derive_pbkdf2_key() - Low-level PBKDF2 for v3 files Types and constants:
• AescryptError - Comprehensive error type
• PasswordString and other secure types via aliases::*
• Configuration constants via constants::* Advanced access: Lower-level functions available via decryption::* and encryption::* module paths for custom flows.

API Examples

Detect file version (header only)

use aescrypt_rs::read_version;
use std::io::Cursor;

// v3 file header
let header = b"AES\x03\x00";
let version = read_version(Cursor::new(header))?;
assert_eq!(version, 3);

// v0 file header (3-byte)
let header = b"AES";
let version = read_version(Cursor::new(header))?;
assert_eq!(version, 0);
# Ok::<(), aescrypt_rs::AescryptError>(())

Standard encrypt / decrypt

use aescrypt_rs::{encrypt, decrypt, PasswordString, constants::DEFAULT_PBKDF2_ITERATIONS};
use std::io::Cursor;

let pw = PasswordString::new("correct horse battery staple".to_string());
let data = b"top secret";
let mut ciphertext = Vec::new();
encrypt(Cursor::new(data), &mut ciphertext, &pw, DEFAULT_PBKDF2_ITERATIONS)?;
let mut plaintext = Vec::new();
decrypt(Cursor::new(&ciphertext), &mut plaintext, &pw)?;
assert_eq!(data, &plaintext[..]);
# Ok::<(), aescrypt_rs::AescryptError>(())

PBKDF2 Key Derivation Builder

For custom key derivation with a fluent API:

use aescrypt_rs::{Pbkdf2Builder, PasswordString, aliases::Aes256Key32};

let password = PasswordString::new("my-secret-password".to_string());

// Use defaults (300k iterations, random salt)
let mut key = Aes256Key32::new([0u8; 32]);
Pbkdf2Builder::new()
    .derive_secure(&password, &mut key)?;

// Or customize
let mut custom_key = Aes256Key32::new([0u8; 32]);
Pbkdf2Builder::new()
    .with_iterations(500_000)
    .with_salt([0x42; 16])
    .derive_secure(&password, &mut custom_key)?;

// Or get a new key directly
let derived_key = Pbkdf2Builder::new()
    .derive_secure_new(&password)?;
# Ok::<(), aescrypt_rs::AescryptError>(())

Advanced API Access

For custom decryption/encryption flows, access lower-level functions via module paths:

use aescrypt_rs::{
    decryption::{extract_session_data, StreamConfig, read_file_version},
    encryption::{derive_setup_key, encrypt_session_block},
    aliases::{Aes256Key32, Iv16, PasswordString},
    constants::DEFAULT_PBKDF2_ITERATIONS,
};
use std::io::Cursor;

let mut reader = Cursor::new(b"encrypted data...");
let version = read_file_version(&mut reader)?;
let password = PasswordString::new("password".to_string());

// Read public IV from file header (example placeholder)
let public_iv = Iv16::new([0u8; 16]);
let mut setup_key = Aes256Key32::new([0u8; 32]);
// derive_setup_key(&password, &public_iv, version, &mut setup_key)?;
let mut session_iv = Iv16::new([0u8; 16]);
let mut session_key = Aes256Key32::new([0u8; 32]);
extract_session_data(&mut reader, version, &public_iv, &setup_key, &mut session_iv, &mut session_key)?;

// Continue custom decryption with StreamConfig::V3, etc.
# Ok::<(), aescrypt_rs::AescryptError>(())

Constants

Configuration constants are available via the constants module:

use aescrypt_rs::constants::{
    DEFAULT_PBKDF2_ITERATIONS, // 300,000 (recommended default)
    PBKDF2_MIN_ITER,           // 1
    PBKDF2_MAX_ITER,           // 5,000,000
    AESCRYPT_LATEST_VERSION,   // 3
};

Performance (release mode, modern laptop)

Note: For very large files (GB+), operations may take minutes. All functions are thread-safe and can be spawned in threads for parallel processing or custom cancellation implementations.

Features

Feature Details:

• When zeroize is disabled, regular equality comparisons (==) are used (not constant-time, vulnerable to timing attacks).
• When rand is disabled, encryption convenience methods are unavailable (decryption still works; encryption possible with custom RNG).
• All features are optional — library can run with --no-default-features.

Installation

[dependencies]
aescrypt-rs = "0.2.0-rc.1"

Changelog

See CHANGELOG.md for a list of changes.

License

Licensed under MIT or Apache-2.0 at your option.

aescrypt-rs — the modern, safe, and future-proof way to handle AES Crypt files in Rust.