Registry Provider::GetRegKeySecurity

Obtains the discretionary access control list (DACL) security settings for a registry key. Used by Microsoft® Provisioning Framework (MPF).

GetRegKeySecurity is a namespace-only procedure that executes Active Directory Provider::Get DACL.

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>
</executeData>

XML Output Schema

The following code fragment shows the format for data this procedure returns. For more information on individual elements and attributes, see the Elements and Attributes table.

<executeData>1..1
  <regKeyResp>1..1
	<dacl>0..1
	<ace>0..unbounded
		<permission>1..1</permission>
		<mode>1..1</mode>
		<trusteeForm>1..1</trusteeForm>
		<trustee>1..1</trustee>
		<trusteeType>1..1</trusteeType>
		<inheritance>1..1</inheritance>
		<objectTypeName>0..1</objectTypeName>
		<inheritedObjectTypeName>0..1</inheritedObjectTypeName>
	</ace>
	</dacl>
  </regKeyResp>
</executeData>

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="1" maxOccurs="1")
inheritedObjectTypeName (minOccurs="0" maxOccurs="1")
mode (minOccurs="1" maxOccurs="1")
objectTypeName (minOccurs="0" maxOccurs="1")
permission (minOccurs="1" maxOccurs="1")
trustee (minOccurs="1" maxOccurs="1")
trusteeForm (minOccurs="1" maxOccurs="1")
trusteeType (minOccurs="1" maxOccurs="1")
dacl Description:
DACL for the specified object; consists of ACEs. The returned list contains both inherited and non-inherited ACEs. Returned values are decimals rather than enumeration strings.

Parent:
 executeData

Child:
ace (minOccurs="0" maxOccurs="*")
executeData Description:
 Encapsulates the procedure's input and output data.

Children:
 regKey (minOccurs="1" maxOccurs="1", input only)
regKeyResp  (minOccurs="1" maxOccurs="1", output only)
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. The value of this member corresponds to the inheritance portion (low-order byte) of the AceFlags member of the ACE_HEADER structure. This parameter can be zero to indicate that the ACE is not inheritable, or it can be a combination of the values in the AceFlags table. For example: 
<ace>
  <inheritance>3</inheritance>
</ace>

AceFlags:

0x0 Default. This ACE will not be inherited by other objects.
0x1 Non-container objects contained by the primary object inherit the ACE.
0x2 Other containers contained by the primary object inherit the ACE.
0x3 Both containers and non-container objects contained by the primary object inherit the ACE.
0x4 The SUB_OBJECTS_ONLY_INHERIT and SUB_CONTAINERS_ONLY_INHERIT flags are not propagated to an inherited ACE.
0x8 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.
0x10 The permission or restriction is inherited from the parent object.

Parent:
 ace
inheritedObjectTypeName Description:
Identifies the type of objects that can inherit the ACE.

Parent:
 ace
machine Description:
 Machine for the key to retrieve the DACL for. The following sample code illustrates the use of machine. 
<machine>
  <name>BOB1</name>
</machine>

Parent:
regKey

Child:
 name (minOccurs="1" maxOccurs="1")
mode Description:
Indicates whether the DACL allows or denies the specified access rights. Specifies a value from the following ACCESS_MODE enumeration.
2 Indicates an ACCESS_ALLOWED_ACE that allows the specified rights.
3 Indicates an ACCESS_DENIED_ACE that denies the specified rights.

Parent:
 ace
name Description:
 Name of the machine, root key, or subkey to retrieve the DACL for.

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. The permission value can be any combination of bits from the following tables.

Standard and generic permissions (ACCESS_MASK):

0x00010000L Delete access
0x00020000L Read access to the owner, group, and DACL of the security descriptor
0x00040000L Write access to the DACL
0x00080000L Write access to owner
0x00100000L Microsoft® Windows NT® and Windows® 2000: Synchronize access
0x01000000L Access system security (ACCESS_SYSTEM_SECURITY). This flag is not a typical access type. It is used to indicate access to a system access control list (SACL). 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 SACL access will be audited.
0x02000000L Maximum allowed
0x10000000L Generic all
0x20000000L Generic execute
0x40000000L Generic write
0x80000000L Generic read


Registry permissions:

0x0001 Permission to query subkey data.
0x0002 Permission to set subkey data.
0x0004 Permission to create subkeys.
0x0008 Permission to enumerate subkeys.
0x0010 Permission for change notification.
0x0020 Permission to create a symbolic link.

Parent:
 ace
regKey Description:
 Encapsulates information about the key to retrieve the DACL for. 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")
regKeyResp Description:
 Returns the DACL for the registry key specified by the machine, root key, and subkey.

Parent:
executeData

Child:
dacl (minOccurs="0" maxOccurs="1")
rootkey Description:
 Root key for the key to return the DACL for. 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 to return the DACL for. 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.
0 trustee is the SID of the trustee.
1 trustee is the name of the trustee.
3 trustee is the SID of the trustee. Returns objectTypeName and/or inheritedObjectTypeName.
4 trustee is the name of the trustee. Returns objectTypeName and/or inheritedObjectTypeName.

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.
0 Trustee type is unknown, but not necessarily invalid.
1 Indicates a user.
2 Indicates a group.
3 Indicates a Microsoft® Active Directory® or Windows NT domain.
4 Indicates an alias.
5 Indicates a well-known group.
6 Indicates a deleted account.
7 Indicates an invalid trustee type.
8 Indicates a computer.

Parent:
 ace

See Also

Registry Provider, SetRegKeySecurity

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