use std::collections::BTreeSet;
use sha2::{Digest, Sha256};
use crate::error::FingerprintError;
const DOMAIN: &str = "tamga-fingerprint-v1";
const UNIT_SEPARATOR: char = '\u{1f}';
const ASCII_WHITESPACE: [char; 6] = [' ', '\t', '\r', '\n', '\u{b}', '\u{c}'];
pub fn canonical<I, L, V>(components: I) -> Result<String, FingerprintError>
where
I: IntoIterator<Item = (L, V)>,
L: AsRef<str>,
V: AsRef<str>,
{
let mut seen_labels = BTreeSet::new();
let mut parts: Vec<String> = Vec::new();
for (label, value) in components {
let label = label.as_ref();
validate_label(label)?;
if !seen_labels.insert(label.to_owned()) {
return Err(FingerprintError::DuplicateLabel {
label: label.to_owned(),
});
}
let value = value
.as_ref()
.trim_matches(|c| ASCII_WHITESPACE.contains(&c));
if value.chars().any(|c| c.is_ascii_control()) {
return Err(FingerprintError::ControlCharacterInValue {
label: label.to_owned(),
});
}
let mut part = String::with_capacity(label.len() + 1 + value.len());
part.push_str(label);
part.push('=');
part.push_str(value);
parts.push(part);
}
if parts.is_empty() {
return Err(FingerprintError::NoComponents);
}
parts.sort_unstable();
let mut out =
String::with_capacity(DOMAIN.len() + parts.iter().map(|p| p.len() + 1).sum::<usize>());
out.push_str(DOMAIN);
for part in &parts {
out.push(UNIT_SEPARATOR);
out.push_str(part);
}
Ok(out)
}
pub fn compute<I, L, V>(components: I) -> Result<String, FingerprintError>
where
I: IntoIterator<Item = (L, V)>,
L: AsRef<str>,
V: AsRef<str>,
{
const HEX: &[u8; 16] = b"0123456789abcdef";
let canonical = canonical(components)?;
let digest = Sha256::digest(canonical.as_bytes());
let mut hex = String::with_capacity(digest.len() * 2);
for byte in digest {
hex.push(HEX[usize::from(byte >> 4)] as char);
hex.push(HEX[usize::from(byte & 0x0f)] as char);
}
Ok(hex)
}
fn validate_label(label: &str) -> Result<(), FingerprintError> {
if label.is_empty() {
return Err(FingerprintError::EmptyLabel);
}
let valid = label.chars().all(|c| c.is_ascii_graphic() && c != '=');
if !valid {
return Err(FingerprintError::InvalidLabel {
label: label.to_owned(),
});
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
const SINGLE: &str = "8edf2aef2de1f97d8c49b093cd789342003cc35132411010328db9c65ae47c21";
#[test]
fn canonical_uses_the_real_unit_separator_byte() {
let c = canonical([("machine-id", "abc123")]).unwrap();
assert_eq!(c, "tamga-fingerprint-v1\u{1f}machine-id=abc123");
assert!(c.as_bytes().contains(&0x1f));
assert!(!c.contains("<US>"));
}
#[test]
fn compute_is_64_lowercase_hex_characters() {
let fp = compute([("machine-id", "abc123")]).unwrap();
assert_eq!(fp.len(), 64);
assert!(fp
.chars()
.all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase()));
assert_eq!(fp, SINGLE);
}
#[test]
fn component_order_does_not_change_the_fingerprint() {
let sorted = compute([("disk", "SN-9"), ("machine-id", "abc123")]).unwrap();
let unsorted = compute([("machine-id", "abc123"), ("disk", "SN-9")]).unwrap();
assert_eq!(sorted, unsorted);
}
#[test]
fn surrounding_ascii_whitespace_is_trimmed_not_rejected() {
let padded = compute([("machine-id", " abc123\t\n")]).unwrap();
assert_eq!(padded, SINGLE);
}
#[test]
fn interior_whitespace_is_preserved() {
let a = compute([("name", "My Machine")]).unwrap();
let b = compute([("name", "MyMachine")]).unwrap();
assert_ne!(a, b);
}
#[test]
fn unicode_whitespace_is_not_trimmed() {
let nbsp = compute([("machine-id", "\u{a0}abc123")]).unwrap();
assert_ne!(nbsp, SINGLE);
}
#[test]
fn case_is_preserved() {
let upper = compute([("machine-id", "ABC123")]).unwrap();
assert_ne!(upper, SINGLE);
assert_eq!(
upper,
"d9515717e1662b5e24d33ddbc05839fb9c6a50f4704c537f43127e468cdad82a"
);
}
#[test]
fn sorts_case_sensitively_not_by_case_insensitive_collation() {
let c = canonical([("a", "1"), ("Z", "2")]).unwrap();
assert_eq!(c, "tamga-fingerprint-v1\u{1f}Z=2\u{1f}a=1");
}
#[test]
fn sorts_on_the_whole_component_not_on_the_label_alone() {
let c = canonical([("a", "x"), ("a-b", "y")]).unwrap();
assert_eq!(c, "tamga-fingerprint-v1\u{1f}a-b=y\u{1f}a=x");
}
#[test]
fn an_empty_value_still_contributes_its_label() {
let empty = canonical([("machine-id", "")]).unwrap();
assert_eq!(empty, "tamga-fingerprint-v1\u{1f}machine-id=");
assert_ne!(compute([("machine-id", "")]).unwrap(), SINGLE);
}
#[test]
fn equals_is_legal_in_a_value_and_splits_at_the_first_one() {
let c = canonical([("path", "a=b=c")]).unwrap();
assert_eq!(c, "tamga-fingerprint-v1\u{1f}path=a=b=c");
}
#[test]
fn non_ascii_values_pass_through_as_utf8_bytes() {
let c = canonical([("owner", "café")]).unwrap();
assert_eq!(c, "tamga-fingerprint-v1\u{1f}owner=café");
assert_eq!(
compute([("owner", "café")]).unwrap(),
"8a729bee74af4aeaf886d4584cc61bc8025d4bad3cce72441693e84e5c450739"
);
}
#[test]
fn nfc_and_nfd_spellings_are_deliberately_different() {
let precomposed = compute([("owner", "caf\u{e9}")]).unwrap();
let decomposed = compute([("owner", "cafe\u{301}")]).unwrap();
assert_ne!(precomposed, decomposed);
}
#[test]
fn accepts_owned_strings_and_borrowed_str_alike() {
let owned = compute([(String::from("machine-id"), String::from("abc123"))]).unwrap();
let borrowed = compute([("machine-id", "abc123")]).unwrap();
assert_eq!(owned, borrowed);
let v: Vec<(&str, String)> = vec![("machine-id", "abc123".to_string())];
assert_eq!(compute(v).unwrap(), borrowed);
}
#[test]
fn rejects_no_components() {
let none: [(&str, &str); 0] = [];
assert_eq!(canonical(none), Err(FingerprintError::NoComponents));
}
#[test]
fn rejects_an_empty_label() {
assert_eq!(canonical([("", "x")]), Err(FingerprintError::EmptyLabel));
}
#[test]
fn rejects_a_duplicate_label() {
assert_eq!(
canonical([("id", "a"), ("id", "b")]),
Err(FingerprintError::DuplicateLabel {
label: "id".to_string()
})
);
}
#[test]
fn rejects_a_duplicate_label_even_when_the_values_are_equal() {
assert!(matches!(
canonical([("id", "a"), ("id", "a")]),
Err(FingerprintError::DuplicateLabel { .. })
));
}
#[test]
fn rejects_equals_in_a_label() {
assert_eq!(
canonical([("a=b", "x")]),
Err(FingerprintError::InvalidLabel {
label: "a=b".to_string()
})
);
}
#[test]
fn rejects_the_separator_in_a_label() {
assert!(matches!(
canonical([("a\u{1f}b", "x")]),
Err(FingerprintError::InvalidLabel { .. })
));
}
#[test]
fn rejects_a_non_ascii_label() {
assert!(matches!(
canonical([("café", "x")]),
Err(FingerprintError::InvalidLabel { .. })
));
}
#[test]
fn rejects_a_space_in_a_label() {
assert!(matches!(
canonical([("a b", "x")]),
Err(FingerprintError::InvalidLabel { .. })
));
}
#[test]
fn rejects_the_separator_in_a_value() {
assert_eq!(
canonical([("id", "a\u{1f}b")]),
Err(FingerprintError::ControlCharacterInValue {
label: "id".to_string()
})
);
}
#[test]
fn rejects_a_control_character_in_a_value_rather_than_stripping_it() {
assert!(matches!(
canonical([("id", "a\u{7}b")]),
Err(FingerprintError::ControlCharacterInValue { .. })
));
assert!(canonical([("id", "ab")]).is_ok());
}
#[test]
fn rejects_del_in_a_value() {
assert!(matches!(
canonical([("id", "a\u{7f}b")]),
Err(FingerprintError::ControlCharacterInValue { .. })
));
}
#[test]
fn a_value_of_only_whitespace_trims_to_empty_and_is_accepted() {
assert_eq!(
canonical([("id", " \t\r\n")]).unwrap(),
"tamga-fingerprint-v1\u{1f}id="
);
}
#[test]
fn error_display_escapes_a_control_character_in_the_label() {
let err = canonical([("a\u{1f}b", "x")]).unwrap_err();
let msg = err.to_string();
assert!(msg.contains("\\u{1f}"), "{msg}");
assert!(!msg.contains('\u{1f}'), "{msg}");
}
#[test]
fn control_character_error_does_not_echo_the_value() {
let err = canonical([("id", "secret\u{7}stuff")]).unwrap_err();
let msg = err.to_string();
assert!(msg.contains("id"));
assert!(!msg.contains("secret"), "{msg}");
}
}