Crate age

Library for encrypting and decryping age files

This crate implements file encryption according to the age-encryption.org/v1 specification. It generates and consumes encrypted files that are compatible with the rage CLI tool, as well as the reference Golang implementation.

The encryption and decryption APIs are provided by Encryptor and Decryptor. There are several ways to use these:

• For most cases (including programmatic usage), use Encryptor::with_recipients with x25519::Recipient, and Decryptor with x25519::Identity.
• APIs are available for passphrase-based encryption and decryption. These should only be used with passphrases that were provided by (or generated for) a human.
• For compatibility with existing SSH keys, enable the ssh feature flag, and use [ssh::Recipient] and [ssh::Identity].

Age-encrypted files are binary and non-malleable. To encode them as text, use the wrapping readers and writers in the [armor] module, behind the armor feature flag.

Caution: all crate versions prior to 1.0 are beta releases for testing purposes only.

Examples

Recipient-based encryption

use std::io::{Read, Write};
use std::iter;

let key = age::x25519::Identity::generate();
let pubkey = key.to_public();

let plaintext = b"Hello world!";

// Encrypt the plaintext to a ciphertext...
let encrypted = {
    let encryptor = age::Encryptor::with_recipients(vec![Box::new(pubkey)]);

    let mut encrypted = vec![];
    let mut writer = encryptor.wrap_output(&mut encrypted)?;
    writer.write_all(plaintext)?;
    writer.finish()?;

    encrypted
};

// ... and decrypt the obtained ciphertext to the plaintext again.
let decrypted = {
    let decryptor = match age::Decryptor::new(&encrypted[..])? {
        age::Decryptor::Recipients(d) => d,
        _ => unreachable!(),
    };

    let mut decrypted = vec![];
    let mut reader = decryptor.decrypt(
        iter::once(Box::new(key) as Box<dyn age::Identity>))?;
    reader.read_to_end(&mut decrypted);

    decrypted
};

assert_eq!(decrypted, plaintext);

Passphrase-based encryption

use secrecy::Secret;
use std::io::{Read, Write};

let plaintext = b"Hello world!";
let passphrase = "this is not a good passphrase";

// Encrypt the plaintext to a ciphertext using the passphrase...
let encrypted = {
    let encryptor = age::Encryptor::with_user_passphrase(Secret::new(passphrase.to_owned()));

    let mut encrypted = vec![];
    let mut writer = encryptor.wrap_output(&mut encrypted)?;
    writer.write_all(plaintext)?;
    writer.finish()?;

    encrypted
};

// ... and decrypt the ciphertext to the plaintext again using the same passphrase.
let decrypted = {
    let decryptor = match age::Decryptor::new(&encrypted[..])? {
        age::Decryptor::Passphrase(d) => d,
        _ => unreachable!(),
    };

    let mut decrypted = vec![];
    let mut reader = decryptor.decrypt(&Secret::new(passphrase.to_owned()), None)?;
    reader.read_to_end(&mut decrypted);

    decrypted
};

assert_eq!(decrypted, plaintext);

Modules

decryptor	Decryptors for age.
stream	I/O helper structs for age file encryption and decryption.
x25519	The "x25519" recipient type, native to age.

Structs

Encryptor	Encryptor for creating an age file.
IdentityFile	A list of identities that has been parsed from some input file.

Enums

DecryptError	The various errors that can be returned during the decryption process.
Decryptor	Decryptor for an age file.
EncryptError	The various errors that can be returned during the encryption process.

Traits

Identity	A private key or other value that can unwrap an opaque file key from a recipient stanza.
Recipient	A public key or other value that can wrap an opaque file key to a recipient stanza.

Functions

localizer

Returns the Localizer to be used for localizing this library.