aff4_image/lib.rs
1//! Experimental AFF4 evidence streams, separate from the EWF format implementation.
2//!
3//! Supports ZIP AFF4 v1 physical ImageStreams and Maps, legacy AFF4-L 1.1,
4//! and a documented subset of the AFF4-L 2.1 draft. Reads never extract
5//! archive paths onto the host filesystem. Verification reports linear content,
6//! block/map structures, metadata digests, and byte provenance. Physical volume
7//! sets support assembled-image SHA256 and contextual metadata/block/map checks
8//! with explicit source attribution and caller-supplied stripe order. Neither
9//! internal hashes nor matching bytes establish independent authenticity.
10#![forbid(unsafe_code)]
11
12mod disk;
13mod reader;
14pub use disk::{DiskImageInfo, DiskImageReader};
15#[cfg(feature = "write")]
16mod writer;
17pub use reader::{
18 BackingVolume, ByteCoverage, CheckOutcome, Container, ContainerVerification, DiskImageSet,
19 IntegrityCheck, Limits, MetadataScan, MetadataVerification, PhysicalDisk, PhysicalDiskReader,
20 Property, ReaderCacheInfo, ReaderStatistics, ResourceVerification, SetDigest, SetVerification,
21 SetVolumeVerification, StreamInfo, Verification, VolumeSet, VolumeSource,
22};
23#[cfg(feature = "write")]
24pub use writer::{
25 AcquiredStream, CaseMetadata, CollectionIssue, CollectionLimits, CollectionOptions,
26 CollectionReport, Compression, LogicalMetadata, Profile, SubstreamKind, WriteOptions,
27 WriteResult, Writer,
28};
29
30/// AFF4 operation result.
31pub type Result<T> = std::result::Result<T, Error>;
32
33/// Malformed, unsupported, cancelled, or unreadable evidence.
34#[derive(Debug, thiserror::Error)]
35pub enum Error {
36 /// Finalized staging failed verification and was not published.
37 #[error("staged AFF4 container verification failed; inspect the retained verification report")]
38 VerificationFailed {
39 /// Complete available checks, resource errors and metadata diagnostics.
40 /// The temporary container is removed; this report retains the evidence
41 /// needed to distinguish mismatches, unreadable data and incomplete checks.
42 report: Box<ContainerVerification>,
43 },
44 /// Collection stopped before exceeding an explicit resource budget.
45 #[error("AFF4 collection limit {resource}: requires {required}, limit {limit}")]
46 ResourceLimit {
47 /// Budget name, matching the CLI report.
48 resource: &'static str,
49 /// Required bytes or count, including reserved final metadata.
50 required: u64,
51 /// Configured maximum bytes or count.
52 limit: u64,
53 },
54 /// Backing I/O error.
55 #[error(transparent)]
56 Io(#[from] std::io::Error),
57 /// Output was published, but synchronizing its parent directory failed.
58 /// Preserve the result and independently verify it before further use.
59 #[error("AFF4 output published at {path}, but directory synchronization failed: {source}", path = result.path.display())]
60 #[cfg(feature = "write")]
61 PublishedButUnsynced {
62 /// Published path and source digests; output must not be overwritten.
63 result: Box<WriteResult>,
64 /// Directory synchronization failure.
65 #[source]
66 source: std::io::Error,
67 },
68 /// ZIP structure or decoding error.
69 #[error(transparent)]
70 Zip(#[from] zip::result::ZipError),
71 /// Invalid metadata, offsets, or references.
72 #[error("malformed AFF4: {0}")]
73 Malformed(String),
74 /// Recognized feature outside this implementation's supported profile.
75 #[error("unsupported AFF4: {0}")]
76 Unsupported(String),
77 /// Cooperative cancellation.
78 #[error("operation cancelled")]
79 Aborted,
80}
81
82pub(crate) fn malformed(message: impl Into<String>) -> Error {
83 Error::Malformed(message.into())
84}