use super::{AuditEvent, AuditIntegrity};
use hmac::{Hmac, KeyInit, Mac};
use sha2::Sha256;
use std::sync::Mutex;
type HmacSha256 = Hmac<Sha256>;
pub const MAC_FIELD: &str = "mac";
pub const CHAIN_INDEX_FIELD: &str = "chain_index";
const GENESIS: &str = "ash-log:genesis:v1";
pub const KEY_ID_FIELD: &str = "key_id";
pub const WRITER_FIELD: &str = "writer";
fn to_hex(bytes: &[u8]) -> String {
use std::fmt::Write as _;
bytes.iter().fold(String::new(), |mut acc, b| {
let _ = write!(acc, "{b:02x}");
acc
})
}
fn canonicalize(event: &AuditEvent) -> Option<Vec<u8>> {
let mut value = serde_json::to_value(event).ok()?;
if let Some(metadata) = value
.get_mut("metadata")
.and_then(serde_json::Value::as_object_mut)
{
metadata.remove(MAC_FIELD);
metadata.remove(CHAIN_INDEX_FIELD);
}
serde_json::to_vec(&value).ok()
}
fn compute_mac(key: &[u8], previous_mac: &str, canonical: &[u8]) -> String {
let mut mac =
<HmacSha256 as KeyInit>::new_from_slice(key).expect("HMAC accepts keys of any length");
mac.update(
&u64::try_from(previous_mac.len())
.unwrap_or(u64::MAX)
.to_be_bytes(),
);
mac.update(previous_mac.as_bytes());
mac.update(canonical);
to_hex(&mac.finalize().into_bytes())
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RotationError {
NoKeyId,
EmptyKey,
DuplicateKeyId(String),
}
impl std::fmt::Display for RotationError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::NoKeyId => write!(
f,
"cannot rotate a chain with no key id; call `with_key_id` before signing"
),
Self::EmptyKey => write!(f, "the replacement key is empty and provides no security"),
Self::DuplicateKeyId(id) => {
write!(f, "key id `{id}` is already in use by this chain")
}
}
}
}
impl std::error::Error for RotationError {}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ChainError {
MissingMac {
index: usize,
},
NotCanonicalizable {
index: usize,
},
MacMismatch {
index: usize,
},
MissingChainIndex {
index: usize,
},
UnknownKeyId {
index: usize,
key_id: String,
},
MixedWriters {
index: usize,
expected: String,
found: String,
},
IndexMismatch {
index: usize,
found: u64,
},
}
impl std::fmt::Display for ChainError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::MissingMac { index } => {
write!(f, "entry {index}: missing or malformed `{MAC_FIELD}` field")
}
Self::NotCanonicalizable { index } => {
write!(f, "entry {index}: could not be canonicalized for hashing")
}
Self::MissingChainIndex { index } => write!(
f,
"entry {index}: missing `{CHAIN_INDEX_FIELD}` field, so its position \
in the chain cannot be established"
),
Self::UnknownKeyId { index, key_id } => write!(
f,
"entry {index}: signed with key `{key_id}`, which this verifier does not hold"
),
Self::MixedWriters {
index,
expected,
found,
} => write!(
f,
"entry {index}: written by `{found}` but the chain began with `{expected}` — \
two processes cannot share one chain; give each its own chain or key"
),
Self::MacMismatch { index } => write!(
f,
"entry {index}: MAC mismatch — this entry or an earlier one was altered, \
removed, or reordered"
),
Self::IndexMismatch { index, found } => write!(
f,
"entry {index}: recorded chain index {found} does not match its position — \
entries were removed or reordered"
),
}
}
}
impl std::error::Error for ChainError {}
pub struct HmacChainIntegrity {
key: Vec<u8>,
key_id: Option<String>,
writer: Option<String>,
previous_keys: Vec<(String, Vec<u8>)>,
state: Mutex<ChainState>,
}
#[derive(Debug, Clone)]
struct ChainState {
previous_mac: String,
index: u64,
}
impl HmacChainIntegrity {
#[must_use]
pub fn new(key: &[u8]) -> Self {
assert!(
!key.is_empty(),
"HmacChainIntegrity requires a non-empty key; an empty key provides no security"
);
Self {
key: key.to_vec(),
key_id: None,
writer: None,
previous_keys: Vec::new(),
state: Mutex::new(ChainState {
previous_mac: GENESIS.to_string(),
index: 0,
}),
}
}
#[must_use]
pub fn resume(key: &[u8], last_mac: impl Into<String>, last_index: u64) -> Self {
assert!(
!key.is_empty(),
"HmacChainIntegrity requires a non-empty key; an empty key provides no security"
);
Self {
key: key.to_vec(),
key_id: None,
writer: None,
previous_keys: Vec::new(),
state: Mutex::new(ChainState {
previous_mac: last_mac.into(),
index: last_index.saturating_add(1),
}),
}
}
#[must_use]
pub fn with_key_id<S: Into<String>>(mut self, key_id: S) -> Self {
self.key_id = Some(key_id.into());
self
}
#[must_use]
pub fn writer<S: Into<String>>(mut self, writer: S) -> Self {
self.writer = Some(writer.into());
self
}
pub fn rotate_to(
&mut self,
new_key: &[u8],
new_key_id: impl Into<String>,
) -> Result<(), RotationError> {
if new_key.is_empty() {
return Err(RotationError::EmptyKey);
}
let Some(current_id) = self.key_id.clone() else {
return Err(RotationError::NoKeyId);
};
let new_key_id = new_key_id.into();
if new_key_id == current_id || self.previous_keys.iter().any(|(id, _)| *id == new_key_id) {
return Err(RotationError::DuplicateKeyId(new_key_id));
}
self.previous_keys.push((
current_id,
std::mem::replace(&mut self.key, new_key.to_vec()),
));
self.key_id = Some(new_key_id);
Ok(())
}
#[must_use]
pub fn key_id(&self) -> Option<&str> {
self.key_id.as_deref()
}
#[must_use]
pub fn retired_key_ids(&self) -> Vec<&str> {
self.previous_keys
.iter()
.map(|(id, _)| id.as_str())
.collect()
}
fn key_for(&self, key_id: Option<&str>) -> Option<&[u8]> {
match key_id {
None => Some(&self.key),
Some(id) if Some(id) == self.key_id.as_deref() => Some(&self.key),
Some(id) => self
.previous_keys
.iter()
.find(|(known, _)| known == id)
.map(|(_, key)| key.as_slice()),
}
}
fn lock(&self) -> std::sync::MutexGuard<'_, ChainState> {
self.state
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
}
#[must_use]
pub fn current_mac(&self) -> String {
self.lock().previous_mac.clone()
}
#[must_use]
pub fn next_index(&self) -> u64 {
self.lock().index
}
pub fn verify_chain(&self, events: &[AuditEvent]) -> Result<usize, ChainError> {
let mut previous_mac = GENESIS.to_string();
let mut chain_writer: Option<&str> = None;
for (index, event) in events.iter().enumerate() {
let stored_mac = event
.metadata
.get(MAC_FIELD)
.and_then(serde_json::Value::as_str)
.ok_or(ChainError::MissingMac { index })?;
let writer = event
.metadata
.get(WRITER_FIELD)
.and_then(serde_json::Value::as_str);
match (chain_writer, writer) {
(None, Some(found)) => chain_writer = Some(found),
(Some(expected), Some(found)) if expected != found => {
return Err(ChainError::MixedWriters {
index,
expected: expected.to_string(),
found: found.to_string(),
});
}
_ => {}
}
let key_id = event
.metadata
.get(KEY_ID_FIELD)
.and_then(serde_json::Value::as_str);
let key = self
.key_for(key_id)
.ok_or_else(|| ChainError::UnknownKeyId {
index,
key_id: key_id.unwrap_or_default().to_string(),
})?;
if let Some(found) = event
.metadata
.get(CHAIN_INDEX_FIELD)
.and_then(serde_json::Value::as_u64)
&& found != index as u64
{
return Err(ChainError::IndexMismatch { index, found });
}
let canonical = canonicalize(event).ok_or(ChainError::NotCanonicalizable { index })?;
let expected = compute_mac(key, &previous_mac, &canonical);
if !constant_time_eq(expected.as_bytes(), stored_mac.as_bytes()) {
return Err(ChainError::MacMismatch { index });
}
previous_mac = expected;
}
Ok(events.len())
}
pub fn verify_unordered(&self, events: &[AuditEvent]) -> Result<usize, ChainError> {
let mut ordered: Vec<AuditEvent> = events.to_vec();
for (index, event) in ordered.iter().enumerate() {
if event
.metadata
.get(CHAIN_INDEX_FIELD)
.and_then(serde_json::Value::as_u64)
.is_none()
{
return Err(ChainError::MissingChainIndex { index });
}
}
ordered.sort_by_key(|event| {
event
.metadata
.get(CHAIN_INDEX_FIELD)
.and_then(serde_json::Value::as_u64)
.unwrap_or(u64::MAX)
});
self.verify_chain(&ordered)
}
}
fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
if a.len() != b.len() {
return false;
}
a.iter().zip(b).fold(0u8, |acc, (x, y)| acc | (x ^ y)) == 0
}
impl AuditIntegrity for HmacChainIntegrity {
fn add_integrity(&self, event: &mut AuditEvent) {
let mut state = self.lock();
event.add_metadata(CHAIN_INDEX_FIELD, state.index);
if let Some(key_id) = &self.key_id {
event.add_metadata(KEY_ID_FIELD, key_id.clone());
}
if let Some(writer) = &self.writer {
event.add_metadata(WRITER_FIELD, writer.clone());
}
let Some(canonical) = canonicalize(event) else {
eprintln!("[AUDIT ERROR] Failed to canonicalize event for HMAC chaining");
return;
};
let mac = compute_mac(&self.key, &state.previous_mac, &canonical);
event.add_metadata(MAC_FIELD, mac.clone());
state.previous_mac = mac;
state.index = state.index.saturating_add(1);
}
fn verify(&self, event: &AuditEvent) -> bool {
event
.metadata
.get(MAC_FIELD)
.and_then(serde_json::Value::as_str)
.is_some_and(|mac| mac.len() == 64 && mac.bytes().all(|b| b.is_ascii_hexdigit()))
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::{AuditEventType, AuditResult};
const KEY: &[u8] = b"test-key-at-least-32-bytes-long!!";
fn event(principal: &str) -> AuditEvent {
AuditEvent::builder()
.event_type(AuditEventType::AuthenticationAttempt)
.principal(principal)
.method("login")
.result(AuditResult::Success)
.build()
}
fn chain_of(n: usize) -> Vec<AuditEvent> {
let integrity = HmacChainIntegrity::new(KEY);
(0..n)
.map(|i| {
let mut e = event(&format!("user{i}@example.com"));
integrity.add_integrity(&mut e);
e
})
.collect()
}
#[test]
fn test_valid_chain_verifies() {
let events = chain_of(5);
let verifier = HmacChainIntegrity::new(KEY);
assert_eq!(verifier.verify_chain(&events), Ok(5));
}
#[test]
fn test_empty_chain_verifies() {
let verifier = HmacChainIntegrity::new(KEY);
assert_eq!(verifier.verify_chain(&[]), Ok(0));
}
#[test]
fn test_wrong_key_fails() {
let events = chain_of(3);
let verifier = HmacChainIntegrity::new(b"a-completely-different-secret-key");
assert_eq!(
verifier.verify_chain(&events),
Err(ChainError::MacMismatch { index: 0 })
);
}
#[test]
fn test_restamp_forgery_is_detected() {
let mut events = chain_of(3);
events[1].principal = Some("innocent@example.com".to_string());
events[1].result = AuditResult::Success;
events[1].metadata.remove(MAC_FIELD);
events[1].metadata.remove(CHAIN_INDEX_FIELD);
let attacker = HmacChainIntegrity::new(b"attacker-guessed-key-not-the-real");
attacker.add_integrity(&mut events[1]);
let verifier = HmacChainIntegrity::new(KEY);
assert_eq!(
verifier.verify_chain(&events),
Err(ChainError::IndexMismatch { index: 1, found: 0 })
);
events[1].add_metadata(CHAIN_INDEX_FIELD, 1u64);
assert_eq!(
verifier.verify_chain(&events),
Err(ChainError::MacMismatch { index: 1 })
);
}
#[test]
fn test_field_edit_is_detected() {
let mut events = chain_of(3);
events[2].principal = Some("attacker@evil.com".to_string());
let verifier = HmacChainIntegrity::new(KEY);
assert_eq!(
verifier.verify_chain(&events),
Err(ChainError::MacMismatch { index: 2 })
);
}
#[test]
fn test_previously_uncovered_fields_are_detected() {
for (name, mutate) in [
(
"severity",
(|e: &mut AuditEvent| {
e.severity = crate::AuditSeverity::Critical;
}) as fn(&mut AuditEvent),
),
("error", |e: &mut AuditEvent| {
e.error = Some("rewritten".to_string());
}),
("metadata", |e: &mut AuditEvent| {
e.add_metadata("amount", 1);
}),
("params", |e: &mut AuditEvent| {
e.params = Some(serde_json::json!({"forged": true}));
}),
] {
let mut events = chain_of(2);
mutate(&mut events[1]);
let verifier = HmacChainIntegrity::new(KEY);
assert_eq!(
verifier.verify_chain(&events),
Err(ChainError::MacMismatch { index: 1 }),
"tampering with `{name}` went undetected"
);
}
}
#[test]
fn test_deletion_is_detected() {
let mut events = chain_of(5);
events.remove(2);
let verifier = HmacChainIntegrity::new(KEY);
assert_eq!(
verifier.verify_chain(&events),
Err(ChainError::IndexMismatch { index: 2, found: 3 })
);
}
#[test]
fn test_reorder_is_detected() {
let mut events = chain_of(4);
events.swap(1, 2);
let verifier = HmacChainIntegrity::new(KEY);
assert!(verifier.verify_chain(&events).is_err());
}
#[test]
fn test_truncation_is_detected_via_index() {
let events = chain_of(5);
let truncated = &events[..3];
let verifier = HmacChainIntegrity::new(KEY);
assert_eq!(verifier.verify_chain(truncated), Ok(3));
let last_index = truncated[2]
.metadata
.get(CHAIN_INDEX_FIELD)
.and_then(serde_json::Value::as_u64);
assert_eq!(last_index, Some(2), "index reveals the stream length");
}
#[test]
fn test_missing_mac_is_detected() {
let mut events = chain_of(2);
events[1].metadata.remove(MAC_FIELD);
let verifier = HmacChainIntegrity::new(KEY);
assert_eq!(
verifier.verify_chain(&events),
Err(ChainError::MissingMac { index: 1 })
);
}
#[test]
fn test_resume_continues_chain() {
let integrity = HmacChainIntegrity::new(KEY);
let mut first = event("alice@example.com");
integrity.add_integrity(&mut first);
let resumed = HmacChainIntegrity::resume(KEY, integrity.current_mac(), 0);
let mut second = event("bob@example.com");
resumed.add_integrity(&mut second);
let verifier = HmacChainIntegrity::new(KEY);
assert_eq!(verifier.verify_chain(&[first, second]), Ok(2));
}
#[test]
fn test_canonicalization_is_order_independent() {
let integrity = HmacChainIntegrity::new(KEY);
let mut a = event("alice@example.com");
a.add_metadata("zebra", 1);
a.add_metadata("apple", 2);
integrity.add_integrity(&mut a);
let integrity2 = HmacChainIntegrity::new(KEY);
let mut b = event("alice@example.com");
b.add_metadata("apple", 2);
b.add_metadata("zebra", 1);
b.timestamp = a.timestamp;
integrity2.add_integrity(&mut b);
assert_eq!(
a.metadata.get(MAC_FIELD),
b.metadata.get(MAC_FIELD),
"metadata ordering must not affect the MAC"
);
}
#[test]
fn test_serialization_round_trip_preserves_verification() {
let events = chain_of(3);
let lines: Vec<String> = events
.iter()
.map(|e| serde_json::to_string(e).unwrap())
.collect();
let parsed: Vec<AuditEvent> = lines
.iter()
.map(|l| serde_json::from_str(l).unwrap())
.collect();
let verifier = HmacChainIntegrity::new(KEY);
assert_eq!(verifier.verify_chain(&parsed), Ok(3));
}
#[test]
fn test_constant_time_eq() {
assert!(constant_time_eq(b"abc", b"abc"));
assert!(!constant_time_eq(b"abc", b"abd"));
assert!(!constant_time_eq(b"abc", b"ab"));
assert!(constant_time_eq(b"", b""));
}
#[cfg(feature = "hlc")]
mod hlc_canonical_form {
use super::*;
use crate::{EventClock, HlcClock, Logger, NoopAuditBackend};
use std::sync::Arc;
const KEY: &[u8] = b"test-key-at-least-32-bytes-long!!";
#[test]
fn test_events_without_a_timestamp_canonicalize_unchanged() {
let integrity = HmacChainIntegrity::new(KEY);
let mut events: Vec<AuditEvent> = (0..4)
.map(|n| {
let mut event = AuditEvent::builder()
.event_type(AuditEventType::AuthenticationAttempt)
.principal(format!("user{n}"))
.result(AuditResult::Success)
.build();
integrity.add_integrity(&mut event);
event
})
.collect();
assert!(
events.iter().all(|e| e.hlc.is_none()),
"no clock was configured, so no event carries a timestamp"
);
assert_eq!(
HmacChainIntegrity::new(KEY).verify_chain(&events),
Ok(4),
"a chain with no timestamps verifies under an hlc-enabled build"
);
let json = serde_json::to_value(&events[0]).unwrap();
assert!(json.get("hlc").is_none());
let line = serde_json::to_string(&events[0]).unwrap();
events[0] = serde_json::from_str(&line).unwrap();
assert_eq!(HmacChainIntegrity::new(KEY).verify_chain(&events), Ok(4));
}
#[test]
fn test_a_stamped_chain_verifies() {
let backend = Arc::new(NoopAuditBackend);
let logger = Logger::builder(backend)
.integrity(Arc::new(HmacChainIntegrity::new(KEY)))
.clock(Arc::new(HlcClock::new()))
.build();
let integrity = HmacChainIntegrity::new(KEY);
let clock = HlcClock::new();
let mut events: Vec<AuditEvent> = (0..4)
.map(|n| {
let mut event = AuditEvent::builder()
.event_type(AuditEventType::AdminAction)
.result(AuditResult::Success)
.method(format!("action{n}"))
.hlc(EventClock::from(clock.now().unwrap()))
.build();
integrity.add_integrity(&mut event);
event
})
.collect();
assert_eq!(
HmacChainIntegrity::new(KEY).verify_chain(&events),
Ok(4),
"a chain of stamped events verifies"
);
let line = serde_json::to_string(&events[2]).unwrap();
let reloaded: AuditEvent = serde_json::from_str(&line).unwrap();
assert_eq!(reloaded.hlc, events[2].hlc);
events[2] = reloaded;
assert_eq!(HmacChainIntegrity::new(KEY).verify_chain(&events), Ok(4));
let _ = logger;
}
#[test]
fn test_rewriting_the_causal_order_is_detected() {
let integrity = HmacChainIntegrity::new(KEY);
let clock = HlcClock::new();
let mut events: Vec<AuditEvent> = (0..3)
.map(|_| {
let mut event = AuditEvent::builder()
.event_type(AuditEventType::SecurityViolation)
.result(AuditResult::Violation)
.hlc(EventClock::from(clock.now().unwrap()))
.build();
integrity.add_integrity(&mut event);
event
})
.collect();
assert_eq!(HmacChainIntegrity::new(KEY).verify_chain(&events), Ok(3));
events[2].hlc = Some(EventClock {
physical: 1,
logical: 0,
});
assert_eq!(
HmacChainIntegrity::new(KEY).verify_chain(&events),
Err(ChainError::MacMismatch { index: 2 }),
"altering the causal timestamp breaks the MAC"
);
}
#[test]
fn test_adding_a_timestamp_to_a_signed_event_is_detected() {
let integrity = HmacChainIntegrity::new(KEY);
let mut event = AuditEvent::builder()
.event_type(AuditEventType::AdminAction)
.result(AuditResult::Success)
.build();
integrity.add_integrity(&mut event);
assert_eq!(
HmacChainIntegrity::new(KEY).verify_chain(&[event.clone()]),
Ok(1)
);
event.hlc = Some(EventClock {
physical: 99,
logical: 0,
});
assert_eq!(
HmacChainIntegrity::new(KEY).verify_chain(&[event]),
Err(ChainError::MacMismatch { index: 0 }),
"a timestamp cannot be added to an already-signed event"
);
}
}
}