Share via

3.1.4.2.40 ApiSetKeySecurity (Opnum 39)

  • Article

(Protocol Version 3) The ApiSetKeySecurity method modifies any or all components of the security descriptor for the designated cluster key.

The server MUST accept an ApiSetKeySecurity request for processing only if it is in the read/write state, as specified in section 3.1.1.

The server MUST require that the client have a security access level of "All" (section 3.1.4).

 error_status_t ApiSetKeySecurity(
   [in] HKEY_RPC hKey,
   [in] DWORD SecurityInformation,
   [in] PRPC_SECURITY_DESCRIPTOR pRpcSecurityDescriptor,
   [out] error_status_t *rpc_status
 );

hKey: The RPC context handle for a key that was previously obtained by a call to ApiGetRootKey, ApiCreateKey, or ApiOpenKey.

SecurityInformation: A bitmask, as described in [MS-RRP] section 2.2.9, that indicates which components of the security descriptor designated pRpcSecurityDescriptor are used to modify the key's security descriptor.

pRpcSecurityDescriptor: A pointer to an RPC_SECURITY_DESCRIPTOR structure, as specified in section 2.2.3.1, that contains the security attributes for the designated key.

rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether the runtime succeeded in executing this method on the server. The encoding of the value passed in this parameter MUST conform to encoding for  comm_status and fault_status, as specified in Appendix E of [C706].

Return Values: The method MUST return the following error codes for the specified conditions.

Return value/code

Description

0x00000000

ERROR_SUCCESS

Success.

0x00000006

ERROR_INVALID_HANDLE

The hKey parameter does not represent a valid HKEY_RPC context handle.

0x00000057

ERROR_INVALID_PARAMETER

The RPC_SECURITY_DESCRIPTOR data structure identified by the pRpcSecurityDescriptor parameter does not contain a valid security descriptor in self-relative form, as specified in [MS-DTYP] section 2.4.6.

For any other condition, the server MUST set Status to a value that is not one of the values listed in the preceding table. The client MUST treat all values not listed in the preceding table the same, except as specified in section 3.2.4.6.