Registry Provider::CreateRegKeyWithSecurity

Registry Provider::CreateRegKeyWithSecurity

Creates a registry key and sets values for its discretionary access control lists (DACLs). Used by Microsoft® Provisioning Framework (MPF).

CreateRegKeyWithSecurity is a namespace-only procedure that executes CreateRegKey and Active Directory Provider::Update ACL.

XML Input Schema
The following code fragment shows the format for sending data to this procedure. For more information on individual elements and attributes, see the Elements and Attributes table.
<executeData>1..1
  <regKey>1..1
	<machine>1..1
	<name>1..1</name>
	</machine>
	<rootkey>1..1
	<name>1..1</name>
	</rootkey> 
	<subkey>1..1
	<name>1..1</name>
	</subkey>
  </regKey>
  <dacl>1..1
	<ace>0..unbounded
	<permission>1..unbounded</permission>
	<mode>1..1</mode>
	<trusteeForm>1..1</trusteeForm>
	<trustee>1..1</trustee>
	<trusteeType>0..1</trusteeType>
	<inheritance>0..unbounded</inheritance>
	<objectTypeName>0..1</objectTypeName>
	<inheritedObjectTypeName>0..1</inheritedObjectTypeName>
	</ace>
  </dacl>
</executeData>
XML Output Schema

CreateRegKeyWithSecurity does not return data.

Elements and Attributes

The following table describes the XML elements and attributes. Unless otherwise indicated, the data type is string.
Element Description, relationships, and attributes

ace Description:
Access control elements (ACEs) for the DACL.
Parent:
dacl

Children:
inheritance (minOccurs="0" maxOccurs="*")
inheritedObjectTypeName (minOccurs="0" maxOccurs="1")
mode (minOccurs="1" maxOccurs="1")
objectTypeName (minOccurs="0" maxOccurs="1")
permission (minOccurs="1" maxOccurs="*")
trustee (minOccurs="1" maxOccurs="1")
trusteeForm (minOccurs="1" maxOccurs="1")
trusteeType (minOccurs="0" maxOccurs="1")

dacl Description:
DACL for the specified registry key; consists of ACEs.
Parent:
executeData

Child:
ace (minOccurs="0" maxOccurs="*")

executeData Description:
Encapsulates the procedure's input data.
Children:
dacl (minOccurs="1" maxOccurs="1")
regKey (minOccurs="1" maxOccurs="1")
inheritance
Description:
Set of bit flags that determines whether other containers or objects can inherit the access control entry (ACE) from the primary object to which the DACL is attached. This value can be either a number or an AceFlags string. (See the AceFlags table following the sample code.)
The value for this element corresponds to the inheritance portion (low-order byte) of the AceFlags member of the ACE_HEADER structure. This parameter can be NO_INHERITANCE to indicate that the ACE is not inheritable, or it can be a combination of the values from the AceFlags table following the sample code. An ace parent can have multiple inheritance elements whose values are concatenated by a bitwise OR to build a single inheritance value.

The following example creates an ACE with an inheritance value of 3.
<ace>
  <inheritance>SUB_OBJECTS_ONLY_INHERIT</inheritance>
  <inheritance>2</inheritance>
</ace>
AceFlags values:

0x0 NO_INHERITANCE Default. This ACE will not be inherited by other objects.

0x1 SUB_OBJECTS_ONLY_INHERIT Non-container objects contained by the primary object inherit the ACE.

0x2 SUB_CONTAINERS_ONLY_INHERIT Other containers contained by the primary object inherit the ACE.

0x3 SUB_CONTAINERS_AND_OBJECTS_INHERIT Both containers and non-container objects contained by the primary object inherit the ACE.

0x4 INHERIT_NO_PROPAGATE The SUB_OBJECTS_ONLY_INHERIT and SUB_CONTAINERS_ONLY_INHERIT flags are not propagated to an inherited ACE.

0x8 INHERIT_ONLY The ACE does not apply to the primary object to which the DACL is attached, but objects contained by the primary object inherit the ACE.

Parent:
ace
inheritedObjectTypeName Description:
Identifies the type of objects that can inherit the ACE.
Parent:
ace
machine
Description:
Machine for the new key. The following sample code illustrates the use of machine.
<machine>
  <name>BOB1</name>
</machine> 
Parent:
regKey

Child:
name (minOccurs="1" maxOccurs="1")
mode Description:
Specifies a value from the ACCESS_MODE enumeration. For a DACL, mode indicates whether the DACL allows or denies the specified access rights.

1 GRANT_ACCESS The new ACE combines the specified rights with any existing allowed or denied rights of the trustee.

2 SET_ACCESS On input, this flag discards any matching access-control information for the trustee and adds the new ACE. See REVOKE_ACCESS for limitations on what is discarded.

3 DENY_ACCESS On input, this flag denies the specified rights in addition to any currently denied rights of the trustee. It also modifies or deletes any existing access-control information for the trustee that allows the specified rights.

4 REVOKE_ACCESS An input flag that removes matching access-control information for the trustee. When modifying an existing DACL, specify REVOKE_ACCESS to remove any existing ACEs for the specified trustee. However, note that the operating system typically converts generic permissions to specific ones. Use GetRegKeySecurity to generate a list of all specific permissions, then SetRegKeySecurity to revoke individual permissions.

Parent:
ace

name Description:
Name of the machine, root key, or subkey for the new key.
Parents:
machine, rootkey, subkey

