feat(pq-key-encoder): phase 2 - ASN.1 primitives (ENG-1310, ENG-1311, ENG-1312, ENG-1313, ENG-1314, ENG-1315, ENG-1316)

Author: eacet

packages/pq-key-encoder/rust/src/asn1/algorithm.rs

@@ -0,0 +1,165 @@
+use alloc::vec::Vec;
+use pq_oid::Algorithm;
+
+use crate::error::{Error, Result};
+
+use super::decode::{decode_oid, read_tlv};
+use super::length::encode_length;
+use super::tags;
+
+/// Encode an AlgorithmIdentifier SEQUENCE for the given algorithm.
+/// Writes: SEQUENCE { OID } (no NULL parameter for PQ algorithms).
+pub(crate) fn encode_algorithm_identifier(algorithm: Algorithm, out: &mut Vec<u8>) {
+    // Build the OID TLV
+    let mut oid_bytes = Vec::new();
+    pq_oid::encode_oid_to(algorithm.oid(), &mut oid_bytes)
+        .expect("known algorithm OID should always encode");
+
+    let mut oid_tlv = Vec::new();
+    oid_tlv.push(tags::TAG_OBJECT_IDENTIFIER);
+    encode_length(oid_bytes.len(), &mut oid_tlv);
+    oid_tlv.extend_from_slice(&oid_bytes);
+
+    // Wrap in SEQUENCE
+    out.push(tags::TAG_SEQUENCE);
+    encode_length(oid_tlv.len(), out);
+    out.extend_from_slice(&oid_tlv);
+}
+
+/// Decode an AlgorithmIdentifier SEQUENCE.
+/// Returns `(Algorithm, bytes_read)`.
+/// Accepts both absent and NULL parameters for interoperability.
+pub(crate) fn decode_algorithm_identifier(
+    input: &[u8],
+    offset: usize,
+) -> Result<(Algorithm, usize)> {
+    // Read outer SEQUENCE
+    let outer = read_tlv(input, offset)?;
+    if outer.tag != tags::TAG_SEQUENCE {
+        return Err(Error::InvalidDer(
+            "expected SEQUENCE for AlgorithmIdentifier",
+        ));
+    }
+
+    // Read OID inside the sequence
+    let oid_tlv = read_tlv(outer.value, 0)?;
+    if oid_tlv.tag != tags::TAG_OBJECT_IDENTIFIER {
+        return Err(Error::InvalidDer(
+            "expected OBJECT IDENTIFIER in AlgorithmIdentifier",
+        ));
+    }
+
+    let oid_string = decode_oid(oid_tlv.value)?;
+
+    // Check for optional parameters after the OID
+    let consumed = oid_tlv.bytes_read;
+    if consumed < outer.value.len() {
+        let remaining = &outer.value[consumed..];
+        // Accept NULL (0x05 0x00)
+        if remaining.len() >= 2 && remaining[0] == tags::TAG_NULL && remaining[1] == 0x00 {
+            // NULL parameter — accepted and skipped
+        } else {
+            return Err(Error::InvalidDer(
+                "unsupported AlgorithmIdentifier parameters",
+            ));
+        }
+    }
+
+    let algorithm = Algorithm::from_oid(&oid_string).map_err(|_| Error::UnsupportedAlgorithm)?;
+
+    Ok((algorithm, outer.bytes_read))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pq_oid::{MlDsa, MlKem, SlhDsa};
+
+    #[test]
+    fn test_roundtrip_ml_kem_512() {
+        let alg = Algorithm::MlKem(MlKem::Kem512);
+        let mut buf = Vec::new();
+        encode_algorithm_identifier(alg, &mut buf);
+        let (decoded, bytes_read) = decode_algorithm_identifier(&buf, 0).unwrap();
+        assert_eq!(decoded, alg);
+        assert_eq!(bytes_read, buf.len());
+    }
+
+    #[test]
+    fn test_roundtrip_ml_dsa_44() {
+        let alg = Algorithm::MlDsa(MlDsa::Dsa44);
+        let mut buf = Vec::new();
+        encode_algorithm_identifier(alg, &mut buf);
+        let (decoded, bytes_read) = decode_algorithm_identifier(&buf, 0).unwrap();
+        assert_eq!(decoded, alg);
+        assert_eq!(bytes_read, buf.len());
+    }
+
+    #[test]
+    fn test_roundtrip_slh_dsa_sha2_128s() {
+        let alg = Algorithm::SlhDsa(SlhDsa::Sha2_128s);
+        let mut buf = Vec::new();
+        encode_algorithm_identifier(alg, &mut buf);
+        let (decoded, bytes_read) = decode_algorithm_identifier(&buf, 0).unwrap();
+        assert_eq!(decoded, alg);
+        assert_eq!(bytes_read, buf.len());
+    }
+
+    #[test]
+    fn test_roundtrip_all_algorithms() {
+        for alg in Algorithm::all() {
+            let mut buf = Vec::new();
+            encode_algorithm_identifier(alg, &mut buf);
+            let (decoded, bytes_read) = decode_algorithm_identifier(&buf, 0).unwrap();
+            assert_eq!(decoded, alg, "failed for {}", alg);
+            assert_eq!(bytes_read, buf.len());
+        }
+    }
+
+    #[test]
+    fn test_decode_with_null_parameter() {
+        let alg = Algorithm::MlKem(MlKem::Kem512);
+        let mut buf = Vec::new();
+        encode_algorithm_identifier(alg, &mut buf);
+
+        // Manually add NULL parameter (0x05 0x00) inside the SEQUENCE
+        // We need to rebuild: SEQUENCE { OID, NULL }
+        let mut oid_bytes = Vec::new();
+        pq_oid::encode_oid_to(alg.oid(), &mut oid_bytes).unwrap();
+
+        let mut inner = Vec::new();
+        inner.push(0x06); // OID tag
+        super::super::length::encode_length(oid_bytes.len(), &mut inner);
+        inner.extend_from_slice(&oid_bytes);
+        inner.extend_from_slice(&[0x05, 0x00]); // NULL
+
+        let mut with_null = Vec::new();
+        with_null.push(0x30); // SEQUENCE
+        super::super::length::encode_length(inner.len(), &mut with_null);
+        with_null.extend_from_slice(&inner);
+
+        let (decoded, _) = decode_algorithm_identifier(&with_null, 0).unwrap();
+        assert_eq!(decoded, alg);
+    }
+
+    #[test]
+    fn test_decode_unsupported_parameters() {
+        let alg = Algorithm::MlKem(MlKem::Kem512);
+
+        let mut oid_bytes = Vec::new();
+        pq_oid::encode_oid_to(alg.oid(), &mut oid_bytes).unwrap();
+
+        let mut inner = Vec::new();
+        inner.push(0x06);
+        super::super::length::encode_length(oid_bytes.len(), &mut inner);
+        inner.extend_from_slice(&oid_bytes);
+        inner.extend_from_slice(&[0x04, 0x01, 0x00]); // OCTET STRING (unsupported)
+
+        let mut bad = Vec::new();
+        bad.push(0x30);
+        super::super::length::encode_length(inner.len(), &mut bad);
+        bad.extend_from_slice(&inner);
+
+        assert!(decode_algorithm_identifier(&bad, 0).is_err());
+    }
+}

