Malleum Knowledge Base

Introduction to Windows API in Rust - Part 2

6 min read

Understanding the OpenProcess API

In our previous blog post, we explored how to create a simple message box using the MessageBoxA API in Rust. In this post, we will move forward by discussing the OpenProcess API, which allows us to open a handle to a process on a Windows system. Specifically, we will focus on the API call, its parameters, and the various access rights that can be requested when opening a process.

Process: A process is a container that holds a running instance of a program. Each process has its own isolated virtual memory space.

Thread: Threads are the actual units of execution inside a process. Multiple threads in a process can share the same memory space while performing separate tasks simultaneously.

What is OpenProcess?

The OpenProcess API is used to obtain a handle to a process. A handle is essential when you want to perform actions on a process, such as reading its memory, writing to it, or terminating it. With OpenProcess, you can specify the level of access you need and obtain the handle based on the security context of your process.

Getting Started

Create a new Rust project named open_process using Cargo:

cargo new --bin open_process

OpenProcess Function Prototype

Here’s the function signature for OpenProcess in Rust using the windows crate:

pub unsafe fn OpenProcess<P0>(
    dwdesiredaccess: PROCESS_ACCESS_RIGHTS,
    binherithandle: P0,
    dwprocessid: u32,
) -> Result<HANDLE>
where
    P0: Param<BOOL>,

Understanding the Parameters

  1. dwdesiredaccess: PROCESS_ACCESS_RIGHTS:

    • This parameter specifies the access rights you are requesting for the process.
    • PROCESS_ACCESS_RIGHTS is an enumeration that defines different levels of access such as:
      • PROCESS_ALL_ACCESS: Grants full access to the process.
      • PROCESS_QUERY_INFORMATION: Allows you to query the process information.
      • PROCESS_VM_READ: Grants read access to the process’s virtual memory.
      • PROCESS_VM_WRITE: Allows writing to the process’s memory.
    • This value defines what you are allowed to do with the process once you have the handle.

  2. binherithandle: P0:

    • This is a boolean value (BOOL) that determines whether the process handle can be inherited by child processes.
    • The generic parameter P0 is used here to allow flexibility in the type. P0 implements the Param trait for BOOL, which allows you to pass either a literal bool or other types that can be converted to a BOOL internally.
    • Typically, you would pass true or false depending on whether you want child processes to inherit the handle.

  3. dwprocessid: u32:

    • This is the process ID of the target process. Each process running on Windows has a unique process ID, which you can retrieve using system tools like Task Manager or programmatically via APIs like GetCurrentProcessId.
    • You need to supply this ID so that OpenProcess knows which process you want to open a handle to.

Return Type

  • Result<HANDLE>:
    • The function returns a Result type, which is commonly used in Rust to indicate whether an operation was successful or if an error occurred.
    • If successful, the Result contains a HANDLE, which is a Windows API type representing the handle to the process. You can use this handle to perform operations on the process.
    • If the operation fails, the Result will contain an error, which you can handle accordingly.

unsafe Keyword

  • unsafe:
    • This function is marked as unsafe because interacting directly with system-level APIs can introduce risks such as dereferencing invalid pointers or accessing invalid memory regions. Rust requires you to explicitly acknowledge these risks by using the unsafe block when calling the function.

Example: Opening a Process in Rust

Add the windows crate dependency to your Cargo.toml file:

[dependencies.windows]  
version = "0.57.0"  
features = [  
    "Win32_Foundation",  
    "Win32_System_Threading",  
]

Here’s a basic example of how to use the OpenProcess API to obtain a handle to the current process. We will request full access using PROCESS_ALL_ACCESS:

use windows::Win32::Foundation::{HANDLE};  
use windows::Win32::System::Threading::{  
    GetCurrentProcessId, OpenProcess, PROCESS_ALL_ACCESS,  
};  
  
unsafe fn open_process() -> Result<HANDLE,windows::core::Error> {  
    let process_id = GetCurrentProcessId(); // Get current process ID  
    println!("The Process ID is {}", process_id);  
    let handle = OpenProcess(PROCESS_ALL_ACCESS, false, process_id)?; // Open process with full access  
    Ok(handle) //returns handle  
}  
fn main() {  
    unsafe {  
        match open_process() {  
            Ok(handle) => println!("Successfully opened process with handle: {:?}", handle),  
            Err(e) => println!("Failed to open process: {:?}", e),  
        }  
    }  
}

In this example:

  • We use PROCESS_ALL_ACCESS to request full access rights.
  • The bInheritHandle is set to false, meaning we don’t need the handle to be inherited by any child processes.
  • We obtain the process ID of the current process using GetCurrentProcessId, but this could be replaced with the ID of any other process you want to open.

Access Rights

When calling OpenProcess, you need to be aware of the access rights you’re requesting. If you request more permissions than necessary, or if you request permissions your process is not authorized for, the call may fail. Below are some common access rights used with OpenProcess:

  • PROCESS_ALL_ACCESS: This grants full access to the process, including reading, writing, and terminating the process. Use this when you need complete control over the process.

  • PROCESS_VM_READ: This allows reading memory from the process. You’ll need this if you want to inspect the process’s memory but don’t need to modify it.

  • PROCESS_VM_WRITE: This allows writing to the process’s memory. Use this when you need to modify the memory of the target process.

  • PROCESS_QUERY_INFORMATION: This allows querying information about the process, such as its status, priority, or memory usage. This is useful if you’re building monitoring or diagnostic tools.

Security and Privileges

To successfully open a handle to a process, your current process must have the appropriate privileges and access rights. For example, if you’re trying to open a process that is running with elevated privileges (such as a process running as an administrator), and your process does not have similar privileges, the OpenProcess call may fail.

Additionally, processes are also restricted by Integrity Levels. Lower-integrity processes cannot interact with higher-integrity ones unless the appropriate security context is used (e.g., running the code as an administrator).

Conclusion

In this post, we explored the OpenProcess API in Rust and broke down its parameters and access rights. Understanding how to open a process handle is a crucial step in working with the Windows API, especially if you need to interact with other processes for tasks like debugging, monitoring, or memory manipulation.

In the next blog, we will take this further by exploring how to allocate memory in a process using the VirtualAllocEx API and other related concepts.

Graph View