objectTypeName Description:
String that identifies the type of object, property set, or property protected by the ACE. If this ACE is inherited, it identifies the type of object, property set, or property protected by the inherited ACE. The format varies depending on the value for trusteeForm.
Parent:
ace

permission Description:
Value containing standard, specific, and generic rights. These rights are used in ACEs and are the primary means of specifying the requested or granted access to an object. This value can be either a number or string from any of the following tables. Multiple permission elements can be concatenated by a bitwise OR to create a single value.

Standard and generic permissions (ACCESS_MASK):

DELETE 0x00010000L Delete access

READ_CONTROL 0x00020000L Read access to the owner, group, and DACL of the security descriptor

WRITE_DAC 0x00040000L Write access to the DACL

WRITE_OWNER 0x00080000L Write access to owner

SYNCHRONIZE 0x00100000L Microsoft® Windows NT® and Microsoft® Windows® 2000: Synchronize access

ACCESS_SYSTEM_SECURITY 0x01000000L Indicates access to a DACL. This type of access requires the calling process to SE_SECURITY_NAME (Manage auditing and security log) privilege. If this flag is set in the access mask of an audit access ACE (successful or unsuccessful access), the system access control list (SACL) access will be audited.

MAXIMUM_ALLOWED 0x02000000L Maximum allowed

GENERIC_READ 0x80000000L Generic read

GENERIC_WRITE 0x40000000L Generic write

GENERIC_EXECUTE 0x20000000L Generic execute

GENERIC_ALL 0x10000000L Generic all

Registry permissions:

KEY_QUERY_VALUE 0x0001 Permission to query subkey data.

KEY_SET_VALUE 0x0002 Permission to set subkey data.

KEY_CREATE_SUB_KEY 0x0004 Permission to create subkeys.

KEY_ENUMERATE_SUB_KEYS 0x0008 Permission to enumerate subkeys.

KEY_NOTIFY 0x0010 Permission for change notification.

KEY_CREATE_LINK 0x0020 Permission to create a symbolic link.

KEY_READ 0x20019 Combines the READ_CONTROL, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access rights.

KEY_WRITE 0x20006 Combines the READ_CONTROL, KEY_SET_VALUE, and KEY_CREATE_SUB_KEY access rights.

KEY_EXECUTE 0x20019 Permission for read access.

KEY_ALL_ACCESS 0xF003F Combines the KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access rights, plus all the standard access rights except SYNCHRONIZE.

Parent:
ace
regKey
Description:
Encapsulates information about the new registry key. The following sample code illustrates the use of regKey.
<regKey>
  <machine>
	<name>BOB1</name>
  </machine>
  <rootkey>
	<name>HKEY_LOCAL_MACHINE</name>
  </rootkey>
  <subkey>
	<name>SOFTWARE\Microsoft\Active Setup\TestCreateKey</name>
  </subkey>
</regKey>
Parent:
executeData

Children:
machine (minOccurs="1" maxOccurs="1")
rootkey (minOccurs="1" maxOccurs="1")
subkey (minOccurs="1" maxOccurs="1")
rootkey
Description:
Root key for the new key. The following sample code illustrates the use of rootkey.
<rootkey>
  <name>HKEY_LOCAL_MACHINE</name>
</rootkey>
Parent:
regKey

Child:
name (minOccurs="1" maxOccurs="1")
subkey
Description:
Subkey for the new key. The following sample code illustrates the use of subkey.
<subkey>
  <name>SOFTWARE\Microsoft\Active Setup</name>
</subkey> 
Parent:
regKey

Child:
name (minOccurs="1" maxOccurs="1")
trustee Description:
Identifies the user, group, or program (such as a Microsoft® Win32® service) to which the ACE applies. The format varies depending on the value for the trusteeForm node.
Parent:
ace

trusteeForm Description:
Type of value in the trustee node. Specifies a value from the following TRUSTEE_FORM enumeration. If an objectTypeName or inheritedObjectTypeName is supplied, it should be either TRUSTEE_IS_OBJECTS_AND_NAME or TRUSTEE_IS_OBJECTS_AND_SID.

0 TRUSTEE_IS_SID trustee is the security identifier (SID) of the trustee.

1 TRUSTEE_IS_NAME trustee is the name of the trustee.

3 TRUSTEE_IS_OBJECTS_AND_SID trustee is the SID of the trustee and either objectTypeName or inheritedObjectTypeName is supplied.

4 TRUSTEE_IS_OBJECTS_AND_NAME trustee is the name of the trustee and either objectTypeName or inheritedObjectTypeName is supplied.

Parent:
ace

trusteeType Description:
Indicates whether the trustee is a user account, a group account, or the account type is unknown. Specifies a value from the following TRUSTEE_TYPE enumeration. The default is TRUSTEE_IS_UNKNOWN.

0 TRUSTEE_IS_UNKNOWN Trustee type is unknown, but not necessarily invalid.

1 TRUSTEE_IS_USER Indicates a user.

2 TRUSTEE_IS_GROUP Indicates a group.

3 TRUSTEE_IS_DOMAIN Indicates a Microsoft® Active Directory® or Windows NT domain.

4 TRUSTEE_IS_ALIAS Indicates an alias.

5 TRUSTEE_IS_WELL_KNOWN_GROUP Indicates a well-known group.

6 TRUSTEE_IS_DELETED Indicates a deleted account.

7 TRUSTEE_IS_INVALID Indicates an invalid trustee type.

8 TRUSTEE_IS_COMPUTER Indicates a computer.

Parent:
ace
See Also

Registry Provider, CreateRegKey

Top of Page
© 1999-2002 Microsoft Corporation. All rights reserved.