From d7a91adc877090a9a8d2efd006643aafa71d248d Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Sun, 10 Jan 2021 15:47:43 +0000 Subject: [PATCH] Plugin docs and changelog entries --- age-plugin/CHANGELOG.md | 13 ++++ age-plugin/README.md | 148 +++++++++++++++++++++++++++++++++++++++- age-plugin/README.tpl | 20 ++++++ age-plugin/src/lib.rs | 2 +- age/CHANGELOG.md | 9 +++ rage/CHANGELOG.md | 4 ++ 6 files changed, 192 insertions(+), 4 deletions(-) create mode 100644 age-plugin/CHANGELOG.md create mode 100644 age-plugin/README.tpl diff --git a/age-plugin/CHANGELOG.md b/age-plugin/CHANGELOG.md new file mode 100644 index 0000000..1d74bc1 --- /dev/null +++ b/age-plugin/CHANGELOG.md @@ -0,0 +1,13 @@ +# Changelog +All notable changes to the age crate will be documented in this file. Changes +to the [age-core crate](../age-core/CHANGELOG.md) also apply to the age-plugin +crate, and are not duplicated here. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to Rust's notion of +[Semantic Versioning](https://semver.org/spec/v2.0.0.html). All versions prior +to 1.0.0 are beta releases. + +## [Unreleased] + +Initial beta release! diff --git a/age-plugin/README.md b/age-plugin/README.md index 0a846fc..7a366e3 100644 --- a/age-plugin/README.md +++ b/age-plugin/README.md @@ -2,9 +2,151 @@ This crate provides an API for building age plugins. -Currently in unstable alpha; the plugin architecture has been designed, but -expect APIs to be altered and bugs to be fixed as we iterate. Try using it and -[let me know how it goes!](https://github.com/str4d/rage/issues/new/choose) +## Introduction + +The [age file encryption format] follows the "one well-oiled joint" design philosophy. +The mechanism for extensibility (within a particular format version) is the recipient +stanzas within the age header: file keys can be wrapped in any number of ways, and age +clients are required to ignore stanzas that they do not understand. + +The core APIs that exercise this mechanism are: +- A recipient that wraps a file key and returns a stanza. +- An identity that unwraps a stanza and returns a file key. + +The age plugin system provides a mechanism for exposing these core APIs across process +boundaries. It has two main components: + +- A map from recipients and identities to plugin binaries. +- State machines for wrapping and unwrapping file keys. + +With this composable design, you can implement a recipient or identity that you might +use directly with the [`age`] library crate, and also deploy it as a plugin binary for +use with clients like [`rage`]. + +[age file encryption format]: https://age-encryption.org/v1 +[`age`]: https://crates.io/crates/age +[`rage`]: https://crates.io/crates/rage + +## Mapping recipients and identities to plugin binaries + +age plugins are identified by an arbitrary case-insensitive string `NAME`. This string +is used in three places: + +- Plugin-compatible recipients are encoded using Bech32 with the HRP `age1name` + (lowercase). +- Plugin-compatible identities are encoded using Bech32 with the HRP + `AGE-PLUGIN-NAME-` (uppercase). +- Plugin binaries (to be started by age clients) are named `age-plugin-name`. + +Users interact with age clients by providing either recipients for file encryption, or +identities for file decryption. When a plugin recipient or identity is provided, the +age client searches the `PATH` for a binary with the corresponding plugin name. + +Recipient stanza types are not required to be correlated to specific plugin names. +When decrypting, age clients will pass all recipient stanzas to every connected +plugin. Plugins MUST ignore stanzas that they do not know about. + +A plugin binary may handle multiple recipient or identity types by being present in +the `PATH` under multiple names. This can be implemented with symlinks or aliases to +the canonical binary. + +Multiple plugin binaries can support the same recipient and identity types; the first +binary found in the `PATH` will be used by age clients. Some Unix OSs support +"alternatives", which plugin binaries should leverage if they provide support for a +common recipient or identity type. + +Note that the identity specified by a user doesn't need to point to a specific +decryption key, or indeed contain any key material at all. It only needs to contain +sufficient information for the plugin to locate the necessary key material. + +### Standard age keys + +A plugin MAY support decrypting files encrypted to native age recipients, by including +support for the `x25519` recipient stanza. Such plugins will pick their own name, and +users will use identity files containing identities that specify that plugin name. + +## Example plugin binary + +The following example uses `gumdrop` to parse CLI arguments, but any argument parsing +logic will work as long as it can detect the `--age-plugin=STATE_MACHINE` flag. + +```rust +use age_core::format::{FileKey, Stanza}; +use age_plugin::{ + identity::{self, Callbacks, IdentityPluginV1}, + print_new_identity, + recipient::{self, RecipientPluginV1}, + run_state_machine, +}; +use gumdrop::Options; +use std::collections::HashMap; +use std::io; + +struct RecipientPlugin; + +impl RecipientPluginV1 for RecipientPlugin { + fn add_recipients<'a, I: Iterator>( + &mut self, + recipients: I, + ) -> Result<(), Vec> { + todo!() + } + + fn wrap_file_key( + &mut self, + file_key: &FileKey, + ) -> Result, Vec> { + todo!() + } +} + +struct IdentityPlugin; + +impl IdentityPluginV1 for IdentityPlugin { + fn add_identities<'a, I: Iterator>( + &mut self, + identities: I, + ) -> Result<(), Vec> { + todo!() + } + + fn unwrap_file_keys( + &mut self, + files: Vec>, + mut callbacks: impl Callbacks, + ) -> io::Result>>> { + todo!() + } +} + +#[derive(Debug, Options)] +struct PluginOptions { + #[options(help = "print help message")] + help: bool, + + #[options(help = "run the given age plugin state machine", no_short)] + age_plugin: Option, +} + +fn main() -> io::Result<()> { + let opts = PluginOptions::parse_args_default_or_exit(); + + if let Some(state_machine) = opts.age_plugin { + // The plugin was started by an age client; run the state machine. + run_state_machine( + &state_machine, + || RecipientPlugin, + || IdentityPlugin, + )?; + return Ok(()); + } + + // Here you can assume the binary is being run directly by a user, + // and perform administrative tasks like generating keys. + + Ok(()) +} +``` ## License diff --git a/age-plugin/README.tpl b/age-plugin/README.tpl new file mode 100644 index 0000000..41727f4 --- /dev/null +++ b/age-plugin/README.tpl @@ -0,0 +1,20 @@ +# age-plugin Rust library + +{{readme}} + +## License + +Licensed under either of + + * Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or + http://www.apache.org/licenses/LICENSE-2.0) + * MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally +submitted for inclusion in the work by you, as defined in the Apache-2.0 +license, shall be dual licensed as above, without any additional terms or +conditions. diff --git a/age-plugin/src/lib.rs b/age-plugin/src/lib.rs index 5b6a20b..e1f3417 100644 --- a/age-plugin/src/lib.rs +++ b/age-plugin/src/lib.rs @@ -1,4 +1,4 @@ -//! This is a helper crate for implementing age plugins. +//! This crate provides an API for building age plugins. //! //! # Introduction //! diff --git a/age/CHANGELOG.md b/age/CHANGELOG.md index b863e28..ccad342 100644 --- a/age/CHANGELOG.md +++ b/age/CHANGELOG.md @@ -9,6 +9,15 @@ and this project adheres to Rust's notion of to 1.0.0 are beta releases. ## [Unreleased] +### Added +- Plugin support, enabled by the `plugin` feature flag: + - `age::plugin::{Identity, Recipient}` structs for parsing plugin recipients + and identities from strings. + - `age::plugin::RecipientPluginV1`, which implements `age::Recipient` and runs + the V1 recipient plugin protocol. + - `age::plugin::IdentityPluginV1`, which implements `age::Identity` and runs + the V1 identity plugin protocol. + ### Changed - Files encrypted with this version of `age` might not decrypt with previous beta versions, due to changes in how stanza bodies are canonically encoded. diff --git a/rage/CHANGELOG.md b/rage/CHANGELOG.md index ce34df6..95fee50 100644 --- a/rage/CHANGELOG.md +++ b/rage/CHANGELOG.md @@ -10,6 +10,10 @@ to 1.0.0 are beta releases. ## [Unreleased] ### Added +- Plugin support! + - The new [`age-plugin`](https://crates.io/crates/age-plugin) crate provides + a Rust API for building age plugins. + - See https://hackmd.io/@str4d/age-plugin-spec for the beta specification. - The `-R/--recipients-file` flag, which accepts a path to a file containing age recipients, one per line (ignoring "#" prefixed comments and empty lines).