instruction-md 0.4.0

Read, check, resolve and verify instruction.md documents (the specification's first edition, instruction/1): the reader, the agent text, composition and signature verification
Documentation
//! Digests (§14.1, §19): SHA-256 over a source's original bytes — no line endings normalized, no metadata removed —
//! written `sha256:<lower-hex>`. An author signature covers the authored digest, a delivery signature the delivered
//! text's.

use serde_json::Value;

use crate::read::{ReadOptions, read};

/// The lower-hex SHA-256 of the bytes.
pub fn sha256_hex(data: &[u8]) -> String {
    let d = sha256(data);
    let mut s = String::with_capacity(64);
    for b in d {
        const HEX: &[u8; 16] = b"0123456789abcdef";
        s.push(HEX[(b >> 4) as usize] as char);
        s.push(HEX[(b & 0xf) as usize] as char);
    }
    s
}

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,
];

/// The SHA-256 of the bytes (FIPS 180-4), this crate's own: a build without the `verify` feature has no `ring`.
pub fn sha256(data: &[u8]) -> [u8; 32] {
    let mut h: [u32; 8] = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
    let mut block = |chunk: &[u8; 64]| {
        let mut w = [0u32; 64];
        for (i, word) in chunk.as_chunks::<4>().0.iter().enumerate() {
            w[i] = u32::from_be_bytes(*word);
        }
        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 a, mut b, mut c, mut d, mut e, mut f, mut g, mut hh] = h;
        for i in 0..64 {
            let s1 = e.rotate_right(6) ^ e.rotate_right(11) ^ e.rotate_right(25);
            let ch = (e & f) ^ (!e & g);
            let t1 = hh.wrapping_add(s1).wrapping_add(ch).wrapping_add(K[i]).wrapping_add(w[i]);
            let s0 = a.rotate_right(2) ^ a.rotate_right(13) ^ a.rotate_right(22);
            let maj = (a & b) ^ (a & c) ^ (b & c);
            let t2 = s0.wrapping_add(maj);
            hh = g;
            g = f;
            f = e;
            e = d.wrapping_add(t1);
            d = c;
            c = b;
            b = a;
            a = t1.wrapping_add(t2);
        }
        for (x, y) in h.iter_mut().zip([a, b, c, d, e, f, g, hh]) {
            *x = x.wrapping_add(y);
        }
    };
    let (chunks, rest) = data.as_chunks::<64>();
    for chunk in chunks {
        block(chunk);
    }
    // the padding: 0x80, zeros, then the message's length in bits, big-endian, to a whole block (or two)
    let mut tail = [0u8; 128];
    tail[..rest.len()].copy_from_slice(rest);
    tail[rest.len()] = 0x80;
    let blocks = if rest.len() < 56 { 1 } else { 2 };
    let bits = (data.len() as u64).wrapping_mul(8);
    tail[blocks * 64 - 8..blocks * 64].copy_from_slice(&bits.to_be_bytes());
    for chunk in tail[..blocks * 64].as_chunks::<64>().0 {
        block(chunk);
    }
    let mut out = [0u8; 32];
    for (o, x) in out.as_chunks_mut::<4>().0.iter_mut().zip(h) {
        *o = x.to_be_bytes();
    }
    out
}

/// `sha256:<hex>` of some bytes: a document's authored digest (its stored bytes, byte for byte), or the digest of
/// delivered text, a value, a source.
pub fn digest(bytes: &[u8]) -> String {
    format!("sha256:{}", sha256_hex(bytes))
}

/// The digest of a text (its UTF-8 bytes).
pub fn digest_text(text: &str) -> String {
    digest(text.as_bytes())
}

/// The authored digest an author signature binds (§14.1, §19): the stored bytes as they are — in instruction/1 no
/// line is left out (a signature travels beside the document, never in it). The same as [`digest`].
pub fn author_digest(document: &[u8]) -> String {
    digest(document)
}

/// The front matter's `id` (§3.1), when the document has front matter that is valid YAML and an `id` string — what an
/// attestation's `doc` claim names. Bytes that are not UTF-8 have none.
pub fn front_matter_id(document: &[u8]) -> Option<String> {
    let text = std::str::from_utf8(document).ok()?;
    let r = read(text, &ReadOptions::default());
    match r.document.metadata.front.get("id") {
        Some(Value::String(id)) => Some(id.clone()),
        _ => None,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn digests() {
        assert_eq!(digest(b""), "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
        assert_eq!(front_matter_id(b"---\nid: instruction://ins_x\nspec: \"1\"\n---\nbody\n").as_deref(), Some("instruction://ins_x"));
        assert_eq!(front_matter_id(b"no front matter\n"), None);
    }

    #[test]
    fn sha256_vectors() {
        // FIPS 180-4's examples, and every length around the padding's block boundaries
        assert_eq!(sha256_hex(b"abc"), "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad");
        assert_eq!(
            sha256_hex(b"abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq"),
            "248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1"
        );
        assert_eq!(sha256_hex(&[b'a'; 1_000_000]), "cdc76e5c9914fb9281a1c7e284d73e67f1809a48a497200e046d39ccc7112cd0");
        #[cfg(feature = "verify")]
        for n in 0..300 {
            let data: Vec<u8> = (0..n).map(|i| (i * 7 + n) as u8).collect();
            assert_eq!(sha256(&data).as_slice(), ring::digest::digest(&ring::digest::SHA256, &data).as_ref(), "length {n}");
        }
    }
}