Use CBOR-based fingerprint serialization (#241)

Author: casey

README.md

@@ -879,41 +879,29 @@ of file hashing and verification.
 
 Filepack allows for the creation of Ed25519 signatures over the contents of a
 manifest, which thus commit to the contents of the directory covered by the
-manifest. Signatures are made not over serialized manifest, but over a message
-containing a "fingerprint" hash, a Merkle tree hash created from the contents
-of the manifest. This keeps signatures independent of the manifest format,
-avoids issues with canonicalization of the manifest JSON, avoids hash loops due
-to the inclusion of signatures in the manifest itself, and allows proving the
-inclusion of files covered by a signature using a Merkle receipt.
+manifest. Signatures are made over a message containing a "fingerprint" hash of
+a canonical CBOR serialization of the manifest. This keeps signatures
+independent of the manifest format, avoids issues with canonicalization of the
+manifest JSON, avoids hash loops due to the inclusion of signatures in the
+manifest itself, and allows proving the inclusion of files covered by a
+signature.
 
 ### Fingerprints
 
-Although only package fingerprints are exposed externally, several types of
-fingerprints are used internally, namely directory, entry, file, and message
-fingerprints.
-
-Fingerprints are constructed to be unique, both between and within types,
-meaning that it is impossible two different values with different types or
-contents but which have the same fingerprint.
-
-Fingerprints are BLAKE3 hashes. To guarantee that fingerprints are unique
-between types, the hasher is first initialized with a length-prefixed string
-unique to each type.
-
-After the prefix, the value is hashed as a sequence of TLV fields.
-
-Fields are hashed in order, but may be skipped, in the case of optional fields,
-or repeated, in the case of fields containing multiple values.
+Package fingerprints are the BLAKE3 hash of a canonical CBOR serialization of
+the contents of the manifest. Fingerprints are constructed to be unique,
+meaning meaning that it is impossible for two different packages with different
+contents to have the same fingerprint.
 
 Currently, no fingerprint test vectors exist, and the best documentation is the
 code itself.
 
 In particular, see:
 
-- [FingerprintHasher](src/fingerprint_hasher.rs)
-- [FingerprintPrefix](src/fingerprint_prefix.rs)
 - [Manifest](src/manifest.rs)
 - [Directory](src/directory.rs)
 - [Entry](src/entry.rs)
 - [Files](src/file.rs)
 - [Message](src/message.rs)
+
+And the [cbor](src/cbor.rs) module for the encoding.

src/cbor.rs

@@ -0,0 +1,29 @@
+use super::*;
+
+pub(crate) use self::{
+  directory::Directory, encode::Encode, encoder::Encoder, entry::Entry, entry_type::EntryType,
+  head::Head, major_type::MajorType, map_encoder::MapEncoder, version::Version,
+};
+
+#[cfg(test)]
+pub(crate) use self::{
+  decode::Decode, decode_error::DecodeError, decoder::Decoder, map_decoder::MapDecoder,
+};
+
+#[cfg(test)]
+mod decode;
+#[cfg(test)]
+pub(crate) mod decode_error;
+#[cfg(test)]
+mod decoder;
+mod directory;
+mod encode;
+mod encoder;
+mod entry;
+mod entry_type;
+mod head;
+mod major_type;
+#[cfg(test)]
+mod map_decoder;
+mod map_encoder;
+mod version;

src/cbor/decode.rs

@@ -0,0 +1,60 @@
+use super::*;
+
+pub(crate) trait Decode: Sized {
+  fn decode(decoder: &mut Decoder) -> Result<Self, DecodeError>;
+}
+
+impl<K, V> Decode for BTreeMap<K, V>
+where
+  K: Clone + Decode + Debug + Ord + PartialOrd,
+  V: Decode,
+{
+  fn decode(decoder: &mut Decoder) -> Result<Self, DecodeError> {
+    let mut decoder = decoder.map::<K>()?;
+
+    let mut map = BTreeMap::new();
+    while let Some((key, value)) = decoder.next::<V>()? {
+      map.insert(key, value);
+    }
+
+    decoder.finish()?;
+
+    Ok(map)
+  }
+}
+
+impl Decode for String {
+  fn decode(decoder: &mut Decoder) -> Result<Self, DecodeError> {
+    Ok(decoder.text()?.to_owned())
+  }
+}
+
+impl Decode for Vec<u8> {
+  fn decode(decoder: &mut Decoder) -> Result<Self, DecodeError> {
+    Ok(decoder.bytes()?.to_vec())
+  }
+}
+
+impl Decode for u8 {
+  fn decode(decoder: &mut Decoder) -> Result<Self, DecodeError> {
+    decoder
+      .integer()?
+      .try_into()
+      .context(decode_error::IntegerRange)
+  }
+}
+
+impl Decode for u64 {
+  fn decode(decoder: &mut Decoder) -> Result<Self, DecodeError> {
+    decoder.integer()
+  }
+}
+
+impl Decode for usize {
+  fn decode(decoder: &mut Decoder) -> Result<Self, DecodeError> {
+    decoder
+      .integer()?
+      .try_into()
+      .context(decode_error::IntegerRange)
+  }
+}

src/cbor/decode_error.rs

@@ -0,0 +1,37 @@
+use super::*;
+
+#[derive(Debug, PartialEq, Snafu)]
+#[snafu(context(suffix(false)), visibility(pub(crate)))]
+pub(crate) enum DecodeError {
+  #[snafu(display("failed to parse component"))]
+  Component { source: ComponentError },
+  #[snafu(display("integer out of range"))]
+  IntegerRange { source: TryFromIntError },
+  #[snafu(display("map keys out of order"))]
+  KeyOrder,
+  #[snafu(display("overlong integer"))]
+  OverlongInteger,
+  #[snafu(display("reserved additional information value: {value}"))]
+  ReservedAdditionalInformation { value: u8 },
+  #[snafu(display("size out of range"))]
+  SizeRange { source: TryFromIntError },
+  #[snafu(display("trailing bytes"))]
+  TrailingBytes,
+  #[snafu(display("truncated"))]
+  Truncated,
+  #[snafu(display("unconsumed map entries"))]
+  UnconsumedEntries,
+  #[snafu(display("unexpected key"))]
+  UnexpectedKey,
+  #[snafu(display("expected {expected} but found {actual}"))]
+  UnexpectedType {
+    expected: MajorType,
+    actual: MajorType,
+  },
+  #[snafu(display("unexpected value"))]
+  UnexpectedValue,
+  #[snafu(display("string not valid unicode"))]
+  Unicode { source: Utf8Error },
+  #[snafu(display("unsupported additional information value: {value}"))]
+  UnsupportedAdditionalInformation { value: u8 },
+}

src/cbor/decoder.rs

@@ -0,0 +1,192 @@
+use super::*;
+
+pub(crate) struct Decoder {
+  buffer: Vec<u8>,
+  i: usize,
+}
+
+impl Decoder {
+  fn array<const N: usize>(&mut self) -> Result<[u8; N], DecodeError> {
+    Ok(self.slice(N)?.try_into().unwrap())
+  }
+
+  pub(crate) fn bytes(&mut self) -> Result<&[u8], DecodeError> {
+    let len = self
+      .expect(MajorType::Bytes)?
+      .try_into()
+      .context(decode_error::SizeRange)?;
+
+    self.slice(len)
+  }
+
+  fn expect(&mut self, expected: MajorType) -> Result<u64, DecodeError> {
+    let Head { major_type, value } = self.head()?;
+
+    ensure!(
+      major_type == expected,
+      decode_error::UnexpectedType {
+        actual: major_type,
+        expected,
+      }
+    );
+
+    Ok(value)
+  }
+
+  pub(crate) fn finish(self) -> Result<(), DecodeError> {
+    ensure!(self.i == self.buffer.len(), decode_error::TrailingBytes);
+    Ok(())
+  }
+
+  pub(crate) fn head(&mut self) -> Result<Head, DecodeError> {
+    let initial_byte = self.array::<1>()?[0];
+
+    let major_type = MajorType::from_initial_byte(initial_byte);
+
+    let additional_information = initial_byte & 0b11111;
+
+    let value = match additional_information {
+      0..24 => additional_information.into(),
+      24 => u8::from_be_bytes(self.array()?).into(),
+      25 => u16::from_be_bytes(self.array()?).into(),
+      26 => u32::from_be_bytes(self.array()?).into(),
+      27 => u64::from_be_bytes(self.array()?),
+      value @ 28..31 => {
+        return Err(decode_error::ReservedAdditionalInformation { value }.build());
+      }
+      value @ 31 => {
+        return Err(decode_error::UnsupportedAdditionalInformation { value }.build());
+      }
+      32..=u8::MAX => unreachable!(),
+    };
+
+    let min = match additional_information {
+      0..24 => 0,
+      24 => 24,
+      25 => 0x100,
+      26 => 0x1_0000,
+      27 => 0x1_0000_0000,
+      _ => unreachable!(),
+    };
+
+    ensure!(value >= min, decode_error::OverlongInteger);
+
+    Ok(Head { major_type, value })
+  }
+
+  pub(crate) fn integer(&mut self) -> Result<u64, DecodeError> {
+    self.expect(MajorType::Integer)
+  }
+
+  pub(crate) fn map<K>(&mut self) -> Result<MapDecoder<K>, DecodeError> {
+    let len = self.expect(MajorType::Map)?;
+    Ok(MapDecoder::new(self, len))
+  }
+
+  pub(crate) fn new(buffer: Vec<u8>) -> Self {
+    Self { buffer, i: 0 }
+  }
+
+  fn slice(&mut self, n: usize) -> Result<&[u8], DecodeError> {
+    let start = self.i;
+    let end = start + n;
+
+    ensure! {
+      end <= self.buffer.len(),
+      decode_error::Truncated,
+    }
+
+    self.i = end;
+
+    Ok(&self.buffer[start..end])
+  }
+
+  pub(crate) fn text(&mut self) -> Result<&str, DecodeError> {
+    let len = self
+      .expect(MajorType::Text)?
+      .try_into()
+      .context(decode_error::SizeRange)?;
+
+    str::from_utf8(self.slice(len)?).context(decode_error::Unicode)
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  #[test]
+  fn integer_range() {
+    assert!(matches!(
+      u8::decode(&mut Decoder::new(256u64.encode_to_vec())),
+      Err(DecodeError::IntegerRange { .. }),
+    ));
+  }
+
+  #[test]
+  fn overlong_integer() {
+    #[track_caller]
+    fn case(bytes: &[u8]) {
+      assert_eq!(
+        Decoder::new(bytes.to_vec()).head(),
+        Err(DecodeError::OverlongInteger),
+      );
+    }
+
+    case(&[0x18, 0x17]);
+    case(&[0x19, 0x00, 0xFF]);
+    case(&[0x1A, 0x00, 0x00, 0xFF, 0xFF]);
+    case(&[0x1B, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0xFF]);
+  }
+
+  #[test]
+  fn reserved_additional_information() {
+    assert_eq!(
+      Decoder::new(vec![0x1C]).head(),
+      Err(DecodeError::ReservedAdditionalInformation { value: 28 }),
+    );
+  }
+
+  #[test]
+  fn trailing_bytes() {
+    assert_eq!(
+      Decoder::new(vec![0x00]).finish(),
+      Err(DecodeError::TrailingBytes)
+    );
+  }
+
+  #[test]
+  fn truncated() {
+    assert_eq!(Decoder::new(vec![]).head(), Err(DecodeError::Truncated),);
+  }
+
+  #[test]
+  fn type_mismatch() {
+    assert_eq!(
+      Decoder::new(vec![0x60]).integer(),
+      Err(DecodeError::UnexpectedType {
+        expected: MajorType::Integer,
+        actual: MajorType::Text,
+      }),
+    );
+  }
+
+  #[test]
+  #[expect(invalid_from_utf8)]
+  fn unicode() {
+    assert_eq!(
+      Decoder::new(vec![0x62, 0xFF, 0xFE]).text().map(drop),
+      Err(DecodeError::Unicode {
+        source: str::from_utf8(&[0xFF, 0xFE]).unwrap_err()
+      }),
+    );
+  }
+
+  #[test]
+  fn unsupported_additional_information() {
+    assert_eq!(
+      Decoder::new(vec![0x1F]).head(),
+      Err(DecodeError::UnsupportedAdditionalInformation { value: 31 }),
+    );
+  }
+}