Crate ewf_image

Expand description

Rust library for reading and writing Expert Witness Format forensic images.

ewf_image provides direct Rust APIs for working with Expert Witness Format images. It can open physical, logical, SMART, and EWF2 segment families, expose metadata and stored hashes, read the logical media stream, walk logical single-file catalogs, and create EWF output. An optional acquisition CLI is available; a filesystem mount layer is not currently implemented.

§Terminology

Logical media size is the decoded byte length exposed by Image::media_size and ImageInfo::logical_size. Segment set size is the total byte length of the opened EWF container files, as reported by Image::segment_set_size. Chunks are the stored allocation units used by EWF tables. Logical EWF images can also contain a single-file catalog, where each entry describes a file-like object stored inside the image.

§Supported container families

EWF1 physical .E01 / EVF images.
X-Ways AES-128/AES-256 encrypted EWF1 images.
EWF1 logical .L01 / LVF images.
EWF1 SMART .S01 images.
EWF2 physical .Ex01 images.
EWF2 logical .Lx01 images.

§Reading

use std::io::Read;

fn main() -> ewf_image::Result<()> {
    let image = ewf_image::Image::open("case.E01")?;
    let info = image.info();

    println!("{:?}: {} bytes", info.format, info.logical_size);
    println!("segments: {}", image.number_of_segments());

    let mut sector = vec![0; 512];
    image.cursor().read_exact(&mut sector)?;

    let mut later_sector = vec![0; 512];
    image.read_at(&mut later_sector, 4096)?;

    Ok(())
}

Password-protected X-Ways EWF1 images use the same read APIs after a password-aware open:

fn main() -> ewf_image::Result<()> {
    let password = ewf_image::EwfPassword::utf8("operator-supplied-password");
    let image = ewf_image::Image::open_with_password("case.E01", &password)?;
    println!("{:?}", image.encryption_info());
    Ok(())
}

§Metadata and hashes

fn main() -> ewf_image::Result<()> {
    let image = ewf_image::Image::open("case.E01")?;

    if let Some(case_number) = image.header_value("case_number") {
        println!("case: {case_number}");
    }

    if let Some(md5) = image.hash_value("MD5") {
        println!("stored MD5: {md5}");
    }

    #[cfg(feature = "verify")]
    {
        let verification = image.verify()?;
        println!("MD5 match: {:?}", verification.md5_match);
        println!("SHA1 match: {:?}", verification.sha1_match);
    }

    Ok(())
}

§Writing

use std::fs::File;

fn main() -> ewf_image::Result<()> {
    let mut input = File::open("disk.raw")?;

    let mut options = ewf_image::WriteOptions::default();
    options.format = ewf_image::WriteFormat::Ewf2Physical;
    options.compression = ewf_image::WriteCompression::Zlib;
    options.metadata.set_header_value("case_number", "CASE-001");

    let mut writer = ewf_image::EwfWriter::create("case.Ex01", options)?;
    std::io::copy(&mut input, &mut writer)?;
    writer.finish()?;

    Ok(())
}

§Streaming acquisition

AcquisitionWriter seals physical E01 segments as input arrives and can resume sealed checkpoints without rewriting them. It requires a known, sector-aligned source size and a filesystem supporting hard links.

use std::fs::File;
use std::ops::ControlFlow;
use ewf_image::{AcquisitionOptions, AcquisitionReadOptions, AcquisitionStatus, AcquisitionWriter};

fn continue_acquisition(source_identity: [u8; 32]) -> ewf_image::Result<()> {
    let mut input = File::open("disk.raw")?;
    let options = AcquisitionOptions::new(input.metadata()?.len());
    // Use create instead of resume for the first acquisition session.
    // The caller must bind source_identity to a stable source snapshot.
    let mut writer = AcquisitionWriter::resume("case.E01", &options, source_identity)?;
    let outcome = writer.acquire_with_progress(
        &mut input, &AcquisitionReadOptions::default(), |progress| {
            println!("{} accepted; {} checkpointed", progress.bytes_written, progress.checkpoint_bytes);
            // Return Break(()) when the application's cancellation flag is set.
            ControlFlow::Continue(())
        }
    )?;
    if outcome.status == AcquisitionStatus::Complete {
        writer.finish()?;
    }
    Ok(())
}

§Feature flags

