Crate age

Library for encrypting and decrypting 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 Go 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.
• For passphrase-based encryption and decryption, use scrypt::Recipient and scrypt::Identity, or the helper method Encryptor::with_user_passphrase. 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

Streamlined APIs

These are useful when you only need to encrypt to a single recipient, and the data is small enough to fit in memory.

Recipient-based encryption

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

let plaintext = b"Hello world!";

let encrypted = age::encrypt(&pubkey, plaintext)?;
let decrypted = age::decrypt(&key, &encrypted)?;

assert_eq!(decrypted, plaintext);

Passphrase-based encryption

use age::secrecy::SecretString;

let passphrase = SecretString::from("this is not a good passphrase".to_owned());
let recipient = age::scrypt::Recipient::new(passphrase.clone());
let identity = age::scrypt::Identity::new(passphrase);

let plaintext = b"Hello world!";

let encrypted = age::encrypt(&recipient, plaintext)?;
let decrypted = age::decrypt(&identity, &encrypted)?;

assert_eq!(decrypted, plaintext);

Full APIs

The full APIs support encrypting to multiple recipients, streaming the data, and have async I/O options.

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(iter::once(&pubkey as _))
        .expect("we provided a recipient");

    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 = age::Decryptor::new(&encrypted[..])?;

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

    decrypted
};

assert_eq!(decrypted, plaintext);

Passphrase-based encryption

use age::secrecy::SecretString;
use std::io::{Read, Write};
use std::iter;

let plaintext = b"Hello world!";
let passphrase = SecretString::from("this is not a good passphrase".to_owned());

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

    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 = age::Decryptor::new(&encrypted[..])?;

    let mut decrypted = vec![];
    let mut reader = decryptor.decrypt(iter::once(&age::scrypt::Identity::new(passphrase) as _))?;
    reader.read_to_end(&mut decrypted);

    decrypted
};

assert_eq!(decrypted, plaintext);

Re-exports

pub use age_core::secrecy;

Modules

armorarmor

I/O helper structs for the age ASCII armor format.

cli_commoncli-common

Common helpers for CLI binaries.

encrypted

The “encrypted age identity file” identity type.

pluginplugin

Support for the age plugin system.

scrypt

The “scrypt” passphrase-based recipient type, native to age.

sshssh

The “ssh-rsa” and “ssh-ed25519” recipient types, which allow reusing existing SSH keys for encryption with age-encryption.org/v1.

stream

I/O helper structs for age file encryption and decryption.

x25519

The “x25519” recipient type, native to age.

Structs

Decryptor

Decryptor for an age file.

Encryptor

Encryptor for creating an age file.

IdentityFile

A list of identities that has been parsed from some input file.

NoCallbacks

An implementation of Callbacks that does not allow callbacks.

Enums

DecryptError

The various errors that can be returned during the decryption process.

EncryptError

The various errors that can be returned during the encryption process.

IdentityFileConvertError

Errors returned when converting an identity file to a recipients file.

Traits

Callbacks

Callbacks that might be triggered during encryption or decryption.

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

decrypt

Decrypts the given ciphertext with the given identity.

encrypt

Encrypts the given plaintext to the given recipient.

encrypt_and_armorarmor

Encrypts the given plaintext to the given recipient, and wraps the ciphertext in ASCII armor.

localizer

Returns the Localizer to be used for localizing this library.