diff --git a/descriptions/initializeobjectattributes.md b/descriptions/initializeobjectattributes.md index e69de29bb2d..a66d7f160a6 100644 --- a/descriptions/initializeobjectattributes.md +++ b/descriptions/initializeobjectattributes.md @@ -0,0 +1 @@ +Initializes an `OBJECT_ATTRIBUTES` structure. This macro is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows/win32/api/ntdef/nf-ntdef-initializeobjectattributes). diff --git a/descriptions/ntclose.md b/descriptions/ntclose.md index 434291aa46f..217b1a5fb28 100644 --- a/descriptions/ntclose.md +++ b/descriptions/ntclose.md @@ -1,8 +1,21 @@ -This function is documented in Windows Driver Kit [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntclose) and [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwclose). +Closes the specified kernel handle. This function is documented in Windows Driver Kit [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntclose) and [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwclose). ---- +# Parameters + - `Handle` - a handle to a kernel object. -### ObjectHandle +# Notable return values + - `STATUS_INVALID_HANDLE` - an invalid handle value was specified. + - `STATUS_HANDLE_NOT_CLOSABLE` - the provided handle is marked as protected from closing. See `OBJ_PROTECT_CLOSE` for more details. -Handle to open object. \ -If `ObjectHandle` is last reference to object in system, object will be removed from memory. +# Remarks +`NtClose` is one the few Native API functions that can raise exceptions instead of returning an error status code. See the [exploit protection reference](https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exploit-protection-reference?view=o365-worldwide#validate-handle-usage) for a description of the mitigation that causes this behavior. + +# Related Win32 API + - [`CloseHandle`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle) + +# See also + - `OBJ_PROTECT_CLOSE` + - `NtMakeTemporaryObject` + - `NtDuplicateObject` + - `NtQueryObject` + - `NtSetInformationObject` diff --git a/descriptions/ntcompareobjects.md b/descriptions/ntcompareobjects.md index e69de29bb2d..b01663b9804 100644 --- a/descriptions/ntcompareobjects.md +++ b/descriptions/ntcompareobjects.md @@ -0,0 +1,22 @@ +Determines whether two handles point to the same kernel object. + +# Parameters + - `FirstObjectHandle` - a handle to the first object. + - `SecondObjectHandle` - a handle to the second object. + +The handles do not need to grant any specific access. Any of the handles can be a pseudo-handle to the current thread (`NtCurrentThread`) or the current process (`NtCurrentProcess`). + +# Notable return values + - `STATUS_SUCCESS` - the two handles point to the same underlying kernel object. + - `STATUS_NOT_SAME_OBJECT` - the handles point toward different objects. + +# Related Win32 API + - [`CompareObjectHandles`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-compareobjecthandles) + +# Required OS version +This function was introduced in Windows 10 TH1 (1507). + +# See also + - `NtDuplicateObject` + - `RtlIsCurrentThread` + - `RtlIsCurrentProcess` diff --git a/descriptions/ntcurrentprocess.md b/descriptions/ntcurrentprocess.md index e69de29bb2d..28ef8835531 100644 --- a/descriptions/ntcurrentprocess.md +++ b/descriptions/ntcurrentprocess.md @@ -0,0 +1,5 @@ +This macro is a native equivalent of the [`GetCurrentProcess`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentprocess) function. It returns a pseudo-handle that grants `PROCESS_ALL_ACCESS` to the current process. You do not need to call `NtClose` on the returned handle. + +# See also + - `NtCurrentThread` + - `RtlIsCurrentProcess` diff --git a/descriptions/ntcurrentthread.md b/descriptions/ntcurrentthread.md index c74d9a3f90e..29bcf1a1dbc 100644 --- a/descriptions/ntcurrentthread.md +++ b/descriptions/ntcurrentthread.md @@ -1 +1,5 @@ -This macro is a native equivalent of the [`GetCurrentThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentthread) function. It returns a pseudo-handle that grants `THREAD_ALL_ACCESS` to the current thread. +This macro is a native equivalent of the [`GetCurrentThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentthread) function. It returns a pseudo-handle that grants `THREAD_ALL_ACCESS` to the current thread. You do not need to call `NtClose` on the returned handle. + +# See also + - `NtCurrentProcess` + - `RtlIsCurrentThread` diff --git a/descriptions/ntdelayexecution.md b/descriptions/ntdelayexecution.md index 6b4178bed9d..3d1eb411ea8 100644 --- a/descriptions/ntdelayexecution.md +++ b/descriptions/ntdelayexecution.md @@ -8,6 +8,7 @@ Initiates a sleep on the current thread. - `STATUS_SUCCESS` - the thread woke due to the timeout. - `STATUS_USER_APC` - the sleep was interrupted by an APC. - `STATUS_ALERTED` - the sleep was interrupted by a call to `NtAlertThread`. + - `STATUS_NO_YIELD_PERFORMED` - a zero-timeout sleep did not cause switching to other threads. # Remarks Despite the name, `NtAlertThreadByThreadId` is unrelated to alertable sleeps and cannot interrupt them. diff --git a/descriptions/ntduplicateobject.md b/descriptions/ntduplicateobject.md index 6df86e5c74b..00f54c9d0ef 100644 --- a/descriptions/ntduplicateobject.md +++ b/descriptions/ntduplicateobject.md @@ -1,9 +1,33 @@ -This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwduplicateobject). +Allows copying handles across process boundaries and opening additional handles pointing to the same underlying kernel object. This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwduplicateobject). ---- +# Parameters + - `SourceProcessHandle` - a handle to the source process. This can be the `NtCurrentProcess` pseudo-handle or a handle granting `PROCESS_DUP_HANDLE` access. + - `SourceHandle` - the source handle to duplicate. This value is meaningful in the context of the source process. + - `TargetProcessHandle` - a handle to the target process. This can be the `NtCurrentProcess` pseudo-handle or a handle granting `PROCESS_DUP_HANDLE` access. + - `TargetHandle` - an optional pointer to a variable that receives the new handle. This value is meaningful in the context of the target process. + - `DesiredAccess` - the access mask to grant on the new handle. + - `HandleAttributes` - the object attribute flags to set on the new handle. Supported flags are `OBJ_INHERIT` and `OBJ_PROTECT_CLOSE`. + - `Options` - the flags that control the behavior of the function described below. -See *Microsoft SDK* for description of `DuplicateHandle` *Win32 API*. +# Supported flags + - `DUPLICATE_CLOSE_SOURCE` - instructs the system to close the source handle. Note that this occurs regardless of any error status returned. The target handle parameter becomes optional when using this flag. + - `DUPLICATE_SAME_ACCESS` - instructs the system to ignore the `DesiredAccess` parameter and copy the access mask from the source handle. + - `DUPLICATE_SAME_ATTRIBUTES` - instructs the system to ignore the `HandleAttributes` parameter and copy the handle attributes from the source handle. -# Documented by +# Remarks +This function offers a wide range of modes of operation: -* Tomasz Nowak +1. Duplicate or reopen handles within the calling process. This function allows making copies of existing handles with different access/attributes. +2. Copying handles from other processes. +3. Copying handles into other processes. +4. Closing handles in other processes. + +Note that this function performs an access check against the security descriptor of the source handle only when the `Options` parameter does not include the `DUPLICATE_SAME_ACCESS` flag. + +# Related Win32 API + - [`DuplicateHandle`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-duplicatehandle) + +# See also + - `NtClose` + - `NtQueryObject` + - `NtSetInformationObject` diff --git a/descriptions/ntmakepermanentobject.md b/descriptions/ntmakepermanentobject.md index e69de29bb2d..32c404acca7 100644 --- a/descriptions/ntmakepermanentobject.md +++ b/descriptions/ntmakepermanentobject.md @@ -0,0 +1,13 @@ +Marks an object as permanent, extending its lifetime past the last closed handle. Calling this function requires having `SeCreatePermanentPrivilege` enabled. To undo the operation, use `NtMakeTemporaryObject`. + +# Parameters + - `Handle` - a handle to a kernel object. The handle does not need to grant any specific access. + +# Remarks +To make new objects have permanent state from their creation, include `OBJ_PERMANENT` in `OBJECT_ATTRIBUTES`. + +# See also + - `NtMakeTemporaryObject` + - `OBJ_PERMANENT` + - `OBJECT_BASIC_INFORMATION` + - `NtQueryObject` diff --git a/descriptions/ntmaketemporaryobject.md b/descriptions/ntmaketemporaryobject.md index ce7152a8c41..959c501d275 100644 --- a/descriptions/ntmaketemporaryobject.md +++ b/descriptions/ntmaketemporaryobject.md @@ -1,20 +1,13 @@ -This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwmaketemporaryobject). +Removes the permanent flag from the object, restoring its lifetime to be dependant on the number of handles. This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwmaketemporaryobject). ---- +# Parameters + - `Handle` - a handle to a kernel object. The handle must grant `DELETE` access. -*(Also avaiable in Win2000 DDK)* - -Function clears object's *PERMANENT* flag, so it's live as long as the latest `HANDLE` is closed. - -### ObjectHandle - -`HANDLE` to object to make temporary. - -# Documented by - -* Tomasz Nowak +# Remarks +This function undoes the effects of `NtMakePermanentObject` and specifying `OBJ_PERMANENT` in `OBJECT_ATTRIBUTES`. # See also - -* `NtClose` -* `NtQueryObject` + - `NtMakePermanentObject` + - `OBJ_PERMANENT` + - `OBJECT_BASIC_INFORMATION` + - `NtQueryObject` diff --git a/descriptions/ntqueryobject.md b/descriptions/ntqueryobject.md index 6231e3cf8a1..cd5708801a9 100644 --- a/descriptions/ntqueryobject.md +++ b/descriptions/ntqueryobject.md @@ -1,34 +1,21 @@ -This function is documented in Windows Driver Kit [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntqueryobject) and [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwqueryobject). +Retrieves various information about kernel handles and the objects they point to. This function is partially documented in Windows Driver Kit [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntqueryobject) and [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwqueryobject). ---- +# Parameters + - `Handle` - a kernel handle to query information about. The handle does not need to grant any specific access. + - `ObjectInformationClass` - the type of information to retrieve. + - `ObjectInformation` - a pointer to a user-allocated buffer that receives the requested information. + - `ObjectInformationLength` - the size of the provided buffer in bytes. + - `ReturnLength` - an optional pointer to a variable that receives the number of bytes written when the function succeeds or the number of bytes requires when the buffer is too small. -Function `NtQueryObject` retrives some informations about any or all objects opened by calling process. It can be used with any type of object. +# Information classes +For the list of supported information classes, see `OBJECT_INFORMATION_CLASS`. -### ObjectHandle +# Notable return values + - `STATUS_BUFFER_TOO_SMALL` and `STATUS_INFO_LENGTH_MISMATCH` indicate that the requested information does not fit into the provided buffer. -HANDLE to object. - -### ObjectInformationClass - -Kind of information to retrive. See `OBJECT_INFORMATION_CLASS` for possible values list. - -### ObjectInformation - -Output buffer allocated by caller. - -### Length - -Length of `ObjectInformation` buffer, in bytes. - -### ResultLength - -Pointer to `ULONG` value that contains required size of `ObjectInformation` buffer after function call. - -# Documented by - -* Tomasz Nowak +# Related Win32 API + - [`GetHandleInformation`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-gethandleinformation) # See also - -* `NtSetInformationObject` -* `OBJECT_INFORMATION_CLASS` + - `NtSetInformationObject` + - `NtQuerySecurityObject` diff --git a/descriptions/ntqueueapcthread.md b/descriptions/ntqueueapcthread.md index 28f933c0e1a..3d337cbd8d0 100644 --- a/descriptions/ntqueueapcthread.md +++ b/descriptions/ntqueueapcthread.md @@ -20,7 +20,7 @@ Note that user APCs on the Native API level have three parameters in contrast wi - [`QueueUserAPC`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-queueuserapc) # See also - - `NtQueueApcThread` + - `NtQueueApcThreadEx` - `NtQueueApcThreadEx2` - `RtlQueueApcWow64Thread` - `NtOpenThread` diff --git a/descriptions/ntqueueapcthreadex.md b/descriptions/ntqueueapcthreadex.md index 64878802f09..0880ace834f 100644 --- a/descriptions/ntqueueapcthreadex.md +++ b/descriptions/ntqueueapcthreadex.md @@ -13,7 +13,7 @@ This function has three modes of operation: 1. When `ReserveHandle` is `NULL`, the function behaves identically to `NtQueueApcThread`. To execute the APC, the thread must first enter an alertable wait via `NtDelayExecution` (or a similar function) or call `NtTestAlert`. 2. When `ReserveHandle` is a handle to the reserve object, the function uses this object to avoid additional memory allocations. Otherwise, the behavior is identical to option 1. -3. When `ReserveHandle` is the `QUEUE_USER_APC_SPECIAL_USER_APC` value, the function queues a *special user-mode APC* that does not require the thread to enter an alertable state. The APC will be executed on the next thread's transition to user mode. This flag is supported on Windows 10 RS5 (1809) and above. Because execution of special APCs is not synchronized with the target thread +3. When `ReserveHandle` is the `QUEUE_USER_APC_SPECIAL_USER_APC` value, the function queues a *special user-mode APC* that does not require the thread to enter an alertable state. The APC will be executed on the next thread's transition to user mode. This flag is supported on Windows 10 RS5 (1809) and above. Because execution of special APCs is not synchronized with the target thread (which might happen to acquire locks), it is crucial to keep the amount and complexity of the code invoked by the special APC routine to a minimum. To queue a WoW64 APC, encode the `ApcRoutine` parameter using the `Wow64EncodeApcRoutine` macro or use `RtlQueueApcWow64Thread`. diff --git a/descriptions/ntqueueapcthreadex2.md b/descriptions/ntqueueapcthreadex2.md index 41904f83fb6..242b024f39b 100644 --- a/descriptions/ntqueueapcthreadex2.md +++ b/descriptions/ntqueueapcthreadex2.md @@ -27,7 +27,7 @@ This function was introduced in Windows 11. # See also - `NtQueueApcThread` - - `NtQueueApcThreadEx2` + - `NtQueueApcThreadEx` - `RtlQueueApcWow64Thread` - `NtOpenThread` - `NtTestAlert` diff --git a/descriptions/ntsetinformationobject.md b/descriptions/ntsetinformationobject.md index 6fef32354bc..5cfcdf67b4d 100644 --- a/descriptions/ntsetinformationobject.md +++ b/descriptions/ntsetinformationobject.md @@ -1,28 +1,19 @@ -### ObjectHandle +Adjusts various information common to all types of kernel handles. -Open handle to any NT object. +# Parameters + - `Handle` - a handle to set information on. The handle does not need to grant any specific access. + - `ObjectInformationClass` - the type of information to set. + - `ObjectInformation` - a pointer to the buffer with the data specific to the request. + - `ObjectInformationLength` - the size of the provided buffer in bytes. -### ObjectInformationClass +# Information classes +For the list of supported information classes, see `OBJECT_INFORMATION_CLASS`. -See `NtQueryObject` for detailed description of possible information classes. - -### ObjectInformation - -Buffor with data to set. - -### Length - -Length of `ObjectInformation` buffer, in bytes. - ---- - -Currently only one class in allowed in set mode: `ObjectDataInformation`. See description of `OBJECT_DATA_INFORMATION` structure. - -# Documented by - -* Tomasz Nowak +# Related Win32 API + - [`SetHandleInformation`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-sethandleinformation) # See also - -* `NtQueryObject` -* `OBJECT_DATA_INFORMATION` + - `NtQueryObject` + - `NtSetSecurityObject` + - `OBJ_INHERIT` + - `OBJ_PROTECT_CLOSE` diff --git a/descriptions/ntsetthreadexecutionstate.md b/descriptions/ntsetthreadexecutionstate.md index 4bfeec2a9ea..fb173499ad8 100644 --- a/descriptions/ntsetthreadexecutionstate.md +++ b/descriptions/ntsetthreadexecutionstate.md @@ -15,7 +15,7 @@ Sets the execution state for the current thread and manages the corresponding po You can view the power requests created via this and other APIs via `powercfg /requests`. # Related Win32 API - - [`SetThreadExecutionState`](https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-setthreadexecutionstate + - [`SetThreadExecutionState`](https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-setthreadexecutionstate) # See also - `NtPowerInformation` diff --git a/descriptions/ntwaitformultipleobjects.md b/descriptions/ntwaitformultipleobjects.md index 596a82c9c5e..53d7796eb7f 100644 --- a/descriptions/ntwaitformultipleobjects.md +++ b/descriptions/ntwaitformultipleobjects.md @@ -1,33 +1,27 @@ -### ObjectCount +Waits for one or more object to enter a signaled state. -Number of objects in `ObjectsArray` array. +# Parameters + - `Count` - the number of handles passed in the `Handles` parameter, up to `MAXIMUM_WAIT_OBJECTS` (64). + - `Handles` - a pointer to an array of handles. Each handle must grant `SYNCHRONIZE` access. + - `WaitType` - the type of wait to perform, either `WaitAll` or `WaitAny`. + - `Alertable` - determines whether the wait should be altertable. This allows external triggers (such as [APCs](https://learn.microsoft.com/en-us/windows/win32/sync/asynchronous-procedure-calls) or calls to `NtAlertThread`) to interrupt wait prematurely. + - `Timeout` - an optional pointer to a variable that stores the wait internal. A negative value indicates relative timeout for the specified number of 100-nanosecond intervals. To wait a specific number of milliseconds, multiply them by `-10,000`. Positive values indicate an absolute time. `NULL` indicates an infinite timeout. -### ObjectsArray +# Notable return values + - `STATUS_WAIT_0`..`STATUS_WAIT_63` - the thread woke due to the n'th object being signaled. + - `STATUS_ABANDONED_WAIT_0`..`STATUS_ABANDONED_WAIT_63` - the thread woke due to the n'th passed mutex becoming abandoned. + - `STATUS_TIMEOUT` - the thread woke due to the timeout. + - `STATUS_USER_APC` - the wait was interrupted by an APC. + - `STATUS_ALERTED` - the wait was interrupted by a call to `NtAlertThread`. -Pointer to array of `HANDLE`. Each must be opened with `SYNCHRONIZE` access. +# Remarks +Despite the name, `NtAlertThreadByThreadId` is unrelated to alertable waits and cannot interrupt them. -### WaitType - -Can be `WaitAllObjects` or `WaitAnyObject`. - -### Alertable - -If set, thread is signaled (*APC* routines queued for this thread are executed). - -### TimeOut - -Time-out interval. - ---- - -`NtWaitForMultipleObjects` is used typically to response for notyfications. For synchronization purposes you should use `NtWaitForSingleObject`. - -# Documented by - -* Tomasz Nowak +# Related Win32 API + - [`WaitForMultipleObjectsEx`](https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitformultipleobjectsex) # See also - -* `NtSignalAndWaitForSingleObject` -* `NtWaitForSingleObject` -* `OBJECT_WAIT_TYPE` + - `NtWaitForSingleObject` + - `NtDelayExecution` + - `NtAlertThread` + - `NtQueueApcThread` diff --git a/descriptions/ntwaitforsingleobject.md b/descriptions/ntwaitforsingleobject.md index d51c36452e9..ad181d893cf 100644 --- a/descriptions/ntwaitforsingleobject.md +++ b/descriptions/ntwaitforsingleobject.md @@ -1,24 +1,25 @@ -This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwwaitforsingleobject). +Waits for the object to enter a signaled state. This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwwaitforsingleobject). ---- +# Parameters + - `Handle` - a handle granting `SYNCHRONIZE` access. + - `Alertable` - determines whether the wait should be altertable. This allows external triggers (such as [APCs](https://learn.microsoft.com/en-us/windows/win32/sync/asynchronous-procedure-calls) or calls to `NtAlertThread`) to interrupt wait prematurely. + - `Timeout` - an optional pointer to a variable that stores the wait internal. A negative value indicates relative timeout for the specified number of 100-nanosecond intervals. To wait a specific number of milliseconds, multiply them by `-10,000`. Positive values indicate an absolute time. `NULL` indicates an infinite timeout. -### ObjectHandle +# Notable return values + - `STATUS_WAIT_0` - the thread woke due to the object being signaled. + - `STATUS_ABANDONED_WAIT_0` - the thread woke due to the passed mutex becoming abandoned. + - `STATUS_TIMEOUT` - the thread woke due to the timeout. + - `STATUS_USER_APC` - the wait was interrupted by an APC. + - `STATUS_ALERTED` - the wait was interrupted by a call to `NtAlertThread`. -`HANDLE` to alertable object. +# Remarks +Despite the name, `NtAlertThreadByThreadId` is unrelated to alertable waits and cannot interrupt them. -### Alertable - -If set, calling thread is signaled, so all queued *APC* routines are executed. - -### TimeOut - -Time-out interval, in microseconds. **NULL** means infinite. - -# Documented by - -* Tomasz Nowak +# Related Win32 API + - [`WaitForSingleObjectEx`](https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitforsingleobjectex) # See also - -* `NtSignalAndWaitForSingleObject` -* `NtWaitForMultipleObjects` + - `NtWaitForMultipleObjects` + - `NtDelayExecution` + - `NtAlertThread` + - `NtQueueApcThread` diff --git a/descriptions/obj_case_insensitive.md b/descriptions/obj_case_insensitive.md index e69de29bb2d..ee4fad8111c 100644 --- a/descriptions/obj_case_insensitive.md +++ b/descriptions/obj_case_insensitive.md @@ -0,0 +1,18 @@ +This `OBJECT_ATTRIBUTES` flag indicates that the open operation should search for a named object in a case-insensitive manner. + +# Related flags + - `OBJ_PROTECT_CLOSE` + - `OBJ_INHERIT` + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` + - `OBJ_PERMANENT` + - `OBJ_EXCLUSIVE` + - `OBJ_OPENIF` + - `OBJ_OPENLINK` + - `OBJ_KERNEL_HANDLE` + - `OBJ_FORCE_ACCESS_CHECK` + - `OBJ_IGNORE_IMPERSONATED_DEVICEMAP` + - `OBJ_DONT_REPARSE` + +# See also + - `OBJECT_ATTRIBUTES` diff --git a/descriptions/obj_dont_reparse.md b/descriptions/obj_dont_reparse.md index e69de29bb2d..37ba3613302 100644 --- a/descriptions/obj_dont_reparse.md +++ b/descriptions/obj_dont_reparse.md @@ -0,0 +1,18 @@ +This `OBJECT_ATTRIBUTES` flag indicates that the open/create operation should fail with `STATUS_REPARSE_POINT_ENCOUNTERED` if the target path contains reparse points. + +# Related flags + - `OBJ_PROTECT_CLOSE` + - `OBJ_INHERIT` + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` + - `OBJ_PERMANENT` + - `OBJ_EXCLUSIVE` + - `OBJ_CASE_INSENSITIVE` + - `OBJ_OPENIF` + - `OBJ_OPENLINK` + - `OBJ_KERNEL_HANDLE` + - `OBJ_FORCE_ACCESS_CHECK` + - `OBJ_IGNORE_IMPERSONATED_DEVICEMAP` + +# See also + - `OBJECT_ATTRIBUTES` diff --git a/descriptions/obj_exclusive.md b/descriptions/obj_exclusive.md index e69de29bb2d..f852c37ae40 100644 --- a/descriptions/obj_exclusive.md +++ b/descriptions/obj_exclusive.md @@ -0,0 +1,20 @@ +This `OBJECT_ATTRIBUTES` flag indicates that the object/handle should be marked as exclusive. Exclusive handles prevent other callers from opening handles to the object. + +# Related flags + - `OBJ_PROTECT_CLOSE` + - `OBJ_INHERIT` + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` + - `OBJ_PERMANENT` + - `OBJ_CASE_INSENSITIVE` + - `OBJ_OPENIF` + - `OBJ_OPENLINK` + - `OBJ_KERNEL_HANDLE` + - `OBJ_FORCE_ACCESS_CHECK` + - `OBJ_IGNORE_IMPERSONATED_DEVICEMAP` + - `OBJ_DONT_REPARSE` + +# See also + - `OBJECT_ATTRIBUTES` + - `NtQueryObject` + - `OBJECT_BASIC_INFORMATION` diff --git a/descriptions/obj_force_access_check.md b/descriptions/obj_force_access_check.md index e69de29bb2d..28447efc8fd 100644 --- a/descriptions/obj_force_access_check.md +++ b/descriptions/obj_force_access_check.md @@ -0,0 +1,18 @@ +This `OBJECT_ATTRIBUTES` flag forces the system to perform an access check on the target object when called from kernel mode. + +# Related flags + - `OBJ_PROTECT_CLOSE` + - `OBJ_INHERIT` + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` + - `OBJ_PERMANENT` + - `OBJ_EXCLUSIVE` + - `OBJ_CASE_INSENSITIVE` + - `OBJ_OPENIF` + - `OBJ_OPENLINK` + - `OBJ_KERNEL_HANDLE` + - `OBJ_IGNORE_IMPERSONATED_DEVICEMAP` + - `OBJ_DONT_REPARSE` + +# See also + - `OBJECT_ATTRIBUTES` diff --git a/descriptions/obj_ignore_impersonated_devicemap.md b/descriptions/obj_ignore_impersonated_devicemap.md index e69de29bb2d..36c7dd23bb0 100644 --- a/descriptions/obj_ignore_impersonated_devicemap.md +++ b/descriptions/obj_ignore_impersonated_devicemap.md @@ -0,0 +1,20 @@ +This `OBJECT_ATTRIBUTES` flag indicates that the open/create operation should ignore the device map from the logon session of the impersonated token. + +# Related flags + - `OBJ_PROTECT_CLOSE` + - `OBJ_INHERIT` + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` + - `OBJ_PERMANENT` + - `OBJ_EXCLUSIVE` + - `OBJ_CASE_INSENSITIVE` + - `OBJ_OPENIF` + - `OBJ_OPENLINK` + - `OBJ_KERNEL_HANDLE` + - `OBJ_FORCE_ACCESS_CHECK` + - `OBJ_DONT_REPARSE` + +# See also + - `OBJECT_ATTRIBUTES` + - `NtOpenThreadToken` + - `NtSetInformationThread` with `ThreadImpersonationToken` diff --git a/descriptions/obj_inherit.md b/descriptions/obj_inherit.md index e69de29bb2d..e268532c245 100644 --- a/descriptions/obj_inherit.md +++ b/descriptions/obj_inherit.md @@ -0,0 +1,25 @@ +This `OBJECT_ATTRIBUTES` flag indicates that the handle should be inheriable. Whether the child processes actually inherit this handle depends on the flags used during process creation and some other attributes of the object. + +# Related flags + - `OBJ_PROTECT_CLOSE` + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` + - `OBJ_PERMANENT` + - `OBJ_EXCLUSIVE` + - `OBJ_CASE_INSENSITIVE` + - `OBJ_OPENIF` + - `OBJ_OPENLINK` + - `OBJ_KERNEL_HANDLE` + - `OBJ_FORCE_ACCESS_CHECK` + - `OBJ_IGNORE_IMPERSONATED_DEVICEMAP` + - `OBJ_DONT_REPARSE` + +# See also + - `OBJECT_ATTRIBUTES` + - `NtQueryObject` + - `NtSetInformationObject` + - `OBJECT_HANDLE_FLAG_INFORMATION` + - `OBJECT_BASIC_INFORMATION` + - `NtCreateProcess` + - `NtCreateProcessEx` + - `NtCreateUserProcess` diff --git a/descriptions/obj_kernel_handle.md b/descriptions/obj_kernel_handle.md index e69de29bb2d..461d90fc202 100644 --- a/descriptions/obj_kernel_handle.md +++ b/descriptions/obj_kernel_handle.md @@ -0,0 +1,18 @@ +This `OBJECT_ATTRIBUTES` flag indicates that the handle should be inserted into the kernel handle table as opposed to the handle table of the attached process. This flag cannot be used from user mode. + +# Related flags + - `OBJ_PROTECT_CLOSE` + - `OBJ_INHERIT` + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` + - `OBJ_PERMANENT` + - `OBJ_EXCLUSIVE` + - `OBJ_CASE_INSENSITIVE` + - `OBJ_OPENIF` + - `OBJ_OPENLINK` + - `OBJ_FORCE_ACCESS_CHECK` + - `OBJ_IGNORE_IMPERSONATED_DEVICEMAP` + - `OBJ_DONT_REPARSE` + +# See also + - `OBJECT_ATTRIBUTES` diff --git a/descriptions/obj_openif.md b/descriptions/obj_openif.md index e69de29bb2d..d4a71f5e6ab 100644 --- a/descriptions/obj_openif.md +++ b/descriptions/obj_openif.md @@ -0,0 +1,18 @@ +This `OBJECT_ATTRIBUTES` flag indicates that the create operation should open the object if the specified name is already taken. + +# Related flags + - `OBJ_PROTECT_CLOSE` + - `OBJ_INHERIT` + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` + - `OBJ_PERMANENT` + - `OBJ_EXCLUSIVE` + - `OBJ_CASE_INSENSITIVE` + - `OBJ_OPENLINK` + - `OBJ_KERNEL_HANDLE` + - `OBJ_FORCE_ACCESS_CHECK` + - `OBJ_IGNORE_IMPERSONATED_DEVICEMAP` + - `OBJ_DONT_REPARSE` + +# See also + - `OBJECT_ATTRIBUTES` diff --git a/descriptions/obj_openlink.md b/descriptions/obj_openlink.md index e69de29bb2d..9cc1b30955a 100644 --- a/descriptions/obj_openlink.md +++ b/descriptions/obj_openlink.md @@ -0,0 +1,18 @@ +This `OBJECT_ATTRIBUTES` flag indicates that the open operation should open the reparse point instead of following it. + +# Related flags + - `OBJ_PROTECT_CLOSE` + - `OBJ_INHERIT` + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` + - `OBJ_PERMANENT` + - `OBJ_EXCLUSIVE` + - `OBJ_CASE_INSENSITIVE` + - `OBJ_OPENIF` + - `OBJ_KERNEL_HANDLE` + - `OBJ_FORCE_ACCESS_CHECK` + - `OBJ_IGNORE_IMPERSONATED_DEVICEMAP` + - `OBJ_DONT_REPARSE` + +# See also + - `OBJECT_ATTRIBUTES` diff --git a/descriptions/obj_permanent.md b/descriptions/obj_permanent.md index e69de29bb2d..33abfc536c4 100644 --- a/descriptions/obj_permanent.md +++ b/descriptions/obj_permanent.md @@ -0,0 +1,25 @@ +This `OBJECT_ATTRIBUTES` flag indicates that the object should be marked as permanent. This flag alters the lifetime of the object, making it independent from reference counting. Creating or marking objects as permanent requires `SeCreatePermanentPrivilege`. To delete such object, make it temporary first via `NtMakeTemporaryObject`. + +# Related flags + - `OBJ_PROTECT_CLOSE` + - `OBJ_INHERIT` + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` + - `OBJ_EXCLUSIVE` + - `OBJ_CASE_INSENSITIVE` + - `OBJ_OPENIF` + - `OBJ_OPENLINK` + - `OBJ_KERNEL_HANDLE` + - `OBJ_FORCE_ACCESS_CHECK` + - `OBJ_IGNORE_IMPERSONATED_DEVICEMAP` + - `OBJ_DONT_REPARSE` + +# Remarks +To make an existing object permanent, use `NtMakePermanentObject`. + +# See also + - `OBJECT_ATTRIBUTES` + - `NtMakePermanentObject` + - `NtMakeTemporaryObject` + - `NtQueryObject` + - `OBJECT_BASIC_INFORMATION` diff --git a/descriptions/obj_protect_close.md b/descriptions/obj_protect_close.md index e69de29bb2d..18f9847119f 100644 --- a/descriptions/obj_protect_close.md +++ b/descriptions/obj_protect_close.md @@ -0,0 +1,22 @@ +This `OBJECT_ATTRIBUTES` flag indicates that the handle should be protected from closing. Passing such handle to `NtClose` returns an error; trying to close it via `NtDuplicateObject` has no effect. + +# Related flags + - `OBJ_INHERIT` + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` + - `OBJ_PERMANENT` + - `OBJ_EXCLUSIVE` + - `OBJ_CASE_INSENSITIVE` + - `OBJ_OPENIF` + - `OBJ_OPENLINK` + - `OBJ_KERNEL_HANDLE` + - `OBJ_FORCE_ACCESS_CHECK` + - `OBJ_IGNORE_IMPERSONATED_DEVICEMAP` + - `OBJ_DONT_REPARSE` + +# See also + - `OBJECT_ATTRIBUTES` + - `NtQueryObject` + - `NtSetInformationObject` + - `OBJECT_HANDLE_FLAG_INFORMATION` + - `OBJECT_BASIC_INFORMATION` diff --git a/descriptions/object_attributes.md b/descriptions/object_attributes.md index e69de29bb2d..d2cb04b8f56 100644 --- a/descriptions/object_attributes.md +++ b/descriptions/object_attributes.md @@ -0,0 +1,33 @@ +Describes the name and other attributes of an object for open or creation operations. This structure is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows/win32/api/ntdef/ns-ntdef-_object_attributes). Use `InitializeObjectAttributes` to initialize this structure. + +# Members + - `Length` - the size of the structure; set it to `sizeof(OBJECT_ATTRIBUTES)`. + - `RootDirectory` - an optional handle to an object relative to which the system should interpret the `ObjectName` field. + - `ObjectName` - the absolute native name of the object when the `RootDirectory` field is `NULL` or a relative name otherwise. Set this value to `NULL` for unnamed objects. + - `Attributes` - a set of bit flags described below. + - `SecurityDescriptor` - an optional pointer to a security descriptor to protect the object with during creation. + - `SecurityQualityOfService` - an optional pointer to a QoS structure that defines impersonation-related information. + +# Known attribute values + - `OBJ_PROTECT_CLOSE` - the handle is protected from closing. + - `OBJ_INHERIT` - the handle is inheritable. + - `OBJ_AUDIT_OBJECT_CLOSE` + - `OBJ_NO_RIGHTS_UPGRADE` - prevents upgrading rights when duplicating the handle. + - `OBJ_PERMANENT` - alters the lifetime management rules for the object, making it permanent. + - `OBJ_EXCLUSIVE` - allow only one handle to the object. + - `OBJ_CASE_INSENSITIVE` - treat the name of the object as case-insensitive. + - `OBJ_OPENIF` - open the existing object instead of failing to create one on name collision. + - `OBJ_OPENLINK` - open the reparse point instead of following it. + - `OBJ_KERNEL_HANDLE` - make a kernel handle. + - `OBJ_FORCE_ACCESS_CHECK` - force performing an access check even for kernel callers. + - `OBJ_IGNORE_IMPERSONATED_DEVICEMAP` - ignore device map from the impersonated token. + - `OBJ_DONT_REPARSE` - fail on encountering reparse points. + - `OBJ_KERNEL_EXCLUSIVE` + +See the corresponding pages for details. + +# Remarks +Native API uses a different format of paths from the Win32 API. The root of the NT object namespace is the `\` directory. For more details about the relationship between Native and Win32 filenames, see this [blog post](https://googleprojectzero.blogspot.com/2016/02/the-definitive-guide-on-win32-to-nt.html). + +# See also + - `InitializeObjectAttributes` diff --git a/descriptions/object_basic_information.md b/descriptions/object_basic_information.md index d28cfb33f0f..c9749578238 100644 --- a/descriptions/object_basic_information.md +++ b/descriptions/object_basic_information.md @@ -1,32 +1,56 @@ -Structure `OBJECT_BASIC_INFORMATION` is returned in a result of call `NtQueryObject` with `ObjectBasicInformation` information class. +Basic kernel handle/object information, common to all object types. -### Attributes +# Applicable to + - `NtQueryObject` with `ObjectBasicInformation`. -### DesiredAccess +# Members -### HandleCount +## Attributes +A bit mask containing attributes of the handle/object: -### ReferenceCount + - `OBJ_PROTECT_CLOSE` - the handle is protected from closing. + - `OBJ_INHERIT` - the handle is inheritable. + - `OBJ_PERMANENT` - object has permanent lifetime. + - `OBJ_EXCLUSIVE` - the handle/object is exclusive and prevents other handles from being open to the object. -### PagedPoolUsage +## GrantedAccess +The access mask granted on the handle. -### NonPagedPoolUsage +## HandleCount +The number of handles pointing to the object. -### Reserved[3] +## PointerCount +The number of pointers to the object. -### NameInformationLength +## PagedPoolCharge +The number of paged pool bytes charged for the object. -### TypeInformationLength +## NonPagedPoolCharge +The number of non-paged pool bytes charged for the object. -### SecurityDescriptorLength +## Reserved[3] +Unused field. -### CreationTime +## NameInfoSize +The number of bytes required to query object name information. -# Documented by +### See also + - `NtQueryObject` with `ObjectNameInformation`. -* Tomasz Nowak +## TypeInfoSize +The number of bytes required to query object type information. -# See also +### See also + - `NtQueryObject` with `ObjectTypeInformation`. -* `NtQueryObject` -* `OBJECT_INFORMATION_CLASS` +## SecurityDescriptorSize +The number of bytes required to query the security descriptor of the object. Note that the system populates this field only when the handle grants `READ_CONTROL` access. + +### See also + - `NtQuerySecurityObject` + +## CreationTime +The time of creation for symbolic link objects. + +### See also + - `NtCreateSymbolicLinkObject` diff --git a/descriptions/object_handle_flag_information.md b/descriptions/object_handle_flag_information.md index e69de29bb2d..82455d95e38 100644 --- a/descriptions/object_handle_flag_information.md +++ b/descriptions/object_handle_flag_information.md @@ -0,0 +1,23 @@ +This structure controls handle inheritance and protection attributes. + +# Applicable to + - `NtQueryObject` with `ObjectHandleFlagInformation`. + - `NtSetInformationObject` with `ObjectHandleFlagInformation`. + +# Members + +## Inherit +A boolean indicating whether the handle is marked as inheritable. + +### See also + - `OBJ_INHERIT` + - `NtCreateProcess` + - `NtCreateProcessEx` + - `NtCreateUserProcess` + +## ProtectFromClose +A boolean indicating whether the handle is marked as protected from closing. + +### See also + - `OBJ_PROTECT_CLOSE` + - `NtClose` diff --git a/descriptions/object_information_class.md b/descriptions/object_information_class.md index 87c5e92dfd4..0dd18df5eec 100644 --- a/descriptions/object_information_class.md +++ b/descriptions/object_information_class.md @@ -1,45 +1,61 @@ -This enumeration is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/ne-ntifs-_object_information_class). +Defines common types of information that can be queried or set for kernel handles/objects. This enumeration is partially [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/ne-ntifs-_object_information_class). ---- +# Applicable to + - `NtQueryObject` + - `NtSetInformationObject` -`OBJECT_INFORMATION_CLASS` specifies a kind of information of any object available in caller context. It's used with functions `NtQueryObject` and `NtSetInformationObject`. +# Members -### ObjectBasicInformation -* Action: `Query` -* Buffer size: *0x038* -* Structure: `OBJECT_BASIC_INFORMATION` +## ObjectBasicInformation (0) +Retrieves basic information about the handle and the underlying object, such as the granted access mask and handle count. -### ObjectNameInformation +| | Query | Set +| --------------- | -------------------------- | --- +| Type | `OBJECT_BASIC_INFORMATION` | N/A +| Required access | None | N/A +| Optional access | `READ_CONTROL` | N/A -* Action: `Query` -* Buffer size: *0x08* -* Structure: `OBJECT_NAME_INFORMATION` +## ObjectNameInformation (1) +Retrieves the name of the object in its native form. -### ObjectTypeInformation +| | Query | Set +| --------------- | ------------------------- | --- +| Type | `OBJECT_NAME_INFORMATION` | N/A +| Required access | None | N/A -* Action: `Query` -* Buffer size: *0x070* -* Structure: `OBJECT_TYPE_INFORMATION` +## ObjectTypeInformation (2) +Retrieves information about the type of the object referenced via the handle. -### ObjectAllInformation +| | Query | Set +| --------------- | ------------------------- | --- +| Type | `OBJECT_TYPE_INFORMATION` | N/A +| Required access | None | N/A -* Action: `Query` -* Buffer size: *0x04+* -* Structure: `OBJECT_ALL_INFORMATION` -* Comment: Size of buffer depends on number of objects opened by caller. +## ObjectTypesInformation (3) +Retrieves information about all types of kernel objects registered on the system. This information class does not require a handle on input. -### ObjectDataInformation +| | Query | Set +| --------------- | -------------------------- | --- +| Type | `OBJECT_TYPES_INFORMATION` | N/A +| Required access | N/A | N/A -* Action: `Query, Set` -* Buffer size: *0x02* -* Structure: `OBJECT_DATA_INFORMATION` +## ObjectHandleFlagInformation (4) +Controls handle inheritance and protection attributes. -# Documented by +| | Query | Set +| --------------- | -------------------------------- | --- +| Type | `OBJECT_HANDLE_FLAG_INFORMATION` | `OBJECT_HANDLE_FLAG_INFORMATION` +| Required access | None | None -* Tomasz Nowak +### Related Win32 API + - [`GetHandleInformation`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-gethandleinformation) + - [`SetHandleInformation`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-sethandleinformation) -# See also +### See also + - `OBJ_INHERIT` + - `OBJ_PROTECT_CLOSE` -* `NtQueryObject` -* `NtSetInformationObject` +## ObjectSessionInformation (5) + +## ObjectSessionObjectInformation (6) diff --git a/descriptions/object_name_information.md b/descriptions/object_name_information.md index 4cd472101ea..b4108d835be 100644 --- a/descriptions/object_name_information.md +++ b/descriptions/object_name_information.md @@ -1,18 +1,9 @@ -Structure `OBJECT_NAME_INFORMATION` is used as a result of call `NtQueryObject` with `ObjectNameInformation` information class. +This structure describes the full name for named kernel objects. -### Name +# Applicable to + - `NtQueryObject` with `ObjectNameInformation`. -Name of object or `NULL` if object don't have associated name. +# Members -### NameBuffer[0] - -Buffer with UNICODE name of object. - -# Documented by - -* Tomasz Nowak - -# See also - -* `NtQueryObject` -* `OBJECT_INFORMATION_CLASS` +## Name +The name of the object inside the NT namespace. For more details about the relationship between Native and Win32 filenames, see this [blog post](https://googleprojectzero.blogspot.com/2016/02/the-definitive-guide-on-win32-to-nt.html). diff --git a/descriptions/object_type_information.md b/descriptions/object_type_information.md index c6c02ff6aeb..8e68c70f113 100644 --- a/descriptions/object_type_information.md +++ b/descriptions/object_type_information.md @@ -1,14 +1,76 @@ +This structure describes various information about a type of kernel objects. +# Applicable to + - `NtQueryObject` with `ObjectTypeInformation`. + - `OBJECT_TYPES_INFORMATION` -# Documented by +# Members -* Tomasz Nowak +## TypeName +The string containing the name unique of the type, such as `Process` or `IoCompletion`. -# See also +## TotalNumberOfObjects +The current number of objects of this type. -* `NtQueryObject` -* `OBJECT_ALL_INFORMATION` -* `OBJECT_BASIC_INFORMATION` -* `OBJECT_DATA_INFORMATION` -* `OBJECT_NAME_INFORMATION` -* `OBJECT_TYPE_INFORMATION` +## TotalNumberOfHandles +The current number of handles to objects of this type. + +## TotalPagedPoolUsage +The total number of paged pool bytes used by objects of this type. + +## TotalNonPagedPoolUsage +The total number of non-paged pool bytes used by objects of this type. + +## TotalNamePoolUsage +The total number of name pool bytes used by objects of this type. + +## TotalHandleTableUsage +The total number of handle table bytes used by objects of this type. + +## HighWaterNumberOfObjects +The maximum recorded number of objects of this type since boot. + +## HighWaterNumberOfHandles +The maximum recorded number of handles to objects of this type since boot. + +## HighWaterPagedPoolUsage +The maximum recorded number of paged pool bytes used by objects of this type. + +## HighWaterNonPagedPoolUsage +The maximum recorded number of non-paged pool bytes used by objects of this type. + +## HighWaterNamePoolUsage +The maximum recorded number of name pool bytes used by objects of this type. + +## HighWaterHandleTableUsage +The maximum recorded number of handle table bytes used by objects of this type. + +## InvalidAttributes +A bit mask of object/handle attribute flags that are not applicable to objects this type. For the list of values, see `OBJECT_ATTRIBUTES`. + +## GenericMapping +A mapping between specific and generic access rights for this type. + +## ValidAccessMask +A bit mask describing specific and standard access rights that are valid for objects of this type. + +## SecurityRequired +Whether unnamed objects of this type maintain security descriptors. + +## MaintainHandleCount +Whether the system should keep track of handles for this type. + +## TypeIndex +The index of this type in the global list of kernel types. Note that the system only populates this value on Windows 8.1 and above. To infer the value on older OS versions, take the index under which the type appears in the result of `ObjectTypesInformation` enumeration (made via `NtQueryObject`) and add 2 to it. + +## ReservedByte +This field in reserved for future use. + +## PoolType +The type of memory pool used by this type. + +## DefaultPagedPoolCharge +The default number of paged pool bytes charged for objects of this type. + +## DefaultNonPagedPoolCharge +The default number of non-paged pool bytes charged for objects of this type. diff --git a/descriptions/object_types_information.md b/descriptions/object_types_information.md index e69de29bb2d..b6ad84019d5 100644 --- a/descriptions/object_types_information.md +++ b/descriptions/object_types_information.md @@ -0,0 +1,33 @@ +This structure defines a collection of all registered types of kernel objects. + +# Applicable to + - `NtQueryObject` with `ObjectTypesInformation`. + +# Members + +## NumberOfTypes +The total number of types present. + +## (Variable part) +The variable part of the structure contains variable-sized `OBJECT_TYPES_INFORMATION` structures following each other. Each entry occupies `sizeof(OBJECT_TYPE_INFORMATION) + entry->TypeName.MaximumLength` bytes and is aligned up to a pointer boundary. + +# Parsing +Here is an example on how to parse this structure: + +```c +#define ALIGN_UP(p) ((PVOID)(((ULONG_PTR)p + sizeof(PVOID) - 1) & ~(sizeof(PVOID) - 1))) + +POBJECT_TYPES_INFORMATION types = { ... }; + +// Locate the first entry +POBJECT_TYPE_INFORMATION entry = ALIGN_UP(((ULONG_PTR)types + sizeof(OBJECT_TYPES_INFORMATION))); + +for (ULONG i = 0; i < types->NumberOfTypes; i++) +{ + // Process the entry + wprintf_s(L"%wZ\r\n", &entry->TypeName); + + // Advance to the next one + entry = ALIGN_UP((ULONG_PTR)entry + sizeof(OBJECT_TYPE_INFORMATION) + entry->TypeName.MaximumLength); +} +``` diff --git a/descriptions/ps_attribute_client_id.md b/descriptions/ps_attribute_client_id.md index 0229e15659c..aeb63e26b31 100644 --- a/descriptions/ps_attribute_client_id.md +++ b/descriptions/ps_attribute_client_id.md @@ -2,14 +2,14 @@ This attribute allows the caller to request the client ID of the new thread to b # Parameters - `Attribute` - `PS_ATTRIBUTE_CLIENT_ID` (numeric value `0x10003`). - - `Size` - `sizeof(CLIEND_ID)`. - - `ValuePtr` - a pointer to a `CLIEND_ID` buffer that receives the ID of the new thread. + - `Size` - `sizeof(CLIENT_ID)`. + - `ValuePtr` - a pointer to a `CLIENT_ID` buffer that receives the ID of the new thread. # Applicable to - `NtCreateThreadEx` - `NtCreateUserProcess` # See also - - `CLIEND_ID` + - `CLIENT_ID` - `NtOpenThread` - `PS_ATTRIBUTE_NUM` diff --git a/descriptions/psattributevalue.md b/descriptions/psattributevalue.md index 538de6743c8..dfa0e285d9c 100644 --- a/descriptions/psattributevalue.md +++ b/descriptions/psattributevalue.md @@ -2,7 +2,7 @@ This macro allows constructing a process/thread creation attribute value based o # Known values - `PS_ATTRIBUTE_PARENT_PROCESS` = 0x60000; - - `PS_ATTRIBUTE_DEBUG_PORT` = 0x60001; + - `PS_ATTRIBUTE_DEBUG_OBJECT` = 0x60001; - `PS_ATTRIBUTE_TOKEN` = 0x60002; - `PS_ATTRIBUTE_CLIENT_ID` = 0x10003; - `PS_ATTRIBUTE_TEB_ADDRESS` = 0x10004; diff --git a/descriptions/queue_user_apc_callback_data_context.md b/descriptions/queue_user_apc_callback_data_context.md index 8844e0288af..d241e9c9990 100644 --- a/descriptions/queue_user_apc_callback_data_context.md +++ b/descriptions/queue_user_apc_callback_data_context.md @@ -1,4 +1,4 @@ -This flags indicates that the callback routine should receive the context (set of registers) that was interrupted when the thread was directed to call the APC function. The the documentation for [the corresponding Win32 flags](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/ne-processthreadsapi-queue_user_apc_flags) for more details. +This flags indicates that the callback routine should receive the context (set of registers) that was interrupted when the thread was directed to call the APC function. See the documentation for [the corresponding Win32 flags](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/ne-processthreadsapi-queue_user_apc_flags) for more details. # Applicable to - `NtQueueApcThreadEx2` diff --git a/descriptions/queue_user_apc_flags_special_user_apc.md b/descriptions/queue_user_apc_flags_special_user_apc.md index 7a1677b9c84..e53c4d6c242 100644 --- a/descriptions/queue_user_apc_flags_special_user_apc.md +++ b/descriptions/queue_user_apc_flags_special_user_apc.md @@ -10,5 +10,7 @@ This flags indicates the use of a *special user-mode APC* that does not require # Remarks For the introduction to special user-mode APCs, see [this blog post](https://repnz.github.io/posts/apc/user-apc/#ntqueueapcthreadex-meet-special-user-apc). +Because execution of special APCs is not synchronized with the target thread (which might happen to acquire locks), it is crucial to keep the amount and complexity of the code invoked by the special APC routine to a minimum. + # Required OS version This flag was introduced in Windows 11. diff --git a/descriptions/queue_user_apc_special_user_apc.md b/descriptions/queue_user_apc_special_user_apc.md index d4f898cc616..ff2183354ce 100644 --- a/descriptions/queue_user_apc_special_user_apc.md +++ b/descriptions/queue_user_apc_special_user_apc.md @@ -6,5 +6,7 @@ This constant defines a special value for `ReserveHandle` that allows queuing *s # Remarks For the introduction to special user-mode APCs, see [this blog post](https://repnz.github.io/posts/apc/user-apc/#ntqueueapcthreadex-meet-special-user-apc). +Because execution of special APCs is not synchronized with the target thread (which might happen to acquire locks), it is crucial to keep the amount and complexity of the code invoked by the special APC routine to a minimum. + # Required OS version This flag was introduced in Windows 10 RS5 (1809). diff --git a/descriptions/rtliscurrentprocess.md b/descriptions/rtliscurrentprocess.md index e69de29bb2d..8db406b1419 100644 --- a/descriptions/rtliscurrentprocess.md +++ b/descriptions/rtliscurrentprocess.md @@ -0,0 +1,15 @@ +Determines whether the specified handle is a handle to the current process. + +# Parameters + - `ProcessHandle` - a process handle. The handle does not need to grant any specific access mask. + +# Implementation details +This function is a wrapper over `NtCompareObjects`. + +# Related Win32 API +This functionality is not exposed in Win32 API. + +# See also + - `NtCompareObjects` + - `NtOpenProcess` + - `RtlIsCurrentThread` diff --git a/descriptions/rtliscurrentthread.md b/descriptions/rtliscurrentthread.md index 03d9460b4b7..510c7b655ca 100644 --- a/descriptions/rtliscurrentthread.md +++ b/descriptions/rtliscurrentthread.md @@ -1,7 +1,7 @@ Determines whether the specified handle is a handle to the current thread. # Parameters - - `ThreadHandle` - a thread handle with any access mask. + - `ThreadHandle` - a thread handle. The handle does not need to grant any specific access mask. # Implementation details This function is a wrapper over `NtCompareObjects`. @@ -12,3 +12,4 @@ This functionality is not exposed in Win32 API. # See also - `NtCompareObjects` - `NtOpenThread` + - `RtlIsCurrentProcess`