use std::cmp::Reverse;
use std::fmt;
use std::io::Read;
use std::str::FromStr;
use age::x25519::{Identity, Recipient};
use anyhow::{Context, Result, anyhow, ensure};
use ed25519_dalek::VerifyingKey;
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use sha2::{Digest, Sha256};
use zeroize::Zeroizing;
use super::{KeyGuard, hex, unhex};
const KEY_ID_DOMAIN: &[u8] = b"second-brain identity key id v1";
const TAG_DOMAIN: &[u8] = b"second-brain identity tag v1";
const ENVELOPE_DOMAIN: &[u8] = b"second-brain K_id envelope v1";
const KEY_LEN: usize = 32;
pub struct IdentityKey(KeyGuard<[u8; KEY_LEN]>);
impl IdentityKey {
pub fn generate() -> Result<Self> {
Ok(Self(
KeyGuard::<[u8; KEY_LEN]>::random().context("generating an identity key")?,
))
}
pub fn from_bytes(bytes: KeyGuard<[u8; KEY_LEN]>) -> Self {
Self(bytes)
}
pub fn expose(&self) -> &[u8; KEY_LEN] {
self.0.expose()
}
pub fn key_id(&self) -> KeyId {
let digest = Sha256::new()
.chain_update(KEY_ID_DOMAIN)
.chain_update(self.expose())
.finalize();
let mut id = [0u8; 8];
id.copy_from_slice(&digest[..8]);
KeyId(id)
}
}
impl fmt::Debug for IdentityKey {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("IdentityKey")
.field("key_id", &self.key_id())
.finish_non_exhaustive()
}
}
#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct KeyId(pub [u8; 8]);
impl fmt::Display for KeyId {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&hex(&self.0))
}
}
impl fmt::Debug for KeyId {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "KeyId({self})")
}
}
impl FromStr for KeyId {
type Err = anyhow::Error;
fn from_str(s: &str) -> Result<Self> {
unhex(s)
.map(KeyId)
.ok_or_else(|| anyhow!("a key id is 16 hex characters"))
}
}
impl Serialize for KeyId {
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.collect_str(self)
}
}
impl<'de> Deserialize<'de> for KeyId {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let text = String::deserialize(deserializer)?;
text.parse().map_err(serde::de::Error::custom)
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct Epoch {
pub number: u32,
pub key_id: KeyId,
}
pub fn newest_epoch<'a>(epochs: impl IntoIterator<Item = &'a Epoch>) -> Option<Epoch> {
epochs
.into_iter()
.max_by_key(|e| (e.number, Reverse(e.key_id)))
.copied()
}
#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct IdentityTag(String);
impl IdentityTag {
pub fn migrated(epoch0: &KeyId) -> Self {
Self(format!("m-{epoch0}"))
}
pub fn founded(first: &KeyId, founder: &VerifyingKey) -> Self {
let digest = Sha256::new()
.chain_update(TAG_DOMAIN)
.chain_update(first.0)
.chain_update(founder.as_bytes())
.finalize();
Self(format!("f-{}", hex(&digest[..16])))
}
pub fn as_str(&self) -> &str {
&self.0
}
}
impl From<String> for IdentityTag {
fn from(tag: String) -> Self {
Self(tag)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct Envelope {
pub identity_tag: IdentityTag,
pub epoch: Epoch,
pub recipient: String,
pub machine_id: Option<String>,
pub ciphertext: Vec<u8>,
}
pub fn wrap(
key: &IdentityKey,
epoch_number: u32,
tag: &IdentityTag,
recipient: &Recipient,
machine_id: Option<String>,
) -> Result<Envelope> {
let plaintext = envelope_plaintext(key, epoch_number, tag)?;
let ciphertext = age::encrypt(recipient, plaintext.as_slice())
.map_err(|e| anyhow!("sealing the identity key envelope: {e}"))?;
Ok(Envelope {
identity_tag: tag.clone(),
epoch: Epoch {
number: epoch_number,
key_id: key.key_id(),
},
recipient: recipient.to_string(),
machine_id,
ciphertext,
})
}
impl Envelope {
pub fn open(&self, identity: &Identity) -> Result<IdentityKey> {
let opening = || {
format!(
"opening the identity key envelope for epoch {}",
self.epoch.number
)
};
let decryptor = age::Decryptor::new_buffered(self.ciphertext.as_slice())
.map_err(|e| anyhow!("{}: {e}", opening()))?;
let mut reader = decryptor
.decrypt(std::iter::once(identity as &dyn age::Identity))
.map_err(|e| anyhow!("{}: {e}", opening()))?;
let expected = plaintext_len(&self.identity_tag);
let mut plaintext = Zeroizing::new(vec![0u8; expected + 1]);
let mut filled = 0;
while filled < plaintext.len() {
let read = reader
.read(&mut plaintext[filled..])
.with_context(opening)?;
if read == 0 {
break;
}
filled += read;
}
let key = parse_plaintext(&plaintext[..filled], &self.identity_tag, self.epoch.number)?;
ensure!(
key.key_id() == self.epoch.key_id,
"the key in the envelope for epoch {} does not have key id {}",
self.epoch.number,
self.epoch.key_id
);
Ok(key)
}
}
fn envelope_plaintext(
key: &IdentityKey,
epoch_number: u32,
tag_label: &IdentityTag,
) -> Result<Zeroizing<Vec<u8>>> {
let tag = tag_label.as_str().as_bytes();
let tag_len = u32::try_from(tag.len()).context("identity tag is too long")?;
let mut out = Zeroizing::new(Vec::with_capacity(plaintext_len(tag_label)));
out.extend_from_slice(ENVELOPE_DOMAIN);
out.extend_from_slice(&tag_len.to_be_bytes());
out.extend_from_slice(tag);
out.extend_from_slice(&epoch_number.to_be_bytes());
out.extend_from_slice(key.expose());
Ok(out)
}
fn plaintext_len(tag: &IdentityTag) -> usize {
ENVELOPE_DOMAIN.len() + 4 + tag.as_str().len() + 4 + KEY_LEN
}
fn parse_plaintext(plaintext: &[u8], tag: &IdentityTag, epoch_number: u32) -> Result<IdentityKey> {
let rest = plaintext
.strip_prefix(ENVELOPE_DOMAIN)
.context("envelope plaintext lacks its domain tag")?;
let (tag_len, rest) = rest
.split_first_chunk::<4>()
.context("envelope plaintext is truncated")?;
let tag_len =
usize::try_from(u32::from_be_bytes(*tag_len)).context("envelope tag length overflows")?;
ensure!(
Some(rest.len()) == tag_len.checked_add(4 + KEY_LEN),
"envelope plaintext has the wrong length"
);
let (sealed_tag, rest) = rest.split_at(tag_len);
ensure!(
sealed_tag == tag.as_str().as_bytes(),
"envelope was sealed for a different identity than its label {}",
tag.as_str()
);
let (sealed_number, key_bytes) = rest
.split_first_chunk::<4>()
.context("envelope plaintext is truncated")?;
ensure!(
u32::from_be_bytes(*sealed_number) == epoch_number,
"envelope was sealed for a different epoch than its label {epoch_number}"
);
let mut guard = KeyGuard::new([0u8; KEY_LEN]);
guard.expose_mut().copy_from_slice(key_bytes);
Ok(IdentityKey(guard))
}
#[cfg(test)]
mod tests {
use ed25519_dalek::SigningKey;
use super::*;
fn key(byte: u8) -> IdentityKey {
IdentityKey::from_bytes(KeyGuard::new([byte; KEY_LEN]))
}
fn tag() -> IdentityTag {
IdentityTag::migrated(&key(9).key_id())
}
fn founder(byte: u8) -> VerifyingKey {
SigningKey::from_bytes(&[byte; 32]).verifying_key()
}
#[test]
fn each_device_opens_only_its_own_envelope() {
let k = key(1);
let alpha = Identity::generate();
let beta = Identity::generate();
let for_alpha = wrap(&k, 1, &tag(), &alpha.to_public(), Some("a".into())).unwrap();
let for_beta = wrap(&k, 1, &tag(), &beta.to_public(), None).unwrap();
assert!(for_alpha.open(&beta).is_err());
assert!(for_beta.open(&alpha).is_err());
assert_eq!(for_alpha.open(&alpha).unwrap().expose(), k.expose());
assert_eq!(for_beta.open(&beta).unwrap().expose(), k.expose());
}
#[test]
fn opening_returns_the_wrapped_key_and_labels() {
let k = key(2);
let device = Identity::generate();
let envelope = wrap(&k, 3, &tag(), &device.to_public(), Some("m1".into())).unwrap();
assert_eq!(envelope.identity_tag, tag());
assert_eq!(envelope.epoch.number, 3);
assert_eq!(envelope.epoch.key_id, k.key_id());
assert_eq!(envelope.recipient, device.to_public().to_string());
assert_eq!(envelope.machine_id.as_deref(), Some("m1"));
let opened = envelope.open(&device).unwrap();
assert_eq!(opened.expose(), k.expose());
assert_eq!(opened.key_id(), k.key_id());
}
#[test]
fn a_relabelled_envelope_does_not_open() {
let k = key(3);
let device = Identity::generate();
let envelope = wrap(&k, 2, &tag(), &device.to_public(), None).unwrap();
let mut other_number = envelope.clone();
other_number.epoch.number = 3;
assert!(other_number.open(&device).is_err());
let mut other_tag = envelope.clone();
other_tag.identity_tag = IdentityTag::from("m-0000000000000000".to_string());
assert!(other_tag.open(&device).is_err());
let mut other_key_id = envelope.clone();
other_key_id.epoch.key_id = key(4).key_id();
assert!(other_key_id.open(&device).is_err());
assert!(envelope.open(&device).is_ok());
}
#[test]
fn plaintext_parsing_is_exact() {
let k = key(5);
let plaintext = envelope_plaintext(&k, 7, &tag()).unwrap();
assert_eq!(
parse_plaintext(&plaintext, &tag(), 7).unwrap().expose(),
k.expose()
);
let mut longer = plaintext.to_vec();
longer.push(0);
assert!(parse_plaintext(&longer, &tag(), 7).is_err());
assert!(parse_plaintext(&plaintext[..plaintext.len() - 1], &tag(), 7).is_err());
let mut other_domain = plaintext.to_vec();
other_domain[0] ^= 1;
assert!(parse_plaintext(&other_domain, &tag(), 7).is_err());
}
#[test]
fn key_ids_are_stable_and_distinct() {
assert_eq!(key(1).key_id(), key(1).key_id());
assert_ne!(key(1).key_id(), key(2).key_id());
let generated = IdentityKey::generate().unwrap();
assert_ne!(generated.key_id(), key(0).key_id());
}
#[test]
fn key_id_hex_round_trips() {
let id = key(6).key_id();
let text = id.to_string();
assert_eq!(text.len(), 16);
assert!(
text.bytes()
.all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
);
assert_eq!(text.parse::<KeyId>().unwrap(), id);
assert_eq!(text.to_uppercase().parse::<KeyId>().unwrap(), id);
let json = serde_json::to_string(&id).unwrap();
assert_eq!(json, format!("\"{text}\""));
assert_eq!(serde_json::from_str::<KeyId>(&json).unwrap(), id);
for bad in [
"",
"0123456789abcde",
"0123456789abcdef0",
"0123456789abcdeg",
"+123456789abcdef",
] {
assert!(bad.parse::<KeyId>().is_err(), "{bad:?} parsed");
}
}
#[test]
fn tags_are_deterministic_and_distinct() {
let first = key(7).key_id();
let migrated = IdentityTag::migrated(&first);
assert_eq!(migrated, IdentityTag::migrated(&first));
assert_eq!(migrated.as_str(), format!("m-{first}"));
let founded = IdentityTag::founded(&first, &founder(1));
assert_eq!(founded, IdentityTag::founded(&first, &founder(1)));
assert!(founded.as_str().starts_with("f-"));
assert_eq!(founded.as_str().len(), 2 + 32);
assert_ne!(founded, migrated);
assert_ne!(founded, IdentityTag::founded(&first, &founder(2)));
assert_ne!(founded, IdentityTag::founded(&key(8).key_id(), &founder(1)));
let json = serde_json::to_string(&founded).unwrap();
assert_eq!(json, format!("\"{}\"", founded.as_str()));
assert_eq!(serde_json::from_str::<IdentityTag>(&json).unwrap(), founded);
}
#[test]
fn envelope_serde_round_trips() {
let device = Identity::generate();
let envelope = wrap(&key(1), 4, &tag(), &device.to_public(), None).unwrap();
let json = serde_json::to_string(&envelope).unwrap();
let back: Envelope = serde_json::from_str(&json).unwrap();
assert_eq!(back, envelope);
assert_eq!(back.open(&device).unwrap().expose(), key(1).expose());
}
#[test]
fn debug_output_hides_the_key() {
let shown = format!("{:?}", key(0xab));
assert!(!shown.contains("171"), "{shown}");
assert!(!shown.to_lowercase().contains("abab"), "{shown}");
assert!(shown.contains(&key(0xab).key_id().to_string()));
}
}