Skip to content

C/C++ Runtime library for system file (Windows Kernel Driver) - Supports Microsoft STL

License

Notifications You must be signed in to change notification settings

ntoskrnl7/crtsys

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

97 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

crtsys

C/C++ Runtime library for system file (Windows Kernel Driver)

CMake GitHub GitHub release (latest SemVer) Windows 7+ Visual Studio 2017+ CMake 3.14+ C++ 14+ Architecture

[This document has been machine translated.]

crtsys is open source library that helps you use C++ CRT and STL features in your kernel drivers.

Overview

This project has the most support for C++ STL features among similar projects.

more

We investigated the functions that help us to use C++ and STL in the kernel driver, and among them, the best implemented project to use is as follows.

(22-04-26)

  • UCXXRT

    • Pros
    • Cons
      • Until now, only functions related to data types or data structures such as std::string and std::vector classes, which have little relevance to Win32 API, are supported.
      • Since vcxproj is dependent on the development environment, if the VS version changes, you have to manually modify it.
      • Hanging occurs on x86. this code
      • It seems that they copied Microsoft's source code as it is and put their own license comments at the top and included it in the project, and it does not seem to be free from licensing problems.
        • Changing the license and redistributing the Microsoft CRT and STL source code are not permitted.
  • KTL

    • Pros
      • CMake
        • Easy to create and automate project files suitable for development environment.
      • Independent implementation of all code including CRT
        • It is free from license, and the exception handling code part is lightweight, which can save the stack.
      • Provides a template library specialized for the kernel
        • Because it provides a template library for mechanisms that exist only in the kernel, there are many functions that can be used more favorably than STL when making an actual driver.
      • high quality code.
    • Cons
      • MIt seems that it was written with consideration to using Microsoft STL, but I feel it is difficult to actually change to use Microsoft STL (there were more typos and code using only ktl than I thought)
      • Russian comments, but the file is not UTF8+BOM encoded, so the build fails in a non-Russian environment.
      • x86 not supported.

While I was working to make up for the shortcomings of each library, I developed a new library for the following reasons.

  1. UCXXRT copied the Microsoft CRT source code as is and included it in the project.
  2. KTL does not support x86.

The advantages of crtsys are as follows.

  1. Microsoft CRT source code is used to support the Microsoft CRT and STL as closely as possible, but it builds and processes the source directly in the directory where Microsoft Visual Studio or Build Tools are installed, so users who use Visual Studio legally can be licensed. . You can use it without any problems.
  2. It supports a wide range of STL features by leveraging Ldk that implement the Win32 API.
  3. You can organize your projects with CMake, and CPM makes it really easy to use the library.

Goal

This project aims to provide a development experience similar to using C++ and STL in your applications when writing kernel drivers.

Features currently supported or supported in the future are listed below.

  • Checked items are items that have been implemented.
  • For the item where the test code is written, a link to the test code is added.

C++ Standard

It was written based on the C++ reference

STL

C Standard

  • math functions
    • I did not have enough time to implement it myself, so I referred to the contents of the project below. thank you! :-)
    • RetrievAL
    • musl

NTL (NT Template Library)

Provides features to support a better development environment in the kernel.

  • ntl::expand_stack (tested)
    • Function to extend the stack size
    • By default, the kernel stack is allocated a much smaller size than the user thread stack, so it is recommended to use the STL function or especially when performing throw.
  • ntl::status
    • Class for NTSTATUS
  • ntl::driver
  • ntl::device
    • Class for DEVICE_OBJECT
    • Features
  • ntl::driver_main (tested)
    • Driver entry point for C++.
    • Called by expanding the stack to its maximum size with the ntl::expand_stack function.
  • ntl::rpc
    • Provides an easy communication method between User Mode Application and Kernel Driver.
  • ntl::irql
  • ntl::spin_lock
    • Class for KSPIN_LOCK
    • Classes
  • ntl::resource

Requirements

Test Environments

  • Windows 10 x64

    • It can be built with x86, x64, ARM, ARM64, but the actual test has only been validated against x86 and x64 modules.
  • CMake 3.21.4

  • Git 2.23.0

  • Visual Studio 2017

    • Visual Studio 2017's CRT source code was missing some headers and could not be built, so it is supported using some of UCXXRT code.
    • In the future, we plan to support by manually writing the missing header.
  • Visual Studio 2019

  • Visual Studio 2022

  • VC Tools

    • 14.16.27023
    • 14.24.28314
    • 14.26.28801
    • 14.29.30133
    • 14.31.31103
    • 14.33.31629
  • Windows Kits (SDK, WDK)

    • 10.0.17763.0
    • 10.0.18362.0
    • 10.0.22000.0
    • 10.0.22621.0

