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,#Bloband#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.