2.2.4 GPO Search
The GPO Search message uses file access and LDAP as transports. The purpose of this message is to allow the Group Policy client to query the GPOs that are associated with SOMs.
An LDAP SearchRequest MUST be sent to the Group Policy server with the following parameters.
|
Parameter |
Value |
|---|---|
|
baseObject |
cn=policies,cn=system,< LDAP DN for the root of the domain> The <LDAP DN for the root of the domain> is an input parameter referenced from the Policy Target Domain DN ADM element. |
|
Scope |
Search entire subtree (this MUST be set to 2). |
|
derefAliases |
MUST be set to 0 (neverDerefAliases). |
|
sizeLimit |
SHOULD be set to 65536. |
|
timeLimit |
MAY<5> be 0 (infinite), but SHOULD be 240 (seconds). |
|
typesOnly |
MUST be set to 0 (FALSE). |
|
Filter |
The following LDAP filter (using the representation as specified in [RFC2254]) MUST be used: (|(distinguishedName=<GPOPath1>)(distinguishedName=<GPOPath2>)... (distinguishedName=<GPOPathN>)) where <GPOPath1> and <GPOPathN> are the GPO DNs (as specified in sections 2.2.2 and 2.2.3) without the prefix "LDAP://"; all other characters are to be interpreted literally. The following LDAP filter (using the representation as specified in [RFC2251]) makes the LDAP query more efficient by returning only GPOs that are enabled and contain extensions: GPO targeted to user policy: (&(!(flags:1.2.840.113556.1.4.803:=1))(gPCUserExtensionNames=[*])((|(distinguishedName=<GPOPath1>)(distinguishedName=<GPOPath2>)... (distinguishedName=<GPOPathN>))))where <GPOPath1> and <GPOPathN> are the GPO DNs (as specified in sections 2.2.2 and 2.2.3) without the prefix "LDAP://"; all other characters are to be interpreted literally. GPO targeted to a computer policy: (&(!(flags:1.2.840.113556.1.4.803:=2))(gPCMachineExtensionNames=[*])((|(distinguishedName=<GPOPath1>)(distinguishedName=<GPOPath2>)... (distinguishedName=<GPOPathN>))))where <GPOPath1> and <GPOPathN> are the GPO DNs (as specified in sections 2.2.2 and 2.2.3) without the prefix "LDAP://"; all other characters are to be interpreted literally. |
|
attributes |
nTSecurityDescriptor, cn, displayName, gPCFileSysPath, versionNumber, gPCMachineExtensionNames, gPCUserExtensionNames, gPCFunctionalityVersion, flags, gPCWQLFilter, and objectClass. |
The client receives a reply from the search request from the Group Policy server with one or more LDAP searchResponse messages. Those messages contain one or more searchResultEntries. Those searchResultEntries MUST contain an objectName DN attribute that is the GPO named by that DN. The searchResultEntry also MUST contain an attributes field with the values in Active Directory for the attributes of the GPOs that were searched for. The attributes MUST have the following format.
|
Attribute |
Format |
|---|---|
|
nTSecurityDescriptor |
A security descriptor whose format is specified in [MS-DTYP] section 2.4.6. |
|
cn |
The common name of the GPO; all GPO common names are curly braced GUID strings of the form {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. |
|
displayName |
A human-readable directory string description of the GPO. |
|
gPCFileSysPath |
A GPO path. |
|
versionNumber |
A GPO container version. It is a 32-bit integer which consists of 16 bits of user GPO version and 16 bits of machine GPO version. |
|
gPCMachineExtensionNames |
A directory string with the format: [<CSE GUID1><TOOL GUID1>][<CSE GUID2><TOOL GUID2>] sorted in case-insensitive ascending order by <CSE GUID> where <CSE GUIDn> is a CSE GUID and <TOOL GUIDn> is a tool extension GUID, and the "[" and "]" characters are to be interpreted literally. The CSE GUID and tool extension GUID are each a 38-character curly braced GUID string. Group Policy processing terminates at the first <CSE GUIDn> out of sequence. |
|
gPCUserExtensionNames |
This attribute has the same format as gPCMachineExtensionNames. |
|
gPCFunctionalityVersion |
A 32-bit integer, as described in section 1.7. This MUST be set to 2 for the GPO to be included in the protocol sequence; any other value means the GPO MUST be considered denied. |
|
flags |
A 32-bit integer that is interpreted as a flags bit field. Any bitwise combination of the following two flag values is valid. The client MUST ignore any other flags: If no bits are set (0x00000000): This GPO is enabled for both user and computer policy mode. If bit 0 is set (0x00000001): Ignore this GPO for user policy mode. If bit 1 is set (0x00000002): Ignore this GPO for computer policy mode. If both bits are set (0x00000003): This GPO is disabled for both user and computer policy mode. |
|
gPCWQLFilter |
A directory string of the format: "["<DOMAIN NAME>";"<WMI FILTER ID>";"<FLAGS>"]" where "[", ";", and "]" are to be included literally, and where <WMI FILTER ID> is the identifier of the WMI filter, <DOMAIN NAME> is the fully qualified domain name (FQDN) of the domain in which the WMI filter is defined, and <FLAGS> MUST be ignored by the client. |
|
objectClass |
Name of the Active Directory object class type. |
For each GPO successfully retrieved in each search, <gpo path>\gpt.ini is a file on the Group Policy server. The directory <gpo path> corresponds to the file system path retrieved for the GPO in the gPCFileSysPath attribute of the search.
The format of the file is as follows:
The gpt.ini file MUST be encoded in ANSI and is described with the following Augmented Backus-Naur Form (ABNF), as specified in [RFC4234].
-
IniFile = WhiteSpace Sections WhiteSpace Sections = Section / Sections Section WhiteSpaceClass = %x09 / " " WhiteSpace = *WhiteSpaceClass LineBreak = CR / LF / CRLF IniId = 1*ALPHAKey IniIdIniValue = 1*(ALPHA / "_" / DIGIT ) Id = 1*(ALPHA / "_" / DIGIT ) Section = SectionId Keys Keys = Key / Keys Key SectionId = "[" SectionName "]" WhiteSpace LineBreak SectionName = 1*SectionChar SectionChar = ALPHA / "_" / WSP Key = KeyId WhiteSpace "=" WhiteSpace IniValue WhiteSpace LineBreak
Abstractly, the file is described as having unique sections that correspond to the section tags in the previous code example. Each section MUST have a unique SectionId. The Key tags that are part of the definition of section define abstract "Keys" that MUST be unique within that abstract section only, defined by their associated KeyId tags. When testing uniqueness of the KeyId and SectionId tags, case MUST be ignored.
Using the sections, keys, and values terminology of this documentation, the specific format of gpt.ini can be specified as follows:
Sections: The file MUST have the required section, "General". If this section is not present, the file is considered corrupt, and the protocol exchange MUST be terminated.
Keys: The required key, "Version", MUST exist under the "General" section.
Value: The value of the key, "Version", MUST be a 32-bit integer that corresponds to a GPO version. This is where the GPO file system version is defined. It is a 32-bit integer which consists of 16 bits of user GPO version and 16 bits of machine GPO version.