SeCaptureSubjectContext function (ntifs.h)

Article
02/22/2023

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

Syntax

void SeCaptureSubjectContext(
  [out] PSECURITY_SUBJECT_CONTEXT SubjectContext
);

Parameters

[out] SubjectContext

[out] Pointer to an opaque caller-allocated SECURITY_SUBJECT_CONTEXT structure. SeCaptureSubjectContext 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 SeCaptureSubjectContext 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.

SeCaptureSubjectContext 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 2000
Target Platform	Universal
Header	ntifs.h (include Ntifs.h, Wdm.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL