3.1.5.7 BaseRegCreateKey (Opnum 6)

The BaseRegCreateKey method is called by the client. In response, the server creates the specified registry key and returns a handle to the newly created key. If the key already exists in the registry, a handle to the existing key is opened and returned.

 error_status_t BaseRegCreateKey(
   [in] RPC_HKEY hKey,
   [in] PRRP_UNICODE_STRING lpSubKey,
   [in] PRRP_UNICODE_STRING lpClass,
   [in] DWORD dwOptions,
   [in] REGSAM samDesired,
   [in, unique] PRPC_SECURITY_ATTRIBUTES lpSecurityAttributes,
   [out] PRPC_HKEY phkResult,
   [in, out, unique] LPDWORD lpdwDisposition
 );

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: BaseRegCreateKey, OpenClassesRoot, OpenCurrentUser, OpenLocalMachine, OpenPerformanceData, OpenUsers, BaseRegOpenKey, OpenCurrentConfig, OpenPerformanceText, OpenPerformanceNlsText.

lpSubKey: A pointer to an RRP_UNICODE_STRING structure that specifies the name of the key (as specified in section 3.1.1.1) that this method opens or creates. The name of the key specified is relative to the key specified by the hkey parameter.

lpClass: A pointer to an RRP_UNICODE_STRING structure that specifies the class of the key (as specified in section 3.1.1.6).<16>

dwOptions: Registry key options. MUST be the bitwise OR of one of the key types defined in section 3.1.1.2, and any or none of the following options. The BaseRegCreateKey method fails with ERROR_INVALID_PARAMETER if an unlisted value is specified.

Value	Meaning
REG_OPTION_BACKUP_RESTORE 0x00000004	Indicates that the caller wishes to assert its backup and/or restore privileges.
REG_OPTION_OPEN_LINK 0x00000008	Indicates that the caller wishes to open the targeted symlink source rather than the symlink target.
REG_OPTION_DONT_VIRTUALIZE 0x00000010	Indicates that the caller wishes to disable limited user access virtualization for this operation.

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

lpSecurityAttributes: A pointer to an RPC_SECURITY_ATTRIBUTES structure for the new subkey provided a new subkey is created.

phkResult: A pointer to a variable that receives a handle to the opened or created key.

lpdwDisposition: The disposition of the returned key indicated by phkResult. The value of this parameter set by the client is ignored by the server. Its value MUST be one of the following.

Value	Meaning
REG_CREATED_NEW_KEY 0x00000001	The key did not exist and was created.
REG_OPENED_EXISTING_KEY 0x00000002	The key already existed and was opened without being changed.

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
0x00000005 ERROR_ACCESS_DENIED	The caller does not have KEY_CREATE_SUB_KEY access rights.
0x00000005 ERROR_ACCESS_DENIED	Access is denied.
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 the value of the lpSubKey parameter is NULL, the server MUST fail the method and return ERROR_INVALID_PARAMETER.

If this method fails, and the server returns a failure error code, the lpdwDisposition parameter is unchanged from the value set by the client.

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<17> 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 only to 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).

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 determines if the key supports subkey creation. If the key indicated by hKey refers to the predefined key HKEY_LOCAL_MACHINE or HKEY_USERS and lpSubKey is not specified (the key is to be created under HKEY_LOCAL_MACHINE or HKEY_USERS in the registry key hierarchy), the server MUST fail the method and return ERROR_INVALID_PARAMETER.

Then, 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 support both the 64-bit and 32-bit key namespaces (see section 3.1.1.4). If the key path indicated by hKey and lpSubKey are within the subset of registry paths that support both the 64-bit and 32-bit key namespaces, the server MUST open or create 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 or create the HKEY_LOCAL_MACHINE\Software\Wow6432Node\TEST_KEY key.

The server MUST determine if the key indicated by lpSubKey already exists within the set of children keys for the key indicated by hKey. If the key indicated by lpSubKey exists within the set of children keys for the key indicated by hKey, the server MUST create a new open handle to the key indicated by lpSubKey and return the handle in the phkResult parameter. The server MUST insert the new open handle in the handle table (HANDLETABLE). If the key already exists, the key type in the dwOptions parameter in the client request MUST be ignored.

