Merge pull request #514 from str4d/403-labels

Implement labels

age-core/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to Rust's notion of
 to 1.0.0 are beta releases.
 
 ## [Unreleased]
+### Added
+- `age_core::format::is_arbitrary_string`
+
+### Changed
+- `age::plugin::Connection::unidir_receive` now takes an additional argument to
+  enable handling an optional fourth command.
 
 ## [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-core/src/plugin.rs

@@ -51,10 +51,11 @@ impl std::error::Error for Error {}
 ///   should explicitly handle.
 pub type Result<T> = io::Result<std::result::Result<T, Error>>;
 
-type UnidirResult<A, B, C, E> = io::Result<(
+type UnidirResult<A, B, C, D, E> = io::Result<(
     std::result::Result<Vec<A>, Vec<E>>,
     std::result::Result<Vec<B>, Vec<E>>,
     Option<std::result::Result<Vec<C>, Vec<E>>>,
+    Option<std::result::Result<Vec<D>, Vec<E>>>,
 )>;
 
 /// A connection to a plugin binary.
@@ -205,23 +206,26 @@ impl<R: Read, W: Write> Connection<R, W> {
     ///
     /// # Arguments
     ///
-    /// `command_a`, `command_b`, and (optionally) `command_c` are the known commands that
+    /// `command_a`, `command_b`, and (optionally) `command_c` and `command_d` are the
-    /// are expected to be received. All other received commands (including grease) will
+    /// known commands that are expected to be received. All other received commands
-    /// be ignored.
+    /// (including grease) will be ignored.
-    pub fn unidir_receive<A, B, C, E, F, G, H>(
+    pub fn unidir_receive<A, B, C, D, E, F, G, H, I>(
         &mut self,
         command_a: (&str, F),
         command_b: (&str, G),
         command_c: (Option<&str>, H),
-    ) -> UnidirResult<A, B, C, E>
+        command_d: (Option<&str>, I),
+    ) -> UnidirResult<A, B, C, D, E>
     where
         F: Fn(Stanza) -> std::result::Result<A, E>,
         G: Fn(Stanza) -> std::result::Result<B, E>,
         H: Fn(Stanza) -> std::result::Result<C, E>,
+        I: Fn(Stanza) -> std::result::Result<D, E>,
     {
         let mut res_a = Ok(vec![]);
         let mut res_b = Ok(vec![]);
         let mut res_c = Ok(vec![]);
+        let mut res_d = Ok(vec![]);
 
         for stanza in iter::repeat_with(|| self.receive()).take_while(|res| match res {
             Ok(stanza) => stanza.tag != COMMAND_DONE,
@@ -251,14 +255,28 @@ impl<R: Read, W: Write> Connection<R, W> {
                 validate(command_a.1(stanza), &mut res_a)
             } else if stanza.tag.as_str() == command_b.0 {
                 validate(command_b.1(stanza), &mut res_b)
-            } else if let Some(tag) = command_c.0 {
+            } else {
-                if stanza.tag.as_str() == tag {
+                if let Some(tag) = command_c.0 {
-                    validate(command_c.1(stanza), &mut res_c)
+                    if stanza.tag.as_str() == tag {
+                        validate(command_c.1(stanza), &mut res_c);
+                        continue;
+                    }
+                }
+                if let Some(tag) = command_d.0 {
+                    if stanza.tag.as_str() == tag {
+                        validate(command_d.1(stanza), &mut res_d);
+                        continue;
+                    }
                 }
             }
         }
 
-        Ok((res_a, res_b, command_c.0.map(|_| res_c)))
+        Ok((
+            res_a,
+            res_b,
+            command_c.0.map(|_| res_c),
+            command_d.0.map(|_| res_d),
+        ))
     }
 
     /// Runs a bidirectional phase as the controller.
@@ -481,10 +499,11 @@ mod tests {
             .unidir_send(|mut phase| phase.send("test", &["foo"], b"bar"))
             .unwrap();
         let stanza = plugin_conn
-            .unidir_receive::<_, (), (), _, _, _, _>(
+            .unidir_receive::<_, (), (), (), _, _, _, _, _>(
                 ("test", Ok),
                 ("other", |_| Err(())),
                 (None, |_| Ok(())),
+                (None, |_| Ok(())),
             )
             .unwrap();
         assert_eq!(
@@ -496,7 +515,8 @@ mod tests {
                     body: b"bar"[..].to_owned()
                 }]),
                 Ok(vec![]),
-                None
+                None,
+                None,
             )
         );
     }

age-plugin/CHANGELOG.md

@@ -14,6 +14,13 @@ to 1.0.0 are beta releases.
 - `impl age_plugin::identity::IdentityPluginV1 for std::convert::Infallible`
 - `impl age_plugin::recipient::RecipientPluginV1 for std::convert::Infallible`
 
+### Changed
+- `age_plugin::recipient::RecipientPluginV1` has a new `labels` method. Existing
+  implementations of the trait should either return `HashSet::new()` to maintain
+  existing compatibility, or return labels that apply the desired constraints.
+- `age_plugin::run_state_machine` now supports the `recipient-v1` labels
+  extension.
+
 ### Fixed
 - `age_plugin::run_state_machine` now takes an `impl age_plugin::PluginHandler`
   argument, instead of its previous arguments.

age-plugin/examples/age-plugin-unencrypted.rs

@@ -10,7 +10,7 @@ use age_plugin::{
 };
 use clap::Parser;
 
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
 use std::convert::Infallible;
 use std::env;
 use std::io;
@@ -104,6 +104,16 @@ impl RecipientPluginV1 for RecipientPlugin {
         }
     }
 
+    fn labels(&mut self) -> HashSet<String> {
+        let mut labels = HashSet::new();
+        if let Ok(s) = env::var("AGE_PLUGIN_LABELS") {
+            for label in s.split(',') {
+                labels.insert(label.into());
+            }
+        }
+        labels
+    }
+
     fn wrap_file_keys(
         &mut self,
         file_keys: Vec<FileKey>,

age-plugin/src/identity.rs

@@ -222,7 +222,7 @@ pub(crate) fn run_v1<P: IdentityPluginV1>(mut plugin: P) -> io::Result<()> {
 
     // Phase 1: receive identities and stanzas
     let (identities, recipient_stanzas) = {
-        let (identities, stanzas, _) = conn.unidir_receive(
+        let (identities, stanzas, _, _) = conn.unidir_receive(
             (ADD_IDENTITY, |s| match (&s.args[..], &s.body[..]) {
                 ([identity], []) => Ok(identity.clone()),
                 _ => Err(Error::Internal {
@@ -255,6 +255,7 @@ pub(crate) fn run_v1<P: IdentityPluginV1>(mut plugin: P) -> io::Result<()> {
                 }
             }),
             (None, |_| Ok(())),
+            (None, |_| Ok(())),
         )?;
 
         // Now that we have the full list of identities, parse them as Bech32 and add them

age-plugin/src/lib.rs

@@ -78,7 +78,7 @@
 //! };
 //! use clap::Parser;
 //!
-//! use std::collections::HashMap;
+//! use std::collections::{HashMap, HashSet};
 //! use std::io;
 //!
 //! struct Handler;
@@ -117,6 +117,10 @@
 //!         todo!()
 //!     }
 //!
+//!     fn labels(&mut self) -> HashSet<String> {
+//!         todo!()
+//!     }
+//!
 //!     fn wrap_file_keys(
 //!         &mut self,
 //!         file_keys: Vec<FileKey>,

age-plugin/src/recipient.rs

@@ -1,13 +1,14 @@
 //! Recipient plugin helpers.
 
 use age_core::{
-    format::{FileKey, Stanza, FILE_KEY_BYTES},
+    format::{is_arbitrary_string, FileKey, Stanza, FILE_KEY_BYTES},
     plugin::{self, BidirSend, Connection},
     secrecy::SecretString,
 };
 use base64::{prelude::BASE64_STANDARD_NO_PAD, Engine};
 use bech32::FromBase32;
 
+use std::collections::HashSet;
 use std::convert::Infallible;
 use std::io;
 
@@ -16,12 +17,20 @@ use crate::{Callbacks, PLUGIN_IDENTITY_PREFIX, PLUGIN_RECIPIENT_PREFIX};
 const ADD_RECIPIENT: &str = "add-recipient";
 const ADD_IDENTITY: &str = "add-identity";
 const WRAP_FILE_KEY: &str = "wrap-file-key";
+const EXTENSION_LABELS: &str = "extension-labels";
 const RECIPIENT_STANZA: &str = "recipient-stanza";
+const LABELS: &str = "labels";
 
 /// The interface that age implementations will use to interact with an age plugin.
 ///
 /// Implementations of this trait will be used within the [`recipient-v1`] state machine.
 ///
+/// The trait methods are always called in this order:
+/// - [`Self::add_recipient`] / [`Self::add_identity`] (in any order, including
+///   potentially interleaved).
+/// - [`Self::labels`] (once all recipients and identities have been added).
+/// - [`Self::wrap_file_keys`]
+///
 /// [`recipient-v1`]: https://c2sp.org/age-plugin#wrapping-with-recipient-v1
 pub trait RecipientPluginV1 {
     /// Stores a recipient that the user would like to encrypt age files to.
@@ -39,6 +48,36 @@ pub trait RecipientPluginV1 {
     /// Returns an error if the identity is unknown or invalid.
     fn add_identity(&mut self, index: usize, plugin_name: &str, bytes: &[u8]) -> Result<(), Error>;
 
+    /// Returns labels that constrain how the stanzas produced by [`Self::wrap_file_keys`]
+    /// may be combined with those from other recipients.
+    ///
+    /// Encryption will succeed 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 labels(&mut self) -> HashSet<String>;
+
     /// Wraps each `file_key` to all recipients and identities previously added via
     /// `add_recipient` and `add_identity`.
     ///
@@ -65,6 +104,11 @@ impl RecipientPluginV1 for Infallible {
         Ok(())
     }
 
+    fn labels(&mut self) -> HashSet<String> {
+        // This is never executed.
+        HashSet::new()
+    }
+
     fn wrap_file_keys(
         &mut self,
         _: Vec<FileKey>,
@@ -215,8 +259,8 @@ pub(crate) fn run_v1<P: RecipientPluginV1>(mut plugin: P) -> io::Result<()> {
     let mut conn = Connection::accept();
 
     // Phase 1: collect recipients, and file keys to be wrapped
-    let ((recipients, identities), file_keys) = {
+    let ((recipients, identities), file_keys, labels_supported) = {
-        let (recipients, identities, file_keys) = conn.unidir_receive(
+        let (recipients, identities, file_keys, labels_supported) = conn.unidir_receive(
             (ADD_RECIPIENT, |s| match (&s.args[..], &s.body[..]) {
                 ([recipient], []) => Ok(recipient.clone()),
                 _ => Err(Error::Internal {
@@ -243,6 +287,7 @@ pub(crate) fn run_v1<P: RecipientPluginV1>(mut plugin: P) -> io::Result<()> {
                     })
                     .map(FileKey::from)
             }),
+            (Some(EXTENSION_LABELS), |_| Ok(())),
         )?;
         (
             match (recipients, identities) {
@@ -263,6 +308,13 @@ pub(crate) fn run_v1<P: RecipientPluginV1>(mut plugin: P) -> io::Result<()> {
                 }]),
                 r => r,
             },
+            match &labels_supported.unwrap() {
+                Ok(v) if v.is_empty() => Ok(false),
+                Ok(v) if v.len() == 1 => Ok(true),
+                _ => Err(vec![Error::Internal {
+                    message: format!("Received more than one {} command", EXTENSION_LABELS),
+                }]),
+            },
         )
     };
 
@@ -327,23 +379,58 @@ pub(crate) fn run_v1<P: RecipientPluginV1>(mut plugin: P) -> io::Result<()> {
         |index, plugin_name, bytes| plugin.add_identity(index, plugin_name, &bytes),
     );
 
+    let required_labels = plugin.labels();
+
+    let labels = match (labels_supported, required_labels.is_empty()) {
+        (Ok(true), _) | (Ok(false), true) => {
+            if required_labels.contains("") {
+                Err(vec![Error::Internal {
+                    message: "Plugin tried to use the empty string as a label".into(),
+                }])
+            } else if required_labels.iter().all(is_arbitrary_string) {
+                Ok(required_labels)
+            } else {
+                Err(vec![Error::Internal {
+                    message: "Plugin tried to use a label containing an invalid character".into(),
+                }])
+            }
+        }
+        (Ok(false), false) => Err(vec![Error::Internal {
+            message: "Plugin requires labels but client does not support them".into(),
+        }]),
+        (Err(errors), true) => Err(errors),
+        (Err(mut errors), false) => {
+            errors.push(Error::Internal {
+                message: "Plugin requires labels but client does not support them".into(),
+            });
+            Err(errors)
+        }
+    };
+
     // Phase 2: wrap the file keys or return errors
     conn.bidir_send(|mut phase| {
-        let (expected_stanzas, file_keys) = match (recipients, identities, file_keys) {
+        let (expected_stanzas, file_keys, labels) =
-            (Ok(recipients), Ok(identities), Ok(file_keys)) => (recipients + identities, file_keys),
+            match (recipients, identities, file_keys, labels) {
-            (recipients, identities, file_keys) => {
+                (Ok(recipients), Ok(identities), Ok(file_keys), Ok(labels)) => {
-                for error in recipients
+                    (recipients + identities, file_keys, labels)
-                    .err()
-                    .into_iter()
-                    .chain(identities.err())
-                    .chain(file_keys.err())
-                    .flatten()
-                {
-                    error.send(&mut phase)?;
                 }
-                return Ok(());
+                (recipients, identities, file_keys, labels) => {
-            }
+                    for error in recipients
-        };
+                        .err()
+                        .into_iter()
+                        .chain(identities.err())
+                        .chain(file_keys.err())
+                        .chain(labels.err())
+                        .flatten()
+                    {
+                        error.send(&mut phase)?;
+                    }
+                    return Ok(());
+                }
+            };
+
+        let labels = labels.iter().map(|s| s.as_str()).collect::<Vec<_>>();
+        phase.send(LABELS, &labels, &[])?.unwrap();
 
         match plugin.wrap_file_keys(file_keys, BidirCallbacks(&mut phase))? {
             Ok(files) => {

age/CHANGELOG.md

@@ -18,6 +18,10 @@ 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.
+- `age::plugin::RecipientPluginV1` now supports the labels extension.
 
 ### 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;
@@ -32,6 +33,7 @@ const PLUGIN_IDENTITY_PREFIX: &str = "age-plugin-";
 
 const CMD_ERROR: &str = "error";
 const CMD_RECIPIENT_STANZA: &str = "recipient-stanza";
+const CMD_LABELS: &str = "labels";
 const CMD_MSG: &str = "msg";
 const CMD_CONFIRM: &str = "confirm";
 const CMD_REQUEST_PUBLIC: &str = "request-public";
@@ -377,7 +379,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)?;
 
@@ -391,11 +396,13 @@ impl<C: Callbacks> crate::Recipient for RecipientPluginV1<C> {
             for identity in &self.identities {
                 phase.send("add-identity", &[&identity.identity], &[])?;
             }
+            phase.send("extension-labels", &[], &[])?;
             phase.send("wrap-file-key", &[], file_key.expose_secret())
         })?;
 
         // Phase 2: collect either stanzas or errors
         let mut stanzas = vec![];
+        let mut labels = None;
         let mut errors = vec![];
         if let Err(e) = conn.bidir_receive(
             &[
@@ -404,6 +411,7 @@ impl<C: Callbacks> crate::Recipient for RecipientPluginV1<C> {
                 CMD_REQUEST_PUBLIC,
                 CMD_REQUEST_SECRET,
                 CMD_RECIPIENT_STANZA,
+                CMD_LABELS,
                 CMD_ERROR,
             ],
             |mut command, reply| match command.tag.as_str() {
@@ -459,6 +467,34 @@ impl<C: Callbacks> crate::Recipient for RecipientPluginV1<C> {
                     }
                     reply.ok(None)
                 }
+                CMD_LABELS => {
+                    if labels.is_none() {
+                        let labels_count = command.args.len();
+                        let label_set = command.args.into_iter().collect::<HashSet<_>>();
+                        if label_set.len() == labels_count {
+                            labels = Some(label_set);
+                        } else {
+                            errors.push(PluginError::Other {
+                                kind: "internal".to_owned(),
+                                metadata: vec![],
+                                message: format!(
+                                    "{} command must not contain duplicate labels",
+                                    CMD_LABELS
+                                ),
+                            });
+                        }
+                    } else {
+                        errors.push(PluginError::Other {
+                            kind: "internal".to_owned(),
+                            metadata: vec![],
+                            message: format!(
+                                "{} command must not be sent more than once",
+                                CMD_LABELS
+                            ),
+                        });
+                    }
+                    reply.ok(None)
+                }
                 CMD_ERROR => {
                     if command.args.len() == 2 && command.args[0] == "recipient" {
                         let index: usize = command.args[1].parse().unwrap();
@@ -484,7 +520,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.unwrap_or_default())),
             (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,16 +317,18 @@ 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;
 
     use super::{Decryptor, Encryptor};
     use crate::{
         identity::{IdentityFile, IdentityFileEntry},
-        scrypt, x25519, Identity, Recipient,
+        scrypt, x25519, EncryptError, Identity, Recipient,
     };
 
     #[cfg(feature = "async")]
@@ -510,4 +537,50 @@ mod tests {
             .unwrap();
         recipient_async_round_trip(vec![Box::new(pk)], iter::once(&sk as &dyn Identity));
     }
+
+    #[test]
+    fn mixed_recipient_and_passphrase() {
+        let pk: x25519::Recipient = crate::x25519::tests::TEST_PK.parse().unwrap();
+        let passphrase = crate::scrypt::Recipient::new(SecretString::new("passphrase".to_string()));
+
+        let recipients = vec![Box::new(pk) as _, Box::new(passphrase) as _];
+
+        let mut encrypted = vec![];
+        let e = Encryptor::with_recipients(recipients).unwrap();
+        assert!(matches!(
+            e.wrap_output(&mut encrypted),
+            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 rand::{
-use std::time::Duration;
+    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 {
+        let label = Alphanumeric.sample_string(&mut rng, 32);
-            tag: SCRYPT_RECIPIENT_TAG.to_owned(),
+
-            args: vec![encoded_salt, format!("{}", log_n)],
+        Ok((
-            body: encrypted_file_key,
+            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 {
+        Ok((
-            tag: X25519_RECIPIENT_TAG.to_owned(),
+            vec![Stanza {
-            args: vec![encoded_epk],
+                tag: X25519_RECIPIENT_TAG.to_owned(),
-            body: encrypted_file_key,
+                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());