Crate ferrocrypt

Expand description

§ferrocrypt

Authenticated encryption of files and directories.

FerroCrypt writes .fcr files using one recipient-oriented container: one random per-file key, one streamed authenticated payload, and one or more typed recipient entries that independently wrap the same file key. The public API exposes this through Encryptor and Decryptor rather than through low-level cryptographic building blocks.

§Design goals

Recipient-oriented encryption: passphrases and public keys are native recipient schemes over the same .fcr container.
Path-based file workflows: archiving, streaming encryption, staging, and output naming are handled by the library.
Typed routing: Decryptor::open inspects the recipient list and returns a passphrase or private-key decryptor variant.
Typed diagnostics: operations return CryptoError values with structured format, KDF, recipient, authentication, and I/O failures.

§Quick start (passphrase recipient)

These examples assume the input paths exist and the output names are unused.

use ferrocrypt::{Decryptor, Encryptor, CryptoError, Passphrase};

std::fs::create_dir_all("./out")?;
std::fs::create_dir_all("./restored")?;
// Encrypt
let encrypted = Encryptor::with_passphrase(Passphrase::new("correct horse battery staple"))
    .write("./secrets", "./out", |ev| eprintln!("{ev}"))?;
println!("Encrypted to {}", encrypted.output_path.display());

// Decrypt — each operation consumes its own `Passphrase` value
let restored = match Decryptor::open(&encrypted.output_path)? {
    Decryptor::Passphrase(d) => d.decrypt(
        Passphrase::new("correct horse battery staple"),
        "./restored",
        |ev| eprintln!("{ev}"),
    )?,
    Decryptor::PrivateKey(_) => unreachable!("we just encrypted with a passphrase"),
    _ => unreachable!("Decryptor is non_exhaustive; only Passphrase and PrivateKey exist today"),
};
println!("Decrypted to {}", restored.output_path.display());

§Quick start (public-key recipients)

use ferrocrypt::{
    Decryptor, Encryptor, generate_key_pair, PublicKey, PrivateKey,
    CryptoError, Passphrase,
};

std::fs::create_dir_all("./out")?;
std::fs::create_dir_all("./restored")?;
// 1) Generate X25519 keypair
let keys = generate_key_pair("./keys", Passphrase::new("my-key-pass"), |ev| eprintln!("{ev}"))?;
println!("Fingerprint: {}", keys.fingerprint);

// 2) Encrypt with the recipient's public key (no passphrase required)
let encrypted = Encryptor::with_public_key(PublicKey::from_key_file(&keys.public_key_path)?)
    .write("./payload", "./out", |ev| eprintln!("{ev}"))?;

// 3) Decrypt with the recipient's private key + its passphrase
let restored = match Decryptor::open(&encrypted.output_path)? {
    Decryptor::PrivateKey(d) => d.decrypt(
        PrivateKey::from_key_file(&keys.private_key_path, Passphrase::new("my-key-pass")),
        "./restored",
        |ev| eprintln!("{ev}"),
    )?,
    Decryptor::Passphrase(_) => unreachable!("we just encrypted to a public key"),
    _ => unreachable!("Decryptor is non_exhaustive; only Passphrase and PrivateKey exist today"),
};
println!("Decrypted to {}", restored.output_path.display());

§Choosing a recipient path

Passphrase recipient: use Encryptor::with_passphrase when the same passphrase should encrypt and decrypt the file. The resulting .fcr contains exactly one native argon2id recipient.
Public-key recipient: use Encryptor::with_public_key or Encryptor::with_public_keys when the sender should encrypt to one or more public recipient keys. Decryption requires a matching PrivateKey file and that key file’s passphrase. This does not authenticate the sender.

§Format compatibility

FerroCrypt stores four independent version bytes: .fcr outer-container version 0x01, FCA archive version 0x01, public-key encoding version 0x01, and private-key encoding version 0x01. The compatibility guarantee starts with the first stable 0.3.0 release. The 0.3.0 pre-release series (-alpha.N, -beta.N, -rc.N) is outside it: files written by a pre-release or by an untagged build of main carry no cross-version guarantee and may fail to decrypt under a later release.