verify is enabled by default and adds Image::verify() plus VerifyResult for streamed MD5/SHA1 verification. Stored hash parsing, EWF2 section integrity checks, and writer hash support are available without this feature.
external-fixtures enables ignored integration tests that require local EWF corpora and external EWF tools. It does not change library behavior.
fuzzing exposes the logical catalog parser to the isolated fuzz workspace.
parallel enables multiple decompression workers for verification and analysis. It implies verify; scans remain single-threaded by default.
serde enables serialization of analysis, verification, recovery, and section-summary results.

§Analysis and recovery

Image::sections exposes descriptor locations. Image::open_sources accepts SegmentSource backings with independent positioned reads. With verify, verify_with_options computes SHA256 and compares external references; analyze returns typed findings and explicit media coverage. EwfRecovery separately recovers physical raw/zlib EWF1 data with provenance and exclusive creation of output files.

§Limitations

X-Ways encrypted EWF1 reading is supported. Encrypted EWF2 images are detected and rejected, and encrypted writing is not implemented. Secondary/shadow target mirroring is supported by the file-backed writer. Base-plus-overlay delta/shadow images are not implemented.

Structs§

AcquisitionCheckpoint: Snapshot of a stopped acquisition.
AcquisitionError: Acquisition error range recorded in image metadata.
AcquisitionOperationProgress: Progress for one validation, rehash, or publication phase.
AcquisitionOptions: Configuration for a new, single-destination physical E01 acquisition. The source size must be known, nonzero, and a multiple of the sector size.
AcquisitionOutcome: Source-acquisition outcome. Publication remains an explicit finish step.
AcquisitionProgress: Source progress delivered synchronously on the acquiring thread.
AcquisitionReadOptions: Source-reading policy; it can be changed between calls or after resume. Previously substituted sectors and their provenance are never rewritten.
AcquisitionWriter: Append-only physical E01 writer with resumable sealed segments.
CompressionFlags: Compression flags recorded in EWF metadata.
CompressionValues: Compression level and flags recorded together.
ComputedHashes: Hashes over every logical media byte, excluding final-chunk padding.
DataChunk: Decoded logical data chunk.
EncodedDataChunk: Encoded data chunk as stored in an EWF segment.
EncryptionInfo: Non-secret encryption status for an opened EWF image.
EwfMetadata: Parsed case and acquisition metadata.
EwfPassword: Password bytes supplied for one encrypted EWF image open attempt.
EwfRecovery: Read-only recovery plan for physical, unencrypted raw/zlib EWF1 segments.
EwfWriter: Incremental EWF writer.
HashComparison: One comparison; external references never replace embedded references.
Image: Opened EWF image and logical media reader.
ImageCursor: Seekable cursor over an Image logical media stream.
ImageInfo: Parsed summary of an opened EWF image.
IntegrityFinding: One finding with optional source and logical locations.
IntegrityReport: Bounded integrity findings plus explicit scan coverage.
LogicalEntryMetadata: Caller-supplied metadata for a logical acquisition entry.
LogicalWriteProgress: Progress within the file currently being added.
LogicalWriter: Builds an L01/Lx01 catalog and file hashes while accepting file streams.
MediaFlags: Media flags recorded for an image.
MediaInfo: Parsed media geometry and storage metadata.
MemoryExtent: Memory acquisition extent recorded in pages.
OpenOptions: Options that control how an image is opened and read.
ReaderCacheInfo: Configured and observed payload bytes for one shared EWF reader cache set.
ReaderStatistics: Cumulative performance counters for one shared EWF image reader.
RecoveryNotice: Structural damage or missing metadata encountered while locating recoverable data.
RecoveryOptions: Controls recovery output size, suspect-data handling, and report retention.
RecoveryProgress: Streaming recovery progress. The initial event has no last status.
RecoveryRange: Consecutive chunks sharing the same recovery outcome.
RecoveryReport: Completed recovery accounting. Recovery does not establish image authenticity.
SectionInfo: A section’s location in its original segment. Payloads are not retained. These are the descriptors accepted during opening, not a fresh integrity check.
SectorRange: Inclusive start plus count sector range.
SegmentFileVersion: EWF2 segment file version.
SegmentSource: A bounded view of a positioned backing, memory buffer, or file.
SequentialOptions: Settings for a known-length, append-only EWF1 physical or EWF2 write.
SequentialWriter: Streams EWF1 physical or EWF2 payload into staged native segments without a full raw spool.
SingleFileAttribute: Extended attribute for a logical single-file entry.
SingleFileCursor: Seekable cursor over one logical single-file catalog entry.
SingleFileEntry: Entry in a logical single-file catalog.
SingleFileExtent: Data extent for a logical single-file entry.
SingleFilePermission: Access-control entry for a logical single-file entry.
SingleFilePermissionGroup: Access-control group for logical single-file entries.
SingleFileProgress: Progress over one file’s bytes, including sparse zeroes.
SingleFileSource: Source record for logical single-file metadata.
SingleFileSubject: Subject record for logical single-file metadata.
SingleFileVerification: Completed file-level verification; never certifies the whole container.
SingleFilesAuxTables: Preserved auxiliary EWF2 single-file tables.
SingleFilesInfo: Logical single-file catalog metadata.
StoredHashes: Stored hash values parsed from an image.
VerificationReport: Completed media verification. Mismatches are results, not I/O errors.
VerifyOptions: Options shared by verification and media integrity analysis.
VerifyProgress: Progress delivered on the calling thread, in logical order.
VerifyResult: Result of streamed logical media hash verification.
WriteCompressionValues: Compression settings for writer output.
WriteHashes: Hash values configured for writer output.
WriteMediaProfile: Media type and acquisition flags configured for writer output.
WriteOptions: Configuration used to create an EwfWriter.
WriteResult: Result returned after finalizing writer output.

