3.1.5.15 BaseRegOpenKey (Opnum 15)

The BaseRegOpenKey method is called by the client. In response, the server opens a specified key for access and returns a handle to it.

 error_status_t BaseRegOpenKey(
   [in] RPC_HKEY hKey,
   [in] PRRP_UNICODE_STRING lpSubKey,
   [in] DWORD dwOptions,
   [in] REGSAM samDesired,
   [out] PRPC_HKEY phkResult
 );

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, BaseRegOpenKey, OpenCurrentConfig, OpenPerformanceText, OpenPerformanceNlsText.

lpSubKey: A pointer to an RRP_UNICODE_STRING structure that MUST contain the name of a key to open. This parameter is always relative to the key that is specified by the hKey parameter and is a pointer to a null-terminated string that contains the name of the subkey to open, as specified in section 3.1.1. This key MUST be an existing subkey of the key that is identified by the hKey parameter.

dwOptions: Registry key options. MUST be the bitwise OR of any or none of the following values.

Value	Meaning
REG_OPTION_BACKUP_RESTORE 0x00000004	Indicates that the caller requests to assert its backup and/or restore privileges.
REG_OPTION_OPEN_LINK 0x00000008	Indicates that the caller requests to open the targeted symlink source rather than the symlink target.

samDesired: A bit field that describes the requested security access for the handle to the key that is being opened. It MUST be constructed from one or more of the values that are specified in section 2.2.3.

phkResult: A pointer to the handle of the open key. The server MUST return a NULL for phkResult in case of failure.

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.

Server Operations

In response to this request from the client, for a successful operation, the server SHOULD<19> open the registry key that is specified by the lpSubKey parameter. In the event of success, the server MUST create a handle to the new key for this request and return the handle value in the phkResult parameter.

If hKey is not an open handle to a key on the server, the server MUST fail the method and return ERROR_INVALID_HANDLE.

The server then determines which key namespace to operate on (KEYS32 or KEYS64) by inspecting the value of the samDesired parameter. If the server does not support the 64-bit key namespace (see section 3.1.1.4), the server MUST operate on the 32-bit key namespace (KEYS32).

If the server is a 64-bit registry server and supports both the 32-bit and 64-bit key namespaces, as defined in section 3.1.1.4, the server MUST first check if both the KEY_WOW64_64KEY and KEY_WOW64_32KEY bits are set in the samDesired parameter. If both KEY_WOW64_64KEY and KEY_WOW64_32KEY are set, the server SHOULD<20> fail the method and return ERROR_INVALID_PARAMETER.

The server then checks to see if the key specified by the hKey parameter is a key that can only be operated on in the 64-bit key namespace (KEYS64). See section 3.1.1.4.

If the key specified by the hKey parameter is a key that can only be operated on in the 64-bit key namespace (KEYS64), the server MUST ignore the KEY_WOW64_64KEY and KEY_WOW64_32KEY bits in the samDesired parameter and operate on and create or open the key in the 64-bit namespace (KEYS64).

If the key specified by lpSubKey has a KEYTYPE of symbolic link and the client has not set REG_OPTION_OPEN_LINK in the dwOptions parameter, the server MUST return a handle to the key that is the target of the symbolic link (see section 3.1.1.11). The server first checks for a value of the key indicated by lpSubKey named "SymbolicLinkValue". If a value named SymbolicLinkValue is not found, the server MUST fail the method and return ERROR_INVALID_PARAMETER. If the target of the symbolic link does not exist, the server MUST fail the method and return ERROR_INVALID_PARAMETER.

If the key specified by lpSubKey has a KEYTYPE of symbolic link and the client has set REG_OPTION_OPEN_LINK in the dwOptions parameter, the server returns a handle to the key that is the source of the symbolic link.

If the lpSubKey parameter is a pointer to an empty WCHAR array, the method returns a new handle to the same key indicated by the hKey parameter.

If lpSubKey is set to NULL by the client, the server MUST fail this method and return ERROR_INVALID_PARAMETER.

Next, the server checks if the KEY_WOW64_32KEY is set in the samDesired parameter. If the KEY_WOW64_32KEY is set in the samDesired parameter, the server MUST create the key in the 32-bit key namespace (KEYS32). If the KEY_WOW64_32KEY is not set in the samDesired parameter, the server MUST create the key in the 64-bit key namespace (KEYS64).

Next, the server MUST determine if the key path indicated by hKey and lpSubKey refer to a path that is within the subset of registry paths that can support both 64-bit and 32-bit key namespaces (section 3.1.1.4). If the key path indicated by hKey and lpSubKey are within the subset of registry paths that can support both 64-bit and 32-bit key namespaces, the server MUST open the registry key within the appropriate path in the 64-bit key namespace. For example, if hKey refers to HKEY_LOCAL_MACHINE\Software and the value of the lpSubKey parameter is "TEST_KEY" and the server MUST operate on the 32-bit key namespace, then the server MUST open the HKEY_LOCAL_MACHINE\Software\Wow6432Node\TEST_KEY key.

The server MUST first validate that the key specified by lpSubKey is a child key of the key specified by hKey. If the key specified by lpSubKey is not a subkey of the key specified by hKey, the server MUST set phkResult to NULL and return ERROR_FILE_NOT_FOUND.

If the dwOptions parameter specifies the REG_OPTION_BACKUP_RESTORE option, the server MUST ignore all bits set in the samDesired parameter except for KEY_WOW64_32KEY and KEY_WOW64_64KEY. The desired key access MUST be computed based on whether the caller holds the backup and restore privileges as outlined in the following table. If the caller holds neither privilege, the server MUST fail the method and return STATUS_ACCESS_DENIED.

Privileges Held	Desired Access
Backup and Restore	STANDARD_RIGHTS_READ KEY_QUERY_VALUE KEY_ENUMERATE_SUB_KEYS KEY_NOTIFY STANDARD_RIGHTS_WRITE KEY_SET_VALUE KEY_CREATE_SUB_KEY ACCESS_SYSTEM_SECURITY WRITE_DAC WRITE_OWNER DELETE
Only Backup	STANDARD_RIGHTS_READ KEY_QUERY_VALUE KEY_ENUMERATE_SUB_KEYS KEY_NOTIFY ACCESS_SYSTEM_SECURITY
Only Restore	STANDARD_RIGHTS_WRITE KEY_SET_VALUE KEY_CREATE_SUB_KEY ACCESS_SYSTEM_SECURITY WRITE_DAC WRITE_OWNER DELETE

The server MUST validate that the client has access to open the key using the security descriptor of the key indicated by lpSubKey. If the value of samDesired includes flags set that are not listed in section 2.2.3, the server MUST return ERROR_INVALID_PARAMETER.

If the caller is permitted to open the key, the server MUST return 0 to indicate success, create a new valid context handle, insert it into the handle table (HANDLETABLE), and place the handle value (see 3.1.1.9) in the phkResult parameter. If the caller does not have access, the server MUST return ERROR_ACCESS_DENIED.

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