packages/pq-key-encoder/rust/src/asn1/decode.rs

@@ -0,0 +1,113 @@
+use alloc::string::String;
+
+use crate::error::{Error, Result};
+
+use super::length::decode_length;
+
+/// A parsed TLV element borrowing from the input buffer.
+#[derive(Debug)]
+pub(crate) struct Tlv<'a> {
+    pub tag: u8,
+    pub value: &'a [u8],
+    pub bytes_read: usize,
+}
+
+/// Read one TLV element from input starting at offset.
+pub(crate) fn read_tlv(input: &[u8], offset: usize) -> Result<Tlv<'_>> {
+    if offset >= input.len() {
+        return Err(Error::InvalidDer("unexpected end of input"));
+    }
+
+    let tag = input[offset];
+    let (length, len_bytes) = decode_length(input, offset + 1)?;
+    let value_start = offset + 1 + len_bytes;
+
+    if value_start + length > input.len() {
+        return Err(Error::InvalidDer("truncated value"));
+    }
+
+    Ok(Tlv {
+        tag,
+        value: &input[value_start..value_start + length],
+        bytes_read: 1 + len_bytes + length,
+    })
+}
+
+/// Decode an OID from raw DER value bytes (without tag/length).
+/// Returns dotted notation string like "2.16.840.1.101.3.4.4.1".
+pub(crate) fn decode_oid(bytes: &[u8]) -> Result<String> {
+    Ok(pq_oid::decode_oid(bytes)?)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_read_tlv_simple() {
+        // OCTET STRING containing [0xAA, 0xBB]
+        let data = [0x04, 0x02, 0xAA, 0xBB];
+        let tlv = read_tlv(&data, 0).unwrap();
+        assert_eq!(tlv.tag, 0x04);
+        assert_eq!(tlv.value, &[0xAA, 0xBB]);
+        assert_eq!(tlv.bytes_read, 4);
+    }
+
+    #[test]
+    fn test_read_tlv_empty_value() {
+        let data = [0x05, 0x00]; // NULL
+        let tlv = read_tlv(&data, 0).unwrap();
+        assert_eq!(tlv.tag, 0x05);
+        assert_eq!(tlv.value, &[]);
+        assert_eq!(tlv.bytes_read, 2);
+    }
+
+    #[test]
+    fn test_read_tlv_with_offset() {
+        let data = [0xFF, 0xFF, 0x02, 0x01, 0x00];
+        let tlv = read_tlv(&data, 2).unwrap();
+        assert_eq!(tlv.tag, 0x02);
+        assert_eq!(tlv.value, &[0x00]);
+        assert_eq!(tlv.bytes_read, 3);
+    }
+
+    #[test]
+    fn test_read_tlv_sequence() {
+        // SEQUENCE { INTEGER 0 }
+        let data = [0x30, 0x03, 0x02, 0x01, 0x00];
+        let tlv = read_tlv(&data, 0).unwrap();
+        assert_eq!(tlv.tag, 0x30);
+        assert_eq!(tlv.value, &[0x02, 0x01, 0x00]);
+        assert_eq!(tlv.bytes_read, 5);
+    }
+
+    #[test]
+    fn test_read_tlv_error_empty() {
+        assert!(read_tlv(&[], 0).is_err());
+    }
+
+    #[test]
+    fn test_read_tlv_error_truncated() {
+        // Claims 3 bytes but only 2 available
+        let data = [0x04, 0x03, 0xAA, 0xBB];
+        assert!(read_tlv(&data, 0).is_err());
+    }
+
+    #[test]
+    fn test_read_tlv_error_offset_past_end() {
+        let data = [0x04, 0x01, 0xAA];
+        assert!(read_tlv(&data, 10).is_err());
+    }
+
+    #[test]
+    fn test_decode_oid_ml_kem_512() {
+        let bytes = [0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x04, 0x01];
+        let oid = decode_oid(&bytes).unwrap();
+        assert_eq!(oid, "2.16.840.1.101.3.4.4.1");
+    }
+
+    #[test]
+    fn test_decode_oid_invalid() {
+        assert!(decode_oid(&[]).is_err());
+    }
+}

