ecqv 0.1.0

SEC 4 ECQV implicit certificates on P-256: reconstruct a public key from a certificate and the issuer's key, with no signature to carry
Documentation
//! SEC 4 v1.0 section 2.3: hashing octet strings to integers modulo n (`Hn`).
//!
//! `Hn(S)` is defined as the leftmost `floor(log2 n)` bits of `H(S)`,
//! interpreted as an integer. For P-256 with SHA-256, `n` is 256 bits so
//! `floor(log2 n)` is 255: `e` is the 256-bit SHA-256 digest with its lowest
//! bit dropped (a right shift by one), NOT the top bit masked off. Those two
//! are different values, and the known-answer vectors pin the right-shift
//! form.
//!
//! Why truncation and not reduction (`digest % n`): because `2^255 < n`, every
//! 255-bit value is strictly below the P-256 group order, so the truncation
//! lands in `[0, n)` with no wraparound and therefore no modular bias. A naive
//! `digest % n` over a full 256-bit digest is biased, which over many
//! certificates leaks private key bits, and it would also fail every known
//! answer vector here. Do not "fix" this function into a reduction; that is
//! exactly the hazard this comment exists to prevent.

use elliptic_curve::ff::PrimeField;
use p256::Scalar;
use sha2::{Digest, Sha256};

/// `Hn` per SEC 4 v1.0 section 2.3 for P-256 with SHA-256.
///
/// Takes the opaque certificate bytes and returns `e` as a P-256 scalar:
/// the SHA-256 digest interpreted as a big-endian integer, shifted right by
/// one bit (the leftmost 255 bits).
pub fn hash_to_scalar(cert: &[u8]) -> Scalar {
    let mut digest = Sha256::digest(cert);
    // Right shift the whole 256-bit value by one: carry each byte's lowest bit
    // into the next byte's top. The final lowest bit is dropped.
    let mut prev_lsb = 0u8;
    for b in digest.iter_mut() {
        let cur_lsb = *b & 1;
        *b = (*b >> 1) | (prev_lsb << 7);
        prev_lsb = cur_lsb;
    }
    Scalar::from_repr(digest).unwrap() // < n for P-256, cannot fail
}

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

    /// Fixed known answer for the empty-string-free input b"ECQV", computed
    /// by independent arithmetic: e = sha256("ECQV") >> 1.
    #[test]
    fn truncation_drops_the_lowest_bit_not_the_highest() {
        let e = hash_to_scalar(b"ECQV");
        let expected =
            hex::decode("20D6D7C521BBC6C8661FD13EB680443639329E11D5FCC550AC714E8BA08E2053")
                .unwrap();
        let arr: [u8; 32] = expected.try_into().unwrap();
        assert_eq!(e, Scalar::from_repr(arr.into()).unwrap());
    }

    /// Permanent guard against the exact hazard this file documents: a future
    /// contributor "fixing" the truncation into a reduction would change `e`
    /// and fail every vector. This catches the regression at the function level
    /// first, and is the same wrongness the harness was proven to detect.
    #[test]
    fn truncation_is_not_reduction_mod_n() {
        use elliptic_curve::ops::Reduce;
        let cert = b"ECQV";
        let e = hash_to_scalar(cert);
        let reduced = Scalar::reduce(&Sha256::digest(cert));
        assert_ne!(
            e, reduced,
            "Hn must truncate (right shift), never reduce mod n"
        );
    }
}