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
258 lines
8.5 KiB
Rust
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);
|
|
}
|
|
}
|