packages/pq-key-encoder/rust/src/asn1/encode.rs

@@ -0,0 +1,88 @@
+use alloc::vec::Vec;
+
+use super::length::encode_length;
+use super::tags;
+
+/// Write a complete TLV (tag + length + value) to the buffer.
+pub(crate) fn encode_tlv(tag: u8, value: &[u8], out: &mut Vec<u8>) {
+    out.push(tag);
+    encode_length(value.len(), out);
+    out.extend_from_slice(value);
+}
+
+/// Write a SEQUENCE containing the given pre-encoded elements.
+pub(crate) fn encode_sequence(elements: &[&[u8]], out: &mut Vec<u8>) {
+    let total_len: usize = elements.iter().map(|e| e.len()).sum();
+    out.push(tags::TAG_SEQUENCE);
+    encode_length(total_len, out);
+    for element in elements {
+        out.extend_from_slice(element);
+    }
+}
+
+/// Write an OCTET STRING wrapping the given data.
+pub(crate) fn encode_octet_string(data: &[u8], out: &mut Vec<u8>) {
+    encode_tlv(tags::TAG_OCTET_STRING, data, out);
+}
+
+/// Write a BIT STRING with 0 unused bits wrapping the given data.
+pub(crate) fn encode_bit_string(data: &[u8], out: &mut Vec<u8>) {
+    out.push(tags::TAG_BIT_STRING);
+    encode_length(data.len() + 1, out);
+    out.push(0x00); // unused bits
+    out.extend_from_slice(data);
+}
+
+/// Write INTEGER 0 (version field for PKCS8). Fixed bytes: 02 01 00.
+pub(crate) fn encode_integer_zero(out: &mut Vec<u8>) {
+    out.extend_from_slice(&[0x02, 0x01, 0x00]);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_encode_tlv() {
+        let mut out = Vec::new();
+        encode_tlv(0x04, &[0x01, 0x02, 0x03], &mut out);
+        assert_eq!(out, [0x04, 0x03, 0x01, 0x02, 0x03]);
+    }
+
+    #[test]
+    fn test_encode_tlv_empty() {
+        let mut out = Vec::new();
+        encode_tlv(0x04, &[], &mut out);
+        assert_eq!(out, [0x04, 0x00]);
+    }
+
+    #[test]
+    fn test_encode_sequence() {
+        let elem1 = [0x02, 0x01, 0x00]; // INTEGER 0
+        let elem2 = [0x04, 0x02, 0xAA, 0xBB]; // OCTET STRING
+        let mut out = Vec::new();
+        encode_sequence(&[&elem1, &elem2], &mut out);
+        assert_eq!(out, [0x30, 0x07, 0x02, 0x01, 0x00, 0x04, 0x02, 0xAA, 0xBB]);
+    }
+
+    #[test]
+    fn test_encode_octet_string() {
+        let mut out = Vec::new();
+        encode_octet_string(&[0xDE, 0xAD], &mut out);
+        assert_eq!(out, [0x04, 0x02, 0xDE, 0xAD]);
+    }
+
+    #[test]
+    fn test_encode_bit_string() {
+        let mut out = Vec::new();
+        encode_bit_string(&[0xCA, 0xFE], &mut out);
+        assert_eq!(out, [0x03, 0x03, 0x00, 0xCA, 0xFE]);
+    }
+
+    #[test]
+    fn test_encode_integer_zero() {
+        let mut out = Vec::new();
+        encode_integer_zero(&mut out);
+        assert_eq!(out, [0x02, 0x01, 0x00]);
+    }
+}