3.1.5.13 BaseRegGetKeySecurity (Opnum 12)

The BaseRegGetKeySecurity method is called by the client. In response, the server returns a copy of the security descriptor that protects the specified open registry key.

 error_status_t BaseRegGetKeySecurity(
   [in] RPC_HKEY hKey,
   [in] SECURITY_INFORMATION SecurityInformation,
   [in] PRPC_SECURITY_DESCRIPTOR pRpcSecurityDescriptorIn,
   [out] PRPC_SECURITY_DESCRIPTOR pRpcSecurityDescriptorOut
 );

hKey: A handle to a key that MUST have been opened previously by using one of the open methods that are specified in section 3.1.5: OpenClassesRoot, OpenCurrentUser, OpenLocalMachine, OpenPerformanceData, OpenUsers, BaseRegCreateKey, BaseRegOpenKey, OpenCurrentConfig, OpenPerformanceText, OpenPerformanceNlsText.

SecurityInformation: The information that is needed to determine the type of security that is returned in pRpcSecurityDescriptorOut. See SECURITY_INFORMATION (includes a list of possible values).

pRpcSecurityDescriptorIn: A pointer to a buffer containing a security descriptor. The client MUST provide a pointer to an RPC_SECURITY_DESCRIPTOR with arbitrary contents. The server uses the size of this security descriptor to validate the client has the correct amount of memory allocated for the RPC_SECURITY_DESCRIPTOR pointed to by the pRpcSecurityDescriptorOut parameter

pRpcSecurityDescriptorOut: A pointer to a buffer to which the requested security descriptor MUST be written.

Return Values: The method returns 0 (ERROR_SUCCESS) to indicate success; otherwise, it returns a nonzero error code, as specified in [MS-ERREF] section 2.2. The most common error codes are listed in the following table.

Return value/code	Description
0x0000000E ERROR_OUTOFMEMORY	Not enough storage is available to complete this operation.
0x00000057 ERROR_INVALID_PARAMETER	A parameter is incorrect.
0x00000013 ERROR_WRITE_PROTECT	A read or write operation was attempted to a volume after it was dismounted. The server can no longer service registry requests because server shutdown has been initiated.

Server Operations

If the registry server can no longer service registry requests because server shutdown has been initiated (SHUTDOWNINPROGRESS is set to TRUE), the server MUST return ERROR_WRITE_PROTECT.

If hKey refers to a key that is one of the predefined performance handles (HKEY_PERFORMANCE_DATA, HKEY_PERFORMANCE_TEXT or HKEY_PERFORMANCE_NLSTEXT) and the client has set bit 0x8 (SACL_SECURITY_INFORMATION) in the SecurityInformation parameter, the server MUST fail the method and return ERROR_PRIVILEGE_NOT_HELD.

The server MUST first validate that the hKey parameter is currently an open handle which MUST have been opened previously using one of the methods specified in section 3.1.5. If the hKey parameter is not an already opened handle, the server MUST return ERROR_INVALID_PARAMETER.

In response to this request from the client, for a successful operation, the server MUST return a copy of the SECURITY_DESCRIPTOR that is associated with the registry key that is specified by the hKey parameter.

The server MUST return the security descriptor in the buffer that is pointed to by the pRpcSecurityDescriptorOut parameter. The returned values in the pRpcSecurityDescriptorOut parameter depend on the values that are requested by the client in the SecurityInformation parameter. See SECURITY_INFORMATION.

The server MUST return 0 to indicate success or an appropriate error code (as specified in [MS-ERREF]) to indicate an error.

If the server returns 122 (ERROR_INSUFFICIENT_BUFFER), the size of the output buffer pointed to by the pRpcSecurityDescriptorOut parameter is not large enough. The required output buffer size is indicated by the cbInSecurityDescriptor field of the RPC_SECURITY_DESCRIPTOR structure pointed to by the pRpcSecurityDescriptorOut parameter. The remaining fields of the RPC_SECURITY_DESCRIPTOR structure MUST be NULL.