SeCaptureSubjectContextEx function (ntifs.h)

Article
02/22/2024

SeCaptureSubjectContextEx takes a snapshot of the calling thread's security context for access validation and auditing.

Syntax

void SeCaptureSubjectContextEx(
  PETHREAD                  Thread,
  PEPROCESS                 Process,
  PSECURITY_SUBJECT_CONTEXT SubjectContext
);

Parameters

Thread

[in] The thread from which to capture the thread token. This parameter is optional. When it's NULL, SeCaptureSubjectContextEx doesn't capture an impersonation token.

Process

[in] Pointer to the ID of the process from which to capture the primary token.

SubjectContext

[out] Pointer to an opaque caller-allocated SECURITY_SUBJECT_CONTEXT structure. SeCaptureSubjectContextEx will write the snapshot of the calling thread's security profile, which contains references to access tokens, in this structure. Drivers must not modify or try to directly access any members of this structure to make security decisions. Instead, to avoid security issues in authorization, pass this opaque structure in calls to SeAccessCheck or SePrivilegeCheck.

Return value

None

Remarks

You must call SeCaptureSubjectContextEx before performing services such as access validation or generating audit messages. This is necessary to provide a consistent security context to routines such as the following:

After access validation, privilege checking, and audit generation services have been performed, release the captured context as soon as possible by calling SeReleaseSubjectContext.

SeCaptureSubjectContextEx locks tokens as necessary while taking the snapshot of the calling thread's security context.

On return, references to access tokens are contained in the structure that SubjectContext points to. The contents of that structure can change. To prevent this, call SeLockSubjectContext to lock the primary access token and any impersonation tokens associated with the structure. For example, when using routines that query token information more than once in the same security context (such as the ones previously listed), lock the subject context with SeLockSubjectContext to obtain consistent results.

For more information about security and access control, see Windows security model for driver developers and the documentation on these topics in the Windows SDK.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Header	ntifs.h
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL