age: Return label set from Recipient::wrap_file_key

age-core/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to Rust's notion of
 to 1.0.0 are beta releases.
 
 ## [Unreleased]
+### Added
+- `age_core::format::is_arbitrary_string`
 
 ## [0.10.0] - 2024-02-04
 ### Added

age-core/src/format.rs

@@ -90,6 +90,16 @@ impl From<AgeStanza<'_>> for Stanza {
     }
 }
 
+/// Checks whether the string is a valid age "arbitrary string" (`1*VCHAR` in ABNF).
+pub fn is_arbitrary_string<S: AsRef<str>>(s: &S) -> bool {
+    let s = s.as_ref();
+    !s.is_empty()
+        && s.chars().all(|c| match u8::try_from(c) {
+            Ok(u) => (33..=126).contains(&u),
+            Err(_) => false,
+        })
+}
+
 /// Creates a random recipient stanza that exercises the joint in the age v1 format.
 ///
 /// This function is guaranteed to return a valid stanza, but makes no other guarantees

age/CHANGELOG.md

@@ -18,6 +18,9 @@ to 1.0.0 are beta releases.
 ### Changed
 - `age::Decryptor` is now an opaque struct instead of an enum with `Recipients`
   and `Passphrase` variants.
+- `age::Recipient::wrap_file_key` now returns `(Vec<Stanza>, HashSet<String>)`:
+  a tuple of the stanzas to be placed in an age file header, and labels that
+  constrain how the stanzas may be combined with those from other recipients.
 
 ### Removed
 - `age::decryptor::PassphraseDecryptor` (use `age::Decryptor` with

age/i18n/en-US/age.ftl

@@ -57,6 +57,11 @@ err-header-invalid = Header is invalid
 
 err-header-mac-invalid = Header MAC is invalid
 
+err-incompatible-recipients-oneway = Cannot encrypt to a recipient with labels '{$labels}' alongside a recipient with no labels
+err-incompatible-recipients-twoway = Cannot encrypt to a recipient with labels '{$left}' alongside a recipient with labels '{$right}'
+
+err-invalid-recipient-labels = The first recipient requires one or more invalid labels: '{$labels}'
+
 err-key-decryption = Failed to decrypt an encrypted key
 
 err-mixed-recipient-passphrase = {-scrypt-recipient} can't be used with other recipients.

age/src/encrypted.rs

@@ -269,7 +269,8 @@ fOrxrKTj7xCdNS3+OrCdnBC8Z9cKDxjCGWW3fkjLsYha0Jo=
     fn round_trip() {
         let pk: x25519::Recipient = TEST_RECIPIENT.parse().unwrap();
         let file_key = [12; 16].into();
-        let wrapped = pk.wrap_file_key(&file_key).unwrap();
+        let (wrapped, labels) = pk.wrap_file_key(&file_key).unwrap();
+        assert!(labels.is_empty());
 
         // Unwrapping with the wrong passphrase fails.
         {

age/src/error.rs

@@ -1,5 +1,6 @@
 //! Error type.
 
+use std::collections::HashSet;
 use std::fmt;
 use std::io;
 
@@ -101,6 +102,18 @@ impl fmt::Display for PluginError {
 pub enum EncryptError {
     /// An error occured while decrypting passphrase-encrypted identities.
     EncryptedIdentities(DecryptError),
+    /// The encryptor was given recipients that declare themselves incompatible.
+    IncompatibleRecipients {
+        /// The set of labels from the first recipient provided to the encryptor.
+        l_labels: HashSet<String>,
+        /// The set of labels from the first non-matching recipient.
+        r_labels: HashSet<String>,
+    },
+    /// One or more of the labels from the first recipient provided to the encryptor are
+    /// invalid.
+    ///
+    /// Labels must be valid age "arbitrary string"s (`1*VCHAR` in ABNF).
+    InvalidRecipientLabels(HashSet<String>),
     /// An I/O error occurred during encryption.
     Io(io::Error),
     /// A required plugin could not be found.
@@ -130,6 +143,11 @@ impl Clone for EncryptError {
     fn clone(&self) -> Self {
         match self {
             Self::EncryptedIdentities(e) => Self::EncryptedIdentities(e.clone()),
+            Self::IncompatibleRecipients { l_labels, r_labels } => Self::IncompatibleRecipients {
+                l_labels: l_labels.clone(),
+                r_labels: r_labels.clone(),
+            },
+            Self::InvalidRecipientLabels(labels) => Self::InvalidRecipientLabels(labels.clone()),
             Self::Io(e) => Self::Io(io::Error::new(e.kind(), e.to_string())),
             #[cfg(feature = "plugin")]
             Self::MissingPlugin { binary_name } => Self::MissingPlugin {
@@ -142,10 +160,51 @@ impl Clone for EncryptError {
     }
 }
 
+fn print_labels(labels: &HashSet<String>) -> String {
+    let mut s = String::new();
+    for (i, label) in labels.iter().enumerate() {
+        s.push_str(label);
+        if i != 0 {
+            s.push_str(", ");
+        }
+    }
+    s
+}
+
 impl fmt::Display for EncryptError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             EncryptError::EncryptedIdentities(e) => e.fmt(f),
+            EncryptError::IncompatibleRecipients { l_labels, r_labels } => {
+                match (l_labels.is_empty(), r_labels.is_empty()) {
+                    (true, true) => unreachable!("labels are compatible"),
+                    (false, true) => {
+                        wfl!(
+                            f,
+                            "err-incompatible-recipients-oneway",
+                            labels = print_labels(l_labels),
+                        )
+                    }
+                    (true, false) => {
+                        wfl!(
+                            f,
+                            "err-incompatible-recipients-oneway",
+                            labels = print_labels(r_labels),
+                        )
+                    }
+                    (false, false) => wfl!(
+                        f,
+                        "err-incompatible-recipients-twoway",
+                        left = print_labels(l_labels),
+                        right = print_labels(r_labels),
+                    ),
+                }
+            }
+            EncryptError::InvalidRecipientLabels(labels) => wfl!(
+                f,
+                "err-invalid-recipient-labels",
+                labels = print_labels(labels),
+            ),
             EncryptError::Io(e) => e.fmt(f),
             #[cfg(feature = "plugin")]
             EncryptError::MissingPlugin { binary_name } => {

age/src/lib.rs

@@ -136,6 +136,8 @@
 #![deny(rustdoc::broken_intra_doc_links)]
 #![deny(missing_docs)]
 
+use std::collections::HashSet;
+
 // Re-export crates that are used in our public API.
 pub use age_core::secrecy;
 
@@ -222,7 +224,9 @@ pub trait Identity {
 ///
 /// Implementations of this trait might represent more than one recipient.
 pub trait Recipient {
-    /// Wraps the given file key, returning stanzas to be placed in an age file header.
+    /// Wraps the given file key, returning stanzas to be placed in an age file header,
+    /// and labels that constrain how the stanzas may be combined with those from other
+    /// recipients.
     ///
     /// Implementations MUST NOT return more than one stanza per "actual recipient".
     ///
@@ -231,7 +235,38 @@ pub trait Recipient {
     /// recipients to [`Encryptor::with_recipients`].
     ///
     /// [one joint]: https://www.imperialviolet.org/2016/05/16/agility.html
-    fn wrap_file_key(&self, file_key: &FileKey) -> Result<Vec<Stanza>, EncryptError>;
+    ///
+    /// # Labels
+    ///
+    /// [`Encryptor`] will succeed at encrypting only if every recipient returns the same
+    /// set of labels. Subsets or partial overlapping sets are not allowed; all sets must
+    /// be identical. Labels are compared exactly, and are case-sensitive.
+    ///
+    /// Label sets can be used to ensure a recipient is only encrypted to alongside other
+    /// recipients with equivalent properties, or to ensure a recipient is always used
+    /// alone. A recipient with no particular properties to enforce should return an empty
+    /// label set.
+    ///
+    /// Labels can have any value that is a valid arbitrary string (`1*VCHAR` in ABNF),
+    /// but usually take one of several forms:
+    ///   - *Common public label* - used by multiple recipients to permit their stanzas to
+    ///     be used only together. Examples include:
+    ///     - `postquantum` - indicates that the recipient stanzas being generated are
+    ///       postquantum-secure, and that they can only be combined with other stanzas
+    ///       that are also postquantum-secure.
+    ///   - *Common private label* - used by recipients created by the same private entity
+    ///     to permit their recipient stanzas to be used only together. For example,
+    ///     private recipients used in a corporate environment could all send the same
+    ///     private label in order to prevent compliant age clients from simultaneously
+    ///     wrapping file keys with other recipients.
+    ///   - *Random label* - used by recipients that want to ensure their stanzas are not
+    ///     used with any other recipient stanzas. This can be used to produce a file key
+    ///     that is only encrypted to a single recipient stanza, for example to preserve
+    ///     its authentication properties.
+    fn wrap_file_key(
+        &self,
+        file_key: &FileKey,
+    ) -> Result<(Vec<Stanza>, HashSet<String>), EncryptError>;
 }
 
 /// Callbacks that might be triggered during encryption or decryption.

age/src/plugin.rs

@@ -10,6 +10,7 @@ use base64::{prelude::BASE64_STANDARD_NO_PAD, Engine};
 use bech32::Variant;
 
 use std::borrow::Borrow;
+use std::collections::HashSet;
 use std::fmt;
 use std::io;
 use std::iter;
@@ -377,7 +378,10 @@ impl<C: Callbacks> RecipientPluginV1<C> {
 }
 
 impl<C: Callbacks> crate::Recipient for RecipientPluginV1<C> {
-    fn wrap_file_key(&self, file_key: &FileKey) -> Result<Vec<Stanza>, EncryptError> {
+    fn wrap_file_key(
+        &self,
+        file_key: &FileKey,
+    ) -> Result<(Vec<Stanza>, HashSet<String>), EncryptError> {
         // Open connection
         let mut conn = self.plugin.connect(RECIPIENT_V1)?;
 
@@ -396,6 +400,7 @@ impl<C: Callbacks> crate::Recipient for RecipientPluginV1<C> {
 
         // Phase 2: collect either stanzas or errors
         let mut stanzas = vec![];
+        let labels = HashSet::new();
         let mut errors = vec![];
         if let Err(e) = conn.bidir_receive(
             &[
@@ -484,7 +489,7 @@ impl<C: Callbacks> crate::Recipient for RecipientPluginV1<C> {
             return Err(e.into());
         };
         match (stanzas.is_empty(), errors.is_empty()) {
-            (false, true) => Ok(stanzas),
+            (false, true) => Ok((stanzas, labels)),
             (a, b) => {
                 if a & b {
                     errors.push(PluginError::Other {

age/src/protocol.rs

@@ -1,6 +1,6 @@
 //! Encryption and decryption routines for age.
 
-use age_core::secrecy::SecretString;
+use age_core::{format::is_arbitrary_string, secrecy::SecretString};
 use rand::{rngs::OsRng, RngCore};
 use std::io::{self, BufRead, Read, Write};
 
@@ -78,9 +78,34 @@ impl Encryptor {
         let file_key = new_file_key();
 
         let recipients = {
+            let mut control = None;
+
             let mut stanzas = Vec::with_capacity(self.recipients.len() + 1);
             for recipient in self.recipients {
-                stanzas.append(&mut recipient.wrap_file_key(&file_key)?);
+                let (mut r_stanzas, r_labels) = recipient.wrap_file_key(&file_key)?;
+
+                if let Some(l_labels) = control.take() {
+                    if l_labels != r_labels {
+                        // Improve error message.
+                        let err = if stanzas
+                            .iter()
+                            .chain(&r_stanzas)
+                            .any(|stanza| stanza.tag == crate::scrypt::SCRYPT_RECIPIENT_TAG)
+                        {
+                            EncryptError::MixedRecipientAndPassphrase
+                        } else {
+                            EncryptError::IncompatibleRecipients { l_labels, r_labels }
+                        };
+                        return Err(err);
+                    }
+                    control = Some(l_labels);
+                } else if r_labels.iter().all(is_arbitrary_string) {
+                    control = Some(r_labels);
+                } else {
+                    return Err(EncryptError::InvalidRecipientLabels(r_labels));
+                }
+
+                stanzas.append(&mut r_stanzas);
             }
             stanzas
         };
@@ -292,9 +317,11 @@ impl<R: AsyncBufRead + Unpin> Decryptor<R> {
 
 #[cfg(test)]
 mod tests {
-    use age_core::secrecy::SecretString;
+    use std::collections::HashSet;
     use std::io::{BufReader, Read, Write};
 
+    use age_core::secrecy::SecretString;
+
     #[cfg(feature = "ssh")]
     use std::iter;
 
@@ -525,4 +552,35 @@ mod tests {
             Err(EncryptError::MixedRecipientAndPassphrase),
         ));
     }
+
+    struct IncompatibleRecipient(crate::x25519::Recipient);
+
+    impl Recipient for IncompatibleRecipient {
+        fn wrap_file_key(
+            &self,
+            file_key: &age_core::format::FileKey,
+        ) -> Result<(Vec<age_core::format::Stanza>, HashSet<String>), EncryptError> {
+            self.0.wrap_file_key(file_key).map(|(stanzas, mut labels)| {
+                labels.insert("incompatible".into());
+                (stanzas, labels)
+            })
+        }
+    }
+
+    #[test]
+    fn incompatible_recipients() {
+        let pk: x25519::Recipient = crate::x25519::tests::TEST_PK.parse().unwrap();
+
+        let recipients = vec![
+            Box::new(pk.clone()) as _,
+            Box::new(IncompatibleRecipient(pk)) as _,
+        ];
+
+        let mut encrypted = vec![];
+        let e = Encryptor::with_recipients(recipients).unwrap();
+        assert!(matches!(
+            e.wrap_output(&mut encrypted),
+            Err(EncryptError::IncompatibleRecipients { .. }),
+        ));
+    }
 }

age/src/scrypt.rs

@@ -1,13 +1,20 @@
 //! The "scrypt" passphrase-based recipient type, native to age.
 
+use std::collections::HashSet;
+use std::iter;
+use std::time::Duration;
+
 use age_core::{
     format::{FileKey, Stanza, FILE_KEY_BYTES},
     primitives::{aead_decrypt, aead_encrypt},
     secrecy::{ExposeSecret, SecretString},
 };
 use base64::{prelude::BASE64_STANDARD_NO_PAD, Engine};
-use rand::{rngs::OsRng, RngCore};
-use std::time::Duration;
+use rand::{
+    distributions::{Alphanumeric, DistString},
+    rngs::OsRng,
+    RngCore,
+};
 use zeroize::Zeroize;
 
 use crate::{
@@ -107,9 +114,14 @@ impl Recipient {
 }
 
 impl crate::Recipient for Recipient {
-    fn wrap_file_key(&self, file_key: &FileKey) -> Result<Vec<Stanza>, EncryptError> {
+    fn wrap_file_key(
+        &self,
+        file_key: &FileKey,
+    ) -> Result<(Vec<Stanza>, HashSet<String>), EncryptError> {
+        let mut rng = OsRng;
+
         let mut salt = [0; SALT_LEN];
-        OsRng.fill_bytes(&mut salt);
+        rng.fill_bytes(&mut salt);
 
         let mut inner_salt = [0; SCRYPT_SALT_LABEL.len() + SALT_LEN];
         inner_salt[..SCRYPT_SALT_LABEL.len()].copy_from_slice(SCRYPT_SALT_LABEL);
@@ -123,11 +135,16 @@ impl crate::Recipient for Recipient {
 
         let encoded_salt = BASE64_STANDARD_NO_PAD.encode(salt);
 
-        Ok(vec![Stanza {
-            tag: SCRYPT_RECIPIENT_TAG.to_owned(),
-            args: vec![encoded_salt, format!("{}", log_n)],
-            body: encrypted_file_key,
-        }])
+        let label = Alphanumeric.sample_string(&mut rng, 32);
+
+        Ok((
+            vec![Stanza {
+                tag: SCRYPT_RECIPIENT_TAG.to_owned(),
+                args: vec![encoded_salt, format!("{}", log_n)],
+                body: encrypted_file_key,
+            }],
+            iter::once(label).collect(),
+        ))
     }
 }
 

age/src/ssh/identity.rs

@@ -507,7 +507,8 @@ AwQFBg==
 
         let file_key = [12; 16].into();
 
-        let wrapped = pk.wrap_file_key(&file_key).unwrap();
+        let (wrapped, labels) = pk.wrap_file_key(&file_key).unwrap();
+        assert!(labels.is_empty());
         let unwrapped = identity.unwrap_stanzas(&wrapped);
         assert_eq!(
             unwrapped.unwrap().unwrap().expose_secret(),
@@ -533,7 +534,8 @@ AwQFBg==
 
             let file_key = [12; 16].into();
 
-            let wrapped = pk.wrap_file_key(&file_key).unwrap();
+            let (wrapped, labels) = pk.wrap_file_key(&file_key).unwrap();
+            assert!(labels.is_empty());
             let unwrapped = identity.unwrap_stanzas(&wrapped);
             assert_eq!(
                 unwrapped.unwrap().unwrap().expose_secret(),

age/src/ssh/recipient.rs

@@ -1,3 +1,6 @@
+use std::collections::HashSet;
+use std::fmt;
+
 use age_core::{
     format::{FileKey, Stanza},
     primitives::{aead_encrypt, hkdf},
@@ -18,7 +21,6 @@ use nom::{
 use rand::rngs::OsRng;
 use rsa::{traits::PublicKeyParts, Oaep};
 use sha2::Sha256;
-use std::fmt;
 use x25519_dalek::{EphemeralSecret, PublicKey as X25519PublicKey, StaticSecret};
 
 use super::{
@@ -144,10 +146,13 @@ impl TryFrom<Identity> for Recipient {
 }
 
 impl crate::Recipient for Recipient {
-    fn wrap_file_key(&self, file_key: &FileKey) -> Result<Vec<Stanza>, EncryptError> {
+    fn wrap_file_key(
+        &self,
+        file_key: &FileKey,
+    ) -> Result<(Vec<Stanza>, HashSet<String>), EncryptError> {
         let mut rng = OsRng;
 
-        match self {
+        let stanzas = match self {
             Recipient::SshRsa(ssh_key, pk) => {
                 let encrypted_file_key = pk
                     .encrypt(
@@ -159,11 +164,11 @@ impl crate::Recipient for Recipient {
 
                 let encoded_tag = BASE64_STANDARD_NO_PAD.encode(ssh_tag(ssh_key));
 
-                Ok(vec![Stanza {
+                vec![Stanza {
                     tag: SSH_RSA_RECIPIENT_TAG.to_owned(),
                     args: vec![encoded_tag],
                     body: encrypted_file_key,
-                }])
+                }]
             }
             Recipient::SshEd25519(ssh_key, ed25519_pk) => {
                 let pk: X25519PublicKey = ed25519_pk.to_montgomery().to_bytes().into();
@@ -190,13 +195,15 @@ impl crate::Recipient for Recipient {
                 let encoded_tag = BASE64_STANDARD_NO_PAD.encode(ssh_tag(ssh_key));
                 let encoded_epk = BASE64_STANDARD_NO_PAD.encode(epk.as_bytes());
 
-                Ok(vec![Stanza {
+                vec![Stanza {
                     tag: SSH_ED25519_RECIPIENT_TAG.to_owned(),
                     args: vec![encoded_tag, encoded_epk],
                     body: encrypted_file_key,
-                }])
+                }]
             }
-        }
+        };
+
+        Ok((stanzas, HashSet::new()))
     }
 }
 

age/src/x25519.rs

@@ -1,5 +1,8 @@
 //! The "x25519" recipient type, native to age.
 
+use std::collections::HashSet;
+use std::fmt;
+
 use age_core::{
     format::{FileKey, Stanza, FILE_KEY_BYTES},
     primitives::{aead_decrypt, aead_encrypt, hkdf},
@@ -8,7 +11,6 @@ use age_core::{
 use base64::{prelude::BASE64_STANDARD_NO_PAD, Engine};
 use bech32::{ToBase32, Variant};
 use rand::rngs::OsRng;
-use std::fmt;
 use subtle::ConstantTimeEq;
 use x25519_dalek::{EphemeralSecret, PublicKey, StaticSecret};
 use zeroize::Zeroize;
@@ -191,7 +193,10 @@ impl fmt::Debug for Recipient {
 }
 
 impl crate::Recipient for Recipient {
-    fn wrap_file_key(&self, file_key: &FileKey) -> Result<Vec<Stanza>, EncryptError> {
+    fn wrap_file_key(
+        &self,
+        file_key: &FileKey,
+    ) -> Result<(Vec<Stanza>, HashSet<String>), EncryptError> {
         let rng = OsRng;
         let esk = EphemeralSecret::random_from_rng(rng);
         let epk: PublicKey = (&esk).into();
@@ -220,11 +225,14 @@ impl crate::Recipient for Recipient {
 
         let encoded_epk = BASE64_STANDARD_NO_PAD.encode(epk.as_bytes());
 
-        Ok(vec![Stanza {
-            tag: X25519_RECIPIENT_TAG.to_owned(),
-            args: vec![encoded_epk],
-            body: encrypted_file_key,
-        }])
+        Ok((
+            vec![Stanza {
+                tag: X25519_RECIPIENT_TAG.to_owned(),
+                args: vec![encoded_epk],
+                body: encrypted_file_key,
+            }],
+            HashSet::new(),
+        ))
     }
 }
 
@@ -264,11 +272,13 @@ pub(crate) mod tests {
                 StaticSecret::from(tmp)
             };
 
-            let stanzas = Recipient(PublicKey::from(&sk))
+            let res = Recipient(PublicKey::from(&sk))
                 .wrap_file_key(&file_key);
-            prop_assert!(stanzas.is_ok());
+            prop_assert!(res.is_ok());
+            let (stanzas, labels) = res.unwrap();
+            prop_assert!(labels.is_empty());
 
-            let res = Identity(sk).unwrap_stanzas(&stanzas.unwrap());
+            let res = Identity(sk).unwrap_stanzas(&stanzas);
             prop_assert!(res.is_some());
             let res = res.unwrap();
             prop_assert!(res.is_ok());