age 0.11.2

[BETA] A simple, secure, and modern encryption library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

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

use crate::{
    error::{DecryptError, EncryptError},
    Decryptor, Encryptor, Identity, Recipient,
};

#[cfg(feature = "armor")]
use crate::armor::{ArmoredReader, ArmoredWriter, Format};

/// Encrypts the given plaintext to the given recipient.
///
/// To encrypt to more than one recipient, use [`Encryptor::with_recipients`].
///
/// This function returns binary ciphertext. To obtain an ASCII-armored text string, use
/// [`encrypt_and_armor`].
pub fn encrypt(recipient: &impl Recipient, plaintext: &[u8]) -> Result<Vec<u8>, EncryptError> {
    let encryptor =
        Encryptor::with_recipients(iter::once(recipient as _)).expect("we provided a recipient");

    let mut ciphertext = Vec::with_capacity(plaintext.len());
    let mut writer = encryptor.wrap_output(&mut ciphertext)?;
    writer.write_all(plaintext)?;
    writer.finish()?;

    Ok(ciphertext)
}

/// Encrypts the given plaintext to the given recipient, and wraps the ciphertext in ASCII
/// armor.
///
/// To encrypt to more than one recipient, use [`Encryptor::with_recipients`] along with
/// [`ArmoredWriter`].
#[cfg(feature = "armor")]
#[cfg_attr(docsrs, doc(cfg(feature = "armor")))]
pub fn encrypt_and_armor(
    recipient: &impl Recipient,
    plaintext: &[u8],
) -> Result<String, EncryptError> {
    let encryptor =
        Encryptor::with_recipients(iter::once(recipient as _)).expect("we provided a recipient");

    let mut ciphertext = Vec::with_capacity(plaintext.len());
    let mut writer = encryptor.wrap_output(ArmoredWriter::wrap_output(
        &mut ciphertext,
        Format::AsciiArmor,
    )?)?;
    writer.write_all(plaintext)?;
    writer.finish()?.finish()?;

    Ok(String::from_utf8(ciphertext).expect("is armored"))
}

/// Decrypts the given ciphertext with the given identity.
///
/// If the `armor` feature flag is enabled, this will also handle armored age ciphertexts.
///
/// To attempt decryption with more than one identity, use [`Decryptor`] (as well as
/// [`ArmoredReader`] if the `armor` feature flag is enabled).
pub fn decrypt(identity: &impl Identity, ciphertext: &[u8]) -> Result<Vec<u8>, DecryptError> {
    #[cfg(feature = "armor")]
    let decryptor = Decryptor::new_buffered(ArmoredReader::new(ciphertext))?;

    #[cfg(not(feature = "armor"))]
    let decryptor = Decryptor::new_buffered(ciphertext)?;

    let mut plaintext = vec![];
    let mut reader = decryptor.decrypt(iter::once(identity as _))?;
    reader.read_to_end(&mut plaintext)?;

    Ok(plaintext)
}

#[cfg(test)]
mod tests {
    use super::{decrypt, encrypt};
    use crate::x25519;

    #[cfg(feature = "armor")]
    use super::encrypt_and_armor;

    #[test]
    fn x25519_round_trip() {
        let sk: x25519::Identity = crate::x25519::tests::TEST_SK.parse().unwrap();
        let pk: x25519::Recipient = crate::x25519::tests::TEST_PK.parse().unwrap();
        let test_msg = b"This is a test message. For testing.";

        let encrypted = encrypt(&pk, test_msg).unwrap();
        let decrypted = decrypt(&sk, &encrypted).unwrap();
        assert_eq!(&decrypted[..], &test_msg[..]);
    }

    #[cfg(feature = "armor")]
    #[test]
    fn x25519_round_trip_armor() {
        let sk: x25519::Identity = crate::x25519::tests::TEST_SK.parse().unwrap();
        let pk: x25519::Recipient = crate::x25519::tests::TEST_PK.parse().unwrap();
        let test_msg = b"This is a test message. For testing.";

        let encrypted = encrypt_and_armor(&pk, test_msg).unwrap();
        assert!(encrypted.starts_with("-----BEGIN AGE ENCRYPTED FILE-----"));

        let decrypted = decrypt(&sk, encrypted.as_bytes()).unwrap();
        assert_eq!(&decrypted[..], &test_msg[..]);
    }
}