If the key that is specified by the lpSubKey parameter already exists, the key on the server is opened, the key type in the dwOptions parameter in the client request is ignored, and REG_OPENED_EXISTING_KEY (0x00000002) is returned in the lpdwDisposition parameter.

The server MUST determine whether the client is requesting a nonvolatile key to be created as a child of a volatile key. If the key indicated by hKey or any of the intermediate keys specified by lpSubKey are volatile and the value of the dwOptions parameter is not equal to 0x00000001, the server MUST fail the method and return ERROR_CHILD_MUST_BE_VOLATILE (0x000003FD).

If the key indicated by lpSubKey does not exist within the set of children keys for the key indicated by hKey, the server MUST create a new key in the registry Data Store with a name equal to the name indicated by lpSubKey. If the client has set dwOptions to a value of 0x00000002, the server MUST create the new key with a KEYTYPE of symbolic link.

If the client has set dwOptions to a value of 0x00000002 (which specifies access to create a symbolic link) and the key indicated by lpSubKey already exists, the server MUST fail the method and return ERROR_ALREADY_EXISTS.

The server MUST open a handle to the newly created key and return the handle in the phkResult parameter. The server MUST insert the new open handle in the handle table (HANDLETABLE). The server MUST set the value of the lpdwDisposition parameter to REG_CREATED_NEW_KEY (0x00000001). If the key that is specified by the lpSubKey parameter already exists, the key on the server is opened, the dwOptions parameter in the client request is ignored, and 0x00000002 is returned in the lpdwDisposition parameter.

If the key indicated by lpSubKey exists within the set of registry paths for which keys and values are copied between the 32-bit and 64-bit key namespaces, the server MUST set the UPDATECOPY column in the HANDLETABLE to TRUE. The value of the UPDATECOPY column is inspected when the handle is closed to determine whether keys and values are to be copied between the 32-bit and 64-bit key namespaces.

For new keys that are created, if lpClass is not NULL, the server MUST set the class associated with the newly created key to the value of the Unicode string indicated by lpClass. The default class of registry keys is specified to be NULL.

For new keys that are created, the server MUST create the key based on the wanted key type that is specified in the dwOptions parameter. For key types, see section 3.1.1.2.

For new keys that are created, the server MUST set to TRUE the KEYISMODIFIED property of the new key.

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 table below. If the caller holds neither privilege, the server MUST fail the method and return STATUS_ACCESS_DENIED.

If a new key is to be created, the server MUST validate that the client has access to create the registry key indicated by the lpSubKey parameter using the security descriptor of the immediate parent key. If dwOptions specifies REG_OPTION_CREATE_LINK as the key type, an access mask of KEY_CREATE_SUB_KEY | KEY_CREATE_LINK is used for this comparison; otherwise, an access mask of KEY_CREATE_SUB_KEY is used. The access granted to the returned registry handle is the access specified in the samDesired parameter.

If an existing key is to be opened, the server MUST validate that the client has access to open the registry key indicated by the lpSubKey parameter using the security descriptor of the key to be opened and the access mask specified in the samDesired parameter. The access granted to the returned registry handle is the access specified in the samDesired parameter.

The REG_OPTION_DONT_VIRTUALIZE flag specified in the description of dwOptions SHOULD be ignored by the server.

If the client does not have permission to open or create the key, the server MUST fail the method and return ERROR_ACCESS_DENIED.

If the lpSecurityAttributes parameter is NULL and the subkey does not exist, then a created subkey gets a default security descriptor; the access control list (ACL) ([MS-DTYP] section 2.4.5) in the default security descriptor for a newly created subkey is inherited from the security descriptor of its direct parent key.

If the client sets the lpSubKey parameter to the empty string, the server MUST open a new handle to the key indicated by hKey and return the new handle in the phkResult parameter. For a successful operation, the server MUST return an open handle to the new key in the phkResult parameter in the event of success.