If the SDK and WDK versions are different, builds are more likely to fail. If possible, it is recommended to build in the same environment as the SDK and WDK versions.

Build & Test

  1. Please build the library and test code by executing the command below.

    git clone https://github.com/ntoskrnl7/crtsys
    cd crtsys\test\build.bat

    Alternatively, if you execute the command below, both Debug and Release configurations are built for all supported architectures.

    git clone https://github.com/ntoskrnl7/crtsys
    cd crtsys
    build_all.bat test\app
    build_all.bat test\driver
  2. Install and load build\Debug\crtsys_test.sys.

    • driver x64 : test\driver\build_x64\Debug\crtsys_test.sys x86 : test\driver\build_x86\Debug\crtsys_test.sys ARM : test\driver\build_ARM\Debug\crtsys_test.sys ARM64 : test\driver\build_ARM64\Debug\crtsys_test.sys
    • app x64 : test\driver\build_x64\Debug\crtsys_test_app.exe x86 : test\driver\build_x86\Debug\crtsys_test_app.exe ARM : test\driver\build_ARM\Debug\crtsys_test_app.exe ARM64 : test\driver\build_ARM64\Debug\crtsys_test_app.exe
    sc create CrtSysTest binpath= "crtsys_test.sys full path" displayname= "crtsys test" start= demand type= kernel
    sc start CrtSysTest
    
    crtsys_test.app.exe
    
    sc stop CrtSysTest
    sc delete CrtSysTest
  3. If it loads normally and passes/unloads Google Test, the test is successful, and the test contents can be checked through DebugView or WinDbg.

Usage

  1. Please move after creating the project directory.

    mkdir test-project
    cd test-project
  2. Download CPM to your project directory.

    mkdir cmake
    wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake

    or

    mkdir cmake
    curl -o cmake/CPM.cmake -LJO https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake
  3. Please write the following files in the project directory.

    • Directory structure

      📦test-project
      ┣ 📂src
      ┃ ┗ 📜main.cpp
      ┗ 📜CMakeLists.txt
      
    • CMakeLists.txt

      cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
      
      project(crtsys_test LANGUAGES C CXX)
      
      include(cmake/CPM.cmake)
      
      set(CRTSYS_NTL_MAIN ON) # use ntl::main
      CPMAddPackage("gh:ntoskrnl7/[email protected]")
      include(${crtsys_SOURCE_DIR}/cmake/CrtSys.cmake)
      
      # add driver
      crtsys_add_driver(crtsys_test src/main.cpp)
    • src/main.cpp

      • If you enable CRTSYS_NTL_MAIN as shown below, define ntl::main as the entry point. (recommend)

        • CMakeLists.txt

          set(CRTSYS_NTL_MAIN ON)
      • If you disable CRTSYS_NTL_MAIN as shown below, define DriverEntry as the entry point, which is different from the previous one.

        • CMakeLists.txt

          set(CRTSYS_NTL_MAIN OFF)

      Below is example code from a project with ntl::main set as entry point.

      #include <iostream>
      #include <ntl/driver>
      
      ntl::status ntl::main(ntl::driver &driver, const std::wstring &registry_path) {
      
        std::wcout << "load (registry_path :" << registry_path << ")\n";
      
        // TODO
      
        driver.on_unload([registry_path]() {
          std::wcout << "unload (registry_path :" << registry_path << ")\n";
        });
      
        return status::ok();
      }
  4. Perform a build.

    cmake -S . -B build
    cmake --build build
  5. Please check if the driver starts up and shuts down normally.

    sc create CrtSysTest binpath= "crtsys_test.sys full path" displayname= "crtsys test" start= demand type= kernel
    sc start CrtSysTest
    sc stop CrtSysTest
    sc delete CrtSysTest

TODO

  • CMake install handling.
  • Implementing C++ STL features not yet implemented.
  • Build CRT source code in Visual Studio 2017.
  • Running unit tests in GitHub Action.