// 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, { 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); } }