intel® amt ws-management flows · the following topics must be considered when using ws-management...

Intel® Active Management Technology

WS-Management Flows

Version 4.0.7, June 2008

Intel® AMT WS-Management Flows

2

Information in this document is provided in connection with Intel® products. No license, express or implied, by estoppels or otherwise, to any intellectual property rights is granted by this document. Except as provided in Intel’s Terms and Conditions of Sale for such products, Intel assumes no liability whatsoever, and Intel disclaims any express or implied warranty, relating to sale and/or use of Intel products including liability or warranties relating to fitness for a particular purpose, merchantability, or infringement of any patent, copyright or other intellectual property right. Intel products are not intended for use in medical, life saving, or life sustaining applications. Intel may make changes to specifications and product descriptions at any time, without notice. The API and software may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. This document and the software described in it are furnished under license and may only be used or copied in accordance with the terms of the license. The information in this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Intel Corporation. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this document or any software that may be provided in association with this document. Except as permitted by such license, no part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written consent of Intel Corporation. Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order. Copies of documents which have an ordering number and are referenced in this document or other Intel literature may be obtained by calling 1-800-548-4725 or by visiting Intel’s website at http://www.intel.com. Copyright © 2007-2008 Intel Corporation. All rights reserved. * Third party other names and brands may be claimed as the property of others.

http://www.intel.com/


3

Table of Contents

1. Introduction ............................................................................................................................. 5 2. General Information and Considerations ................................................................................ 5

2.1. Supported WS-Management specs: .............................................................................. 5 2.2. UTF Encoding ................................................................................................................ 5 2.3. Selectors ........................................................................................................................ 5 2.4. Function Return Values and Errors................................................................................ 5

2.4.1. PT_STATUS Returned Numeric Values ............................................................... 6 2.4.2. Description of PT_STATUS Responses................................................................ 7

2.5. Return value from Put operations .................................................................................. 9 2.6. Operation Timeout.......................................................................................................... 9 2.7. Enumeration Support ..................................................................................................... 9 2.8. Envelope Size .............................................................................................................. 10 2.9. Key/Required Field Usage in WS-Management Operations ....................................... 10 2.10. Working with Intel AMT using Endpoint References (EPRs) ....................................... 10 2.11. OptionSet Support........................................................................................................ 11 2.12. Using Create and Put with Read-Only Properties........................................................ 11 2.13. Whitespace in XML Elements Policy............................................................................ 12 2.14. Class Namespace Usage............................................................................................. 12

3. Intel AMT Permissions and Realms...................................................................................... 12 4. Intel AMT WS-Management Flows ....................................................................................... 15

4.1. EAC .............................................................................................................................. 16 4.1.1. EAC Flow Diagram.............................................................................................. 16 4.1.2. EAC Flow............................................................................................................. 16

4.2. Environment Detection................................................................................................. 18 4.2.1. Environment Detection Flow................................................................................ 18

4.3. Event Manager ............................................................................................................. 19 4.3.1. Event Manager Diagram...................................................................................... 19 4.3.2. Event Manager Flow............................................................................................ 19

4.4. General Info.................................................................................................................. 22 4.4.1. General Info Diagram .......................................................................................... 22 4.4.2. General Info Flow ................................................................................................ 22

4.5. Firmware Update.......................................................................................................... 24 4.5.1. Firmware Update Diagram .................................................................................. 24 4.5.2. Firmware Update Flow ........................................................................................ 24

4.6. Hardware Asset............................................................................................................ 25 4.6.1. Hardware Asset Diagram .................................................................................... 25 4.6.2. Hardware Asset Flow .......................................................................................... 25

4.7. Network Time ............................................................................................................... 28 4.7.1. Network Time Drawing ........................................................................................ 28 4.7.2. Network Time Flow.............................................................................................. 28

4.8. Power Packages .......................................................................................................... 29 4.8.1. Power Scheme Diagram...................................................................................... 29 4.8.2. Power Package Flow........................................................................................... 29

4.9. Redirection Administration ........................................................................................... 31 4.9.1. Redirection Diagram............................................................................................ 31 4.9.2. Redirection Administration Flow.......................................................................... 31

4.10. Security Administration ................................................................................................ 32 4.10.1. Security Administration Diagram ......................................................................... 32 4.10.2. Security Administration Flow ............................................................................... 32

4.11. Authorization Service ................................................................................................... 35 4.11.1. Authorization Service Flow.................................................................................. 35

4.12. Agent Presence............................................................................................................ 36 4.12.1. Agent Presence Diagram .................................................................................... 36 4.12.2. Agent Presence Flow .......................................................................................... 36


4

4.13. 802.1x Configuration .................................................................................................... 38 4.13.1. 802.1x Configuration Diagram............................................................................. 38 4.13.2. 802.1x Configuration flow.................................................................................... 38

4.14. System Defense........................................................................................................... 40 4.14.1. System Defense Diagram.................................................................................... 40 4.14.2. System Defense Flow.......................................................................................... 40

4.15. Heuristic System Defense............................................................................................ 43 4.15.1. Heuristic System Defense Flow .......................................................................... 43

4.16. Setup and Configuration (Provisioning) ....................................................................... 46 4.16.1. Setup and Configuration Diagram ....................................................................... 46 4.16.2. Setup and Configuration Flow ............................................................................. 46

4.17. Network Administration ................................................................................................ 49 4.17.1. Network Administration Diagram......................................................................... 49 4.17.2. Network Administration Flow............................................................................... 49

4.18. Storage Administration................................................................................................. 51 4.18.1. Storage and Storage Administration Diagram..................................................... 51 4.18.2. Storage Administration Flow................................................................................ 51

4.19. Storage......................................................................................................................... 53 4.19.1. Storage Flow ....................................................................................................... 53

4.20. Remote Control ............................................................................................................ 56 4.20.1. Remote Control Diagram..................................................................................... 56 4.20.2. Remote Control Flow........................................................................................... 56

4.21. Remote Access and User Initiated Connection ........................................................... 58 4.21.1. Remote Access Diagram..................................................................................... 58 4.21.2. Remote Access Flow........................................................................................... 58

4.22. Audit Log ...................................................................................................................... 62 4.22.1. Audit Log Diagram............................................................................................... 62 4.22.2. Audit Log Flows ................................................................................................... 62

4.23. Wireless........................................................................................................................ 64 4.23.1. Wireless Diagram ................................................................................................ 64 4.23.2. Wireless Flow ...................................................................................................... 64

4.24. WS-Eventing ................................................................................................................ 66 4.24.1. Table of Events.................................................................................................... 66 4.24.2. WS-Eventing Diagram......................................................................................... 67 4.24.3. WS-Eventing Flow ............................................................................................... 67 4.24.4. WS-Eventing Serialization Examples .................................................................. 68

4.25. Role Based Authorization Profile ................................................................................. 75 4.26. Simple Identity Management Profile ............................................................................ 75


5

1. Introduction Intel® Active Management Technology (Intel® AMT) Release 3.0 and later releases support the WS-Management specification and can be managed using a combination of standard CIM classes and specially defined AMT classes. The classes are defined in the WS-Management Class documentation. This document provides general information about using the classes to implement a management solution, as well as example flows that show how to access Intel AMT functionality.

2. General Information and Considerations The following topics must be considered when using WS-Management functionality to work with an Intel AMT device.

2.1. Supported WS-Management specs: Intel AMT Release 3.0 supports the following WS-Management specification: Web Services for Management (DSP0226), 1.0.0a, April 5th, 2006

