MicroSEH 🔴

MicroSEH is a tiny library that implements Structured Exception Handling (SEH) in Rust and can catch

and handle hardware exceptions.

Why?

Hardware exceptions are a very powerful tool for specific use cases. One such use case is to detect and handle illegal instructions at runtime.

Implementation

It turns out that implementing SEH in pure Rust has its own issues (as seen in this article from NAMAZSO) This library uses a different, simpler approach, which is to use a C stub that calls back into Rust, wrapping the call in a try except block.

Usage

Add this to your Cargo.toml:

[dependencies]
microseh = "1.2"

Minimal Example: Dereference an invalid pointer without crashing the program, and return the handled exception.

fn guarded() -> Result<(), microseh::Exception> {
    microseh::try_seh(|| unsafe {
        // Read from an unallocated memory region. (we create an aligned not-null
        // pointer to skip the checks in read_volatile that would raise a panic)
        core::ptr::readvolatile(core::mem::alignof::<i32>() as *const i32);
    })
}

Accessing Exception Data: You can obtain the address and register dump of an exception.

if let Err(ex) = microseh::try_seh(|| unsafe {
    // questionable life choices go here
}) {
    println!("address: {:x}", ex.address());
    println!("rax: {:x}", ex.registers().rax());
}

For additional examples and practical use cases, please visit the examples directory!_

Portability

SEH is an extension to the C language developed by Microsoft, and it is exclusively available on Windows when using Microsoft Visual C++ (MSVC). MicroSEH is compatible with and has been tested on Windows platforms with the following architectures: x86, x86_64 and aarch64. When building for other unsupported platforms, the library will disable exception handling and panic when try_seh is called.

Usage on Kernel Drivers

This library can compile to no_std and supports running in Windows Kernel Drivers using Microsoft's windows-drivers-rs project.

Cross-Compiling

Cross-compiling for Windows is possible with full support for SEH using the cargo-xwin project.

License

This work is released under the MIT license. A copy of the license is provided in the LICENSE file.