Skip to main content

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}