Crate ferrocrypt

Crate ferrocrypt 

Source
Expand description

§ferrocrypt

High-level helpers for encrypting and decrypting files or directories using password-based symmetric encryption or hybrid (asymmetric + symmetric) encryption. Designed for straightforward, scriptable workflows rather than low-level cryptographic building blocks.

§Design goals

  • Confidentiality + integrity for small-to-medium file trees.
  • Simple ergonomics: pick symmetric (password) or hybrid (public/private key + optional passphrase) based on your distribution needs.
  • Batteries included: temporary workspace management, path normalization, and output file naming are handled for you.

§Quick start (symmetric path, mirrors ferrocrypt symmetric CLI)

use ferrocrypt::{symmetric_encryption, CryptoError, secrecy::SecretString};

// Encrypt a folder to out/secrets.fcs
let passphrase = SecretString::from("correct horse battery staple".to_string());
let produced = symmetric_encryption("./secrets", "./out", &passphrase, false)?;
println!("wrote {produced}");

// Decrypt the archive back
let recovered = symmetric_encryption("./out/secrets.fcs", "./restored", &passphrase, false)?;
println!("restored to {recovered}");

§Quick start (hybrid path, mirrors ferrocrypt hybrid CLI)

use ferrocrypt::{generate_asymmetric_key_pair, hybrid_encryption, CryptoError, secrecy::SecretString};

// 1) Generate RSA keypair files under ./keys
//    The passphrase encrypts the private key file itself
let passphrase = SecretString::from("my-key-pass".to_string());
let _msg = generate_asymmetric_key_pair(4096, &passphrase, "./keys")?;

// 2) Encrypt to out/payload.fch using the public key (no passphrase needed)
let mut pub_key_path = "./keys/rsa-4096-pub-key.pem".to_string();
let empty_passphrase = SecretString::from("".to_string());
let produced = hybrid_encryption("./payload", "./out", &mut pub_key_path, &empty_passphrase)?;
println!("wrote {produced}");

// 3) Decrypt out/payload.fch using the private key + passphrase to unlock it
let mut priv_key_path = "./keys/rsa-4096-priv-key.pem".to_string();
let restored = hybrid_encryption("./out/payload.fch", "./restored", &mut priv_key_path, &passphrase)?;
println!("restored to {restored}");

§When to choose which mode

  • Symmetric: Fastest; same password encrypts and decrypts. Great for personal backups or team secrets when you can share the password securely. Produces .fcs files.
  • Hybrid: Safer for distribution—encrypt with a recipient’s public key (no password needed for encryption); only their passphrase-protected private key can decrypt. Each file gets a unique random key. Produces .fch files.

§Security notes

  • All cryptographic operations depend on a secure OS RNG; ensure the target platform provides one.
  • Ciphertext integrity is enforced; modification or wrong keys will yield CryptoError results rather than corrupted plaintext.
  • This crate is not third-party audited and is not advertised as compliance-certified.

§Error handling

Every fallible operation returns Result<T, CryptoError>. See CryptoError for variant meanings and remediation hints.

§License

Licensed under GPL-3.0-only. See the LICENSE file in the repository.

Re-exports§

pub use secrecy;

Enums§

CryptoError
Errors that can occur during key generation, encryption, or decryption.

Functions§

generate_asymmetric_key_pair
Generate and store an RSA key pair for hybrid encryption (default: RSA-4096).
hybrid_encryption
Encrypt or decrypt using hybrid (RSA + XChaCha20-Poly1305) envelope encryption.
symmetric_encryption
Encrypt or decrypt files/directories using password-based symmetric crypto.