Skip to main content

ahu/
verify.rs

1use sha2::{Digest, Sha256};
2
3use crate::bundle::Bundle;
4use crate::error::{AhuError, Result};
5use crate::index::validate_sort_order;
6
7/// Results of bundle verification.
8#[derive(Debug)]
9pub struct VerifyResult {
10    pub header_ok: bool,
11    pub manifest_ok: bool,
12    pub index_digest_ok: bool,
13    pub data_digest_ok: bool,
14    pub sort_order_ok: bool,
15    pub entry_bounds_ok: bool,
16    pub seal_present: bool,
17    pub entry_count_matches: bool,
18    pub warnings: Vec<String>,
19}
20
21/// Verify a bundle's structural integrity.
22///
23/// This checks everything *except* the CMS seal signature (which requires
24/// a trust anchor) and individual OCSP response signatures (which are
25/// expensive at scale and optional per §3.1 of the spec).
26/// The decoded manifest must agree with the encoded manifest before its
27/// digests or metadata can be used by a caller.
28pub fn verify_structure(bundle: &Bundle) -> Result<VerifyResult> {
29    let manifest = crate::manifest::Manifest::from_cbor(&bundle.manifest_bytes)?;
30    // Bundle exposes both representations publicly. Compare their normalized
31    // encodings so accepted CBOR encodings and NaN extension values remain
32    // usable, without allowing unsigned changes to the decoded fields. CMS
33    // verification still authenticates the original manifest_bytes verbatim.
34    if manifest.to_cbor() != bundle.manifest.to_cbor() {
35        return Err(AhuError::ManifestField(
36            "decoded manifest does not match manifest bytes".into(),
37        ));
38    }
39
40    let mut result = VerifyResult {
41        header_ok: true,
42        manifest_ok: true,
43        index_digest_ok: false,
44        data_digest_ok: false,
45        sort_order_ok: false,
46        entry_bounds_ok: true,
47        seal_present: !bundle.seal_bytes.is_empty(),
48        entry_count_matches: false,
49        warnings: Vec::new(),
50    };
51
52    // Verify index digest.
53    let mut index_bytes = Vec::new();
54    for record in &bundle.index {
55        record.write_to(&mut index_bytes)?;
56    }
57    let computed_index_digest: [u8; 32] = Sha256::digest(&index_bytes).into();
58    result.index_digest_ok = computed_index_digest == manifest.integrity.index_digest;
59    if !result.index_digest_ok {
60        return Err(AhuError::IndexDigestMismatch {
61            expected: hex::encode(manifest.integrity.index_digest),
62            actual: hex::encode(computed_index_digest),
63        });
64    }
65
66    // Verify data digest.
67    let computed_data_digest: [u8; 32] = Sha256::digest(&bundle.data).into();
68    result.data_digest_ok = computed_data_digest == manifest.integrity.data_digest;
69    if !result.data_digest_ok {
70        return Err(AhuError::DataDigestMismatch {
71            expected: hex::encode(manifest.integrity.data_digest),
72            actual: hex::encode(computed_data_digest),
73        });
74    }
75
76    // Verify sort order.
77    validate_sort_order(&bundle.index)?;
78    result.sort_order_ok = true;
79
80    // Verify entry count.
81    result.entry_count_matches = bundle.index.len() as u64 == manifest.entry_count;
82    if !result.entry_count_matches {
83        result.warnings.push(format!(
84            "entry_count in manifest ({}) does not match index record count ({})",
85            manifest.entry_count,
86            bundle.index.len()
87        ));
88    }
89
90    // Verify entry bounds (each record's offset+length within the data section).
91    for record in &bundle.index {
92        if record.is_tombstone() {
93            continue;
94        }
95        if bundle.entry_bytes(record).is_none() {
96            result.entry_bounds_ok = false;
97            return Err(AhuError::EntryOutOfBounds {
98                offset: record.data_offset,
99                length: record.data_length,
100            });
101        }
102    }
103
104    // Check for delta-specific requirements.
105    if manifest.bundle_type == crate::manifest::BundleType::Delta
106        && manifest.continuity.base_manifest_digest.is_none()
107    {
108        return Err(AhuError::DeltaMissingBase);
109    }
110
111    // Warn about missing seal.
112    if !result.seal_present {
113        result.warnings.push("seal section is empty".into());
114    }
115
116    Ok(result)
117}
118
119/// Compute the SHA-256 digest of the manifest bytes.
120pub fn manifest_digest(manifest_bytes: &[u8]) -> [u8; 32] {
121    Sha256::digest(manifest_bytes).into()
122}
123
124/// Check epoch high-water marks. Returns errors for any rollback attempt.
125pub fn check_epochs(
126    bundle: &Bundle,
127    high_water_marks: &std::collections::HashMap<(String, Vec<u8>), u64>,
128) -> Result<()> {
129    for scope in &bundle.manifest.ca_scopes {
130        let key = (
131            bundle.manifest.producer_id.clone(),
132            scope.issuer_key_hash.clone(),
133        );
134        if let Some(&hw) = high_water_marks.get(&key) {
135            if scope.epoch <= hw {
136                return Err(AhuError::EpochRollback {
137                    scope: hex::encode(&scope.issuer_key_hash),
138                    epoch: scope.epoch,
139                    high_water: hw,
140                });
141            }
142        }
143    }
144    Ok(())
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150    use crate::bundle::BundleBuilder;
151    use crate::manifest::*;
152    use sha2::Sha256;
153    use uuid::Uuid;
154
155    fn test_manifest() -> Manifest {
156        Manifest {
157            format_version: 1,
158            bundle_id: Uuid::nil(),
159            producer_id: "test".into(),
160            created_at: 1700000000,
161            bundle_type: BundleType::Full,
162            ca_scopes: vec![CaScope {
163                hash_algorithm: vec![0x01],
164                issuer_name_hash: vec![0xAA; 32],
165                issuer_key_hash: vec![0xBB; 32],
166                epoch: 5,
167                responder_id: ResponderId {
168                    id_type: ResponderIdType::ByKey,
169                    value: vec![0xCC; 20],
170                },
171                responder_chain: None,
172                signature_algorithm: vec![0x02],
173                completeness: Completeness::AuthoritativeComplete,
174            }],
175            window: Window {
176                produced_at: 1700000000,
177                this_update_min: 1700000000,
178                next_update_min: 1700086400,
179                next_update_max: 1700093600,
180            },
181            integrity: Integrity {
182                index_digest: [0; 32],
183                data_digest: [0; 32],
184            },
185            entry_count: 0,
186            continuity: Continuity {
187                prev_manifest_digest: None,
188                base_manifest_digest: None,
189                chain_length: 0,
190            },
191            shard: None,
192            compression: None,
193            extensions: None,
194        }
195    }
196
197    #[test]
198    fn verify_valid_bundle() {
199        let mut builder = BundleBuilder::new(test_manifest());
200        builder.add_entry([0xAA; 32], b"response".to_vec());
201
202        let bytes = builder.build(|m| Ok(Sha256::digest(m).to_vec())).unwrap();
203
204        let bundle = Bundle::from_bytes(&bytes).unwrap();
205        let result = verify_structure(&bundle).unwrap();
206        assert!(result.index_digest_ok);
207        assert!(result.data_digest_ok);
208        assert!(result.sort_order_ok);
209        assert!(result.entry_bounds_ok);
210        assert!(result.entry_count_matches);
211    }
212
213    fn bundle_with_manifest(manifest: Manifest) -> Bundle {
214        let mut builder = BundleBuilder::new(manifest);
215        builder.add_entry([0xAA; 32], b"response".to_vec());
216        Bundle::from_bytes(&builder.build(|m| Ok(Sha256::digest(m).to_vec())).unwrap()).unwrap()
217    }
218
219    #[test]
220    fn verify_rejects_payload_and_decoded_digest_mismatches() {
221        let valid = bundle_with_manifest(test_manifest());
222        for section in ["data", "index"] {
223            let mut bundle = Bundle::from_bytes(&valid.to_bytes().unwrap()).unwrap();
224            match section {
225                "data" => {
226                    bundle.data[0] ^= 1;
227                    bundle.manifest.integrity.data_digest = Sha256::digest(&bundle.data).into();
228                }
229                "index" => {
230                    bundle.index[0].entry_key[0] ^= 1;
231                    let mut index = Vec::new();
232                    bundle.index[0].write_to(&mut index).unwrap();
233                    bundle.manifest.integrity.index_digest = Sha256::digest(&index).into();
234                }
235                _ => unreachable!(),
236            }
237            assert_eq!(bundle.manifest_bytes, valid.manifest_bytes);
238            let result = verify_structure(&bundle);
239            assert!(
240                matches!(result, Err(AhuError::ManifestField(_))),
241                "modified {section} accepted with an unsigned decoded digest: {result:?}"
242            );
243        }
244    }
245
246    #[test]
247    fn verify_rejects_decoded_metadata_mismatches() {
248        let valid = bundle_with_manifest(test_manifest());
249        for field in ["producer", "scope", "epoch", "window", "entry_count"] {
250            let mut bundle = Bundle::from_bytes(&valid.to_bytes().unwrap()).unwrap();
251            match field {
252                "producer" => bundle.manifest.producer_id = "other".into(),
253                "scope" => bundle.manifest.ca_scopes[0].issuer_key_hash[0] ^= 1,
254                "epoch" => bundle.manifest.ca_scopes[0].epoch += 1,
255                "window" => bundle.manifest.window.next_update_min += 1,
256                "entry_count" => bundle.manifest.entry_count += 1,
257                _ => unreachable!(),
258            }
259            assert_eq!(bundle.manifest_bytes, valid.manifest_bytes);
260            let result = verify_structure(&bundle);
261            assert!(
262                matches!(result, Err(AhuError::ManifestField(_))),
263                "decoded {field} mismatch accepted: {result:?}"
264            );
265        }
266    }
267
268    #[test]
269    fn verify_accepts_equivalent_manifest_encoding() {
270        let mut bundle = bundle_with_manifest(test_manifest());
271        let mut value: ciborium::Value =
272            ciborium::from_reader(bundle.manifest_bytes.as_slice()).unwrap();
273        let ciborium::Value::Map(ref mut entries) = value else {
274            panic!("test manifest must be a map");
275        };
276        entries.reverse();
277        bundle.manifest_bytes.clear();
278        ciborium::into_writer(&value, &mut bundle.manifest_bytes).unwrap();
279
280        let parsed = Bundle::from_bytes(&bundle.to_bytes().unwrap()).unwrap();
281        assert_eq!(parsed.manifest, bundle.manifest);
282        assert_ne!(parsed.manifest_bytes, parsed.manifest.to_cbor());
283        verify_structure(&parsed).unwrap();
284    }
285
286    #[test]
287    fn verify_accepts_parsed_nan_extensions_but_rejects_changed_values() {
288        let mut manifest = test_manifest();
289        manifest.extensions = Some(vec![("test".into(), ciborium::Value::Float(f64::NAN))]);
290        let mut bundle = bundle_with_manifest(manifest);
291        // Manifest's derived PartialEq is non-reflexive for NaN. A consistently
292        // parsed extension must still be accepted by structural verification.
293        verify_structure(&bundle).unwrap();
294        bundle.manifest.extensions.as_mut().unwrap()[0].1 = ciborium::Value::Float(0.0);
295        let result = verify_structure(&bundle);
296        assert!(
297            matches!(result, Err(AhuError::ManifestField(_))),
298            "changed decoded extension accepted: {result:?}"
299        );
300    }
301
302    #[test]
303    fn epoch_rollback_rejected() {
304        let mut builder = BundleBuilder::new(test_manifest());
305        builder.add_entry([0xAA; 32], b"response".to_vec());
306
307        let bytes = builder.build(|m| Ok(Sha256::digest(m).to_vec())).unwrap();
308
309        let bundle = Bundle::from_bytes(&bytes).unwrap();
310
311        let mut hw = std::collections::HashMap::new();
312        hw.insert(("test".to_string(), vec![0xBB; 32]), 5);
313
314        let err = check_epochs(&bundle, &hw).unwrap_err();
315        assert!(matches!(err, AhuError::EpochRollback { .. }));
316    }
317}