Enums§

AcquisitionOperationPhase: Long-running checkpoint or publication operation currently in progress.
AcquisitionStatus: Why a source acquisition call returned successfully.
ChunkCacheCapacity: Capacity policy for the decoded-chunk cache.
CompressionLevel: Compression level recorded in EWF metadata.
CompressionMethod: Compression method recorded for stored chunks.
DataChunkEncoding: Encoding used for a data chunk payload.
EncryptionMethod: Encryption method applied to an opened EWF image.
EwfError: Error type used by EWF readers, writers, and probe helpers.
Format: Top-level EWF container generation.
FormatProfile: Producer/profile inferred from EWF metadata and section layout.
HashAlgorithm: Digest algorithm used in a comparison.
HashReference: Origin of a reference digest.
HeaderCodepage: Codepage used for EWF1 textual header values.
HeaderDateFormat: Formatting applied when returning parsed EWF header date values.
IntegrityFindingKind: Stable categories for findings; diagnostic text is not a machine interface.
IntegritySeverity: Severity of a reported integrity condition.
MediaScanStatus: Coverage of the logical media pass, separate from the findings’ severity.
MediaType: Media type recorded for an image.
OpenStrictness: Strictness used while opening an image.
RecoveryStatus: Provenance of one recovered logical chunk.
SectionKind: On-disk section identifier, preserving unknown producer-defined types.
SingleFileEntryType: Type of a logical single-file catalog entry.
UnreadableSectorPolicy: Treatment of a sector that remains unreadable after its retries.
WriteCompression: Compression method for writer output.
WriteCompressionLevel: Compression level for writer output.
WriteFormat: Output EWF format selected for writing.

Constants§

SINGLE_FILE_PATH_SEPARATOR: Path separator used by EWF2 logical single-file catalogs.

Traits§

SegmentReadAt: A stable-length, thread-safe segment backing with independent positioned reads.
SegmentReader: Reader type accepted by Image::open_readers.

Functions§

analyze_path: Opens strictly, then scans media and redundant tables.
analyze_path_with_password: Password-aware counterpart to analyze_path. Password failures are reported without exposing password or key material.
analyze_path_with_progress: Opens strictly and analyzes with cooperative media-scan cancellation.
analyze_path_with_progress_and_password: Password-aware counterpart to analyze_path_with_progress.
check_file_corruption: Returns whether a single segment appears corrupt based on structural checks.
check_file_encryption: Returns whether a file appears to be an encrypted EWF segment.
check_file_signature: Returns whether a file starts with a recognized EWF segment signature.
check_segment_files_corruption: Returns whether a segment set appears corrupt based on structural checks.
check_segment_files_encryption: Returns whether any segment in a segment set appears to be encrypted.

Type Aliases§

Result: Result type returned by fallible ewf_image APIs.

Crate ewf_image

Crate ewf_image Copy item path

§Terminology

§Supported container families

§Reading

§Metadata and hashes

§Writing

§Streaming acquisition

§Feature flags

§Analysis and recovery

§Limitations

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate ewf_image