plugins: Extend recipient-v1 state machine with add-identities message

This enables plugins to wrap file keys to identities, for example when
the plugin is built around a symmetric primitive (since we do not want
the recipients encoding to ever contain secrets).

age-core/src/plugin.rs

@@ -23,9 +23,10 @@ const RESPONSE_UNSUPPORTED: &str = "unsupported";
 ///   should explicitly handle.
 pub type Result<T, E> = io::Result<std::result::Result<T, E>>;
 
-type UnidirResult<A, B, E> = io::Result<(
+type UnidirResult<A, B, C, 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>>>,
 )>;
 
 /// A connection to a plugin binary.
@@ -161,19 +162,23 @@ impl<R: Read, W: Write> Connection<R, W> {
     ///
     /// # Arguments
     ///
-    /// `command_a` and `command_b` are the known commands that are expected to be
-    /// received. All other received commands (including grease) will be ignored.
-    pub fn unidir_receive<A, B, E, F, G>(
+    /// `command_a`, `command_b`, and (optionally) `command_c` are the known commands that
+    /// are expected to be received. All other received commands (including grease) will
+    /// be ignored.
+    pub fn unidir_receive<A, B, C, E, F, G, H>(
         &mut self,
         command_a: (&str, F),
         command_b: (&str, G),
-    ) -> UnidirResult<A, B, E>
+        command_c: (Option<&str>, H),
+    ) -> UnidirResult<A, B, C, 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>,
     {
         let mut res_a = Ok(vec![]);
         let mut res_b = Ok(vec![]);
+        let mut res_c = Ok(vec![]);
 
         for stanza in iter::repeat_with(|| self.receive()).take_while(|res| match res {
             Ok(stanza) => stanza.tag != COMMAND_DONE,
@@ -203,10 +208,14 @@ 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 {
+                if stanza.tag.as_str() == tag {
+                    validate(command_c.1(stanza), &mut res_c)
+                }
             }
         }
 
-        Ok((res_a, res_b))
+        Ok((res_a, res_b, command_c.0.map(|_| res_c)))
     }
 
     /// Runs a bidirectional phase as the controller.
@@ -420,7 +429,11 @@ mod tests {
             .unidir_send(|mut phase| phase.send("test", &["foo"], b"bar"))
             .unwrap();
         let stanza = plugin_conn
-            .unidir_receive::<_, (), _, _, _>(("test", |s| Ok(s)), ("other", |_| Err(())))
+            .unidir_receive::<_, (), (), _, _, _, _>(
+                ("test", |s| Ok(s)),
+                ("other", |_| Err(())),
+                (None, |_| Ok(())),
+            )
             .unwrap();
         assert_eq!(
             stanza,
@@ -430,7 +443,8 @@ mod tests {
                     args: vec!["foo".to_owned()],
                     body: b"bar"[..].to_owned()
                 }]),
-                Ok(vec![])
+                Ok(vec![]),
+                None
             )
         );
     }

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

@@ -42,6 +42,31 @@ impl RecipientPluginV1 for RecipientPlugin {
         }
     }
 
+    fn add_identities<'a, I: Iterator<Item = &'a str>>(
+        &mut self,
+        identities: I,
+    ) -> Result<(), Vec<recipient::Error>> {
+        let errors = identities
+            .enumerate()
+            .filter_map(|(index, identity)| {
+                if identity.contains(&PLUGIN_NAME.to_uppercase()) {
+                    // A real plugin would store the identity.
+                    None
+                } else {
+                    Some(recipient::Error::Identity {
+                        index,
+                        message: "invalid identity".to_owned(),
+                    })
+                }
+            })
+            .collect::<Vec<_>>();
+        if errors.is_empty() {
+            Ok(())
+        } else {
+            Err(errors)
+        }
+    }
+
     fn wrap_file_key(
         &mut self,
         file_key: &FileKey,

age-plugin/src/identity.rs

@@ -161,7 +161,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| {
                 if s.args.len() == 1 && s.body.is_empty() {
                     Ok(s)
@@ -196,6 +196,7 @@ pub(crate) fn run_v1<P: IdentityPluginV1>(mut plugin: P) -> io::Result<()> {
                     })
                 }
             }),
