crates/gunnar-crypt/src/wrap.rs
//! The key ring, wrapped with age to every member's USER encryption key
//! (`age1…`, or `age1pq1…` in a quantum-safe repository), and unwrapped with
//! that user key ([`crate::userkey`]).
//!
//! A repository never names an SSH key or a security key. Those are unlock
//! METHODS of a user's encryption key: the SSH key file opens the user key in
//! the CLI (age's SSH recipients, below, under feature `wrap`), a security key
//! opens it in the browser and the CLI, and the user key opens every ring the
//! user is a member of. Adding a member is one more stanza, to their public
//! user key: they need not be present.
//!
//! age does every wrap: an `age1…` key is age's X25519 recipient, an
//! `age1pq1…` key is age's hybrid ML-KEM-768 + X25519 recipient
//! ([`crate::pq`]). One age file holds one stanza per member.
//!
//! **ssh-agent cannot unwrap.** The agent protocol only signs; decryption
//! needs the private scalar, so the CLI reads the key FILE and asks for its
//! passphrase if it has one.
use std::io::{Read, Write};
/// age itself, for callers that hold identities.
pub use age;
use age::armor::{ArmoredReader, ArmoredWriter, Format};
use zeroize::Zeroizing;
use crate::keyring::{Keyring, KeyringError};
pub use crate::members::Level;
use crate::members::{KeyKind, MemberKey, Members};
use crate::policy::{self, Refusal};
/// Why the wrap failed.
#[derive(Debug)]
pub enum WrapError {
/// No member key to wrap to.
NoMembers,
/// A member key age would not take.
BadKey(String, String),
/// age itself failed.
Age(String),
}
impl std::fmt::Display for WrapError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
WrapError::NoMembers => write!(f, "the key ring needs at least one member key"),
WrapError::BadKey(name, why) => write!(f, "{name}'s key cannot be used: {why}"),
WrapError::Age(e) => write!(f, "age: {e}"),
}
}
}
impl std::error::Error for WrapError {}
/// Why the unwrap failed.
#[derive(Debug)]
pub enum UnwrapError {
/// The user key is not a recipient of this key file: its holder is not
/// (or no longer) a member.
NotARecipient,
/// The key file is not a readable age file.
Malformed(String),
/// The payload decrypted, but it is not a key ring.
NotAKeyring(KeyringError),
/// The ring's stanzas do not match the members file (a stanza for a key
/// nobody listed, a missing one, or a classical one in a quantum-safe
/// repository): refused before anything is unwrapped.
Mismatch(Refusal),
}
impl std::fmt::Display for UnwrapError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
UnwrapError::NotARecipient => write!(
f,
"your encryption key is not one this key ring is wrapped to: you are not a member \
of this encrypted repository (or were removed before this key ring)"
),
UnwrapError::Malformed(e) => write!(f, "the key file is not a readable age file: {e}"),
UnwrapError::NotAKeyring(e) => write!(f, "the unwrapped payload is refused: {e}"),
UnwrapError::Mismatch(r) => write!(f, "the key ring is refused: {r}"),
}
}
}
impl std::error::Error for UnwrapError {}
/// What a member is told when an SSH key is offered to a quantum-safe ring.
pub const SSH_IS_NOT_PQ: &str = "SSH keys cannot be quantum-safe recipients: an ed25519 \
key's wrap is X25519 and an RSA key's is RSA-OAEP, and a quantum computer breaks both. \
A quantum-safe repository is wrapped to its members' quantum-safe encryption keys \
(age1pq1…, ML-KEM-768 + X25519), which their SSH keys unlock";
/// The age recipient of one member line: a user's encryption key.
pub fn recipient(key: &MemberKey) -> Result<Box<dyn age::Recipient + Send>, String> {
match key.kind {
KeyKind::Age => key
.key
.trim()
.parse::<age::x25519::Recipient>()
.map(|r| Box::new(r) as Box<dyn age::Recipient + Send>)
.map_err(|e| e.to_string()),
#[cfg(feature = "pq")]
KeyKind::AgePq => key
.key
.parse::<crate::pq::Recipient>()
.map(|r| Box::new(r) as Box<dyn age::Recipient + Send>)
.map_err(str::to_string),
#[cfg(not(feature = "pq"))]
KeyKind::AgePq => {
Err("a quantum-safe key ring needs gunnar-crypt's `pq` feature".to_string())
}
KeyKind::SshEd25519 | KeyKind::SshRsa => Err(
"an SSH key is an unlock method of its owner's encryption key, never a member key"
.to_string(),
),
}
}
/// Wrap `ring` to every key in `members`, with the scheme of its level;
/// returns the armored age file (the content of `.gunnar-crypt/keys`).
pub fn wrap(ring: &Keyring, members: &Members) -> Result<String, WrapError> {
if members.is_empty() {
return Err(WrapError::NoMembers);
}
let mut recipients = Vec::new();
for m in members.entries() {
recipients.push(recipient(m).map_err(|e| WrapError::BadKey(m.name.clone(), e))?);
}
let encryptor = age::Encryptor::with_recipients(
recipients.iter().map(|r| r.as_ref() as &dyn age::Recipient),
)
.map_err(|e| WrapError::Age(e.to_string()))?;
let mut out = Vec::new();
let armor = ArmoredWriter::wrap_output(&mut out, Format::AsciiArmor)
.map_err(|e| WrapError::Age(e.to_string()))?;
let mut w = encryptor
.wrap_output(armor)
.map_err(|e| WrapError::Age(e.to_string()))?;
w.write_all(ring.to_text().as_bytes())
.map_err(|e| WrapError::Age(e.to_string()))?;
w.finish()
.and_then(|a| a.finish())
.map_err(|e| WrapError::Age(e.to_string()))?;
String::from_utf8(out).map_err(|e| WrapError::Age(e.to_string()))
}
/// Unwrap a key file with the given identities. The payload must be a key
/// ring; anything else is refused and dropped (zeroed).
pub fn unwrap(keys_file: &[u8], identities: &[&dyn age::Identity]) -> Result<Keyring, UnwrapError> {
// `new_buffered`, not `new`: age's unbuffered header reader asks for the
// bytes it still needs a few at a time and re-parses the header from its
// start after each read, which is quadratic in the header's size — a
// 500-member quantum-safe ring (a ~1 MB header) never finished
// (MEASURED 2026-10-06, `tests/pq_stress.rs` and `examples/pq_bench.rs`).
// The buffered reader parses what the buffer holds, once.
let decryptor = age::Decryptor::new_buffered(ArmoredReader::new(keys_file))
.map_err(|e| UnwrapError::Malformed(e.to_string()))?;
let mut reader = match decryptor.decrypt(identities.iter().copied()) {
Ok(r) => r,
Err(age::DecryptError::NoMatchingKeys) => return Err(UnwrapError::NotARecipient),
Err(e) => return Err(UnwrapError::Malformed(e.to_string())),
};
let mut buf = Zeroizing::new(Vec::new());
reader
.read_to_end(&mut buf)
.map_err(|e| UnwrapError::Malformed(e.to_string()))?;
let text = std::str::from_utf8(&buf)
.map_err(|_| UnwrapError::NotAKeyring(KeyringError::NotAKeyring))?;
Keyring::parse(text).map_err(UnwrapError::NotAKeyring)
}
/// [`unwrap`], after the ring's stanzas are checked against the members file
/// ([`policy::check_ring`]): one stanza per listed key, the SSH ones by their
/// tags, no type the repository's level does not allow. A ring with a stanza
/// for someone the members file does not name is refused before anything is
/// unwrapped.
pub fn unwrap_checked(
keys_file: &[u8],
members: &str,
identities: &[&dyn age::Identity],
) -> Result<Keyring, UnwrapError> {
policy::check_ring(members, keys_file).map_err(UnwrapError::Mismatch)?;
unwrap(keys_file, identities)
}
/// A post-quantum identity file (`gunnar crypt keygen`, or `age-keygen -pq`)
/// as an age identity.
#[cfg(feature = "pq")]
pub fn pq_identity(text: &str) -> Result<Box<dyn age::Identity + Send + Sync>, IdentityError> {
crate::pq::parse_identity_file(text)
.map(|id| Box::new(id) as Box<dyn age::Identity + Send + Sync>)
.map_err(|e| IdentityError::Read(e.to_string()))
}
/// Why a key file could not be used as an identity.
#[derive(Debug)]
pub enum IdentityError {
/// Could not read or parse the file.
Read(String),
/// A key type age cannot decrypt with (for example a security-key `sk-`
/// key, which only signs).
Unsupported(String),
}
impl std::fmt::Display for IdentityError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
IdentityError::Read(e) => write!(f, "{e}"),
IdentityError::Unsupported(e) => write!(
f,
"{e}. A security-key (sk-) SSH key can only sign and cannot decrypt; \
use an ordinary ed25519 key"
),
}
}
}
impl std::error::Error for IdentityError {}
#[cfg(feature = "wrap")]
pub use ssh::*;
#[cfg(feature = "wrap")]
mod ssh {
use super::*;
/// A passphrase source for an encrypted SSH key file.
pub trait Passphrase: Clone + Send + Sync + 'static {
/// Ask for the passphrase of the key `description` names; `None` gives up.
fn ask(&self, description: &str) -> Option<String>;
}
#[derive(Clone)]
struct Callbacks<P: Passphrase>(P);
impl<P: Passphrase> age::Callbacks for Callbacks<P> {
fn display_message(&self, message: &str) {
eprintln!("{message}");
}
fn confirm(&self, _: &str, _: &str, _: Option<&str>) -> Option<bool> {
None
}
fn request_public_string(&self, _: &str) -> Option<String> {
None
}
fn request_passphrase(&self, description: &str) -> Option<age::secrecy::SecretString> {
self.0
.ask(description)
.map(age::secrecy::SecretString::from)
}
}
/// An SSH private key file as an age identity. An encrypted key asks
/// `passphrase` when it is first needed.
pub fn ssh_identity<P: Passphrase>(
pem: &[u8],
filename: Option<String>,
passphrase: P,
) -> Result<Box<dyn age::Identity>, IdentityError> {
let id = age::ssh::Identity::from_buffer(pem, filename)
.map_err(|e| IdentityError::Read(e.to_string()))?;
if let age::ssh::Identity::Unsupported(u) = &id {
return Err(IdentityError::Unsupported(format!("{u:?}")));
}
Ok(Box::new(id.with_callbacks(Callbacks(passphrase))))
}
/// An SSH private key file as an age identity, decrypted NOW: an encrypted
/// key asks `passphrase` once, here, rather than later in the middle of an
/// unwrap: a passphrase is typed once, at start.
pub fn ssh_identity_unlocked(
pem: &[u8],
passphrase: impl Fn(&str) -> Option<String>,
) -> Result<Box<dyn age::Identity + Send + Sync>, IdentityError> {
let id = age::ssh::Identity::from_buffer(pem, None)
.map_err(|e| IdentityError::Read(e.to_string()))?;
match id {
age::ssh::Identity::Unencrypted(_) => Ok(Box::new(id)),
age::ssh::Identity::Encrypted(enc) => {
let pass = passphrase("Passphrase for the SSH key")
.ok_or_else(|| IdentityError::Read("no passphrase given".into()))?;
let key = enc
.decrypt(age::secrecy::SecretString::from(pass))
.map_err(|_| IdentityError::Read("wrong passphrase".into()))?;
Ok(Box::new(age::ssh::Identity::from(key)))
}
age::ssh::Identity::Unsupported(u) => Err(IdentityError::Unsupported(format!("{u:?}"))),
}
}
/// A passphrase source that never answers: for key files without one.
#[derive(Clone, Copy, Debug)]
pub struct NoPassphrase;
impl Passphrase for NoPassphrase {
fn ask(&self, _: &str) -> Option<String> {
None
}
}
}