RegGetKeySecurity

The RegGetKeySecurity function retrieves a copy of the security descriptor protecting the specified open registry key.

LONG RegGetKeySecurity(
  HKEY hKey,                                // handle to key
  SECURITY_INFORMATION SecurityInformation, // request
  PSECURITY_DESCRIPTOR pSecurityDescriptor, // SD
  LPDWORD lpcbSecurityDescriptor            // buffer size
);

Parameters

hKey

[in] Handle to an open key for which to retrieve the security descriptor.

SecurityInformation

[in] Specifies a SECURITY_INFORMATION value that indicates the requested security information.

pSecurityDescriptor

[out] Pointer to a buffer that receives a copy of the requested security descriptor.

lpcbSecurityDescriptor

[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pSecurityDescriptor parameter. When the function returns, the variable contains the number of bytes written to the buffer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

If the buffer specified by the pSecurityDescriptor parameter is too small, the function returns ERROR_INSUFFICIENT_BUFFER and the lpcbSecurityDescriptor parameter contains the number of bytes required for the requested security descriptor.

To read the owner, group, or DACL from the key's security descriptor, the calling process must have been granted READ_CONTROL access when the handle was opened. To get READ_CONTROL access, the caller must be the owner of the key or the key's DACL must grant the access.

To read the SACL from the security descriptor, the calling process must have been granted ACCESS_SYSTEM_SECURITY access when the key was opened. The proper 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.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Header: Declared in Winreg.h; include Windows.h.
  Library: Use Advapi32.lib.

See Also

Low-Level Access-Control Overview, Low-Level Access Control Functions, RegDeleteKey, RegOpenKeyEx, RegSetKeySecurity, SECURITY_INFORMATION