+            (None, |_| Ok(())),
         )?;
 
         let stanzas = stanzas.and_then(|recipient_stanzas| {

age-plugin/src/lib.rs

@@ -90,6 +90,13 @@
 //!         todo!()
 //!     }
 //!
+//!     fn add_identities<'a, I: Iterator<Item = &'a str>>(
+//!         &mut self,
+//!         identities: I,
+//!     ) -> Result<(), Vec<recipient::Error>> {
+//!         todo!()
+//!     }
+//!
 //!     fn wrap_file_key(
 //!         &mut self,
 //!         file_key: &FileKey,

age-plugin/src/recipient.rs

@@ -11,6 +11,7 @@ use std::io;
 use crate::Callbacks;
 
 const ADD_RECIPIENT: &str = "add-recipient";
+const ADD_IDENTITY: &str = "add-identity";
 const WRAP_FILE_KEY: &str = "wrap-file-key";
 const RECIPIENT_STANZA: &str = "recipient-stanza";
 
@@ -27,10 +28,22 @@ pub trait RecipientPluginV1 {
         recipients: I,
     ) -> Result<(), Vec<Error>>;
 
-    /// Wraps `file_key` to all recipients previously added via `add_recipients`.
+    /// Stores identities that the user would like to encrypt age files to.
     ///
-    /// Returns either one stanza per recipient, or any errors if one or more recipients
-    /// could not be wrapped to.
+    /// Each identity string is Bech32-encoded with an HRP of `AGE-PLUGIN-NAME-` where
+    /// `NAME` is the name of the plugin that resolved to this binary.
+    ///
+    /// Returns a list of errors if any of the identities are unknown or invalid.
+    fn add_identities<'a, I: Iterator<Item = &'a str>>(
+        &mut self,
+        identities: I,
+    ) -> Result<(), Vec<Error>>;
+
+    /// Wraps `file_key` to all recipients and identities previously added via
+    /// `add_recipients` and `add_identities`.
+    ///
+    /// Returns either one stanza per recipient and identity, or any errors if one or more
+    /// recipients or identities could not be wrapped to.
     ///
     /// `callbacks` can be used to interact with the user, to have them take some physical
     /// action or request a secret value.
@@ -83,6 +96,13 @@ pub enum Error {
         /// The error message.
         message: String,
     },
+    /// An error caused by a specific identity.
+    Identity {
+        /// The index of the identity.
+        index: usize,
+        /// The error message.
+        message: String,
+    },
     /// A general error that occured inside the state machine.
     Internal {
         /// The error message.
@@ -94,6 +114,7 @@ impl Error {
     fn kind(&self) -> &str {
         match self {
             Error::Recipient { .. } => "recipient",
+            Error::Identity { .. } => "identity",
             Error::Internal { .. } => "internal",
         }
     }
@@ -101,13 +122,16 @@ impl Error {
     fn message(&self) -> &str {
         match self {
             Error::Recipient { message, .. } => &message,
+            Error::Identity { message, .. } => &message,
             Error::Internal { message } => &message,
         }
     }
 
     fn send<R: io::Read, W: io::Write>(self, phase: &mut BidirSend<R, W>) -> io::Result<()> {
         let index = match self {
-            Error::Recipient { index, .. } => Some(index.to_string()),
+            Error::Recipient { index, .. } | Error::Identity { index, .. } => {
+                Some(index.to_string())
+            }
             Error::Internal { .. } => None,
         };
 
@@ -129,8 +153,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, file_keys) = {
-        let (recipients, file_keys) = conn.unidir_receive(
+    let ((recipients, identities), file_keys) = {
+        let (recipients, identities, file_keys) = conn.unidir_receive(
             (ADD_RECIPIENT, |s| {
                 if s.args.len() == 1 && s.body.is_empty() {
                     Ok(s)
@@ -143,7 +167,19 @@ pub(crate) fn run_v1<P: RecipientPluginV1>(mut plugin: P) -> io::Result<()> {
                     })
                 }
             }),
-            (WRAP_FILE_KEY, |s| {
+            (ADD_IDENTITY, |s| {
+                if s.args.len() == 1 && s.body.is_empty() {
+                    Ok(s)
+                } else {
+                    Err(Error::Internal {
+                        message: format!(
+                            "{} command must have exactly one metadata argument and no data",
+                            ADD_IDENTITY
+                        ),
+                    })
+                }
+            }),
+            (Some(WRAP_FILE_KEY), |s| {
                 // TODO: Should we ignore file key commands with unexpected metadata args?
                 TryInto::<[u8; FILE_KEY_BYTES]>::try_into(&s.body[..])
                     .map_err(|_| Error::Internal {
@@ -153,13 +189,19 @@ pub(crate) fn run_v1<P: RecipientPluginV1>(mut plugin: P) -> io::Result<()> {
             }),
         )?;
         (
-            match recipients {
-                Ok(r) if r.is_empty() => Err(vec![Error::Internal {
-                    message: format!("Need at least one {} command", ADD_RECIPIENT),
-                }]),
+            match (recipients, identities) {
+                (Ok(r), Ok(i)) if r.is_empty() && i.is_empty() => (
+                    Err(vec![Error::Internal {
+                        message: format!(
+                            "Need at least one {} or {} command",
+                            ADD_RECIPIENT, ADD_IDENTITY
+                        ),
+                    }]),
+                    Err(vec![]),
+                ),
                 r => r,
             },
-            match file_keys {
+            match file_keys.unwrap() {
                 Ok(f) if f.is_empty() => Err(vec![Error::Internal {
                     message: format!("Need at least one {} command", WRAP_FILE_KEY),
                 }]),
@@ -170,16 +212,16 @@ pub(crate) fn run_v1<P: RecipientPluginV1>(mut plugin: P) -> io::Result<()> {
 
     // Phase 2: wrap the file keys or return errors
     conn.bidir_send(|mut phase| {
-        let (recipients, file_keys) = match (recipients, file_keys) {
-            (Ok(recipients), Ok(file_keys)) => (recipients, file_keys),
-            (Err(errors1), Err(errors2)) => {
-                for error in errors1.into_iter().chain(errors2.into_iter()) {
-                    error.send(&mut phase)?;
-                }
-                return Ok(());
-            }
-            (Err(errors), _) | (_, Err(errors)) => {
-                for error in errors {
+        let (recipients, identities, file_keys) = match (recipients, identities, file_keys) {
+            (Ok(recipients), Ok(identities), Ok(file_keys)) => (recipients, identities, file_keys),
+            (recipients, identities, file_keys) => {
+                for error in recipients
+                    .err()
+                    .into_iter()
+                    .chain(identities.err())
+                    .chain(file_keys.err())
+                    .flatten()
+                {
                     error.send(&mut phase)?;
                 }
                 return Ok(());
@@ -192,6 +234,12 @@ pub(crate) fn run_v1<P: RecipientPluginV1>(mut plugin: P) -> io::Result<()> {
             for error in errors {
                 error.send(&mut phase)?;
             }
+        } else if let Err(errors) =
+            plugin.add_identities(identities.iter().map(|s| s.args.first().unwrap().as_str()))
+        {
+            for error in errors {
+                error.send(&mut phase)?;
+            }
         } else {
             match file_keys
                 .into_iter()
@@ -200,10 +248,10 @@ pub(crate) fn run_v1<P: RecipientPluginV1>(mut plugin: P) -> io::Result<()> {
             {
                 Ok(files) => {
                     for (file_index, stanzas) in files.into_iter().enumerate() {
-                        // The plugin MUST generate an error if one or more
-                        // recipients cannot be wrapped to. And it's a programming
-                        // error to return more stanzas than recipients.
-                        assert_eq!(stanzas.len(), recipients.len());
+                        // The plugin MUST generate an error if one or more recipients or
+                        // identities cannot be wrapped to. And it's a programming error
+                        // to return more stanzas than recipients and identities.
+                        assert_eq!(stanzas.len(), recipients.len() + identities.len());
 
                         for stanza in stanzas {
                             phase

age/src/plugin.rs

@@ -160,19 +160,21 @@ impl Plugin {
 pub struct RecipientPluginV1<C: Callbacks> {
     plugin: Plugin,
     recipients: Vec<Recipient>,
+    identities: Vec<Identity>,
     callbacks: C,
 }
 
 impl<C: Callbacks> RecipientPluginV1<C> {
-    /// Creates an age plugin from a plugin name and a list of recipients.
+    /// Creates an age plugin from a plugin name and lists of recipients and identities.
     ///
-    /// The list of recipients will be filtered by the plugin name; recipients that don't
-    /// match will be ignored.
+    /// The lists of recipients and identities will be filtered by the plugin name;
+    /// recipients that don't match will be ignored.
     ///
     /// Returns an error if the plugin's binary cannot be found in `$PATH`.
     pub fn new(
         plugin_name: &str,
         recipients: &[Recipient],
+        identities: &[Identity],
         callbacks: C,
     ) -> Result<Self, EncryptError> {
         Plugin::new(plugin_name)
@@ -184,6 +186,11 @@ impl<C: Callbacks> RecipientPluginV1<C> {
                     .filter(|r| r.name == plugin_name)
                     .cloned()
                     .collect(),
+                identities: identities
+                    .iter()
+                    .filter(|r| r.name == plugin_name)
+                    .cloned()
+                    .collect(),
                 callbacks,
             })
     }
@@ -194,11 +201,14 @@ impl<C: Callbacks> crate::Recipient for RecipientPluginV1<C> {
         // Open connection
         let mut conn = self.plugin.connect(RECIPIENT_V1)?;
 
-        // Phase 1: add recipients, and file key to wrap
+        // Phase 1: add recipients, identities, and file key to wrap
         conn.unidir_send(|mut phase| {
             for recipient in &self.recipients {
                 phase.send("add-recipient", &[&recipient.recipient], &[])?;
             }
+            for identity in &self.identities {
+                phase.send("add-identity", &[&identity.identity], &[])?;
+            }
             phase.send("wrap-file-key", &[], file_key.expose_secret())
         })?;
 
@@ -257,6 +267,12 @@ impl<C: Callbacks> crate::Recipient for RecipientPluginV1<C> {
                             recipient: self.recipients[index].recipient.clone(),
                             message: String::from_utf8_lossy(&command.body).to_string(),
                         });
+                    } else if command.args.len() == 2 && command.args[0] == "identity" {
+                        let index: usize = command.args[1].parse().unwrap();
+                        errors.push(PluginError::Identity {
+                            binary_name: binary_name(&self.identities[index].name),
+                            message: String::from_utf8_lossy(&command.body).to_string(),
+                        });
                     } else {
                         errors.push(PluginError::from(command));
                     }

rage/src/bin/rage/main.rs

@@ -125,6 +125,7 @@ fn read_recipients(
         recipients.push(Box::new(plugin::RecipientPluginV1::new(
             plugin_name,
             &plugin_recipients,
+            &[],
             UiCallbacks,
         )?))
     }