![[MS-GPSI]: Group Policy: Software Installation Protocol Extension](https://img.yumpu.com/50703911/1/500x640/ms-gpsi-group-policy-software-installation-protocol-extension.jpg)
[MS-GPSI]: Group Policy: Software Installation Protocol Extension
[MS-GPSI]: Group Policy: Software Installation Protocol Extension
[MS-GPSI]: Group Policy: Software Installation Protocol Extension
Create successful ePaper yourself
Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.
[<strong>MS</strong>-<strong>GPSI</strong>]:<strong>Group</strong> <strong>Policy</strong>:<strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Intellectual Property Rights Notice for <strong>Protocol</strong> Documentation• This protocol documentation is covered by Microsoft copyrights. Regardless of any other termsthat are contained in the terms of use for the Microsoft website that hosts this documentation,you may make copies of it in order to develop implementations of the protocols, and maydistribute portions of it in your implementations of the protocols or your documentation asnecessary to properly document the implementation. This permission also applies to anydocuments that are referenced in the protocol documentation.• Microsoft does not claim any trade secret rights in this documentation.• Microsoft has patents that may cover your implementations of the protocols. Neither this noticenor Microsoft's delivery of the documentation grants any licenses under those or any otherMicrosoft patents. If you are interested in obtaining a patent license, please contactprotocol@microsoft.com.• The names of companies and products contained in this documentation may be covered bytrademarks or similar intellectual property rights. This notice does not grant any licenses underthose rights.• All other rights are reserved, and this notice does not grant any rights other than specificallydescribed above, whether by implication, estoppel, or otherwise.This protocol documentation is intended for use in conjunction with publicly available standardspecifications, network programming art, and Microsoft Windows distributed systems concepts, andassumes that the reader either is familiar with the aforementioned material or has immediate accessto it.A protocol specification does not require the use of Microsoft programming tools or programmingenvironments in order for you to develop an implementation. If you have access to Microsoftprogramming tools and environments you are free to take advantage of them.Revision SummaryDate Revision History Revision Class Comments03/14/2007 1.0 Major Updated and revised the technical content.04/10/2007 1.1 Minor Updated the technical content.05/18/2007 2.0 Major New format06/08/2007 2.0.1 Editorial Revised and edited the technical content.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 20081 / 48
Date Revision History Revision Class Comments07/10/2007 3.0 Major Updated and revised the technical content.08/17/2007 4.0 Major Updated and revised the technical content.09/21/2007 5.0 Major Updated and revised the technical content.10/26/2007 5.0.1 Editorial Revised and edited the technical content.01/25/2008 5.0.2 Editorial Revised and edited the technical content.2 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
Table of Contents1 Introduction .............................................................................................................. 51.1 Glossary ................................................................................................................ 51.2 References ............................................................................................................. 61.2.1 Normative References ........................................................................................ 61.2.2 Informative References ...................................................................................... 61.3 <strong>Protocol</strong> Overview (Synopsis) ................................................................................... 71.3.1 Background ...................................................................................................... 71.3.2 <strong>Software</strong> <strong>Installation</strong> <strong>Extension</strong> Overview ............................................................. 71.4 Relationship to Other <strong>Protocol</strong>s ................................................................................. 81.5 Prerequisites/Preconditions ...................................................................................... 81.6 Applicability Statement ............................................................................................ 81.7 Versioning and Capability Negotiation ........................................................................ 81.8 Vendor-Extensible Fields .......................................................................................... 81.9 Standards Assignments ............................................................................................ 92 Messages ................................................................................................................... 102.1 Transport ............................................................................................................... 102.2 Message Syntax ...................................................................................................... 102.2.1 <strong>Policy</strong> Application Messages ................................................................................ 112.2.1.1 <strong>Software</strong> <strong>Installation</strong> Container Search Request ............................................... 112.2.1.2 <strong>Software</strong> <strong>Installation</strong> Container Search Reply .................................................. 122.2.1.3 <strong>Software</strong> <strong>Installation</strong> Search Request ............................................................. 122.2.1.4 <strong>Software</strong> <strong>Installation</strong> Search Reply ................................................................. 132.2.1.5 <strong>Software</strong> <strong>Installation</strong> Maintenance Message ..................................................... 172.2.2 <strong>Software</strong> <strong>Installation</strong> Read Administration Message ................................................ 182.2.3 <strong>Software</strong> <strong>Installation</strong> Write Administration ............................................................ 182.2.3.1 Class Store Creation Message ........................................................................ 182.2.3.2 Packages Container Creation Message ............................................................ 182.2.3.3 Package Creation Message ............................................................................ 192.2.3.4 Class Store Confirmation Message .................................................................. 202.2.3.5 Package Update Message .............................................................................. 202.2.3.6 Package Deletion Message ............................................................................ 212.2.4 Application Advertise Script ................................................................................ 212.2.4.1 Application Advertise Script Record Structure .................................................. 222.2.4.2 Opcode List ................................................................................................. 232.2.4.2.1 Header (Opcode 2) ................................................................................. 232.2.4.2.2 ProductInfo (Opcode 4) ........................................................................... 242.2.4.2.3 SourceListPublish (Opcode 9) ................................................................... 262.2.4.2.4 ProductPublish (Opcode 16) ..................................................................... 272.2.4.2.5 End (Opcode 3) ...................................................................................... 273 <strong>Protocol</strong> Details ......................................................................................................... 283.1 Client Plug-in Details ............................................................................................... 283.1.1 Abstract Data Model ........................................................................................... 283.1.2 Timers ............................................................................................................. 303.1.3 Initialization ...................................................................................................... 303.1.4 Higher-Layer Triggered Events ............................................................................ 303.1.5 Message Processing Events and Sequencing Rules ................................................. 303.1.5.1 <strong>Software</strong> Deployment Retrieval ...................................................................... 303.1.5.2 <strong>Software</strong> Deployment Applicability ................................................................. 313.1.5.3 <strong>Software</strong> Action Determination ...................................................................... 323.1.5.4 <strong>Software</strong> Configuration ................................................................................. 32[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 20083 / 48
3.1.5.5 <strong>Software</strong> <strong>Installation</strong> Maintenance .................................................................. 333.1.6 Timer Events..................................................................................................... 343.1.7 Other Local Events ............................................................................................. 343.2 Administrative Plug-in Details ................................................................................... 343.2.1 Abstract Data Model ........................................................................................... 343.2.2 Timers ............................................................................................................. 363.2.3 Initialization ...................................................................................................... 363.2.4 Higher-Layer Triggered Events ............................................................................ 363.2.5 Message Processing Events and Sequencing Rules ................................................. 363.2.5.1 <strong>Policy</strong> Read Administration ............................................................................ 363.2.5.2 <strong>Policy</strong> Write Administration ............................................................................ 373.2.5.3 Package Creation ......................................................................................... 373.2.5.4 Package Modification .................................................................................... 383.2.5.4.1 Package Patching ................................................................................... 393.2.5.5 Package Removal ......................................................................................... 393.2.5.6 Package Obsolescence .................................................................................. 393.2.5.7 Package Deletion ......................................................................................... 403.2.6 Timer Events..................................................................................................... 403.2.7 Other Local Events ............................................................................................. 404 <strong>Protocol</strong> Example ....................................................................................................... 414.1 <strong>Software</strong> <strong>Installation</strong> Search Result <strong>Protocol</strong> Example .................................................. 414.2 Sample Application Advertise Script File ..................................................................... 425 Security ..................................................................................................................... 445.1 Security Considerations for Implementers .................................................................. 445.2 Index of Security Parameters ................................................................................... 446 Appendix A: Windows Behavior ................................................................................. 457 Index ......................................................................................................................... 47[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 20084 / 48
1 IntroductionThis document specifies the <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> to the <strong>Group</strong><strong>Policy</strong> <strong>Protocol</strong>, as specified in [<strong>MS</strong>-GPOL]. The transmitted configuration data enables centralized(common) configuration of multiple client systems. The software installation extension enables anadministrator to install and remove software applications at client computers. New software versionscan also be pushed out to client computers.1.1 GlossaryThe following terms are defined in [<strong>MS</strong>-GLOS]:Active Directory (AD)AdvertisedApplication Advertise ScriptAssigned ApplicationClass Store Container DNCOM ClassComputer <strong>Policy</strong> ModeCurly Braced GUID StringDirectoryDistinguished Name (DN)DomainGlobally Unique Identifier (GUID)<strong>Group</strong> <strong>Policy</strong> Object (GPO)<strong>Group</strong> <strong>Policy</strong> ServerPackageRegistration Object<strong>Policy</strong> Application<strong>Policy</strong> TargetPrimary Language IdentifierPublished ApplicationRedeploy Action<strong>Software</strong> <strong>Installation</strong> Package<strong>Software</strong> <strong>Installation</strong> Package Modification<strong>Software</strong> Maintenance Utility<strong>Software</strong> Package DN<strong>Software</strong> Scripts PathUncPathUnicode StringUpdate Sequence Number (USN)UpgradeUser <strong>Policy</strong> ModeThe following terms are specific to this document:Client: In this document, client refers to a domain member that is involved in a policyapplication mode sequence.Product Identifier GUID: A globally unique identifier (GUID) assigned to a softwareapplication by the vendor of the software. Each application has a unique GUID. A patchedversion of the application maintains the same GUID as the unpatched version of theapplication. This GUID is referenced by the software installation package to identify theapplication that is installed by the software installation package.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 20085 / 48
User Assistance Resource: A UnicodeString containing a URL pointing to information thatmight be helpful to users of the application when viewing information on the applicationthrough a software maintenance utility. This is defined by the administrator who deploysthe application. The UnicodeString's Unicode BOM encoding is little-endian only; and bigendianUnicode BOM encoding is not supported.MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used asspecified in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, orSHOULD NOT.1.2 References1.2.1 Normative ReferencesWe conduct frequent surveys of the normative references to assure their continued availability. Ifyou have any issue with finding a normative reference, please contact dochelp@microsoft.com. Wewill assist you in finding the relevant information. Please check the archive site,http://msdn2.microsoft.com/en-us/library/E4BD6494-06AD-4aed-9823-445E921C9624, as anadditional source.[C706] The Open <strong>Group</strong>, "DCE 1.1: Remote Procedure Call", C706, August 1997,http://www.opengroup.org/public/pubs/catalog/c706.htm[LDAP] Microsoft Corporation, "About Lightweight Directory Access <strong>Protocol</strong>",http://msdn2.microsoft.com/en-us/library/aa366075.aspxIf you have any trouble finding [LDAP], please check here.[<strong>MS</strong>-ADA1] Microsoft Corporation, "Active Directory Schema Attributes A-L", July 2006.[<strong>MS</strong>-ADSC] Microsoft Corporation, "Active Directory Schema Classes", July 2006.[<strong>MS</strong>-DTYP] Microsoft Corporation, "Windows Data Types", March 2007.[<strong>MS</strong>-GLOS] Microsoft Corporation, "Windows <strong>Protocol</strong>s Master Glossary", March 2007.[<strong>MS</strong>-GPOL] Microsoft Corporation, "<strong>Group</strong> <strong>Policy</strong>: Core <strong>Protocol</strong> Specification", July 2006.[<strong>MS</strong>-SMB] Microsoft Corporation, "Server Message Block (SMB) <strong>Protocol</strong> Specification", July 2006.[<strong>MS</strong>-SPNG] Microsoft Corporation, "Simple and Protected Generic Security Service ApplicationProgram Interface Negotiation Mechanism (SPNEGO) <strong>Protocol</strong> <strong>Extension</strong>s", July 2006.[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC2119, March 1997, http://www.ietf.org/rfc/rfc2119.txt[RFC2251] Wahl, M., Howes, T., and Kille, S., "Lightweight Directory Access <strong>Protocol</strong> (v3)", RFC2251, December 1997, http://www.ietf.org/rfc/rfc2251.txt[RFC2254] Howes, T., "The String Representation of LDAP Search Filters", RFC 2254, December1997, http://www.ietf.org/rfc/rfc2254.txt1.2.2 Informative References[<strong>MS</strong>DN-LI] Microsoft Corporation, "Locale Identifiers", http://msdn2.microsoft.com/enus/library/ms776323.aspx[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 20086 / 48
1.3 <strong>Protocol</strong> Overview (Synopsis)The <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> to the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong>, as specifiedin [<strong>MS</strong>-GPOL], allows administrators to instruct arbitrarily large groups of clients to install andremove administrator-specified software at computer startup, user logon, or when explicitlyinstructed by an interactively logged-on user.1.3.1 BackgroundThe <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong>, as specified in [<strong>MS</strong>-GPOL], allows clients to discover and retrieve policysettings created by administrators of a domain. These settings are persisted within <strong>Group</strong> <strong>Policy</strong>objects (GPO) that are assigned to policy target accounts in the Active Directory. <strong>Policy</strong> targetaccounts are either computer accounts or user accounts in the Active Directory. Each client usesLDAP to determine what GPOs are applicable to it by consulting the Active Directory objectscorresponding to its computer account and the user accounts of any users logging on to the clientcomputer.On each client, each GPO is interpreted and acted on by software components known as client plugins.The client plug-ins that are responsible for a given GPO are specified using an attribute of theGPO. This attribute specifies a list of globally unique identifier (GUID) pairs. The first GUID ofeach pair is referred to as a client-side extension (CSE) GUID. The second GUID of each pair isreferred to as a tool extension GUID.For each GPO that is applicable to a client, the client consults the CSE GUIDs listed in the GPO todetermine what client plug-ins on the client should handle the GPO. The client then invokes theclient plug-ins to handle the GPO.A client plug-in uses the content of the GPO to retrieve settings specific to its class in a mannerspecific to its class. After its class-specific settings are retrieved, the client plug-in uses thosesettings to perform class-specific processing.1.3.2 <strong>Software</strong> <strong>Installation</strong> <strong>Extension</strong> OverviewThis extension specifies the behavior of two components: an administrative plug-in that extends anadministrative tool, as specified in [<strong>MS</strong>-GPOL], and a client plug-in that extends a <strong>Group</strong> <strong>Policy</strong><strong>Protocol</strong> client on client machines.The software installation administrative plug-in allows administrators to specify applications to beinstalled on client computers. The administrator can control how the software is installed. Forexample, the software can be configured to install with a minimal user interface. These options canbe changed by the administrator after they are initially specified. The administrative plug-in storesthe specified settings on a server using LDAP (as specified in [RFC2251]) and SMB (as specified in[<strong>MS</strong>-SMB]), and metadata from which the path to those settings can be constructed and saved in aGPO.The software installation client plug-in consults the GPO to reconstruct the path to the actualsettings, and retrieves them so the client can enforce the intention behind them (that is, install thissoftware, remove this software, or patch this software).<strong>Software</strong> installation settings carried by this extension can cause the Client to do the following:1. Install a given application at computer startup.2. Install a given application when certain users log on.3. Remove an application that was previously installed due to this protocol.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 20087 / 48
4. Patch a currently installed application.5. Allow users logged on to clients to use a software maintenance utility to view applicationsdeployed to the network, and optionally install or remove them.1.4 Relationship to Other <strong>Protocol</strong>sThis protocol is invoked as an extension of the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong>, as specified in [<strong>MS</strong>-GPOL]. It isonly initiated as part of the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong>, as specified in [<strong>MS</strong>-GPOL], and the invocation ofthis (and all <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong> extensions) is as specified in [<strong>MS</strong>-GPOL]. It explicitly depends onall of the protocols on which the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong> depends.The <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong> invokes plug-ins for extensions such as this one, as specified in [<strong>MS</strong>-GPOL] section 3.1.5.7. In summary, this extension's CSE GUID and tool extension GUIDs (asspecified in section 1.9) are stored within a GPO by the policy administration portion of the <strong>Group</strong><strong>Policy</strong> <strong>Protocol</strong> whenever the <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> causes a GPO tocontain policy settings for the software installation extension. During policy application by aClient, the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong> retrieves the CSE GUID from the GPO, signaling to the Client that itshould invoke the <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> plug-in to retrieve <strong>Group</strong><strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> settings from the GPO. Similarly, the tool extensionGUIDs are used by policy administration tools to invoke the policy administration portion of the<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> plug-ins to update the <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong><strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> stored within a GPO.1.5 Prerequisites/PreconditionsThe prerequisites for this protocol are the same as those for the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong>, as specifiedin [<strong>MS</strong>-GPOL]. Additionally, this protocol MUST only be initiated as part of the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong>as an extension of that protocol, as specified in [<strong>MS</strong>-GPOL].It is assumed that a client computer has an OS component capable of performing softwareinstallation and removal based on the abstract state specified in section 3.1.1.6 Applicability Statement<strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong> extensions are only applicable within the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong> framework. The<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> is applicable to the installation, update, andremoval of application software on client computers.This extension is only appropriate for use when the same settings are relevant to all clients.1.7 Versioning and Capability NegotiationThere is no mechanism in the <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> for versioningor capability negotiation.1.8 Vendor-Extensible FieldsThe <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> defines several vendor-extensible fieldsthat are of type GUID. Vendors can acquire GUID values using the GUID generation method, asspecified in [C706].[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 20088 / 48
2 MessagesThe following sections specify how <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> messagesare transported and <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> message syntax.2.1 TransportThe <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> requires the SMB and LDAP transports asspecified for use by <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong> extensions specified in [<strong>MS</strong>-GPOL]. All messages MUST beexchanged over the LDAP and SMB protocols between the client and server, as specified in section2.2.2.2 Message SyntaxThere are two classes of protocol conversations. Each message can be categorized into one of thesetwo classes:• <strong>Policy</strong> application messages: Messages exchanged during policy application. These are triggeredby the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong>, as specified in [<strong>MS</strong>-GPOL], and processed by the <strong>Group</strong> <strong>Policy</strong>:<strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> client plug-in.• Administrative messages: Messages that allow an administrator to view and update <strong>Group</strong> <strong>Policy</strong>:<strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> settings in a domain. They are only used by the <strong>Group</strong><strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> administrative plug-in, never the client plug-in.Both message types retrieve settings for applications through LDAP from Active Directory. Thelayout of these Active Directory objects provides context for understanding the objects andattributes that are retrieved through the messages:[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200810 / 48
Figure 1: Active Directory GPO structure for software installation2.2.1 <strong>Policy</strong> Application MessagesThe following messages are generated by the client and the <strong>Group</strong> <strong>Policy</strong> server during policyapplication.2.2.1.1 <strong>Software</strong> <strong>Installation</strong> Container Search RequestThis message requests the <strong>Group</strong> <strong>Policy</strong> server to search for the software package container for aGPO. This is an LDAP searchRequest message, as specified in [RFC2251], and MUST have thefollowing values.ParameterbaseObjectScopederefAliasessizeLimitValueThis is a class store DN for the object of Active Directory class "classStore" in the ActiveDirectory. This object referenced by this class store DN is contained in an object of classgroup<strong>Policy</strong>Container (as specified in [<strong>MS</strong>-ADSC] section 56). This MUST be a DN of theform CN=Class Store, where is a scoped GPO DN.MUST be the value 0 for the baseObject scope, as specified in [RFC2251].MUST be set to 0 (neverDerefAliases) to dereference in searching.MUST be set to z0 (no limit set).11 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
ParametertimeLimittypesOnlyFilterattributesValueMAY be set to 0 (infinite).MUST be set to FALSE, according to the LDAP protocol definition of FALSE.The following LDAP filter (as specified in [RFC2254]) MUST be used:objectClass=*This field MUST specify the attribute appSchemaVersion.2.2.1.2 <strong>Software</strong> <strong>Installation</strong> Container Search ReplyThis message is an LDAP searchResponse message received by the client from the <strong>Group</strong> <strong>Policy</strong>server in response to a software installation container search request message. A successful replyfrom the search request contains one or more LDAP search response messages. These messagescontain one or more searchResultEntries. The searchResultEntries MUST contain attributes with thefollowing format:AttributeFormatappSchemaVersion This attribute is of type integer (as specified in [<strong>MS</strong>-ADA1] section 64).The message MUST be considered invalid if the appSchemaVersion attribute does not have thevalue 0x000006CC. Further messages MUST NOT be generated by the Client for this cycle of policyapplication.2.2.1.3 <strong>Software</strong> <strong>Installation</strong> Search RequestThis message requests the <strong>Group</strong> <strong>Policy</strong> server to return search results for software installationextension settings in a given GPO. This is an LDAP searchRequest message, as specified in[RFC2251], and MUST have the following values.ParameterbaseObjectScopederefAliasessizeLimittimeLimittypesOnlyFilterValueMUST be a DN of the form CN=Packages,CN=Class Store, where is a scoped GPO DN.MUST be set to 1 (singleLevel).MUST be set to 0 (neverDerefAliases) to dereference in searching.MUST be set to 0 (no limit set).MAY be set to 0 (infinite).MUST be set to FALSE, according to the LDAP protocol definition of FALSE.The following LDAP filter (as specified in [RFC2254]) MUST be used to search the Packagescontainer of the GPO (the representation given here is what is specified in [RFC2254]). Thisrepresentation can be mapped to the LDAP protocol representation:(&(|(msiScriptName="A")(&(msiScriptName="P")(canUpgradeScript=*)))(!(msiScriptName=*)))12 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
ParameterattributesValueThe following attributes MUST be retrieved: nTSecurityDescriptor, canUpgradeScript,packageFlags, packageType, msiScriptPath, lastUpdateSequence, localeID,machineArchitecture, packageName, versionNumberHi, versionNumberLo, installUiLevel,vendor, url, revision, productCode, objectGUID, categories, and msiFileList.2.2.1.4 <strong>Software</strong> <strong>Installation</strong> Search ReplyThis message is an LDAP searchResponse message, as specified in [RFC2251]. The message isreceived by the client from the <strong>Group</strong> <strong>Policy</strong> server in response to a software installation searchrequest message. A successful reply from the search request SHOULD contain one or more LDAPsearch response messages. These messages MUST contain one or more searchResultEntries thatrepresent the software installation extension settings stored in the GPO. The searchResultEntriesMUST contain attributes with the following formats:AttributenTSecurityDescriptorcanUpgradeScriptFormatA security descriptor, as specified in [<strong>MS</strong>-DTYP] section 2.4.6. It SHOULD be usedby the client only for logging purposes to log the security permissions that areassociated with the PackageRegistration object that represents an application.A multivalued attribute, as specified in [<strong>MS</strong>-ADSC], where each value MUST be aUnicode string representing software modeled by another PackageRegistrationobject that is to be upgraded. Each value MUST have the following format:\\:… where … is a software package. This MUST be a DN of the formCN=,CN=Packages,CN=Class Store, where is a scoped GPO DN and is a curlybraced GUID string. MUST be the string form of the objectId GUID attribute of thePackageRegistration object referenced by .If is a two-character string with the value 01, it indicates that theapplication referenced by MUST be removed prior to installing thisapplication. If it is 00, application removal is not required. The value MUST be oneof these values; if it is any other value, the behavior is undefined.It is valid for the attribute to be empty; in which case, the attribute MUST beignored by the client.If this attribute does not conform to the format specified above, the client MUSTbehave as if the value is empty.Attribute(continued)packageFlagsFormatA 32-bit integer that MUST be interpreted as a flags field in which all combinationsof flags are valid, unless otherwise noted. The value of the flags of this integerMUST be as follows.Value0x00000004MeaningApplications already installed on thismachine with the same product identifier13 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
Attribute(continued)FormatACTFLG_UninstallUnmanaged0x00000008ACTFLG_Published0x000000100x00000020ACTFLG_UserInstall0x00000040ACTFLG_OnDemandInstall0x00000080ACTFLG_Orphan0x00000100ACTFLG_Uninstall0x00000400ACTFLG_Assigned0x00000800ACTFLG_OrphanOn<strong>Policy</strong>Removal0x00001000ACTFLG_UninstallOn<strong>Policy</strong>Removalas that specified in this package'sproductCode field MUST be removedbefore this application can be installed.This flag is now obsolete. It SHOULD beignored and be treated as if it was alwaysset (implicit unmanaged applicationremoval).This is a published application. Thisvalue MUST NOT be set if theACTFLG_Assigned flag is set.This flag MUST be set. If it isn't, thisobject MUST be ignored.If a user has invoked the protocol from auser interface with the purpose ofallowing the user to browse deployedapplications, this flag MUST be set.The application is available to be installedwithout user interaction. This MUST beinitiated when an application running onthe system requests the presence ofsoftware that can provide theimplementation of a COM class or opena file with a specific file name extension.If set, this indicates that theadministrator has stopped deploying theapplication and that clients that havealready installed this application MUSTNOT perform application removals,upgrades, or reinstallations of thisinstance of the application through the<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong><strong>Protocol</strong> <strong>Extension</strong>.The client SHOULD remove thisapplication.This application is an assignedapplication. This value MUST NOT beset if the ACTFLG_Published flag is set.In the future, if the policy applicationmode sequence no longer contains theGPO from which this PackageRegistrationobject originated and was detectedduring a previous policy application, thisapplication MUST be treated as if theACTFLG_Orphan flag is set.This is similar toACTFLG_OrphanOnGPORemoval, exceptthat an application removal MUST occur14 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
Attribute(continued)Formatin addition to the behavior specified inACTFLG_OrphanOnGPORemoval.0x00002000ACTFLG_InstallUserAssign0x00004000ACTFLG_Force Upgrade0x00008000ACTFLG_Minimal InstallUI0x00010000ACTFLG_ExcludeX86OnWin640x00020000ACTFLG_Ignore Language0x00040000ACTFLG_Has Upgrades0x00080000ACTFLG_FullInstallUIFor assigned applications, the applicationSHOULD be fully installed by the clientand not advertised.If this application is configured as anupgrade for an application on the client,this application MUST be installed.This flag indicates if installation activity isto provide a user experience that allowscustomization of software duringinstallation. If the flag is enabled, such auser experience SHOULD NOT beprovided. Otherwise, it SHOULD beprovided.This software only executes on Intel x86platforms, and MUST be ignored by anyother platform.This software installation package issuitable for any language, and the clientMUST ignore language when consideringthe applicability of this software.This package has upgrades for otherdeployed applications.This flag is applicable when theapplication was retrieved as part of aquery for a software installationmaintenance application. When this flagis specified, the client MUST display theinstallation package's complete userinterface if the user initiates aninstallation of the package. If the flag isnot specified, a simpler interface withfewer options MAY be presented by thesoftware installation maintenanceapplication at the time of installation.packageTypeAn integer that MUST be one of the following values:Value5MANAGED_APPTYPE_WINDOWSINSTALLER1MANAGED_APPMeaningThis application MUST be installed through asoftware installation package.This application MUST be installed by creating aprocess from the executable program at the file15 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
Attribute(continued)FormatTYPE_SETUPEXEpath specified in the setupCommand attribute ofthis object.msiScriptPathlastUpdateSequencelocaleIDmachineArchitectureMUST be UncPath for a file under the software scripts path directory to anapplication advertise script (.aas) file.MUST be an update sequence number (USN) generated whenever the object isupdated by the server. It MUST be ignored by the client except for loggingpurposes.MUST be Windows locale identifier (for more information, see [<strong>MS</strong>DN-LI]) thatrepresents the language of the software.This integer identifies the hardware architecture requirement for a computer to runthe software. This integer MUST be one of the following values:ValueMeaning0 Indicates the software is for Intel x86 architecture.6 Indicates the software is for Intel IA64 architecture.9 Indicates the software is for x64 architecture.packageNameversionNumberHiversionNumberLoVendorurlRevisionproductCodeobjectGUIDMUST be a friendly human-readable Unicode string value authored on the server byan administrator to identify the application being represented in this object. TheUnicode string's UNICODE BOM encoding MUST be little-endian only. Big-endianUNICODE BOM encoding is not supported.An integer that serves as the major version number of the software. It MUST beused only for logging purposes.An integer that serves as the minor version number of the software. It MUST beused only for logging purposes.MUST be a Unicode String human-readable description for the name of the vendorof the software represented by this object. This field MUST not be validated and isonly to be used for logging. The Unicode String's UNICODE BOM encoding MUST belittle-endian only. Big-endian UNICODE BOM encoding is not supported.MUST be a Unicode string representation of a Uniform Resource Locator (URL) for auser assistance resource (determined by an administrator) that can bepresented to users of the client when browsing for software applications tomanage. The Unicode string's UNICODE BOM encoding MUST be little-endian only.Big-endian UNICODE BOM encoding is not supported.An integer that MUST be incremented every time a redeploy action is initiated forthis application by an administrator of the server.A product identifier that MUST uniquely identify the software to be installed. Thisallows the client to determine if this software is already installed on the client.A GUID that MUST uniquely identify this deployment of the application and doesnot change after the object is initially created.16 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
Attribute(continued)CategoriesmsiFileListFormatMUST be a set of GUIDs represented by a multivalued Unicode string attribute, asspecified in [<strong>MS</strong>-ADSC], that represents application categories to which thesoftware has been determined to belong to by an administrator. It MUST be usedby the client to enable browsing of software by category. The Unicode string'sUNICODE BOM encoding MUST be little-endian only. Big-endian UNICODE BOMencoding is not supported.A multivalued attribute of type Unicode string that MUST represent an ordered listof network file system paths to Windows Installer files supplied by applicationvendors and administrators who customize the application. The Unicode string'sUNICODE BOM encoding MUST be little-endian only. Big-endian UNICODE BOMencoding is not supported. Each string MUST have the following format::Where is a zero-based index that indicates the order in which theclient and administrative tools are to evaluate the Windows Installer network file relative to other such files referenced in this multivalued attribute(when installing the application or modifying its deployment properties). Thefollowing constraints MUST be enforced:• MUST be unique in this multivalued attribute.• MUST NOT be greater than or equal to the number ofvalues in this attribute.• MUST be the UncPath of a valid software installationpackage or software installation package modification file.• If the packageType attribute is set to 5(MANAGED_APPTYPE_WINDOWSINSTALLER), there MUST be a valuewith 0. Otherwise, this object is considered invalid. Ifthis value is invalid, it SHOULD be ignored, as specified in section3.1.5.4.• Value with 0 MUST reference a Windows Installerpackage (.msi) file.• Values with other than 0 MUST NOT reference aWindows Installer package (.msi) file.• If the packageType attribute is set to 1(MANAGED_APPTYPE_SETUPEXE), this attribute MUST be empty.installUiLevelThis attribute's integer value is undefined and MAY contain any value. It MUST beignored.2.2.1.5 <strong>Software</strong> <strong>Installation</strong> Maintenance MessageThis operation allows software maintenance utilities on the client to dynamically retrieve thedeployed software packages from the <strong>Group</strong> <strong>Policy</strong> server in contexts outside the <strong>Group</strong> <strong>Policy</strong><strong>Protocol</strong>, as specified in [<strong>MS</strong>-GPOL]. This message MUST be identical to the software installationread administration message specified in section 2.2.2.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200817 / 48
2.2.2 <strong>Software</strong> <strong>Installation</strong> Read Administration MessageIn this message, settings from a single GPO are retrieved by the client for use in softwaremaintenance utilities or in use by <strong>Policy</strong> Read Administration tools.The <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> sequence for read administration issimilar to that used during policy application for a single GPO, as defined in section 2.2.1. Thedifference is in the search filter used. The search filter for read administration MUST be:(|(|(msiScriptName=*A*)(msiScriptName=*P*))(!(msiScriptName=*)))The remainder of the sequence MUST be the same.2.2.3 <strong>Software</strong> <strong>Installation</strong> Write AdministrationThe following messages MUST be used by administrative tools to update software installationsettings.2.2.3.1 Class Store Creation MessageThe class store container of the gpContainer object in Active Directory is the container for allPackageRegistration objects that represents deployed software. This message MUST be an LDAPaddRequest message, as specified in [RFC2251]. The message MUST have the following fields:ParameterentryattributesValueMUST be a DN of the form CN=Class Store, where is ascoped GPO DN.This field MUST specify the attributes objectClass and displayName in an attributeList, asspecified in [RFC2251].The attributes member is itself a sequence of attribute name and value pairs. The table belowspecifies these pairs and their meanings:AttributeName Value MeaningobjectClassdisplayNameMUST be the Unicode string value classStore. TheUnicode string's UNICODE BOM encoding is little-endianonly. Big-endian UNICODE BOM encoding is notsupported.This field MUST be the Unicode string value ApplicationStore. The Unicode string's UNICODE BOM encoding islittle-endian only. Big-endian UNICODE BOM encodingis not supported.The name of the object ActiveDirectory object class type tocreate through this message.A field whose value indicates awell-formed object.2.2.3.2 Packages Container Creation MessageThe packages container of the classStore object in Active Directory is the container for allPackageRegistration objects that represent deployed software. This message MUST be an LDAPaddRequest message, as specified in [RFC2251]. The message MUST have the following fields:[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200818 / 48
ParameterentryattributesValueMUST be a DN of the form CN=Packages,CN=Class Store, where is a scoped GPO DN.This field MUST specify the attributes objectClass and displayName.The attributes member is itself a sequence of attribute name and value pairs. The table belowspecifies these pairs and their meanings:AttributeName Value MeaningobjectClassdisplayNameMUST be the Unicode String value classStore. TheUnicode String's UNICODE BOM encoding is little-endianonly. Big-endian UNICODE BOM encoding is notsupported.This field MUST be the Unicode String value ApplicationStore. The Unicode String's UNICODE BOM encoding islittle-endian only. Big-endian UNICODE BOM encodingis not supported.The name of the object ActiveDirectory object class type tocreate through this message.A field whose value indicatesa well-formed object.2.2.3.3 Package Creation MessageThis message creates a PackageRegistration object in the Active Directory and an applicationadvertise script file in the file system of the <strong>Group</strong> <strong>Policy</strong> server. The LDAP portion of the messageMUST be an LDAP addRequest message, as specified in [RFC2251].ParameterentryattributesValue<strong>Software</strong> package DN that corresponds to the GPO DN. This MUST be a DN of the formCN=,CN=Packages,CN=Class Store, where is a scoped GPO DN and is a curly braced GUID string. TheGUID portion of the DN MUST be generated using the standard GUID generation algorithm,as specified in [C706].The attributes defined in the software installation search reply message specified in section2.2.1.4 MUST be supplied in the attributeList of this addRequest message along with thevalues wanted by the policy administrator. The semantics of the attributes are the same asthose specified for the PackageRegistration object in the <strong>Software</strong> <strong>Installation</strong> Search Replymessage specified in section 2.2.1.4.Note that the msiScriptName attribute MUST always be present, and it MUST be specified with thefollowing semantics.ParametermsiScriptNameValueUnicode String that MUST have the little-endian UNICODE BOM encoding, and MUST beone of the following values:ValueAPMeaningAssigned application.Published application.19 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
ParameterValueRRemoved application.The SMB portion of the message is an application advertise script file.2.2.3.4 Class Store Confirmation MessageThe class store container of the gpContainer object in Active Directory is the container for allPackageRegistration objects that represent deployed software. This message updates that containerwhen a client has created the packages container within it. In this way, other clients accessing theobject for policy application or administration protocol sequences have an indication that thiscontainer is valid. The marking technique is simply to stamp the object with a valid version number.clients consider this container invalid if it does not have this stamp of approval. The message MUSTbe an LDAP addRequest message, as specified in [RFC2251]. The message MUST have the followingfields:ParameterobjectmodificationValueMUST be a DN of the form CN=Class Store, where is ascoped GPO DN.This field MUST specify the attributes appSchemaVersion and displayName.The attributes member is itself a sequence of attribute name and value pairs. The table that followsspecifies these pairs and their meanings.Attribute Value MeaningappSchemaVersion MUST be the integer value 0x000006CC. A version number used toensure that clients arecompatible with theunderlying object.displayNameThis field MUST be the Unicode String valueApplication Store. The Unicode String's UNICODEBOM encoding is little-endian only. Big-endianUNICODE BOM encoding is not supported.A field whose value indicatesa well-formed object.2.2.3.5 Package Update MessageThis message updates a PackageRegistration object in the Active Directory. The LDAP portion of themessage MUST be an LDAP modifyRequest message, as specified in [RFC2251].ParameterEntryattributesValue<strong>Software</strong> package DN for the PackageRegistration object. This MUST be a DN of the formCN=,CN=Packages,CN=Class Store, where is a scoped GPO DN and is a curly braced GUID string.This field MUST specify the attribute "lastUpdateSequence" and the msiScriptName attributeMUST also be specified for all updates according to the rules in section 2.2.3.3.20 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
The semantics of the attributes are the same as those specified for the PackageRegistration object inthe <strong>Software</strong> <strong>Installation</strong> Search Reply message specified in section 2.2.1.4.The following additional requirements apply to the attributeList:1. lastUpdateSequence attribute value MUST be set to the current UTC time of the client computer'sclock. This attribute's value MUST be specified in USN format.2. objectGUID attribute MUST NOT be specified in the attributes field.3. msiFileList attribute MUST NOT be specified in the attributes field. This field is only specified aspart of the package creation message. That is, it is an invariant of a given package.4. msiScriptPath attribute MUST NOT be specified in the attributes field.The SMB portion of the message MUST BE an application advertise script file. This part of themessage is optional if the file already exists in the GPO. The file only needs to be updated in certaincircumstances, as specified in section 3.2.5.4.2.2.3.6 Package Deletion MessageThis message deletes a PackageRegistration object in the Active Directory. The LDAP portion of themessage MUST be an LDAP deleteRequest message, as specified in [RFC2251], with the followingparameter:ParameterLDAPDNValue<strong>Software</strong> package DN of the PackageRegistration object. This MUST be a DN of the formCN=,CN=Packages,CN=Class Store, where is a scoped GPO DN, and is a curly braced GUID string.2.2.4 Application Advertise ScriptThe Application advertise script is a file containing a linear sequence of installation operations to beperformed, such as file and registry updates, configuration database updates and UI notifications.The file uses a binary format and is specified using ABNF grammar. ABNF is specified in [RFC4234].Each record MUST consist of an operation identifier (opcode), argument count, and an array ofarguments, essentially a serialization of the record objects to be used by the installer.Data types supported include NULL, integer, and variable length string and binary data. All dataMUST be stored in little-endian byte ordering, with the exception of non-Unicode strings and binarystream, which are padded to a 16-bit boundary.The Application advertise script is based on Microsoft Windows Installer technology and requires theauthor of Application advertise script file to have detailed knowledge of the Installer technology.The following ABNF grammar specifies the Application advertise script file format:AASFile = Header ProductInfo SourceListPublish ProductPublish EndHeader= %x02 %x09 ArgumentsProductInfo = %x04 %x10 ArgumentsSourceListPublish = %x09 ArgumentsProductPublish = %x10 %x01 ArgumentsEnd= %x03 %x03 Arguments[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200821 / 48
Arguments = Argument / (Arguments Argument)Argument = DataType DataDataType = Type + [DataLength]Type = *2OCTETDataLength = *2OCTETData = *16383OCTET2.2.4.1 Application Advertise Script Record StructureThe first 16-bit word of a record MUST contain the opcode in the low byte and the argument count inthe high byte.Argument Count (high byte)Operation Code (low byte)Each argument specified MUST be preceded by a 16-bit word that specifies the data type and lengthof the following argument data. The exact data representation depends upon the type. Themaximum length of an argument is 16,383 characters.The following table specifies the Opcode Argument format:Data typeNull string(all types)32-bitsignedintegerNullargumentExtendedsizeASCII charstringbinarystreamUnicodestringType andlengthencoding (16bits)0x00x40000x80000xC0000x0 + length ofstring0x8000 + bytecount0xC000 +length ofDataAbsent32 bit Integer valueAbsent32 bit type and size information followed by data. If the length of thestring or stream is greater than 0x3FFF, the data type value MUST be0xC000 and is followed by a 32-bit value that includes the length of thedata + the type. The type MUST be in the high order 2 bits.The value written is the value obtained from the following formula:(length + DataType
Data typeType andlengthencoding (16bits)Unicode stringData2.2.4.2 Opcode ListOpcodes MUST be specified as part of the Application Advertise Script file. Each opcode, immediatelyfollowed by its arguments, MUST appear in the file in the following sequence:Operation Code Description Number of Arguments2 Header 94 ProductInfo 169 SourceListPublish 5 + 3*(number_of_disks) + 116 ProductPublish 13 End 3Arguments for the opcodes are described in the remaining topics in this section.2.2.4.2.1 Header (Opcode 2)Opcode 2 is the header of an Application Advertise Script. The Header includes the followingarguments:• Signature32-bit signed integer. The value MUST be 1397708873.• Version32-bit signed integer. The value MUST be 400.• Timestamp32-bit signed integer. The stamp is local time represented as 2 OCTETs containing the date andtime. Data in the OCTETS is arranged as follows:Octet Name Bits DescriptionDOSDate 0-4 Day of Month: 1 - 315-8 Month: 1 - 12 (1 = January, 2 = February, etc.)9-15 Year: Offset from 1980DOSTime 0-4 Seconds: Value is divided by 2[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200823 / 48
Octet Name Bits Description5-10 Minutes: 0 - 5911-15 Hour: 0 - 23, using a 24-hour clockThe Timestamp MUST store the OCTETs as follows: ((DOSDate
A string (array) of either ASCII characters or Unicode characters.• PackageNameA string (array) of either ASCII characters or Unicode characters.• Language32-bit signed integer. The value is an LCID, identical in value to LangId in the header.• Version32-bit signed integer. Conversion of authored ProductVersion string property in the formmajor.minor.build where major max is 255 and minor and build max are 65535.The algorithm to compute the version is as follows. Given a version A.B.C, the integerrepresentation is ((A
32-bit signed integer. When the installation is accomplished via a multi-instance transform thevalue MUST be 1. Otherwise, the value MUST be 0. Installing Multiple Instances with InstanceTransforms is described further in [<strong>MS</strong>DN-WindowsInstaller].• LUASetting32-bit signed integer. The value MUST be 1 when the product supports UAC patching. Otherwise,the value MUST be 0. The default value is 0.See [<strong>MS</strong>DN-WindowsInstaller] for "User Account Control (UAC) Patching" details.• RemoteURTInstalls32-bit signed integer. The value MUST be 0.• ProductDeploymentFlags32-bit signed integer. The value MUST be 1.2.2.4.2.3 SourceListPublish (Opcode 9)Opcode 9 provides information about sources for creating the product. SourceListPublish includesthe following arguments:• PatchCodeASCII character string. The value MUST be NULL.• PatchPackageNameASCII character string. The value MUST be NULL.• DiskPromptTemplateA string (array) of either ASCII characters or Unicode characters.The value is copied from the DiskPrompt property specified in [<strong>MS</strong>DN-WindowsInstaller].• PackagePathA string (array) of either ASCII characters or Unicode characters.• NumberOfDisks32-bit signed integer. The value is copied from the Media Table, and is a count of number ofmedia entries for the package.• DiskId32-bit signed integer. The value is copied from the Media Table.Note: This argument is repeated for each disk specified NumberOfDisks.• VolumeNameA string (array) of either ASCII characters or Unicode characters. The value is copied from theMedia Table.Note: This argument is repeated for each disk specified NumberOfDisks.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200826 / 48
• DiskPromptA string (array) of either ASCII characters or Unicode characters. The value is copied from theMedia Table.Note: This argument is repeated for each disk specified NumberOfDisks.• LaunchPathA string (array) of either ASCII characters or Unicode characters. LaunchPath is the sourcelocation for the <strong>MS</strong>I package. The value is copied from the Media Table.When the installation is invoked after advertisement, the <strong>MS</strong>I package will be accessed at thislocation. This location MUST exist and MUST include the .<strong>MS</strong>I for which this advertise scriptrepresents.For example, if a advertise script for the .<strong>MS</strong>I package at"\\server\share\apps\app1\example.msi" was created, then LaunchPath will be set to"\\server\share\apps\app1\".2.2.4.2.4 ProductPublish (Opcode 16)Opcode 16 provides information about the installation package. ProductPublish includes the followingargument:• PackageKeyASCII character string. Represented as a GUID, PackageKey is the package code of theinstallation package.2.2.4.2.5 End (Opcode 3)End (Opcode 3) includes the following arguments:• Checksum32-bit signed integer. The value MUST be 0.• ProgressTotalHDWord32-bit signed integer. The value MUST be 0. This argument is not used.• ProgressTotalLDWord32-bit signed integer. The value MUST be 0. This argument is not used.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200827 / 48
3 <strong>Protocol</strong> Details3.1 Client Plug-in DetailsThe client plug-in is invoked after the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong> client has computed a list of GPOs forwhich the <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> client plug-in is to be invoked.3.1.1 Abstract Data ModelThis section describes a conceptual model of possible data organization that an implementationmaintains to participate in this protocol. The described organization is provided to facilitate theexplanation of how the protocol behaves. This document does not mandate that implementationsadhere to this model as long as their external behavior is consistent with what is specified in thisdocument.The software installation protocol state can be modeled in the following manner:• Client Environment:MUST include the following elements:• Architecture:The architecture of the system (what processor it uses).• User Language:A primary language identifier associated with each user logged on to the system. It MAY beused during user policy application mode to filter software by language.• Computer Language:A primary language identifier associated with the system. It is used during user policyapplication mode to filter software by language.• GPO List:A list of GPOs for which the policy application portion of this extension was invoked. The clientcaches this for use in out-of-band policy application.• <strong>Policy</strong> Target List:A list of entries, each of which contain a policy target account and an associated softwaredeployment list.• <strong>Software</strong> Deployment List:MUST be a list of software deployment entries for software that is installed on the computerthrough the <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> for a particular policy target.This allows the client to keep track of what software has been installed by the protocol; in thisway, when a particular software deployment is no longer returned in the protocol for a givenpolicy target, that software can be removed.• <strong>Software</strong> Deployment:A software package and a deployment instruction.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200828 / 48
• <strong>Software</strong> Package:Provides a reference to an executable or an installation database that allows a certain applicationto be deployed. The reference is a network file system path that MUST resolve to either aWindows Installer package or a Windows executable program that can install the application. Italso gives information on how the client can manipulate this application locally (for example, itdescribes how the application can be installed and removed). Caching this state on the client canbe useful for other local operations that are outside the context of this protocol sequence. Anexample of such a local operation is removing the application when the client is not connected toa network. The state MUST consist of the following:• PackageName:User-friendly name of the application.• VersionHi:Major version number of the application.• VersionLo:Minor version number of the application.• Revision:Version number of the deployment as found in the revision attribute. The version changeseach time a redeploy action occurs.• PackageId:A GUID unique in the domain for this software package. The objectGUID attribute of thePackageRegistration object MAY be used for this.• ProductId:Product identifier GUID.• Language:Numerical primary language identifier that indicates the language version of the applicationretrieved in the localeID attribute.• OutofScopeBehavior:Indicates what to do if the client has installed the application in the past, but policy applicationmessages for this policy target no longer include this software package.• Vendor:Friendly name of the application vendor.• User Assistance Resource:URL to a resource that allows users of the application to obtain support.• PackageType:Indicates the type of package used to install the application. This corresponds to thepackageType attribute defined in section 2.2.1.4.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200829 / 48
• Deployment Instruction:MUST be one of the following:ValueInstallUninstallUpgradeMeaningInstall this application.Remove this application if it was previously installed on this computer through this protocol.Install this application if it is listed as an upgrade of an application previously installedthrough this protocol.Note The above conceptual data can be implemented using a variety of techniques. Animplementation is at liberty to implement such data in any way it pleases.3.1.2 TimersNone.3.1.3 InitializationThere is no initialization behavior required for this extension beyond the initialization required for the<strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong> itself.3.1.4 Higher-Layer Triggered EventsNone.3.1.5 Message Processing Events and Sequencing RulesFor each <strong>Group</strong> <strong>Policy</strong> object for which the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong> has determined the extension mustexecute (that is, with a GUID that is this extension's CSE GUID), one software installation messageMUST be read from the server, as specified below. If any of the operations specified below fail, theentire software installation sequence MUST be terminated.The <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong> sequence steps can be separated into thefollowing high-level steps:1. <strong>Software</strong> Deployment Retrieval2. <strong>Software</strong> Deployment Applicability3. <strong>Software</strong> Action Determination4. <strong>Software</strong> Configuration5. <strong>Software</strong> <strong>Installation</strong> MaintenanceThese steps are specified in detail below.3.1.5.1 <strong>Software</strong> Deployment RetrievalThe procedure described in this section generates the software deployment protocol sequencesspecified in section 2.2.1. Each of the retrieved PackageRegistration objects MUST undergo[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200830 / 48
applicability filtering. If the syntax of a PackageRegistration object is not valid, the entire objectMUST be ignored, and no further protocol sequences are to be generated relating to it.Given a GPO path (DN), the following protocol sequences MUST be generated:1. An LDAP BindRequest message MUST be sent from the client to the <strong>Group</strong> <strong>Policy</strong> server. Theparameters to the BindRequest message MUST include a DN to the classStore containerparameter. The authentication choice MUST be Kerberos for computer policy mode, and itMUST be SPNEGO, as specified in [<strong>MS</strong>-SPNG], for user policy mode. The version field's valueMUST be 3.2. A software installation container search request message, as defined in section 2.2.1.1, MUST begenerated by the client. The corresponding response for this message is as specified in section2.2.1.2. If the ldapResult status for the response portion of the message is a success status, thesequence MUST continue with step 3. Otherwise, the sequence MUST terminate after step 3.3. An LDAP UnBindRequest message MUST be made by the client that corresponds to the previousLDAP BindRequest message in step 1.4. The client MUST generate an LDAP BindRequest message to the <strong>Group</strong> <strong>Policy</strong> server. Theparameters to the BindRequest message MUST include a DN to the packages container under theclassStore container. The authentication choice MUST be Kerberos for computer policy mode, andit MUST be SPNEGO, as specified in [<strong>MS</strong>-SPNG], for user policy mode. The version field MUST beset to 3. If this step fails, the protocol sequence MUST be terminated. Otherwise, it MUSTcontinue at step 5.5. After the successful BindResponse message, a software installation search request message, asspecified in section 2.2.1.3, MUST be generated by the client. The corresponding response forthis message is specified in section 2.2.1.4. If the ldapResult status for this message is a successmessage, the sequence MUST continue to step 6. Otherwise, the sequence MUST terminate afterstep 6.6. An LDAP UnBindRequest message MUST be made by the client corresponding to the previousLDAP BindRequest message in step 4.For each of the software packages listed in the software deployment list associated with the<strong>Policy</strong>Target for which the policy application is invoked, an attempt MUST be made to match thissoftware package with one of the PackageRegistration objects returned from the previous step. Asoftware package and PackageRegistration object match if the PackageRegistration's objectGUIDattribute has the same value as the software package's PackageId state. If no such match can bemade for the software package, the client MUST remove the application modeled by the softwarepackage, if the ACTFLG_Orphan flag is not specified in the packageFlags attribute of the <strong>Software</strong>Package.3.1.5.2 <strong>Software</strong> Deployment ApplicabilityA PackageRegistration object MUST be identified as applicable or not applicable to the client.The software MUST be considered applicable if all of the following criteria are met:1. Platform is applicable if the platform identified by the machineArchitecture attribute of thePackageRegistration object matches that of the local machine, or if the ACTFLG_AllowX86On64flag of the flags attribute is set.2. Language is applicable if the primary language identifier of the localeID attribute matches thatof the client computer, or the ACTFLG_IgnoreLanguage flag is set.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200831 / 48
3. The application is assigned, published, or removed.Any software that does not meet the criteria above is considered inapplicable and MUST NOT be partof the remainder of the protocol sequence.3.1.5.3 <strong>Software</strong> Action DeterminationFor an applicable application, the following rules MUST be used to decide what action to take on theclient:1. If the PackageRegistration object has the ACTFLG_Uninstall flag set in the flags field, the clientMUST attempt to remove it if it is installed on the client.2. If the local client state for a software package has an OutOfScopeBehavior corresponding to thedefinition of ACTFLG_UninstallOn<strong>Policy</strong>Removal in section 2.2.1, and the applicationcorresponding to that state's PackageId was not retrieved during policy application, theapplication MUST be removed.3. If the local client state for a software package has an OutOfScopeBehavior corresponding to thedefinition of ACTFLG_UninstallOrphanOnGPORemoval in section 2.2.1.4, and the applicationcorresponding to that state's PackageId was not retrieved during policy application, theapplication's software deployment in the software deployment list of the client's abstract datamodel MUST be deleted from any state for that model. This causes any such application that hasalready been installed on the client to no longer be affected by the extension.4. If the canUpgradeScript attribute of another PackageRegistration object retrieved during thisprotocol sequence references the objectGUID attribute of this object, this application MUST beignored.5. If the canUpgradeScript attribute contains a value with an objectGUID for an application from aPackageRegistration object that was previously installed by the client, the client MUST attempt toinstall the application.6. If this object and another PackageRegistration object retrieved during this protocol sequence bothreference each other by objectGUID in the canUpgradeScript attribute, only thePackageRegistration object from the higher precedence GPO MUST be installed. The others MUSTbe ignored.7. If this PackageRegistration object has a flags field with ACTFLG_Assigned and is not upgraded byanother application, the client MUST attempt to install it.8. If this PackageRegistration object has a flags field with ACTFLG_Orphan, the client MUST ignorethe application and remove any state on the client associated with it.9. If this PackageRegistration object's revision attribute is greater than that seen by the clientduring a previous protocol sequence, the client MUST attempt to reinstall the application.10.Clients MUST evaluate software package modification files with lower OrderIndex values in themsiFileList attribute before those with higher values when installing the software or modifying thesoftware deployment.For any application that is ignored, there MUST be no further protocol generated for it.3.1.5.4 <strong>Software</strong> ConfigurationThe software MUST be configured according to the action determined above in section 3.1.5.3.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200832 / 48
1. If the PackageType is that of MANAGED_APPTYPE_WINDOWSINSTALLER, then, if an installation,reinstallation, or removal is required according to the action determined above, the applicationadvertise script MUST be retrieved and processed:1. The following SMB protocol sequences MUST be generated to copy the file locally:SequenceSMB File Openfrom Client toServerSMB File ReadSequencesFile CloseDescriptionThe plug-in MUST attempt to open the file that is givenby the value of the msiScriptPath attribute. The authentication choice MUST beKerberos for computer policy mode, and it MUST be SPNEGO, as specified in[<strong>MS</strong>-SPNG], for user policy mode. If this step fails, the remainder of this protocolsequence MUST be skipped.A series of SMB file reads MUST be done to read the entire content of the openedfile, or until an error occurs.An SMB file close operation MUST be performed.The client's local software configuration subsystem SHOULD then process the file retrievedabove to install the application. Otherwise, it MAY install the application by passing theordered list of network file paths retrieved from the package's msiFileList attribute to theclient's local application installation subsystem.2. The software installation package at the location specified with OrderIndex 0 in the msiFileListattribute MUST be used to supply an installation subsystem on the client with the metadata toinstall or remove the application.2. If the PackageType was MANAGED_APPTYPE_SETUPEXE, then, if the action was determined to beinstallation, the client MUST execute the command specified in the PackageRegistration object'ssetupCommand attribute.• If the action was anything other than installation, the client MUST behave as if the action wasto do nothing, because PackageType MANAGED_APPTYPE_SETUPEXE only supports theinstallation action.3.1.5.5 <strong>Software</strong> <strong>Installation</strong> MaintenanceThis operation allows software maintenance utilities on the client to dynamically retrieve thedeployed software packages from the <strong>Group</strong> <strong>Policy</strong> server in contexts outside the <strong>Group</strong> <strong>Policy</strong><strong>Protocol</strong>, as specified in [<strong>MS</strong>-GPOL]. The client MUST then install them if a user or tool on the clientinitiates this.This sequence is not triggered by the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong>, but it is similar to it. It is only applicableto user policy settings.1. <strong>Software</strong> Deployment Retrieval. This is invoked by a software maintenance utility.1. The client maintains a GPO list in its abstract data model for the domain account of the userthat is executing the software maintenance utility. If no such state exists for that account onthe client computer, the extension MUST terminate the protocol sequence. Otherwise, theclient MUST continue with the next step.2. For each GPO in the list, the read administration protocol sequence specified in section 3.2.5.1MUST be invoked to retrieve the software packages for the policy target. This operation MUSTbe authenticated using the domain account of the user executing the software maintenanceutility.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200833 / 48
3. If the read administration sequence fails, this sequence MUST terminate. Otherwise, theextension MUST continue with the next step.2. <strong>Software</strong> Deployment Applicability. This step MUST be the same as specified in section 3.1.5.2,using the software deployments retrieved in step 1.<strong>Software</strong> maintenance utilities on the client MAY then present the applicable list of applications fromthe GPOs to a user. The data retrieved from this protocol enable the user to instruct the client toinstall or remove these applications.3.1.6 Timer EventsNone.3.1.7 Other Local EventsNone.3.2 Administrative Plug-in DetailsAdministrative tools use the policy administration portion of this protocol to present the current setof software deployments stored in a GPO, and also to allow administrators to edit thosedeployments.3.2.1 Abstract Data ModelA <strong>Group</strong> <strong>Policy</strong> server's storage of the policy administration data can be defined as follows.The <strong>Group</strong> <strong>Policy</strong> server models a list of deployed applications stored within a GPO. Each deployedsoftware item has a set of attributes that define what the client should do with the software (that is,install, remove, or reinstall), and how it should perform the operation.The administrative plug-in simply has a UI that can manipulate corresponding settings and pushthem to the server.• <strong>Software</strong> Deployment List:A list of deployed software items.• <strong>Software</strong> Deployment:A software package and a deployment instruction.• <strong>Software</strong> Package:Provides a reference to an executable or installation database that allows a certain application tobe deployed, and also gives information on how to do this. It MUST consist of the following:• PackageName:User-friendly name of the application.• Publisher:Name of the application publisher.• VersionHi:[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200834 / 48
Major version number of the application.• VersionLo:Minor version number of the application.• Revision:Version number of the deployment. The version number MUST change each time anapplication gets patched.• PackageId:This GUID MUST be unique in the domain for this software package. The objectGUID attributeof the PackageRegistration object MUST be used for this.• OutofScopeBehavior:Flag that indicates if the application SHOULD be uninstalled, if the client has installed theapplication in the past. However, policy application messages for this policy target no longerinclude this software package.• ProductId:If this application is installed by Windows Installer, this member MUST be the ProductId GUID.If this application is not installed by Windows Installer, this member MUST be a null GUID.• Language:Numerical language identifier that indicates the language version of the application.• Vendor:Friendly name of the application vendor.• User Assistance Resource:SHOULD be a URL to a resource that allows users of the application to obtain support.• LastUpdateTime:MUST be the last UTC time at which a write administration operation was performed on thissoftware deployment.• PackageType:MUST indicate the type of package used to install the application. This corresponds to thepackageType attribute defined in section 2.2.1.4.• Deployment Instruction:MUST be one of the following:1. Install:Install this application.2. Display:[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200835 / 48
In the context of software maintenance utilities, display this software to the user to allow theuser to install it.3. Uninstall:Remove this application if it was previously installed on this computer through this protocol.4. Upgrade:Install this application if it is listed as an upgrade of an application previously installed throughthis protocol.3.2.2 TimersNone.3.2.3 InitializationNone.3.2.4 Higher-Layer Triggered EventsNone.3.2.5 Message Processing Events and Sequencing Rules3.2.5.1 <strong>Policy</strong> Read AdministrationA policy administration tool on a client can read all of the software settings stored in the user policysettings section of a GPO, or stored in the computer policy settings section. An example of such atool is a utility on the client that uses the software settings stored in a GPO to display a list ofinstalled applications. The client MUST use the following procedure to read the software settings thatare stored in the GPO:1. An LDAP BindRequest message from the client to the <strong>Group</strong> <strong>Policy</strong> server and an LDAPBindResponses message in reply MUST be generated. The parameters to the BindRequestmessage MUST include a DN to the classStore container parameter for the GPO beingadministered, and the authentication choice MUST be SPNEGO, as specified in [<strong>MS</strong>-SPNG]. Theversion field value MUST be 3.2. A <strong>Software</strong> <strong>Installation</strong> Container Search Request message as defined in section 2.2.1.1 MUST begenerated by the Client. The corresponding response for this message is specified in section2.2.1.2. If the ldapResult status for the response portion of the message is a success status, thesequence MUST continue with the next step below. Otherwise, the sequence MUST terminateafter the next step.3. An LDAP UnBindRequest MUST be made by the Client that corresponds to the previous LDAPBindRequest in step 1.4. The Client MUST generate an LDAP BindRequest to the GP Server. The parameters to theBindRequest MUST include a DN to the packages container under the classStore container, andthe authentication choice MUST be SPNEGO, as specified in [<strong>MS</strong>-SPNG]. The version field's valueMUST be 3. If this step fails, the protocol sequence MUST be terminated. Otherwise, it MUSTcontinue at the next step below.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200836 / 48
5. After the successful BindResponse, a <strong>Software</strong> <strong>Installation</strong> Search Request message as specifiedin section 2.2.1.3 MUST be generated by the Client. The corresponding response for this messageis specified in section 2.2.1.4. This <strong>Software</strong> <strong>Installation</strong> Search Reply searchResponse containsPackageRegistration objects that represent deployed software in the GPO. This software MAY thenbe presented to a user who is browsing the GPO's settings or other GPO managementactivities.6. An LDAP UnBindRequest message MUST be made by the client corresponding to the previousLDAP BindRequest message in step 4.Any failure codes returned from the LDAP operations listed above MUST be treated as a failure, andthe protocol sequence above MUST be terminated.Note For read administration, no SMB protocol sequences are generated.3.2.5.2 <strong>Policy</strong> Write AdministrationThe write administration sequence of the <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>allows administrators to add new deployed software to a GPO so that it can be installed by clientsthrough the policy administration portion of the extension. It also allows administrators to makechanges to the way in which the deployed software behaves on the client, or to remove thedeployments.The following sequencing behaviors comprise the class of policy write administration sequences.3.2.5.3 Package CreationWhen an administrator deploys new software, a new software package is created. The plug-in MUSTaccomplish this in the following way, using the messages specified in section 2.2.3:1. An LDAP BindRequest message from the client to the <strong>Group</strong> <strong>Policy</strong> server and an LDAPBindResponses message in reply MUST be generated. The parameters to the BindRequestmessage MUST include a DN to the LDAP DN for the <strong>Group</strong> <strong>Policy</strong> being administered, and theauthentication choice MUST be SPNEGO, as specified in [<strong>MS</strong>-SPNG]. The version field value MUSTbe 3.2. After the successful BindResponse message, an LDAP SearchRequest message MUST be sent tothe <strong>Group</strong> <strong>Policy</strong> server and a searchResponse message is received, as defined in section 2.2.1.This searchResponse message contains PackageRegistration objects that represent deployedsoftware in the GPO. This software SHOULD be presented to a user who is browsing the GPOsettings or other GPO management activities.3. The client MUST issue a class store creation message, as specified in section 2.2.3.1. If thissucceeds or returns an ldapResult message indicating that the ClassStore already exists, theextension MUST continue to the next step. Otherwise, this protocol sequence MUST beterminated.4. The client MUST issue a package container creation message, as specified in section 2.2.3.2.1. If this succeeds, the client MUST issue a Class Store Confirmation message as specified in2.2.3.4. If the ldapResult message returned from that message indicates a failure, thisprotocol sequence MUST be terminated.2. If the package container creation message failed because the container already exists, theextension MUST continue to the next step.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200837 / 48
3. If the package container creation message failed for any other reason, this protocol sequenceMUST be terminated.5. The client MUST issue a package creation message, as specified in section 2.2.3.3, setting theattributes of the message according to the administrator's specifications of the softwaredeployment, as specified in sections 2.2.3.3 and 2.2.1.4. If this message returns a failedldapResult message, the extension protocol MUST be terminated after the next step.6. An LDAP UnBindRequest message MUST be made by the client corresponding to the previousLDAP BindRequest message in step 1.3.2.5.4 Package ModificationAfter software has been deployed in a GPO as a software package, an administrator might want tochange properties of the software package, such as its display name in administrative tools, whetherit is published or assigned, and so on. If specified by an administrator, this MUST be accomplishedwith the following protocol sequences:1. An LDAP BindRequest message from the client to the <strong>Group</strong> <strong>Policy</strong> server MUST be generated,resulting in an LDAP BindResponse message in reply. The parameters to the BindRequestmessage MUST include a software package DN for the software package to be updated, and theauthentication choice MUST be SPNEGO, as specified in [<strong>MS</strong>-SPNG]. The version field value MUSTbe 3.2. The client MUST issue a class store creation message, as specified in section 2.2.3.1. If thissucceeds or returns an ldapResult message indicating that the ClassStore already exists, theextension MUST continue to the next step. Otherwise, the protocol sequence MUST beterminated.3. The client MUST issue a package update message (specifying the attributes of thePackageRegistration object) that corresponds to properties of the software package that theadministrator wants to modify.4. An LDAP UnBindRequest message MUST be made by the client corresponding to the previousLDAP BindRequest message in step 1. If step 3 returned an ldapResult message failure status,the protocol sequence MUST be terminated. Otherwise, the extension MUST continue to step 5.5. If the revision attribute was successfully modified in step 3, the client MAY generate an SMBprotocol sequence to update the application advertise script file for this PackageRegistrationobject. This sequence MUST be the following:1. SMB File Open from client to server:The plug-in MUST attempt to open the file that is identified by thevalue of the msiScriptPath attribute. The authentication choice MUST be Kerberos forcomputer policy mode, and it MUST be SPNEGO, as specified in [<strong>MS</strong>-SPNG], for user policymode. Write access MUST be requested for this operation. If this step fails, the remainder ofthis protocol sequence MUST be skipped.2. SMB File Write Sequence:A series of SMB file writes MUST be done to replace the entire contents of the opened file withthe new application advertise script file content, or until an error is encountered.3. File Close:[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200838 / 48
An SMB file close operation MUST be issued after the file has been replaced by the client, oran error in writing occurs.3.2.5.4.1 Package PatchingAs part of routine software maintenance, software patching is done to update software due todefects in functionality or security. Within the context of the software installation extension,patching MUST be done through the package modification protocol sequence to force all clients thathave previously installed this software package to install the latest version of the software package,thus patching the clients. This also ensures that clients that have not already installed the softwarepackage can install a version that does not have the defects addressed by the patch.The package modification MUST be used for patching in the following manner:1. An administrator might want to update the software package file referenced by thePackageRegistration object's msiFileList attribute to conform to the patch. However, themechanism to do this update is not part of the <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong><strong>Extension</strong>.2. An administrator might also want to update files referenced by the metadata within the softwarepackage file itself to conform to the patch. However, the mechanism to do this update is also notpart of the <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>.3. The package modification sequence specified in section 3.2.5.4 MUST be executed.In step 3 for the package update protocol sequence, one attribute MUST be specified: therevision attribute. The value for this attribute MUST be one more than the value obtained fromreading it through the read administration mechanism.The package update protocol sequence above MUST increment the software package's revisioncount, thus indicating that there are new changes to this software. The effect of this operation onclients is specified in section 3.1.5.3 step 7.3.2.5.5 Package RemovalAdministrators might want an application that is deployed in a GPO to be removed from all clientsthat previously installed it through this extension. If specified by an administrator, this plug-in MUSTaccomplish this through a package update sequence (as specified in section 2.2.3.5) with thefollowing characteristics:• The package update sequence MUST be specified with a packageFlags attribute specified in theattribute list. The value of this integer MUST have the ACTFLG_Uninstall flag set.Information on how this causes the Client to remove this application when the policy applicationmode sequence is invoked is specified in section 3.1.5.3.3.2.5.6 Package ObsolescenceAdministrators might want to stop a GPO from deploying an application without uninstalling theapplication from any clients on which the GPO had already deployed the application. If specified byan administrator, this plug-in MUST accomplish this through a package update sequence (asspecified in section 2.2.3.5) with the following characteristics:• The package update sequence MUST be specified with a packageFlags attribute specified in theattribute list. The value of this integer MUST have the ACTFLG_Uninstall flag set.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200839 / 48
Information on how this causes the client to remove this application when the policy applicationmode sequence is invoked is specified in section 3.1.5.3.3.2.5.7 Package DeletionIf an application that has been deployed by a GPO is not to be deployed on any additional clients,the administrator might want to remove the application from GPO storage on the <strong>Group</strong> <strong>Policy</strong>server. Removing the application saves space on the <strong>Group</strong> <strong>Policy</strong> server. If specified by anadministrator, this MUST be done with the following protocol sequence:1. An LDAP BindRequest message from the client to the <strong>Group</strong> <strong>Policy</strong> server and an LDAPBindResponses message in reply MUST be generated. The parameters to the BindRequestmessage MUST include a software package DN for the software package to be deleted, and theauthentication choice MUST be SPNEGO, as specified in [<strong>MS</strong>-SPNG]. The version field value MUSTbe 3.2. A package deletion message MUST be issued by the client. If the message returns an ldapResultmessage with a failure status code, the plug-in MUST proceed to the next step. Otherwise, theextension MUST be terminated after the next step.3. An LDAP UnbindRequest message MUST be made by the client corresponding to the previousLDAP BindRequest in step 1.4. The file previously referenced in the msiScriptPath attribute of the PackageRegistration objectthat was deleted MUST itself be deleted. This path MUST be obtained by the client by reading thisattribute before the deletion of the object through the read administration protocol sequencespecified in section 2.2.2. The deletion corresponds to the following SMB protocol sequence:1. SMB File Open from client to server:The plug-in MUST attempt to open the file that is identified by thevalue of the msiScriptPath attribute. SPNEGO, as specified in [<strong>MS</strong>-SPNG], authentication MUSTbe used. Write access MUST be requested for this operation. If this step fails, the remainder ofthis protocol sequence MUST be skipped.2. SMB File Delete Message:The message MUST be sent using the UncPath referenced in the msiScriptPath attribute of thePackageRegistration object.3. SMB File Close:An SMB file close operation MUST be issued after the file is replaced by the client, or an errorin writing occurs.3.2.6 Timer EventsNone.3.2.7 Other Local EventsNone.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200840 / 48
4 <strong>Protocol</strong> ExampleThis section provides two topics:• <strong>Software</strong> <strong>Installation</strong> Search Result <strong>Protocol</strong> Example (section 4.1)• Sample Application Advertise Script File (section 4.2).4.1 <strong>Software</strong> <strong>Installation</strong> Search Result <strong>Protocol</strong> ExampleThe following example shows the fields of an LDAP searchResultEntry message as part of a softwareinstallation search result, as specified in section 2.2.1.4. The result has returned an assignedapplication named Sample App by the administrator. The application's primary language identifier isEnglish in this case, and it was created by a vendor named Sample Vendor.FieldmsiScriptNamecanUpgradeScriptpackageFlagsValueANot set0xFA0000110packageType 5msiScriptPathlastUpdateSequencelocaleID\\sampledom.sample.com\SysVol\sampledom.sample.com\Policies\{7D7BFB25-E550-4658-9D3D-068BBA2A672C}\Machine\Applications\{312D25D0-A2B7-4830-B5E9-810BBBCCE0CD}.aas0xFA00001100x409machineArchitecture 0packageNameSample AppversionNumberHi 4versionNumberLo 2VendorurlSample Vendorhttp://sampleapp.orgRevision 3productCodeobjectGUIDCategoriesmsiFileList{58221C66-E527-11CF-ADCF-00AA00A80033}{8EAD3A12-B2C9-11d0-83AA-00A0C92C9D5D}Not set0:\\appserver\appshare\samples\sampleapp.msiinstallUiLevel 041 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
4.2 Sample Application Advertise Script FileThe sample below shows the content of an Application Advertise Script file. Two views of the file arepresented:• A friendly representation of the data in the AAS file• A hexadecimal dump of the AAS fileThe first view: Friendly RepresentationHeader(Signature=1397708873,Version=400,Timestamp=922639356,LangId=1033,Platform=0,ScriptType=3,ScriptMajorVersion=21,ScriptMinorVersion=4,ScriptAttributes=0)ProductInfo(ProductKey={0F23F7E9-5825-4E00-8A00-40F14FC8E6C2},ProductName=<strong>Group</strong> <strong>Policy</strong> Log View Tool,PackageName=gpLogView.msi,Language=1033,Version=16777237,Assignment=0,ObsoleteArg=0,,,PackageCode={5646D4B1-EDED-41C9-B7B1-A1F0C17D9CEE},,,InstanceType=0,LUASetting=0,RemoteURTInstalls=0,ProductDeploymentFlags=3)ProductPublish(PackageKey={5646D4B1-EDED-41C9-B7B1-A1F0C17D9CEE})SourceListPublish(,,,,NumberOfDisks=1,1,,,\\AppServerShare1\Public\)End(Checksum=0,ProgressTotalHDWord=0,ProgressTotalLDWord=0)The second view:[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200842 / 48
Figure 2: AAS Hexadecimal Dump43 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
5 SecurityThe following sections specify security considerations for implementers of the <strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong><strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>.5.1 Security Considerations for ImplementersKey security issues: Implementers should be aware that the network paths used to actually installthe software are not secured by the <strong>Group</strong> <strong>Policy</strong> <strong>Protocol</strong>, as specified in [<strong>MS</strong>-GPOL]. ImplementersMAY choose to implement a separate security mechanism for this purpose, or warn administratorswho deploy applications through this protocol that they should take steps to ensure the integrity ofthe software deployed through this protocol.5.2 Index of Security ParametersSecurity parameterSectionKerberos authentication for computer policy application 2.2SPNEGO authentication for user policy application 2.244 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
6 Appendix A: Windows BehaviorThe information in this specification is applicable to the following versions of Windows:• Windows NT• Windows 2000• Windows XP• Windows Server 2003• Windows VistaExceptions, if any, are noted below. Unless otherwise specified, any statement of optional behaviorin this specification prescribed using the terms SHOULD or SHOULD NOT implies Windows behaviorin accordance with the SHOULD or SHOULD NOT prescription. Unless otherwise specified, the termMAY implies that Windows does not follow the prescription. Section 2.2.1.1: Windows always uses a timeLimit of 0. Section 2.2.1.1: Windows additionally specifies the attribute displayName, but then ignores itin the reply. Section 2.2.1.3: Windows always uses a timeLimit of 0. Section 2.2.1.3: Windows additionally specifies the attribute displayName, but then ignores itin the reply. Section 2.2.1.4: Windows Server 2003, Windows Vista, and Windows XP SP1 and later allignore the flag and act as if it was always set. Earlier versions of Windows use the flag as defined. Section 2.2.4: Microsoft Windows uses the Microsoft Windows Installer APIs,MsiAdvertiseProductEx function, and MsiAdvertiseScript function to generate and consume theApplication advertise scripts. MsiAdvertiseProductEx advertises a product and MsiAdvertiseScriptcopies an advertised script file into the specified locations. Section 3.1.5.3: The value ACTFLG_UninstallUnmanaged of the packageFlags field of thesoftware search response message defined in section 2.2.1.4 is ignored by all systems except forWindows 2000 and versions of Windows XP prior to service pack 1. Section 3.1.5.4: Windows processes the file retrieved above to install the application. Section 3.1.5.4: Windows clients require the software installation package to be a WindowsInstaller package specific to Windows. Section 3.1.5.5: Windows clients include a software maintenance utility that uses thisprotocol to display a list of applications from GPOs applicable to the user and allows the user toinstall or remove any of those applications. Section 3.2.5.1: Windows clients include a software maintenance utility that uses thisprotocol to display a list of applications from GPOs applicable to the user and allows the user toinstall any of those applications. Section 3.2.5.4: The administrative plug-in for the software installation extension of Windowssystems generates a new application advertise script whenever the revision attribute is updated.[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200845 / 48
Section 3.2.5.7: Windows tools use the software installation extension check for softwarethat has the equivalent of ACTFLG_Uninstall set or ACTFLG_Orphan set, and issue a packagedeletion request for <strong>Software</strong>Packages that were last updated more than one year before the timethe tool is executing (by using the LastUpdate property).[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 200846 / 48
7 IndexAAbstract data modeladministrativeclientAction determination - softwareAdministrativeabstract data modelhigher-layer triggered eventsinitializationlocal eventsmessage processingoverviewsequencing rulestimer eventstimersApplicabilitysoftware deploymentstatementApplication advertise script (section 2.2.4, section2.2.4.1)BBackgroundCCapability negotiationClass store confirmation messageClass store creation messageClientabstract data modelhigher-layer triggered eventsinitializationlocal eventsmessage processingoverviewsequencing rulestimer eventstimersConfiguration - softwareCreation - packageDData model - abstractadministrativeclientDeletion - packageEExamplesFFields - vendor-extensibleGGlossaryHHigher-layer triggered eventsadministrativeclientIImplementers - security considerationsInformative referencesInitializationadministrativeclientIntroductionLLocal eventsadministrativeclientMMaintenance - software installationMaintenance messageMessage processingadministrativeclientMessagesapplication advertise script (section 2.2.4, section2.2.4.1)overviewpolicy applicationread administrationsyntaxtransportwrite administrationModification - packageNNormative referencesOObsolescence - packageOverview (synopsis)PPackagecreationdeletion47 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
modificationobsolescencepatchingremovalPackage creation messagePackage deletion messagePackage update messagePackages container creation messageParameters - securityPatching - package<strong>Policy</strong> application messagesPreconditionsPrerequisitesRRead administrationmessagepolicyReferencesinformativenormativeoverviewRelationship to other protocolsRemoval - packageRetrieval - software deploymentTransport - messageTriggered events - higher-layeradministrativeclientVVendor-extensible fieldsVersioningWWindows behaviorWrite administrationmessagespolicySSearchreply message (section 2.2.1.2, section 2.2.1.4)request message (section 2.2.1.1, section 2.2.1.3)SecuritySequencing rulesadministrativeclient<strong>Software</strong>action determinationconfigurationdeployment applicabilitydeployment retrievalinstallation maintenance<strong>Software</strong> dontainer search request message<strong>Software</strong> installation container search reply message<strong>Software</strong> installation extension overview<strong>Software</strong> installation maintenance message<strong>Software</strong> installation read administration message<strong>Software</strong> installation search reply message<strong>Software</strong> installation search request message<strong>Software</strong> installation write administration messagesStandards assignmentsSyntax - messageTTimer eventsadministrativeclientTimersadministrativeclient48 / 48[<strong>MS</strong>-<strong>GPSI</strong>] – v20080207<strong>Group</strong> <strong>Policy</strong>: <strong>Software</strong> <strong>Installation</strong> <strong>Protocol</strong> <strong>Extension</strong>Copyright © 2008 Microsoft Corporation.Release: Thursday, February 7, 2008
![[MS-DFSRH]: DFS Replication Helper Protocol Specification](https://img.yumpu.com/51326226/1/190x245/ms-dfsrh-dfs-replication-helper-protocol-specification.jpg?quality=85)
![[MS-VDS]: Virtual Disk Service (VDS) Protocol Specification](https://img.yumpu.com/50743814/1/190x245/ms-vds-virtual-disk-service-vds-protocol-specification.jpg?quality=85)
![[MS-GPPREF]: Group Policy: Preferences Extension Data Structure](https://img.yumpu.com/50206932/1/190x245/ms-gppref-group-policy-preferences-extension-data-structure.jpg?quality=85)
Change language