ObGetObjectSecurity function (wdm.h)

The ObGetObjectSecurity routine gets the security descriptor for a given object.

Syntax

NTSTATUS ObGetObjectSecurity(
  [in]  PVOID                Object,
  [out] PSECURITY_DESCRIPTOR *SecurityDescriptor,
  [out] PBOOLEAN             MemoryAllocated
);

Parameters

[in] Object

Pointer to the object.

[out] SecurityDescriptor

Pointer to a caller-supplied variable that this routine sets to the address of a buffer containing the SECURITY_DESCRIPTOR for the given object. If the given object has no security descriptor, this variable is set to NULL on return from ObGetObjectSecurity.

[out] MemoryAllocated

Pointer to a caller-supplied variable that this routine sets to TRUE if it allocated a buffer to contain the security descriptor.

Return value

ObGetObjectSecurity either returns STATUS_SUCCESS or an error status, such as STATUS_INSUFFICIENT_RESOURCES if it could not allocate enough memory to return the requested information.

Remarks

A successful call to ObGetObjectSecurity either returns a self-relative security descriptor in the buffer at *SecurityDescriptor or it returns NULL at *SecurityDescriptor if the given object has no security descriptor. For example, any unnamed object, such as an event object, has no security descriptor.

If ObGetObjectSecurity returns STATUS_SUCCESS, the caller must save the value returned at MemoryAllocated. Such a caller must pass MemoryAllocated in a reciprocal call to ObReleaseObjectSecurity eventually, thereby restoring the reference count on the security descriptor to its original value and releasing the buffer, if any, that was allocated by ObGetObjectSecurity.

ObGetObjectSecurity should only be called at IRQL Level = PASSIVE_LEVEL with APCs enabled, otherwise deadlocks or crashes may occur.

Requirements

See also

ObReferenceObjectByHandle

ObReleaseObjectSecurity

SECURITY_DESCRIPTOR