The implementation incorporates the following Change Requests: WIP-WSMANCR00041.001 (UTF-16 support changed to be not mandatory) WIP-WSMANCR00040.000 (Selector Filter Dialect) WIP-WSMANCR00044.002 (Selector Filter Dialect) WSMANCR00039.001 (Update master fault table

The implementation complies with the following: DMTF WS-CIM Mapping-1[1].0.0b DSP0227[1].WS-Man-CIM-Binding.1.0.0a

2.2. UTF Encoding AMT supports UTF-8 only (as UTF-16 is no longer mandatory according to WIP-WSMANCR00041.001)

2.3. Selectors Selector filter dialect (WIP-WSMANCR00040.000, WIP-WSMANCR00044.002): Intel AMT supports the selector filter dialect for specifying a scope on an enumeration, and not the older method (from DSP0226) of using a SelectorSet.

Only properties defined as keys in the MOF files can be used as selectors.

2.4. Function Return Values and Errors All functions can return WS-Management faults, as described in the WS-Management specification. The Intel AMT implementation does not perform some of the SHOULD statements in the WS-Management specification relating to faults.

The implementation returns errors relating to Intel AMT features in two ways:

• Generic WS-Management methods (for example, get, put, create, delete, and pull) will return a "wsman-internal-error” fault, with a detail field containing ”PT_STATUS". PT_STATUS is the Intel AMT status code.

• In "invoke" methods, the return values are defined in the method description in the MOF file. In many cases, for standard CIM classes, the relevant Intel AMT return values are returned in the “Vendor Specific” range of the return value map of the method. In such a case, the return value is the beginning of the “Vendor Specific” range + the PT_STATUS value.

The first table below lists the numbers that map to the PT_STATUS messages. The second table describes the reason for the message.

http://www.dmtf.org/standards/published_documents/DSP0226.pdf


6

2.4.1. PT_STATUS Returned Numeric Values typedef enum<UINT32> _PT_STATUS { PT_STATUS_SUCCESS = 0x0, PT_STATUS_INTERNAL_ERROR = 0x1, PT_STATUS_INVALID_PT_MODE = 0x3, PT_STATUS_INVALID_REGISTRATION_DATA = 0x9, PT_STATUS_APPLICATION_DOES_NOT_EXIST = 0xA, PT_STATUS_NOT_ENOUGH_STORAGE = 0xB, PT_STATUS_INVALID_NAME = 0xC, PT_STATUS_BLOCK_DOES_NOT_EXIST = 0xD, PT_STATUS_INVALID_BYTE_OFFSET = 0xE, PT_STATUS_INVALID_BYTE_COUNT = 0xF, PT_STATUS_NOT_PERMITTED = 0x10, PT_STATUS_NOT_OWNER = 0x11, PT_STATUS_BLOCK_LOCKED_BY_OTHER = 0x12, PT_STATUS_BLOCK_NOT_LOCKED = 0x13, PT_STATUS_INVALID_GROUP_PERMISSIONS = 0x14, PT_STATUS_GROUP_DOES_NOT_EXIST = 0x15, PT_STATUS_INVALID_MEMBER_COUNT = 0x16, PT_STATUS_MAX_LIMIT_REACHED = 0x17 PT_STATUS_INVALID_AUTH_TYPE = 0x18 PT_STATUS_INVALID_DHCP_MODE = 0x1A, PT_STATUS_INVALID_IP_ADDRESS = 0x1B, PT_STATUS_INVALID_DOMAIN_NAME = 0x1C, PT_STATUS_INVALID_PROVISIONING_STATE = 0x20, PT_STATUS_INVALID_TIME = 0x22, PT_STATUS_INVALID_INDEX = 0x23, PT_STATUS_INVALID_PARAMETER = 0x24, PT_STATUS_INVALID_NETMASK = 0x25, PT_STATUS_FLASH_WRITE_LIMIT_EXCEEDED = 0x26, PT_STATUS_UNSUPPORTED_OEM_NUMBER = 0x801, PT_STATUS_UNSUPPORTED_BOOT_OPTION = 0x802, PT_STATUS_INVALID_COMMAND = 0x803, PT_STATUS_INVALID_SPECIAL_COMMAND = 0x804, PT_STATUS_INVALID_HANDLE = 0x805, PT_STATUS_INVALID_PASSWORD = 0x806, PT_STATUS_INVALID_REALM = 0x807, PT_STATUS_STORAGE_ACL_ENTRY_IN_USE = 0x808, PT_STATUS_DATA_MISSING = 0x809, PT_STATUS_DUPLICATE = 0x80A, PT_STATUS_EVENTLOG_FROZEN = 0x80B, PT_STATUS_PKI_MISSING_KEYS = 0x80C, PT_STATUS_PKI_GENERATING_KEYS = 0x80D, PT_STATUS_INVALID_KEY = 0x80E, PT_STATUS_INVALID_CERT = 0x80F, PT_STATUS_CERT_KEY_NOT_MATCH = 0x810, PT_STATUS_MAX_KERB_DOMAIN_REACHED = 0x811, PT_STATUS_UNSUPPORTED = 0x812, PT_STATUS_INVALID_PRIORITY = 0x813, PT_STATUS_NOT_FOUND = 0x814, PT_STATUS_INVALID_CREDENTIALS = 0x815,


7

PT_STATUS_INVALID_PASSPHRASE = 0x816, PT_STATUS_NO_ASSOCIATION = 0x818, } PT_STATUS;

2.4.2. Description of PT_STATUS Responses Code Description

PT_STATUS_APPLICATION_DOES_NOT_EXIST The application handle provided in the request message is not valid.

PT_STATUS_BLOCK_DOES_NOT_EXIST The specified block does not exist.

PT_STATUS_BLOCK_LOCKED_BY_OTHER The specified block is locked by another application.

PT_STATUS_BLOCK_NOT_LOCKED The specified block is not locked.

PT_STATUS_CERT_KEY_NOT_MATCH Key pair does not match.

PT_STATUS_DATA_MISSING Essential data is missing on CommitChanges() command.

PT_STATUS_DUPLICATE The parameter specified is a duplicate of an existing value.

PT_STATUS_EVENTLOG_FROZEN Event log is frozen.

PT_STATUS_FLASH_WRITE_LIMIT_EXCEEDED The operation failed because the flash wear-out protection mechanism prevented a write to an NVRAM sector.

PT_STATUS_GROUP_DOES_NOT_EXIST The specified group does not exist.

PT_STATUS_INTERNAL_ERROR An internal error occurred while performing the operation.

PT_STATUS_INVALID_AUTH_TYPE Specified Key algorithm is invalid.

PT_STATUS_INVALID_BYTE_COUNT The specified byte count is invalid.

PT_STATUS_INVALID_BYTE_OFFSET The specified byte offset is invalid.

PT_STATUS_INVALID_CERT Invalid X.509 Certificate or invalid certificate handle.

PT_STATUS_INVALID_COMMAND The command specified in the remote control command is not supported by the Intel AMT device.

PT_STATUS_INVALID_CREDENTIALS Invalid User credentials.

PT_STATUS_INVALID_DHCP_MODE Specified DHCP mode is invalid.

PT_STATUS_INVALID_DOMAIN_NAME Specified Domain name is invalid.

PT_STATUS_INVALID_GROUP_PERMISSIONS The specified group permission bits are invalid.

PT_STATUS_INVALID_HANDLE The handle specified in the command is invalid.

PT_STATUS_INVALID_INDEX Specified index is not valid.


8

Code Description

PT_STATUS_INVALID_IP_ADDRESS Specified IP address is invalid.

PT_STATUS_INVALID_KEY Invalid RSA Key.

PT_STATUS_INVALID_MEMBER_COUNT The specified member count is invalid.

PT_STATUS_INVALID_NAME Specified name is invalid.

PT_STATUS_INVALID_NETMASK

An invalid netmask was supplied (a valid netmask is an IP address in which all ‘1’s are before the ‘0’ – e.g. FFFC0000h is valid, FF0C0000h is invalid).

PT_STATUS_INVALID_PARAMETER Invalid input parameter.

PT_STATUS_INVALID_PASSPHRASE Passphrase is invalid.

PT_STATUS_INVALID_PASSWORD The password specified in the User ACL is invalid.

PT_STATUS_INVALID_PRIORITY Priority setting is invalid.

PT_STATUS_INVALID_PROVISIONING_STATE Specified provisioning state is not valid.

PT_STATUS_INVALID_PT_MODE Specified mode of operation is invalid.

PT_STATUS_INVALID_REALM The realm specified in the User ACL is invalid.

PT_STATUS_INVALID_REGISTRATION_DATA

1. Either an invalid name was entered or an “Enterprise” name was specified that was not pre-registered.

2. The current registration was attempted from an interface different from the one used for the initial registration of the application.

PT_STATUS_INVALID_SPECIAL_COMMAND The special command specified in the remote control command is not supported by the Intel AMT device.

PT_STATUS_INVALID_TIME Specified time is not valid.

PT_STATUS_MAX_KERB_DOMAIN_REACHED

The FW allows storing an SID from a limited number of domains. This SID domain does not exist and there is no space to store a new domain.

PT_STATUS_MAX_LIMIT_REACHED No available storage in the specified structure.

PT_STATUS_NO_ASSOCIATION Current functionality requires association to a Key Pair.

PT_STATUS_NOT_ENOUGH_STORAGE The number of bytes requested cannot be allocated in ISV storage.

PT_STATUS_NOT_FOUND Unable to find specified element.


9

Code Description

PT_STATUS_NOT_OWNER The requesting application is not the owner of the block as required for the requested operation.

PT_STATUS_NOT_PERMITTED The requesting application is not permitted to request execution of the specified operation.

PT_STATUS_PKI_GENERATING_KEYS Reserved for future use.

PT_STATUS_PKI_MISSING_KEYS Reserved for future use.

PT_STATUS_STORAGE_ACL_ENTRY_IN_USE The FPACL or EACL entry is used by an active registration and cannot be removed or modified.

PT_STATUS_SUCCESS Operation completed successfully.

PT_STATUS_UNSUPPORTED Setting is not supported by this product.

PT_STATUS_UNSUPPORTED_BOOT_OPTION The boot option specified in the remote control command is not supported by the Intel AMT device.

PT_STATUS_UNSUPPORTED_OEM_NUMBER The OEM number specified in the remote control command is not supported by the Intel AMT device.

2.5. Return value from Put operations Intel AMT does not return the representation of an object after a Put operation. The client should invoke another Get request to get the new representation. However, if the Put request includes a read/write property, and the Intel AMT device does not return a fault, the client can assume that the value of any changed fields has been updated to the requested value.

2.6. Operation Timeout Most management operations are time-critical due to quality-of-service constraints and obligations. The WS-Management protocol defines an optional <wsman:OperationTimeout> tag in the SOAP header which specifies the client's request to complete the operation within the specified timeout. Since Intel AMT cannot estimate the time to complete an operation, the Release 3.0 implementation enforces a minimum timeout of 30 seconds, which should be sufficient to complete almost any operation that Intel AMT supports. Clients should be flexible enough in handling related WS-Management faults that occur for operations that might take longer than 30 seconds.

2.7. Enumeration Support Intel AMT provides a mechanism for enumerating a multi-instanced resource or querying the set of instances using WS-Enumeration.

The WS-Enumeration specification indicates that enumeration is a three-part operation: An initial wsen:Enumerate is issued to establish the enumeration context and wsen:Pull operations are used to iterate over the result set. When the enumeration iterator is no longer required and not yet exhausted, a wsen:Release is issued to release the enumerator and associated resources.


10

Intel AMT Release 3.0 and later releases allocate a resource which is reserved for the client during the enumeration period. The implementation imposes the following restrictions to the enumeration operation:

• The enumeration flow (enumerate, pull, release) should be completed within 30 seconds. If the enumeration flow does not complete after 30 seconds, the enumeration context may be purged for the use of other clients requesting to enumerate a resource.

• When the client pulls the last resource, the enumeration context will be purged; however, the client should issue the wsman:Release operation to complete the flow.

• Clients should not rely on the purge mechanism. Rather, they should release the enumeration context as soon as they obtain the data they need.

• Intel AMT Release 3.0 supports a maximum of three concurrent enumeration flows.

2.8. Envelope Size The WS-Management protocol defines an optional <wsman:MaxEnvelopeSize> tag in the SOAP header which specifies the client's request to limit the length of the response size. Intel AMT Release 3.0 requires that if clients specify a maximum response size limitation, then the value for the tag must be at least 50000. If a client specifies a lower value, then it might receive a corresponding WS-Management fault according to the WS-Management specification.

2.9. Key/Required Field Usage in WS-Management Operations When invoking intrinsic WS-Management operations (Get, Put, Create), the CIM object representation must include all Key/Required properties of the instance, as defined in the CIM-XML mapping standard. Similarly, any methods receiving or returning Required fields must receive or return these fields.

If a client attempts to invoke a method and fails to pass a Key or Required element, a wsman:SchemaValidationError fault will be returned. In some cases, the Intel AMT device expects certain fields, although they are not denoted as Required or Key in the MOF file. If a property which the Intel AMT device requires for an operation is not passed, an wxf:InvalidRepresentation fault will be returned on a Put or Create; other methods return a wsman:InvalidParameter fault.

2.10. Working with Intel AMT using Endpoint References (EPRs) An endpoint reference, or EPR, identifies an object based on two elements: the object type and fields that are unique in the object. The object type is contained in a resource URI which includes the class from which the object is instantiated. The unique fields are contained in a selector set. A Create or Put method returns an EPR. Creating an association requires the EPRs of the objects being associated. Performing a Get on an association returns the EPRs, which can then be used to recover the objects that the EPRs refer to.

In the following example, the actual EPR of an object is recovered, starting with the Intel AMT shortcut representation. The operation is done in three steps:

1. First, recover a EPR from Intel AMT (for example, by performing a Get on an association object.)

2. Next, perform a Get using the EPR from step 1 to retrieve the parameters of the object itself. 3. Create an EPR using those fields that are key fields for the object type. Step 1: Intel AMT returns an EPR for an instance of the class CIM_ComputerSystem:

<wsa:Address>http://10.0.0.5:16992/wsman</wsa:Address> <wsa:ReferenceParameters> <wsman:ResourceURI>http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ComputerSystem</wsman:ResourceURI>


11

<wsman:SelectorSet> <wsman:Selector Name="Name">ManagedSystem</wsman:Selector> </wsman:SelectorSet> </wsa:ReferenceParameters> Step 2: Given this representation, the client performs a Get on ResourceURI= http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ComputerSystem with the selectorset above, and gets the object representation itself:

<vxCoaa:CIM_ComputerSystem> <vxCoaa:CreationClassName>CIM_ComputerSystem</vxCoaa:CreationClassName> <vxCoaa:Dedicated>0</vxCoaa:Dedicated> <vxCoaa:ElementName> ManagedSystem</vxCoaa:ElementName> <vxCoaa:EnabledDefault>5</vxCoaa:EnabledDefault> <vxCoaa:EnabledState>2</vxCoaa:EnabledState> <vxCoaa:HealthState>5</vxCoaa:HealthState> <vxCoaa:Name>ManagedSystem</vxCoaa:Name> <vxCoaa:NameFormat>Other</vxCoaa:NameFormat> <vxCoaa:OperationalStatus>0</vxCoaa:OperationalStatus> <vxCoaa:RequestedState>12</vxCoaa:RequestedState> </vxCoaa:CIM_ComputerSystem> Step 3: Given the object representation, to retrieve its EPR use the class ResourceURI and a Selectorset. Since every CIM object is uniquely identified by the set of its key property values, create the following EPR for the above object, with the knowledge that only Name and CreationClassName are keys to CIM_ComputerSystem:

<wsa:Address> http://10.0.0.5:16992/wsman</wsa:Address> <wsa:ReferenceParameters> <wsman:ResourceURI>http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ComputerSystem</wsman:ResourceURI> <wsman:SelectorSet> <wsman:Selector Name="Name"> ManagedSystem</wsman:Selector> <wsman:Selector Name="CreationClassName">CIM_ComputerSystem</wsman:Selector> </wsman:SelectorSet> </wsa:ReferenceParameters>

The flows refer to local functions GetEPR and GetObjectFromEPR. Step 2, above, is an example of what a GetObjectFromEPR function does. Step3 is an example of what a GetEPR function does.

2.11. OptionSet Support Intel AMT does not support the WS-Management Options. If the WS-Management Header OptionSet element is passed with a MustUnderstand=true, a soap:MustUnderstand fault will be returned.

2.12. Using Create and Put with Read-Only Properties When using the Create and Put operations, according to the previously-defined rules for Key and Required properties, all Key or Required properties must be passed. Notice that not all fields of a class are writable; for example, the CreationClassName property is never writable in Intel AMT.

Properties which are read-only and are passed in the Create or Put operations will be ignored, and Intel AMT will fill its own value for them. Any schema-compliant value may be passed for these properties.


12

Specifically, this means the client must pass all keys, whether they are read-only or writable; read-only keys will be ignored, but must nevertheless be passed.

2.13. Whitespace in XML Elements Policy Intel AMT treats any information within a simple XML element tag as the tag’s value. Numeric fields may contain whitespaces; however, string and string-based elements containing any whitespace, including heading or trailing whitespaces, will be treated as though the whitespaces are part of the field’s value.

2.14. Class Namespace Usage Intel AMT implements CIM classes from two vendors:

• Classes whose name begins with CIM_ are provided by the DMTF. Intel AMT uses several versions of the DMTF’s CIM classes, but the major version number is always 2. The exact versions are documented in Intel AMT’s class reference documentation. The namespace prefix and ResourceURI prefix which should be used to access these classes is http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/. For example, CIM_ComputerSystem will belong to the namespace http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ComputerSystem, and this is also its ResourceURI.

• Classes whose names begin with AMT_ are provided by Intel Corporation. Their namespace prefix is http://intel.com/wbem/wscim/1/amt-schema/1/. So, for example, AMT_AuthorizationService will belong to the namespace http://intel.com/wbem/wscim/1/amt-schema/1/AMT_AuthorizationService, and this will also be its ResourceURI.

3. Intel AMT Permissions and Realms Intel AMT functionality is partitioned into services or interfaces. Each service can be accessed either via the remote network interface or via the local interface, or both. A user must have access to the corresponding realm in order to have permission to use the functions that are included in the service.

The Intel AMT Access Control List (ACL) manages who has access to which capabilities within the device. An ACL entry has a user ID and a list of realms to which a user has access. This access is required to use the functionality associated with a realm. A user can be granted access to one or more realms. The AddUserAclEntryEx method in the AMT_AuthorizationService class is used to assign realm permissions to users.

The first table below lists Intel AMT functional areas and the realm permission required to access that functionality. The table uses the names in the Realms enumeration in AddUserAclEntryEx. The table following it lists each realm name with the internal symbolic name used for that realm. The method descriptions in the class documentation identify which realm permissions a user must have to successfully invoke the method. Multiple realms can access a number of the methods. The documentation uses the internal names to identify the realms. Note that methods that retrieve an object or a number of objects will return only those objects that the user is permitted to see.

There is a predefined administrative user named “admin” that has access to all Intel AMT realms. The admin user can use the commands in the Security Administration interface to create additional ACL entries for additional users. The administrative user can have its parameters changed using the SetAdminAclEntryEx method. As part of the setup and configuration process, it is necessary to create the users required for an ISV application, subject to the limits on the number of available ACL entries. Note that a user with PTAdministrationRealm privileges has access to all realms.

http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/

http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ComputerSystem

http://intel.com/wbem/wscim/1/amt-schema/1/

http://intel.com/wbem/wscim/1/amt-schema/1/AMT_AuthorizationService

http://intel.com/wbem/wscim/1/amt-schema/1/AMT_AuthorizationService


13

There are two kinds of ACL entries: Kerberos and non-Kerberos. The main difference between them is that Kerberos entries have an Active Directory SID to identify a user or group of users. Non-Kerberos entries have a username and password for user identification.

Functionality to Realm Mapping

Functionality Realm Function Local Remote

Security Administration PTAdministrationRealm

Manages security control data, such as Access Control Lists, Kerberos parameters, and Transport Layer Security.

√

Power Settings PTAdministrationRealm Manages power saving options and power packages. √

Provisioning PTAdministrationRealm Performs the functions required for Intel AMT setup and configuration. √

PTAdministrationRealm

Configures local network options. These are usually configured with a DHCP server, but can be configured directly using this interface.

√

Network Administration

NetworkTimeRealm

Used to set the clock in the Intel AMT device and synchronize it to network time. Can be assigned to a separate user who has limited administrative privileges.

√

Hardware Asset HardwareAssetRealm Used to retrieve information about the hardware inventory of the platform. √

Remote Control RemoteControlRealm Enables powering a platform up or down remotely. Used in conjunction with the Redirection capability to boot remotely.

√

EventManagerRealm Allows configuring hardware and software events to generate alerts and to send them to a remote console and/or log them locally.

√

LocalUN Provides alerts to a user on the local interface. Used by User Notification Service to communicate with Intel AMT.

√

Event Manager and User Notification

EventLogReaderRealm Controls access for reading the Intel AMT event log. √ √

StorageAdminRealm Used to configure the global parameters that govern the allocation and use of non-volatile storage.

√ Storage

StorageRealm Used to access, configure, manage, write to and read from non-volatile user storage. √ √

Redirection RedirectionRealm

Enables and disables the redirection capability and retrieves the redirection log. The redirection interface itself is a separate proprietary interface. See the Redirection Library Design Guide.

√


14

Functionality Realm Function Local Remote

AgentPresenceLocal Realm

Used by an application designed to run on the local platform to report that it is running and to send heartbeats periodically.

√

Agent Presence AgentPresenceRemote Realm

Used to register Local Agent applications and to specify the behavior of Intel AMT when an application is running or stops running unexpectedly.

√

System Defense and Heuristics CircuitBreakerRealm

Used to define filters, counters, and policies to monitor incoming and outgoing network traffic and to block traffic when a suspicious condition is detected.

√

General Info GeneralInfoRealm

Returns general setting and status information. With this interface, it is possible to give a user permission to read parameters related to other interfaces without giving permission to change the parameters.

√ √

FirmwareUpdate FirmwareUpdateRealm Used only by OEMs via Intel-supplied tools to update the Intel AMT firmware. These functions are not for general ISV use.

√ −

EndpointAccessControl Realm

Returns settings associated with NAC posture. √ −

Endpoint Access Control EndpointAccessControl

AdminRealm Configures and enables the NAC posture. − √

Realm Name to Internal Name Mapping

Realm Name Internal Name

AgentPresenceLocalRealm ADMIN_SECURITY_AGENT_PRESENCE_LOCAL_REALM

AgentPresenceRemoteRealm ADMIN_SECURITY_AGENT_PRESENCE_REMOTE_REALM

CircuitBreakerRealm ADMIN_SECURITY_CIRCUIT_BREAKER_REALM

EndpointAccessControlAdminRealm ADMIN_SECURITY_EAC_ADMIN_REALM

EndpointAccessControlRealm ADMIN_SECURITY_EAC_REALM

EventLogReaderRealm ADMIN_SECURITY_EVENT_LOG_READER_REALM

EventManagerRealm ADMIN_SECURITY_EVENT_MANAGER_REALM

FirmwareUpdateRealm ADMIN_SECURITY_FW_UPDATE_REALM

GeneralInfoRealm ADMIN_SECURITY_GENERAL_INFO_REALM

HardwareAssetRealm ADMIN_SECURITY_HARDWARE_ASSET_REALM

LocalUN ADMIN_SECURITY_LOCAL_APPS_REALM

NetworkTimeRealm ADMIN_SECURITY_NETWORK_TIME_REALM


15

Realm Name Internal Name

PTAdministrationRealm ADMIN_SECURITY_ADMINISTRATION_REALM

RedirectionRealm ADMIN_SECURITY_SOLIDER_REALM

RemoteControlRealm ADMIN_SECURITY_REMOTE_CONTROL_REALM

StorageAdminRealm ADMIN_SECURITY_STORAGE_ADMIN_REALM

StorageRealm ADMIN_SECURITY_STORAGE_REALM

4. Intel AMT WS-Management Flows The following sections describe the order of doing things using WS-Management classes.

Most flows have a diagram showing the relationship of objects in the flow. The flow itself is presented in pseudo-code in the form:

[variable = ] <class name>.<action> <arguments> [selectors <selectors>]

Invocations of the WS-Management classes are shown in bold. Local functions are also bolded. They are distinguished by parentheses around parameters.

The examples in many cases have sample parameter values. See the class descriptions for definitions of the parameters for each class.

The flows refer to GetEPR and GetObjectByEPR. These are user-defined functions that implement endpoint reference handling. See Working with Intel AMT using Endpoint References (EPRs) for a description of what these functions need to do.

The instance diagrams in the flows show the relationship between classes and the association classes used to establish the relationships. The diagrams show instances from an Intel AMT device populated with objects. Many of the objects are built-in (as in the hardware asset diagram), or are added remotely using the WS-Management interface (as in the System Defense diagram).


16

4.1. EAC The following shows a typical EAC flow, performed using CIM objects. It also demonstrates how an admin user uses and manages the EAC service.

4.1.1. EAC Flow Diagram

4.1.2. EAC Flow Get the current EAC status AMT_EndpointAccessControlService service = AMT_EndpointAccessControlService.Get

Get posture - if EAC is enabled. If (service.EnabledState == true) { AMT_EndpointAccessControlService.GetPosture PostureType=0 }

Get posture-hash - if EAC is enabled. If (service.EnabledState == true) { AMT_EndpointAccessControlService.GetPostureHash PostureType=0 }

Manage the EAC service (by admin users)

Get the certificate currently used to sign postures. If a posture signing certificate was not set, the method returns a fault. AMT_EACCredentialContext context = AMT_EACCredentialContext.Get AMT_PublicKeyCertificate cert =GetObjectByEPR(context.ElementInContext)

Set a new posture signer. The posture signer cannot be set or changed while EAC is enabled. The flow disables EAC first. If (service.EnabledState == true) { AMT_EndpointAccessControlService. RequestStateChange RequestedState=3 } AMT_EACCredentialContext.Delete // if already exists

Choose a certificate (with handle number - according to its InstanceID property) to be the signer. CertificateEPR = (AMT_PublicKeyCertificate.Get selectors [InstanceID="Intel(r) AMT Certificate: Handle: #"]).GetEPR() ServiceEPR = AMT_EndpointAccessControlService.Get.GetEPR() AMT_EACCredentialContext.Create ElementProvidingContext=ServiceEPR ElementInCotnext= CertificateEPR

Enable the EAC service.


17

AMT_EndpointAccessControlService.RequestStateChange RequestedState=2

Update posture state. AMT_EndpointAccessControlService.UpdatePostureState UpdateType=0


18

4.2. Environment Detection The following shows a typical Environment Detection flow, performed using CIM objects. It demonstrates how to configure the Environment Detection settings and define a System Defense policy to be used by Environment Detection. See the Security Administration Diagram for class relationships.

4.2.1. Environment Detection Flow Configure the Environment Detection settings. AMT_EnvironmentDetectionSettingData.Put ElementName=any InstanceID=any DetectionAlgorithm=0 DetectionStrings=intel.com

Define a System Defense policy to be used by Environment Detection. AMT_EnvironmentDetectionSettingData.SetSystemDefensePolicy Policy=SystemDefensePolicyEPR


19

4.3. Event Manager The following shows a typical Event-Manager flow, performed using CIM objects. It demonstrates how to configure an event filter, subscribe for events (SNMP and SOAP), and manage the Event-Log.

4.3.1. Event Manager Diagram

CIM_ComputerSystem

AMT_EventManagerService

AMT_SNMPEventSubscriber

CIM_RecordLogAMT_EventLogEntry

AMT_SNMPEventSubscriber

AMT_PETFilterSetting

AMT_PETFilterSetting13

3

3

Association Classes1 AMT_TrapTargetForService2 CIM_LogManagesRecord3 AMT_PETFilterForTarget4 CIM_UseOfLog5 CIM_ElementSettingData 6 CIM_HostedService7 CIM_ElementCapabilities

AMT_PETFilterSetting

2 4

AMT_PETFilterSetting AMT_SOAPEventSubscriber3

1

6

5

AMT_PETCapabilities

AMT_PETCapabilities

AMT_PETCapabilities

77

7

4.3.2. Event Manager Flow Configuring event filters

Enumerate sensor attributes. AMT_PetCapabilities.Enumerate AMT_PetCapabilities[] SensorsAttributes = AMT_PetCapabilities.Pull

Enumerate all filters, to check if there is a free entry for the new filter. AMT_PetFilterSetting.Enumerate AMT_PetFilterSetting[] Filters = AMT_PetFilterSetting.Pull

Remove an event filter, if there isn’t a free entry for the new filter. AMT_PetFilterSetting.Delete selectors InstanceID=Filters[0].InstanceID

Add a new event filter using SensorsAttributes. AMT_PetFilterSetting.Create ElementName=any InstanceID=any


20

EnableFilter=true OEMFilter=false LogOnEvent=true DeviceAddress=SensorsAttributes[0].DeviceAddress EventSensorType=SensorsAttributes[0].EventSensorType EventType=SensorsAttributes[0].EventType EventOffset=SensorsAttributes[0].EventOffset EventSourceType=SensorsAttributes[0].EventSourceType EventSeverity=SensorsAttributes[0].EventSeverity SensorNumber=SensorsAttributes[0].SensorNumber Entity=SensorsAttributes[0].Entity EntityInstance=SensorsAttributes[0].EntityInstance PolicyID=6 SendAlert=true

Subscribing to alerts

Get the current SNMP alert community string. AMT_EventManagerService service = AMT_EventManagerService.Get // Examine service.DefaultCommunityString

Set the SNMP alert community string. AMT_EventManagerService.Put DefaultCommunityString=newCommunityString

Subscribe to receive SNMP event. AMT_SNMPEventSubscriber.Create SystemCreationClassName=any SystemName=any CreationClassName=any Name=any PolicyID=9 CommunityString=myPrivateCommunityString AccessInfo=10.0.0.5

Subscribe to receive SOAP event –used only on the local interface for local user notifications. AMT_SOAPEventSubscriber.Create SystemCreationClassName=any SystemName=any CreationClassName=any Name=any PolicyID=134 AccessInfo= http://localhost:some_port UserName=admin Password=adminPass AlertAuthenticationOptions=2

Event-Log management

Get event-log status. CIM_RecordLog log = CIM_RecordLog.Get // Examine log.CurrentNumberOfRecords, log.MaxNumberOfRecords , // log.EnabledState

Enable the event-log. CIM_RecordLog.RequestStateChange RequestedState=2

Read the event-log entries.


21

AMT_EventLogEntry.Enumerate AMT_EventLogEntry[] LogEntries = AMT_EventLogEntry.Pull

Clear the event-log entries. CIM_RecordLog.ClearLog


22

4.4. General Info The following shows a typical General Info flow, performed using CIM objects. It shows the sequences used to retrieve some of the parameters available via General Info.

4.4.1. General Info Diagram

CIM_RemotePort

AMT_GeneralSettings

AMT_CryptographicCapabilities

Association Classes1 CIM_HostedAccessPoint2 CIM_HostedService3 CIM_InstalledSoftwareIdentity4 CIM_ElementSettingData5 CIM_ElementCapabilities6 CIM_RemoteAccessAvailableToElement7 CIM_ElementSoftwareIdentity8 CIM_SystemBIOS9 CIM_ServiceAvailableToElement10 CIM_SystemDevice

AMT_EthernetPortSettings

CIM_ComputerSystem

AMT_TLSSettingData

AMT_TLSSettingData AMT_TLSProtocolEndpoint

AMT_TLSProtocolEndpoint

CIM_SoftwareIdentity











AMT_RedirectionService

AMT_WebUIService

AMT_AuthorizationService

CIM_SoftwareInstallationService

AMT_SetupAndConfigurationService

2

11

4

4

410

6

5

3 7

CIM_BIOSElement CIM_ComputerSystem8

CIM_EthernetPort4

(Managed system)

(Intel AMT)

9

4.4.2. General Info Flow Get the Core and FW versions. CIM_SoftwareIdentity.Enumerate CIM_SoftwareIdentity[] ids = CIM_SoftwareIdentity.Pull // Examine ids.InstanceID, ids.VersionString

Get the BIOS version. CIM_BIOSElement be = CIM_BIOSElement.Get // Examine be.Version

Get provisioning parameters and password model. AMT_SetupAndConfigurationService s = AMT_SetupAndConfigurationService.Get // Examine s.ProvisioningMode, s.ProvisioningState, s.PasswordModel CIM_RemotePort rp = CIM_RemotePort.Get // Examine rp.AccessInfo, rp.PortInfo

Get network parameters. AMT_GeneralSettings gs = AMT_GeneralSettings.Get // Examine gs.NetworkInterfaceEnabled, gs.HostName


23

AMT_EthernetPortSettings.Enumerate AMT_EthernetPortSettings[] portSettings = AMT_EthernetPortSettings.Pull Foreach currInterface in portSettings { // Examine currInterface.VlanTag, currInterface.LinkIsUp }

Get enabled interfaces. AMT_WebUIService WebS = AMT_WebUIService.Get // Examine WebS.EnabledState AMT_RedirectionService RedS = AMT_RedirectionService.Get // Examine RedS.EnabledState

Get IDER session log. String[] rLogAccesses = RedS.AccessLog

Get SecurityParameters. AMT_CryptographicCapabilities cc = AMT_CryptographicCapabilities.Get // Examine cc.HardwareAcceleration CIM_SoftwareInstallationService sis = CIM_SoftwareInstallationService.Get // Examine sis.EnabledState

Get ACL entries. AMT_AuthorizationService.GetAdminAclEntryStatus AMT_AuthorizationService.GetAdminNetAclEntryStatus


24

4.5. Firmware Update The following shows the flow required to retrieve the status of a firmware update operation using CIM objects.

4.5.1. Firmware Update Diagram CIM_ComputerSystem

CIM_SoftwareInstallationService

Association Classes1 CIM_ServiceAvailableToElement2 CIM_HostedService3 CIM_OwningJobElement

1

CIM_ConcreteJob3

2

4.5.2. Firmware Update Flow Get firmware update state. CIM_ConcreteJob.Get


25

4.6. Hardware Asset The following shows how to access Hardware Asset information, using CIM objects.

4.6.1. Hardware Asset Diagram

CIM_PhysicalMemory

Association Classes1 CIM_SystemComponent2 CIM_Realizes3 CIM_ComputerSystemPackage4 CIM_BIOSFeatureBIOSElements5 CIM_SystemDevice6 CIM_SystemBIOS

CIM_ComputerSystem

CIM_BIOSElement

CIM_Processor

CIM_SensorCIM_Chip

CIM_Card

CIM_Chassis

CIM_PhysicalMemory

CIM_PhysicalMemory

CIM_PhysicalMemoryCIM_Memory

CIM_ComputerSystem

CIM_Sensor

CIM_AdminDomain

CIM_MediaAccessDevice

CIM_BIOSFeature

CIM_PhysicalPackage

52

5

1

1

4

2

52

3

1

6

1

CIM_PowerSupply

CIM_Fan

(Managed system)

(Intel AMT)

AMT_PCIDevice

4.6.2. Hardware Asset Flow Read motherboard information. CIM_Card.Enumerate CIM_Card.Pull

Read chassis information. CIM_ComputerSystemPackage.Enumerate CIM_ComputerSystemPackage[] Results = CIM_ComputerSystemPackage.Pull Foreach csp in Results { // The following request returns the CIM_Chassis connected by this // association to the computer system. CIM_Chassis chassis = GetObjectByEPR(csp.Antecedent) }

Read cooling device information. CIM_Fan.Enumerate CIM_Fan.Pull

Read power supply information. CIM_PowerSupply.Enumerate CIM_PowerSupply.Pull


26

Read Media table information. CIM_Realizes.Enumerate CIM_Realizes[] RealizesRelations = CIM_Realizes.Pull Foreach realizes in RealizesRelations { If (realizes.Dependent.isOfType(CIM_MediaAccessDevice)) { CIM_PhysicalPackage fp = GetObjectByEPR(realizes.Antecedent) CIM_MediaAccessDevice mad = GetObjectByEPR(realizes.Dependent) } }

Read PCI device information. AMT_PCIDevice.Enumerate AMT_PCIDevice.Pull

Read BIOS information. CIM_SystemBIOS.Enumerate CIM_SystemBIOS[] Results = CIM_SystemBIOS.Pull Foreach SystemBios in Results { // The following gets the BiosElement connected by this association // to the computer system BiosElement be = GetObjectByEPR(SystemBios.PartComponent) // The following gets the BiosFeatures associated with the current // system BIOS Enumerate CIM_BIOSFeatureBIOSElement selectors GroupComponent=be.getEPR() CIM_BIOSFeatureBIOSElement[] BIOSFeatureBIOSElements = CIM_BIOSFeatureBIOSElement.Pull Foreach fe in BIOSFeatureBIOSElements { BiosFeature bf = GetObjectByEPR(fe.GroupComponent) } }

Read processor information. CIM_Realizes.Enumerate CIM_Realizes[] RealizesRelations = CIM_Realizes.Pull Foreach realizes in RealizesRelations { If (realizes.Dependent.isOfType(CIM_Processor)) { // Get the Processor and Chip which are connected by the // Realizes association CIM_Processor processor = GetObjectByEPR(realizes.Dependent) CIM_Chip chip = GetObjectByEPR(realizes.Antecedent) // Get the location of the processor CIM_PhysicalElementLocation locationAssociation = CIM_PhysicalElementLocation.Get selectors Element=chip.getEPR() CIM_Location location = GetObjectByEPR(locationAssociation.PhysicalLocation)


27

} }

Read memory information. CIM_Memory.Get CIM_PhysicalMemory.Enumerate CIM_PhysicalMemory.Pull


28

4.7. Network Time The following shows a Network Time flow, performed using CIM objects. It demonstrates how to configure the Intel AMT device time using AMT_TimeSynchronizationService.

4.7.1. Network Time Drawing

4.7.2. Network Time Flow Get the local time of the Intel AMT device. uint32 Ta0Result = AMT_TimeSynchronizationService.GetLowAccuracyTimeSynch

Set new time. AMT_TimeSynchronizationService.SetHighAccuracyTimeSynch Ta0=Ta0Result Tm1=10987663 Tm2=10987665


29

4.8. Power Packages The following shows a typical Power Packages flow, performed using CIM objects. It demonstrates how to retrieve the active power package, select a new package, and set the IdleWakeTimeout setting.

4.8.1. Power Scheme Diagram

4.8.2. Power Package Flow Get active power package. CIM_ElementSettingData.Enumerate CIM_ElementSettingData[] ESD = CIM_ElementSettingData.Pull for each es in ESD { If (es.SettingData.isOfType(AMT_SystemPowerScheme)) { AMT_SystemPowerScheme powerScheme = getObjectByEPR(es.SettingData) if (powerScheme.IsCurrent=1) { // this package is active } } }

Enumerate all packages and get their descriptors. AMT_SystemPowerScheme.Enumerate AMT_SystemPowerScheme[] Packages = AMT_SystemPowerScheme.Pull

Choose one of the packages. AMT_SystemPowerScheme.SetPowerScheme SchemeGUID=Packages[0].SchemeGUID InstanceID=Packages[0].InstanceID

Get the current IdleWakeTimeout setting


30

AMT_GeneralSettings generalSettings = AMT_GeneralSettings.Get // Examine generalSettings.IdleWakeTimeout

Use the old parameters and change only the IdleWakeTimeout parameter generalSettings.IdleWakeTimeout = generalSettings.IdleWakeTimeout+10 AMT_GeneralSettings.Put generalSettings


31

4.9. Redirection Administration The following shows a typical Redirection administration flow, performed using CIM objects. It demonstrates enabling the redirection service and the listener and reading the IDER session log.

4.9.1. Redirection Diagram

4.9.2. Redirection Administration Flow Enable the Redirection Services (by administration users). AMT_RedirectionService.RequestStateChange RequestedState=32771

Get the current Listener state. AMT_RedirectionService rs = AMT_RedirectionService.Get

Enable the Listener state. rs.ListenerEnabled=true AMT_RedirectionService.Put rs

Get the IDER session log. //Examine rs.AccessLog


32

4.10. Security Administration The following shows a typical Security Administration flow, performed using CIM objects. It demonstrates how to manage the Certificate Store (managing keys and certificates), and setting TLS and Kerberos configurations, as well as other parameters that are part of this component.

4.10.1. Security Administration Diagram

4.10.2. Security Administration Flow Manage the Certificate-Store

Get PKI capabilities. AMT_PublicKeyManagementCapabilities pkmc = AMT_PublicKeyManagementCapabilities.Get //Examine pkmc.MaximumCRLSize // pkmc.RootCertMaxSize // pkmc.RootCertMaxCount // pkmc.CommonNameMaxSize // pkmc.CommonNameMaxCount // pkmc.CertChainMaxSize // pkmc.SupportedKeyLengths[]

Enumerate all current keys. AMT_PublicPrivateKeyPair.Enumerate AMT_PublicPrivateKeyPair[] pairs AMT_PublicPrivateKeyPair.Pull

Add a new key. KeyEPR = AMT_PublicKeyManagementService.AddKey KeyBlob

Enumerate all certificates. AMT_PublicKeyCertificate.Enumerate AMT_PublicKeyCertificate[] certs AMT_PublicKeyCertificate.Pull

Add a new certificate.


33

CertificateEPR = AMT_PublicKeyManagementService.AddCertificate CertificateBlob

Get a PKCS#10 Request. // Use CertificateEPR defined when certificate was added CertificateRequest = AMT_PublicKeyManagementService.GeneratePKCS10Request KeyPair=CertificateEPR //DNName and Usage are optional

Set CRLs. EPRofCRL = AMT_PublicKeyManagementService.AddCRL Url= http://www.intel.com/repository/CRL/Intel%20Corporation%20Basic%20Enterprise%20Issuing%20CA%201.crl SerialNumbers[]= 667b8e10000000004ac5 Set TLS and Kerberos configurations

Set Kerberos settings. AMT_KerberosSettingData.Put InstanceID=any RealmName=EnterpriseDomain ServicePrincipalName= ServicePrincipalProtocol= KeyVersion = EncryptionAlgorithm = MasterKey = MaximumClockTolerance = 5 KrbEnabled = true

Set TLS status and options (including setting of trusted FQDN CNs) for 802.3 and LMS. AMT_TLSSettingData.Put InstanceID=<any> MutualAuthentication Enabled[] TrustedCN [InstanceID=<Intel(r) AMT 802.3 TLS Settings / Intel(r) AMT LMS TLS Settings>]

Get current TLS credentials – if there are no current credentials, the method returns a fault. AMT_TLSCredentialContext context = AMT_TLSCredentialContext.Get getObjectByEPR (context.ElementInContext)

Set new TLS credentials. AMT_TLSCredentialContext.Delete // if credentials already exist TLSProtocolsEPR = AMT_TLSProtocolEndpointCollection.Get.GetEPR CertificateEPR = AMT_PublicKeyCertificate.Get [InstanceID="Intel(r) AMT Certificate: Handle: #"].GetEPR AMT_TLSCredentialContext.Create ElementProvidingContext= TLSProtocolsEPR ElementInContext=CertificateEPR

Complete acceptance of the changes by invoking “commit changes”. AMT_SetupAndConfigurationService.CommitChanges


34

Administration functionality

Enable WebUI, SOL and IDER services. AMT_WebUIService.RequestStateChange RequestedState=2 AMT_RedirectionService.RequestStateChange RequestState=32771

Get core version. CIM_SoftwareIdentity id = CIM_SoftwareIdentity.Get //examine id.VersionString

Reset the Flash Wear-Out protection. AMT_SetupAndConfigurationService.ResetFlashWearOutProtection


35

4.11. Authorization Service The following shows a typical authorization flow, performed using CIM objects. It demonstrates adding a new user to Intel AMT device, modifying the user entry and removing the user. All the authorization operations are executed using AMT_AuthorizationService methods.

4.11.1. Authorization Service Flow Create new user. uint32 userHandle = AMT_AuthorizationService.AddUserAclEntryEx DigestUsername=user1 DigestPassword=UGFzc3dvcmQhMTIz AccessPermission=2 Realms=6,8

Get the user details. AMT_AuthorizationService UserInfo = AMT_AuthorizationService.GetUserAclEntryEx Handle=userHandle

Modify the user entry. AMT_AuthorizationService.UpdateUserAclEntryEx Handle = userHandle DigestUsername=newUsername DigestPassword=UGFzc3dvcmQhMTIz AccessPermission=2 Realms=4,5

Remove the user. AMT_AuthorizationService.RemoveUserAclEntry Handle=userHandle


36

4.12. Agent Presence The following shows a typical Agent Presence flow, performed using CIM objects. It demonstrates creating an agent, adding a new action to the agent, removing actions from the agent, and defining a System Defense policy to be used by Agent Presence.

4.12.1. Agent Presence Diagram

CIM_ComputerSystem

AMT_AgentPresenceService

CIM_EthernetPort

AMT_AgentPresenceCapabilities

AMT_AgentPresenceWatchdog

AMT_StateTransitionConditionAMT_StateTransitionConditionAMT_StateTransitionCondition

AMT_AgentPresenceWatchdogAction AMT_AgentPresenceWatchdogAction AMT_AgentPresenceWatchdogAction

AMT_SystemDefensePolicy1

3 4

2 2 2

2 2

Association Classes1 AMT_AgentPresenceInterfacePolicy2 CIM_ConcreteDependency3 CIM_ElementCapabilities4 CIM_HostedService

2

2

4.12.2. Agent Presence Flow Create an agent. AgentEPR = AMT_AgentPresenceWatchdog.Create ElementName=any SystemCreationClassName=any CreationClassName=any StartupInterval=120 MonitoredEntityDescription=sampleAgent DeviceID=MTExMTExMTExMTExMTExMQ== TimeoutInterval=60

Get the created object. AMT_AgentPresenceWatchdog agent = GetObjectByEPR(AgentEPR)

Add an action that will be triggered on a state transition of the agent. //Assumes no selector is required since only one watchdog was created AMT_AgentPresenceWatchdog.AddAction OldState=2 NewState=4 EventOnTransition=true


37

ActionSd=0

Enumerate the agent’s state transitions and actions – only the instances associated with the relevant agent belong to this agent. //1. Enumerate all the associations that associate this agent with its state transitions. CIM_ConcreteDependency.Enumerate selectors Antecedent=AgentEPR CIM_ConcreteDependency[] Associations = CIM_ConcreteDependency.Pull Foreach dep in Associations { // 2. Get the state transition instance StateTransitionEPR = dep.Dependent AMT_StateTransitionCondition st = GetObjectByEPR(StateTransitionEPR) // 3. Get the association of the state transition to the action CIM_ConcreteDependency.Enumerate selectors Antecedent=StateTransitionEPR ActionEPR = CIM_ConcreteDependency.Pull.Dependent AMT_AgentPresenceWatchdogAction action = GetObjectByEPR(ActionEPR) }

Delete all the state transition and action instances associated with the agent. AMT_AgentPresenceWatchdog.DeleteAllActions

Define a System Defense policy for the Agent Presence watchdog by creating an association class between the relevant policy and the relevant network interface. AMT_AgentPresenceInterfacePolicy.Create Dependent=SystemDefensePolicyEPR Antecedent=<wsa:Address>default</wsa:Address> <wsa:ReferenceParameters> <wsman:ResourceURI> http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_EthernetPort </wsman:ResourceURI> <wsman:SelectorSet> <wsman:Selector Name="DeviceID">Intel(r) AMT Ethernet Port 0</wsman:Selector> </wsman:SelectorSet> </wsa:ReferenceParameters>


38

4.13. 802.1x Configuration The following shows a typical 802.1x flow, performed using CIM objects. It demonstrates defining and activating an 802.1x profile; retrieving the profile parameters, including the credential context; changing the profile; and disabling the profile.

4.13.1. 802.1x Configuration Diagram

4.13.2. 802.1x Configuration flow Get the single instance of an 802.1x wired profile. AMT_8021XProfile profile = AMT_801XProfile.Get selectors InstanceID=Intel(r) AMT 802.1x Profile 0

Configure and activate the profile. AMT_8021XProfile.Put profile ElementName=any InstanceID=any Enabled=true AuthenticationProtocol=0 ServerCertificateName = server1 ServerCertificateNameComparison=0 Username=user1 ClientCertificate=ClientCertificateEPR ServerCertificateIssuer=RootCertificateEPR ActiveInS0 = true

Get the parameters of the active profile. profile.Get

Get the credential context (client and root certificates) used by the active profile. AMT_8021xCredentialContext.Enumerate AMT_8021xCredentialContext context = AMT_8021xCredentialContext.Pull CertEPR = context.ElementInContext AMT_PublicKeyCertificate Certificate = GetObjectByEPR(CertEPR) if ( Certificate.TrustedRootCertificate ) { RootCertificate = Certificate } Else {


39

ClientCertificate = Certificate }

Configure and enable a new profile. profile.Put ElementName=any InstanceID=any Enabled=true AuthenticationProtocol=3 Username=user2 Password=pass123 ActiveInS0 = true

Remove the profile (disable 802.1x) profile.Put ElementName=any InstanceID=any Enabled=false


40

4.14. System Defense The following shows a typical System Defense flow, performed using CIM objects. It demonstrates creating filters, creating a policy aggregating those filters, enabling the policy on a network interface, and updating and retrieving the filter statistics.

4.14.1. System Defense Diagram

4.14.2. System Defense Flow Create an Ethernet filter. EthFilterEPR = AMT_Hdr8021Filter.Create Name=EthFilter FilterDirection=0 ElementName=any SystemCreationClassName=any CreationClassName=any HdrProtocolID8021=3 SystemName=any InstanceID=3 FilterProfile=3 ActionEventOnMatch=0

Get the created object and record its creation handle. AMT_Hdr8021Filter EthFilter = GetObjectByEPR(EthFilterEPR)

Create a TCP filter with IPv6 address. TCPFilterEPR = AMT_IPHeadersFilter.Create CreationClassName=any SystemName=any SystemCreationClassName=any


41

InstanceID=2 FilterProfile=3 ElementName=any HdrIPVersion=6 FilterDirection=0 Name=TCPFilter ActionEventOnMatch=0 HdrDestAddress=00000000000000000000000000000011 HdrDestMask=00000000000000000000000000000000

Get the created object and record its creation handle. AMT_IPHeadersFilter IPFilter = GetObjectByEPR(TCPFilterEPR)

Create a policy, using the filter creation handles recorded above. PolicyEPR = AMT_SystemDefensePolicy.Create RxDefaultMatchEvent=0 ElementName=policy1 TxDefaultDrop=0 RxDefaultDrop=0 AntiSpoofingSupport=1 TxDefaultCount=0 PolicyName=policy1 TxDefaultMatchEvent=0 InstanceID=1 RxDefaultCount=0 PolicyPrecedence=3 FilterCreationHandles=<array of the “handle” property of created filters>

Enable the policy by creating an association class, and associating the policy with the relevant network interface. AMT_NetworkPortSystemDefensePolicy.Create Dependent=PolicyEPR Antecedent=<wsa:Address>default</wsa:Address> <wsa:ReferenceParameters> <wsman:ResourceURI> http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_EthernetPort </wsman:ResourceURI> <wsman:SelectorSet> <wsman:Selector Name="DeviceID">Intel(r) AMT Ethernet Port 0</wsman:Selector> </wsman:SelectorSet> </wsa:ReferenceParameters>

Assign a default policy in the same manner by creating an association class, and associating the policy with the relevant network interface. AMT_NetworkPortDefaultSystemDefensePolicy.Create Dependent=PolicyEPR Antecedent=<wsa:Address>default</wsa:Address> <wsa:ReferenceParameters> <wsman:ResourceURI> http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_EthernetPort </wsman:ResourceURI> <wsman:SelectorSet> <wsman:Selector Name="DeviceID">Intel(r) AMT Ethernet Port 0</wsman:Selector> </wsman:SelectorSet>


42

</wsa:ReferenceParameters>

Update and reset the filter statistics. AMT_SystemDefensePolicy.UpdateStatistics ResetOnRead=1 Interface=<wsa:Address>default</wsa:Address> <wsa:ReferenceParameters> <wsman:ResourceURI> http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_EthernetPort </wsman:ResourceURI> <wsman:SelectorSet> <wsman:Selector Name="DeviceID">Intel(r) AMT Ethernet Port 0</wsman:Selector> </wsman:SelectorSet> </wsa:ReferenceParameters>

Read all filter statistics, and examine the relevant entries. AMT_ActiveFilterStatistics.Enumerate AMT_ActiveFilterStatistics.Pull


43

4.15. Heuristic System Defense The following shows a typical Heuristic System Defense flow, performed using CIM objects. It demonstrates how to configure and enable the Heuristics System Defense feature on a wired LAN network interface, how to configure the policy that will be enabled should a worm threat be detected, and how to read the current Heuristic System Defense state.

4.15.1. Heuristic System Defense Flow Step 1: Get the AMT_HeuristicPacketFilterSettings instance that is associated with the wired LAN network interface.

Enumerate the CIM_ElementSettingData and find the instances that associate between the instance of CIM_EthernetPort that represents the wired LAN interface and an instance of AMT_HeuristicPacketFilterSettings

“hpf” will hold the heuristic settings associated with the wired LAN network interface. AMT_HeuristicPacketFilter hpf CIM_ElementSettingData.Enumerate CIM_ElementSettingData[] ElementSettingDataRelations= CIM_ElementSettingData.Pull Foreach relation in ElementSettingDataRelations { If (relation.ManagedElement.isOfType(CIM_EthernetPort) AND

relation.SettingData.isOfType(AMT_HeuristicPacketFilter) { CIM_EthernetPort network =

GetObjectByEPR(relation.ManagedElement) If(network.Description == CONST_WIRED_LAN_IDENTIFIER_STRING) { hpf = GetObjectByEPR(relation.SettingData) break } } }

Step 2: Set the desired Heuristic System Defense settings. In the example shown here the default policy “block all transmit packets” will be activated if a worm threat is detected. AMT_HeuristicPacketFilterSettings.put ElementName=hpf.ElementName Caption=hpf.Caption Description=hpf.Description; InstanceID=hpf.InstanceID Enabled=true BlockAll=true BlockOffensivePort=true FastConnectionRateThreshold=150 FastConnectionRateClearTime=500 SlowConnectionRateThreshold=200 SlowConnectionRateClearTime=10000 EncounterTimeout=20 SELECTORS hpf.GetSelectorSet()

Step 3: (optional) A user may choose to define a specific System Defense policy to be enabled if a worm threat is detected. Should this policy have the highest priority of all of the enabled System Defense policies, it will be activated on the wired LAN interface. To use this option, the default


44

“block all” policy should be set to false in Step 2. If it is set to true, then all Tx traffic will be blocked. Setting “block all” to false allows the System Defense policy to selectively filter Tx packets. To learn how to create a System Defense policy, see the System Defense section. Once a System Defense Policy EPR is created, it is associated with the wired LAN network interface using an AMT_HeuristicPacketFilterInterfacePolicy association object.

“policyEPR” will contain the EPR of a policy defined in AMT_SystemDefensePolicy. PolicyEPR policyEPR

“interfaceEPR” will contain the EPR of the wired LAN CIM_EthernetPort. This can be saved during the enumeration performed in Step 2, or retrieved by enumerating over the instances of CIM_EthernetPort as demonstrated in the NetworkAdministration section and creating an EPR from the instance representing the wired LAN interface. EthernetPortEPR interfaceEPR AMT_HeuristicPacketFilterInterfacePolicy.create Dependent= policyEPR Antecedent=interfaceEPR

Step 4: Get the current state of the Heuristic System Defense settings associated with the wired LAN interface.

Enumerate the CIM_ElementStatisticalData and find the instances that associate between the instance of CIM_EthernetPort that represents the wired LAN interface and an instance of AMT_HeuristicPacketFilterStatistics.

“hpfs” will hold the heuristic statistics associated with the wired LAN network interface. AMT_HeuristicPacketFilterStatistics hpfs CIM_ElementStatisticalData.Enumerate CIM_ElementStatisticalData[] ElementStatisticalDataRelations= CIM_ ElementStatisticalData.Pull Foreach relation in ElementStatisticalDataRelations { If relation.ManagedElement.isOfType(CIM_EthernetPort) AND relation.Stats.isOfType(AMT_HeuristicPacketFilterStatistics) { CIM_EthernetPort network =

GetObjectByEPR(relation.ManagedElement) If(network.Description == CONST_WIRED_LAN_IDENTIFIER_STRING) { hpfs = GetObjectByEPR(relation.SettingData) break } } }

Step 5: Clear the Heuristic System Defense state. AMT_HeuristicPacketFilterStatistics.ResetSelectedStats SelectedStatistics={ALL} SELECTORS hpfs.GetSelectorSet()

Step 6: Disable the Heuristic System Defense feature on the wired LAN interface. AMT_HeuristicPacketFilterSettings.put ElementName=hpf.ElementName Caption=hpf.Caption Description=hpf.Description; InstanceID=hpf.InstanceID Enabled=false BlockAll=false


45

FastConnectionRateThreshold=150 FastConnectionRateClearTime=500 SlowConnectionRateThreshold=200 SlowConnectionRateClearTime=10000 EncounterTimeout=20 SELECTORS hpf.GetSelectorSet()


46

4.16. Setup and Configuration (Provisioning) The following flow demonstrates how to configure an Intel AMT device using the Setup and Configuration Service CIM object. Most of the operations performed are already described in other sections of this document. The example also demonstrates additional functions of the Setup and Configuration Service CIM object.

4.16.1. Setup and Configuration Diagram

4.16.2. Setup and Configuration Flow Preparation for Setup and Configuration

Before beginning configuration, several preparation steps may be necessary:

Invoke the Extend Provisioning Period method to prevent the possibility that the network interface will be closed during the provisioning process. AMT_SetupAndConfigurationService.ExtendProvisioningPeriod Duration=24

In the case of PKI-CH (“Remote Configuration”) setup and configuration, the following additional calls may be required:

Verify the Provisioning Server One Time Password (OTP) of the Intel AMT device: If (ProvisioningServerOTP == AMT_SetupAndConfigurationService.Get.ProvisioningServerOTP) { // Continue } Else { // Halt the provisioning process and return an error }

Modify the MEBx password: The default password must be changed for configuration to succeed. If the default password was already modified, the method will return an error. AMT_SetupAndConfigurationService.SetMEBxPassword password=Admin!123

Perform Setup and Configuration

Step 1: Get the Core Version of the Intel AMT device. This should be called early in the setup and configuration process since the set of setup and configuration functions may change from version to version. To get the core version, one must enumerate the instances of CIM_SoftwareIdentity and search for the instance with “InstanceID” set to “AMT FW Core Version”. String version // will hold the version string CIM_SoftwareIdentity.Enumerate CIM_SoftwareIdentity[] ids= CIM_SoftwareIdentity.Pull Foreach id in ids { If(id.InstanceID == AMT_VERSION_ID_STRING) {


47

version=id.VersionString break } }

Step 2: Set the network settings of the Intel AMT device (these operations are described in the Network Administration section):

• Choose between DHCP and static IP. • Choose between WS-Management only mode and simultaneous mode. • Enable or disable ping response. • Set the FQDN (host name and domain name). This is mandatory for TLS and Kerberos.

Step 3: Set the Public Key Infrastructure (These operations are described in the Security Administration section):

• Create a certificate store. • Define the trusted root certificates. • Define the CRL.

Step 4: To set the TLS and Kerberos settings see the Security Administration section.

Step 5: To enable the WebUI, SOL and IDER interfaces, see the Security Administration section.

Step 6: To Enable EAC see the EAC section

Step 7: To configure the network time see the Network Time section.

Step 8: To configure the 802.1x wired profile see the 802.1x configuration section

Step 9: To add ACL users, see the Authorization Service section.

Step 10: To configure the power settings see the Power Packages section

Step 11: To reset the flash wear-out protection: AMT_SetupAndConfigurationService.ResetFlashWearOutProtection

Step 12: Change the admin network password – the password must have been changed from its default value (“admin”) for configuration to succeed. Note: the password will be changed immediately; therefore, the new password must be used on all subsequent calls. String newPassword = P@ssw0rd AutorizationService.SetAdminAclEntryEx Username=admin DigestPassword=MD5Hash(admin|(AMT_GeneralSettings.Get).DigestRealm| newPassword)

Step 13: Change the PSK pair for future PSK configuration: AMT_SetupAndConfigurationService.SetTlsPsk PID=AAAAAAAN PPS=AAAFAAAFAAAFAAAFAAAFAAAFAAAFAAAF

Step 14: Complete the provisioning process by invoking “commit changes”: AMT_SetupAndConfigurationService.CommitChanges

To get an audit record of the most recent provisioning process: GetProvisioningAuditRecord AuditRecord = AMT_SetupAndConfigurationService.GetProvisioningAuditRecord //Examine the fields within the record

To unprovision an AMT machine:

For full unprovisioning


48

AMT_SetupAndConfigurationService.Unprovision ProvisioningMode=ENTERPRISE

For partial unprovisioning AMT_SetupAndConfigurationService.PartialUnprovision


49

4.17. Network Administration This section demonstrates how to manipulate some of the Network Administration settings using CIM objects. The Network Administration changes that are made in this manner are applied immediately: It is not necessary to invoke the CommitChanges function for the changes to take effect.

4.17.1. Network Administration Diagram

4.17.2. Network Administration Flow Step 1: Enumerate the AMT_EthernetPortSettings and find the instance that represents the wired LAN network interface: AMT_EthernetPortSettings wiredLANInterface AMT_EthernetPortSettings.Enumerate AMT_EthernetPortSettings EthernetPortSettings = AMT_EthernetPortSettings.Pull Foreach instance in EthernetPortSettings { // find the instance we want, using one of its known properties If (instance.InstanceID == ”Intel(r) AMT Ethernet Port Settings 0”) { wiredLANInterface = instance break } }

It is also possible to enumerate CIM_EthernetPort instances and find the wired LAN network interface, whose “Description” property equals “Wired0”, and then find the AMT_EthernetPortSettings instance that is connected to it.

Step 2: Set the wired LAN interface to work in DHCP mode. Note: Once this function is called, future messages to the Intel AMT device will need to be sent to the new IP address. AMT_EthernetPortSettings.put ElementName= wiredLANInterface.ElementName InstanceID= wiredLANInterface.InstanceID SharedMAC=true LinkPolicy[]= wiredLANInterface.LinkPolicy[] DHCPEnabled=true


50

SELECTORS wiredLANInterface.GetSelectorSet()

Step 2: (alternate) Set the wired LAN interface to work in static IP mode. Note: Once this function is called, future messages to the Intel AMT device will need to be sent to the new IP address. AMT_NetworkInterfaceSettings.put ElementName= wiredLANInterface.ElementName Caption= wiredLANInterface.Caption InstanceID= wiredLANInterface.InstanceID Description= wiredLANInterface.Description SharedMAC= true LinkPolicy= wiredLANInterface.LinkPolicy DHCPEnabled=false IPAddress=10.0.0.2 SubnetMask=255.255.255.0 DefaultGateway=0.0.0.0 PrimaryDNS=0.0.0.0 SecondaryDNS=0.0.0.0 SELECTORS wiredLANInterface.GetSelectorSet()

Step 3: Set the host and domain names, enable ping response and set the WsmanOnly mode to simultaneous mode. AMT_GeneralSettings generalSettings = AMT_GeneralSettings.Get AMT_GeneralSettings.Put InstanceID=generalSettings.InstanceID HostName=NewHostName PingResponseEnabled=true DomainName=NewDomainName WsmanOnlyMode=false SELECTORS generalSettings.GetSelectorSet()


51

4.18. Storage Administration The following shows a typical Storage Administration flow performed using the AMT_ThirdPartyDataStorageAdministrationService CIM object. The flow manages global storage attributes, the attributes of storage applications, and enterprise and partner ACL entries.

4.18.1. Storage and Storage Administration Diagram

4.18.2. Storage Administration Flow Get the GlobalStorageAttributes. AMT_ThirdPartyDataStorageAdministrationService.GetGlobalStorageAttributes

Set the GlobalStorageAttributes – update the max non-partner storage space to 4096. AMT_ThirdPartyDataStorageAdministrationService.SetGlobalStorageAttributes MaxNonPartnerTotalAllocationSize=4096

Enumerate the registered applications and get their attributes. AdminGetRegisteredApplications_OUTPUT response = AMT_ThirdPartyDataStorageAdministrationService.AdminGetRegisteredApplications Foreach applicationHandle in response.ApplicationHandles { AMT_ThirdPartyDataStorageAdministrationService.

AdminGetApplicationAttributes Handle=applicationHandle }

Add “Intel” to the list of Enterprise entries. AMT_ThirdPartyDataStorageAdministrationService.AddStorageEaclEntry EnterpriseName=Intel

Enumerate the list of enterprise handles. For each enterprise handle, get the associated enterprise.


52

EnumerateStorageEaclEntries_OUTPUT response = AMT_ThirdPartyDataStorageAdministrationService.EnumerateStorageEaclEntries Foreach enterpriseHandle in response.Handles { AMT_ThirdPartyDataStorageAdministrationService.

GetStorageEaclEntry Handle=enterpriseHandle }

Add “SampleApp” to the list of partner applications. AMT_ThirdPartyDataStorageAdministrationService.AddStorageFpaclEntry ApplicationName=SampleApp VendorName=Intel AttrType=1 IsPartner=true TotalAllocationSize=4096

Enumerate the list of allocation entry handles. For each allocation entry handle, get the associated allocation entry. EnumerateStorageAllocEntries_OUTPUT response = AMT_ThirdPartyDataStorageAdministrationService. EnumerateStorageAllocEntries Foreach allocEntryHandle in response.Handles { AMT_ThirdPartyDataStorageAdministrationService. GetStorageAllocEntry Handle=allocEntryHandle }


53

4.19. Storage The following shows a typical Storage flow using the AMT_ThirdPartyDataStorageService CIM object. It includes pseudo code that provides a context for the CIM methods invoked in the flow. The flow registers an application, allocates a block of memory, creates a permissions group, adds applications to the permissions group, and writes to and reads from the block.

See the Storage Design Guide in the software development kit for a description of the third party storage features and structures. The features and functions in the document generally parallel the methods in the AMT_ThirdPartyDataStorageService class. The library described in the document is not required for the WS-Management implementation. The functions described in the document that set up and manage the library are also not required.

4.19.1. Storage Flow Step 1: Register the application “SampleApp” and extract the associated application handle. Registering an application requires a UUID uniquely identifying the machine where the application executes. The storage service will create just one session handle per application per platform. (The flow assumes that Intel is a pre-registered enterprise name.) Int sessionHandle //will hold the session handle for future calls Int applicationHandle //will hold the application handle for future calls RegisterApplication_OUTPUT response = AMT_ThirdPartyDataStorageService.RegisterApplication ApplicationName=”SampleApp” EnterpriseName=”Intel” VendorName=”Intel” CallerUUID=uuid sessionHandle = response.SessionHandle GetCurrentApplicationHandle_OUTPUT response = AMT_ThirdPartyDataStorageService.GetCurrentApplicationHandle Sessionhandle=sessionHandle applicationHandle = response.ApplicationHandle

Step 2: Allocate a block of non-volatile memory. Int blockHandle //will hold the block handle for future calls // first get the number of bytes available AMT_ThirdPartyDataStorageService.GetBytesAvailable AllocateBlock_OUTPUT response = AMT_ThirdPartyDataStorageService .AllocateBlock SessionHandle=sessionHandle BlockName=”SampleBlock” BlockHidden=false BytesRequested=4096 blockHandle = response.BlockHandle

Step 3: Create a Permissions Group with read-only permissions for the allocated block. Add an application handle (applicationHandle2) to the permissions group. Int groupHandle //will hold the group handle for future calls AddPermissionsGroup_OUTPUT response = AMT_ThirdPartyDataStorageService.AddPermissionsGroup SessionHandle=sessionHandle BlockHandle=blockHandle GroupName=”SampleGroup”


54

GroupPermissions=1 groupHandle= response.GroupHandle AMT_ThirdPartyDataStorageService.AddPermissionsGroupMembers SessionHandle=sessionHandle BlockHandle=blockHandle GroupHandle=groupHandle MemberHandles={applicationHandle2}

Step 4: Write to and Read from the beginning of the allocated block.

Define the data to be written. Byte[] writeData = “Sample Data”

Get the maximum transmission unit. The data must be broken down into buffers of size mtu or less. Int mtu GetMTU_OUTPUT response = AMT_ThirdPartyDataStorageService.GetMTU mtu = response.Mtu

Get the number of available write operations. AMT_ThirdPartyDataStorageService.GetWriteEraseLimit

Lock the block for writing. AMT_ThirdPartyDataStorageService.LockBlock SessionHandle=sessionHandle BlockHandle=blockHandle

Write to the block. Int bytesWritten=0 do { WriteBlock_OUTPUT response = AMT_ThirdPartyDataStorageService.WriteBlock SessionHandle=sessionHandle BlockHandle=blockHandle ByteOffset=bytesWritten Data=writeData[bytesWritten] //Data.Length = min(mtu,writeData.Length - bytesWritten) bytesWritten += response.BytesWritten; } while (bytesWritten < writeData.Length)

Unlock the block. AMT_ThirdPartyDataStorageService.UnlockBlock SessionHandle=sessionHandle BlockHandle=blockHandle

Read from the block to readData. Byte[] readData //set the number of bytes to read Int totalBytes=100 Int bytesRead=0 do { ReadBlock_OUTPUT response = AMT_ThirdPartyDataStorageService.ReadBlock SessionHandle=sessionHandle BlockHandle=blockHandle


55

ByteOffset=bytesRead ByteCount=min(mtu, totalBytes–bytesRead) //Copy min(mtu, totalBytes–bytesRead) bytes from response.Data to //readData[bytesRead] bytesRead += min(mtu, totalBytes–bytesRead) } while (bytesRead < totalBytes)


56

4.20. Remote Control This section presents a sample Remote Control flow using CIM objects. The flow recovers the power state and remote control capabilities of the managed device, sets the reboot source, configures the boot settings, sets the “role” in the CIM_BootService, and then performs a controlled power cycle of the device.

4.20.1. Remote Control Diagram

4.20.2. Remote Control Flow Step 1: Get the current power state of the AMT host CIM_AssociatedPowerManagementServiceType.Get.PowerState

Step 2: Get the Remote Control capabilities AMT_BootCapabilities.Get CIM_PowerManagementCapabilities.Get

Step 3: Set the reboot source:

In addition to a normal power cycle, the user has the option to reboot the Intel AMT host machine from one of the following specific sources:

• PXE Boot • Hard-drive Boot • Diagnostic Boot • CD/DVD Boot

Each of these boots is represented by an instance of CIM_BootSourceSetting. A boot device cannot be chosen if certain boot settings are selected – such as UseIDER, ReflashBIOS, BIOSSetup, and BIOSPause. Therefore, first set these options to “false”, as shown in step 4.

To reboot from a hard drive:

Enumerate the instances of CIM_BootSourceSetting, searching for the one representing the hard drive. CIM_BootSourceSetting hardDriveSetting CIM_BootSourceSetting.Enumerate CIM_BootSourceSetting []SourceSettings = CIM_BootSourceSetting.Pull Foreach instance in SourceSettings {


57

If (instance.InstanceID == "Intel(r) AMT: Force Hard-drive Boot”) { hardDriveSetting = instance break } }

Invoke ChangeBootOrder with the EPR of the CIM_BootSourceSetting above to set the Intel AMT device to reboot from the hard drive: CIM_BootConfigSetting.ChangeBootOrder source = {hardDriveSetting.GetEPR()}

Note: for regular boot set source to {}.

Step 4: Set the boot setting data

For example, set the UseSOL option to true. Note: The user must verify that the settings chosen are supported by the Intel AMT device by checking the boot capabilities returned in Step 2. Some boot settings can not be selected if a boot device was chosen in step 3 – such as UseIDER, ReflashBIOS, BIOSSetup, and BIOSPause. AMT_BootSettingData bootSettings = AMT_BootSettingData.Get AMT_BootSettingData.Put ElementName=bootSettings.ElementName InstanceID= bootSettings.InstanceID Caption= bootSettings.Caption Description= bootSettings.Description OwningEntity= bootSettings.OwningEntity UseSOL=true

Step 5: Set the Role of the CIM_BootConfigSetting: CIM_BootConfigSettingEPR settingEPR= CIM_BootConfigSetting.Get.GetEPR() CIM_BootService.SetBootConfigRole BootConfigSetting= settingEPR Role=1

Step 6: Perform a remotely controlled power cycle:

Find the instance of a CIM_ComputerSystem instance representing the Intel AMT Host.

“host” will hold the CIM_ComputerSystem instance representing the host. CIM_ComputerSystem host CIM_ComputerSystem.Enumerate CIM_ComputerSystem []ComputerSystems = CIM_ComputerSystem.Pull Foreach instance in ComputerSystems { If (instance.Name == “ManagedSystem”) { host = instance break } }

Perform the power cycle. CIM_PowerManagementService.RequestPowerStateChange ManagedElement=host.GetEPR() PowerState=PowerCycle


58

4.21. Remote Access and User Initiated Connection The following shows a typical Remote Access configuration flow, performed using CIM objects. It demonstrates the configuration of a Management Presence Server (MPS), a Remote Access Policy and the enabling of the User Initiated Connection feature. It also demonstrates the setting and deletion of these configurations.

4.21.1. Remote Access Diagram Below is an instance diagram of a possible Remote Access configuration

AMT_RemoteAccessService

CIM_ComputerSystem

AMT_ManagementPresenceRemoteSAP

AMT_RemoteAccessCapabilities

AMT_RemoteAccessPolicyRule

AMT_ManagementPresenceRemoteSAP

AMT_RemoteAccessPolicyRuleAMT_ManagementPresenceRemoteSAP

AMT_MPSUserNamePassword

AMT_PublicKeyCertificate

4

3

12

6

7

7

75

5

AMT_PublicKeyCertificate

1 CIM_HostedService2 CIM_ElementCapabilities3 CIM_ServiceAffectsElement4 CIM_PolicyRuleInSystem5 AMT_RemoteAccessPolicyAppliesToMPS6 CIM_RemoteAccessAvailableToElement7 AMT_RemoteAccessCredentialContext

AMT_UserInitiatedConnectionService 1

4.21.2. Remote Access Flow Get the Remote Access Service instance

AMT_RemoteAccessService raService = AMT_RemoteAccessService.Get


59

Configure an MPS with username-password authentication method

MpsEPR = AMT_RemoteAccessService.AddMpServer AccessInfo= 192.1.0.204 InfoFormat= 3 //IPv4 address Port= somePort AuthMethod= 2 //Username-Password authentication Username= user Password= Password!123 //Should be a strong password CN= MpsCommonName //The given CN is a common name that will be checked against the //common name that appears in the MPS certificate when a connection //with that MPS is established

Get the new MPS instance

AMT_ManagementPresenceRemoteSap mps = GetObjectByEPR(MpsEPR)

Get the username password credential instance created with the new MPS

AMT_MPSUsernamePassword credential = AMT_MPSUsernamePassword.Get selectors InstanceID= Intel(r) AMT:MPS Username Password 0 //credential.RemoteID holds the username //credential.Secret holds the password

Create a Remote Access Policy with a “User Initiated” trigger that is associated with the created MPS

PolicyEPR = AMT_RemoteAccessService.AddRemoteAccessPolicyRule Trigger= 0 //User initiated trigger TunnelLifeTime= 300 //5 minutes MpServer[0] = MpsEPR

Get the new Policy instance

AMT_RemoteAccessPolicyRule policy = GetObjectByEPR(PolicyEPR) //Verify that policy.PolicyRuleName= "User Initiated"

Get the User Initiated Connection Service instance

AMT_RemoteAccessService uiService = AMT_UserInitiatedConnectionService.Get //Check to see uiService.EnabledState to determine which interfaces //are enabled.

Enable the User Initiated Connection Service (all interfaces)

AMT_UserInitiatedConnectionService.RequestStateChange RequestedState= 0x8003 //Bios and OS agent interfaces enabled

Close an open Remote Access connection

AMT_RemoteAccessService.CloseRemoteAccessConnection


60

Disable the User Initiated Connection Service

AMT_UserInitiatedConnectionService.RequestStateChange RequestedState= 0x8000 //All interfaces disabled

Configure an MPS with mutual authentication method (certificate 0)

AMT_PublicKeyCertificate certificate = AMT_PublicKeyCertificate.Get selectors InstanceID=Intel(r) AMT Certificate: Handle: 0 CertificateEPR = certificate.GetEPR() Mps2EPR = AMT_RemoteAccessService.AddMpServer AccessInfo= mps.example.com InfoFormat= 201 //FQDN Port= somePort AuthMethod= 1 //Mutual authentication Certificate= CertificateEPR

Get the new MPS instance

AMT_ManagementPresenceRemoteSap mps2 = GetObjectByEPR(Mps2EPR)

Associate the second created MPS with the created policy.

AMT_ManagementPresenceRemoteSAP mps = AMT_ManagementPresenceRemoteSAP.Get selectors SystemCreationClassName=CIM_ComputerSystem SystemName=Intel(r) AMT CreationClassName=AMT_ManagementPresenceRemoteSAP Name=Intel(r) AMT:Management Presence Server 1 AMT_RemoteAccessPolicRule policy = AMT_RemoteAccessPolicRule.Get selectors PolicyRuleName=User Initiated CreationClassName=AMT_RemoteAccessPolicyRule SystemName=Intel(r) AMT SystemCreationClassName=CIM_ComputerSystem MpsEPR = mps.GetEPR() PolicyEPR = policy.GetEPR() AssociationEPR = AMT_RemoteAccessPolicyAppliesToMPS.Create PolicySet= PolicyEPR ManagedElement= MpsEPR

Remove an association between an MPS and a policy

AMT_RemoteAccessPolicyAppliesToMPS.Delete selectors PolicySet= PolicyEPR ManagedElement= MpsEPR

Update a policy to a new TunnelLifeTime (only TunnelLifeTime and the optional ExtendedData are writable)

AMT_RemoteAccessPolicyRule.Put Selectors[ PolicyRuleName=User Initiated CreationClassName=AMT_RemoteAccessPolicyRule


61

SystemName=Intel(r) AMT SystemCreationClassName=CIM_ComputerSystem] CreationClassName= any ElementName= any PolicyRuleName= any SystemCreationClassName= any SystemName= any Trigger= any TunnelLifeTime=240

Delete a policy

AMT_RemoteAccessPolicRule.Delete selectors PolicyRuleName=User Initiated CreationClassName=AMT_RemoteAccessPolicyRule SystemName=Intel(r) AMT SystemCreationClassName=CIM_ComputerSystem

Update an MPS

AMT_ManagementPresenceRemoteSAP.Put Selectors[ SystemCreationClassName=CIM_ComputerSystem SystemName=Intel(r) AMT CreationClassName=AMT_ManagementPresenceRemoteSAP Name=Intel(r) AMT:Management Presence Server 0] AccessInfo= mpsexample.intel.com CreationClassName= any ElementName= any InfoFormat= 201 //FQDN Name= any Port= somePort SystemCreationClassName= any SystemName= any

Update the password of an MPS configured to use username-password authentication method

AMT_MPSUsernamePassword.Put Selectors[ InstanceID= Intel(r) AMT:MPS Username Password 0] InstanceID= any RemoteID= newUserName Secret=

Update the certificate (from certificate 0 to certificate 1) of an MPS configured to use mutual authentication method.

AMT_PublicKeyCertificate OldCertificate = AMT_PublicKeyCertificate.Get selectors InstanceID=Intel(r) AMT Certificate: Handle: 0 AMT_PublicKeyCertificate NewCertificate = AMT_PublicKeyCertificate.Get selectors InstanceID=Intel(r) AMT Certificate: Handle: 1 AMT_ManagementPresenceRemoteSAP Mps = AMT_ManagementPresenceRemoteSAP.Get selectors


62

SystemCreationClassName=CIM_ComputerSystem SystemName=Intel(r) AMT CreationClassName=AMT_ManagementPresenceRemoteSAP Name=Intel(r) AMT:Management Presence Server 1 OldCertificateEPR= OldCertificate.GetEPR() NewCertificateEPR= NewCertificate.GetEPR() MpsEPR= Mps.GetEPR() AMT_RemoteAccessCredentialContext.Put Selectors[ ElementProvidingContext= MpsEPR ElementInContext= OldCertificateEPR] ElementProvidingContext= any ElementInContext= NewCertificateEPR

Delete an MPS

AMT_ManagementPresenceRemoteSAP.Delete selectors SystemCreationClassName=CIM_ComputerSystem SystemName=Intel(r) AMT CreationClassName=AMT_ManagementPresenceRemoteSAP Name=Intel(r) AMT:Management Presence Server 1

4.22. Audit Log The following shows a typical Audit Log configuration flow, performed using CIM objects. It demonstrates the enabling, exporting and clearing flows of the Audit Log.

4.22.1. Audit Log Diagram

4.22.2. Audit Log Flows Enabling the Audit Log

Set the signing key using SHA1 and a single certificate of size 1400 bytes. AMT_AuditLog.SetSigningKeyMaterial SigningMechanismType= 0 //RSA SHA1 SigningKey= KeyPair //In base64Binary LengthOfCertificates[]= [1400] Certificates= Certificate //In base64Binary

Set an audit policy (ACL Entry Modified event). AMT_AuditPolicyRule.SetAuditPolicy Enable= 1


63

AuditedAppID= 16 // Security Admin app ID EventID= 3 // ACL Entry Modified event ID PolicyType= 0 //Not critical

Get the audit policy. AMT_AuditPolicyRule policyRule = AMT_AuditPolicyRule.Get // policyRule.AuditApplicationEventID[] should now hold the new policy //And policyRule.PolicyType[] of the same index should hold the given //policy type

Enable the Audit Log. AMT_AuditLog.RequestStateChange RequestedState= 2 //Enable

Check the Audit Log state. AMT_AuditLog AuditLog = AMT_AuditLog.Get //AuditLog.EnabledState holds the current state

Remove an audit policy. AMT_AuditPolicyRule.SetAuditPolicy Enable= 0 AuditedAppID= 16 EventID= 3

Locking and Exporting

Lock the Audit Log. SetAuditLock_OUTPUT lockResponse = AMT_AuditLog.SetAuditLock LockTimeoutInSeconds= 120 Flag= 0 //Lock //lockResponse.Handle must be used when unlocking

Read audit event records. ReadRecords_OUTPUT Records Int Index = 0 Do { Records = AMT_AuditLog.ReadRecords StartIndex= Index Index+= Records.RecordsReturned //Copy Records.EventRecords } While Index != Records.TotalRecordCount Export signature ExportAuditLogSignature_OUTPUT Signature= AMT_AuditLog.ExportAuditLogSignature

Verify the lock. AMT_AuditLog AuditLog= AMT_AuditLog.Get //AuditLog.EnabledState should be 6 - Enabled but offline //Also (AuditLog.AuditState & 0x02) == 1

Unlock. AMT_AuditLog.SetAuditLock Flag= 2 //UnLock Handle= lockResponse.Handle //The handle returned on the lock //request


64

Clearing the Audit Log

Lock the audit log, as described above, and then clear. AMT_AuditLog.ClearLog

Unlock, as described above.

4.23. Wireless The following shows typical flows for managing wireless profiles using CIM objects. The flows demonstrate retrieving wireless capabilities, adding and modifying a wireless profile, and deleting a wireless profile.

4.23.1. Wireless Diagram

4.23.2. Wireless Flow Retrieve wireless capabilities

CIM_WiFiPortCapabilities WiFiPortCapabilities; WiFiPortCapabilities.Get(); //port types identifies which 802.11 protocol types the port supports PortTypes[] = WiFiPortCapabilities.SupportedPortTypes[]; CIM_WiFiEndpointCapabilities WiFiEndpointCapabilities; WiFiEndpointCapabilities.Get(); EncryptionMthds[] = WiFiEndpointCapabilities.SupportedEncryptionMethods[];


65

AuthenticationMthds[] = WiFiEndpointCapabilities.SupportedAuthenticationMethods[]; CIM_IEEE8021xCapabilities IEEE8021xCap IEEE8021xCap.Get; SupportedAuthProtocols[] = IEEE8021xCap.SupportedAuthenticationProtocols[];

Add a wireless profile

Before adding a wireless profile, add any necessary certificates and root certificates. See the security admin flow for an example.

Create an instance of CIM_WiFiEndpointSettings, and populate it with profile settings.

CIM_WiFiEndpointSettings wifiSettings; wifiSettings.AuthenticationMethod = AuthenticationMethodWPAIEEE802_1x; wifiSettings.ElementName = ProfileName; wifiSettings.EncryptionMethod = EncryptionMethodTKIP; wifiSettings.InstanceID = ProfileName; wifiSettings.Priority = Priority; wifiSettings.SSID = SSID; If the profile requires IEEE802.1x, then create an instance of CIM_IEEE8021xSettings and set the relevant parameters.

CIM_IEEE8021xSettings settings802_1x; settings802_1x.AuthenticationProtocol = AuthenticationMethods802_1xEAP_TLS; settings802_1x.ElementName = ProfileName; settings802_1x.InstanceID = ProfileName; settings802_1x.Username = UserWireless; Create the profile

AMT_WiFiPortConfigurationService service; service.get; AMT_WiFiPortConfigurationService::AddWiFiSettings_INPUT input; AMT_WiFiPortConfigurationService::AddWiFiSettings_OUTPUT output; // fill the input stucture with the Wifi settings, 802.1x settings and // client certificate settings input.WiFiEndpoint = wifiEndpoint.ToEndpointReference(); input.WiFiEndpointSettingsInput = wifiSettings; input.IEEE8021xSettingsInput = settings802_1x; input.ClientCredential = certificateVec.at(j).ToEndpointReference(); // invoke the actual add profile function service.InvokeAddWiFiSettings(input, output); // The output returns references to the profile settings and the 802.1x settings To update a wireless profile, invoke the update method with the reference to an existing profile returned when it was created and the revised set of parameters.

To delete a wireless profile, use the profile name to identify the profile, and invoke the CIM_WiFiEndpointSettings delete method.

string profileName = “MyProfile” vector<CIM_WiFiEndpointSettings> vecProfiles;


66

CIM_WiFiEndpointSettings::Enumerate(vecProfiles, NULL); for(int i=0; i<vecProfiles.size(); i++) { if( (vecProfiles.at(i).ElementName.compare(profileName) == 0)) { vecProfiles.at(i).Delete(); } }

4.24. WS-Eventing Ws-Eventing is an event–driven reporting method based on the WS-Management data model. A user subscribes for a group of events and specifies the event delivery destination. When an event occurs, it is sent to the defined destination. The user may unsubscribe (remove a previous subscription). As events happen, corresponding messages are buffered (for a maximum of 30 seconds) and then sent to the defined destination. When subscribing, the user may also specify delivery of events with authentication on delivery.

Events are sent as an instance of CIM_AlertIndication – corresponding to the WS-Management data model. There are two major event groupings – events due to Intel AMT objects and those due to CIM objects. The events are sent in a CIM_AlertIndication.

Intel AMT Release 4.0 and later releases support WS-Eventing as well as the event management mechanism described above that enables configuration of PET events.

Note that there is no WS–Eventing event for a BIOS Hang, even though there is a BIOS Hang PET event.

4.24.1. Table of Events The spreadsheet WSEventAndPetTableReplacment.XLS describes the events reported by Intel AMT. The spreadsheet is located in the WS-Management_Class_Reference folder in the DOCS directory of the SDK. The spreadsheet has a row for each event supported. The spreadsheet lists each event and the corresponding data sent in a PET event.

WS-Eventing events are based on the CIM_AlertIndication class.

The first two columns of the spreadsheet, MSG Type and MSG ID, together define the IndicationIdentifier field.

The message iAMT:050 is a special case: it is associated with 14 different messages. In these cases only, the alert will have a Message string included, shown in the Message column. In all other instances, the message is not sent; an application console should match the message in the table to the indication identifier in the message.

Messages have up to three arguments, shown as columns in the table. Other fields in event message are also listed.

The last six columns of the spreadsheet list which events are included in each of the instances of CIM_FilterCollection listed below.

The green columns show fields of the corresponding PET message.

The following shows typical WS-Eventing flows for Intel AMT–subscribing for events, unsubscribing, and processing an event notification.


67

4.24.2. WS-Eventing Diagram

4.24.3. WS-Eventing Flow The following shows typical WS-Eventing flows for Intel AMT–subscribing for events, unsubscribing, and processing an event notification.

WS-Eventing uses three classes: CIM_FilterCollection, CIM_FilterCollectionSubscription, and CIM_ListenerDestinationWSManagement.

Each instance of CIM_FilterCollection in Intel AMT is a filter that passes a predefined set of events. There are six instances of CIM_FilterCollection, defined using the following strings:

• “Intel(r) AMT:FW ProgressEvents”

• “Intel(r) AMT:User”

• “Intel(r) AMT:All”

• “Intel(r) AMT:Platform”

• “Intel(r) AMT:CorePlatform”

• “Intel(r) AMT:Features”

To subscribe for notification of events, a user specifies an instance of CIM_FilterCollection to define the desired subset of events. A CIM_ListenerDestinationWSManagement instance is created for each valid subscription request, as well as an instance of CIM_FilterCollectionSubscription as an association between the instance of CIM_FilterCollection mentioned in the subscription request and the newly created instance of CIM_ListenerDestinationWSManagement.

The number of subscriptions is limited to six. Attempting to create more than six subscriptions without unsubscribing from one of them will fail.

Create a subscription //Get existing CIM_FilterCollection instances CIM_FilterCollection.Enumerate CIM_FilterCollection[] FilterCollections = CIM_FilterCollection.Pull //Chose one of them FilterCollections[0].Subscribe (delivery destination URL, delivery mode [, delivery username, delivery password])


68

Unsubscribe //Get existing CIM_FilterCollectionSubscription instances CIM_FilterCollectionSubscription.Enumerate CIM_FilterCollectionSubscription[] FilterCollectionSubscriptions = CIM_FilterCollectionSubscription.Pull //Chose one of them FilterCollectionSubscriptions[0].Unsubscribe

Put and Renew actions and expiration are not supported.

4.24.4. WS-Eventing Serialization Examples Because the structure of WS-Eventing messages is complex, the following detailed examples will aid in development of WS-Eventing applications. The examples show the elements of a message that change, depending on the message purpose.

New Subscription Request This example creates a new subscription with CIM_FilterCollection “Intel(r) AMT: All”, with a delivery destination of http://www.myserver.com:1234/eventsink.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tns="http://schemas.dmtf.org/wbem/wscim/1/cim-chema/2/CIM_FilterCollection" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsman="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd" xmlns:wscat="http://schemas.xmlsoap.org/ws/2005/06/wsmancat" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wxf="http://schemas.xmlsoap.org/ws/2004/09/transfer" xmlns:cim="http://schemas.dmtf.org/wbem/wscim/1/common" xmlns:wsen="http://schemas.xmlsoap.org/ws/2004/09/enumeration" xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing" xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <soap:Header> <wsa:To>http://myAmtMachine:16992/wsman</wsa:To> <wsa:ReplyTo> <wsa:Address soap:mustUnderstand="true"> http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous </wsa:Address> </wsa:ReplyTo> <wsa:Action soap:mustUnderstand="true"> http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe </wsa:Action> <wsman:MaxEnvelopeSize soap:mustUnderstand="true"> 51200 </wsman:MaxEnvelopeSize> <wsa:MessageID>uuid:85062157-5705-0256-4754-850551807361</wsa:MessageID> <wsman:ResourceURI soap:mustUnderstand="true"> http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_FilterCollection </wsman:ResourceURI> <wsman:SelectorSet> <wsman:Selector Name="InstanceID">Intel(r) AMT:All </wsman:Selector>


69

</wsman:SelectorSet> <wsman:OperationTimeout>PT60.000S</wsman:OperationTimeout> </soap:Header> <soap:Body> <wse:Subscribe> <wse:Delivery Mode="http://schemas.dmtf.org/wbem/wsman/1/wsman/Push"> <wse:NotifyTo> <wsa:Address>http://www.myserver.com:1234/eventsink</wsa:Address> </wse:NotifyTo> </wse:Delivery> </wse:Subscribe> </soap:Body> </soap:Envelope>

This is an InstanceID of the desired CIM_FilterCollection instance. <wsman:SelectorSet> <wsman:Selector Name="InstanceID">Intel(r) AMT:All</wsman:Selector> </wsman:SelectorSet>

This setting says that delivery of an event does not require Ws-Eventing Ack. <wse:Delivery Mode="http://schemas.dmtf.org/wbem/wsman/1/wsman/Push">

Intel AMT also supports requiring an Ack: http://schemas.dmtf.org/wbem/wsman/1/wsman/PushWithAck

This setting specifies the URL where events are sent. The given port number is just an example.

Note that the length of the destination URL is limited to 63 symbols. If the URL exceeds the maximum length, the subscription will not be accepted. <wse:NotifyTo> <wsa:Address>http://www.myserver.com:1234/eventsink</wsa:Address> </wse:NotifyTo>

Deleting a subscription

The following example removes a previously created subscription with CIM_FilterCollection “Intel(r) AMT: All” and delivery destination “http://www.myserver.com/eventsink”. <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tns="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_FilterCollectionSubscription" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsman="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd" xmlns:wscat="http://schemas.xmlsoap.org/ws/2005/06/wsmancat" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wxf="http://schemas.xmlsoap.org/ws/2004/09/transfer" xmlns:cim="http://schemas.dmtf.org/wbem/wscim/1/common" xmlns:wsen="http://schemas.xmlsoap.org/ws/2004/09/enumeration"> <soap:Header> <wsa:To> http://myAmtMachine:16992/wsman </wsa:To> <wsa:ReplyTo> <wsa:Address soap:mustUnderstand="true"> http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous </wsa:Address>


70

</wsa:ReplyTo> <wsa:Action soap:mustUnderstand="true"> http://schemas.xmlsoap.org/ws/2004/08/eventing/Unsubscribe </wsa:Action> <wsman:MaxEnvelopeSize soap:mustUnderstand="true"> 51200 </wsman:MaxEnvelopeSize> <wsa:MessageID>uuid:54566854-1716-2808-5012-785038710670</wsa:MessageID> <wsman:ResourceURI soap:mustUnderstand="true"> http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_FilterCollectionSubscription </wsman:ResourceURI> <wsman:SelectorSet> <wsman:Selector Name="Filter"> <wsa:EndpointReference> <b:Address xmlns:b="http://schemas.xmlsoap.org/ws/2004/08/addressing"> http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous </b:Address> <b:ReferenceParameters xmlns:b="http://schemas.xmlsoap.org/ws/2004/08/addressing"> <c:ResourceURI xmlns:c="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd"> http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_FilterCollection </c:ResourceURI> <c:SelectorSet xmlns:c="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd"> <c:Selector Name="InstanceID">Intel(r) AMT:All</c:Selector> </c:SelectorSet> </b:ReferenceParameters> </wsa:EndpointReference> </wsman:Selector> <wsman:Selector Name="Handler"> <wsa:EndpointReference> <b:Address xmlns:b="http://schemas.xmlsoap.org/ws/2004/08/addressing"> http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous </b:Address> <b:ReferenceParameters xmlns:b="http://schemas.xmlsoap.org/ws/2004/08/addressing"> <c:ResourceURI xmlns:c="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd"> http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ListenerDestinationWSManagement </c:ResourceURI> <c:SelectorSet xmlns:c="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd"> <c:Selector Name="Name">Listener Destination 0</c:Selector> <c:Selector Name="CreationClassName"> CIM_ListenerDestinationWSMAN </c:Selector>


71

<c:Selector Name="SystemName">Intel(r) AMT</c:Selector> <c:Selector Name="SystemCreationClassName"> CIM_ComputerSystem </c:Selector> </c:SelectorSet> </b:ReferenceParameters> </wsa:EndpointReference> </wsman:Selector> </wsman:SelectorSet> <wsman:OperationTimeout>PT60.000S</wsman:OperationTimeout> </soap:Header> <soap:Body /> </soap:Envelope>

This is the address of the Intel AMT machine. <soap:Header> <wsa:To> http://myAmtMachine:16992/wsman </wsa:To>

This is an InstanceID of a CIM_FIlterCollection instance from a previous subscription. <c:Selector Name="InstanceID">Intel(r) AMT:All</c:Selector>

This is a name of a CIM_ListenerDestinationWSManagement instance created at the time of subscription. It differs from subscription to subscription; the delete request must use the name defined at creation. <c:Selector Name="Name">Listener Destination 0</c:Selector>

Creating a subscription that supports authentication To receive events with authentication on delivery, a user may also specify a username and password in the subscription request. Intel AMT will use the digest authentication algorithm for authentication on delivery.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tns="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_FilterCollection" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsman="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd" xmlns:wscat="http://schemas.xmlsoap.org/ws/2005/06/wsmancat" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wxf="http://schemas.xmlsoap.org/ws/2004/09/transfer" xmlns:cim="http://schemas.dmtf.org/wbem/wscim/1/common" xmlns:wsen="http://schemas.xmlsoap.org/ws/2004/09/enumeration" xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing" xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <soap:Header> <wsa:To> http://myAmtMachine:16992/wsman </wsa:To> <wsa:ReplyTo> <wsa:Address soap:mustUnderstand="true"> http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous </wsa:Address> </wsa:ReplyTo> <wsa:Action soap:mustUnderstand="true"> http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe </wsa:Action> <wsman:MaxEnvelopeSize soap:mustUnderstand="true">


72

51200 </wsman:MaxEnvelopeSize> <wsa:MessageID>uuid:85062157-5705-0256-4754-850551807361</wsa:MessageID> <wsman:ResourceURI soap:mustUnderstand="true"> http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_FilterCollection </wsman:ResourceURI> <wsman:SelectorSet> <wsman:Selector Name="InstanceID">Intel(r) AMT:All</wsman:Selector> </wsman:SelectorSet> <wsman:OperationTimeout>PT60.000S</wsman:OperationTimeout> <wst:IssuedTokens soap:mustUnderstand="true"> <wst:RequestSecurityTokenResponse> <wst:TokenType> http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken </wst:TokenType> <wst:RequestedSecurityToken> <wsse:UsernameToken> <wsse:Username>John</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd#PasswordText">Pwd!123</wsse:Password> </wsse:UsernameToken> </wst:RequestedSecurityToken> </wst:RequestSecurityTokenResponse> </wst:IssuedTokens> </soap:Header> <soap:Body> <wse:Subscribe> <wse:Delivery Mode="http://schemas.dmtf.org/wbem/wsman/1/wsman/Push"> <wse:NotifyTo> <wsa:Address>://www.myserver.com:1234/eventsink </wsa:Address> </wse:NotifyTo> <wsman:Auth Profile="http://schemas.dmtf.org/wbem/wsman/1/wsman/secprofile/http/digest"/> </wse:Delivery> </wse:Subscribe> </soap:Body> </soap:Envelope>

The following fragment specifies that user wants to use authentication on delivery. Only digest profile is supported. <wsman:Auth Profile="http://schemas.dmtf.org/wbem/wsman/1/wsman/secprofile/http/digest"/>

The following specifies username and password for authentication on event delivery. In this example, Username = John, Password = Pwd!123 <wsse:UsernameToken> <wsse:Username>John</wsse:Username>


73

<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd#PasswordText">Pwd!123 </wsse:Password> </wsse:UsernameToken>

Event Delivery

The next message is an example of a delivered event. <a:Envelope xmlns:a="http://www.w3.org/2003/05/soap-envelope" xmlns:b="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:c="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd" xmlns:d="http://schemas.xmlsoap.org/ws/2005/02/trust" xmlns:e="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:f="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_AlertIndication"> <a:Header> <b:To>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</b:To> <b:ReplyTo> <b:Address> http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous </b:Address> </b:ReplyTo> <c:AckRequested></c:AckRequested> <b:Action a:mustUnderstand="true"> http://schemas.dmtf.org/wbem/wsman/1/wsman/Event </b:Action> <b:MessageID>uuid:00000000-8086-8086-8086-00000000002B</b:MessageID> <c:ResourceURI> http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_AlertIndication </c:ResourceURI> </a:Header> <a:Body> <f:CIM_AlertIndication> <f:AlertType>8</f:AlertType> <f:AlertingElementFormat>2</f:AlertingElementFormat> <f:AlertingManagedElement></f:AlertingManagedElement> <f:IndicationFilterName>Intel(r) AMT:AllEvents</f:IndicationFilterName> <f:IndicationIdentifier></f:IndicationIdentifier> <f:IndicationTime>2008-1-20T8:27:49.000</f:IndicationTime> <f:Message></f:Message> <f:MessageArguments>0</f:MessageArguments> <f:MessageArguments></f:MessageArguments> <f:MessageArguments>Interop:CIM_ComputerSystem.CreationClassName=CIM_ComputerSystem,Name=Intel(r) AMT</f:MessageArguments> <f:MessageID>iAMT:0021</f:MessageID> <f:OtherAlertingElementFormat></f:OtherAlertingElementFormat> <f:OtherSeverity></f:OtherSeverity> <f:OwningEntity>Intel(r) AMT</f:OwningEntity> <f:PerceivedSeverity>2</f:PerceivedSeverity> <f:ProbableCause>0</f:ProbableCause> <f:SystemName>Intel(r) AMT</f:SystemName>


74

</f:CIM_AlertIndication> </a:Body> </a:Envelope>

The following indicates that the event is delivered in PushWithAck mode and requires an Ack. This item will not appear in a delivery in Push mode. <c:AckRequested></c:AckRequested>

The following is an event specifier. See the WSEventAndPetTableReplacment.XLS document in included in the SDK for a list of events. <f:MessageID>iAMT:0021</f:MessageID>

This message field is empty because it is expected that a software application will fill in this field based on the information in the WSEventAndPetTableReplacment.XLS file. <f:Message></f:Message>

Response when Ack is required <Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.w3.org/2003/05/soap-envelope"> <Header> <To xmlns="http://schemas.xmlsoap.org/ws/2004/08/addressing"> WSMan.CIM.General.EndpointReferenceType2 </To> <ReplyTo xmlns="http://schemas.xmlsoap.org/ws/2004/08/addressing"> <Address> http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous </Address> </ReplyTo> <RelatesTo xmlns="http://schemas.xmlsoap.org/ws/2004/08/addressing"> uuid:00000000-8086-8086-8086-00000000002B </RelatesTo> <Action xmlns="http://schemas.xmlsoap.org/ws/2004/08/addressing"> http://schemas.dmtf.org/wbem/wsman/1/wsman/Ack </Action> <MessageID xmlns="http://schemas.xmlsoap.org/ws/2004/08/addressing"> uuid:49766777-0954-6165-2003-691315299058 </MessageID> <SelectorSet xmlns="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd" /> <MaxEnvelopeSize xmlns="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd"> 51200 </MaxEnvelopeSize> <OperationTimeout xmlns="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd"> PT60.000S </OperationTimeout> <ResourceURI xmlns="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd"> http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_FilterEntryBase </ResourceURI> </Header> </Envelope>

The RelatesTo field UUID should be equal to UUID of the event delivery request.


75

<RelatesTo xmlns="http://schemas.xmlsoap.org/ws/2004/08/addressing"> uuid:00000000-8086-8086-8086-00000000002B </RelatesTo>

All the events that occur in the Intel AMT system are buffered, so it may take up to 30 seconds after an event occurs before it is sent to its destination.

4.25. Role Based Authorization Profile Intel AMT Release 4.0 and later releases implement the DASH 1.0 preliminary specification for the Role Based Authorization Profile. The implementation is based on DSP1039 version 1.0.0a dated 2006-10-23. The profile can be found at the DTMF website under Management Profiles:

http://www.dmtf.org/standards/profiles/

4.26. Simple Identity Management Profile Intel AMT Release 4.0 and later releases implement the DASH 1.0 preliminary specification for the Simple Identity Management Profile. The implementation is based on DSP1034 version 1.0.0a dated 2006-10-30. The profile can be found at the DTMF website under Management Profiles:




intel® amt ws-management flows · the following topics must be considered when using ws-management...

Documents