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
108
109
110
111
112
113
114
115
116
117
118
use crateparse_recipients;
use crateResult;
use crateEncryptError;
use crateArmoredData;
use ;
use Write;
/// Encrypts plaintext for one or more recipients and returns the result
/// in **armor‑encoded** (PEM‑like) format.
///
/// # Overview
///
/// This function is the armored counterpart to [`encrypt`]. Instead of
/// returning raw binary ciphertext, it wraps the encrypted data in a
/// `-----BEGIN AGE ENCRYPTED FILE-----` / `-----END AGE ENCRYPTED FILE-----`
/// envelope, making it safe to transmit over text‑based channels (email,
/// chat, JSON, etc.).
///
/// The returned [`ArmoredData`] guarantees that the string:
/// - is valid UTF‑8,
/// - contains the standard age armor markers,
/// - can be passed directly to [`decrypt_armor`].
///
/// # Parameters
///
/// - `plaintext`: The data to encrypt, as a byte slice.
/// - `recipients`: A slice of recipient public keys, each a string
/// starting with `age1...`. At least one recipient is required.
///
/// # Returns
///
/// - `Ok(ArmoredData)` – a newtype wrapping the armored ciphertext.
/// - `Err(Error::Encrypt(...))` – if any step fails (see [Errors](#errors)).
///
/// # Errors
///
/// | Condition | Error Variant |
/// |-----------|---------------|
/// | `recipients` is empty | [`EncryptError::NoRecipients`] |
/// | Any recipient string is not a valid age public key | [`EncryptError::InvalidRecipient`] |
/// | Internal encryption failure (RNG, key wrapping) | [`EncryptError::Failed`] |
/// | I/O error while writing the armored output | [`EncryptError::Io`] |
/// | The armor output is not valid UTF‑8 (should never happen) | [`EncryptError::Failed`] (with a descriptive message) |
///
/// # Panics
///
/// **No.** The function never panics; all error conditions are returned as `Err`.
///
/// # Security Notes
///
/// - Non‑deterministic – each call produces a different ciphertext,
/// even for the same plaintext and recipients.
/// - Multi‑recipient – any single recipient whose public key was
/// included can decrypt the result (using the corresponding secret key).
/// - Tamper‑evident – the armor+encryption combination is
/// authenticated; modifying a single character of the armored text
/// will make decryption fail.
/// - Armor suitability – the output is safe to embed in JSON,
/// XML, or email bodies because it uses only printable ASCII
/// characters and fixed‑width lines.
/// - Memory – the entire armored string is built in memory. For
/// very large files (>100 MB), consider streaming the encryption
/// directly with `age::Encryptor` and `ArmoredWriter`.
///
/// # Example
///
/// ```
/// use age_crypto::encrypt_armor;
/// use age_setup::build_keypair;
///
/// # fn main() -> age_crypto::errors::Result<()> {
/// // Generate two key pairs
/// let alice = build_keypair().expect("key generation failed");
/// let bob = build_keypair().expect("key generation failed");
/// let pub_a = alice.public.expose();
/// let pub_b = bob.public.expose();
///
/// // Encrypt for both recipients
/// let plaintext = b"Multi\xE2\x80\x91recipient secret";
/// let armored = encrypt_armor(plaintext, &[pub_a, pub_b])?;
///
/// // Verify the armor markers
/// assert!(armored.starts_with("-----BEGIN AGE ENCRYPTED FILE-----"));
/// assert!(armored.ends_with("-----END AGE ENCRYPTED FILE-----\n"));
/// // or simply use the built-in check
/// assert!(age_crypto::ArmoredData::is_valid_armored(&armored));
/// # Ok(())
/// # }
/// ```
///
/// # See Also
///
/// - [`encrypt`] – binary (non‑armored) encryption.
/// - [`encrypt_with_passphrase_armor`] – passphrase‑based armored encryption.