GetUserObjectSecurity function (winuser.h)

Article
10/13/2021

The GetUserObjectSecurity function retrieves security information for the specified user object.

Syntax

BOOL GetUserObjectSecurity(
  [in]                HANDLE                hObj,
  [in]                PSECURITY_INFORMATION pSIRequested,
  [in, out, optional] PSECURITY_DESCRIPTOR  pSID,
  [in]                DWORD                 nLength,
  [out]               LPDWORD               lpnLengthNeeded
);

Parameters

[in] hObj

A handle to the user object for which to return security information.

[in] pSIRequested

A pointer to a SECURITY_INFORMATION value that specifies the security information being requested.

[in, out, optional] pSID

A pointer to a SECURITY_DESCRIPTOR structure in self-relative format that contains the requested information when the function returns. This buffer must be aligned on a 4-byte boundary.

[in] nLength

The length, in bytes, of the buffer pointed to by the pSD parameter.

[out] lpnLengthNeeded

A pointer to a variable to receive the number of bytes required to store the complete security descriptor. If this variable's value is greater than the value of the nLength parameter when the function returns, the function returns FALSE and none of the security descriptor is copied to the buffer. Otherwise, the entire security descriptor is copied.

Return value

If the function succeeds, the function returns nonzero.

If the function fails, it returns zero. To get extended error information, call GetLastError.

Remarks

To read the owner, group, or discretionary access control list (DACL) from the user object's security descriptor, the calling process must have been granted READ_CONTROL access when the handle was opened.

To read the system access control list (SACL) from the security descriptor, the calling process must have been granted ACCESS_SYSTEM_SECURITY access when the handle was opened. The correct way to get this access is to enable the SE_SECURITY_NAME privilege in the caller's current token, open the handle for ACCESS_SYSTEM_SECURITY access, and then disable the privilege.

Examples

For an example that uses this function, see Starting an Interactive Client Process.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	winuser.h (include Windows.h)
Library	User32.lib
DLL	User32.dll

Share via