From a0b009f1ed9e7711377e6a52a7034c3083a188bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Herm=C3=A8s=20B=C3=A9lusca-Ma=C3=AFto?= Date: Mon, 13 Mar 2023 01:10:57 +0100 Subject: [PATCH] [NTOS:EX:KD64] Add Doxygen documentation for Nt/KdSystemDebugControl. Based from external documentation: https://www.ivanlef0u.tuxfamily.org/?p=21 https://www.ivanlef0u.tuxfamily.org/?p=382 http://pds8.egloos.com/pds/200807/09/51/Subverting_Windows_2003_Service_Pack_1_Kernel_Integrity_Protection.pdf http://www.nynaeve.net/?p=114 https://media.defcon.org/DEF%20CON%2030/DEF%20CON%2030%20presentations/Eran%20Segal%20-%20The%20COW%20%28Container%20On%20Windows%29%20Who%20Escaped%20the%20Silo.pdf https://vidstromlabs.com/blog/memory-dumping-with-ntsystemdebugcontrol/ https://www.kernelmode.info/forum/viewtopic0aa3.html?t=5317 --- ntoskrnl/ex/dbgctrl.c | 80 +++++++++++++++++++++++++++---------------- ntoskrnl/kd64/kdapi.c | 43 +++++++++++++++++++++-- 2 files changed, 91 insertions(+), 32 deletions(-) diff --git a/ntoskrnl/ex/dbgctrl.c b/ntoskrnl/ex/dbgctrl.c index 17dc980f999..3aa65b99a97 100644 --- a/ntoskrnl/ex/dbgctrl.c +++ b/ntoskrnl/ex/dbgctrl.c @@ -146,54 +146,75 @@ ExpDebuggerWorker( } } -/*++ - * @name NtSystemDebugControl - * @implemented +/** + * @brief + * Perform various queries to the kernel debugger. * - * Perform various queries to debugger. - * This API is subject to test-case creation to further evaluate its - * abilities (if needed to at all) + * @param[in] Command + * A SYSDBG_COMMAND value describing the kernel debugger command to perform. * - * See: http://www.osronline.com/showthread.cfm?link=93915 - * http://void.ru/files/Ntexapi.h - * http://www.codeguru.com/code/legacy/system/ntexapi.zip - * http://www.securityfocus.com/bid/9694 + * @param[in] InputBuffer + * Pointer to a user-provided input command-specific buffer, whose length + * is given by InputBufferLength. * - * @param ControlCode - * Description of the parameter. Wrapped to more lines on ~70th - * column. + * @param[in] InputBufferLength + * The size (in bytes) of the buffer pointed by InputBuffer. * - * @param InputBuffer - * FILLME + * @param[out] OutputBuffer + * Pointer to a user-provided command-specific output buffer, whose length + * is given by OutputBufferLength. * - * @param InputBufferLength - * FILLME + * @param[in] OutputBufferLength + * The size (in bytes) of the buffer pointed by OutputBuffer. * - * @param OutputBuffer - * FILLME + * @param[out] ReturnLength + * Optional pointer to a ULONG variable that receives the actual length of + * data written written in the output buffer. It is always zero, except for + * the live dump commands where an actual non-zero length is returned. * - * @param OutputBufferLength - * FILLME + * @return + * STATUS_SUCCESS in case of success, or a proper error code otherwise. * - * @param ReturnLength - * FILLME + * @remarks * - * @return STATUS_SUCCESS in case of success, proper error code otherwise + * - The caller must have SeDebugPrivilege, otherwise the function fails + * with STATUS_ACCESS_DENIED. * - * @remarks None + * - Only the live dump commands: SysDbgGetTriageDump, and SysDbgGetLiveKernelDump + * (Win8.1+) are available even if the debugger is disabled or absent. * - *--*/ + * - The following system-critical commands are not accessible anymore + * for user-mode usage with this API on NT 5.2+ (Windows 2003 SP1 and later) + * systems: + * + * SysDbgQueryVersion, + * SysDbgReadVirtual and SysDbgWriteVirtual, + * SysDbgReadPhysical and SysDbgWritePhysical, + * SysDbgReadControlSpace and SysDbgWriteControlSpace, + * SysDbgReadIoSpace and SysDbgWriteIoSpace, + * SysDbgReadMsr and SysDbgWriteMsr, + * SysDbgReadBusData and SysDbgWriteBusData, + * SysDbgCheckLowMemory. + * + * For these, NtSystemDebugControl() will return STATUS_NOT_IMPLEMENTED. + * They are now available from kernel-mode only with KdSystemDebugControl(). + * + * @note + * See: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2004-2339 + * + * @see KdSystemDebugControl() + **/ NTSTATUS NTAPI NtSystemDebugControl( - _In_ SYSDBG_COMMAND ControlCode, + _In_ SYSDBG_COMMAND Command, _In_reads_bytes_(InputBufferLength) PVOID InputBuffer, _In_ ULONG InputBufferLength, _Out_writes_bytes_(OutputBufferLength) PVOID OutputBuffer, _In_ ULONG OutputBufferLength, _Out_opt_ PULONG ReturnLength) { - switch (ControlCode) + switch (Command) { case SysDbgQueryModuleInformation: case SysDbgQueryTraceInformation: @@ -226,10 +247,11 @@ NtSystemDebugControl( case SysDbgSetPrintBufferSize: case SysDbgGetKdUmExceptionEnable: case SysDbgSetKdUmExceptionEnable: + case SysDbgGetKdBlockEnable: case SysDbgSetKdBlockEnable: return KdSystemDebugControl( - ControlCode, + Command, InputBuffer, InputBufferLength, OutputBuffer, OutputBufferLength, ReturnLength, KeGetPreviousMode()); diff --git a/ntoskrnl/kd64/kdapi.c b/ntoskrnl/kd64/kdapi.c index cb0c65bd341..36600e4beac 100644 --- a/ntoskrnl/kd64/kdapi.c +++ b/ntoskrnl/kd64/kdapi.c @@ -2171,9 +2171,46 @@ KdDisableDebugger(VOID) return KdDisableDebuggerWithLock(TRUE); } -/* - * @unimplemented - */ +/** + * @brief + * Perform various queries to the kernel debugger. + * + * @param[in] Command + * A SYSDBG_COMMAND value describing the kernel debugger command to perform. + * + * @param[in] InputBuffer + * Pointer to a user-provided input command-specific buffer, whose length + * is given by InputBufferLength. + * + * @param[in] InputBufferLength + * The size (in bytes) of the buffer pointed by InputBuffer. + * + * @param[out] OutputBuffer + * Pointer to a user-provided command-specific output buffer, whose length + * is given by OutputBufferLength. + * + * @param[in] OutputBufferLength + * The size (in bytes) of the buffer pointed by OutputBuffer. + * + * @param[out] ReturnLength + * Optional pointer to a ULONG variable that receives the actual length of + * data written written in the output buffer. It is always zero, except for + * the live dump commands where an actual non-zero length is returned. + * + * @param[in] PreviousMode + * The processor mode (KernelMode or UserMode) in which the command is being executed. + * + * @return + * STATUS_SUCCESS in case of success, or a proper error code otherwise. + * + * @remarks + * - This is a kernel-mode function, accessible only by kernel-mode drivers. + * + * @note + * See: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2004-2339 + * + * @see NtSystemDebugControl() + **/ NTSTATUS NTAPI KdSystemDebugControl(