DOCSEARCHbyAlgolia
Submit Docs

windows-drivers-rs

repository·main·Indexed 23 days ago

https://github.com/microsoft/windows-drivers-rs

A collection of Rust crates and the cargo-wdk extension (v0.1.1) designed for Windows driver development. It supports WDM, KMDF, and UMDF models, providing tools for project scaffolding, building, packaging, and signing drivers. The toolkit includes crates such as wdk, wdk-sys, wdk-alloc, and wdk-panic to enable Rust integration within the Windows Driver Kit (WDK) environment.

Tokens
10.6K
Snippets
18
Records
79
Agent score
83%

What's inside windows-drivers-rs

  1. Configure driver signing and verification

    main

    The build command manages driver signing via the --sign-mode flag.

    Signing Modes:

    • test (default): Signs with a test certificate. The tool looks for a certificate named WDRLocalTestCert in the WDRTestCertStore. If not found, it automatically generates, adds, and uses a self-signed certificate.
    • off: Skips signing. Use this if you intend to use a separate toolchain for signing.

    Signature Verification: If you use the --verify-signature flag, the tool verifies the signature after the signing process.

    Important Requirements for Verification:

    1. You must manually add a copy of the signing certificate to the Trusted Root Certification Authorities store. The tool will not do this automatically for security reasons.
    2. You cannot combine --verify-signature with --sign-mode off. This will result in an error.

  2. Install the Sample KMDF Rust Driver on a DUT

    main

    Follow these steps to install the driver on your Device Under Test (DUT):

    1. Prepare Files

    Copy the following to the DUT:

    • The driver package folder from your Cargo Output Directory (e.g., target/<target-arch>-pc-windows-msvc/<profile>/package).
    • The devgen.exe utility from your WDK Developer Tools that matches the DUT architecture (e.g., C:\Program Files\Windows Kits\10\Tools\<version>\x64\devgen.exe).

    2. Install Certificates

    You must install the driver certificates into two specific stores on the DUT:

    1. Trusted Root Certification Authorities: Double-click the certificate -> Install Certificate -> Local Machine -> Place all certificates in the following store -> Browse -> Trusted Root Certification Authorities.
    2. Trusted Publishers: Repeat the process but select Trusted Publishers as the store.

    3. Install the Driver

    In the driver package directory, use pnputil.exe to add and install the INF file:

    pnputil.exe /add-driver sample_kmdf_driver.inf /install

    4. Create a Software Device

    Use devgen.exe to simulate the hardware by creating a software device with the required hardware ID:

    devgen.exe /add /hardwareid "root\SAMPLE_KMDF_HW_ID"

  3. Add windows-drivers-rs to Your Driver Package

    main

    Follow these steps to integrate windows-drivers-rs into a new Rust driver project:

    1. Initialize: Create a new library crate.
      cargo new <driver_name> --lib
    2. Dependencies: Add the necessary crates.
      cd <driver_name>
cargo add --build wdk-build
cargo add wdk wdk-sys wdk-alloc wdk-panic
    3. Crate Type: Set the crate type to cdylib in Cargo.toml:
      [lib]
crate-type = ["cdylib"]
    4. WDK Metadata: Configure the driver model in Cargo.toml. For example, for UMDF:
      [package.metadata.wdk.driver-model]
driver-type = "UMDF"
umdf-version-major = 1
target-umdf-version-minor = 33
    5. Build Script: Create a build.rs to configure the WDK binary build:
      fn main() -> Result<(), wdk_build::ConfigError> {
   wdk_build::configure_wdk_binary_build()
}
    6. Static CRT: Enable static CRT linkage in .cargo/config.toml:
      [build]
rustflags = ["-C", "target-feature=+crt-static"]
    7. Makefile: Add a Makefile.toml to enable driver packaging tasks:
      extend = "target/rust-driver-makefile.toml"

[config]
load_script = '''
#!@rust
//! ```cargo
//! [dependencies]
//! wdk-build = "0.5.1"
//! ```
#![allow(unused_doc_comments)]

wdk_build::cargo_make::load_rust_driver_makefile()?
'''
    8. INF File: Add an .inf file that matches the name of your cdylib crate.
    cargo new <driver_name> --lib
cd <driver_name>
cargo add --build wdk-build
cargo add wdk wdk-sys wdk-alloc wdk-panic

  5. Configure Kernel Mode (KMDF/WDM) Drivers

    main

    When developing Kernel Mode drivers (KMDF or WDM), you must apply these specific configurations:

    1. Panic Strategy: Set the panic strategy to abort in Cargo.toml for both dev and release profiles:
      [profile.dev]
panic = "abort"

