crtsys

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

• 한국어 (Korean) 보기

[This document has been machine translated.]

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

• crtsys
  • Overview
  • Goal
    • C++ Standard
      • STL
    • C Standard
    • NTL (NT Template Library)
  • Requirements
  • Test Environments
  • Build & Test
  • Usage
  • TODO

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
    • The concept of using the Microsoft STL directly looks good.
  • 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

• Initialization
  • Non-local variables
    • Static initialization
      • Constant initialization (tested)
      • Zero initialization (tested)
    • Dynamic initialization (tested)
  • Static local variables
    • thread_local
    • static
• Exceptions
  • throw (tested)
  • try-block (tested)
  • Function-try-block (tested)

STL

• std::chrono (tested)
• std::thread (tested)
• std::condition_variable (tested)
• std::mutex (tested)
• std::shared_mutex (tested)
• std::future (tested)
• std::promise (tested)
• std::packaged_task (tested)
• std::cin
• std::clog
• std::cerr
• std::cout (tested)
• std::wcin
• std::wclog
• std::wcerr
• std::wcout (tested)

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
  • Class for DRIVER_OBJECT
  • Features
    • DriverUnload (tested)
    • Create device (tested)
• ntl::device
  • Class for DEVICE_OBJECT
  • Features
    • Device Extension (tested)
    • IRP_MJ_CREATE
    • IRP_MJ_CLOSE
    • IRP_MJ_DEVICE_CONTROL (tested) (tested)
• 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::rpc::server (tested) (tested)
    • ntl::rpc::client (tested) (tested)
      • I did not have enough time to implement the data serialization part myself, so I referred to the contents of the project below. thank you! :-)
        • Eyal Z/zpp serializer
• ntl::irql
  • Class for KIRQL
  • Classes
    • ntl::irql (tested)
  • Functions
    • ntl::raise_irql (tested)
    • raise_irql_to_dpc_level (tested)
    • raise_irql_to_synch_level (tested)
• ntl::spin_lock
  • Class for KSPIN_LOCK
  • Classes
    • ntl::spin_lock (tested)
    • ntl::unique_lock (tested)
• ntl::resource
  • Class for ERESOURCE
  • Classes
    • ntl::resource (tested)
    • ntl::unique_lock (tested)
    • ntl::shared_lock (tested)

Requirements

• Windows 7 or later
• Visual Studio / Build Tools 2017 or later
• CMake 3.16 or later
• Git

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.