Files
coursebank/src/util/hash.rs
T
alexmandClaude c8d6f4a5dd
Pipeline / check (pull_request) Successful in 12m21s
Pipeline / docs (pull_request) Skipped
Pipeline / nightly (pull_request) Skipped
Pipeline / release (pull_request) Skipped
Name Scienting as the copyright holder and contributor
Replace 'Scientific Computing Studio' in the source headers, the Cargo.toml
authors, and the LICENSE contributor line. pixi.toml still has the old
authors line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014zNf4shD4zaCKLucZWPYL9
2026-10-20 00:21:19 -04:00

258 lines
8.5 KiB
Rust

// SPDX-License-Identifier: Prosperity-3.0.0
// Copyright Scienting
// Source: https://git.scient.ing/education/coursebank
//! Content fingerprints and student pseudonyms.
//!
//! Two different jobs need two different hashes, and conflating them would be a
//! privacy bug.
//!
//! [`fingerprint`] answers "is this the same question I used last time?". It
//! only needs to be stable and short, so it uses FNV-1a. It is not a security
//! primitive and is never applied to anything about a person.
//!
//! [`pseudonym`] answers "can I keep a response table under version control
//! without publishing who answered what?". Student identifiers are low entropy
//! (a seven-digit number is a ten-million-item dictionary), so an unkeyed hash
//! of one is trivially reversible and would provide no protection at all. It
//! therefore uses HMAC-SHA-256 under a secret salt that lives outside the
//! repository. Both primitives are implemented here so the crate needs no
//! cryptography dependency.
/// FNV-1a 64-bit offset basis.
const FNV_OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
/// FNV-1a 64-bit prime.
const FNV_PRIME: u64 = 0x0000_0100_0000_01b3;
/// A short, stable content fingerprint rendered as 16 lowercase hex digits.
///
/// Used to detect that a question was silently edited between two
/// administrations, which invalidates pooling their statistics.
///
/// # Arguments
///
/// * `parts` - the canonical content pieces, hashed in order with a separator
/// so that reordering or regrouping them changes the result.
///
/// # Returns
///
/// The fingerprint as a hex string.
pub fn fingerprint<'a, I>(parts: I) -> String
where
I: IntoIterator<Item = &'a str>,
{
let mut h = FNV_OFFSET;
for part in parts {
for b in part.as_bytes() {
h ^= *b as u64;
h = h.wrapping_mul(FNV_PRIME);
}
// A byte that cannot appear in the inputs, so concatenation is unambiguous.
h ^= 0x1f;
h = h.wrapping_mul(FNV_PRIME);
}
format!("{h:016x}")
}
/// A keyed pseudonym for a student identifier.
///
/// # Arguments
///
/// * `salt` - a secret of at least 16 bytes, kept out of version control.
/// * `id` - the institutional identifier or email to replace.
/// * `len` - how many hex characters to keep; 16 gives a 64-bit tag, which is
/// ample for a cohort and short enough to read in a table.
///
/// # Returns
///
/// The truncated hex tag, prefixed with `s-`.
pub fn pseudonym(salt: &[u8], id: &str, len: usize) -> String {
let mac = hmac_sha256(salt, id.trim().to_lowercase().as_bytes());
let hex: String = mac.iter().map(|b| format!("{b:02x}")).collect();
format!("s-{}", &hex[..len.min(hex.len())])
}
/// HMAC-SHA-256.
///
/// # Arguments
///
/// * `key` - the secret key, of any length.
/// * `msg` - the message to authenticate.
///
/// # Returns
///
/// The 32-byte tag.
pub fn hmac_sha256(key: &[u8], msg: &[u8]) -> [u8; 32] {
const BLOCK: usize = 64;
let mut k = [0u8; BLOCK];
if key.len() > BLOCK {
k[..32].copy_from_slice(&sha256(key));
} else {
k[..key.len()].copy_from_slice(key);
}
let mut inner = Vec::with_capacity(BLOCK + msg.len());
let mut outer = Vec::with_capacity(BLOCK + 32);
for b in k.iter() {
inner.push(b ^ 0x36);
outer.push(b ^ 0x5c);
}
inner.extend_from_slice(msg);
outer.extend_from_slice(&sha256(&inner));
sha256(&outer)
}
/// SHA-256 round constants.
#[rustfmt::skip]
const K: [u32; 64] = [
0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
];
/// SHA-256 of a byte slice.
///
/// # Arguments
///
/// * `msg` - the message to digest.
///
/// # Returns
///
/// The 32-byte digest.
pub fn sha256(msg: &[u8]) -> [u8; 32] {
let mut h: [u32; 8] = [
0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab,
0x5be0cd19,
];
// Pad to a multiple of 64 bytes: 0x80, zeros, then the 64-bit bit length.
let mut data = msg.to_vec();
let bit_len = (msg.len() as u64).wrapping_mul(8);
data.push(0x80);
while data.len() % 64 != 56 {
data.push(0);
}
data.extend_from_slice(&bit_len.to_be_bytes());
let mut w = [0u32; 64];
for chunk in data.chunks(64) {
for (i, w_i) in w.iter_mut().enumerate().take(16) {
let j = i * 4;
*w_i = u32::from_be_bytes([chunk[j], chunk[j + 1], chunk[j + 2], chunk[j + 3]]);
}
for i in 16..64 {
let s0 = w[i - 15].rotate_right(7) ^ w[i - 15].rotate_right(18) ^ (w[i - 15] >> 3);
let s1 = w[i - 2].rotate_right(17) ^ w[i - 2].rotate_right(19) ^ (w[i - 2] >> 10);
w[i] = w[i - 16]
.wrapping_add(s0)
.wrapping_add(w[i - 7])
.wrapping_add(s1);
}
let mut v = h;
for i in 0..64 {
let s1 = v[4].rotate_right(6) ^ v[4].rotate_right(11) ^ v[4].rotate_right(25);
let ch = (v[4] & v[5]) ^ ((!v[4]) & v[6]);
let t1 = v[7]
.wrapping_add(s1)
.wrapping_add(ch)
.wrapping_add(K[i])
.wrapping_add(w[i]);
let s0 = v[0].rotate_right(2) ^ v[0].rotate_right(13) ^ v[0].rotate_right(22);
let maj = (v[0] & v[1]) ^ (v[0] & v[2]) ^ (v[1] & v[2]);
let t2 = s0.wrapping_add(maj);
v[7] = v[6];
v[6] = v[5];
v[5] = v[4];
v[4] = v[3].wrapping_add(t1);
v[3] = v[2];
v[2] = v[1];
v[1] = v[0];
v[0] = t1.wrapping_add(t2);
}
for i in 0..8 {
h[i] = h[i].wrapping_add(v[i]);
}
}
let mut out = [0u8; 32];
for i in 0..8 {
out[i * 4..i * 4 + 4].copy_from_slice(&h[i].to_be_bytes());
}
out
}
/// Renders bytes as lowercase hex.
///
/// # Arguments
///
/// * `bytes` - the bytes to render.
///
/// # Returns
///
/// The hex string.
pub fn hex(bytes: &[u8]) -> String {
bytes.iter().map(|b| format!("{b:02x}")).collect()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn sha256_matches_known_vectors() {
assert_eq!(
hex(&sha256(b"")),
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
);
assert_eq!(
hex(&sha256(b"abc")),
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
);
// Longer than one block, to exercise the multi-chunk path.
assert_eq!(
hex(&sha256(
b"abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq"
)),
"248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1"
);
}
#[test]
fn hmac_matches_rfc4231_case_2() {
// RFC 4231 test case 2: key "Jefe", data "what do ya want for nothing?".
assert_eq!(
hex(&hmac_sha256(b"Jefe", b"what do ya want for nothing?")),
"5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843"
);
}
#[test]
fn fingerprint_is_order_sensitive_and_unambiguous() {
assert_ne!(fingerprint(["a", "b"]), fingerprint(["b", "a"]));
// Separator prevents "ab" + "c" colliding with "a" + "bc".
assert_ne!(fingerprint(["ab", "c"]), fingerprint(["a", "bc"]));
assert_eq!(fingerprint(["a", "b"]), fingerprint(["a", "b"]));
assert_eq!(fingerprint(["x"]).len(), 16);
}
#[test]
fn pseudonym_is_keyed_and_normalized() {
let a = pseudonym(b"salt-one-0123456", "4496395", 16);
let b = pseudonym(b"salt-two-0123456", "4496395", 16);
assert_ne!(a, b, "different salts must give different pseudonyms");
assert_eq!(
pseudonym(b"salt-one-0123456", " SCD62@pitt.edu ", 16),
pseudonym(b"salt-one-0123456", "scd62@pitt.edu", 16)
);
assert!(a.starts_with("s-"));
assert_eq!(a.len(), 18);
}
}