https://github.com/sonodima/microseh

Structured Exception Handling (SEH) for Rust
https://github.com/sonodima/microseh

exceptions rust seh structured windows

Last synced: 12 days ago
JSON representation

Structured Exception Handling (SEH) for Rust

• Host: GitHub
• URL: https://github.com/sonodima/microseh
• Owner: sonodima
• License: mit
• Created: 2022-10-11T09:05:24.000Z (about 2 years ago)
• Default Branch: master
• Last Pushed: 2024-02-22T09:41:04.000Z (9 months ago)
• Last Synced: 2024-02-23T09:48:04.843Z (9 months ago)
• Topics: exceptions, rust, seh, structured, windows
• Language: Rust
• Homepage: https://docs.rs/microseh
• Size: 72.3 KB
• Stars: 20
• Watchers: 2
• Forks: 3
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
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](https://engineering.zeroitlab.com/2022/03/13/rust-seh))

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`:

```toml

[dependencies]

microseh = "1.1"

```

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

```rust

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::read_volatile(core::mem::align_of::() as *const i32);

    })

}

```

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

```rust

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](./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](https://github.com/microsoft/windows-drivers-rs) project.

## Cross-Compiling

Cross-compiling for Windows is possible with full support for SEH using the

[cargo-xwin](https://github.com/rust-cross/cargo-xwin) project.

## License

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

[LICENSE](./LICENSE) file.