Windows API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

// Native API structures and functions
// Note: These are typically NOT declared in standard headers
 
// Native string type used by Native API
typedef struct _UNICODE_STRING {
    USHORT Length;        // Current length in BYTES (not characters)
    USHORT MaximumLength; // Maximum length in BYTES
    PWSTR  Buffer;        // Pointer to wide-character string
} UNICODE_STRING, *PUNICODE_STRING;
 
// Object attributes for native object creation
typedef struct _OBJECT_ATTRIBUTES {
    ULONG           Length;
    HANDLE          RootDirectory;
    PUNICODE_STRING ObjectName;
    ULONG           Attributes;
    PVOID           SecurityDescriptor;
    PVOID           SecurityQualityOfService;
} OBJECT_ATTRIBUTES, *POBJECT_ATTRIBUTES;
 
// I/O status block - returned by native I/O operations
typedef struct _IO_STATUS_BLOCK {
    union {
        NTSTATUS Status;   // Final status
        PVOID    Pointer;
    };
    ULONG_PTR Information;  // Bytes transferred or other info
} IO_STATUS_BLOCK, *PIO_STATUS_BLOCK;
 
// Native file creation function
NTSTATUS NTAPI NtCreateFile(
    PHANDLE            FileHandle,
    ACCESS_MASK        DesiredAccess,
    POBJECT_ATTRIBUTES ObjectAttributes,
    PIO_STATUS_BLOCK   IoStatusBlock,
    PLARGE_INTEGER     AllocationSize,
    ULONG              FileAttributes,
    ULONG              ShareAccess,
    ULONG              CreateDisposition,
    ULONG              CreateOptions,
    PVOID              EaBuffer,
    ULONG              EaLength
);
 
// Example: Using Native API to create a file
NTSTATUS CreateFileNative(LPCWSTR filePath, PHANDLE pHandle) {
    UNICODE_STRING nativePath;
    OBJECT_ATTRIBUTES objAttr;
    IO_STATUS_BLOCK ioStatus;
    NTSTATUS status;
    
    // Native API requires NT path format: \??\C:\path\file.txt
    WCHAR ntPath[MAX_PATH + 4];
    swprintf_s(ntPath, MAX_PATH + 4, L"\\??\\%s", filePath);
    
    // Initialize UNICODE_STRING - Native API doesn't use null-terminated strings
    RtlInitUnicodeString(&nativePath, ntPath);
    
    // Initialize object attributes
    InitializeObjectAttributes(
        &objAttr,
        &nativePath,
        OBJ_CASE_INSENSITIVE,  // Case-insensitive path lookup
        NULL,                   // No root directory
        NULL                    // No security descriptor
    );
    
    // Call the Native API function
    status = NtCreateFile(
        pHandle,
        GENERIC_READ | SYNCHRONIZE,
        &objAttr,
        &ioStatus,
        NULL,                    // No allocation size
        FILE_ATTRIBUTE_NORMAL,
        FILE_SHARE_READ,
        FILE_OPEN,               // Equivalent to OPEN_EXISTING
        FILE_SYNCHRONOUS_IO_NONALERT,  // Synchronous I/O
        NULL,                    // No extended attributes
        0
    );
    
    return status;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

// What happens when you call CreateFileW():
 
HANDLE CreateFileW(
    LPCWSTR lpFileName,
    DWORD dwDesiredAccess,
    DWORD dwShareMode,
    LPSECURITY_ATTRIBUTES lpSecurityAttributes,
    DWORD dwCreationDisposition,
    DWORD dwFlagsAndAttributes,
    HANDLE hTemplateFile
) {
    // 1. Validate parameters
    if (!lpFileName) {
        SetLastError(ERROR_INVALID_PARAMETER);
        return INVALID_HANDLE_VALUE;
    }
    
    // 2. Convert Win32 path to Native path format
    //    "C:\file.txt" → "\??\C:\file.txt"
    UNICODE_STRING ntPath;
    RtlDosPathNameToNtPathName_U(lpFileName, &ntPath, ...);
    
    // 3. Convert Win32 flags to Native flags
    ACCESS_MASK ntAccess = MapWin32AccessToNtAccess(dwDesiredAccess);
    ULONG ntDisposition = MapCreationDisposition(dwCreationDisposition);
    ULONG ntOptions = MapFlagsToOptions(dwFlagsAndAttributes);
    
    // 4. Build OBJECT_ATTRIBUTES
    OBJECT_ATTRIBUTES objAttr;
    InitializeObjectAttributes(&objAttr, &ntPath, ...);
    
    // 5. Call Native API
    HANDLE hFile;
    IO_STATUS_BLOCK ioStatus;
    NTSTATUS status = NtCreateFile(
        &hFile,
        ntAccess,
        &objAttr,
        &ioStatus,
        NULL,
        dwFlagsAndAttributes & FILE_ATTRIBUTE_MASK,
        dwShareMode,
        ntDisposition,
        ntOptions,
        NULL,
        0
    );
    
    // 6. Convert NTSTATUS to Win32 error and return
    if (!NT_SUCCESS(status)) {
        SetLastError(RtlNtStatusToDosError(status));
        return INVALID_HANDLE_VALUE;
    }
    
    return hFile;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

; Typical ntdll.dll syscall stub for x64 Windows 10/11
; This is what NtCreateFile looks like in ntdll.dll:
 
NtCreateFile:
    ; Move the system call number into EAX
    mov     r10, rcx        ; Save first parameter (rcx is clobbered by syscall)
    mov     eax, 55h        ; System call number for NtCreateFile
                            ; (This number varies between Windows versions!)
    
    ; Test if running inside the Windows hypervisor
    test    byte ptr ds:[7FFE0308h], 1
    jne     UseHypercall    ; Use different path for Hyper-V
    
    ; Execute the system call
    syscall                 ; CPU transitions to kernel mode
                            ; Jumps to LSTAR MSR (KiSystemCall64)
    
    ; Return - we're back in user mode
    ret
 
UseHypercall:
    ; When running in Hyper-V, use INT 2E for system calls
    ; (This is a security feature called Virtual Secure Mode)
    int     2Eh
    ret

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

// What happens in the kernel when a syscall arrives
// (Simplified view of KiSystemCall64 and KiSystemServiceStart)
 
KiSystemCall64:
    ; We're now in kernel mode (Ring 0)
    
    ; SWAPGS: Exchange kernel and user GS base addresses
    ; GS points to KPCR (Kernel Processor Control Region)
    swapgs
    
    ; Switch to kernel stack
    ; User stack pointer is saved in TSS
    mov     rsp, gs:[KPCR.CurrentThread.InitialStack]
    
    ; Build trap frame on kernel stack
    ; Save all user-mode state
    push    user_ss
    push    user_rsp
    push    user_rflags
    push    user_cs
    push    user_rip  ; return address from syscall
    push    error_code
    ; ... push all general registers
    
    ; Validate system call number
    cmp     eax, MAX_SYSCALL_NUMBER
    jae     InvalidSyscall
    
    ; Look up system service routine in SSDT
    lea     rbx, [KeServiceDescriptorTable]
    mov     rdi, qword ptr [rbx + SSDT.ServiceTable]
    
    ; Get the routine address (relative offset in table)
    movsxd  r10, dword ptr [rdi + rax*4]
    sar     r10, 4  ; Remove argument count from low bits
    add     r10, rdi
    
    ; Validate and copy arguments from user stack
    ; (Critical security boundary!)
    call    CopyUserModeArguments
    
    ; Call the actual system service routine
    call    r10  ; e.g., calls NtCreateFile in ntoskrnl.exe
    
    ; Restore user state and return
    ; ... restore registers from trap frame
    swapgs
    sysretq  ; Return to user mode

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

// Direct syscall example - FOR EDUCATIONAL PURPOSES ONLY
// This code is fragile and will break across Windows versions
 
#include <windows.h>
 
// Syscall stub - must be in assembly
// This is the same code pattern that ntdll.dll uses
extern NTSTATUS DirectNtClose(HANDLE Handle);
 
// In separate .asm file:
// DirectNtClose:
//     mov r10, rcx
//     mov eax, 0Fh    ; NtClose syscall number for Win10/11
//     syscall
//     ret
 
// Finding syscall number at runtime (more portable approach)
DWORD GetSyscallNumber(LPCSTR functionName) {
    // Get ntdll base address
    HMODULE hNtdll = GetModuleHandleA("ntdll.dll");
    if (!hNtdll) return 0;
    
    // Get function address
    PBYTE pFunction = (PBYTE)GetProcAddress(hNtdll, functionName);
    if (!pFunction) return 0;
    
    // Parse the syscall stub
    // First instruction: mov r10, rcx = 4C 8B D1
    // Second instruction: mov eax, <syscall#> = B8 XX XX XX XX
    if (pFunction[0] == 0x4C && 
        pFunction[1] == 0x8B && 
        pFunction[2] == 0xD1 &&
        pFunction[3] == 0xB8) {
        // Extract the syscall number
        return *(DWORD*)(pFunction + 4);
    }
    
    // Stub pattern may be different (hooked or different Windows version)
    return 0;
}
 
void ExampleUsage() {
    DWORD syscallNumber = GetSyscallNumber("NtClose");
    printf("NtClose syscall number: 0x%X\n", syscallNumber);
    
    // You could then use this number with a dynamic syscall stub
    // But again - this is fragile and not recommended for production
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

┌──────────────────────────────────────────────────────────────────┐
│ USER MODE (Ring 3)                                                │
│                                                                   │
│   1. Application calls kernel32!CreateFileW()                     │
│      - User-mode code, normal function call                       │
│                                                                   │
│   2. kernel32!CreateFileW validates parameters                    │
│      - Still user mode                                            │
│      - Converts path format, maps flags                           │
│                                                                   │
│   3. kernel32!CreateFileW calls ntdll!NtCreateFile                │
│      - Still user mode                                            │
│      - Normal function call into ntdll.dll                        │
│                                                                   │
│   4. ntdll!NtCreateFile syscall stub executes                     │
│      - mov r10, rcx           ; Save first parameter              │
│      - mov eax, 55h           ; Load syscall number               │
│      - syscall                ; ← TRANSITION POINT                │
│                                                                   │
╠══════════════════════════════════════════════════════════════════╣
│                           CPU OPERATIONS                          │
│                                                                   │
│   The SYSCALL instruction atomically:                             │
│   - Saves RIP to RCX (return address)                            │
│   - Saves RFLAGS to R11                                          │
│   - Loads CS from STAR MSR (kernel code segment)                 │
│   - Loads SS implicitly                                          │
│   - Masks RFLAGS (clears IF, TF, etc.)                           │
│   - Loads RIP from LSTAR MSR (KiSystemCall64)                    │
│   - Privilege level changes to Ring 0                             │
│                                                                   │
╠══════════════════════════════════════════════════════════════════╣
│ KERNEL MODE (Ring 0)                                              │
│                                                                   │
│   5. KiSystemCall64 runs                                          │
│      - swapgs             ; Switch to kernel GS                   │
│      - Switch to kernel stack                                     │
│      - Build KTRAP_FRAME on stack                                 │
│                                                                   │
│   6. KiSystemServiceStart                                         │
│      - Validate syscall number                                    │
│      - Look up in SSDT                                           │
│      - Copy user-mode arguments                                   │
│      - Probe user-mode buffers for validity                       │
│                                                                   │
│   7. NtCreateFile executes (in ntoskrnl.exe)                      │
│      - Full kernel privileges                                     │
│      - Calls file system drivers                                  │
│      - Returns NTSTATUS                                           │
│                                                                   │
│   8. KiSystemServiceExit                                          │
│      - Places return value in RAX                                 │
│      - Restores user state from trap frame                       │
│      - swapgs             ; Switch to user GS                     │
│      - sysretq            ; Return to user mode                   │
│                                                                   │
╠══════════════════════════════════════════════════════════════════╣
│ USER MODE (Ring 3 - after sysret)                                 │
│                                                                   │
│   9. ntdll!NtCreateFile returns                                   │
│      - NTSTATUS in RAX                                            │
│                                                                   │
│  10. kernel32!CreateFileW handles result                          │
│      - Converts NTSTATUS to Win32 error                           │
│      - Returns HANDLE or INVALID_HANDLE_VALUE                     │
└──────────────────────────────────────────────────────────────────┘

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

// Equivalent operations: Windows vs POSIX
 
// ==== File Open ====
// POSIX (Linux):
int fd = open("/path/to/file", O_RDONLY);
if (fd < 0) {
    perror("open failed");
}
 
// Windows Win32:
HANDLE hFile = CreateFileW(L"C:\\path\\to\\file",
    GENERIC_READ, FILE_SHARE_READ, NULL,
    OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
if (hFile == INVALID_HANDLE_VALUE) {
    // GetLastError() for error code
}
 
// Windows Native API (internal):
UNICODE_STRING path;
OBJECT_ATTRIBUTES objAttr;
IO_STATUS_BLOCK ioStatus;
HANDLE hFile;
RtlInitUnicodeString(&path, L"\\??\\C:\\path\\to\\file");
InitializeObjectAttributes(&objAttr, &path, OBJ_CASE_INSENSITIVE, NULL, NULL);
NTSTATUS status = NtCreateFile(&hFile, GENERIC_READ, &objAttr, &ioStatus, ...);
 
// ==== Process Creation ====
// POSIX:
pid_t pid = fork();
if (pid == 0) {
    execve("/bin/program", argv, envp);
}
 
// Windows Win32:
STARTUPINFO si = { sizeof(si) };
PROCESS_INFORMATION pi;
CreateProcessW(L"C:\\program.exe", NULL, NULL, NULL,
    FALSE, 0, NULL, NULL, &si, &pi);
 
// ==== Memory Allocation ====
// POSIX:
void* mem = mmap(NULL, size, PROT_READ | PROT_WRITE,
    MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
 
// Windows:
LPVOID mem = VirtualAlloc(NULL, size, MEM_COMMIT | MEM_RESERVE, 
    PAGE_READWRITE);