Skip to main content

Crate cildec

Crate cildec 

Source
Expand description

A zero-dependency decoder for ECMA-335 metadata and CIL method bodies.

cildec reads a managed PE image, or a bare metadata blob, and exposes its tables, heaps, signatures, method bodies and exception-handling tables as typed, bounds-checked Rust values. It then decodes CIL method bodies into a typed instruction stream with exact byte offsets and sizes, absolute branch targets, folded prefixes and the per-opcode static facts from ECMA-335 Partition VI, Annex C.

The normative reference throughout is ECMA-335, 6th edition (June 2012). Module documentation cites the partition and section each part implements.

§Design

  • Safe on hostile input. The crate is a parser of untrusted bytes. It forbids unsafe, has no reachable panic on any input, never allocates on the basis of a declared count without checking it against the bytes that remain, and never loops without making progress. This is enforced by fuzzing, not just by review.
  • Lazy. Opening an image parses headers and the table directory only. Heaps, signatures and method bodies are decoded when asked for.
  • Borrowing. Everything borrows the input &[u8]; row and instruction decoding copies only the few bytes of the value itself.
  • Deterministic. No hash-map iteration affects any output, so two runs over the same bytes produce identical results in identical order.

§Strictness

Real images deviate from ECMA-335. Strictness::Permissive, the default, accepts the deviations listed under DiagnosticCode and records each one so a consumer can decide what to do. Strictness::Strict rejects everything the specification rejects.

§Example

use cildec::{PeImage, MethodBody, Names};

let bytes = std::fs::read("Example.dll").unwrap();
let image = PeImage::parse(&bytes)?;
let metadata = image.metadata()?;
let names = Names::new(&metadata);

for (rid, row) in metadata.tables().iter::<cildec::tables::MethodDefRow>() {
    let row = row?;
    if metadata.strings().str_opt(row.name) != Some("Main") {
        continue;
    }
    let Some(body) = MethodBody::from_image(&image, &row)? else { continue };
    println!("{}", names.method_def_full(cildec::Rid::new(rid))?);
    for folded in body.folded_instructions() {
        let folded = folded?;
        let instruction = &folded.instruction;
        print!("  IL_{:04x}: {}", instruction.offset, instruction.opcode.name());
        if let Some(token) = instruction.operand.token() {
            print!(" {}", names.token(token));
        }
        println!();
    }
}

§What this crate does not do

It does not simulate the stack, build control-flow graphs, verify IL, check operand types, resolve across assemblies, decode custom-attribute or marshalling blobs, verify signatures, decode managed resources, interpret Portable PDB semantics, or write metadata. Ranges and raw blobs for those are exposed so that a consumer can do its own work.

Re-exports§

pub use compressed::read_i32 as read_compressed_i32;
pub use compressed::read_u32 as read_compressed_u32;
pub use body::ExceptionHandler;
pub use body::FatFlags;
pub use body::HandlerKind;
pub use body::HeaderKind;
pub use body::MethodBody;
pub use body::RawSection;
pub use display::Names;
pub use error::Diagnostic;
pub use error::DiagnosticCode;
pub use error::Error;
pub use error::ErrorKind;
pub use error::Result;
pub use error::Strictness;
pub use heaps::BlobHeap;
pub use heaps::Guid;
pub use heaps::GuidHeap;
pub use heaps::StringsHeap;
pub use heaps::UserString;
pub use heaps::UserStringsHeap;
pub use il::FlowControl;
pub use il::FoldedInstruction;
pub use il::FoldedIter;
pub use il::Instruction;
pub use il::InstructionIter;
pub use il::NoChecks;
pub use il::OpCode;
pub use il::OpCodeInfo;
pub use il::OpCodeKind;
pub use il::Operand;
pub use il::OperandKind;
pub use il::Prefixes;
pub use il::StackBehaviourPop;
pub use il::StackBehaviourPush;
pub use metadata::Metadata;
pub use metadata::StreamHeader;
pub use pe::CliFlags;
pub use pe::CliHeader;
pub use pe::DataDirectory;
pub use pe::EntryPoint;
pub use pe::PeImage;
pub use pe::Section;
pub use signature::ArrayShape;
pub use signature::CallConv;
pub use signature::CustomMod;
pub use signature::FieldSig;
pub use signature::LocalVar;
pub use signature::LocalVarSig;
pub use signature::MethodSig;
pub use signature::MethodSpecSig;
pub use signature::Param;
pub use signature::PropertySig;
pub use signature::SignatureOptions;
pub use signature::Type;
pub use signature::TypeSpecSig;
pub use tables::CodedIndex;
pub use tables::ColumnKind;
pub use tables::TableLayout;
pub use tables::TableRow;
pub use tables::Tables;
pub use token::BlobIndex;
pub use token::GuidIndex;
pub use token::Rid;
pub use token::StringIndex;
pub use token::TableId;
pub use token::Token;
pub use token::UserStringToken;
pub use token::marker;

Modules§

body
Method bodies and exception-handling tables (ECMA-335 II.25.4).
compressed
Compressed integer encoding used by metadata blobs (ECMA-335 II.23.2).
display
Readable names for tokens and signatures.
error
Error and diagnostic types.
heaps
The four metadata heaps: #Strings, #US, #Blob and #GUID (II.24.2.2–II.24.2.4).
il
The CIL instruction decoder (ECMA-335 Partition III, Partition VI Annex C).
metadata
The metadata root and its streams (ECMA-335 II.24.2.1, II.24.2.2).
pe
The PE/COFF container that carries a managed image (ECMA-335 II.25).
signature
Blob signatures (ECMA-335 II.23.1.16, II.23.2).
tables
The metadata table stream: #~ (compressed) and #- (uncompressed).
token
Metadata tokens, row identifiers, and heap indices (ECMA-335 II.22, II.24.2.6).

Functions§

read_file
Reads a file and parses it as a managed PE image.