RegGetKeySecurity

RegGetKeySecurity

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

LONG RegGetKeySecurity(

HKEY hKey,	// open handle of key to set
SECURITY_INFORMATION SecurityInformation,	// descriptor contents
PSECURITY_DESCRIPTOR pSecurityDescriptor,	// address of descriptor for key
LPDWORD lpcbSecurityDescriptor	// address of size of buffer and descriptor
);

Parameters

hKey

Identifies an open key for which to retrieve the security descriptor.

SecurityInformation

Specifies a SECURITY_INFORMATION structure that indicates the requested security information.

pSecurityDescriptor

Points to a buffer that receives a copy of the requested security descriptor.

lpcbSecurityDescriptor

Points 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 security descriptor for the specified key, the calling process must have been granted READ_CONTROL access when the key was opened, or it must be the owner of the key. (READ_CONTROL access is granted by the KEY_READ, KEY_WRITE, KEY_EXECUTE, and KEY_ALL_ACCESS access rights.) In addition, the caller must have the SE_SECURITY_NAME privilege to read the system access-control list (SACL).

For more information about security, see Security.