[profile.release]
panic = "abort"
    2. No Standard Library: Mark your crate as no_std in lib.rs:
      #![no_std]
    3. Panic Handler: Add the wdk_panic crate in lib.rs:
      #[cfg(not(test))]
extern crate wdk_panic;
    4. Global Allocator (Optional): If you need to use the alloc modules, add the wdk_alloc allocator in lib.rs:
      #[cfg(not(test))]
use wdk_alloc::WdkAllocator;

#[cfg(not(test))]
#[global_allocator]
static GLOBAL_ALLOCATOR: WdkAllocator = WdkAllocator;
    #![no_std]

#[cfg(not(test))]
extern crate wdk_panic;

#[cfg(not(test))]
use wdk_alloc::WdkAllocator;

#[cfg(not(test))]
#[global_allocator]
static GLOBAL_ALLOCATOR: WdkAllocator = WdkAllocator;

  6. Install Build Requirements for windows-drivers-rs

    main

    To develop Windows drivers in Rust, you must satisfy the following requirements:

    1. LLVM/libclang: Required for binding generation via bindgen. Use winget to install LLVM version 17.0.6. Note: Do not use LLVM 18 as it has a bug affecting ARM64 bindings. Ensure you select the option to add LLVM to your PATH.
      winget install -i LLVM.LLVM --version 17.0.6 --force
    2. cargo-make: Used for post-build tasks like inf2cat and infverif.
      cargo install --locked cargo-make --no-default-features --features tls-native
    3. WDK Environment: You must be in a valid Windows Driver Kit (WDK) environment. The recommended method is to use an eWDK developer prompt.
    winget install -i LLVM.LLVM --version 17.0.6 --force

cargo install --locked cargo-make --no-default-features --features tls-native

  8. Install the Sample UMDF Rust Driver on a DUT

    main

    Follow these steps to install the driver on your Device Under Test (DUT):

    1. Copy Files to DUT

    Copy the following from your build machine to the DUT:

    • The driver package folder from your Cargo Output Directory (e.g., target/x86_64-pc-windows-msvc/debug/package or target/release/package).
    • The devgen.exe tool from your WDK Developer Tools that matches the DUT architecture (e.g., C:\Program Files\Windows Kits\10\Tools\<version>\x64\devgen.exe).

    2. Install Certificates

    You must install the driver certificates into the following stores on the DUT:

    1. Trusted Root Certification Authorities
    2. Trusted Publishers

    To install: Double-click the certificate -> Install Certificate -> Store Location: Local Machine -> Place all certificates in the following store -> Browse to the respective store -> OK -> Next -> Finish.

    3. Install the Driver via PnPUtil

    In the driver package directory, run:

    pnputil.exe /add-driver sample_umdf_driver.inf /install

    4. Create a Software Device

    In the directory where you copied devgen.exe, run the following to create the software device using the specific hardware ID:

    devgen.exe /add /hardwareid "root\\SAMPLE_UMDF_HW_ID"

  9. Install the Sample WDM Rust Driver on a DUT

    main

    Follow these steps to install the driver on your Device Under Test (DUT):

    1. Prepare Files

    Copy the following to the DUT:

    • The driver package folder from your Cargo Output Directory (e.g., <REPO_ROOT>/target/<target-triple>/<profile>/package).
    • The devgen.exe tool from your WDK Developer Tools that matches the DUT architecture (e.g., C:\Program Files\Windows Kits\10\Tools\<version>\x64\devgen.exe).

    2. Install Certificates

    Install the driver certificate on the DUT into two specific stores:

    1. Trusted Root Certification Authorities: Double-click certificate -> Install Certificate -> Local Machine -> Browse -> Trusted Root Certification Authorities -> Next -> Finish.
    2. Trusted Publishers: Repeat the process but select Trusted Publishers as the store location.

    3. Install Driver via PnPUtil

    In the driver package directory, run:

    pnputil.exe /add-driver sample_wdm_driver.inf /install

    4. Create Software Device

    In the directory where you copied devgen.exe, run:

    devgen.exe /add /hardwareid "root\SAMPLE_WDM_HW_ID"

  12. Use wdk-sys for direct WDK FFI bindings

    main

    The wdk-sys crate provides direct FFI bindings to the Windows Driver Kit (WDK) APIs. The available modules and types are conditionally compiled based on the driver_model__driver_type configuration (WDM, KMDF, or UMDF) and enabled features.

    Available Modules by Driver Model

    • WDM or KMDF: Provides ntddk module.
    • UMDF: Provides windows module.
    • KMDF or UMDF: Provides wdf module.

    Feature-based Modules

    If the corresponding feature is enabled, the following modules are also available for all driver models:

    • gpio
    • hid
    • parallel-ports
    • spb
    • storage
    • usb