1 parent
228a0da47f
commit
abc0bdf621
79 files changed
+31370
No files matched your search
@@ -0,0 +1,257 @@
|
||||
// SPDX-License-Identifier: Prosperity-3.0.0
|
||||
// Copyright Scientific Computing Studio
|
||||
// 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);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user