Stable 0.3.0 establishes the 0.3.0 compatibility baseline (FORMAT.md §11.4): artifacts that use only the four stored versions above stay readable under every later release. A future release may introduce a new version in any one domain; that adds support without removing baseline read support.

Older pre-0.3.0 files and key pairs use a different format family and, for historical hybrid encryption, a different key-agreement stack. To migrate older data, decrypt it with the release that created it, then re-encrypt it with the current release.

§API stability

The on-disk format is versioned independently from the crate; see Format compatibility above for its stability guarantee. The public Rust API (Encryptor, Decryptor, PublicKey, PrivateKey, the error types) is pre-1.0; it may change in minor releases (0.x → 0.y), while patch releases (0.x.y → 0.x.z) preserve it. See the repository CHANGELOG.md for release notes.

§Security notes

Encryption and key generation require a secure OS random-number source.
Sender authentication is out of scope; public-key encryption identifies who can decrypt, not who encrypted.
A successful decrypt requires header and payload authentication. Wrong credentials or corrupted ciphertext return CryptoError; authenticated partial plaintext may already have been staged when a later check fails.
Passphrase and key-pair writing reject Argon2id memory below a fixed 19 MiB floor with CryptoError::KdfBelowWriteFloor. This prevents accidentally choosing a lower memory cost; it does not make a weak passphrase strong. The floor applies only when writing; readers accept lower memory costs subject to structural validation and their KdfLimit.
FerroCrypt authenticates each file as written, but it does not detect replay or rollback to an older valid .fcr; use external versioning or a freshness check if that matters.
FerroCrypt encrypts file contents and, for directory inputs, internal names, tree structure, and per-file sizes. It does not hide the total ciphertext length (an approximate plaintext-size signal), recipient count, or that the file is a FerroCrypt .fcr container.
Choose output directories and path ancestors that untrusted processes cannot modify during an operation. Existing output entries are refused; an error after commit can still leave complete output on disk.
Decryption stages authenticated plaintext under an .incomplete name. See IncompleteOutputPolicy for cleanup, retention, and interruption behavior. Do not consume staged output as a successfully decrypted file.
Encryption is not a filesystem snapshot. Prevent concurrent source changes or use a snapshot when a point-in-time copy is required.
Unattended services must configure resource limits and bound concurrent operations. The default Argon2id memory budget is 1 GiB per derivation; see KdfLimit. These APIs perform blocking filesystem and cryptographic work; asynchronous applications should run them on a blocking worker.
Public-key checksums do not establish ownership. Verify the recipient’s fingerprint through a trusted channel before encrypting.
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.

Structs§

ArchiveLimits: Resource caps for FCA archive encoding and extraction.
AuthenticatedRecipientMode: Recipient mode returned after successful authenticated decryption.
DecryptOutcome: Successful outcome of PassphraseDecryptor::decrypt or PrivateKeyDecryptor::decrypt.
EncryptOutcome: Successful outcome of an Encryptor::write call.
Encryptor: Builder-style entry point for encryption.
HeaderReadLimits: Resource caps for encrypted-file headers.
KdfLimit: Resource policy for Argon2id derivation during reading and writing.
KdfParams: KDF parameters stored in file headers and key files.
KeyGenOutcome: Successful outcome of generate_key_pair or KeyPairGenerator::write.
KeyPairGenerator: Builder for X25519 key-pair generation.
KeyReadLimits: Local resource caps applied while reading key material: the recipient-string cap to a public.key or a fcr1… recipient string, and the wrapped-secret cap to a private.key.
Passphrase: A passphrase held in a buffer that is wiped when the value drops.
PassphraseDecryptor: Decryptor for passphrase-sealed .fcr files. Returned from Decryptor::open when the file’s recipient list classifies as UnauthenticatedRecipientMode::Passphrase.
PrivateKey: Private key for public-key-recipient decryption.
PrivateKeyDecryptor: Decryptor for public-key-sealed .fcr files. Returned from Decryptor::open when the file’s recipient list classifies as UnauthenticatedRecipientMode::PublicKey.
PublicKey: Public recipient key for FerroCrypt public-key encryption.

Enums§

AuthenticatedRecipientModeKind: Recipient kind exposed by AuthenticatedRecipientMode::kind.
CryptoError: Errors from key generation, encryption, decryption, and validation.
Decryptor: Type-safe entry point for decryption.
FormatDefect: Structural defects detected while parsing a FerroCrypt encrypted file or key file. Carried inside CryptoError::InvalidFormat so format failures can be pattern-matched without substring comparisons and without parsing display text.
IncompleteOutputPolicy: Cleanup policy for staged plaintext after a returned decryption error.
InvalidKdfParams: KDF parameter that violates a format structural bound.
MixingPolicy: Public diagnostic category for a recipient mixing rule, surfaced through CryptoError::IncompatibleRecipients.
ProgressEvent: Progress notification for encryption, decryption, or key generation.
UnauthenticatedRecipientMode: Result of a cheap structural probe of an .fcr file’s recipient list.
UnsupportedVersion: File-format or key-file version rejection. Carries the raw version byte so callers can inspect it without parsing a formatted string.

Constants§

ARGON2_SALT_SIZE: Argon2id salt size in bytes. Stored alongside KdfParams in any header that consumes a passphrase (argon2id recipient body, private.key cleartext header); the crate’s internal Argon2id derivation takes its salt at exactly this width.
ENCRYPTED_EXTENSION: Default extension for encrypted FerroCrypt files, without the leading dot.
FCR_FILE_V1_VERSION: .fcr outer-container version byte (0x01) for the first container revision (FORMAT.md §3.1). Stays pinned when a future revision advances FCR_FILE_VERSION, mirroring crate::key::private::PRIVATE_KEY_V1_VERSION and crate::key::public::PUBLIC_KEY_V1_VERSION.
FCR_FILE_VERSION: .fcr outer-container version byte the current writer emits (FORMAT.md §3.1). Equals FCR_FILE_V1_VERSION today; a future container revision advances this constant while first-revision files stay readable (FORMAT.md §11.4), so compare against the pinned constant — not this one — to identify a first-revision file.
KDF_PARAMS_SIZE: Serialized size of KdfParams in bytes (3 × u32 big-endian).
MAGIC: Four-byte magic identifying binary .fcr and private.key files. Text public.key files use the fcr1 prefix instead.
PRIVATE_KEY_FILENAME: Default filename for the private key file (binary, wrapped).
PRIVATE_KEY_V1_VERSION: Private-key encoding version byte (0x01) for key-pair suite KPS-1. Pinned to KPS-1 even when the current writer moves to another suite.
PRIVATE_KEY_VERSION: Wire-version byte the current writer emits in private.key headers. Derived from WRITER_KEYPAIR_SUITE (crate-internal); not an independent support list.
PUBLIC_KEY_FILENAME: Default filename for the public key file (text form).
PUBLIC_KEY_V1_VERSION: Public-key encoding version byte (0x01) for key-pair suite KPS-1. Pinned to KPS-1 even when the current writer moves to another suite.
PUBLIC_KEY_VERSION: Wire-version byte the current writer emits at offset 0 of every public.key recipient payload. Derived from WRITER_KEYPAIR_SUITE (crate-internal); mirrors crate::key::private::PRIVATE_KEY_VERSION so a future suite bump flows through both writers in lockstep.
VERSION: The crate version from Cargo.toml, captured at compile time.

Functions§

decode_x25519_recipient_string: Decodes a Bech32 recipient string (fcr1…) into raw X25519 public-key material.
default_encrypted_filename: Returns the default encrypted filename for a given input path.
generate_key_pair: Generates and stores an X25519 key pair for public-key (recipient) encryption.
probe_recipient_mode: Cheap structural probe of an .fcr file’s recipient list. Not a security claim.
probe_recipient_mode_with_limits: Same as probe_recipient_mode but uses the supplied HeaderReadLimits for the structural header read instead of the conservative defaults.
validate_private_key_file: Checks the cleartext structure of a FerroCrypt private.key file.
validate_public_key_file: Validates that a file is a well-formed FerroCrypt public.key text file.