network interface guide interface guide ... 7.9 circuit breaker interface ... message formats are...

June 2007

Intel® Active Management Technology

Network Interface Guide

Version 3.0.06

ii June 2007

Legal Notice

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL 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.

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.

Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them.

The Intel product(s) referenced in this document 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.

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.

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 order 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.

*Other names and brands may be claimed as the property of others.

Copyright © Intel Corporation 2005, 2006, 2007

http://www.intel.com/

Intel® AMT Network Interface Guide

iii June 2007

1 Introduction......................................................................................................................................8

2 Reference Documents.....................................................................................................................8

3 Glossary ..........................................................................................................................................9

4 Notational Conventions .................................................................................................................10

5 Network Interface ..........................................................................................................................10

5.1 SOAP RPC-based Programmatic Interface...........................................................................11

5.1.1 Soap Errors and Faults ...................................................................................................12

6 Access Control ..............................................................................................................................12

7 Supported Network Interfaces.......................................................................................................12

7.1 Security Administration Interface ...........................................................................................15

7.1.1 Service APIs ...................................................................................................................18

7.1.2 Service APIs – Access Control Management.................................................................36

7.1.3 Service APIs – Certificate Management .........................................................................50

7.1.4 Service APIs – Power Settings .......................................................................................69

7.1.5 Service APIs – Environment detection & VPN Connectivity...........................................78

7.1.6 Service APIs – User Notification.....................................................................................81

7.1.7 Service APIs – Provisioning............................................................................................83

7.1.8 Service Data Types.........................................................................................................96

7.2 Network Administration Interface .........................................................................................117

7.2.1 Service APIs .................................................................................................................118

7.2.2 Service Data Types.......................................................................................................134

7.3 Storage Administration Interface..........................................................................................146

7.3.1 Service APIs .................................................................................................................146


7.4 Hardware Asset Interface.....................................................................................................165

7.4.1 Service APIs .................................................................................................................165


7.5 Remote Control Interface.....................................................................................................184

7.5.1 Service APIs .................................................................................................................184



iv

7.6 Storage Interface..................................................................................................................197

7.6.1 Service APIs .................................................................................................................197


7.7 Event Manager Interface......................................................................................................199

7.7.1 Service APIs .................................................................................................................200

7.7.2 Intel AMT Client Initiated APIs ......................................................................................220


7.8 Agent Presence....................................................................................................................233

7.8.1 Service APIs - Remote Interface .................................................................................233

7.8.2 Service APIs - Local Interface ......................................................................................241


7.9 Circuit Breaker Interface ......................................................................................................248

7.9.1 Service APIs .................................................................................................................248

7.9.2 Service APIs (Heuristics Circuit Breaker) .....................................................................260


7.10 Redirection Interface ........................................................................................................281

7.10.1 Service APIs .................................................................................................................281


7.11 Network Time Interface ....................................................................................................285

7.11.1 Service APIs .................................................................................................................285


7.12 GeneralInfo Interface........................................................................................................288

7.12.1 Service APIs .................................................................................................................289


7.13 FirmwareUpdate Interface................................................................................................301

7.13.1 Service APIs .................................................................................................................301


7.14 EIT Interface .....................................................................................................................304

7.14.1 Service APIs .................................................................................................................304


7.15 Wireless Configuration Interface ......................................................................................307


v

7.15.1 Service APIs .................................................................................................................307

7.15.2 Type definitions.............................................................................................................313

7.16 Endpoint Access Control Admin Interface........................................................................320

7.16.1 Service APIs .................................................................................................................320


7.17 Endpoint Access Control Interface ...................................................................................325

7.17.1 Service APIs .................................................................................................................325


7.18 User Notification Interface ................................................................................................329

7.18.1 Service APIs .................................................................................................................329

7.18.2 Client Initiated APIs.......................................................................................................330


8 Common Data Types ..................................................................................................................330

8.1 General data structures........................................................................................................331

8.1.1 INVALID_HANDLE .......................................................................................................331

8.1.2 PT_STATUS .................................................................................................................331

8.1.3 IPv4AddressType..........................................................................................................333

8.1.4 BinaryData ....................................................................................................................334

8.1.5 URL...............................................................................................................................334

8.1.6 NodeAddressType ........................................................................................................334

9 Self Generated Platform Event Trap Definitions .........................................................................335

9.1 Link Up Event.......................................................................................................................336

9.2 Watchdog Events .................................................................................................................337

9.2.1 Default Watchdog Event ...............................................................................................337

9.2.2 OS Hang Watchdog Event............................................................................................337

9.3 Password Attack Event ........................................................................................................339

9.4 Circuit Breaker Event ...........................................................................................................340

9.5 Agent Presence Event .........................................................................................................341

9.6 Firmware Update Event .......................................................................................................342

9.6.1 Update Status Structure ...............................................................................................342

9.6.2 Update Status Codes....................................................................................................343


vi

9.6.3 Update Failure Reason Codes .....................................................................................343

9.7 Network Adapter State Tampered .......................................................................................347

9.8 Bringup Events.....................................................................................................................349

9.8.1 CPU Missing Event .......................................................................................................349

9.8.2 CPU Dead On Arrival Event .........................................................................................349

9.8.3 DIMM Missing or Not Functional Event ........................................................................350

9.8.4 BIOS Hang Event..........................................................................................................351

9.9 Circuit Breaker Heuristics notification ..................................................................................352

9.9.1 Report state ..................................................................................................................352

9.10 User Notification Alert.......................................................................................................354

9.10.1 Report state ..................................................................................................................354

9.11 AMT Diagnostic Alert........................................................................................................357

10 Product Capabilities.................................................................................................................359

10.1 Quantitative Properties and Capabilities ..........................................................................360

10.1.1 Agent presence (supported as of Intel AMT Release 2.0)............................................360

10.1.2 System Defense (Circuit Breaker) (supported as of Intel AMT Release 2.0) ...............360

10.1.3 PKI ................................................................................................................................360

10.1.4 User ACL ......................................................................................................................361

10.1.5 Event Manager..............................................................................................................361

10.2 TLS Certificates and Authentication .................................................................................362

10.2.1 Server Side Authentication ...........................................................................................362

10.2.2 Client Side Authentication.............................................................................................362

10.3 Intel AMT Release 2.0 Reduced Functionality .................................................................364

10.3.1 Introduction ...................................................................................................................364

10.3.2 Detailed Description of Unsupported Features and Functions.....................................364

10.3.3 Additional Compatibility Notes ......................................................................................365

10.4 Power Packages...............................................................................................................366

11 New APIs and Deprecated APIs..............................................................................................367


vii

This page is intentionally left blank.


8

1 Introduction This document defines the Intel® Active Management Technology Network Interface. The interface is a SOAP-based API between remote management server host software and the Intel Active Management Technology (Intel® AMT) microcontroller firmware. Each implementation must meet the interface specification.

2 Reference Documents The following documents are companion and supporting specifications for the Intel AMT Network Interface:

[SOAP] Box, D., et al., “Simple Object Access Protocol Version 1.1,” W3C note, May 2000, http://www.w3c.org/TR/2000/NOTE-SOAP-20000508

[WSDL] Weerawarana, S., et al., “Web Services Description Language (WSDL) Version 1.1,” W3C Working Draft, July 2002, http://www.w3.org/TR/2002/WD-wsdl12-20020709

[DNS] Mockapetris, P., “Domain names - Concepts and Facilities,” The Internet Engineering Task Force (IETF), RFC 1034, November 1987, http://www.ietf.org/rfc/rfc1034.txt

[PET] IPMI Platform Event Trap Format Specification v1.0, 1998, Intel Corporation, Hewlett-Packard Company, NEC Corporation, and Dell Computer Corporation

[TLS] Dierks, T., et al., “Transport Layer Security,” IETF, RFC 2246, January 1999, http://www.ietf.org/rfc/rfc2246.txt

[HTTP] Fielding, R., et al, “Hypertext Transfer Protocol -- HTTP/1.1,” The Internet Society, June 1999, http://www.w3.org/Protocols/rfc2616/rfc2616.html

[HTTPS] Rescorla, E. “HTTP Over TLS,” IETF, RFC 2818, May 2000, http://www.ietf.org/rfc/rfc2818.txt

[DIGEST]

[RFC 2617]

Franks, J., et al, “HTTP Authentication: Basic and Digest Access Authentication,” IETF, RFC 2617, June 1999, http://www.ietf.org/rfc/rfc2617.txt

[SSH] Ylonen, T., et al., “SSH Protocol Architecture,” IETF, Internet draft, May 2000, http://www.ietf.org/proceedings/00jul/I-D/secsh-architecture-05.txt

[IP] Postel, J. (ed.), "Internet Protocol - DARPA Internet Program Protocol Specification,” IETF, RFC 791, USC/Information Sciences Institute, September 1981, http://www.ietf.org/rfc/rfc791.txt

[ASF] Cline, K. (ed.) “Alert Standard Format (ASF) Specification,” DMTF, Version 2.0, April 2003, http://www.dmtf.org/standards/documents/ASF/DSP0136.pdf

[DHCP] Droms, R. “Dynamic Host Configuration Protocol,” IETF, RFC 2131, March 1997, http://www.ietf.org/rfc/rfc2131.txt

[DHCP-BOOTP]

Alexander, S. “DHCP Options and BOOTP Vendor Extensions,” IETF, RFC 2132, March 1997, http://www.ietf.org/rfc/rfc2132.txt

http://www.w3c.org/TR/2000/NOTE-SOAP-20000508

http://www.w3.org/TR/2002/WD-wsdl12-20020709

http://www.ietf.org/rfc/rfc1034.txt


http://www.w3.org/Protocols/rfc2616/rfc2616.html



http://www.ietf.org/proceedings/00jul/I-D/secsh-architecture-05.txt

http://www.ietf.org/proceedings/00jul/I-D/secsh-architecture-05.txt


http://www.dmtf.org/standards/documents/ASF/DSP0136.pdf




9

[DHCP-FQDN] Stapp, M. (et al.), “The DHCP Client FQDN Option,” IETF, Internet-Draft, March 2006, http://www.ietf.org/internet-drafts/draft-ietf-dhc-fqdn-option-13.txt

[802.1Q] IEEE Std 802.1Q, 2003 Edition (Incorporates IEEE Std 802.1Q-1998, IEEE Std 802.1u-2001, IEEE Std 802.1v-2001, and IEEE Std 802.1s-2002)

[NUM] Postel, J. “Assigned Numbers,” IETF, RFC 790, September 1981, http://www.ietf.org/rfc/rfc790.txt

[RFC 3280] Housley, R. (et al.), “Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile,” IETF, RFC 3280, April 2002 http://www.ietf.org/rfc/rfc3280.txt

[AES] “Advanced Encryption Standard (AES),” FIPS Publication 197, November 2001, http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf

[RSA] Rivest, R.L. (et al.), ”A method for obtaining digital signatures and public-key cryptosystems,'' Communications of the ACM, 21(February 1978), 120-126

[SHA-1] "Secure Hash Standard,” FIPS Publication 180-1, April 1995, http://www.itl.nist.gov/fipspubs/fip180-1.htm

[RFC 3602] Frankel, S. “The AES-CBC Cipher Algorithm and Its Use with IPsec,” IETF, RFC 3602, http://www.ietf.org/rfc/rfc3602.txt

[RC4] Thayer, R. and Kaukonen, K., “A Stream Cipher Encryption Algorithm,” RC4, Work in Progress.

[IANA-PROTOCOLS]

Internet Assigned Numbers Authority – protocol number assignment, http://www.iana.org/assignments/protocol-numbers

[Kerberos] Kohl, J. (et al.), “The Kerberos Network Authentication Service (V5),” IETF, RFC 1510, http://www.ietf.org/rfc/rfc1510.txt

[TLS-PSK] Eronen, P. and Tschofenig, H., “Pre-Shared Key Ciphersuites for Transport Layer Security (TLS),” IETF, RFC 4279, http://www.ietf.org/rfc/rfc4279.txt

[SDG] Intel AMT Storage Design Guide

3 Glossary The following terms are used in this document:

FW Firmware, specifically the firmware of the Intel AMT device

ISV Independent Software Vendor

SID Microsoft* Active Directory Security ID

SMBIOS System Management BIOS

SOAP-RPC SOAP Remote Procedure Call Representation

SPN Service Principal Name

http://www.ietf.org/internet-drafts/draft-ietf-dhc-fqdn-option-13.txt

http://www.ietf.org/internet-drafts/draft-ietf-dhc-fqdn-option-13.txt



http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf

http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf

http://www.itl.nist.gov/fipspubs/fip180-1.htm


http://www.iana.org/assignments/protocol-numbers




10

4 Notational Conventions This document uses several notational conventions for the purpose of clarification or abbreviation. Message formats are presented using a pseudo-code that is virtually identical to the C language, with the following exceptions:

Arrays that contain Null-terminated strings are declared as strings instead of a numeric size.

For example: string VendorName;

API prototypes are defined in IDL file syntax as:

uint32 EnumerateAssetTypes( [out] uint32 Count, [out] AssetTypeArrayType AssetTypes );

Message parameters are in this font. The return parameter is actually a part (out parameter) named Status within the WSDL output message.

When a requested storage operation fails, a response is returned to indicate failure. Data fields that would be returned as part of a success response message are omitted from failure responses. The attribute keyword “success” is prepended to each field that is omitted from a response message when the corresponding operation fails. This is done for storage operations because their messages are embedded in SOAP messages as binary data. The structure below gives an example of this syntax:

typedef struct _ISVS_REGISTER_APPLICATION_RESPONSE { ISVS_MESSAGE_HEADER Header; ISVS_REGISTRATION_TYPE RegistrationType; PT_STATUS Status; [success] ISVS_REGISTRATION_OUTPUT_DATA RegistrationData; ISVS_ICV IntegrityCheckValue; } ISVS_REGISTER_APPLICATION_RESPONSE;

As these examples demonstrate, a fixed-width font is used to distinguish pseudo-code from other text.

5 Network Interface The interface allows an external network host such as an enterprise management system to access Intel AMT features. This section describes the network programmatic interface that allows an external network host to perform the following actions:

• Perform administrative operations.

• Access the Event Log and manipulate the event filters.

• Power off, power on, reboot, or wake up the PC.

• Read Hardware Asset Management information.

• Read/write unformatted data to the public area of the non-volatile store.


11

5.1 SOAP RPC-based Programmatic Interface The SOAP RPC-based programmatic interface allows external network hosts to access Intel AMT features. This section describes details about the supported version of the SOAP RPC.

Intel AMT supports SOAP Version 1.1, as outlined in the W3C Note 08. SOAP is bound to the HTTP protocol. An RPC method invocation maps to an HTTP request and an RPC response maps to an HTTP response. Refer to the W3C note on requirements for a SOAP node bound to the HTTP protocol. The Intel AMT API is described in Web Service Description Language [WSDL] and follows WSDL version 1.1, available at http://schemas.xmlsoap.org/wsdl/. SOAP messages can contain a WSDL-based description of the API. Intel AMT only supports UTF-8 SOAP, the message encoding used by most network SOAP clients.

A platform with Intel AMT supports the management services listed in “Supported Network Interfaces”, below.

Each of these services is provided through a unique WSDL interface. WSDL interfaces also are known as PortTypes, which consist of operations that deliver Intel AMT services to client software.

Each WSDL-based Intel AMT operation has two associated messages — input and output. Input messages represent service requests sent by client software to the Intel AMT server. Output messages represent the corresponding server-to-client responses.

A WSDL binding describes the protocol used for carrying SOAP messages for a PortType. A Port/endpoint is a combination of a binding and a specific address. A service is a collection of related endpoints.

Because Intel AMT services have only one PortType per service, each of the above management services is exposed via a separate service. Moreover, since Intel AMT only supports SOAP binding, each service has only one Port.

Intel AMT devices support SOAP extensions to HTTP digest authentication, which are adaptations of the corresponding mechanisms defined in RFC 2617. The digest mechanism allows a client to authenticate itself by presenting credentials consisting of a username/password pair transmitted using cryptographic hashes in the request message.

HTTP digest authentication depends on a local access control list (ACL). Each ACL entry contains a username and password (Digest user) or an Active Directory Security Identifier (SID) (Kerberos user). All entries contain a list of the corresponding HTTP realms that the user can access. The local ACL will be contained in the Intel AMT data schema and managed via the user and programmatic interfaces. Each HTTP realm corresponds to one or more interfaces.

Starting with Intel AMT Release 2.0, local applications communicate with Intel AMT the same way that remote applications do, by encapsulating commands in a SOAP/HTTP message. However, when a local application sends a SOAP/HTTP message addressed to the local Intel AMT host name, the Local Manageability Service (LMS), which listens for traffic directed to the host name, intercepts the message and routes it to the Intel® Management Engine Interface driver. The Intel Management Engine Interface multi-threaded connection-based driver communicates over the Intel Management Engine Interface, where the counterpart driver receives the information and passes it to the Intel AMT embedded IP stack. The Intel Management Engine Interface driver supports multiple connections operating simultaneously. If the driver is interrupted because the CPU has gone into a “hibernate” state, all connections are terminated and the Intel Management Engine Interface driver returns all pending requests with an error. Application developers should take this into account and provide for error handling. Applications can also register for power events and not perform operations during events such as being in a “hibernate,” “standby,” or other low power state.

http://schemas.xmlsoap.org/wsdl/


12

5.1.1 Soap Errors and Faults As most of the commands in this document rely on XML/SOAP transport, the leading principle is to enforce parameter checking through Schema validation (XSD) wherever possible. While some of the commands may return various errors to reflect erroneous input (e.g. PT_STATUS_INVALID_CERT), it is not guaranteed that these errors will always be returned as it may be possible that the schema validation will be extended to cover more types and include more validation rules.

Some of the error codes serve to help with understanding what the erroneous input is, but the same effect may be achieved by cross checking against the corresponding Schema validation document.

6 Access Control All commands of a given interface have the same access permissions (defined by an "AMT Realm"). A user has permission to access an interface based on the AMT Realm settings of the interface and the configured AMT Realms of the user. When there is a match, the caller is allowed to execute the command; otherwise the caller is sent the relevant HTTP error code.

Security concerns imply that Intel AMT should authenticate the user before executing a supported command. The LocalUN Realm may not require users to authenticate; however, this can be changed to improve the access control to the interface.

7 Supported Network Interfaces This section describes the operations supported by the Intel AMT out-of-band network interface. The operations are grouped by interface.

Note: A SOAP fault might be generated by calling any of the interfaces in a manner that deviates from this specification.

Each interface has an associated security model that includes transport layer security (TLS) for data confidentiality and authentication of the Intel AMT device to a management console. The models include different methods for authentication depending on the entity that is given access to the interface.

For example, since access to administration interfaces is granted to users, protocols based on user access control lists (ACLs) are employed. The security interface contains a default admin ACL entry that provides the root authenticator remote configuration of the LoginPackage credentials.

Note: This ACL entry can be updated by the IT department through the host or network interface.

Access to third party non-volatile storage is granted to applications and enterprises, so the protocols and control structures used for the storage interface focus on application IDs and enterprise IDs.

The interfaces described in the sections that follow are summarized in the table below. The security methods that are used for each interface – other than TLS, which is assumed for all interfaces – are listed in the right-hand column. The realm associated with each interface is listed in the middle column.

Important notes regarding "anonymous" user authentication in Intel AMT Release 2.5 or later:

In order to resolve several issues related to local host software trying to interact with Intel AMT devices, the notion of "anonymous access” was defined for specific local URIs (listed in the table below). By default, a local URI that has "Anonymous authentication" listed will start off as a URI that does not require authentication of incoming commands. These default settings may be changed to strengthen the local interface access; however, the local software must then be configured to authenticate with the username/password which were configured for the interface.


13

Important notes regarding "anonymous" user authentication in Intel AMT 3.0 or later:

Since Intel AMT Release 3.0 includes a WS-Management implementation, there was an equivalent effort to resolve the anonymous access issue that arose in the previous generation. By default, Intel AMT Release 3.0 or later includes system ACL entries named $$uns with access to the User Notification Realm and $$eac with access to the Endpoint Access Control Realm. These entries have default passwords that match the usernames. These ACL entries may be considered public/anonymous as long as the password has not changed. The system ACL entries can be disabled and their passwords may be modified, but they cannot be deleted and the realm access for that ACL cannot be changed.

Interface Realm Local A

ccess

Rem

oteAccess

Authentication modes

Security Administration Interface PT administration − √ - HTTP Digest Authentication.

- Kerberos authentication

Network Administration PT administration − √ - HTTP Digest Authentication. - Kerberos authentication

Hardware Asset Interface HW asset − √ - HTTP Digest Authentication. - Kerberos authentication

Remote Control Remote control − √ - HTTP Digest Authentication. - Kerberos authentication

Storage Storage √ √ - HTTP Digest Authentication. - Kerberos authentication

Event mgmt − √ - HTTP Digest Authentication. - Kerberos authentication

Event Management EventLogReader √ √ - HTTP Digest Authentication.


Storage Administration Storage Admin − √ - HTTP Digest Authentication. - Kerberos authentication

Redirection Interface Redirection − √

- HTTP Digest Authentication - Kerberos authentication - Redirection Authentication Protocol

Local Agent Presence LocalAgentPresence √ − - HTTP Digest Authentication - Kerberos authentication

Remote Agent Presence RemoteAgentPresence − √ - HTTP Digest Authentication - Kerberos authentication

Circuit Breaker Circuit Breaker − √ - HTTP Digest Authentication - Kerberos authentication


14

NetworkTime NetworkTime − √ - HTTP Digest Authentication - Kerberos authentication

GeneralInfo GeneralInfo √ √ - HTTP Digest Authentication - Kerberos authentication

FirmwareUpdate FirmwareUpdate √ √ - HTTP Digest Authentication - Kerberos authentication

EIT PT administration √ − - HTTP Digest Authentication - Kerberos authentication

WirelessConfiguration PT administration − √ - HTTP Digest Authentication - Kerberos authentication

EndpointAccessControl EndpointAccessControl √ − - HTTP Digest Authentication - Kerberos authentication OR Anonymous authentication

EndpointAccessControlAdmin

EndpointAccessControlAdmin − √ - HTTP Digest Authentication


LocalUserNotification LocalUN √ − - HTTP Digest Authentication - Kerberos authentication OR Anonymous authentication


15

7.1 Security Administration Interface Namespace : http://schemas.intel.com/platform/client/SecurityAdministration/2004/01 Port : http://hostname:port/SecurityAdministrationService

Default Interface Access Permissions:

Local Access −

Network Access √

The Security Administration Interface exposes security administration functionality to remote configuration applications. The operations in this interface allow administrators to manage security control and data structures.

Method Description

AddUserAclEntry Adds an entry to the User Access Control List (ACL)

AddUserAclEntryEx Adds an entry to the User ACL

EnumerateUserAclEntries Enumerates all entries in the User ACL

GetUserAclEntry Reads a single User ACL entry

GetUserAclEntryEx Reads a single User ACL entry

UpdateUserAclEntry Updates the contents of a User ACL entry

UpdateUserAclEntryEx Updates the contents of a User ACL entry

RemoveUserAclEntry Removes a User ACL entry

SetAdminAclEntry Modifies the Administrative ACL properties

SetAdminAclEntryEx Modifies the Administrative ACL properties

GetAdminAclEntry Returns the attributes of the Administrative ACL

GetDigestRealm Reads the Digest Realm string

SetAclEnabledState Enables or disables an ACL entry

GetAclEnabledState Reads the enabled state of an ACL entry

SetKerberosOptions Sets the Kerberos options

GetKerberosOptions Reads the Kerberos options

SetEnabledInterfaces Sets the enabled interfaces

GetEnabledInterfaces Reads the enabled interfaces

SetTlsEnabled Enables or disables TLS on the Intel AMT device

SetTlsOptions Sets TLS options

GetTlsOptions Gets TLS options


16

SetTLSKeyAndCertificate Sets the TLS Certificate Chain and associated Private Key

SetTLSPSK Configures the TLS PSK used in the partial unprovisioned state.

SetRngKey Sets the Random Number Generator key used in the Intel AMT device

SetTLSCertificate Sets the TLS certificate chain

GetTLSCertificate Returns the TLS certificate chain

AddTrustedRootCertificate Adds trusted root certificate

GetTrustedRootCertificate Gets trusted root certificate

DeleteTrustedRootCertificate Deletes trusted root certificate

EnumerateTrustedRootCertificates Enumerates trusted root certificate

SetTrustedFqdnCN Sets trusted FQDN CN

GetTrustedFqdnCN Gets trusted FQDN CN

SetCRL Sets Certificate Revocation List

GetCRL Gets Certificate Revocation List

GetServerCertificateReq Gets server-side certificate request

GetPkiCapabilities Gets PKI capabilities

UpdateCoreFromUrl Updates the Intel AMT firmware by instructing the device to download an image using a URL

GetProvisioningMode Gets the current configuration (provisioning) mode

SetProvisioningMode Sets the configuration (provisioning) mode

CommitChanges Applies pending configuration changes

Unprovision Returns Intel AMT to Factory Mode

PartialUnprovision Puts Intel AMT into a partially-unprovisioned state

ResetFlashWearOutProtection Globally resets the flash wear out mechanism to initial state

GetCoreVersion Returns information about the core capability module

SetPowerSavingOptions Sets various power saving options

GetPowerSavingOptions Gets various power saving options

EnumeratePowerPackages Lists the power packages defined on the platform.

GetActivePowerPackage Returns the identifier of the currently active power package.

GetPowerPackage Returns the policy descriptor string of a selected power package.

SetActivePowerPackage Sets a selected power package to be active.

SetGlobalPowerPolicy Sets the global power policy for a platform.

GetGlobalPowerPolicy Returns the platform global power policy.


17

CertStoreAddKey Adds an asymmetric key pair to the Intel AMT store.

CertStoreGetKey Returns the public portion of a stored key pair.

CertStoreEnumerateKeys Returns a list of the keys in the certificate store.

CertStoreRemoveKey Removes a key pair from the certifcate store.

CertStoreAddCertificate Adds a certificate to the certificate store.

CertStoreGetCertificate Returns a certificate from the certificate store.

CertStoreEnumerateCertificates Returns an array of certificate handles.

CertStoreRemoveCertificate Deletes a certificate from the certificate store.

CertStoreGetPKCS10Request Returns a PKCS#10 request used to renew a certificate.

CertStoreUpdateCertificate Renews an existing certificate.

SetTLSCredentials Sets the certificate used for TLS authentication.

GetTLSCredentials Gets the certificate in use for TLS authentication.

EnableVPNRouting Enables or disables VPN routing of Intel AMT messages.

SetEnvironmentDetection Enables and defines environment detection.

GetEnvironmentDetection Returns environment detection parameters.

SetRealmAuthOptions Defines authentication options for a specific Realm.

GetRealmAuthOptions Returns the authentication options for a selected Realm.

SetMEBxPassword Changes the default MEBx password to a new value.

SetProvisioningServerOTP Sets the setup and configuration one-time password.

GetProvisioningServerOTP Returns the setup and configuration one-time password.

EnumerateCertificateHashEntries Returns a list of the certificate hashes.

GetCertificateHashEntry Returns a certificate hash.

AddCertificateHashEntry Adds a certificate hash to the store of hashes.

DeleteCertificateHashEntry Deletes a certificate hash.

EnableCertificateHashEntry Enables or disables a certificate hash.

GetZeroTouchConfigurationMode Returns Remote Configuration status.

SetZeroTouchConfigurationMode Enables or disables Remote Configuration.

GetProvisioningAuditRecord Returns parameters of the last time the Intel AMT device was set up.

GetProvisioningPID Returns the PID stored in the device.

ExtendProvisioningPeriod Extends the time available for setup and configuration.

SetConfigurationServerFQDN Sets the FQDN to be used with “Hello” messages.

GetConfigurationServerFQDN Returns the configuration server FQDN.


18

7.1.1 Service APIs

7.1.1.1 SetKerberosOptions

This call sets the Kerberos options in the Intel AMT device. In particular, this call enables and disables the Kerberos feature.

Header PT_STATUS SetKerberosOptions( [in, optional] KerberosOptionsType KerberosOptions

);

Compatibility This routine is supported in Intel AMT Release 2.0 and later releases.

Parameters

KerberosOptions are a set of options for enabling Kerberos on the Intel AMT device. If this parameter is missing, then previously set options are deleted and the Kerberos feature is disabled. Return Values One of the following status codes MUST be returned by this method:

Code Description

PT_STATUS_SUCCESS Request succeeded.

PT_STATUS_INTERNAL_ERROR An internal error occurred in the Intel AMT device during this operation.

PT_STATUS_INVALID_PARAMETER

One of the parameters in KerberosOptions is invalid. See KerberosOptionsType for the valid ranges within this structure.

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_DUPLICATE Duplicate SPN type detected

7.1.1.2 GetKerberosOptions

This call queries the Kerberos options from the Intel AMT device.

Header PT_STATUS GetKerberosOptions( [out] KerberosOptionsType KerberosOptions

);

Compatibility

This routine is supported in Intel AMT Release 2.0 and later releases.


19

Parameters

KerberosOptions are a set of options for enabling Kerberos on the Intel AMT device.

Note: confidential parameters such as the KerberosMasterKey should be omitted from the response structure. Return Values One of the following status codes MUST be returned by this method:

Code Description



PT_STATUS_DATA_MISSING Kerberos options are not configured (or have been deleted).

7.1.1.3 SetEnabledInterfaces

This call enables or disables various features or interfaces of the Intel AMT device.

Header PT_STATUS SetEnabledInterfaces( [in] EnabledInterfacesType EnabledInterfaces[]

);

Compatibility


Parameters

EnabledInterfaces are a list of enabled options or interfaces. (Options which are not specified are considered as if they were disabled.) Return Values One of the following status codes MUST be returned by this method:

Code Description



PT_STATUS_INVALID_PARAMETER Specified parameter is invalid



20

Remarks

When both IDER and SOL protocols are disabled, the listening sockets state is automatically disabled. For more details please refer to the SetRedirectionListenerState() command.

Note: This call may succeed but SOL and IDER may still be blocked because of a BIOS MEBx override.

7.1.1.4 GetEnabledInterfaces

This call gets the enabled state of various features or interfaces of the Intel AMT device.

Header PT_STATUS GetEnabledInterfaces( [out] EnabledInterfacesType EnabledInterfaces[]

);

Compatibility


Parameters

EnabledInterfaces are a list of enabled options or interfaces. (Options that are not specified are considered as if they are disabled.)

Return Values One of the following status codes MUST be returned by this method:

Code Description



Remarks

Note: When both IDER and SOL features are disabled in the MEBx, SOL and IDER settings will be omitted from the response regardless of the success of the SetEnabledInterfaces() call.

7.1.1.5 SetTlsEnabled SetTlsEnabled sets the value of the Intel AMT TlsEnabled operational parameter. When TlsEnabled is “true”, then Transport Layer Security (TLS) is used for data confidentiality on all Intel AMT network connections. When it is “false”, then Intel AMT data is transported in the clear. Settings made by this routine are stored after CommitChanges() command is issued and executed successfully. This function is deprecated in favor of SetTLSOptions.


21

Header PT_STATUS SetTlsEnabled( [in] boolean TLSEnabled

);

Compatibility This routine is supported in Intel AMT Release 1.0. It is deprecated in Intel AMT Release 2.0 and later releases in favor of SetTlsOptions.

Parameters

TlsEnabled

Specifies whether TLS is enabled.


Code Description


PT_STATUS_INVALID_PT_MODE The configuration mode of the Intel AMT device does not support configuring TLS.


7.1.1.6 SetTlsOptions

This call sets various TLS modes such as enablement and authentication for the local interface host.

Header PT_STATUS SetTlsOptions(

[in] TlsOptionsType TlsOptions[] );

Compatibility

This routine is supported in Intel AMT Release 2.0 and later releases. This routine should be used instead of SetTlsEnabled(), which is deprecated.

Parameters

TlsOptions are a list of interfaces associated with operational modes. Caller should specify only one operational option per interface. Interfaces which are not specified will operate in NoAuth mode. Return Values One of the following status codes MUST be returned by this method:


22

Code Description




PT_STATUS_NOT_PERMITTED

The specified configuration is not permitted or unsupported. This value may be returned, for example, if the caller enabled TLS but the Private Key was not configured or if Mutual Authentication on one of the interfaces fails because there are no Trusted Root certificates installed.

PT_STATUS_INVALID_PT_MODE The provisioning mode of the Intel AMT device does not support configuring TLS.

Remarks

This call is a superset of the SetTlsEnabled (which is left for backwards compatibility reasons). Developers should use this call in future products.

To disable TLS for a given interface, specify NoAuth as a value to for the respective TlsEnabled element in the list.

For backwards compatibility concerns, when the SetTlsEnabled routine is called, the internal state of the network and local interfaces is toggled between NoAuth and ServerAuth states.

In Intel AMT Release 2.0 the operational modes in the table below apply to the network interface and the local host interface. Both interfaces must have TLS enabled or both must be configured to not require authentication:

NetworkInterface LocalHostInterface

NoAuth NoAuth

ServerAuth ServerAuth

ServerAuth MutualAuth

MutualAuth ServerAuth

MutualAuth MutualAuth

Settings made by this routine are stored after CommitChanges() command is issued and executed successfully.

7.1.1.7 GetTlsOptions

This call gets the currently used authentication modes of TLS.


23

Header PT_STATUS GetTlsOptions(

[out] TlsOptionsType TlsOptions[] );

Compatibility


Parameters

TlsOptions are a list of interfaces associated with operational modes. Interfaces which are not specified should be treated as in NoAuth mode.


Code Description



Remarks

For backwards compatibility concerns, when the SetTlsEnabled routine is called, the internal state of the network interface is toggled between NoAuth and ServerAuth states.

7.1.1.8 SetTLSKeyAndCertificate SetTLSKeyAndCertificate sets the RSA public/private key pair and the TLS Server Certificate Chain used by the Intel AMT device. Note: the RSA public key appears in the certificate.

Header PT_STATUS SetTLSKeyAndCertificate( [in, optional] RsaKeyType PrivateKey, [in] CertificateChainType CertificateChain

);

Compatibility For devices with Intel AMT Release 2.0 technology, the supported RSA key pair size and the maximum supported certificate chain size are reported by GetPkiCapabilities. This will be the case even if the platform is configured for 1.0 Legacy mode.

For devices with Intel AMT Release 1.0 technology, the supported RSA key pair size is 1024 or 1536 bits. The maximum supported certificate chain size is 3600 bytes.


24

Devices with Intel AMT only support RSA key pairs with a public key length of 1536 bits. This API is deprecated in Release 2.5 and later releases in favor of CertStoreGetCertificate() and GetTLSCredentials().

Parameters PrivateKey is an RSA Private Key. The corresponding public key should appear within the Certificate Chain.

CertificateChain is an X.509v3 certificate chain. The public key field of CertificateChain must contain an RSA public key. Certificates will be produced by third-party Certificate Authorities (CAs).



Code Description PT_STATUS_SUCCESS Request succeeded.


One of the input parameters is invalid. Note that some versions of Intel AMT devices cannot detect inconsistency within the Certificate Chain or non-matching private and public keys.


PT_STATUS_INVALID_KEY Private Key is invalid

PT_STATUS_CERT_KEY_NOT_MATCH Certificate Chain and Private Key do not match

7.1.1.9 SetTLSPSK

This call configures the TLS-PSK to be used when moving to the partial-unprovision state.

Header PT_STATUS SetTLSPSK(

[in] BinaryData PID, [in] BinaryData PPS );

Compatibility



25

Parameters

PID is the PID setting for TLS PSK (should be 8 bytes long).

PPS is the PPS setting for TLS PSK (should be 32 bytes long). Return Values One of the following status codes MUST be returned by this method:

Code Description



PT_STATUS_INVALID_PARAMETER Malformed input parameter

Remarks

This call sets the TLS PSK parameters, to be used when Intel AMT is partially-unprovisioned. When both PPS and PID are set have zero data – Intel AMT clears and disables TLS PSK mode.


For more information, please refer to PartialUnprovision() API.

7.1.1.10 SetRngKey

This call sets the internal Pseudo Random Generator Seed.

Header PT_STATUS SetRngKey(

[in] RngKeyType Key );

Compatibility For devices with Intel AMT Release 1.0 technology, the expected RNG Seed length is 20 bytes.

For devices with Intel AMT Release 2.0 or later technology, the expected RNG Seed length is 20 bytes or more (reserved for future compatibility). This also applies to devices configured to run in Intel AMT Release 1.0 Legacy mode.

This API is deprecated as of Intel AMT Release 3.0. The local RNG is seeded automatically using dedicated hardware mechanisms.

Parameters

Key is a binary random seed which is used for scrambling the internal seed. Return Values One of the following status codes MUST be returned by this method:


26

Code Description


PT_STATUS_INVALID_PARAMETER Key is invalid. (Often, this result is returned because of a length problem).


PT_STATUS_FLASH_WRITE_LIMIT_EXCEEDED

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

Remarks

This command sets the key used by the Intel AMT device for its pseudo-random number generator.

Key must be initialized with the type, length, and data bytes with random content.

Intel AMT will fail if the Key length is too short but will process large Key values as long as the overall SOAP message size can be processed.

7.1.1.11 SetTLSCertificate SetTLSCertificate installs a TLS certificate chain to the Intel AMT device.

Header PT_STATUS SetTLSCertificate( [in] CertificateChainType CertificateChain

);

For devices with Intel AMT Release 2.0 technology, the maximum supported certificate chain size is reported by GetPkiCapabilities. This also applies when the device is configured in Intel AMT Release 1.0 Legacy mode.

For devices with Intel AMT Release 1.0 technology, the maximum supported certificate chain size is 3600 bytes. This API is deprecated in Release 2.5 and later releases in favor of CertStoreAddCertificate(), CertStoreUpdateCertificate(), and SetTLSCredentials().

Parameters CertificateChain is an X.509v3 certificate chain. Certificates will be produced by third-party Certificate Authorities (CAs).

Note: SetTLSCertificate should be called only if a private key is stored in the Intel AMT device, (i.e., after SetTLSKeysAndCertificate and CommitChanges were executed successfully.) Otherwise, SetTLSKeysAndCertificate should be used.


27



Code Description


PT_STATUS_INVALID_PARAMETER Certificate Chain is invalid.

PT_STATUS_DATA_MISSING The Intel AMT device was not configured with an RSA Private Key.


PT_STATUS_CERT_KEY_NOT_MATCH Certificate Chain and Private Key do not match

PT_STATUS_INVALID_PT_MODE Invalid mode, See section 7.1.3

7.1.1.12 GetTLSCertificate GetTLSCertificate returns the TLS Server certificate chain currently used by the Intel AMT device.

Header PT_STATUS GetTLSCertificate( [out] CertificateChainType CertificateChain

);

Compatibility This routine is supported in Intel AMT Release 1.0 and Intel AMT Release 2.0/2.1.

This API is deprecated in Release 2.5 and later releases in favor of CertStoreGetCertificate() and GetTLSCredentials().

Parameters If the request succeeds, CertificateChain contains the TLS Server X.509v3 certificate chain currently used by the Intel AMT device.


Code Description




28

PT_STATUS_INVALID_PT_MODE Invalid mode, See section 7.1.3

7.1.1.13 GetServerCertificateReq

This call gets a PKCS#10 certificate request from the Intel AMT device.

Header PT_STATUS GetServerCertificateReq(

[out] BinaryData CertReq );

Compatibility This routine is supported in Intel AMT Release 2.0. It is deprecated in Intel AMT Release 2.5 and later releases in favor of CertStoreGetPKCS10Request().

Parameters

CertReq is a binary representation of the certificate request. Return Values One of the following status codes MUST be returned by this method:

Code Description



PT_STATUS_PKI_MISSING_KEYS The device does not have private key material.

PT_STATUS_PKI_GENERATING_KEYSThe device is currently generating a key pair. Caller may try repeating this operation at a later time. This status code is reserved for future compatibility

PT_STATUS_INVALID_PT_MODE Invalid mode, See section 7.1.3.

Remarks

This call obtains the Certificate request (in the format of PKCS#10, according to RFC 2986) from the Intel AMT device so that it could be submitted to a third party CA, which can then issue (re-issue) a Certificate back to the device.

For future compatibility, this routine should be used first during the configuration process. If the Intel AMT device responds with a Certificate request, it should be interpreted as if the device generated key material internally, which is considered more secure.

A caller that receives the binary representation may generate a PKCS#10 text file by enclosing a Base64 representation of the CertReq between “-----BEGIN CERTIFICATE REQUEST-----” and “-----END CERTIFICATE REQUEST-----”, and storing the output in a text file.


29

The parameters in the certificate request are based on the last certificate which was set previously.

7.1.1.14 GetPkiCapabilities

This call gets the PKI capabilities of the Intel AMT device.

Header PT_STATUS GetPkiCapabilities(

[out] PkiCapsType PkiCaps );

Compatibility


Parameters

PkiCaps is a PKI capabilities structure report for the Intel AMT device. Return Values One of the following status codes MUST be returned by this method:

Code Description



Remarks

Caller may use this routine to determine the Public Key Infrastructure capabilities of the Intel AMT device.

The returned information may differ, depending on the Intel AMT version.

7.1.1.15 UpdateCoreFromUrl UpdateCoreFromUrl updates the core CPMP capability module by instructing the device to download the image using a TFTP URL.

The request will fail if the FW-Update feature is disabled.

Header PT_STATUS UpdateCoreFromUrl( [in] IPv4AddressType TftpServerIp, [in, optional] string TftpServerName, [in] uint16 TftpServerPort, [in] uint16 MagicPacketPort, [in] string PackagePath, [in] AMTVersionType AmtAppVersion, [in] AMTVersionType UpdateAppVersion,


30

[in] IPv4AddressType MgmtConsoleAddr, [in] UpdateCoreUrlKeyType Key

);

Compatibility This routine is supported in Intel AMT Release 1.0 but is not supported in Intel AMT Release 2.0 or later releases or in Intel AMT Release 1.0 Legacy mode.

Parameters TftpServerIp specifies the IP address of the TFTP server used for image download.

TftpServerName specifies the DNS name of the TFTP server used for image download.

If TftpServerIp value is 0xffffffff or 0, then TftpServerName must be specified. Otherwise, TftpServerName is ignored.

TftpServerPort specifies the port number of the TFTP server used for image download.

MagicPacketPort specifies the port number the Intel AMT device should listen on for magic packets.

PackagePath specifies the location of the new core image relative to the TFTP server root.

AmtAppVersion specifies the Intel AMT Application version of the new core image.

UpdateAppVersion specifies the Intel AMT Update Application version of the new core image.

MgmtConsoleAddr is the IP address of the management machine to which the Intel AMT device will send success or failure PETs. Note: MgmtConsoleAddr must not change until FW update process succeeds.

Key is a signature used to verify the downloaded image.


Code Description

PT_STATUS_SUCCESS Request succeeded. Intel AMT device started the image download. (This does not indicate the completion of the operation).

PT_STATUS_INVALID_PARAMETER One of the input parameters sent to the command is invalid.

PT_STATUS_INVALID_PROVISIONING_STATE Intel AMT is not in “provisioning” state (Setup Mode).

PT_STATUS_INVALID_AUTH_TYPE Key.KeyAlgorithm is invalid.


PT_STATUS_NOT_PERMITTED Request failed, since FW-update feature is disabled.


31

7.1.1.16 CommitChanges

This call commits pending configuration commands made to the Intel AMT device.

Header PT_STATUS CommitChanges();



Code Description

PT_STATUS_SUCCESS Request succeeded. Intel AMT device moved to provisioned state (operational mode).

PT_STATUS_DATA_MISSING Essential data missing for completing setup and configuration. Intel AMT device remains in Setup Mode.



Remarks

This routine commits pending configuration commands which are dependent on an internal restart sequence or a cumulative validity check. (Commands that require a call to CommitChanges() are specifically documented as such). Failure to execute this command prevents the pending configurations (which are not stored in flash memory) to take effect. Operations (or situations such as a power loss) that immediately change flash memory depend on a call to CommitChanges()to refresh the internal Firmware state.

Note:

1. If TLS is enabled, RSA Key and Certificate must be configured in order to work properly with the changes being committed.

2. If DHCP is enabled, host-name must be set.

3. If mutual authentication is configured, then at least one trusted root certificate must exist.

4. If in EnterpriseMode Provisioning, then caller must update the internal clock and change the PRNG by calling SetRngKey().

Since committing changes may cause an internal restart sequence, remote applications should allow sufficient time for Intel AMT to reload before issuing the next command.


32

Below is a list of commands that modify the flash when they are executed but require CommitChanges() to cause a reset sequence:

AddTrustedRootCertificate(), SetTrustedFqdnCN(), SetCRL(), SetPowerSavingOptions(), CertStoreUpdateCertificate().

The list of commands below will not modify the flash until CommitChanges() is issued and performed successfully. Their settings will be lost if the platform loses power before processing the CommitChanges() command:

SetTLSEnabled(), SetTLSOptions(), SetTLSKeyandCertificate(), SetTLSPSK(), SetTLSCertificate(), SetTcpIpParameters(), SetVlanParameters(), SetHostName(), SetDomainName().

7.1.1.17 ResetFlashWearOutProtection ResetFlashWearOutProtection resets the wear-out protection to the initial state for all protected flash sectors. At the initial state, each sector is granted sufficient Erase or Write Operations for the device to work correctly. This operation should be used only in rare occasions such as during setup and configuration or following contamination from a malicious application that caused a denial-of-service (DoS) attack by consuming the entire credit for flash erase operations.

Header PT_STATUS ResetFlashWearOutProtection(

);



Code Description



7.1.1.18 GetCoreVersion

Reads version information from the Intel AMT device.

Header PT_STATUS GetCoreVersion(

[out] string Version );


33


Parameters Version is a string describing the device version.


Code Description



Remarks

GetCoreVersion returns version information about the device. If the operation succeeds, then Version contains version information about the device.

The format of the string is XX.YY.ZZZZ where XX is a Major version, YY is a Minor version and ZZZZ is a Micro version.

7.1.1.19 Unprovision Un-Provisioning resets the Intel AMT device to default factory settings. The device will need to go through the setup and configuration process after this command.

Header PT_STATUS Unprovision( [in] ProvisioningModeType ProvisioningMode

);

Compatibility This routine is supported in Intel AMT Release 1.0 and and later releases.

Parameters ProvisioningMode indicates the provisioning mode (Enterprise or Small Business) the device will enter following successful completion of the command.


Code Description


PT_STATUS_INVALID_PARAMETER ProvisioningMode is invalid.


34


PT_STATUS_NOT_PERMITTED Command is invalid when system administrator is currently within the Intel® ME BIOS extension.

7.1.1.20 PartialUnprovision

This command puts Intel AMT into a partially-unprovisioned state.

Header PT_STATUS PartialUnprovision(

);

Compatibility



Code Description




• Cannot execute this command in Small Business mode

• Missing TLS-PSK keys

• Command is invalid when system administrator is currently within the Intel® ME BIOS extension.

Remarks

This command puts Intel AMT into a Partial Unprovision state. The effect of this command is similar to calling the Unprovision() command (with ProvisioningMode set to ‘Enterprise’).

The only difference is that the following settings remain unchanged:

• Admin ACL settings (name and password)

• TLS-PSK keys

• Host name

• Provisioning server IP and port number

• Domain name


35

For additional information, please refer to the SetTLSPSK() API.

7.1.1.21 GetProvisioningMode This operation is used to get the current provisioning mode (Enterprise or Small Business) from the Intel AMT device.

Header PT_STATUS GetProvisioningMode( [out] ProvisioningModeType ProvisioningMode;

);


Parameters ProvisioningMode is the current provisioning mode of the device.


Code Description



7.1.1.22 SetProvisioningMode This operation is used to set the current setup type (Enterprise or Small Business) of the Intel AMT device. The command only can be used during Setup Mode.

When changing the mode to Enterprise, TLS will be enabled (by using the SetTlsEnabled() or SetTlsOptions() API calls).

When changing the mode to Small Business, TLS will be automatically disabled.

Header PT_STATUS SetProvisioningMode( [in] ProvisioningModeType ProvisioningMode

);



36

Parameters ProvisioningMode the desired setup type


Code Description


PT_STATUS_INVALID_PARAMETER ProvisioningMode is invalid.

PT_STATUS_INVALID_PROVISIONING_STATE Intel AMT is not in “provisioning” state (Setup Mode).


7.1.2 Service APIs – Access Control Management

7.1.2.1 AddUserAclEntry This function adds an entry to the User Access Control List (ACL).

Header PT_STATUS AddUserAclEntry( [in] UserAclEntryType Entry, [out] UserAclEntryHandleType Handle

);

Compatibility This routine is supported in Intel AMT Release 1.0. It is deprecated in Intel AMT Release 2.0 and later releases in favor of AddUserAclEntryEx.

Parameters

Entry contains the username, password, and realms associated with this user ACL entry.

If the operation is successful, a unique 32-bit ACL entry handle is returned in Handle. This handle can be used in subsequent calls to GetUserAclEntry(), UpdateUserAclEntry(), GetUserAclEntryEx(), UpdateUserAclEntryEx(), and RemoveUserAclEntry().

Return Values

One of the following status codes MUST be returned by this method:


37

Code Description

PT_STATUS_SUCCESS Request succeeded

PT_STATUS_MAX_LIMIT_REACHED User ACL is full

PT_STATUS_INVALID_NAME Entry.Username is invalid, or the username already exists in one of defined ACL entries

PT_STATUS_INVALID_PASSWORD Entry.Password is invalid

PT_STATUS_INVALID_REALM Entry.Realms contains an invalid interface name

PT_STATUS_INTERNAL_ERROR An internal error occurred in the Intel AMT device during this operation


User AccessPermissionType conflicts with the Default Interface Access Permissions of a configured Realm. (This usually happens if a user is added to a Realm which can be accessed only from the local interface.)



Remarks

• Developers using this interface are encouraged to use the AddUserAclEntryEx() routine.

• The newly created ACL entry will be granted with Network access permissions (See AddUserAclEntryEx() for more details).

In Intel AMT Release 3.0 or later, system accounts are denoted by ACL entries that have a prefix of “$$”. Therefore, creating ACL entries with a user name that starts with "$$" is not permitted. Due to backwards compatibility issues, deletion of a system account is silently ignored.

7.1.2.2 AddUserAclEntryEx

This call adds a user entry to the Intel AMT device

Header PT_STATUS AddUserAclEntryEx(

[in] UserAclEntryExType EntryEx, [out] UserAclEntryHandleType Handle );

Compatibility

This routine is supported in Intel AMT Release 2.0 and later releases. This routine should be used instead of AddUserAclEntry(), which is deprecated.


38

Parameters

EntryEx is a user ACL entry descriptor. Upon a successful return, the Handle variable contains a creation handle. Return Values One of the following status codes MUST be returned by this method:

Code Description

PT_STATUS_SUCCESS Request succeeded

PT_STATUS_MAX_LIMIT_REACHED User ACL is full

PT_STATUS_INVALID_NAME Username or SID is either invalid or already exists in one of defined ACL entries

PT_STATUS_INVALID_REALM HandleEx.Realms contains an invalid interface name

PT_STATUS_INTERNAL_ERROR An internal error occurred in the Intel AMT device during this operation

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


- User AccessPermissionType conflicts with the Default Interface Access Permissions of a configured Realm.

- "$$" cannot be used as a naming prefix.

PT_STATUS_MAX_KERB_DOMAIN_REACHED

The FW allows storing an SID from a limited number of domains (the domain is the first 24 Bytes of the SID). This error is returned if the domain within the SID is not one of the used domains and there is no space to store a new domain. Currently, only 4 domains are allowed.

Remarks

This call replaces AddUserAclEntry() for security reasons. The call allows a localized hashed password to be set on the remote Intel AMT device. The localized password, in turn, is used during the process of HTTP Digest Authentication. One of the benefits of a localized hashed password is that it cannot be used for other devices on the network.

Here is the procedure for changing the password:

1. Call GetDigestRealm() to get the Digest Realm string

2. Compute an MD5 hash on a concatenated message which contains: EntryEx.Username, ‘:’, DigestRealm, ‘:’ Password

3. Set EntryEx.Password to the hash result

4. Call AddUserAclEntryEx() providing the EntryEx parameter


39

Note: The caller provides the hashed password, and so has the responsibility to ensure that the password meets the “complex password” requirements. The Intel AMT device will not be able to verify these requirements when receiving the hashed password.

The newly created ACL entry will be granted with network or local access permissions based on the values specified in the UserAclEntryExType structure. However, the entry will be subject to restriction by the Default Interface Access Permissions.


7.1.2.3 EnumerateUserAclEntries This function enumerates entries in the User Access Control List (ACL) in order.

Header PT_STATUS EnumerateUserAclEntries( [in] uint32 StartIndex, [out] uint32 TotalCount, [out] uint32 HandleCount, [out] UserAclEntryHandleListType Handles

);


Parameters The StartIndex parameter indicates the first ACL entry to retrieve. To enumerate the entire list, an application sends this message with StartIndex set to 1. If TotalCount is greater than HandleCount (which indicates that an incomplete list has been returned), then the application can send additional messages to retrieve the remainder of the list, each time setting StartIndex to point to the handle that follows the last one returned in the previous message.

If the parameters are correct, and no User ACL entries exist, then the function will return PT_STATUS_SUCCESS with an empty list and TotalCount = HandleCount = 0.

If the request succeeds, then TotalCount contains the total number of entries in the User ACL, and Handles contains a list of HandleCount entry handles.

Return Values

One of the following status codes MUST be returned by this method: Code Description


PT_STATUS_INVALID_INDEX StartIndex is greater than the last index in the list or is equal to zero.


40


7.1.2.4 GetUserAclEntryEx

This call reads a user entry from the Intel AMT device.

Header PT_STATUS GetUserAclEntryEx( [in] UserAclEntryHandleType Handle, [out] UserAclEntryExType EntryEx

);

Compatibility

This routine is supported in Intel AMT Release 2.0 and later releases. This routine should be used instead of GetUserAclEntry(), which is deprecated.

Parameters

Handle

Specifies the ACL entry to fetch. (User ACL entry handles are returned by AddUserAclEntry(), AddUserAclEntryEx(), and EnumerateUserAclEntries().)

EntryEx

A User ACL entry descriptor. If the call is successful, EntryEx contains the requested ACL entry.


Code Description



PT_STATUS_INVALID_HANDLE Handle is invalid.

Remarks

This call reads a user entry.

Note: confidential information, such as password (hash) is omitted or zeroed in the response.


41

7.1.2.5 GetUserAclEntry This function returns a single User Access Control List (ACL) entry, given a handle returned by AddUserAclEntry or EnumerateUserAclEntries.

Header PT_STATUS GetUserAclEntry( [in] UserAclEntryHandleType Handle, [out] UserAclEntryType Entry

);

Compatibility This routine is supported in Intel AMT Release 1.0. It is deprecated in Intel AMT Release 2.0 and later releases in favor of GetUserAclEntryEx.

Parameters Handle

specifies the ACL entry to fetch. User ACL entry handles are returned by AddUserAclEntry() and EnumerateUserAclEntries().

GetUserAclEntry can retrieve an ACL entry associated with a handle returned by AddUserAclEntryEx(), but only if it is a simple, legacy entry (for example, not a Kerberos entry).

Entry

If successful, contains the requested ACL entry. The password field is NULL.

Return Values





7.1.2.6 UpdateUserAclEntry This function updates the attributes of an existing User Access Control List (ACL) entry, given a handle and the updated information.

Header PT_STATUS UpdateUserAclEntry( [in] UserAclEntryHandleType Handle, [in] UserAclEntryType Entry

);


42


Parameters

Handle specifies the ACL entry to update.

Entry specifies the new entry values.

Entry.Username contains a new username.

Entry.Password contains a new password.

Entry.Realms contains a new set of interface names to which the entry has access.

Return Values



PT_STATUS_INVALID_HANDLE Entry.Handle is invalid.

PT_STATUS_INVALID_NAME Entry.Username is invalid.

PT_STATUS_INVALID_PASSWORD Entry.Password is invalid.

PT_STATUS_INVALID_REALM Entry.Realms contains an invalid interface name.




- User AccessPermissionType conflicts with the Default Interface Access Permissions of a configured Realm. (This usually happens if a user is added to a Realm which can be accessed only from the local interface.)

- "$$" cannot be used as a naming prefix

Remarks



43

7.1.2.7 UpdateUserAclEntryEx

This call updates a user entry in the Intel AMT device

Header PT_STATUS UpdateUserAclEntryEx( [in] UserAclEntryHandleType Handle, [in] UserAclEntryExType EntryEx

);

Compatibility

This routine is supported in Intel AMT Release 2.0 and later releases. This routine should be used instead of 3UpdateUserAclEntry(), which is deprecated.

Parameters

Handle is a creation handle to a User ACL entry.

EntryEx is a User ACL Entry descriptor to be updated.


Code Description


PT_STATUS_INVALID_HANDLE EntryEx.Handle is invalid. PT_STATUS_INVALID_NAME EntryEx.Username is invalid.

PT_STATUS_INVALID_REALM EntryEx.Realms contains an invalid interface name.




- A EntryEx.DigestUser cannot be changed to EntryEx.KerberosUser or vice versa.- User AccessPermissionType conflicts with the Default Interface Access Permissions of a configured Realm.

- "$$" cannot be used as a naming prefix.


44


The FW allows storing SID from a limited number of domains (the domain is the first 24 Bytes of the SID). This error is returned if the domain within the SID is not one of the used domains and there is no space to store a new domain. Currently, only 4 domains are allowed.

Remarks

This call replaces UpdateUserAclEntry() for security reasons. The call allows the caller to update a localized hashed password on the remote Intel AMT device. This localized password will be used during the process of HTTP Digest Authentication. One of the benefits of a localized hashed password is that it cannot be used for other devices on the network.

Here is the procedure for changing the password:

1. Call GetDigestRealm() to get the Digest Realm string.

2. Compute an MD5 hash on a concatenated message which contains: EntryEx.Username, “:”, DigestRealm, “:”, Password.

3. Set the EntryEx.Password with the hash result.

4. Call UpdateUserAclEntryEx() providing the EntryEx parameter

Note: the caller provides the hashed password, and so must ensure that the password meets the “complex password” requirements as described in Section 7.1.8.1. The Intel AMT device will not be able to verify these requirements when it receives the hashed password.

In Intel AMT Release 3.0 or later, system accounts are denoted by ACL entries that have a prefix of “$$”. Therefore, creating ACL entries with a user name that starts with "$$" is not permitted. Due to backwards compatibility issues, the deletion of a system account is silently ignored.

7.1.2.8 RemoveUserAclEntry This function removes an entry from the User Access Control List (ACL), given an associated handle with the entry.

Header PT_STATUS RemoveUserAclEntry( [in] UserAclEntryHandleType Handle

);


Parameters Handle specifies the ACL entry to be removed.


45


Code Description




7.1.2.9 SetAdminAclEntry This command has been deprecated. In Intel AMT Release 2.0, use SetAdminAclEntryEx() instead. The Admin ACL is a default administrative account. It exists in the Intel AMT device prior to product shipment. Unlike the other User ACL entries, it cannot be deleted and its realm property cannot be modified. The Admin ACL is also used to authenticate BIOS level access during device configuration.

The default settings of the Admin ACL are:

User: admin

Password: admin

Realm: PTAdministrationRealm

Header PT_STATUS SetAdminAclEntry( [in] AdminAclEntryType Entry

);


Parameters Entry.Username contains the new admin username.

Entry.Password contains a new admin password.


Code Description


PT_STATUS_INVALID_NAME Entry.Username is invalid.

PT_STATUS_INVALID_PASSWORD Entry.Password is invalid.


46


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

Remarks

The ACL entry will be granted with local and network access permissions (subject to restriction by the Default Interface Access Permissions).

In Intel AMT Release 3.0 or later, system accounts are denoted by ACL entries that have a prefix of “$$”. Therefore, creating ACL entries with a user name that starts with "$$" is not permitted.

Developers using this interface are encouraged to use the SetAdminAclEntryEx() routine.

7.1.2.10 SetAdminAclEntryEx

This call updates an Admin entry in the Intel AMT device.

Header PT_STATUS SetAdminAclEntryEx( [in] AdminAclEntryExType EntryEx

);

Compatibility

This routine is supported in Intel AMT Release 2.0 and later releases. This routine should be used instead of 3SetAdminAclEntry(), which is deprecated.

Parameters

EntryEx is an admin ACL Entry descriptor.


Code Description


PT_STATUS_INVALID_NAME EntryEx.Username is invalid.




47

Remarks

This call replaces SetAdminAclEntry() for security reasons. The call allows the caller to update a localized hashed password on the remote Intel AMT device. This localized password will be used during the process of HTTP Digest Authentication. One of the benefits of a localized hashed password is that it cannot be used for other devices on the network.

Here is the procedure for changing the administrative password:

2. Call GetDigestRealm() to get the Digest Realm string.

3. Compute an MD5 hash on a concatenated message which contains: EntryEx.Username, “:”, DigestRealm, “:”, Password.

4. Set the EntryEx.Password with the hash result.

5. Call SetAdminAclEntryEx() providing the EntryEx parameter

Note: the caller provides the hashed password, and so must ensure that the password meets the “complex password” requirements as described in Section 7.1.8.1. The Intel AMT device will not be able to verify these requirements when it receives the hashed password.

In Intel AMT Release 3.0 or later, system accounts are denoted by ACL entries that have a prefix of “$$”. Therefore, creating ACL entries with a user name that starts with "$$" is not permitted.

Developers using this interface are encouraged to use the SetAdminAclEntryEx() routine. The ACL entry will be granted with local and network access permissions (subject to restriction by the Default Interface Access Permissions.)

7.1.2.11 GetAdminAclEntry This call returns the username attribute of the Admin ACL.

Header PT_STATUS GetAdminAclEntry(

[out] string Username );


Parameters Username contains the username of the Admin ACL.


Code Description




48

7.1.2.12 GetDigestRealm

This call returns the Intel AMT device Digest Authentication Realm (RFC 2617).

Header PT_STATUS GetDigestRealm( [out] string DigestRealm

);

Compatibility


Parameters

Upon successful return, DigestRealm contains the Intel AMT Digest Authentication Realm parameter as defined by RFC 2617. Return Values One of the following status codes MUST be returned by this method:

Code Description



Remarks

This API provides a Digest Realm value which can later be used to add or modify a user password without transmitting the password over the network. This parameter may include a machine UUID or a random value which is unique for the platform. Callers of this routine can assume that the returned value will never change.

7.1.2.13 SetAclEnabledState

This call enables or disables a User ACL entry.

Header PT_STATUS SetAclEnabledState( [in] UserAclEntryHandleType Handle, [in] boolean Enabled

);

Compatibility



49

Parameters Handle

Specifies the ACL entry. User ACL entry handles are returned by EnumerateUserAclEntries().

Enabled

TRUE if the entry should be enabled; FALSE if the entry should be disabled.


Code Description





Remarks

When this function returns successfully, a User ACL entry should be either in an 'enabled' or 'disabled' state. An ACL entry which is in the 'disabled' state prevents the user from being able to authenticate (logon) to Intel AMT and to issue commands.

Disabling ACL entries is useful when accounts that cannot be removed (system accounts) must be disabled.


7.1.2.14 GetAclEnabledState

This call retrieves the state of a user ACL entry,and whether it is 'enabled' or 'disabled'

Header PT_STATUS GetAclEnabledState( [in] UserAclEntryHandleType Handle, [out] boolean Enabled

);

Compatibility


Parameters Handle


50

Specifies the ACL entry. User ACL entry handles are returned by EnumerateUserAclEntries().

Enabled

TRUE if the entry is enabled, FALSE if the entry is disabled.


Code Description




Remarks

A User ACL entry is either in a 'enabled' or 'disabled' state (by default, it is enabled after creation). An ACL entry which is in a 'disabled' state prevents the User from being able to authenticate (/logon) to Intel AMT and to issue commands. Disabling ACL entries is useful when accounts that cannot be removed (system accounts) must be disabled.


7.1.3 Service APIs – Certificate Management This section defines complementary certificate store API definitions.

These definitions apply to various cryptographic capabilities which use RSA Keys and certificates for authentication or encryption purposes.

Mutual exclusion of Legacy API:

Intel AMT 2.5 deprecates the following TLS Server Certificate configuration APIs:

SetTLSKeyAndCertificate(), SetTLSCertificate(), GetTLSCertificate(), GetServerCertificateReq().

When using new API to configure TLS Server Certificate (SetTLSCredentials() ),

Some of the legacy APIs are obsolete (SetTLSCertificate(), GetTLSCertificate() ).


51

When using Legacy API to configure TLS Server Certificate (SetTLSKeyAndCertificate() ) the obsolete APIs will be usable again: however, GetTLSCredentials() will not be able to reflect the configuration and will fail.

7.1.3.1 AddTrustedRootCertificate

This call adds a trusted root certificate to the Intel AMT device.

Header PT_STATUS AddTrustedRootCertificate(

[in] CertificateType Certificate, [out] CertificateHandleType CertHandle );

Compatibility


Parameters

Certificate is an X.509 encoded certificate.

CertHandle is a reference handle to the certificate. Return Values One of the following status codes MUST be returned by this method:

Code Description



PT_STATUS_MAX_LIMIT_REACHED Cannot add the certificate as the maximum storage limit for certificates was reached.


PT_STATUS_NOT_PERMITTED Caller tried to add a trusted root certificate but TLS mutual authentication is enabled on one of the interfaces.

PT_STATUS_DUPLICATE Entry already exists in the store.

PT_STATUS_INVALID_CERT Invalid certificate parameter.

Remarks

The trusted root certificates are used when TLS is set to mutually authenticate.

For storage limit capabilities, please refer to GetPkiCapabilities.


52

Settings made by this routine are stored but not used until a CommitChanges() command is issued and executed successfully or Intel AMT has been restarted.

Changing the Root Certificate store is allowed only if TLS mutual authentication is currently inactive. (This feature helps to preserve consistency in a situation such as a power loss.)

7.1.3.2 GetTrustedRootCertificate

This call gets the trusted root certificate from an Intel AMT device.

Header PT_STATUS GetTrustedRootCertificate(

[in] CertificateHandleType CertHandle , [out] CertificateType Certificate );

Compatibility


Parameters

CertHandle is a reference handle to the certificate.

Certificate is an X.509 encoded certificate.


Code Description



PT_STATUS_INVALID_PARAMETER The reference handle to a certificate does not exist

Remarks

The trusted root certificates are used when TLS is set for mutual authentication.

7.1.3.3 DeleteTrustedRootCertificate

This call deletes a trusted root certificate from an Intel AMT device.


53

Header PT_STATUS DeleteTrustedRootCertificate(

[in] CertificateHandleType CertHandle );

Compatibility


Parameters

CertHandle is a certificate reference handle. Return Values One of the following status codes MUST be returned by this method:

Code Description



PT_STATUS_INVALID_PARAMETER The reference handle to a certificate does not exist.


• Caller tried to delete the trusted root certificates but TLS Mutual authentication is enabled on one of the interfaces.

• Certificate can not be deleted as it may be referenced from an existing 802.1X Profile

Remarks


Changing the Root Certificate store is allowed only if TLS mutual authentication is currently inactive. (This feature helps to preserve consistency in a situation such as a power loss.)

7.1.3.4 EnumerateTrustedRootCertificates

This call enumerates trusted root certificates from an Intel AMT device.

Header PT_STATUS EnumerateTrustedRootCertificates(

[out] CertificateHandleType CertHandle[] );

Compatibility



54

Parameters

CertHandle[] is an array of reference handles to the certificates. Return Values One of the following status codes MUST be returned by this method:

Code Description



Remarks

This call gets the list of trusted root certificate handles.


7.1.3.5 SetTrustedFqdnCN

This call sets a list of FQDN suffixes to be verified during the TLS handshake protocol.

Header PT_STATUS SetTrustedFqdnCN(

[in] string FqdnSuffix[] );

Compatibility


Parameters

FqdnSuffix is a list of string elements (max 5 elements in a list where each element is limited to 64 maximum characters), containing a FQDN suffix. If the list is empty, then FQDN suffix checking is turned off. Return Values One of the following status codes MUST be returned by this method:

Code Description





55


Remarks

The Intel AMT device validates incoming client certificates based on the root of trust configured.

Additionally, when configured to do so, the device can verify that the leaf certificate Common Name (CN) field of an incoming certificate matches a predefined FQDN suffix as an additional security check.

Settings made by this routine are stored but not used until a CommitChanges() command is issued and executed successfully or Intel AMT has been restarted.

7.1.3.6 GetTrustedFqdnCN

This call gets a list of FQDN suffixes to be verified during the TLS handshake protocol.

Header PT_STATUS GetTrustedFqdnCN(

[out] string FqdnSuffix[] );

Compatibility


Parameters

FqdnSuffix is a list of string elements, containing a FQDN suffix. If the list is empty (or Null), then the FQDN suffix checking is turned off. Return Values One of the following status codes MUST be returned by this method:

Code Description



Remarks

The Intel AMT device validates incoming client certificates based on the root of trust configured.

Additionally, when configured to do so, the device can verify that the CN field of an incoming certificate matches a predefined FQDN suffix as an additional security check.


56

7.1.3.7 SetCRL

This call sets a Certificate revocation list to be used by the Intel AMT device.

Header PT_STATUS SetCRL(

[in] CrlType Crl[] );

Compatibility


Parameters

Crl is a list of Certificate revocation list descriptors. Return Values One of the following status codes MUST be returned by this method:

Code Description



PT_STATUS_INVALID_PARAMETER Specified parameter is invalid.


PT_STATUS_MAX_LIMIT_REACHED Input is beyond the storage limit of the device

Remarks

The Intel AMT device uses a Certificate Revocation List (CRL) while mutually authenticating with a remote entity. This routine allows distribution of a CRL by a management console.

Specifying CRL information overrides any previous configuration. Specifying an empty list will remove the usage of CRL during the authentication process.

A Certificate Authority (CA) should be configured to issue certificates that have a “CRL Distribution points” field so that this command can be used later to revoke the certificates. The CRL Distribution Points field should have an HTTP distribution point type, as Intel AMT does not support LDAP and other distribution point types. Intel AMT compares the CRL Distribution Point and serial number information included in the peer certificate with the contents of the stored revocation list. Intel AMT rejects certificates that match those in the CRL.

For Intel AMT Releases 2.0, 2.1, and 2.2 only: Settings made by this routine are stored but not used until a CommitChanges() command is issued and executed successfully or Intel AMT has been restarted.


57

7.1.3.8 GetCRL

This call returns a Certificate revocation list used by the Intel AMT device.

Header PT_STATUS GetCRL(

[out] CrlType Crl[] );

Compatibility


Parameters

Crl is a list of Certificate revocation list descriptors. Return Values One of the following status codes MUST be returned by this method:

Code Description



Remarks

The Intel AMT device uses a Certificate Revocation List (CRL) while mutually authenticating a remote entity. This routine retrieves the CRL from the Intel AMT device.

7.1.3.9 CertStoreAddKey

This call adds an asymmetric key pair to the Intel AMT store.

Header PT_STATUS CertStoreAddKey(

[in] KeyPairType KeyPair, [out] KeyPairHandleType KeyPairHandle );

Compatibility



58

Parameters

KeyPair

Key pair to be added

KeyPairHandle

Handle to key pair


Code Description



PT_STATUS_FLASH_WRITE_LIMIT_EXCEEDED Wear out protection failure

PT_STATUS_INVALID_KEY Key pair is invalid

PT_STATUS_MAX_LIMIT_REACHED No space for new key

PT_STATUS_DUPLICATE A duplicate key pair already exists.

Remarks

This API adds a key pair (public key and private key) to the Intel AMT device. The key pair may be used for various cryptographic usages (for example: NAC posture signing, or TLS encryption protocol).

Note: since the SetTLSKeyAndCertificate() API is deprecated, a program that wishes to add a TLS certificate should call this routine to add a private and public key; call CertStoreAddCertificate() to add a certificate and associate the certificate using the SetTLSCredentials() call.

7.1.3.10 CertStoreGetKey

This command returns the public portion of a stored key pair.

Header PT_STATUS CertStoreGetKey(

[in] CertificateHandleType KeyPairHandle, [out] KeyPairType PublicKey );


59

Compatibility


Parameters

KeyPairHandle

Handle to key pair

PublicKey

The returned public key of a key pair (the private section is never exportable).


Code Description



PT_STATUS_INVALID_PARAMETER Handle is invalid

Remarks

This routine returns the public section of the key pair. The private section is excluded for security reasons.

7.1.3.11 CertStoreEnumerateKeys

This command lists all the keys in the Intel AMT certificate store or only the key pair associated with a selected certificate.

Header PT_STATUS CertStoreEnumerateKeys(

[in, optional] CertificateHandleType FindByCert, [out] CertificateHandleType KeyPairHandle[] );

Compatibility



60

Parameters

FindByCert

An optional handle to a certificate to look for the matching key pair handle. If this parameter is omitted, all keys will be enumerated.

KeyPairHandle

A returned key pair (private section is never exportable).


Code Description



PT_STATUS_INVALID_PARAMETER Certificate Handle is invalid

7.1.3.12 CertStoreRemoveKey

This command removes a key pair from the certificate store.

Header PT_STATUS CertStoreRemoveKey(

[in] CertificateHandleType KeyPairHandle );

Compatibility


Parameters

KeyPairHandle

A handle to a key pair to be removed.


61


Code Description



PT_STATUS_INVALID_PARAMETER Certificate Handle is invalid


A key pair cannot be removed if its corresponding certificate is referenced (for example, used by TLS, 802.1X or EAC).

7.1.3.13 CertStoreAddCertificate

This command adds a certificate to the certificate store.

Header PT_STATUS CertStoreAddCertificate(

[in] CertificateType Certificate, [out] CertificateHandleType CertHandle );

Compatibility


Parameters

Certificate

An X.509 Certificate to be added

CertHandle

A reference certificate handle.


Code Description



62



PT_STATUS_MAX_LIMIT_REACHED No space for new certificate

PT_STATUS_INVALID_CERT Device does not support the certificate format

PT_STATUS_DUPLICATE A certificate with the exact content already exists.

Remarks

This API is used to add a Certificate to the Intel AMT device. A certificate may have different usages (for example, used by NAC, TLS or 802.1X). Multiple Certificates may have a single matching key added using the CertStoreAddKey() API. Certificates that do not have a matching key are used for reporting certificate chain dependency during authentication.

This API deprecates the old SetTLSKeyAndCertificate() API. Instead, a program that wishes to add a TLS certificate should call the CertStoreAddKey() routine to add a private key, call CertStoreAddCertificate() to add a certificate and associate the certificate using the SetTLSCredentials() call. The certificate store can hold certificates with the same properties as long as they are binary diffrent.

7.1.3.14 CertStoreGetCertificate

This command returns the certificate associated with a certificate handle. Header PT_STATUS CertStoreGetCertificate(

[in] 3CertificateHandleType CertHandle, [out] CertificateType Certificate );

Compatibility


Realm:

Admin Realm

Parameters

CertHandle


63

Handle to key pair

Certificate

Certificate data


Code Description



PT_STATUS_INVALID_PARAMETER Handle is invalid.

7.1.3.15 CertStoreEnumerateCertificates

This command returns an array of certificate handles. The certificates can be filtered by optional parameters.

Header PT_STATUS CertStoreEnumerateCertificates(

[in, optional] string FindByDNName, [in, optional] string FindByUsage, [in, optional] string FindByIssuer, [out] 3CertificateHandleType CertHandles[] );

Compatibility


Parameters

FindByDNName

An optional rule to filter by DN string

FindByUsage

An optional rule to filter by Usage string


64

FindByIssuer

An optional rule to filter by Issuer string

CertHandles

List of certificate handles


Code Description




One of the optional input parameters is formatted incorrectly. For example, FindByDNName can parse "C=Marketing" but it might not know how to parse "Marketing" as an input.

7.1.3.16 CertStoreRemoveCertificate

This command deletes a certificate from the certificate store.

Header PT_STATUS CertStoreRemoveCertificate(

[in] 3CertificateHandleType CertHandle );

Compatibility


Parameters

CertHandle

A handle to a certificate to be removed



65

Code Description



PT_STATUS_NOT_PERMITTED A certificate cannot be removed if it is referenced (for example, used by TLS, 802.1X or EAC).


Remarks

This API will fail as long as CertHandle is a leaf certificate used internally by other components (for example, by TLS, 802.1X or EAC)).

7.1.3.17 CertStoreGetPKCS10Request

This command returns a PKCS#10 request used to renew a certificate.

Header PT_STATUS CertStoreGetPKCS10Request(

[in] CertificateHandleType KeyPairHandle, [in, optional] string DNName, [in, optional] string Usage, [out] BinaryData CertificateRequest;

Compatibility

This routine is supported in Intel AMT Release 2.5 and later releases. In Release 2.5 only, omit the Usage parameter.

Parameters

KeyPairHandle

Handle to key pair.

DNName

The distinguished name (DN) of the entity for which the request is being made. DNName must follow the X.500 naming convention. For example, "CN=User, O=Microsoft.” If a two-letter prefix does not exist, an object identifier (OID) may be provided instead. Intel AMT supportes only these qualifiers: CN, OU, O, S, L, C.


66

Usage

An OID that describes the purpose of the certificate being generated (a.k.a "Extended usage"), for example, an individual or commercial Authenticode certificate, or client authentication. It is also possible to specify multiple OIDs separated by a comma.

The OID is passed through to the PKCS #10 request. The control does not examine the OID. For Intel AMT 2.5, this parameter must be omitted. If the parameter is included, Intel AMT will return an error.

CertificateRequest

A binary representation of the PKCS#10 request.


Code Description




PT_STATUS_UNSUPPORTED Usage parameter is not supported in this release.

Remarks

This API is used to renew a certificate without modifying keys.

This API produces a PKCS#10 certificate request. This command resembles the Microsoft usage of IEnroll4::createFilePKCS10WStr.

If DNName and Usage are Null, Intel AMT will try to build a request based on the machine UUID, host name and domain name.

A caller that receives the binary representation may generate a PKCS#10 text file by enclosing a Base64 representation of the CertReq between “-----BEGIN CERTIFICATE REQUEST-----” and “-----END CERTIFICATE REQUEST-----”, and storing the output in a text file.

7.1.3.18 CertStoreUpdateCertificate

This command renews an existing certificate.

Header PT_STATUS CertStoreUpdateCertificate(

[in] 3CertificateHandleType CertHandle, [in] CertificateType Certificate );


67

Compatibility


Parameters

CertHandle

Handle to key pair

Certificate

Handle to certificate


Code Description




Wear out protection failure (previous settings remain unchanged)

PT_STATUS_CERT_KEY_NOT_MATCH

Certificate and key pair do not match. Current setting remains unchanged.

PT_STATUS_INVALID_CERT Device does not support the certificate format.


PT_STATUS_DUPLICATE A certificate with the exact content already exists.

Remarks

This API is used to renew a certificate without modifying keys. In any case of an error, previous settings remain unchanged.

A caller would usually call GetCertificateRequest() before updating the certificate. Settings made by this routine are stored but not used until a CommitChanges() command is issued and executed successfully or Intel AMT has been restarted.

The certificate store can hold certificates with the same properties as long as their binary values are different.

If the certificate has a matching key and is being referenced (for example, used by TLS, 802.1x, or EAC), a certificate update operation will be possible only if the new certificate has a matching key (i.e. it makes use of a key which was previously added using the CertStoreAddKey() API).


68

7.1.3.19 SetTLSCredentials

This command identifies the certificate to be used for TLS authentication. Header PT_STATUS SetTLSCredentials(

[in,optional] 4CertificateHandleType CertHandle );

Compatibility


Parameters

CertHandle

Handle to a certificate to be used by the TLS server. Null value indicates that TLS certificate should be disassociated.


Code Description




PT_STATUS_INVALID_PARAMETER CertHandle is invalid or a corresponding private key was not found.

Remarks

This API supports configuration of TLS Server using a new set of APIs. Alternately, the internal implementation may support legacy SetTLSKeyAndCertificate() as if a new entry is created into the certificate store. In this case, the entry may be enumerated, but it cannot be deleted as it is referenced virtually from within Intel AMT.

7.1.3.20 GetTLSCredentials

This command retrieves the handle to the certificate in use for TLS authentication.


69

Header PT_STATUS GetTLSCredentials(

[out,optional] 4CertificateHandleType CertHandle );

Compatibility


Parameters

CertHandle

Handle to a certificate used by the TLS server. Null value indicates that no TLS certificate is currently in use.


Code Description



Remarks

This API is used to read the value set by SetTLSCredentials()

7.1.4 Service APIs – Power Settings Intel AMT operates under a selectable set of power schemas, called power packages, defined for the Intel ME. Each package defines ME behavior in Sx states, including whether the ME will reactivate on receipt of traffic over a LAN connection (known as the “wake on LAN” feature.)

The schemas are configurable from the BIOS, from the Intel AMT SOAP interface, and from the WEB-UI.

This section defines a unified API for exposing these schemas and selecting one package to be enabled.

In Intel AMT Release 2.5 and later releases, SetPowerSavingsOptions and GetPowerSavingsOptions are deprecated in favor of the power package functions.

See Power Packages for power package descriptions for the latest releases.


70

7.1.4.1 SetPowerSavingOptions

Sets various power saving options.

Header PT_STATUS SetPowerSavingOptions(

[in] PowerStateType ActiveStateAC, [in, optional] PowerStateType WakeOnNetAccessThresholdAC, [in, optional] uint16 WakeOnNetAccessSleepTimer );

Compatibility This routine is supported in Intel AMT Release 2.0. WakeOnNetAccessSleepTimer is supported from Release 2.1 onward. Release 2.0 ignores this parameter but does not generate an error.

This API is deprecated in Intel AMT Releases 2.5 and 3.0 in favor of the power package and power policy functions – callers should use the SetActivePowerPackage() and SetGlobalPowerPolicy() API.

Parameters

ActiveStateAC

Defines the highest power state at which Intel AMT will operate while the device is connected to AC power. Note that this includes operation in higher power states. For example, if the platform is in S3 and this parameter is set to S0, Intel AMT will not operate. Note that Intel AMT treats S0 and S1 as equivalent states. In releases 2.5 and 3.0, S1 and S2 are invalid values.

WakeOnNetAccessThresholdAC

This parameter is reserved for forward compatibility and should be omitted.

WakeOnNetAccessSleepTimer

Once the Intel AMT device wakes up and the host system is not turned on, this parameter determines the minimum time (in minutes) that the Intel AMT device will remain operable when there is no activity. The device will return to a sleep state after the timer times out. The timer is restarted whenever the device is serving requests. If the value of the parameter is zero, the device will remain on when there is no activity.


Code Description



71

PT_STATUS_INTERNAL_ERROR

An internal error occurred in the Intel AMT device during this operation. In Intel AMT Releases 2.5 and 3.0 and onward, there is no power package that matches the requested parameters.

PT_STATUS_FLASH_WRITE_LIMIT_EXCEEDED Flash wear-out limit reached. Caller may try repeating this operation at a later time.


One of the supplied input parameters is invalid.

(0≤ WakeOnNetAccessSleepTimer ≤ 65535)

PT_STATUS_NOT_PERMITTED Command is invalid when system administrator is currently within the Intel® ME BIOS extension.

Remarks

This call is used to customize the Intel AMT behavior during various system power states. Usage of this command is usually intended to minimize the power consumption of the platform during various system states.

Note that once the device is put to sleep (and allowed to wake-up on network access), the caller should allow sufficient time for the device to go through a restart sequence before issuing network commands. This may be done by waiting a reasonable amount of time (e.g., 30 seconds) and then resending network commands that may have failed.

If the device is put to sleep with no option to wake-up on network access), then the caller might never be responded to.

When the Management Console executes on a platform running Microsoft Vista* or LINUX, it is recommended that WakeOnNetAccessSleepTimer is set no lower than 3 minutes.

While issuing the call, the Intel AMT device will try to adjust to the closest higher (S0>S5) possible power state setting. (An error will not be reported). The caller may read these settings using the GetPowerSavingOptions() routine.

Unless configured differently, the default state after configuration is to stay turned off during Sx power state. It is highly recommended that this value be changed in order to allow manageability even if in lower power states. When returning Intel AMT to Factory Setup Mode, settings made by this routine will not be reset to initial values as they are owned by the BIOS configuration screen and maintained outside of the Intel AMT memory space.

In Releases 2.5 and 3.0, Intel AMT matches the request to a power package. If there is no corresponding power package then the device will return an error.

The following table summarizes Intel AMT behavior due to the possible settings of this command.

ActiveStateAC Setting

When the platform CPU transitions from S0 to S3

When the platform CPU transitions to S5 from any state

PowerStateS0, S1 or S2

Intel AMT turns off until the power state returns to the ActiveStateAC setting.

Intel AMT turns off until the power state returns to the ActiveStateAC setting


72

ActiveStateAC Setting

When the platform CPU transitions from S0 to S3

When the platform CPU transitions to S5 from any state

PowerStateS3 The Intel AMT device stays active; if there is no activity for <WakeOnNetAccessSleepTimer> minutes, the device goes to “sleep” but can be awakened by *network access.


PowerStateS4 The Intel AMT device stays active; if there is no activity for <WakeOnNetAccessSleepTimer> minutes, the device goes to “sleep” but can be awakened by *network access.


PowerStateS5 The Intel AMT device stays active; if there is no activity for <WakeOnNetAccessSleepTimer> minutes, the device goes to “sleep” but can be awakened by a *network access.

The Intel AMT device stays active; if there is no activity for <WakeOnNetAccessSleepTimer> minutes, the device goes to “sleep” but can be awakened by an OOB network access.

*The device awakens based on receiving a directed network access: ARP, ICMP, or TCP/UDP ports 16992 through 16995 network packet directed to the Intel AMT device.

Note: If Intel AMT is configured to use DHCP, then the device may wake-up periodically to renew the lease and go back to sleep.

For Intel AMT Release 2.1 and later releases: settings made by this routine are stored but not used until a CommitChanges() command is issued and executed successfully or Intel AMT has been restarted.

Note: when Intel AMT returns from sleep state, all its memory is re initialized and transient data is lost. (i.e., all operations that are stored only after CommitChanges()).

7.1.4.2 GetPowerSavingOptions

This command returns the power savings settings. This API is deprecated in Intel AMT Releases 2.5 and 3.0 in favor of the power package and power policy functions.

Header PT_STATUS GetPowerSavingOptions( [out] PowerStateType ActiveStateAC, [out, optional] PowerStateType WakeOnNetAccessThresholdAC, [out, optional] uint16 WakeOnNetAccessSleepTimer

);

Compatibility This routine is supported in Intel AMT Release 2.0/2.1.


73

It is deprecated in releases 2.5 and later – callers should use the GetActivePowerPackage() and GetGlobalPowerPolicy() API instead.

Parameters

ActiveStateAC

Defines the highest power state at which Intel AMT will operate while the device is connected to AC power. Note that this includes operation in higher power states. For example, if the platform is in S3 and this parameter is set to S0, Intel AMT will not operate. Note that Intel AMT treats S0 and S1 as equivalent states.

WakeOnNetAccessThresholdAC

Always returns NULL.

WakeOnNetAccessSleepTimer

Once the Intel AMT device wakes up and the host system is not turned on, this parameter determines the minimum time (in minutes) that the Intel AMT device will remain operable when there is no activity. The device will return to a sleep state after the timer times out. The timer is restarted whenever the device is serving requests. If the value of the parameter is zero, the device will remain on when there is no activity.


Code Description



Remarks

This call is used to query the Intel AMT behavior during various system power states. Important note: it is important to read these values after they are set, as the device may adjust the setting to the closest, more restrictive settings that are supported. Please refer to SetPowerSavingOptions() for more information.

7.1.4.3 EnumeratePowerPackages This function returns the GUIDs for all the power packages defined in this Intel AMT instance.

Header PT_STATUS EnumeratePowerPackages(

[out] GuidBuf PolicyGUID[] );


74

Compatibility


Parameters

PolicyGUID

A unique configuration identifier for the power package.


Code Description



Remarks

Unique PolicyGUID values allow software vendors to maintain a global repository of well known GUIDs and a localized version of the policy description. An OEM specifies the power packages enabled in an Intel AMT instance.

7.1.4.4 GetActivePowerPackage This function returns the GUID of the currently active power package.

Header PT_STATUS GetActivePowerPackage(

[out] GuidBuf PolicyGUID );

Compatibility


Parameters

PolicyGUID


75

A unique configuration identifier for the current power package


Code Description



7.1.4.5 GetPowerPackage This function returns a policy descriptor string associated with a selected power policy.

Header PT_STATUS GetPowerPackage(

[in] GuidBuf PolicyGUID, [out] string PolicyDescriptor );

Compatibility


Parameters

PolicyGUID

A unique configuration identifier for the power package

PolicyDescriptor

A policy descriptor


Code Description



PT_STATUS_INVALID_PARAMETER Specified PolicyGUID does not exist


76

Remarks

Use EnumeratePowerPackages and GetActivePowerPackage to retrieve the GUID of all power packages or the current active power package, then use this command to request the descriptive string based on a selected GUID.

7.1.4.6 SetActivePowerPackage This command sets the active power package to the one defined by selected GUID.

Header PT_STATUS SetActivePowerPackage(

[in] GuidBuf PolicyGUID );

Compatibility


Parameters

PolicyGUID

A unique configuration identifier for the power package


Code Description



PT_STATUS_INVALID_PARAMETER Specified PolicyGUID does not exist


Remarks

Changes made by this routine do not revert to default values after unprovisioning as these are platform settings and Unprovision applies only to Intel AMT parameters.


77

7.1.4.7 SetGlobalPowerPolicy This functions sets power policy options that apply independent of the selected power package.

Header PT_STATUS SetGlobalPowerPolicy(

[in] GlobalPowerPolicyType GlobalPowerPolicy );

Compatibility


Parameters

GlobalPowerPolicy

Sets a global power policy to be used by Intel AMT.


Code Description




PT_STATUS_INVALID_PARAMETER Settings are unsupported by the device. (0< GlobalPowerPolicy ≤ 65535)

7.1.4.8 GetGlobalPowerPolicy This function returns the current value of the global power policy.

Header PT_STATUS GetGlobalPowerPolicy(

[out] GlobalPowerPolicyType GlobalPowerPolicy );

Compatibility



78

Parameters

GlobalPowerPolicy

Reads the global power policy to be used by Intel AMT.


Code Description



Remarks

Gets the global power policy for Intel AMT.

7.1.5 Service APIs – Environment detection & VPN Connectivity Intel AMT may operate in roaming mobile platforms, which may be connected to a foreign network that is not directly interconnected to the enterprise network.

The current feature set offers this operational scenario:

• Intel AMT may block its network management interface - this is useful when the IT administrator wishes to conceal Intel AMT functionality when operating on foreign networks.

• A host that runs VPN software could be used to route traffic to Intel AMT through the local interface. This mode should allow access to the Intel AMT device even when the platform operates on foreign networks. This mode is possible only if Intel AMT assumes (according to a specified set of rules) that it can operate on a foreign network.

• Intel AMT may apply or remove System Defense policies to enforce host network security. Environment detection maintains a separate state for each network interface.

The following sections describe a unified interface for configuring the environment detection feature.

7.1.5.1 EnableVpnRouting This command is used to enable or disable VPN routing of Intel AMT network messages.


79

Header PT_STATUS EnableVpnRouting(

[in] boolean Enable );

Compatibility

This routine is supported in Intel AMT Release 2.5 and 2.6.

Parameters

Enable

Enables or disables the VPN routing feature.


Code Description



PT_STATUS_FLASH_WRITE_LIMIT_EXCEEDED Wear out protection failure.

Remarks

This Administration Realm command enables or disables the VpnRouting feature that exposes the remote management interface through the local host to be used in a VPN environment.

7.1.5.2 SetEnvironmentDetection

This command enables the environment detection mechanism and defines the operating environment where the manageability interface is permitted to operate.

Header PT_STATUS SetEnvironmentDetection(

[in] EnvironmentDetectionType Params );

Compatibility



80

Parameters

Params

Describes the enterprise operating environment. If the parameter is Null, disables environment detection.


Code Description




PT_STATUS_UNSUPPORTED Configuration is not supported.

PT_STATUS_NOT_PERMITTED Configuration is forbidden (example, user specified an HTTP string in the URL input).

7.1.5.3 GetEnvironmentDetection

Returns the enterprise environment definition.

Header PT_STATUS GetEnvironmentDetection(

[out] EnvironmentDetectionType Params );

Compatibility


Parameters

Params

The domains where the manageability interface is permitted to operate. Environment detection is disabled if this parameter returns Null.



81

Code Description



7.1.6 Service APIs – User Notification Intel AMT is required to:

• Send events to the local machine (local notification). The Intel-supplied User Notification Service defines alerts and logs them to the Windows event log.

• Send network events to any subscribed destination wrapped within SOAP structure. This provides security at the message level and should allow communications with consumers on different Ports or URIs.

7.1.6.1 SetRealmAuthOptions

Header PT_STATUS SetRealmAuthOptions(

[in] UserAclRealmType Realm, [in] HTTPAuthOptionType HTTPAuthOption );

Compatibility


Parameters

Realm

A user Realm to be configured with the desired authentication options (must be equal to LocalUN or EndpointAccessControl)


82

HTTPAuthOption

Authentication option.


Code Description





PT_STATUS_NOT_PERMITTED Changing permission for the specified realm is not allowed.

Remarks

This commands sets all the URIs associated with a given realm to a configured authentication option (authentication is either anonymous, authenticate or disable-access).

Currently, only LocalUN or EndpointAccessControl realms may be manipulated by this API. Note: LocalUN and EndpointAccessControl realms are set to anonymous by default.

7.1.6.2 GetRealmAuthOptions

This command returns the authentication options for a selected Realm. Header PT_STATUS GetRealmAuthOptions (

[in] UserAclRealmType Realm, [out] HTTPAuthOptionType HTTPAuthOption );

Compatibility


Parameters

Realm

A user Realm to be queried


83

HTTPAuthOption

Authentication option which exists for that realm


Code Description




Remarks

This commands reads the authentication option which is configured at a specific Realm (authentication is either anonymous, authenticate or disable-access).

Note: LocalUN and EndpointAccessControl realms are set to anonymous by default.

7.1.7 Service APIs – Provisioning

7.1.7.1 SetMEBxPassword

This command is used to change the MEBx password.

Header PT_STATUS SetMEBxPassword(

[in] string Password );

Compatibility

This routine is supported in Intel AMT Releases 2.2, 2.6 and 3.0.

Parameters

Password

A string containing 8-32 characters meeting the requirements of a strong password.



84

Code Description



PT_STATUS_NOT_PERMITTED Password was already changed.

PT_STATUS_INVALID_PASSWORD Password does not meet the strong password characteristics.

Remarks

This command can be issued only once. It allows a remote caller to change the ME access password for the BIOS extension screen.

This call succeeds only when the current password is still the default value and was not changed.

7.1.7.2 SetProvisioningServerOTP

This command sets the one-time password to be used in a subsequent setup and configuration session.

Header PT_STATUS SetProvisioningServerOTP(

[in, optional] BinaryData OTP );

Compatibility


Parameters

OTP

A binary data value containing 8-32 characters, or Null, to change the one-time password (OTP).


Code Description



85



PT_STATUS_NOT_PERMITTED Intel AMT is not in provisioning state.

PT_STATUS_INVALID_PARAMETER Malformed input parameter.

Remarks

This call sets an OTP from a network entity. The OTP may be set by a local agent using a separate designated interface available locally.

7.1.7.3 GetProvisioningServerOTP

This command returns the setup and configuration one-time password, if one has been set.

Header PT_STATUS GetProvisioningServerOTP(

[out] BinaryData OTP );

Compatibility

This routine is supported in Intel AMT Releases 2.2, 2.6, and 3.0.

Parameters

OTP

A binary data value containing 8-32 characters or Null in case OTP is not set


Code Description



PT_STATUS_NOT_PERMITTED Intel AMT is not in provisioning state.


86

PT_STATUS_NOT_FOUND OTP is not set

Remarks

This call returns an OTP which was previously set by a Local software agent.

7.1.7.4 EnumerateCertificateHashEntries

This command returns a list of handles to the certificate hashes in stored in the Intel AMT device.

Header PT_STATUS EnumerateCertificateHashEntries(

[out] uint32 Handles[] );

Compatibility


Parameters

Handles

An array of handles to hash entries


Code Description


PT_STATUS_NOT_PERMITTED A factory default certificate cannot be deleted or Intel AMT is not in the right provisioning state.


7.1.7.5 GetCertificateHashEntry

This command returns a certificate hash associated with a handle.


87

Header PT_STATUS GetCertificateHashEntry(

[in] uint32 Handle, [out] CertHashEntryType CertHashEntry );

Compatibility


Parameters

Handle

A handle to a certificate hash entry

CertHashEntry

A certificate hash entry descriptor


Code Description



PT_STATUS_NOT_PERMITTED A factory default certificate cannot be deleted or Intel AMT is not in the right provisioning state.

PT_STATUS_INVALID_HANDLE Handle is invalid

Remarks

This call returns the certificate hash entry associated with the handle.

7.1.7.6 AddCertificateHashEntry

This command adds a certificate hash to the store of hashes.

Header PT_STATUS AddCertificateHashEntry(


88

[in] CertHashEntryType CertHashEntry, [out] uint32 Handle );

Compatibility


Parameters

CertHashEntry

A certificate hash entry descriptor. Note that CertHashEntry.Default will be ignored.

Handle

If this call is completed successfully, this variable contains the handle to the newly created certificate hash entry.


Code Description



PT_STATUS_MAX_LIMIT_REACHED Not enough space for storing the given Hash entry.

PT_STATUS_INVALID_PARAMETER Specified parameter is not valid

7.1.7.7 DeleteCertificateHashEntry

This command deletes a selected certificate hash from the store in an Intel AMT device.

Header PT_STATUS DeleteCertificateHashEntry(

[in] uint32 Handle );


89

Compatibility


Parameters

Handle



Code Description




PT_STATUS_NOT_PERMITTED A factory default certificate cannot be deleted or not in the right provisioning state.


Remarks

The caller cannot delete a factory default hash entry. Rather than deleting the hash entry, caller can disable the entry using EnableCertificateHashEntry().

7.1.7.8 EnableCertificateHashEntry

This command enables or disables a selected certificate hash. Header PT_STATUS EnableCertificateHashEntry(

[in] uint32 Handle, [in] boolean Enabled );

Compatibility



90

Parameters

Handle


Enabled

Sets the entry to 'enabled' or 'disabled' when this variable is set to true or false.


Code Description





7.1.7.9 GetZeroTouchConfigurationMode

This command returns a status showing whether Remote Configuration is enabled or disabled (this feature was originally called Zero Touch Configuration).

Header PT_STATUS GetZeroTouchConfigurationMode(

[out] boolean Enabled );

Compatibility


Parameters

Enabled

Indicates if Remote Configuration is enabled or disabled.


91


Code Description



7.1.7.10 SetZeroTouchConfigurationMode

This command enables or disables Remote Configuration (this feature was originally called Zero Touch Configuration).

Header PT_STATUS SetZeroTouchConfigurationMode(

[in] boolean Enabled );

Compatibility


Parameters

Enabled

Indicates if Remote Configuration is enabled or disabled.


Code Description



PT_STATUS_MAX_LIMIT_REACHED Not enough space for storing the given Hash entry.

PT_STATUS_NOT_PERMITTED Intel AMT is not in the right provisioning state. This command cannot be performed while the device is in the in-provisioning state.


92

7.1.7.11 GetProvisioningAuditRecord

This command returns a record of the last time the Intel AMT device was set up.

Header PT_STATUS GetProvisioningAuditRecord(

[out, optional] ProvisioningAuditRecordType ProvisioningAuditRecord );

Compatibility

This routine is supported in Intel AMT Release Releases 2.2, 2.6 and 3.0.

Parameters

ProvisioningAuditRecord

Provisioning audit record descriptor


Code Description



PT_STATUS_DATA_MISSING Provisioning Audit record is not available, machine may have been provisioned manually.

PT_STATUS_NOT_READY The machine has not yet been in a provisioning state.

7.1.7.12 GetProvisioningPID

This command returns the PID from a PID/PPS pair.

Header PT_STATUS GetProvisioningPID(

[out, optional] BinaryData PID );


93

Compatibility


Parameters

PID

The PID part of TLS PSK (Null if not set)


Code Description



7.1.7.13 ExtendProvisioningPeriod

This command defines the time that the network interface is open so that the Intel AMT device is available for setup and configuration.

Header PT_STATUS ExtendProvisioningPeriod(

[in] uint32 Duration );

Compatibility


Parameters

Duration

The duration in hours (limited to maximum value of 24 in each call).



94

Code Description



PT_STATUS_NOT_PERMITTED Intel AMT is not in the right provisioning state.


Remarks

This command allows a configuration server to extend the configuration time, during which Intel AMT is expected to be provisioned. If a configuration server does not call this command within the very first 24 hours in which Intel AMT is waiting to be provisioned, Intel AMT will disable the network interface.

Calling this command with Duration = 0 disables the network interface.

Either the MEBx partial unprovisioning command or a Remote Configuration local agent is required to re-open the network interface.

7.1.7.14 SetConfigurationServerFQDN

This command sets the FQDN of a configuration server to be used by Intel AMT in sending “Hello” messages.

Header PT_STATUS SetConfigurationServerFQDN(

[in] string fqdn );

Compatibility

This routine is supported in Intel AMT Release 3.0.

Parameters

fqdn

A non-empty string defining the FQDN of the configuration server.



95

Code Description




PT_STATUS_INVALID_PARAMETER Input is invalid.

Remarks

Once a configuration server FQDN is set, Intel AMT will try to send “Hello” messages to the specified configuration server and will expect to match this FQDN against the configuration server name in the certificate in PKI mode (servers with unmatched certificate names will not be able to connect).

7.1.7.15 GetConfigurationServerFQDN

This command returns the FQDN of the configuration server stored in the Intel AMT device.

Header PT_STATUS GetConfigurationServerFQDN(

[in] string fqdn );

Compatibility

This routine is supported in Intel AMT Release 3.0.

Parameters

fqdn

The FQDN of the configuration server.


Code Description




96

7.1.8 Service Data Types

7.1.8.1 UserAclEntryType typedef struct _UserAclEntryType { AclStringType Username; AclPasswordStringType Password; UserAclRealmListType Realms; } UserAclEntryType;

Field Description

Username Username for access control. Contains 7-bit ASCII characters, in the range of 33-126, excluding ‘:’, ‘,’, ‘<’, ‘>’, ‘&’, and ‘”’ characters. String length is limited to 16 characters. Username cannot be an empty string.

Password

Password for the user. Contains 7-bit ASCII characters, in the range of 32-126, excluding ‘:’, ‘,’ and ‘”’ characters. String length is limited to 32 characters.

Limitations:

Password Length: Passwords must be least 8 characters long.

Password Complexity: Password must include:

a. At least one Digit character ('0', '1',…'9')

b. At least one 7-bit ASCII non alpha-numeric character, above 0x20, (e.g. '!', '$', ';'). Note that “_” is considered alpha-numeric.

c. Both lower-case Latin ('a', 'b',…,'z') and upper case Latin ('A', 'B',…'Z'). Realms Array of interface names. Interfaces the ACL entry is allowed to access.

7.1.8.2 UserAclEntryExType typedef struct _UserAclEntryExType { choice {

UserEntryDigestType DigestUser ; UserEntryKerberosType KerberosUser ; } u ; AccessPermissionType AccessPermission; UserAclRealmListType Realms;

} UserAclEntryExType;


97

Field Description

DigestUser Descriptor for user which is authenticated using Digest Authentication

KerberosUser Descriptor for user (SID) which is authenticated using Kerberos Authentication

AccessPermission Indicates whether the User is allowed to access Intel AMT from the Network or Local Interfaces. Note: this definition is restricted by the Default Interface Access Permissions of each Realm.

Realms Array of interface names. Interfaces the ACL entry is allowed to access.

7.1.8.3 UserEntryDigestType typedef struct _UserEntryDigestType { AclStringType Username; BinaryData DigestPassword; } UserEntryDigestType;

Field Description


DigestPassword

An MD5 Hash of these parameters concatenated together {Username | DigestRealm | Password}.

The DigestRealm is obtained by calling GetDigestRealm().

The Password should meet the complex password requirements as specified in Section 7.1.8.1.

The Intel AMT device will not be able to check that the caller indeed met these requirements.

7.1.8.4 UserEntryKerberosType

typedef struct _UserEntryKerberosType { BinaryData Sid; } UserEntryKerberosType;


98

Field Description

Sid

Byte array, specifying the Security Identifier (SID) according to the Kerberos specification. Current requirements imply that SID should be not smaller than 1 byte length and no longer than 28 bytes. SID length should also be a multiple of 4.

7.1.8.5 AccessPermissionType

typedef enum<string> _AccessPermissionType {

“LocalAccessPermission”, “NetworkAccessPermission”, “AnyAccessPermission”

} AccessPermissionType;

Field Description

LocalAccessPermission Access permission is permitted to the Local interface.

NetworkAccessPermission Access permission is permitted to the Network interface.

AnyAccessPermission

Access permission is permitted to both Network and Local interfaces. Note:

• This capability should be restricted as much as possible, because it could enable local applications to access remote manageability services.

• This capability is restricted by the Default Interface access permissions defined for each Realm.

7.1.8.6 AclStringType

typedef string AclStringType;

Field Description

AclStringType A string (maximum length 16 bytes).

7.1.8.7 AclPasswordStringType

typedef string AclPasswordStringType;


99

Field Description

AclStringType A string (maximum length 32 bytes).

7.1.8.8 UserAclEntryHandleType

This data type is returned in the Add ACL Entry response message, and is used to reference an ACL entry in subsequent Access Control Manager Interface operations.

typedef uint32 UserAclEntryHandleType;

Field Description

UserAclEntryHandleType A handle to an entry in the User Access Control List (ACL)

7.1.8.9 UserAclEntryHandleListType

typedef struct _UserAclEntryHandleListType { UserAclEntryHandleType *Handle; } UserAclEntryHandleListType;

Field Description

Handle A list of User Access Control List (ACL) entry handles.

7.1.8.10 UserAclRealmType UserAclRealmType enumerates the User Access Control List (ACL) realms used for HTTP digest authentication and SOL/IDER user authentication. These realms allow user authorization at the interface level.

typedef enum<uint32> _UserAclRealmType { InvalidRealm = 0, RedirectionRealm = 2, PTAdministrationRealm = 3, HardwareAssetRealm = 4, RemoteControlRealm = 5, StorageRealm = 6, EventManagerRealm = 7, StorageAdminRealm = 8, AgentPresenceLocalRealm = 9, AgentPresenceRemoteRealm = 10, CircuitBreakerRealm = 11, NetworkTimeRealm = 12, GeneralInfoRealm = 13, FirmwareUpdateRealm = 14, EITRealm = 15,


100

LocalUN = 16, EndpointAccessControlRealm = 17, EndpointAccessControlAdminRealm = 18, EventLogReaderRealm = 19, } UserAclRealmType;

Code Description

InvalidRealm For internal use only.

RedirectionRealm Controls access to redirection interfaces (SOL/IDER).

PTAdministrationRealm Controls access to all Intel AMT exposed interfaces.

HardwareAssetRealm Controls access to the Hardware Asset Interface.

RemoteControlRealm Controls access to the Remote Control Interface.

StorageRealm Controls access to the ISV Storage Interface.

EventManagerRealm Controls access to the Event Manager Interface.

StorageAdminRealm Controls access to the Storage Admin Interface.

AgentPresenceLocalRealm Controls access to the Local Agent Presence Interface.

AgentPresenceRemoteRealm Controls access to the Remote Agent Presence Interface.

CircuitBreakerRealm Controls access to the Circuit Breaker Interface.

NetworkTimeRealm Controls access to the NetworkTime Interface.

GeneralInfoRealm Controls access to the GeneralInfo Interface.

FirmwareUpdateRealm Controls access to the FirmwareUpdate interface.

EITRealm Controls access to the EIT interface.

LocalUNRealm Controls access to the LocalUN interface.

EndpointAccessControlRealm Controls access to the EAC interface.

EndpointAccessControlAdminRealm Controls access to the EAC Admin interface.

EventLogReaderRealm Controls access to the Event Log for reading.

7.1.8.11 AdminAclEntryType

typedef struct _AdminAclEntryType { AclStringType Username; AclStringType Password; } AdminAclEntryType;


101

Field Description


Password

Password for the user. Contains 7-bit ASCII characters, in the range of 32-126, excluding ‘:’, ‘,’ and ‘”’ characters. String length is limited to 32 characters.

Limitations:

1. Password Length: Passwords must be at least 8 characters long.

2. Password Complexity: Password must include:


b. At least one 7-bit ASCII non alpha-numeric character, above 0x20, (e.g. '!', '$', ';'). Note that “_” is considered alphanumeric.

c. Both lower-case Latin ('a', 'b',…,'z') and upper case Latin ('A', 'B',…'Z').

7.1.8.12 AdminAclEntryExType

typedef struct _AdminAclEntryExType { AclStringType Username; BinaryData DigestPassword; } AdminAclEntryExType;

Field Description

Username

Username for access control. Contains 7-bit ASCII characters, in the range of 33-126, excluding ‘:’, ‘,’, ‘<’, ‘>’, ‘&’, and ‘”’ characters. String length is limited to 16 characters. Username cannot be an empty string.

DigestPassword The content of this field has similar content to the DigestPassword field in the UserAclEntryExType structure.

7.1.8.13 EnabledInterfacesType

typedef enum<string> _EnabledInterfacesType {

“WebUI” , “SerialOverLAN” , “IdeRedirection”

} EnabledInterfacesType;


102

Field Description

“WebUI” Enable Web User Interface

“SerialOverLAN” Enable Serial Over LAN

“IdeRedirection” Enable IDE Redirection

7.1.8.14 TlsOptionsType

typedef struct _TlsOptionsType {

InterfaceType Interface; TlsAuthenticationType TlsAuthentication;

} TlsOptionsType;

Field Description

Interface A specified interface

TlsAuthentication Authentication mode

7.1.8.15 InterfaceType

typedef enum<string> _InterfaceType { “NetworkInterface” , “LocalHostInterface” } InterfaceType;

Field Description

“NetworkInterface” Network Interface

“LocalHostInterface” Host Interface (KCS or Intel Management Engine Interface)

7.1.8.16 TlsAuthenticationType

typedef enum<string> _TlsAuthenticationType {

“NoAuth”, “ServerAuth” , “MutualAuth”


103

} TlsAuthenticationType;

Field Description

NoAuth No Authentication (TLS is turned off)

ServerAuth The Intel AMT authenticates as a server

MutualAuth The Intel AMT authenticates as a server and requires a client side certificate

7.1.8.17 CertificateType

typedef BinaryData CertificateType ;

Field Description

CertificateType Binary representation of the X.509 certificate

7.1.8.18 CrlType

typedef struct _CrlType {

string CrlUrl; BinaryData SerialNumber[];

} CrlType;

Field Description

CrlUrl The issuer URL of the revoked certificates.

SerialNumber A list of serial numbers removed by the CA which is specified in the CrlUrl variable.

7.1.8.19 PkiCapsType

typedef struct {

uint CrlStoreSize;

uint RootCertMaxSize; uint RootCertMaxInstances;

uint FqdnSuffixMaxEntries; uint FqdnSuffixMaxEntryLength;

uint CertChainMaxSize;


104

uint SupportedKeyLengths[];

} PkiCapsType;

Field Description

CrlStoreSize

This field exposes the maximum byte size of the CRL store. This size includes the internal overhead structures and it should be used for rough estimation of the caller that wishes to add new entries to the CRL using SetCRL.

RootCertMaxSize Maximum byte length of a root certificate that can be added using AddTrustedRootCertificate.

RootCertMaxInstances Maximum number of root certificates that can be configured using AddTrustedRootCertificate.

FqdnSuffixMaxEntries Maximum number of FQDN Suffix entries that can be configured using SetTrustedFqdnCN.

FqdnSuffixMaxEntryLength Maximum byte length of an FQDN Suffix entry that can be configured using SetTrustedFqdnCN.

CertChainMaxSize

Maximum byte size for certificate chain that can be configured using SetTlsKeyAndCertificate or SetTlsCertificate.

SupportedKeyLengths A list of supported key length sizes, such as 1024, 1536, 2048, …

7.1.8.20 UserAclRealmListType

typedef struct _UserAclRealmListType { UserAclRealmType Realm; } UserAclRealmListType;

Field Description

Realm Array of interface names. Interfaces the ACL entry is allowed to access.

7.1.8.21 RsaKeyType typedef struct _RsaKeyType { RsaKeyEncodingType Encoding; uint32 Length;


105

BinaryData Value; } RsaKeyType;

Field Description

Encoding Specifies the format and algorithm used to encode the key pair. The single encoding format supported is “SSHv2 MPINT.”

Length The length of the key data, in bytes.

Value The binary key data. A buffer containing P, Q, N and E parameters of the RSA scheme, stored as MPINT, MPINT is defined in [SSH].

7.1.8.22 RsaKeyEncodingType A code that specifies the format and algorithm used to encode the key pair.

typedef enum<uint32> _RsaKeyEncodingType { RsaKeyEncodingTypeInvalid = 30, RsaKeyEncodingTypesSshv2Mpint = 31 } RsaKeyEncodingType;

Field Description

RsaKeyEncodingTypesSshv2Mpint Match MPINT format, defined in SSHv2 RFC

7.1.8.23 RngKeyType typedef struct _RngKeyType { RngKeyEncodingType Type; uint32 Length; BinaryData Data; } RngKeyType;

Field Description

Type The type of key.

Length The length of the key data, in bytes.

Data The binary key data. This must be in a format that the Intel AMT firmware can identify and parse.

7.1.8.24 RngKeyEncodingType A code that specifies the format and algorithm used to encode the key pair.

typedef enum<uint32> _RngKeyEncodingType { RngKeyEncodingTypeInvalid = 20, RngKeyEncodingTypeBare = 21 } RngKeyEncodingType;


106

Field Description

RngKeyEncodingTypeBare Bare encoding type.

7.1.8.25 CertificateChainType typedef struct _CertificateChainType { RsaCertificateEncodingType Encoding; uint32 Length; BinaryData Value; } CertificateChainType;

Field Description

Encoding Specifies the format and algorithm used to encode the certificate. The single encoding format supported is “X.509.”

Length The length of the certificate, in bytes.

Data

This is a sequence (chain) of X.509v3 certificates. The Intel AMT Device certificate must come first in the list. Each subsequent certificate must directly certify the one preceding it. Because certificate validation requires that root keys be distributed independently, the self-signed certificate which specifies the root certificate authority optionally may be omitted from the chain. See [HTTPS] and [TLS] for more information. Certificate #1 Length (3 bytes network order)

Certificate #1 data (device certificate)

Certificate #2 Length (3 bytes network order)

Certificate #2 data (Signing CA of Cert #1)

…….

Certificate #N Length (3 bytes network order)

Certificate #N data (signing CA of Cert #N-1 )

7.1.8.26 RsaCertificateEncodingType A code that specifies the format and algorithm used to encode the key pair.

typedef enum<uint32> _RsaCertificateEncodingType { RsaCertificateEncodingTypeInvalid = 10, RsaCertificateEncodingTypeX509 = 11 } RsaCertificateEncodingType;

Field Description

RsaCertificateEncodingTypeX509 X.509 encoding type.


107

7.1.8.27 ProvisioningModeType typedef enum<uint32> _ProvisioningModeType { ProvisioningModeCurrent = 0, ProvisioningModeEnterprise = 1, ProvisioningModeSmallBusiness = 2 } ProvisioningModeType;

Code Description

ProvisioningModeCurrent Current provisioning mode based on the flash image settings.

ProvisioningModeEnterprise Enterprise provisioning mode.

ProvisioningModeSmallBusiness Small business provisioning mode.

7.1.8.28 UpdateCoreUrlKeyType typedef struct _UpdateCoreUrlKeyType { uint32 KeyLength; UpdateCoreUrlKeyAlgorithmType KeyAlgorithm; uint8 *KeyData; } UpdateCoreUrlKeyType;

KeyAlgorithm specifies the digital signature algorithm used to produce KeyData. It is optional, but must be provided if KeyData is present.

KeyData is an optional digital signature used to verify the downloaded image.

Field Description

KeyLength Specifies the length of the signature provided by KeyData.

KeyAlgorithm Specifies the digital signature algorithm used to produce KeyData.

KeyData The starting offset of the current certificate fragment, in bytes.

7.1.8.29 UpdateCoreUrlKeyAlgorithmType A code that specifies the algorithm used to update core URL key.

typedef enum<uint32> _ UpdateCoreUrlKeyAlgorithmType { UpdateCoreUrlKeyAlgorithmInvalid = 0, UpdateCoreUrlKeyAlgorithmSHA1 = 1, } UpdateCoreUrlKeyAlgorithmType;

Field Description

UpdateCoreUrlKeyAlgorithmSHA1 SHA1 encoding type.


108

7.1.8.30 AmtVersionType typedef struct _AmtVersionType { uint8 major; uint8 minor; uint8 micro; } AmtVersionType;

Field Description

Major Specifies the major version.

Minor Specifies the minor version.

Micro Specifies the micro version.

7.1.8.31 KerberosOptionsType typedef struct _KerberosOptionsType {

string KerberosRealmName; KerberosSpnType KerberosSpn[]; uint32 KerberosKeyVersion; KerberosEncryptionType KerberosEncryption; BinaryData KerberosMasterKey; uint32 MaximumClockTolerance;

} KerberosOptionsType;

Field Description

KerberosRealmName Kerberos Realm name (1 to 63 chars not including the Null termination).

KerberosSpn An array of KerberosSpnType elements describing Kerberos SPN options. (Only one definition is allowed per protocol).

KerberosKeyVersion Kerberos Key version.

KerberosEncryption Supported Encryption type.

KerberosMasterKey Kerberos Master Key. Currently, this field should be 16 bytes long.

MaximumClockTolerance

The policy for Maximum Tolerance for Clock Synchronization. This is a number representing the number of minutes by which the clocks of the Intel AMT device and the client and KDC can be out of sync – typically 5 minutes. (Note: specifying zero for this value is invalid.) Currently MaximumClockTolerance is limited to a range of 1 to 5.


109

7.1.8.32 KerberosSpnType typedef struct _KerberosSpnType {

KerberosSpnProtocolType SpnProtocolIndex; string SpnString;

} KerberosSpnType;

Field Description

SpnProtocolIndex Protocol definition for SPN.

SpnString Should be of the form: HTTP/<fqdn>:<port number> (0 to 267 chars including Null termination – this should allow sufficient space for FQDN and the SPN trailer (HTTP\:nnnnnn)).

7.1.8.33 KerberosSpnProtocolType typedef enum<string> _KerberosSpnProtocolType { ”HTTP” , ”HTTPS” , ”SOL_IDER”, ”SOL_IDER_SSL" } KerberosSpnProtocolType;

Field Description

HTTP HTTP Protocol definition

HTTPS HTTPS Protocol definition

SOL_IDER SOL&IDER protocol definition

SOL_IDER_SSL SOL&IDER protocol definition (using SSL)

7.1.8.34 KerberosEncryptionType typedef enum<string> _KerberosEncryptionType { ”HMAC_RC4” } KerberosEncryptionType;

Field Description

HMAC RC4_ RC4 encryption and HMAC authentication

7.1.8.35 PowerStateType typedef enum<string> _PowerStateType


110

{ “PowerStateS0”, “PowerStateS1”, “PowerStateS2”, “PowerStateS3”, “PowerStateS4”, “PowerStateS5” } PowerStateType;

Field Description

PowerStateS0 S0 power state






See Section 7.5.2.10, SystemPowerStateType for a description of the different “S” power state values.

7.1.8.36 CertificateHandleType

typedef uint32 CertificateHandleType ;

Field Description

CertificateHandleType A Certificate Handle

7.1.8.37 KeyPairHandleType

typedef uint32 KeyPairHandleType ;

Remarks

A handle to a key pair

7.1.8.38 KeyPairType

typedef struct {

choice {


111

RSAKeyPairType RSAKeyPair ; };

} KeyPairType ;

Field Description

RSAKeyPair RSA key pair (Public & Private).

Remarks

The private section of the key pair is settable but not gettable.

7.1.8.39 RSAKeyPairType

typedef struct {

BinaryData DERKey ;

} RSAKeyPairType ;

Field Description

DERKey RSA Key encoded as DES PKCS#1. When this structure is used as an output parameter, only the public section of the key is exported.

Remarks

The private section of the key pair is settable but not gettable. The Exponent (E) is expected to be 65537 (0x010001).

7.1.8.40 GuidBuf

typedef GuidBuf BinaryData;

Remarks

GuidBuf is restricted to the exact length of 16 bytes.

GUIDs are frequently stored in files as text, but sometimes they are stored in binary. This is a binary representation of a GUID.

For example, a Text GUID {01020304-0506-0708-0910-111213141516} Is translated to this binary form in order: 04 03 02 01 06 05 08 07 09 10 11 12 13 14 15 16


112

7.1.8.41 GlobalPowerPolicyType

typedef struct { uint32 IdleWakeTimeout;

} GlobalPowerPolicyType ;

Field Description

IdleWakeTimeout

Defines the minimum time value, in minutes, that Intel AMT will be operable after waking up from a sleep power state. This timer value will be reloaded whenever Intel AMT is servicing requests.

This value should not be set to less than 3 minutes so that Wake on LAN has time to complete. This is essential opposite Microsoft Vista and Linux-based platforms.

In Intel AMT Releases 2.5 and 3.0, the platform does not transition to Moff in less than two minutes, even if this value is set to one minute.

Note: this setting may not be applicable under some power package definitions.

Remarks

Note: some global settings may not be applicable under some power package definitions.

7.1.8.42 CertIdType

typedef struct {

URL Url ; BinaryData SerialNumber[] ;

} CertIdType ;

Field Description

Url The issuer URL of the certificates.

SerialNumber A list of serial numbers.


113

Remarks

This type is similar to CrlType. The only difference is that it implies positive inclusion. A revoked certificate in a Certificate Revocation List (CRL) supersedes inclusion in a CertIdType list.

7.1.8.43 EnvironmentDetectionDomainType

typedef struct { string values[] ;

} EnvironmentDetectionDomainType ;

Field Description

values List of domain suffix names.

Max 5 domains, max 64 bytes each.

Remarks If IP settings are static, Intel AMT can not use the local domain list for detection.

7.1.8.44 EnvironmentDetectionType

typedef struct { EnvironmentDetectionDomainType DomainSuffixList ;

[optional] uint32 ExternalCircuitBreakerPolicy;

} EnvironmentDetectionType ;

Field Description

DomainSuffixList List of domain suffix names.

ExternalCircuitBreakerPolicy

The handle of a Circuit Breaker policy that is applied to each interface separately when it is assumed that the interface is connected to the external network. When this parameter is Null, Circuit Breaker functionality is expected to remain the same when operating inside or outside the organization.

Remarks Each network interface operates separately and independently.


114

7.1.8.45 HTTPAuthOptionType

typedef enum<string> {

"NoAuth", "Auth", "Disable"

} HTTPAuthOptionType ;

Field Description

NoAuth No authentication required (Anonymous login).

Auth Use Digest Authentication.

Disable Disable access to interface.

7.1.8.46 ProvisioningTLSModeType

typedef enum<uint8> {

NOT_READY = 0, PSK, PKI

} ProvisioningTLSModeType ;

Field Description

NOT_READY Provisioning not started.

PSK Provisioning started using PSK (PID-PPS pair).

PKI Provisioning started using certificate hash.

7.1.8.47 CertHashEntryType

typedef struct {

boolean Default; boolean Active; HashTypeType HashType; BinaryData Hash; string FriendlyName;


115

} CertHashEntryType ;

Field Description

Default Indicates whether this entry is a factory default.

Active Indicates whether this entry is in use.

HashType Hash type.

Hash Hash value (length depending on hash type).

FriendlyName Friendly name string (min length = 1, max length = 32).

7.1.8.48 HashTypeType

typedef enum<uint8> {

SHA_1_160 = 1,

} HashTypeType ;

Field Description

SHA_1_160 Indicates a 20-byte hash created by SHA-1.

7.1.8.49 ProvisioningAuditRecordType

typedef struct {

ProvisioningTLSModeType ProvisioningTLSMode; boolean SecureDNS; boolean HostInitiated; [optional] string ProvServerFQDN; HashTypeType SelectedHashType; BinaryData SelectedHashData; BinaryData CaCertSerials[]; [optional] boolean AdditionalCaSerialNums; boolean IsOemDefault; boolean IsTimeValid; IPv4AddressType ProvServerIP; TimeType TlsStartTime;

} ProvisioningAuditRecordType ;

Field Description

ProvisioningTLSMode Mode used to start provisioning.


116

Field Description

SecureDNS

True if the provisioning server FQDN came from the OEM default or from the MEBx (either manually or from USB key). False oif the value came from a local agent or from a DHCP server quesry.

HostInitiated True if provisioning was started from the Host (e.g., by a local agent). False if provisioning started due to OEM Bare Metal configuration.

ProvServerFQDN Certificate Comon Name is copied into this field. Not relevant in TLS-PSK mode.

SelectedHashType Hash algorithm used.

SelectedHashData Root certificate hash used.

CaCertSerials

A list of certificate serial numbers. Records the serial numbers of the issuing CA certificates. Current implementation implies: max 3 items of at most 16 bytes each. If the certificate chain has more thatn three certificates, this field contains the serial numbers of the last three certificates.

AdditionalCaSerialNums True if there were more than three certificates in the chain.

IsOemDefault True if the hash used is one of the OEM default hashes.

IsTimeValid

Because the time in the Intel AMT device is not trusted when configuration starts, the device will accept a certificate even if it has expired according to the local time. This parameter is true if the certificate had not expired.

ProvServerIP The IP address of the Provisioning server that issued the CommitChanges() command and changed the provisioning state of the device.

TlsStartTime Time of the last TLS handshake.

Remarks When configuration mode is TLS-PSK, only the first field and the last two fields of this record are applicable.


117

7.2 Network Administration Interface Namespace : http://schemas.intel.com/platform/client/NetworkAdministration/2004/01 Port : http://hostname:port/NetworkAdministrationService


Local Access −

Network Access √

The Network Administration Interface enables administrators to configure local network parameters. Many of these parameters are typically provided by DHCP. However, in environments that do not use DHCP, static values for these parameters can be configured via the Network Administration Interface.

Method Description

SetTcpIPParameters Sets the TCP/IP parameters to be used on a wired interface by the Intel AMT device.

GetTcpIPParameters Gets the TCP/IP parameters used on a wired interface by the Intel AMT device.

SetHostName Sets the host name to be used by the Intel AMT device.

GetHostName Gets the host name currently used by the Intel AMT device.

SetDomainName Sets the domain name to be used by the Intel AMT device

GetDomainName Gets the domain name used by the Intel AMT device.

SetVlanParameters Sets the VLAN mode and ID to be used by the Intel AMT device.

GetVlanParameters Gets the VLAN mode and ID used by the Intel AMT device.

SetPingResponse Controls whether the Intel AMT device responds to ping request.

GetPingResponse Gets Ping response behavior.

EnumerateInterfaces Returns a handle for each defined interface.

SetInterfaceSettings Sets parameters for a selected interface.

GetInterfaceSettings Returns settings for a selected interface.

Set8021XWiredProfile Assigns an 802.1x profile to a selected interface.

Get8021XWiredProfile Returns an 802.1x profile.

Set8021XActiveS0 Set the activity setting of the 802.1X module in S0 state.

Get8021XActiveS0 Get the activity setting of the 802.1X module in S0 state.

Set8021XPxeTimeout Enables and sets PXE Timeout

Get8021XPxeTimeout Returns the PXE Timeout setting.


118

7.2.1 Service APIs

7.2.1.1 SetTcpIpParameters This command sets the TCP/IP parameters of the Intel AMT device wired network interface.

Header PT_STATUS SetTcpIpParameters ( [in] DhcpModeType DhcpMode, [in, optional] StaticIPv4ParametersType StaticIPv4Parameters

);

Compatibility This command is supported by Intel AMT Release 1.0 and Intel AMT Release 2.0/2.1. It is deprecated in releases 2.5 and later – callers should use the SetInterfaceSettings() API.

Parameters DhcpMode specifies whether the Intel AMT device should use DHCP to retrieve the IP parameters or whether the IP parameters are static. The enumeration DhcpModeType specifies the valid values for this parameter.

StaticIPv4Parameters contains the static IP parameters. This value is optional and should be sent only if DhcpMode is “disabled.” Otherwise, if this structure is sent, it will be ignored.


Code Description


PT_STATUS_INVALID_DHCP_MODE DhcpMode is invalid.

PT_STATUS_INVALID_IP_ADDRESS One of the IP address in StaticIPv4Parameters is not a valid IP unicast address.

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_DOMAIN_NAME The StaticIPv4Parameters.DomainName is invalid.


Remarks When the Intel AMT device is configured to DHCP enabled mode, the host OS must also be configured to use DHCP.

When Intel AMT is configured for static IP, its IP address must be different from the host IP address.


119

In StaticIPv4Parameters, the function will succeed even if only the IP address and netmask fields are set. If the gateway or DNS addresses are set to 0 or the domain name is set to an empty string, then those fields will be ignored and will not be considered “invalid.” This will allow the Intel AMT device to work only in the local subnet – behavior that matches the OS behavior when partial IP parameters are set.

When changing DHCP mode from “disabled” to “enabled” when the OS driver is present, the Intel AMT device will establish connectivity only in the next host DHCP negotiation. It is advised to renew the host’s DHCP address in this case.


7.2.1.2 GetTcpIpParameters This command gets the currently used TCP/IP parameters of the Intel AMT device wired network interface.

Header PT_STATUS GetTcpIpParameters ( [out] DhcpModeType DhcpMode,

[out] StaticIPv4ParametersType StaticIPv4Parameters );

Compatibility This command is supported by Intel AMT Release 1.0 and Intel AMT Release 2.0/2.1. It is deprecated in releases 2.5 and later – callers should use the GetInterfaceSettings() API.

Parameters DhcpMode specifies whether the Intel AMT device uses DHCP to retrieve the IP parameters or whether the IP parameters are static. The enumeration DhcpModeType specifies the valid values for this parameter.

StaticIPv4Parameters contains the static IP parameters. This value has meaning only if DhcpMode is “disabled.”


Code Description



7.2.1.3 SetHostName SetHostName sets the host name to be used by the Intel AMT device.


120

Header PT_STATUS SetHostName ( [in] string HostName

);

Compatibility This command is supported by Intel AMT Release 1.0 and later releases.

Parameters

HostName Host name to be used


Code Description


PT_STATUS_INVALID_NAME HostName does not comply with the restrictions in [DNS].


Remarks

Host name should match the managed machine name if Intel AMT operates in shared IP mode.

If the Intel AMT device operates in static IP mode: then the specified host name should be different from the managed-computer host name.

If the Intel AMT device operates in Dynamic IP mode (DHCP):

In Intel AMT Release 1.0,

• If the Intel AMT device is in DHCP mode while the OS is up and the host DHCP is configured with options 12 or 81, then the host name set by this API will be overridden by the host DHCP negotiation.

• If the Intel AMT device is in DHCP mode while the OS is down and the host DHCP is configured with options 12 or 81, then host name set by this API will not be used by the Intel AMT device for host name registrations. However, the host name will be returned by the SOAP GetHostName API call as well as by the Web user interface. Network transactions will be done using the OS host name.

In Intel AMT Release 2.0 or later, host name is not overridden by the local host. An Intel AMT Release 2.0 (or later) platform configured for 1.0 Legacy mode behaves the same way as an Intel AMT Release 2.0 (or later) platform in normal mode.


The Intel AMT device registers an FQDN in the enterprise DNS which is comprised of the machine name and the domain name (Intel AMT Release 1.0 uses the domain name returned by the DHCP server or uses the domain name from the static IP settings).


121

7.2.1.4 GetHostName GetHostName returns the host name that Intel AMT device uses.

Header PT_STATUS GetHostName( [out] string HostName

);


Parameters

HostName Host name to be retrieved. I If the Host Name has not been set, then this method will return PT_STATUS_SUCCESS and an empty string.


Code Description



Remarks

Intel AMT Release 1.0 host name may be overridden by the local host as Intel AMT Release 1.0 tries to snoop the host name used by the host using the DHCP protocol.

Intel AMT Release 2.0 or later does not implement the snooping protocol and the returned name will not change unless explicitly set to a different name. An Intel AMT Release 2.0 (or later) platform configured for 1.0 Legacy mode behaves the same way as an Intel AMT Release 2.0 (or later) platform in normal mode.

The Intel AMT device registers an FQDN in the enterprise DNS, which is comprised of the machine name and the domain name.

7.2.1.5 SetDomainName SetDomainName sets the domain to be used by the Intel AMT device.

Header PT_STATUS SetDomainName ( [in] string DomainName

);


122

Compatibility This routine is supported by Intel AMT Release 2.0 and later releases.

Parameters

DomainName Domain name to be used.


Code Description


PT_STATUS_INVALID_DOMAIN_NAME HostName does not comply with the restrictions in [DNS].


Remarks

The Intel AMT device registers an FQDN in the enterprise DNS which is comprised of the machine name and the domain name.


7.2.1.6 GetDomainName GetDomainName returns the domain name used by the Intel AMT device.

Header PT_STATUS GetDomainName( [out] string DomainName

);


Parameters

DomainName Domain name to be retrieved.



123

Code Description



Remarks

The Intel AMT device registers an FQDN in the enterprise DNS that is comprised of the machine name and the domain name.

If the domain name has not been set, then this method will return PT_STATUS_SUCCESS and an empty string.

7.2.1.7 SetVlanParameters This function sets the VLAN mode and ID to be used by the Intel AMT device.

Header PT_STATUS SetVlanParameters(

[in, optional] InterfaceHandleType InterfaceHandle, [in] boolean VlanMode, [in] uint16 VlanTag );


Parameters

InterfaceHandle

A handle to interface descriptor. If IntefaceHandle is Null, then this method applies to the default LAN interface.

VlanMode If VlanMode is TRUE, then VLAN should be enabled on the Intel AMT device. If it is FALSE, then VLAN should be disabled.

VlanTag

The parameter VlanTag is only valid if VlanMode is TRUE, and it is ignored otherwise. The parameter denotes the VLAN ID that should be used for the manageability VLAN.



124

Code Description


PT_STATUS_INVALID_PARAMETER Invalid handle or settings.



PT_STATUS_UNSUPPORTED The configuration cannot be supported by the device. (This is the expected return value for Intel AMT Release 2.5).

Remarks

When the Intel AMT device is configured to share its IP address with the host operating system, the same VLAN ID also must be configured by the host OS. The DHCP server also should be enabled on that VLAN ID.


7.2.1.8 GetVlanParameters This function gets the VLAN mode and ID currently used by the Intel AMT device.

Header PT_STATUS GetVlanParameters(

[in, optional] 5InterfaceHandleType InterfaceHandle, [out] boolean VlanMode, [out] uint16 VlanTag );


Parameters

InterfaceHandle A handle to interface descriptor. If InterfaceHandle is Null, then this method applies to the default LAN interface.

VlanMode If VlanMode is TRUE, then VLAN is enabled on the Intel AMT device. If it is FALSE, VLAN is disabled.


125

VlanTag The parameter VlanTag is only valid if VlanMode is TRUE. It denotes the VLAN ID that is used for the manageability VLAN.

Return Value

One of the following status codes MUST be returned by this method:

Code Description




PT_STATUS_UNSUPPORTED The configuration cannot be supported by the device. (This is the expected return value for Intel AMT Release 2.5).

7.2.1.9 SetPingResponse This function allows an administrator to configure how an Intel AMT device will respond to ICMP requests (Ping).

Header PT_STATUS SetPingResponse( [in] boolean enabled

);


Parameters If enabled is set to TRUE, then the Intel AMT device responds to ICMP echo requests. Otherwise the device ignores such requests.


Code Description




126

Code Description


Remarks When ping is enabled and Intel AMT is sharing its IP address with the host, then Intel AMT will only respond to pings when the host OS is down or the OS is up but the interface driver (wired or wireless) is not present.

7.2.1.10 GetPingResponse This function returns the state of the ICMP echo reply functionality of the Intel AMT device.

Header PT_STATUS GetPingResponse(

[out] boolean enabled );


Parameters If enabled is TRUE, then the Intel AMT device responds to ICMP echo requests. Otherwise the device ignores such requests.


Code Description



7.2.1.11 EnumerateInterfaces

This command returns handles for each interface known to the Intel AMT device.

Header PT_STATUS EnumerateInterfaces(

[out] 5InterfaceHandleType InterfaceHandles[] );


127


Parameters

InterfaceHandles

A list of handles to interface descriptors.


Code Description



Remarks

The values returned by this call match the Circuit Breaker HardwareID parameters returned by CbQueryCapabilities().

7.2.1.12 GetInterfaceSettings

This command returns the settings of an interface, given an interface handle.

Header PT_STATUS GetInterfaceSettings(

[in] 5InterfaceHandleType InterfaceHandle, [out] InterfaceDescriptorGetType InterfaceDescriptor );


Parameters

InterfaceHandle

A handle to interface descriptor.


128

InterfaceDescriptor

Interface settings.


Code Description



PT_STATUS_INVALID_PARAMETER Invalid handle

Remarks

Interface handles can be retrieved by calling EnumerateInterfaces().

7.2.1.13 SetInterfaceSettings

This command sets interface parameters for a selected network interface.

Header PT_STATUS SetInterfaceSettings(

[in] 5InterfaceHandleType InterfaceHandle, [in] InterfaceDescriptorSetType InterfaceDescriptor );


Parameters

InterfaceHandle


InterfaceDescriptor

Interface settings.



129

Code Description





PT_STATUS_UNSUPPORTED

The configuration cannot be supported by the device: Factory settings may not allow separate MAC

configuration. Firmware may not support separate MAC while

configured to operate in DHCP mode. Current release implies that LAN interface is always

available when ME is ON.

PT_STATUS_INVALID_IP_ADDRESS Invalid IP address entered.

PT_STATUS_INVALID_NETMASK Invalid subnet mask entered.

Remarks

Setting Read Only fields should have no effect and no error will be returned.


7.2.1.14 Set8021XWiredProfile

This command assigns an 802.1X profile to an interface.

Header PT_STATUS Set8021XWiredProfile(

[in] 5InterfaceHandleType InterfaceHandle, [in, optional] XProfileType XProfile );


Parameters

InterfaceHandle


130


XProfile

802.1X Profile Settings. If Null, then 802.1X settings are removed for the specified device.


Code Description





PT_STATUS_UNSUPPORTED The configuration cannot be supported by the device (Currently returned for a Wireless interface).

Remarks

Intel AMT does not check the strings included in the Xprofile structure for Username, Password, Domain, and Roaming Identity for more than correct length. These parameters are used to authenticate with external equipment such as a RADIUS server, and must conform to the naming requirements of such devices or services. For example, user names must not have special characters embedded in them (“ / \ [ ] : ; | = , + * ? < >).

7.2.1.15 Get8021XWiredProfile

This command retrieves the 802.1X profile assigned to an interface.

Header PT_STATUS Get8021XWiredProfile(

[in] 5InterfaceHandleType InterfaceHandle, [out, optional] XProfileType XProfile );


Parameters

InterfaceHandle


131


XProfile

802.1X Profile Settings. If Null, then there are no 802.1X settings for the specified device. Confidential information such as passwords is not returned to the caller. Wireless interfaces always return Null as their 802.1X settings are configured through a wireless profile.


Code Description




7.2.1.16 Set8021XActiveS0

This command sets the activity setting of the 802.1X module in S0 state

Header PT_STATUS Set8021XActiveS0(

[in] boolean Enabled, );


Parameters

Enabled

Enable/disable flag


Code Description



132

Code Description



Remarks If 802.1X is not configured, this API may still succeed as the setting will be stored for future use. The default factory setting is: Enabled = TRUE.

7.2.1.17 Get8021XActiveS0

This command gets the activity setting of the 802.1X module in S0 state.

Header PT_STATUS Get8021XActiveS0(

[out] boolean Enabled, );


Parameters

Enabled

Enabled/disabled flag.


Code Description



Remarks If 802.1X is not configured, this API may still succeed as the setting may be stored for future use.

7.2.1.18 Set8021XPxeTimeout

This command enables/disables 802.1X negotiation in PXE environement.


133

Header PT_STATUS Set8021XPxeTimeout(

[in, optional] uint32 Timeout, );

Compatibility This routine is supported by Intel AMT Release 2.6.

Parameters

Timeout

Timeout in seconds, in which the Intel AMT will hold an authenticated 802.1X session. During the defined period, Intel AMT manages the 802.1X negotiation while a PXE boot takes place. After the timeout, control of the negotiation passes to the host. A value of 0 disables the feature. If this optional value is omitted, Intel AMT sets a default value of 120 seconds.


Code Description





Remarks If 802.1X is not configured, this API may still succeed and the setting will be stored for future use. The default factory setting disables 802.1X for PXE.

7.2.1.19 Get8021XPxeTimeout

This command reads the enable/disable state of 802.1X negotiation in PXE environement.

Header PT_STATUS Get8021XPxeTimeout(

[out] uint32 Timeout, );



134

Parameters

Timeout

Timeout in seconds, in which the Intel AMT will hold an authenticated 802.1X session. If the value is 0, the feature is disabled.


Code Description



Remarks If 802.1X is not configured, this API may still succeed.


7.2.2.1 DhcpModeType

typedef enum<uint32> _DhcpModeType { DhcpModeInvalid = 0, DhcpModeDisabled = 1, DhcpModeEnabled = 2 } DhcpModeType;

Code Description

DhcpModeInvalid Invalid DHCP mode.

DhcpModeDisabled DHCP disabled mode.

DhcpModeEnabled DHCP enabled mode.

7.2.2.2 InterfaceHandleType

typedef uint32 InterfaceHandleType ;


135

Remarks

This type is a handle to describe a network Interface such as a wireless or a LAN interface (should match the HardwareID output in Circuit Breaker legacy interface).

7.2.2.3 InterfaceDescriptorGetType

typedef struct {

string HardwareDescription ; string MACAddress; InterfaceModeType InterfaceMode ; LinkPolicyType LinkPolicy ; boolean DhcpEnabled ; [optional] IPv4ParametersType IPv4Parameters ;

} InterfaceDescriptorGetType ;

Field Description

HardwareDescription Description of the hardware interface (should match the HardwareDescription output in Circuit Breaker interface).

MACAddress

String description of the MAC address of the manageability device (may be different depending on InterfaceMode). Example: “02-00-4C-4F-4F-50”

InterfaceMode

Determines whether the manageability device uses the same MAC address as the Host MAC address or a separate MAC address (determined internally).

LinkPolicy

Link policy restriction for better power consumption. If Intel AMT will not be able to determine the exact power state, the more restrictive closest configuration applies.

DhcpEnabled Boolean flag that indicates whether DHCP is enabled.

IPV4Parameters Current assigned IPv4 settings. If DHCP is enabled and no IP address is accepted, the parameter will be Null.

Remarks

This type is a descriptor for a network Interface such as a wireless or a LAN interface.


136

7.2.2.4 InterfaceDescriptorSetType

typedef struct {

InterfaceModeType InterfaceMode ; LinkPolicyType LinkPolicy ; [optional] IPv4ParametersType IPv4Parameters ;

} InterfaceDescriptorSetType ;

Field Description

InterfaceMode

Determines whether the manageability device uses the same MAC address as the Host MAC address or a separate MAC address (determined internally).

LinkPolicy

Link policy restriction for better power consumption. If Intel AMT will not be able to determine the exact power state, the more restrictive closest configuration applies.

IPv4Parameters Optional (if omitted, DHCP will be assumed) Static IPv4 settings.

Remarks

This type is a descriptor for a network Interface such as a wireless or a LAN interface.

7.2.2.5 InterfaceModeType

typedef enum<string> { SEPARATE_MAC_ADDRESS, SHARED_MAC_ADDRESS

} InterfaceModeType ;

Field Description

SEPARATE_MAC_ADDRESS Device will use a MAC address separate from the local host interface.

SHARED_MAC_ADDRESS Device will share MAC address with the local host interface.

Remarks


137

Some configurations may not support separate MAC address with DHCP. A shared MAC address with static IPs is also not supported.

7.2.2.6 LinkPolicyType

typedef enum<uint8> { AVAILABLE_ON_AC_S0 = 0x01, AVAILABLE_ON_AC_SX = 0x0E, AVAILABLE_ON_DC_S0 = 0x10, AVAILABLE_ON_DC_SX = 0xE0

} LinkPolicyType ;

Field Description

AVAILABLE_ON_AC_S0 Link should be operational if ME is operational and power state is S0 while on AC power.

Note: this setting is always assumed.

AVAILABLE_ON_AC_SX Link should be operational if ME is operational and power state is Sx while on AC power.

AVAILABLE_ON_DC_S0 Link should be operational if ME is operational and power state is S0 while on DC power.

AVAILABLE_ON_DC_SX Link should be operational if ME is operational and power state is Sx while on DC power.

Remarks

AVAILABLE_ON_AC is always assumed (the set operation ignores this option). Fields from this enum can be combined using logical OR. If Intel AMT will not be able to determine the exact power state, the more restrictive closest configuration applies.

7.2.2.7 StaticIPv4ParametersType

typedef struct _StaticIPv4ParametersType { IPv4AddressType LocalAddress; IPv4AddressType SubnetMask; IPv4AddressType DefaultGatewayAddress; IPv4AddressType PrimaryDnsAddress; IPv4AddressType SecondaryDnsAddress; string DomainName; } StaticIPv4ParametersType;


138

Field Description

LocalAddress An IPv4 unicast address that is used by Intel AMT as its local address.

SubnetMask The IPv4 subnet mask that is applied to the local address to distinguish the network ID from the host ID.

DefaultGatewayAddress An IPv4 unicast address that is used as the default gateway. A 0 value indicates that the entry is not set.

PrimaryDnsAddress IP Address of the Primary DNS. A 0 value indicates that the entry is not set.

SecondaryDnsAddress IP Address of the Secondary DNS. A 0 value indicates that the entry is not set.

DomainName

The domain name used by the Intel AMT device.

This parameter is deprecated from Intel AMT Release 2.0 onward, and should be ignored.

Clients that wish to modify or read the domain settings should use SetDomainName() and GetDomainName()

Note: this value should not be confused with DNS suffix which may have been used here (and is not used).

7.2.2.8 IPv4ParametersType

typedef struct { IPv4AddressType LocalAddress; IPv4AddressType SubnetMask; IPv4AddressType DefaultGatewayAddress; IPv4AddressType PrimaryDnsAddress; IPv4AddressType SecondaryDnsAddress;

} IPv4ParametersType ;

Field Description

LocalAddress An IPv4 unicast address that is used by Intel AMT as its local address.

SubnetMask The IPv4 subnet mask that is applied to the local address to distinguish the network ID from the host ID.

DefaultGatewayAddress An IPv4 unicast address that is used as the default gateway. A 0 value indicates that the entry is not set.

PrimaryDnsAddress IP Address of the Primary DNS. A 0 value indicates the entry is not set.


139

SecondaryDnsAddress IP Address of the Secondary DNS. A 0 value indicates the entry is not set.

7.2.2.9 XProfileType

typedef struct {

choice { XProfileTLSType TLS; XProfileTTLS_MSCHAPv2Type TTLS_MSCHAPv2; XProfilePEAP_MSCHAPv2Type PEAP_MSCHAPv2; XProfileEAP_GTCType EAP_GTC; XProfileEAPFAST_MSCHAPv2Type EAPFAST_MSCHAPv2; XProfileEAPFAST_GTCType EAPFAST_GTC; XProfileEAPFAST_TLSType EAPFAST_TLS; };

} XProfileType;

Field Description

TLS Parameters required for TLS profile

TTLS_MSCHAPv2 Parameters required for tunneled TLS profile using MSCHAPv2

PEAP_MSCHAPv2 Parameters required for PEAP profile using MSCHAPv2

EAP_GTC Parameters required for EAP profile using GTC

EAPFAST_MSCHAPv2 Parameters required for EAP-FAST profile using MSCHAPv2

EAPFAST _GTC Parameters required for EAP-FAST profile using GTC

EAPFAST _TLS Parameters required for EAP-FAST profile using TLS. Supported for Intel AMT 2.6 or later.

7.2.2.10 XProfileTLSType

typedef struct {

string Username; ServerIdentityType ServerIdentity; 5CertificateHandleType ClientCertificate;

} XProfileType;


140

Field Description

Username

ServerIdentity

ClientCertificate

Remarks

Intel AMT does not check Username for more than correct length. This parameter is used to authenticate with external equipment such as a RADIUS server, and must conform to the naming requirements of such devices or services.

7.2.2.11 XProfileTTLS_MSCHAPv2Type

typedef struct {

[optional] string RoamingIdentity; ServerIdentityType ServerIdentity; UserCredentialsType UserCredentials; [optional] 5CertificateHandleType ClientCertificate;

} XProfileTTLS_MSCHAPv2Type;

Field Description

RoamingIdentity Roaming Identity descriptor (max 80 chars, not including the Null termination).

ServerIdentity

UserCredentials

ClientCertificate

7.2.2.12 XProfilePEAP_MSCHAPv2Type

typedef struct {

[optional] string RoamingIdentity; ServerIdentityType ServerIdentity; UserCredentialsType UserCredentials; [optional] 5CertificateHandleType ClientCertificate;

} XProfilePEAP_MSCHAPv2Type;


141

Field Description

RoamingIdentity

ServerIdentity

UserCredentials

ClientCertificate

Remarks

Intel AMT does not check Roaming Identity for more than correct length. This parameter is used to authenticate with external equipment such as a RADIUS server, and must conform to the naming requirements of such devices or services.

7.2.2.13 XProfileEAP_GTCType

typedef struct {

UserCredentialsType UserCredentials; } XProfilePEAP_GTCType;

Field Description

UserCredentials

7.2.2.14 XProfileEAPFAST_MSCHAPv2Type

typedef struct {

[optional] string RoamingIdentity; ServerIdentityType ServerIdentity; UserCredentialsType UserCredentials; [optional] ManualPACType ProtectedAccessCredentials; [optional] 6CertificateHandleType ClientCertificate;

} XProfileEAPFAST_MSCHAPv2Type;

Field Description

RoamingIdentity Optional string used to identify this mobile platform

ServerIdentity

UserCredentials


142

ProtectedAccessCredentials Due to security concerns - this field is write-only and cannot be read after setting.

ClientCertificate

Remarks

Due to security concerns, when not specifying ProtectedAccessCredentials, caller must specify ClientCertificate and UserCredentials. This should cause the PAC provisioning to happen securely.


7.2.2.15 XProfileEAPFAST_GTCType

typedef struct {

[optional] string RoamingIdentity; ServerIdentityType ServerIdentity; UserCredentialsType UserCredentials; [optional] ManualPACType ProtectedAccessCredentials; [optional] 6CertificateHandleType ClientCertificate;

} XProfileEAPFAST_GTCType;

Field Description

RoamingIdentity max 80 chars, not including the Null termination

ServerIdentity

UserCredentials

ProtectedAccessCredentials

ClientCertificate

Remarks

Due to security concerns, when not specifying ProtectedAccessCredentials, caller must specify ClientCertificate and UserCredentials. This should cause the PAC provisioning to happen securely.


7.2.2.16 XProfileEAPFAST_TLSType

typedef struct {


143

[optional] string RoamingIdentity; ServerIdentityType ServerIdentity; UserCredentialsType UserCredentials; [optional] ManualPACType ProtectedAccessCredentials; 6CertificateHandleType ClientCertificate;

} XProfileEAPFAST_TLSType;

Field Description

RoamingIdentity max 80 chars, not including the Null termination

ServerIdentity

UserCredentials User credentials (note: password field will be ignored in this inner method).

ProtectedAccessCredentials

ClientCertificate

Remarks

Intel AMT does not check Roaming Identity for more than correct length and for falling within the ASCII character set. This parameter is used to authenticate with external equipment such as a RADIUS server, and must conform to the naming requirements of such devices or services.

7.2.2.17 ServerIdentityType

typedef struct {

[optional] 66CertificateHandleType CertificateIssuer; [optional] CertificateNameType Certificate;

} ServerIdentityType;

Field Description

CertificateIssuer An optional handle of a specific trusted root CA

Certificate A name descriptor of the trusted certificate

7.2.2.18 CertificateNameType

typedef struct {

string ServerOrCertName; CertNameOptionsType Options;

} CertificateNameType;


144

Field Description

ServerOrCertName

Options

7.2.2.19 CertNameOptionsType

typedef enum<string> {

CertNameMatch, DomainSuffixMatch

} CertNameOptionsType;

Field Description

CertNameMatch Certificate CN field must match exactly

DomainSuffixMatch Certificate CN field suffix should match

7.2.2.20 UserCredentialsType

typedef struct {

string Username; string Password; [optional] string Domain;

} UserCredentialsType;

Field Description

Username Username (max 32 chars, not including the Null termination)

Password Password (max 32 chars, not including the Null termination)

Domain Domain name (max 40 chars, not including the Null termination)

Remarks

Intel AMT does not check the strings included in this type for more than correct length. These parameters are used to authenticate with external equipment such as a RADIUS server, and must conform to the naming requirements of such devices or services.


145

7.2.2.21 ManualPACType

typedef struct {

BinaryData PACData; [optional] string Password;

} ManualPACType;

Field Description

PACData Binary data containing the PAC information

Password Optional password to extract the PAC information from the PAC Data

Remarks

Due to security concerns: this structure is used for setting PAC information and is never returned by Intel AMT.


146

7.3 Storage Administration Interface Namespace : http://schemas.intel.com/platform/client/StorageAdministration/2004/01 Port : http://hostname:port/StorageAdministrationService


Local Access −

Network Access √

The Storage Administration Interface enables administrators to reconfigure the global parameters that govern allocation and use of third-party non-volatile storage.

Method Description

GetGlobalStorageAttributes Get the global attributes of the third party storage system in the Intel AMT device.

SetGlobalStorageAttributes Set global attributes of the third party storage system in the Intel AMT device.

AdminGetRegisteredApplications Get list of registered third party applications from the Intel AMT device.

AdminGetApplicationAttributes Get attributes of a third party application from the Intel AMT device.

AdminRemoveApplication Remove a registered application from the Intel AMT device.

AddStorageEaclEntry Add storage Enterprise Access Control List (EACL) entry.

EnumerateStorageEaclEntries Enumerate the EACL.

GetStorageEaclEntry Get one EACL entry.

RemoveStorageEaclEntry Remove one EACL entry.

AddStorageFpaclEntry Add Factory Partner Allocation Control List (FPACL) entry.

EnumerateStorageAllocEntries Enumerate the FPACL and NACL.

GetStorageAllocEntry Get one FPACL or NACL entry.

UpdateStorageFpaclEntry Update a FPACL entry.

RemoveStorageFpaclEntry Remove one FPACL entry.

7.3.1 Service APIs


147

7.3.1.1 GetGlobalStorageAttributes This function returns the global attributes that govern storage allocation and use for all applications.

Header PT_STATUS GetGlobalStorageAttributes( [out] GlobalStorageAttributesType Attributes

);


Parameters If the request succeeds, the global attributes are returned in Attributes.


Code Description



7.3.1.2 SetGlobalStorageAttributes This function modifies one or more global attributes that govern the allocation and use of non-volatile storage for all third-party applications.

Header PT_STATUS SetGlobalStorageAttributes( [in, optional] uint32 MaxPartnerStorage, [in, optional] uint16 MaxNonPartnerTotalAllocationSize

);


Parameters All parameters are optional.

If present, MaxPartnerStorage specifies a new value for the size of the portion of third-party non-volatile storage that is reserved for partner applications. This size is specified as a number of bytes. The remaining portion of third-party non-volatile storage is used for non-partner applications. The total size of non-volatile storage is an implementation-dependent quantity, but shall not be less than 96 kilobytes. The size must be a multiple of 4kBytes.


148

If present, MaxNonPartnerTotalAllocationSize specifies the maximum total number of bytes that can be allocated by any application that is not in the Factory Partner Allocation Control List. The size must be a multiple of 4kBytes.

The result of this function is subject to the current allocated space. If the non-partner currently allocated space is larger than the portion which is left after MaxPartnerStorage is increased, then the function will fail. (The IT would have to first remove the non-partner application(s) and reduce the non-partner allocated space).

If the MaxNonPartnerTotalAllocationSize is smaller than the size currently used by a non-partner application, then the function will fail. Similarly, if one of the new values contradicts the current actual allocation (e.g. a non-partner application has allocated more space than defined in the new MaxNonPartnerTotalAllocationSize value), then the call will fail.


Code Description



One of the attribute values supplied is invalid. (For examples, one of the values is not a multiple of 4kb, is larger than the total storage space, or does not match the currently allocated space). None of the parameters will be modified.



7.3.1.3 AdminGetRegisteredApplications This function returns a list of handles, each associated with a storage application which has registered to the Intel AMT device in the past (i.e. in the ARL list). Each handle can be used to AdminGetApplicationAttributes or AdminRemoveApplication.

Header PT_STATUS AdminGetRegisteredApplications ( [in] uint32 StartIndex, [out] uint32 TotalCount, [out] uint32 HandlesCount, [out] StorageApplicationHandleListType ApplicationHandles

);



149

Parameters StartIndex indicates the first application handle to retrieve. To enumerate the entire list, an application sends this message with StartIndex set to 1. If TotalCount is greater than HandlesCount (which indicates that an incomplete list has been returned), then the application can send additional messages to retrieve the remainder of the list, each time setting StartIndex to point to the handle that follows the last one returned in the previous message.

If no registered applications exist, the function will always return PT_STATUS_SUCCESS with an empty list and TotalCount = HandlesCount = 0.

If the operation succeeds, then the list of application handles is returned in ApplicationHandles.


Code Description




7.3.1.4 AdminGetApplicationAttributes This function returns the attributes for any single registered ISV storage application.

Header PT_STATUS AdminGetApplicationAttributes ( [in] StorageApplicationHandleType Handle, [out] StorageApplicationAttributesType Attributes,

);


Parameters Handle specifies the application whose attributes are being requested.

If the operation succeeds, then Attributes contains the requested application attributes.


Code Description




150


7.3.1.5 AdminRemoveApplication Releases all Intel AMT resources associated with a single ISV application. If the application owns any storage blocks, then they are released, along with any associated permissions group resources. The application is removed from all permissions groups associated with storage blocks that are owned by another application. This function has exactly the same results as the ISVS_RemoveApplication command in the storage interface.

Header PT_STATUS AdminRemoveApplication( [in] StorageApplicationHandleType Handle

);


Parameters Handle

Specifies the application being removed.


Code Description




7.3.1.6 AddStorageEaclEntry AddStorageEaclEntry adds a new ISV Storage Enterprise Access Control List (EACL) entry and returns a handle that can be used in subsequent EACL operations.

Header PT_STATUS AddStorageEaclEntry( [in] StorageEaclEntryType Entry, [out] StorageEaclEntryHandleType Handle

);


151


Parameters Entry is an EACL entry to be added to the list.

If the request succeeds, then a handle is returned in Handle. This handle can be used to subsequently remove the entry (RemoveStorageEaclEntry) or retrieve its contents (GetStorageEaclEntry).


Code Description


PT_STATUS_INVALID_NAME Enterprise Name is invalid.

PT_STATUS_DUPLICATE Entry already exists in EACL.

PT_STATUS_MAX_LIMIT_REACHED Storage Enterprise ACL is full.



7.3.1.7 EnumerateStorageEaclEntries EnumerateStorageEaclEntries returns a list of ISV Storage Enterprise Access Control List (EACL) entry handles that can be used in subsequent EACL operations.

Header PT_STATUS EnumerateStorageEaclEntries( [in] uint16 StartIndex, [out] uint16 TotalCount, [out] uint16 HandlesCount, [out] StorageEaclEntryHandleListType Handles

);


Parameters StartIndex indicates the first EACL entry to retrieve. To enumerate the entire list, an application sends this message with StartIndex set to 1. If TotalCount is greater than HandlesCount, then it indicates that an incomplete list has been returned. When this happens, the application can send additional messages to retrieve the remainder of the list, each time setting StartIndex to point to the record that follows the last one returned in the previous message.


152

If no EACL entries exist, then the function will always return PT_STATUS_SUCCESS with an empty list and TotalCount = HandlesCount = 0.

If the request succeeds, then TotalCount contains the total number of entries in the EACL, and Handles contains a list of HandlesCount entry handles.


Code Description




7.3.1.8 GetStorageEaclEntry GetStorageEaclEntry returns a single ISV Storage Enterprise Access Control List (EACL) entry, given a handle returned by AddStorageEaclEntry or EnumerateStorageEaclEntries.

Header PT_STATUS GetStorageEaclEntry ( [in] StorageEaclEntryHandleType Handle, [out] StorageEaclEntryType Entry

);


Parameters Handle contains a handle to one of the EACL entries. Handles are returned by AddStorageEaclEntry and EnumerateStorageEaclEntries.


Code Description





153

7.3.1.9 RemoveStorageEaclEntry RemoveStorageEaclEntry removes a single ISV Storage Enterprise Access Control List (EACL) entry, given a handle returned by AddStorageEaclEntry or EnumerateStorageEaclEntries. If an application using this Enterprise ACL entry has registered, then this operation will fail. The applications using the entry must be removed before the entry itself can be removed.

Header PT_STATUS RemoveStorageEaclEntry ( [in] StorageEaclEntryHandleType Handle

);


Parameters Handle contains a handle to one of the EACL entries. Handles are returned by AddStorageEaclEntry and EnumerateStorageEaclEntries.


Code Description



PT_STATUS_STORAGE_ACL_ENTRY_IN_USE The entry could not be removed because an active registration has a reference on it.


7.3.1.10 AddStorageFpaclEntry This function adds an entry to the ISV Storage Factory Partner Allocation Control List (FPACL).

Non-partner allocation control list (NACL) entries cannot be added using this method. NACL entries are added when a non-partner application registers for the first time.

Header PT_STATUS AddStorageFpaclEntry( [in] StorageAllocEntryType Entry, [out] StorageAllocEntryHandleType Handle

);



154

Parameters Entry contains the new FPACL entry. Note: if the entry contains a non-partner application, then the function will fail. If the operation is successful, then a unique 32-bit FPACL entry handle is returned in Handle. This handle can be used in subsequent calls to GetStorageFpaclEntry, UpdateStorageFpaclEntry, and RemoveStorageFpaclEntry.


Code Description


PT_STATUS_MAX_LIMIT_REACHED Factory Partner ACL is full.

PT_STATUS_INVALID_NAME Vendor Name or Application Name is invalid.

PT_STATUS_INVALID_PARAMETER Data in Entry is invalid.

PT_STATUS_DUPLICATE Entry already exists in FPACL or in NACL.


PT_STATUS_INVALID_BYTE_COUNT TotalAllocationSize in Entry is invalid.


7.3.1.11 EnumerateStorageAllocEntries This function enumerates entries in the ISV Storage Factory Partner Allocation Control List (FPACL) and in the non-partner Allocation Control List.

Header PT_STATUS EnumerateStorageAllocEntries( [in] uint16 StartIndex, [out] uint16 TotalCount, [out] uint16 HandlesCount, [out] StorageAllocEntryHandleListType Handles

);


Parameters StartIndex indicates the first storage application entry to retrieve. To enumerate the entire list, an application sends this message with StartIndex set to 1. If TotalCount is greater than HandlesCount, then it indicates that an incomplete list has been returned. In this case, the application can send additional messages to retrieve the remainder of the list, each time setting StartIndex to point to the record that follows the last one returned in the previous message.


155

If no storage allocation entries exist, then the function will always return PT_STATUS_SUCCESS with an empty list and TotalCount = HandlesCount = 0.

If the request succeeds, then TotalCount contains the total number of entries in the FPACL and NACL together, and Handles contains a list of HandlesCount FPACL or NACL entry handles.


Code Description




7.3.1.12 GetStorageAllocEntry This function returns a single ISV Storage Factory Partner Allocation Control List (FPACL) or non-partner Allocation Control List (NACL) entry, given the entry’s handle. FPACL entry handles are returned by the methods AddStorageFpaclEntry and EnumerateStorageAllocEntries. NACL entry handles are returned by EnumerateStorageAllocEntries.

Header PT_STATUS GetStorageAllocEntry( [in] StorageAllocEntryHandleType Handle, [out] StorageAllocEntryType Entry

);


Parameters

Handle

Specifies the FPACL or NACL entry to fetch.

Entry

If successful, contains an external representation of the requested FPACL or NACL entry.


Code Description



156

Code Description



7.3.1.13 UpdateStorageFpaclEntry This function updates the allocation size of an existing entry in the ISV Storage Factory Partner Allocation Control List (FPACL), given the entry’s handle and the new size. FPACL entry handles are returned by the methods AddStorageFpaclEntry and EnumerateStorageAllocEntries.

If the method increases the allowed allocation size, then it will succeed. Decreasing the size will only succeed if the currently allocated size for this application does not exceed the new size.

Note: Non-partner allocation control list (NACL) entries cannot be updated using this function. The allowed allocation size for non-partner applications can be set using the SetGlobalStorageAttributes method.

Header PT_STATUS UpdateStorageFpaclEntry( [in] StorageAllocEntryHandleType Handle, [in] uint32 NewAllocationSize

);


Parameters Handle specifies the FPACL entry to update.

NewAllocationSize specifies the new maximum size, in bytes, of storage area that an application of this type can allocate. The size must be a multiple of 4kb.


Code Description



PT_STATUS_INVALID_PARAMETER The handle points to an NACL entry.


PT_STATUS_INVALID_BYTE_COUNT NewAllocationSize is invalid: i.e., it is not a multiple of 4kb or the size is smaller than the currently allocated size for this application.


157


7.3.1.14 RemoveStorageFpaclEntry This function removes an entry from the ISV Storage Factory Partner Allocation Control List (FPACL), given the entry’s handle. FPACL entry handles are returned by the methods AddStorageFpaclEntry and EnumerateStorageAllocEntries. If an application using this FPACL entry has registered, then this operation will fail. The applications using the entry must be removed before the entry itself can be removed.

Note: Non-partner allocation control list (NACL) entries cannot be removed using this function. NACL entries are removed when all application instances of the non-partner application are removed from the device.

Header PT_STATUS RemoveStorageFpaclEntry( [in] StorageAllocEntryHandleType Handle

);


Parameters Handle

Specifies the FPACL entry to be removed.


Code Description



PT_STATUS_INVALID_PARAMETER The handle points to a NACL entry.

PT_STATUS_STORAGE_ACL_ENTRY_IN_USE The entry could not be removed because an active registration has a reference on it



158


7.3.2.1 GlobalStorageAttributesType typedef struct _GlobalStorageAttributesType { uint32 TotalStorage; uint32 TotalAllocatedStorage; uint32 MaxPartnerStorage; uint32 TotalPartnerAllocatedStorage; uint32 MaxNonPartnerStorage; uint16 MaxFpaclEntries; uint16 MaxAslEntries; uint16 MaxEaclEntries; uint16 MaxGroupsPerBlock; uint16 MaxMembersPerGroup; uint16 MaxNonPartnerTotalAllocationSize; } GlobalStorageAttributesType;

Field Description

TotalStorage

Specifies the total size, in bytes, of the portion of non-volatile memory that is available to third-party applications. This total is subdivided into partner and non-partner areas.

TotalAllocatedStorage Specifies the total size, in bytes, of the portion of third-party application storage which is already allocated for use by applications.

MaxPartnerStorage

Specifies the size, in bytes, of the portion of third-party non-volatile storage that is reserved for partner applications. This size is specified as a number of bytes. The sum of MaxPartnerStorage and MaxNonPartnerStorage must not exceed the total size of third-party non-volatile storage. The total size of non-volatile storage is an implementation-dependent quantity, but shall not be less than 96 kilobytes.

TotalPartnerAllocatedStorage Specifies the size, in bytes, of the portion of third-party partner application storage which is already allocated for use by applications.


159

MaxNonPartnerStorage

Specifies the size, in bytes, of the portion of third-party non-volatile storage that is available for non-partner applications. This area also is open to partner applications when partner storage becomes unavailable. This size is specified as a number of bytes. The sum of MaxPartnerStorage and MaxNonPartnerStorage must not exceed the total size of third-party non-volatile storage. The total size of non-volatile storage is an implementation-dependent quantity, but shall not be less than 96 kilobytes.

MaxFpaclEntries

Specifies the maximum number of entries supported in the Factory Partner Allocation Control List (FPACL). This is also the maximum number of different partner applications supported by the Intel AMT device at one time.

MaxAslEntries

Specifies the maximum number of entries in the Application Session List (ASL). This is the maximum number of application sessions supported concurrently at the same time.

MaxEaclEntries Specifies the maximum number of entries in the Enterprise ACL.

MaxGroupsPerBlock

Specifies the maximum number of permissions groups that may be associated with a single block of storage. Every permissions group is associated with a single block of storage.

MaxMembersPerGroup Specifies the maximum number of members that any permissions group may have.

MaxNonPartnerTotalAllocationSize The maximum total allocation size, in bytes, for a single non-partner storage application.

7.3.2.2 StorageApplicationHandleType typedef uint32 StorageApplicationHandleType;

Field Description

StorageApplicationHandleType

A handle to a registered storage application that can be used in operations such as AdminGetApplicationAttributes and RemoveStorageApplication.

7.3.2.3 StorageApplicationHandleListType typedef struct _StorageApplicationHandleListType {


160

StorageApplicationHandleType *Handle; } StorageApplicationHandleListType;

Field Description

Handle A list of handles to registered storage applications, each of which can be used in operations such as AdminGetApplicationAttributes and RemoveStorageApplication.

7.3.2.4 StorageApplicationAttributesType typedef _StorageApplicationAttributesType { ISVS_APP_ATTR_TYPE AttrType; union _AppAttributes { StorageSnrpApplicationAttributesType SnrpAppTypes; } uint32 CurrentAllocationSize; boolean ActiveSession; boolean Partner; } StorageApplicationAttributesType;

Field Description

AttrType The type of application attributes in this entry.

_AppAttributes A union containing the application attributes themselves. Each different attribute type defines a different application attributes structure.

SnrpAppTypes An application attribute entry that matches the SNRP protocol.

CurrentAllocationSize The number of bytes of storage currently allocated to the application.

ActiveSession Set to TRUE if Intel AMT has active session state for the application; otherwise this field is set to FALSE.

Partner Set to TRUE if the application is in the Factory Partner Allocation List (FPACL), otherwise this field is set to FALSE.

7.3.2.5 StorageSnrpApplicationAttributesType typedef _StorageSnrpApplicationAttributesType { GUID UUID; string VendorName; string ApplicationName; string EnterpriseName; } StorageSnrpApplicationAttributesType;


161

Field Description

UUID Unique identifier of this application. This should be the 16-byte SMBIOS UUID value of the machine from which the registration originated.

VendorName

The name of the vendor as specified by the vendor and provided in the ISVS_RegisterApplication operation request message. The string length must accommodate, at most, 64 bytes when encoded in UTF-8 encoding.

ApplicationName

The name of the ISV application, as specified by the vendor and provided in the ISVS_RegisterApplication operation request message. The string length must accommodate, at most, 64 bytes when encoded in UTF-8 encoding.

EnterpriseName

The name of the enterprise that acquires and owns the Intel AMT system, as specified by the enterprise and provided in the ISVS_RegisterApplication operation request message. The string length must accommodate, at most, 64 bytes when encoded in UTF-8 encoding.

7.3.2.6 GUID This structure is defined to represent Globally Unique Identifiers (GUIDs).

typedef byte[16] Guid;

Field Description

Guid A 16-byte array representing a Globally Unique Identifier.

7.3.2.7 StorageEaclEntryType typedef struct _StorageEaclEntryType { string EnterpriseName; } StorageEaclEntryType;

Field Description

EnterpriseName

The name of an enterprise that has permission to access third-party storage. This means that computing processes running within the identified enterprise have access to third-party storage controlled by the Intel AMT device. These processes will execute third-party application code or enterprise IT code. In many cases, only the enterprise that owns the Intel AMT-managed PC will have access to third-party storage. However, some owner enterprises may grant another enterprise access to storage so that it can perform management services on its behalf. The string length must accommodate, at most, 64 bytes when encoded in UTF-8 encoding


162

7.3.2.8 StorageEaclEntryHandleType typedef uint32 StorageEaclEntryHandleType;

Field Description

StorageEaclEntryHandleType

A handle to an entry in the Enterprise Access Control List (EACL) that can be used in operations such as GetStorageEaclEntry and RemoveStorageEaclEntry.

7.3.2.9 StorageEaclEntryHandleListType typedef struct _StorageEaclEntryHandleListType { StorageEaclEntryHandleType *Handle; } StorageEaclEntryHandleListType;

Field Description

Handle A list of Enterprise Access Control List (EACL) entry handles, each of which can be used in operations such as GetStorageEaclEntry and RemoveStorageEaclEntry.

7.3.2.10 StorageAllocEntryType typedef struct _StorageAllocEntryType { ISVS_APP_ATTR_TYPE AttrType; union _AppAttrEntry { StorageAllocSnrpEntryType StorageAllocSnrpEntry; } boolean IsPartner; uint32 TotalAllocationSize; } StorageAllocEntryType;

Field Description

AttrType The type of application attributes in this entry.

_AppAttrEntry A union containing the application attributes themselves. Each different attribute type defines a different application attributes structure.

StorageAllocSnrpEntry An application attribute entry that matches the SNRP protocol.

IsPartner TRUE if this application is a partner application. FALSE otherwise.

TotalAllocationSize Maximum size, in bytes, of storage area an application of this type can allocate. Must be a multiple of 4kb.


163

7.3.2.11 StorageAllocSnrpEntryType typedef struct _StorageAllocSnrpEntryType { string ApplicationName; string VendorName; } StorageAllocSnrpEntryType;

Field Description

ApplicationName Name of an ISV storage application. The string length must accommodate, at most, 64 bytes when encoded in UTF-8 encoding.

VendorName Name of the ISV vendor name. The string length must accommodate, at most, 64 bytes when encoded in UTF-8 encoding.

7.3.2.12 StorageAllocEntryHandleType typedef uint32 StorageAllocEntryHandleType;

Field Description

StorageAllocEntryHandleType A handle to an entry in the Factory Partner Allocation Control List (FPACL) or non-partner Allocation Control List (NACL)

7.3.2.13 StorageAllocEntryHandleListType typedef struct _StorageAllocEntryHandleListType { StorageAllocEntryHandleType *Handle; } StorageAllocEntryHandleListType;

Field Description

Handle A list of Storage Application Control List (FPACL) or non-partner Allocation Control List (NACL) entry handles.

7.3.2.14 ISVS_APP_ATTR_TYPE typedef UINT32 ISVS_APP_ATTR_TYPE; static const ISVS_APP_ATTR_TYPE ISVS_APP_ATTR_TYPE_NONE = 0; static const ISVS_APP_ATTR_TYPE ISVS_APP_ATTR_TYPE_SNRP = 1;

Remarks

A parameter of this type should always have the value of 1.


164


165

7.4 Hardware Asset Interface Namespace : http://schemas.intel.com/platform/client/HardwareAsset/2004/01 Port : http://hostname:port/HardwareAssetService


Local Access −

Network Access √

The Hardware Asset Interface exposes operations that return hardware asset data.

Method Description

EnumerateAssetTypes Enumerates the asset types supported by the Intel AMT device.

GetAssetData Gets asset data of a specific type.

7.4.1 Service APIs

7.4.1.1 EnumerateAssetTypes This operation is used to enumerate the names of hardware asset types supported by the Intel AMT device.

Header PT_STATUS EnumerateAssetTypes( [out] uint32 Count, [out] AssetTypeArrayType AssetTypes

);


Parameters The Count output parameter contains the number of asset types returned.

The AssetTypes output parameter returns an array of codes that indicate the asset types for which Intel AMT contains data.


Field Description



166


7.4.1.2 GetAssetData This operation is used to return HW asset data described in Section 7.4.1 above.

Header PT_STATUS GetAssetData( [in] AssetTypeType AssetType, [out] uint32 Count, [out] AssetDataArrayType AssetData

);


Parameters The AssetType input parameter defines the name of the asset data to be retrieved.

The out parameter, AssetData, is an array that contains the requested asset data. If AssetType contains a valid type for which Intel AMT does not contain data, then a 0 size array will be returned.

The out parameter Count contains the number of elements in the AssetData array.


Code Description


PT_STATUS_MAX_LIMIT_REACHED Indicates the platform contains additional asset data information that was not captured by the Intel AMT device due to container space limitation.


PT_STATUS_INVALID_PARAMETER Requested asset type is not supported

7.4.2 Service Data Types The following sections describe the data structures for hardware asset information supported by the Intel AMT device. The hardware asset information is mainly from SMBIOS data structures and system BIOS. These data types are defined under the namespace:

http://schemas.intel.com/platform/client/AssetManager/2004/01

http://schemas.intel.com/platform/client/AssetManager/2004/01


167

7.4.2.1 PT_BIOS_CHARACTERISTICS PT_BIOS_CHARACTERISTICS defines a set of bit flags that indicate the features that the BIOS support.

typedef struct _PT_BIOS_CHARACTERISTICS { uint32 reserved_1 : 2; uint32 unknown : 1; uint32 BIOS_characteristics_not_supported : 1; uint32 ISA_supported : 1; uint32 MCA_supported : 1; uint32 EISA_supported : 1; uint32 PCI_supported : 1; uint32 PC_card_supported : 1; uint32 PnP_supported : 1; uint32 APM_supported : 1; uint32 BIOS_upgradeable : 1; uint32 BIOS_shadowing_allowed : 1; uint32 VL_VESA_supported : 1; uint32 ESCD_supported : 1; uint32 boot_from_CD_supported : 1; uint32 selectable_boot_supported : 1; uint32 BIOS_ROM_socketed : 1; uint32 boot_from_PC_card_supported : 1; uint32 EDD_spec_supported : 1; uint32 int13h_floppy_for_NEC_9800_supported : 1; uint32 int13h_floppy_for_Toshiba_supported : 1; uint32 int13h_5_25_in_360_kb_floppy_supported : 1; uint32 int13h_5_25_in_1_2_mb_floppy_supported : 1; uint32 int13h_3_5_in_720_kb_floppy_supported : 1; uint32 int13h_3_5_in_2_88_mb_floppy_supported : 1; uint32 int5h_print_screen_services_supported : 1; uint32 int9h_8042_keyboard_services_supported : 1; uint32 int14h_serial_services_supported : 1; uint32 int17h_printer_services_supported : 1; uint32 int10h_CGA_and_mono_video_supported : 1; uint32 NEC_PC_98 : 1; } PT_BIOS_CHARACTERISTICS;

7.4.2.2 PT_BIOS PT_BIOS represents the Basic Input/Output System (BIOS) of the Intel AMT managed system. There is, at most, one instance of this structure in the Intel AMT hardware asset inventory.

typedef struct _PT_BIOS { uint32 StructureVersion; uint8 Vendor[65]; uint8 Version[65]; uint8 ReleaseDate[65]; uint8 Padding; PT_BIOS_CHARACTERISTICS Characteristics; } PT_BIOS;


168

Field Description

StructureVersion The version of this structure. 16 MSB correspond to the major version, 16 LSB correspond to the minor version. For this revision of the network interface specification, the structure version is 1.0.

Vendor The name of the BIOS vendor. Corresponds to the string referenced by the Vendor field in the SMBIOS Type 0 structure.

Version The version of the system BIOS image. Corresponds to the string referenced by the BIOS Version field in the SMBIOS Type 0 structure.

ReleaseDate

The release date of the system BIOS image. The date is in either mm/dd/yy or mm/dd/yyyy format. If the year portion of the string is two digits, then the year is assumed to be 19yy. The mm/dd/yyyy format is required for SMBIOS version 2.3 and later. Corresponds to the BIOS Release Date field in the SMBIOS Type 0 structure.

Padding A padding byte to make sure all structure fields are correctly aligned. Set to 0.

Characteristics Defines which functions the BIOS supports (PCI, PCMCIA, flash, etc.). Corresponds to the BIOS Characteristics field in the SMBIOS Type 0 structure.

7.4.2.3 PT_COMPUTER_SYSTEM PT_COMPUTER_SYSTEM represents the system being managed by the Intel AMT device. There is, at most, one instance of this structure in the Intel AMT hardware asset inventory.

PT_COMPUTER_SYSTEM structure members are defined below:

typedef struct _PT_COMPUTER_SYSTEM { uint32 StructureVersion; uint8 Manufacturer[65]; uint8 Product[65]; uint8 Version[65]; uint8 SerialNumber[65]; BYTE UUID[16]; } PT_COMPUTER_SYSTEM;

Descriptions of the PT_COMPUTER_SYSTEM structure members are given below:

Field Description


Manufacturer The name of the system manufacturer. Corresponds to the string referenced by the Manufacturer field in the SMBIOS Type 1 structure.

Product The name of the system product. Corresponds to the string referenced by the Product Name field in the SMBIOS Type 1 structure.


169

Version The version of the system product. Corresponds to the string referenced by the Version field in the SMBIOS Type 1 structure.

SerialNumber The serial number of the specific instance of the system product. Corresponds to the string referenced by the Serial Number field in the SMBIOS Type 1 structure.

UUID

Universal Unique ID number. If the value is all FFh, the ID is not currently present in the system, but is settable. If the value is all 00h, the ID is not present in the system. Corresponds to the UUID field of the SMBIOS Type 1 structure

7.4.2.4 PT_BASEBOARD The PT_BASEBOARD structure has information about a system’s baseboard. The structure’s members are from the Base Board Information (Type 2) SMBIOS structure. There is, at most, one instance of this structure in the Intel AMT hardware asset inventory.

typedef struct _PT_BASEBOARD { uint32 StructureVersion; uint8 Manufacturer[65]; uint8 Product[65]; uint8 Version[65]; uint8 SerialNumber[65]; uint8 AssetTag[65]; uint8 Replaceable; uint8 Padding[2]; } PT_BASEBOARD;

Field Description


Manufacturer The name of the manufacturer of the baseboard product. Corresponds to the string referenced by the Manufacturer field in the Type 2 structure.

Product The name of the baseboard product. Corresponds to the string referenced by the Product field in the Type 2 structure.

Version The version of the baseboard product. Corresponds to the string referenced by the Version field in the Type 2 structure.

SerialNumber The serial number of the specific instance of the baseboard product. Corresponds to the string referenced by the Serial Number field in the Type 2 structure.

AssetTag The asset tag string of the specific instance of the baseboard product. Corresponds to the string referenced by the Asset Tag field in the Type 2 structure.


170

Replaceable Boolean value. TRUE if baseboard is replaceable; FALSE if baseboard is not replaceable. Corresponds to bit 3 of the Feature Flags field of the Type 2 structure.

Padding Pad the structure to be 4-byte aligned. Set to 0.

7.4.2.5 PT_PROCESSOR The PT_PROCESSOR structure has information pertaining to the system’s processor. Structures’ members are based on the Processor Information (Type 4) SMBIOS structure. There is, at most, one instance of this structure per physical processor in the Intel AMT hardware asset inventory.

PT_PROCESSOR structure members are defined below:

typedef struct _PT_PROCESSOR { uint32 StructureVersion; uint32[2] ID; uint16 MaxSocketSpeed; uint16 CurrentSpeed; PT_PROCESSOR_STATUS Status; PT_PROCESSOR_TYPE Type; PT_PROCESSOR_FAMILY Family; PT_PROCESSOR_UPGRADE UpgradeInformation; uint8 SocketPopulated; uint8 SocketDesignation[65]; uint8 Manufacturer[65]; uint8 Version[65]; } PT_PROCESSOR;

Field Description


SocketDesignation The reference designation for the processor socket. Corresponds to the string referenced by the Socket Designation field in the Type 4 structure.

Manufacturer The name of the processor manufacturer. Corresponds to the string referenced by the Processor Manufacturer field in the Type 4 structure.

Version The version of the processor product. Corresponds to the string referenced by the Processor Version field in the Type 4 structure.


171

ID

Contains processor-specific information that describes the processor’s features. For x86 class CPUs, the field’s format depends on the processor’s support of the CPUID instruction. If the instruction is supported, then the Processor ID field contains two DWORD-formatted values. The first is the EAX value returned by a CPUID instruction with input EAX set to 1; the second is the EDX value returned by that instruction. Otherwise, only the first two bytes of the Processor ID field are significant (all others are set to 0) and contain (in WORD-format) the contents of the DX register at CPU reset. Corresponds to the Processor ID field of the Type 4 structure.

MaxSocketSpeed

Maximum processor speed (in MHz) supported by the system for this processor socket. 0E9h for a 233 MHz processor. If the value is unknown, the field is set to 0. Corresponds to the Max Speed field of the Type 4 structure. Note: This value is rounded down (e.g. if the speed is 3615MHz, the value will be 3600MHz).

CurrentSpeed

Current speed of processor. Same format as MaxSocketSpeed. Corresponds to the Current Speed field of the Type 4 structure. Note: This value is rounded down (e.g., if the speed is 3615MHz, then the value will be 3600MHz).

Status Indicates the status of the processor. Valid values are specified by the PROCESSOR_STATUS enumeration. Corresponds to bits 0:2 of the Status field of the Type 4 structure.

Type Specifies the type of processor. Valid values are specified by the PROCESSOR_TYPE enumeration. Corresponds to the Processor Type field in the Type 4 structure.

Family Specifies the processor family. Valid values are specified by the PROCESSOR_FAMILY enumeration. Corresponds to the Processor Family field in the Type 4 structure.

Upgrade Specifies the processor upgrade method. Valid values are specified by the PROCESSOR_UPGRADE enumeration. Corresponds to the Processor Upgrade field of the Type 4 structure.

SocketPopulated Boolean value. If the processor socket is populated, TRUE. If the processor socket is not populated, FALSE. Corresponds to bit 6 of the Status field of the Type 4 structure.

7.4.2.5.1 PT_PROCESSOR_TYPE The PROCESSOR_TYPE enumeration is derived from the Processor Information (Type 4) SMBIOS structure.

typedef enum<uint8> _PT_PROCESSOR_TYPE { PT_PROCESSOR_TYPE_OTHER = 1, PT_PROCESSOR_TYPE_UNKNOWN = 2, PT_PROCESSOR_TYPE_CENTRAL = 3, PT_PROCESSOR_TYPE_MATH = 4, PT_PROCESSOR_TYPE_DSP = 5, PT_PROCESSOR_TYPE_VIDEO = 6 } PT_PROCESSOR_TYPE;


172

Code Description

PT_PROCESSOR_TYPE_OTHER Processor type is not specified in this enumeration.

PT_PROCESSOR_TYPE_UNKNOWN Processor type is not known.

PT_PROCESSOR_TYPE_CENTRAL Processor is a CPU.

PT_PROCESSOR_TYPE_MATH Processor is a math coprocessor.

PT_PROCESSOR_TYPE_DSP Processor is a digital signal processor.

PT_PROCESSOR_TYPE_VIDEO Processor is a video processor.

7.4.2.5.2 PT_PROCESSOR_FAMILY The PROCESSOR_FAMILY enumeration is derived from the Processor Information (Type 4) SMBIOS structure.

typedef enum<uint8> _PT_PROCESSOR_FAMILY { PT_PROCESSOR_FAMILY_OTHER = 0x01, PT_PROCESSOR_FAMILY_UNKNOWN = 0x02, PT_PROCESSOR_FAMILY_8086 = 0x03, PT_PROCESSOR_FAMILY_80286 = 0x04, PT_PROCESSOR_FAMILY_INTEL_386 = 0x05, PT_PROCESSOR_FAMILY_INTEL_486 = 0x06, PT_PROCESSOR_FAMILY_8087 = 0x07, PT_PROCESSOR_FAMILY_80287 = 0x08, PT_PROCESSOR_FAMILY_80387 = 0x09, PT_PROCESSOR_FAMILY_80487 = 0x0A, PT_PROCESSOR_FAMILY_PENTIUM = 0x0B, PT_PROCESSOR_FAMILY_PENTIUM_PRO = 0x0C, PT_PROCESSOR_FAMILY_PENTIUM_II = 0x0D, PT_PROCESSOR_FAMILY_PENTIUM_MMX_TECHNOLOGY = 0x0E, PT_PROCESSOR_FAMILY_CELERON = 0x0F, PT_PROCESSOR_FAMILY_PENTIUM_II_XEON = 0x10, PT_PROCESSOR_FAMILY_PENTIUM_III = 0x11, PT_PROCESSOR_FAMILY_ITANIUM = 0x82, PT_PROCESSOR_FAMILY_PENTIUM_III_XEON = 0xB0, PT_PROCESSOR_FAMILY_PENTIUM_III_SPEEDSTEP_TECHNOLOGY = 0xB1, PT_PROCESSOR_FAMILY_PENTIUM_4 = 0xB2, PT_PROCESSOR_FAMILY_XEON = 0xB3, PT_PROCESSOR_FAMILY_XEON_MP = 0xB5, PT_PROCESSOR_FAMILY_ITANIUM_2 = 0xB8, PT_PROCESSOR_FAMILY_PENTIUM_M = 0xB9, PT_PROCESSOR_FAMILY_CELERON_D = 0xBA, PT_PROCESSOR_FAMILY_PENTIUM_D = 0xBB, PT_PROCESSOR_FAMILY_PENTIUM_EXTREME_EDITION = 0xBC, } PT_PROCESSOR_FAMILY;


173

Code Description

PT_PROCESSOR_FAMILY_OTHER Processor family is not specified in this enumeration.

PT_PROCESSOR_FAMILY_UNKNOWN Processor family is not known.

PT_PROCESSOR_FAMILY_8086 Processor family is Intel® 8086.

PT_PROCESSOR_FAMILY_80286 Processor family is Intel 80286.

PT_PROCESSOR_FAMILY_INTEL_386 Intel Intel386™ processor

PT_PROCESSOR_FAMILY_INTEL_486 Intel Intel486™ processor





PT_PROCESSOR_FAMILY_PENTIUM Intel Pentium® processor

PT_PROCESSOR_FAMILY_PENTIUM_PRO Intel Pentium® Pro processor

PT_PROCESSOR_FAMILY_PENTIUM_II Intel Pentium® II processor.

PT_PROCESSOR_FAMILY_PENTIUM_MMX_TECHNOLOGY Intel Pentium® processor with MMX™ technology.

PT_PROCESSOR_FAMILY_CELERON Intel Celeron® processor.

PT_PROCESSOR_FAMILY_PENTIUM_II_XEON Intel Pentium® II Xeon™ processor.

PT_PROCESSOR_FAMILY_PENTIUM_III Intel Pentium® III processor.

PT_PROCESSOR_FAMILY_ITANIUM Intel Itanium® processor

PT_PROCESSOR_FAMILY_PENTIUM_III_XEON Pentium® III Xeon™ processor

PT_PROCESSOR_FAMILY_PENTIUM_III_SPEEDSTEP_TECHNOLOGY Pentium® III Processor with Intel SpeedStep™ Technology

PT_PROCESSOR_FAMILY_PENTIUM_4 Intel Pentium® 4 Processor

PT_PROCESSOR_FAMILY_XEON Intel® Xeon™


174

PT_PROCESSOR_FAMILY_XEON_MP Intel® Xeon™ processor MP

PT_PROCESSOR_FAMILY_ITANIUM_2 Intel Itanium® processor

PT_PROCESSOR_FAMILY_PENTIUM_M Intel Pentium® M Processor

PT_PROCESSOR_FAMILY_CELERON_D Intel Celeron® D Processor

PT_PROCESSOR_FAMILY_PENTIUM_D Intel Pentium® D processor

PT_PROCESSOR_FAMILY_PENTIUM_EXTREME_EDITION Intel Pentium® Processor Extreme Edition

7.4.2.5.3 PT_PROCESSOR_STATUS The PT_PROCESSOR_STATUS enumeration is derived from the Processor Information (Type 4) SMBIOS structure.

typedef enum<uint8> _PT_PROCESSOR_STATUS { PROCESSOR_STATUS_UNKNOWN = 0x0, PROCESSOR_STATUS_ENABLED = 0x1, PROCESSOR_STATUS_DISABLED_BY_USER = 0x2, PROCESSOR_STATUS_DISABLED_BY_BIOS = 0x3, PROCESSOR_STATUS_WAITING_TO_BE_ENABLED = 0x4, PROCESSOR_STATUS_OTHER = 0x7, } PT_PROCESSOR_STATUS;

Code Description

PROCESSOR_STATUS_UNKNOWN Processor status is not known.

PROCESSOR_STATUS_ENABLED Processor is enabled.

PROCESSOR_STATUS_DISABLED_BY_USER Processor was disabled by user in BIOS setup.

PROCESSOR_STATUS_DISABLED_BY_BIOS Processor was disabled by BIOS due to a POST error.

PROCESSOR_STATUS_WAITING_TO_BE_ENABLED Processor is idle, waiting to be enabled.

PROCESSOR_STATUS_OTHER Specific processor status code is not specified in this enumeration.

7.4.2.5.4 PT_PROCESSOR_UPGRADE The PT_PROCESSOR_UPGRADE enumeration is derived from the Processor Information (Type 4) SMBIOS structure.

typedef enum<uint8> _PT_PROCESSOR_UPGRADE {


175

PT_PROCESSOR_UPGRADE_OTHER = 0x01, PT_PROCESSOR_UPGRADE_UNKNOWN = 0x02, PT_PROCESSOR_UPGRADE_DAUGHTER_BOARD = 0x03, PT_PROCESSOR_UPGRADE_ZIF_SOCKET = 0x04, PT_PROCESSOR_UPGRADE_REPLACEABLE_PIGGYBACK = 0x05, PT_PROCESSOR_UPGRADE_NONE = 0x06, PT_PROCESSOR_UPGRADE_LIF_SOCKET = 0x07, PT_PROCESSOR_UPGRADE_SLOT_1 = 0x08, PT_PROCESSOR_UPGRADE_SLOT_2 = 0x09, PT_PROCESSOR_UPGRADE_370_PIN_SOCKET = 0x0A, PT_PROCESSOR_UPGRADE_SLOT_M = 0x0C, PT_PROCESSOR_UPGRADE_SOCKET_423 = 0x0D, PT_PROCESSOR_UPGRADE_SOCKET_478 = 0x0F } PT_PROCESSOR_UPGRADE;

Code Description

PT_PROCESSOR_UPGRADE_OTHER Processor upgrade method is not specified in this enumeration.

PT_PROCESSOR_UPGRADE_UNKNOWN Processor upgrade method is not known.

PT_PROCESSOR_UPGRADE_DAUGHTER_BOARD Processor can be upgraded with a daughterboard.

PT_PROCESSOR_UPGRADE_ZIF_SOCKET Processor is in a Zero Insertion Force (ZIF) socket.

PT_PROCESSOR_UPGRADE_REPLACEABLE_PIGGYBACK

Processor is replaceable piggyback.

PT_PROCESSOR_UPGRADE_NONE Processor is not upgradeable.

PT_PROCESSOR_UPGRADE_LIF_SOCKET Processor is in a Low Insertion Force (LIF) socket.

PT_PROCESSOR_UPGRADE_SLOT_1 Processor is in Intel Slot 1.

PT_PROCESSOR_UPGRADE_SLOT_2 Processor is in Intel Slot 2.

PT_PROCESSOR_UPGRADE_370_PIN_SOCKET Processor is in Intel Socket 370.

PT_PROCESSOR_UPGRADE_SLOT_M Processor is in Intel Slot M.

PT_PROCESSOR_UPGRADE_SOCKET_423 Processor is in Intel Socket 423.

PT_PROCESSOR_UPGRADE_SOCKET_478 Processor is in Intel Socket 478.

7.4.2.6 PT_MEMORY_DEVICE The PT_MEMORY_DEVICE structure represents a single physical memory device. Structure members are based on the Memory Device (Type 17) SMBIOS structure. There is, at most, one instance of this structure per physical memory device in the Intel AMT hardware asset inventory.

PT_MEMORY_DEVICE structure members are defined below:

typedef struct _PT_MEMORY_DEVICE {


176

uint32 StructureVersion; uint16 Size; PT_MEMORY_FORM_FACTOR FormFactor; PT_MEMORY_TYPE Type; PT_MEMORY_TYPE_DETAIL TypeDetail; uint16 Speed; uint8 Manufacturer[65]; uint8 SerialNumber[65]; uint8 AssetTag[65]; uint8 PartNumber[65]; } PT_MEMORY_DEVICE;

Field Description


Size

The size of the memory device. If the value is 0, no memory device is installed in the socket; if the size is unknown, the field value is FFFFh. The granularity in which the value is specified depends on the setting of the most significant bit (bit 15). If the bit is 0, then the value is specified in megabyte units; if the bit is 1, then the value is specified in kilobyte units. For example, the value 8100h identifies a 256KB memory device and 0100h identifies a 256MB memory device. Corresponds to the Size field of the SMBIOS Type 17 structure.

FormFactor The implementation form factor for this memory device. Corresponds to the Form Factor field of the SMBIOS Type 17 structure.

Type The type of memory used in this device. Corresponds to the Memory Type field of the SMBIOS Type 17 structure.

TypeDetail Additional detail on the memory device type. Corresponds to the Type Detail field of the SMBIOS Type 17 structure.

Speed Identifies the speed of the device, in megahertz (MHz). If the value is 0, the speed is unknown. Note: n MHz = (1000 / n) nanoseconds (ns). Corresponds to the Speed field of the SMBIOS Type 17 structure.

Manufacturer The name of the memory device manufacturer. Corresponds to the Manufacturer field of the SMBIOS Type 17 structure.

SerialNumber The serial number of the memory device. Corresponds to the Serial Number field of the SMBIOS Type 17 structure.

AssetTag The asset tag of the memory device. Corresponds to the Asset Tag field of the SMBIOS Type 17 structure.

PartNumber The part number of the memory device. This value is set by the manufacturer and normally not changeable. Corresponds to the Part Number field of the SMBIOS Type 17 structure.

7.4.2.6.1 PT_MEMORY_FORM_FACTOR The PT_MEMORY_FORM_FACTOR enumeration is derived from the Memory Device (Type 17) SMBIOS structure.


177

typedef enum<uint8> _PT_MEMORY_FORM_FACTOR {

PT_MEMORY_FORM_FACTOR_OTHER = 01h, PT_MEMORY_FORM_FACTOR_UNKNOWN = 02h, PT_MEMORY_FORM_FACTOR_SIMM = 03h, PT_MEMORY_FORM_FACTOR_SIP = 04h, PT_MEMORY_FORM_FACTOR_CHIP = 05h, PT_MEMORY_FORM_FACTOR_DIP = 06h, PT_MEMORY_FORM_FACTOR_ZIP = 07h, PT_MEMORY_FORM_FACTOR_PROPRIETARY = 08h, PT_MEMORY_FORM_FACTOR_DIMM = 09h, PT_MEMORY_FORM_FACTOR_TSOP = 0Ah, PT_MEMORY_FORM_FACTOR_ROW_OF_CHIPS = 0Bh, PT_MEMORY_FORM_FACTOR_RIMM = 0Ch, PT_MEMORY_FORM_FACTOR_SODIMM = 0Dh, PT_MEMORY_FORM_FACTOR_SRIMM = 0Eh, PT_MEMORY_FORM_FACTOR_FBDIMM = 0Fh

} PT_MEMORY_FORM_FACTOR;

7.4.2.6.2 PT_MEMORY_TYPE The PT_MEMORY_TYPE enumeration is derived from the Memory Device (Type 17) SMBIOS structure.

typedef enum<uint8> _PT_MEMORY_TYPE {

PT_MEMORY_TYPE_OTHER = 01h, PT_MEMORY_TYPE_UNKNOWN = 02h, PT_MEMORY_TYPE_DRAM = 03h, PT_MEMORY_TYPE_EDRAM = 04h, PT_MEMORY_TYPE_VRAM = 05h, PT_MEMORY_TYPE_SRAM = 06h, PT_MEMORY_TYPE_RAM = 07h, PT_MEMORY_TYPE_ROM = 08h, PT_MEMORY_TYPE_FLASH = 09h, PT_MEMORY_TYPE_EEPROM = 0Ah, PT_MEMORY_TYPE_FEPROM = 0Bh, PT_MEMORY_TYPE_EPROM = 0Ch, PT_MEMORY_TYPE_CDRAM = 0Dh, PT_MEMORY_TYPE_3DRAM = 0Eh, PT_MEMORY_TYPE_SDRAM = 0Fh, PT_MEMORY_TYPE_SGRAM = 10h, PT_MEMORY_TYPE_RDRAM = 11h, PT_MEMORY_TYPE_DDR = 12h, PT_MEMORY_TYPE_DDR2 = 13h, PT_MEMORY_TYPE_DDR2_FBDIMM = 14h

} PT_MEMORY_TYPE;

7.4.2.6.3 PT_MEMORY_TYPE_DETAIL The PT_MEMORY_TYPE_DETAIL bit map is derived from the Memory Device (Type 17) SMBIOS structure.

typedef struct _PT_MEMORY_TYPE_DETAIL {

uint16 Reserved1 : 1;


178

uint16 Other : 1; uint16 Unknown : 1; uint16 FastPaged : 1; uint16 StaticColumn : 1; uint16 PseudoStatic : 1; uint16 RAMBUS : 1; uint16 Synchronous : 1; uint16 CMOS : 1; uint16 EDO : 1; uint16 WindowDRAM : 1; uint16 CacheDRAM : 1; uint16 NonVolatile : 1; uint16 Reserved2 : 3;

} PT_MEMORY_TYPE_DETAIL;

7.4.2.7 PT_FRU PT_FRU class defines attributes that describe the Plug’N’Play information and bus/slot location of a PCI/AGP add-in device in the PC. There is, at most, one instance of this structure per PCI or AGP FRU in the Intel AMT hardware asset inventory.

typedef struct _PT_FRU { uint32 StructureVersion; uint16 VendorID; uint16 DeviceID; uint8 RevisionID; uint8 ProgIf; uint8 Subclass; uint8 BaseClass; uint16 SubvendorID; uint16 SubsystemID; uint16 DeviceLocation; uint8 padding[2]; } PT_FRU;

Field Description


VendorID The value in the Vendor ID configuration space register

DeviceID The value in the Device ID configuration space register

RevisionID The value in the Revision ID configuration space register

ProgIf The value in the Programming Interface byte in the Class Code configuration space register

Subclass The value in the Subclass byte in the Class Code configuration space register


179

BaseClass The value in the Base Class byte in the Class Code configuration space register

SubvendorID The value in the Subvendor ID configuration space register

SubsystemID The value in the Subsystem ID configuration space register

DeviceLocation The bus and slot number where the device is installed


7.4.2.8 PT_MEDIA_DEVICE PT_MEDIA_DEVICE class defines attributes that describe IDE/SATA devices (e.g., CD-ROM drive and hard disk drive). There is, at most, one instance of this structure per physical media device in the Intel AMT hardware asset inventory.

typedef struct PT_MEDIA_DEVICE { uint32 StructureVersion; uint8 ModelNumber[40]; uint8 SerialNumber[20]; uint16 Capabilities[3]; uint32[2] MaxMediaSize; uint8 padding[2]; } PT_MEDIA_DEVICE;

Field Description


ModelNumber

This field contains the model number of the device, represented as a non-Null terminated ASCII character string of 40 bytes. If necessary, the string is padded with spaces to ensure that it is the proper length. The combination of Serial number and Model number is unique for a given manufacturer. This contains the value of the Model number field (words 46:27) of the ATA IDENTIFY DEVICE response.

SerialNumber

The serial number of the device, represented as a non-Null terminated ASCII character string of 20 bytes. If necessary, the string is padded with spaces to ensure that it is the proper length. The combination of Serial number and Model number is unique for a given manufacturer. This contains the value of the Serial number field (words 19:10) of the ATA IDENTIFY DEVICE response.

Capabilities Describes the capabilities of the media device This enumeration contains the value of the command set supported fields (words 84:82) of the ATA IDENTIFY DEVICE response.

MaxMediaSize Describes the maximum size in bytes of supported media, where MaxMediaSize[0] is the low dword.



180

7.4.2.9 PT_PORTABLE_BATTERY

The PT_PORTABLE_BATTERY corresponds to the Portable Battery Information (Type 22) SMBIOS structure. This structure supports the population of the Portable Battery group, as defined in the DMTF Mobile Supplement to Standard Groups, v1.0 and describes the attributes of the portable battery(s) for the system. The structure contains the static attributes for the group. Each structure describes a single battery pack’s attributes.

typedef struct _PT_PORTABLE_BATTERY { uint32 StructuredVersion; uint32 OEMSpecific; uint16 SBDSManufactureDate; uint16 DesignCapacity; uint16 DesignVoltage; uint16 SBDSSerialNumber; uint8 DesignCapacityMultiplier; uint8 DeviceChemistry; uint8 MaximumErrorInBatteryData; uint8 SerialNumber[65]; uint8 SBDSVersionNumber[65]; uint8 Location[65]; uint8 Manufacturer[65]; uint8 ManufactureDate[65]; uint8 DeviceName[65]; uint8 SBDSDeviceChemistry[65]; } PT_PORTABLE_BATTERY;

Field Description

StructuredVersion The version of this structure. 16 MSB correspond to the major version, 16 LSB correspond to the minor version. For this revision of the Network Interface Guide, the structure version is 1.0.

OEMSpecific Contains OEM- or BIOS vendor-specific information.

SBDSManufactureDate

The date the cell pack was manufactured, in packed format: Bits 15:9 Year, biased by 1980, in the range 0 to 127. Bits 8:5 Month, in the range 1 to 12. Bits 4:0 Date, in the range 1 to 31. For example, 01 February 2000 would be identified as 0010 1000 0100 0001b (0x2841). The Manufacture Date field must be set to 0 (no string) to for this field to be valid.

DesignCapacity The design capacity of the battery in mWatt-hours. If the value is unknown, the field contains 0. This value is multiplied by the Design Capacity Multiplier to produce the actual value.

DesignVoltage The design voltage of the battery, in mVolts. If the value is unknown, the field contains 0.


181

SBDSSerialNumber

The 16-bit value that identifies the battery’s serial number. This value, when combined with the Manufacturer, Device Name, and Manufacture Date will uniquely identify the battery. The Serial Number field must be set to 0 (no string) for this field to be valid.

DesignCapacityMultiplier

The multiplication factor of the Design Capacity value and assures that the mWatt hours value does not overflow for SBDS implementations. The multiplier default is 1, SBDS implementations use the value 10 to correspond to the data as returned from the SBDS Function 18h.

DeviceChemistry

Identifies the battery chemistry. Implementations that use a Smart Battery will set this field to 02h (Unknown) to indicate that the SBDS Device Chemistry field contains the information. 01h Other 02h Unknown 03h Lead Acid 04h Nickel Cadmium 05h Nickel metal hydride 06h Lithium-ion 07h Zinc air 08h Lithium Polymer

MaximumErrorInBatteryData

The maximum error (as a percentage in the range 0 to 100) in the Watt-hour data reported by the battery, indicating an upper bound on how much additional energy the battery might have above the energy it reports having. If the value is unknown, the field contains FFh.

SerialNumber

A string that contains the serial number for the battery. Implementations that use a Smart Battery will set this field to 0 (no string) to indicate that the SBDS Serial Number field contains the information.

SBDSVersionNumber A string that contains the Smart Battery Data Specification version number supported by this battery. If the battery does not support the function, no string is supplied.

Location A string that identifies the location of the battery, e.g. “in the back, on the left-hand side.”

Manufacturer A string that names the company that manufactured the battery.

ManufactureDate

A string that identifies the date on which the battery was manufactured.Implementations that use a Smart Battery will set this field to 0 (no string) to indicate that the SBDS Manufacture Date field contains the information.

DeviceName A string that names the battery device, e.g. “DR-36”.

SBDSDeviceChemistry A string that identifies the battery chemistry, e.g. “PbAc”. The Device Chemistry field must be set to 02h (Unknown) for this field to be valid.

Remarks

Please refer to SMBIOS 2.5 specifications Type 22 for more information about the reported fields. The order of the fields may have been changed due to alignment requirements.


182

7.4.2.10 AssetDataType PT Asset data structure is a union of all the supported asset data structures. It is primarily used to send asset data from Intel AMT firmware.

typedef struct _AssetDataType { AssetTypeType AssetType; uint32 AssetSize; BinaryData AssetData; } AssetDataType;

All asset data structures are returned as AssetData with packing alignment of 1 for all structures’ members. The data is in little endian format.

AssetType denotes the type of asset data contained in the structure.

Field Description

AssetType An enumeration specifying the type of asset data

AssetSize Size in bytes of the asset data

AssetData A byte stream of supported asset information

7.4.2.11 AssetDataArrayType typedef _ AssetDataArrayType {

AssetDataType AssetData[]; } AssetDataArrayType;

Field Description

AssetDataArrayType An array of asset type codes.

7.4.2.12 AssetTypeType AssetTypeType enumerates the values that can be specified in the AssetType field of an AssetDataType structure. Each value corresponds to a data structure type that describes an Intel AMT asset type.

typedef enum <uint32> _AssetTypeType { AssetTypeInvalid=0, AssetTypeAll =1, AssetTypeBIOS =2, AssetTypeComputerSystem =3, AssetTypeBaseboard =4, AssetTypeProcessor =5, AssetTypeMemoryModule =6, AssetTypeFRU =7,


183

AssetTypeMediaDevice =8, AssetTypePortableBattery =9, } AssetTypeType;

Code Structure

AssetTypeInvalid Reserved for internal use.

AssetTypeAll Reserved, not supported.

AssetTypeBIOS PT_BIOS

AssetTypeComputerSystem PT_COMPUTER_SYSTEM

AssetTypeBaseboard PT_BASEBOARD

AssetTypeProcessor PT_PROCESSOR

AssetTypeMemoryModule PT_MEMORY_MODULE

AssetTypeFRU PT_FRU

AssetTypeMediaDevice PT_MEDIA_DEVICE

AssetTypePortableBattery PT_PORTABLE_BATTERY

7.4.2.13 AssetTypeArrayType typedef struct _AssetTypeArrayType { AssetTypeType AssetType[]; } AssetTypeArrayType;

Code Structure

AssetType An array of asset type codes.


184

7.5 Remote Control Interface Namespace : http://schemas.intel.com/platform/client/RemoteControl/2004/01 Port : http://hostname:port/RemoteControlService


Local Access −

Network Access √

The Remote Control Interface allows managing the power and booting state of the Intel AMT-managed system.

Method Description

GetRemoteControlCapabilities Gets the remote control capabilities supported by the Intel AMT device

RemoteControl Remotely controls the boot and power state of the Intel AMT-managed PC

GetSystemPowerState Gets the Intel AMT system power state

7.5.1 Service APIs

7.5.1.1 GetRemoteControlCapabilities This operation is used to query the Intel AMT device’s remote control capabilities. These capabilities indicate which commands and options are supported in the RemoteControl method.

Header PT_STATUS GetRemoteControlCapabilities( [out] uint32 IanaOemNumber, [out] OemDefinedCapabilitiesType OemDefinedCapabilities, [out] SpecialCommandsSupportedType SpecialCommandsSupported, [out] SystemCapabilitiesSupportedType SystemCapabilitiesSupported, [out] SystemFirmwareCapabilitiesType SystemFirmwareCapabilities

);


Parameters The output parameter IanaOemNumber contains the IANA-assigned Enterprise Number assigned to ASF (for ASF standard commands and capabilities) or to Intel (for OEM-defined commands and capabilities), which is used in the RemoteControl method.


185

The output parameter OemDefinedCapabilities contains a set of flags that indicate the values the Intel AMT device supports in the OemDefinedCapabilities parameter of the RemoteControl method.

The output parameter SpecialCommandsSupported contains a set of flags that indicate the values the Intel AMT device supports in the SpecialCommandsSupported parameter of the RemoteControl method.

The output parameter SystemCapabilitiesSupported contains a set of flags that indicate the values the Intel AMT device supports in the Command parameter of the RemoteControl method.

The output parameter SystemFirmwareCapabilities contains a set of flags that indicate the values the Intel AMT device supports in the BootOptions parameter of the RemoteControl method.


Code Description



7.5.1.2 RemoteControl This operation is used to remotely control the boot and power state of the Intel AMT-managed PC.

Header PT_STATUS RemoteControl( [in] RemoteControlCommandType Command, [in] uint32 IanaOemNumber, [in, optional] SpecialCommandType SpecialCommand, [in, optional] SpecialCommandParameterType SpecialCommandParameter, [in, optional] BootOptionsType BootOptions, [in, optional] OemParametersType OEMparameters );


Parameters The input parameter IanaOemNumber specifies an IANA-assigned Enterprise Number. Valid values for this parameter are 343 (Intel IANA) and 4542 (ASF IANA).

The input parameter Command specifies the boot or power state operation to be performed. The enumeration RemoteControlCommandType specifies the valid values for this parameter. Reset command is allowed only in S0, S1 and S2 system states (see the PowerState field in the SystemPowerStateType structure for definition). Command value of SetBootOptions is valid only for IanaOemNumber value 343 and at least one of the optional parameters is specified. If Command value is PowerDown, then optional parameters must not be sent.


186

The input parameter SpecialCommand specifies an optional modification to the boot behavior. If not provided, then the SpecialCommand defaults to NOP. The enumeration SpecialCommandType specifies the valid values for this parameter. SpecialCommand value 0xC1 is valid only for IanaOemNumber value 343.

The input parameter SpecialCommandParameter is optionally used to augment the SpecialCommand. If not provided, then the SpecialCommand defaults to NOP. For SpecialCommand value 0xC1, SpecialCommandParameter specifies Intel AMT proprietary boot options to be set or invoked during the boot cycle caused by calling this function. Valid values for the parameter for SpecialCommand value 0xC1 are specified by the enumeration SpecialCommandParameterType. Otherwise, valid values for this parameter are specified in [ASF].

The input parameter BootOptions specifies standard boot options to be set or invoked during the boot cycle caused by calling this function. If not provided, then the SpecialCommand defaults to NOP. The enumeration BootOptionsType specifies the valid values for this parameter.

The input parameter OEMparameters specifies Intel AMT proprietary boot options to be set or invoked during the boot cycle caused by calling this function. If not provided, then the SpecialCommand defaults to NOP. OEMparameters is valid only for IanaOemNumber value 343. The enumeration OemParametersType specifies valid values for the parameter.


Code Description


PT_STATUS_INVALID_COMMAND Command contains an undefined code, or is invalid in the current system state.

PT_STATUS_INVALID_PARAMETER Invalid input parameters specified

PT_STATUS_INVALID_SPECIAL_COMMAND

SpecialCommand contains an undefined code, or SpecialCommandParameter contains an invalid value for the code in SpecialCommand.

PT_STATUS_UNSUPPORTED_OEM_NUMBER IanaOemNumber contains an unsupported Enterprise Number.

PT_STATUS_UNSUPPORTED_BOOT_OPTION BootOptions or OEMparameters specifies an unsupported boot option or combination of boot options.


PT_STATUS_NOT_PERMITTED Parameters are valid but are not supported by the platform.

7.5.1.3 GetSystemPowerState This operation is used to retrieve the power state of the Intel AMT-managed PC system.


187

Header PT_STATUS GetSystemPowerState( [out] SystemPowerStateType SystemPowerState

);


Parameters The output parameter SystemPowerState contains power state information about the Intel AMT-managed PC.


Code Description



7.5.2 Service Data Types The following sections describe the data structures for remote control interface supported by the Intel AMT device. These data types are defined under the namespace:

http://schemas.intel.com/platform/client/RemoteControl/2004/01

7.5.2.1 SystemCapabilitiesSupportedType SystemCapabilitiesSupportedType defines a set of bit flags that represent the remote control commands that the Intel AMT device supports. These flags indicate what commands are supported in the enumeration RemoteControlCommandType.

typedef struct _SystemCapabilitiesSupportedType { uint8 PowerCycleReset : 1; uint8 PowerDown : 1; uint8 PowerUp : 1; uint8 Reset : 1; uint8 Reserved : 4; } SystemCapabilitiesSupportedType

Field Description

PowerCycleReset Supports Power Cycle Reset, if 1b.

PowerDown Supports Power Down, if 1b.

PowerUp Supports Power Up, if 1b.

Reset Supports Reset, if 1b.

http://schemas.intel.com/platform/client/RemoteControl/2004/01


188

Reserved Reserved for future definition by this specification, set to 0000b.

7.5.2.2 RemoteControlCommandType RemoteControlCommandType enumerates the remote boot and power state commands supported by the Intel AMT device via the Remote Control Interface.

typedef enum<uint8> _RemoteControlCommandType { Reset = 0x10, PowerUp = 0x11, PowerDown = 0x12, PowerCycleReset = 0x13, SetBootOptions = 0x21, } RemoteControlCommandType;

Code Description

Reset The reset function causes a low latency reset of the system. This reset must, at a minimum, reset the host processor(s) and cause the PCI Reset# to be asserted so that all devices on the PCI bus are initialized.

PowerUp The power-up function brings a sleeping system into the S0/G0 “working” state or into the Legacy ON state.

PowerDown

The unconditional power-down function forces the system into an S5 entered by override or a Legacy OFF powered-off state. This power-down occurs without any blocking from software or the system. Because of this, ACPI and system state context is not guaranteed to be preserved.

PowerCycleReset The power cycle reset function causes a hard reset of the system. This reset is functionally equivalent to an Unconditional Power-Down operation, followed by a Power Up operation.

SetBootOptions

The set boot options function causes the system to use the given boot options after the next graceful shutdown or restart. This function does not change the power state of the system. This option can be used in conjunction with IDE-R session to favor a graceful boot during installation.

7.5.2.3 SpecialCommandsSupportedType SpecialCommandsSupportedType defines a set of bit flags that represent the special commands that the Intel AMT device supports. The corresponding commands are listed in the enumeration SpecialCommandType.

typedef struct _SpecialCommandsSupportedType { uint16 Reserved1 : 8; uint16 ForcePXEBoot : 1; uint16 ForceHardDriveBoot : 1; uint16 ForceHardDriveSafeModeBoot : 1; uint16 ForceDiagnosticBoot : 1; uint16 ForceCDorDVDBoot : 1;


189

uint16 Reserved2 : 3; } SpecialCommandsSupportedType;

Code Description

Reserved1 Reserved for future definition by this specification, set to 00h.

ForcePXEBoot Supports Force PXE Boot command, if set to 1b.

ForceHardDriveBoot Supports Force Hard-drive Boot command, if set to 1b.

ForceHardDriveSafeModeBoot Supports Force Hard-drive Safe-mode Boot command, if set to 1b.

ForceDiagnosticBoot Supports Force Diagnostic Boot command, if set to 1b.

ForceCDorDVDBoot Supports Force CD/DVD Boot command, if set to 1b.

Reserved2 Reserved for future definition by this specification, set to 000b.

7.5.2.4 SpecialCommandType SpecialCommandType enumerates the special commands that can be used to modify the normal boot behavior when RemoteControl is used to boot or reboot the PC.

typedef enum<uint8> _SpecialCommandType { NOP = 0x00, ForcePxeBoot = 0x01, ForceHardDriveBoot = 0x02, ForceHardDriveSafeModeBoot = 0x03, ForceDiagnosticsBoot= 0x04, ForceCdOrDvdBoot = 0x05, // 06h-0BFh Reserved for future ASF definition IntelOemCommand = 0x0C1 // 0C2h-0FFh Reserved FOR OEM } SpecialCommandType;

Code Description

NOP No additional special command is included; the Special Command Parameter has no meaning.

ForcePxeBoot

The Special Command Parameter is used to specify a PXE parameter. When the parameter value is 0, the system default PXE device is booted. All other values for the PXE parameter are reserved for future definition by this specification.


190

ForceHardDriveBoot

The Special Command Parameter identifies the boot-media index for the managed client. When the parameter value is 0, the default hard-drive is booted; when the parameter value is 1, the primary hard drive is booted; when the value is 2, the secondary hard drive is booted - and so on.

ForceHardDriveSafeModeBoot

The Special Command Parameter identifies the boot-media index for the managed client. When the parameter value is 0, the default hard drive is booted; when the parameter value is 1, the primary hard drive is booted; when the value is 2, the secondary hard drive is booted - and so on.

ForceDiagnosticsBoot

The Special Command Parameter can be used to specify a diagnostic parameter. When the parameter value is 0, the default diagnostic media is booted. All other values for the diagnostic parameter are reserved for future definition by this specification.

ForceCdOrDvdBoot

The Special Command Parameter identifies the boot-media index for the managed client. When the parameter value is 0, the default CD/DVD is booted; when the parameter value is 1, the primary CD/DVD is booted; when the value is 2, the secondary CD/DVD is booted; and so on.

IntelOemCommand

The Special Command Parameter identifies the special Intel boot options (IDER, SOL etc). The Intel AMT boot options are defined in Intel AMT Proprietary Special Command parameters.

7.5.2.5 SystemFirmwareCapabilitiesType SystemFirmwareCapabilitiesType defines a set of bit flags that represent the standard firmware boot options that the Intel AMT device supports. These flags indicate which flags are supported in BootOptionsType.

typedef struct _SystemFirmwareCapabilitiesType { uint32 VerbosityScreenBlank : 1; uint32 PowerButtonLock : 1; uint32 ResetButtonLock : 1; uint32 Reserved1 : 2; uint32 KeyboardLock : 1; uint32 SleepButtonLock : 1; uint32 Reserved2 : 1; uint32 Reserved3 : 3; uint32 UserPasswordBypass : 1; uint32 ForcedProgressEvents : 1; uint32 VerbosityVerbose : 1; uint32 VerbosityQuiet : 1; uint32 ConfigurationDataReset : 1; uint32 Reserved4 : 16; } SystemFirmwareCapabilitiesType;


191

Field Description

VerbosityScreenBlank Supports Firmware Verbosity/Screen Blank, if 1b.

PowerButtonLock Supports Power Button Lock, if 1b.

ResetButtonLock Supports Reset Button Lock, if 1b.


KeyboardLock Supports Lock Keyboard, if 1b.

SleepButtonLock Supports Sleep Button Lock, if 1b.



UserPasswordBypass Supports User Password Bypass, if 1b.

ForcedProgressEvents Supports Forced Progress Events, if 1b.

VerbosityVerbose Supports Firmware Verbosity/Verbose, if 1b.

VerbosityQuiet Supports Firmware Verbosity/Quiet, if 1b.

ConfigurationDataReset Supports Configuration Data Reset, if 1b.

Reserved4 Reserved for future definition by this specification, set to 0000h.

7.5.2.6 BootOptionsType BootOptionsType defines a set of bit flags that represent standard firmware boot options.

typedef struct _BootOptionsType { uint16 Reserved1 : 1; uint16 LockPowerButton : 1; uint16 LockResetButtons : 1; uint16 Reserved2 : 2; uint16 LockKeyboard : 1; uint16 LockSleepButton : 1; uint16 Reserved3 : 1; uint16 Reserved4 : 3; uint16 UserPasswordBypass : 1; uint16 ForceProgressEvents : 1; uint16 FirmwareVerbosity : 2; uint16 ConfigurationDataReset : 1; } BootOptionsType;

Field Description


LockPowerButton

When set to 1b, the managed client’s firmware disables the power button operation for the system, normally until the next boot cycle. Client instrumentation might provide the capability to re-enable the button functionality without rebooting.


192

Field Description

LockResetButtons

When set to 1b, the managed client’s firmware disables the reset button operation for the system, normally until the next boot cycle. Client instrumentation might provide the capability to re-enable the button functionality without rebooting.


LockKeyboard

When set to 1b, the managed client’s firmware disallows keyboard activity during its boot process. Client instrumentation or OS drivers might provide the capability to re-enable the keyboard functionality without rebooting.

LockSleepButton

When set to 1b, the managed client’s firmware disables the sleep button operation for the system, normally until the next boot cycle. Client instrumentation might provide the capability to re-enable the button functionality without rebooting.



UserPasswordBypass

When set to 1b, the managed client’s firmware boots the system and bypasses any user or boot password that might be set in the system. For example, this option allows a system administrator to force a system boot via PXE in an unattended manner.

ForceProgressEvents When set to 1b, the managed client’s firmware transmits all progress PET events to the alert-sending device. This option is usually used to aid in fail-to-boot problem determination.

FirmwareVerbosity

When set to a non-zero value, controls the amount of information the managed client writes to its local display:

00b System default

01b Quiet, minimal screen activity

10b Verbose, all messages appear on the screen

11b Screen blank, no messages appear on the screen.

ConfigurationDataReset When set to 1b, the managed client’s firmware resets its non-volatile configuration data to the client’s Setup defaults prior to booting the client.

7.5.2.7 OemDefinedCapabilitiesType OemDefinedCapabilitiesType defines a set of bit flags that represent the proprietary boot options that the Intel AMT device supports. There are two versions of the type, one for Intel AMT Release 1.0 and one for Intel AMT Release 2.0.

Intel AMT Release 1.0:

typedef struct _OemDefinedCapabilitiesType { uint32 IDER : 1; uint32 SOL : 1;


193

uint32 BiosReflash : 1; uint32 BiosSetup : 1; uint32 BiosPause : 1; uint32 NoFloppyBoot : 1; uint32 NoCDBoot ;1; uint32 Reserved1 : 1; uint32 TerminalEmulation : 8; uint32 Reserved2 : 16; } OemDefinedCapabilitiesType;

Field Description

BiosSetup BIOS boot into setup screen supported, if 1b.

BiosReflash BIOS reflash supported, if 1b.

BiosPause BIOS pause before booting operating system is supported, if 1b.

SOL Serial over LAN Supported, if 1b.

IDER IDE Redirection Supported, if 1b.

NoFloppyBoot BIOS does not support boot from Floppy device, if 1b

NoCDBoot BIOS does not support boot from CD device, if 1b

Reserved1 Reserved for future definition by this specification, must be set to 0b.

TerminalEmulation

Specifies which type of terminal should be used by the remote console when redirecting BIOS screens. Possible values:

0x01 – VT52 (Basic monochrome)

0x02 – VT100+ (Adds function keys F5 to F14)

0x03 – VT-UTF8

0x04 – PC-ANSI

Reserved2 Reserved for future definition by this specification, must be set to 0000h.

Intel AMT Release 2.0:

typedef struct _OemDefinedCapabilitiesType { uint32 IDER : 1; uint32 SOL : 1; uint32 BiosReflash : 1; uint32 BiosSetup : 1; uint32 BiosPause : 1; uint32 Reserved1 : 3; uint32 Reserved2 : 24; } OemDefinedCapabilitiesType;

Field Description

BiosSetup BIOS boot into setup screen supported, if 1b.

BiosReflash BIOS reflash supported, if 1b.


194

Field Description

BiosPause BIOS pause before booting operating system is supported, if 1b.

SOL Serial over LAN Supported, if 1b.

IDER IDE Redirection Supported, if 1b.



7.5.2.8 SpecialCommandParameterType SpecialCommandParameterType is a uint16 number. It is interpreted according to the special command. If SpecialCommand is 0xC1, it is interpreted as shown below. Otherwise, it is interpreted according to [ASF].

typedef struct _SpecialCommandParameterType { uint16 UseIder : 1; uint16 Reserved1 : 1; uint16 ReflashBios : 1; uint16 BiosSetup : 1; uint16 BiosPause : 1; uint16 Reserved2 : 3; uint16 IderBootDevice : 1; uint16 Reserved3 : 7; } SpecialCommandParameterType;


195

Field Description

UseIDER When set to 1b, use IDE redirection as boot device on next boot. IderBootDevice specifies boot device.

Reserved1 Obsolete field.

ReflashBIOS When set to 1b, BIOS boot block reflash the BIOS on the next boot, using IDE redirection as the source of BIOS image.

BiosSetup When set to 1b, BIOS boots into setup screen on next boot.

BiosPause When set to 1b, BIOS runs until the point that it would load the operating system and pauses on the next boot. The BIOS waits until it receives a message – for example, via the SMBus – that instructs it to continue.

Reserved2 Reserved for future definition by this specification; must be set to 000b.

IderBootDevice

Specifies the device to use when UseIder is set to 1b:

0b Floppy Boot

1b CD Boot

Reserved3 Reserved for future definition by this specification; must be set to 000 0000b.

7.5.2.9 OemParametersType OemParametersType is a uint16 number. It defines a set of bit flags that represent the Intel AMT proprietary boot options to be set or invoked during the boot cycle. This parameter is interpreted only when the SpecialCommand parameter has a value of 0x0C1.

typedef struct _OemParametersType { uint16 UseSol : 1; uint16 Reserved : 15; } OemParametersType;

Field Description

UseSol When set to 1b, use Serial over LAN keyboard/text redirection on next boot.

Reserved Reserved for OEM usage

7.5.2.10 SystemPowerStateType SystemPowerStateType contains power state information about the Intel AMT-managed PC. The fields are interpreted according to [ASF].

typedef struct SystemPowerStateType { uint32 PowerState : 4; uint32 Reserved1 : 4; uint32 WatchdogExpired : 1; uint32 PowerSource : 1;


196

uint32 Reserved2 : 6; uint32 Reserved3 : 16; } SystemPowerStateType;

Field Description

PowerState

0000b S0 / G0 “working”

0001b S1 “sleeping with system h/w & processor context maintained”

0010b S2 “sleeping, processor context lost”

0011b S3 “sleeping, processor & h/w context lost, memory retained.”

0100b S4 “non-volatile sleep / suspend-to disk”

0101b S5 / G2 “soft-off”

0110b S4 / S5 soft-off, particular S4/S5 state cannot be determined

0111b G3 / Mechanical Off

1000b Sleeping in an S1, S2, or S3 states (used when particular S1, S2, S3 state cannot be determined), or Legacy SLEEP state.

1001b G1 sleeping (S1-S4 state cannot be determined)

1010b S5 entered by override (e.g. 4-second power button override)

1011b Legacy ON state (e.g. non-ACPI OS working state)

1100b Legacy OFF state (e.g. non-ACPI OS off state)

1110b Unknown

1111b Reserved for future definition


WatchdogExpired

1b Indicates that the Watchdog Timer has expired and has not been stopped by a Stop Watchdog Timer command.

0b Indicates that the ASF alert-sending device’s Watchdog Timer is currently not expired because (a) it has not yet been started since power-on reset, (b) it has been started and is running but not expired yet, or (c) it has been stopped. This bit becomes set when the Watchdog Timer expires after a Start Watchdog Timer command is issued and the timer expires. Subsequent Start Watchdog Timer or Stop Watchdog Timer commands or an alert-sending device power-on reset will clear this status to 0b.

PowerSource 0 – AC power state.

1 – DC power state (valid for Intel AMT Release 2.6 or later)



197

7.6 Storage Interface Namespace : http://schemas.intel.com/platform/client/Storage/2004/01 Port : http://hostname:port/StorageService


Local Access √

Network Access √

The Storage Interface gives third-party applications the ability to allocate, use and manage blocks of Intel AMT non-volatile storage, which can be used to store information that is remotely accessible in all power states of the Intel AMT-managed system.

Method Description

ExecuteStorageOperation Execute a third-party storage operation in the Intel AMT device

7.6.1 Service APIs

7.6.1.1 ExecuteStorageOperation ExecuteStorageOperation results in the execution of a third-party storage operation in the Intel AMT device. Because all input and output parameters for third-party storage are binary in format, a single method suffices for all storage operations.

Header PT_STATUS ExecuteStorageOperation( [in] BinaryData Request, [out] BinaryData Response,

);


Parameters Request

Contains the binary third-party storage operation request message.

Response

Contains the binary third-party storage operation response that corresponds to the Request message.

The request and response byte streams contain ISVS request and response structures, as defined in [SDG].


198

Note: The returned status code is not related to the ISVS status code embedded in the ISVS response message itself (and which is returned in the Response byte stream). The method returns the status of the interface operation (i.e., whether the SOAP operation was successfully executed, and not necessarily whether the ISVS operation was successfully executed).If the method returns a PT_STATUS_SUCCESS code, then the status returned by the ISVS command denotes the status of the ISVS operation. If the method returns an error code, then the response byte stream will contain an empty string.


Code Description



7.6.2 Service Data Types All the data structures used for ISV Storage are defined in [SDG].


199

7.7 Event Manager Interface Namespace : http://schemas.intel.com/platform/client/Events/2004/01 Port : http://hostname:port/EventManagerService


Local Access −

Network Access √

The Event Manager interface includes operations that can be used by a remote application to subscribe for events, set event filters and manage the event log.

When a remote application loses network connectivity with an Intel AMT device, any events occurring during this time will also be lost unless they are set to be logged locally. This will be true even if the event is persistent. It is recommended that all critical events be configured to be logged. It is also recommended that when the remote application receives a “link up” Platform Event Trap (PET), it should read the log to identify any events that may have occurred while the link was down.

The EventLogReader realm gives a local or network user the ability to read the system log. (Release 2.6 or greater).

The User Notification service provides an event registration interface for local host applications.

By default, after provisioning, the user notification URI is accessible to local host applications without any need to authenticate. The interface access may be disabled or configured to require authentication (HTTP Digest) to increase the interface security. When configured to require authentication, authenticated users from the LocalUN Realm are able to access this interface.

When this interface is disabled, registered user events may still flow until the Intel AMT administrator removes the events.

Restrictions in Intel AMT Release 2.5/2.6 and Release 3.0: • Subscribing using AlertSubscriptionSoapType cannot be made from the "/EventManagerService"

URI and kept for future compatibility. Currently these subscriptions can be made from the "/UserNotificationService" URI.

The local event registration interface is very similar to remote event registration interface, with some restrictions: • Only a "user notification" event can be registered from the local interface.

Section 9.10 describes user notification events. The "user notification" event is marked by PolicyID number 0x86.

• Local applications can register to User notification events only when they are directed back to the local host name or address.

• Remote Event registration does not allow registering events to be directed to the local host name or address ("localhost", hostname, or 127.*.*.*).

• Intel AMT limits the rate of local user registrations to 1 subscription per 3 minutes. This restriction is maintained as a best effort and may be loosened across power state changes.


200

Method Description

SubscribeforAlert Adds an alert subscription to the Intel AMT device.

EnumerateAlertSubscriptions Enumerates alert subscriptions in the Intel AMT device.

GetAlertSubscription Gets value of one alert subscription from the Intel AMT device.

CancelAlertSubscription Removes an alert subscription from Intel AMT device.

EnumerateAlertPolicies Enumerates alert policies in the Intel AMT device.

SetAlertCommunityString Sets the community string in the Intel AMT device PET alerts.

GetAlertCommunityString Gets the community string used in the Intel AMT device PET alerts.

AddEventFilter Adds an event filter to the Intel AMT device.

EnumerateEventFilters Enumerates the event filters in the Intel AMT device.

GetEventFilter Gets the value of one event filter from the Intel AMT device.

UpdateEventFilter Updates value of one event filter in the Intel AMT device.

RemoveEventFilter Removes an event filter from the Intel AMT device.

GetEventLogStatus Gets the attributes of the event log status.

ReadEventLogRecords Reads all event log records stored in the Intel AMT device.

ClearEventLog Clear the event log in the Intel AMT device.

FreezeEventLog Freezes the event log in the Intel AMT device to prevent modification.

SetEventLogTimestampClock Sets the time used to timestamp the event log.

GetEventLogTimestampClock Gets the current time used to timestamp the event log.

EnumerateSensors Enumerates all sensors controlled by the Intel AMT Device.

GetSensorAttributes Gets sensor attributes from a sensor controlled by the Intel AMT device.

SubscribeForGeneralAlert Register to receive a selected alert type.

EnumerateGeneralAlertSubscriptions Enumerate subscriptions for events created by the user.

GetGeneralAlertSubscription Returns details of a selected general alert

7.7.1 Service APIs

7.7.1.1 SubscribeForAlert Applications can use this operation to add an alert subscription.


201

Header PT_STATUS SubscribeForAlert( [in] AlertSubscriptionType SubscriptionInfo, [out] AlertSubscriptionHandleType SubscriptionHandle,

);

Compatibility This routine is supported by Intel AMT Release 1.0 and Intel AMT Release 2.0/2.1. It is deprecated in releases 2.5 and later – callers should use the SubscribeForGeneralAlert() API.

Parameters The input parameter SubscriptionInfo specifies the subscription information.

If successful, then the output parameter SubscriptionHandle contains a handle that can be used to reference the subscription in subsequent operations.

Note: SubscriptionInfo contains the IP address. Therefore, if the subscriber’s IP address changes, then the subscriber will no longer receive PETs. When such a change occurs, the current subscription should be cancelled, and a new subscription should be established.


Field Description


PT_STATUS_MAX_LIMIT_REACHED Subscription list is full.


Parameter supplied by SubscriptionInfo is invalid (invalid IP address is an address in which all of the fields are 00h or FFh.)

PT_STATUS_DUPLICATE This subscription already exists. Identical subscriptions are identical in all fields of SubscriptionInfo.


PT_STATUS_FLASH_WRITE_LIMIT_EXCEEDED Flash wearout limit reached. Caller may try repeating this operation at a later time.

7.7.1.2 EnumerateAlertSubscriptions Application can use this operation to get PET alert subscriptions.

Header PT_STATUS EnumerateAlertSubscriptions( [in] uint32 StartIndex, [in, optional] AlertSubscriptionPolicyIDType AlertSubscriptionPolicyID,


202

[out] uint32 TotalSubscriptionCount, [out] uint32 SubscriptionsReturned,

[out] AlertSubscriptionHandleArrayType SubscriptionHandles );

Compatibility This routine is supported by Intel AMT Release 1.0 and Intel AMT Release 2.0/2.1. It is deprecated in releases 2.5 and later – callers should use the EnumerateGeneralAlertSubscriptions() API.

Parameters The input parameter StartIndex identifies the position (in the complete list of subscriptions) of the first subscription to retrieve. The first time the message is sent, the sending application should specify 1 for this field. If the response indicates that an incomplete list has been provided, then the application can send another message, this time specifying the position in the list after the last handle returned in the previous response.

If no alert subscriptions exist, then the function will always return PT_STATUS_SUCCESS with an empty list and TotalSubscriptionCount = SubscriptionsReturned = 0.

If AlertSubscriptionPolicyID is present, then it is used to limit the enumeration to subscriptions that have the specified subscription policy ID.

If successful, then the output parameter TotalSubscriptionCount gives the total number of alert subscriptions in the Intel AMT device or the total number of alert subscriptions which belong to AlertSubscriptionPolicyID, if specified.

The output parameter SubscriptionsReturned contains the total number of subscriptions returned in the Subscriptions array.


Field Description




7.7.1.3 GetAlertSubscription Applications can use this operation to get information about an alert subscription.

Header PT_STATUS GetAlertSubscription( [in] AlertSubscriptionHandleType SubscriptionHandle, [out] AlertSubscriptionType SubscriptionInfo

);


203

Compatibility This routine is supported by Intel AMT Release 1.0 and Intel AMT Release 2.0/2.1. It is deprecated in releases 2.5 and later – callers should use the GetGeneralAlertSubscription() API.

Parameters The input parameter SubscriptionHandle identifies the subscription for which information is required.

If successful, then the output parameter SubscriptionInfo gives the subscription information associated with SubscriptionHandle.


Field Description


PT_STATUS_INVALID_PARAMETER Invalid subscription identifier. Subscription may not exist.


7.7.1.4 CancelAlertSubscription Applications can use this operation to cancel a subscription to Alerts.

Header PT_STATUS CancelAlertSubscription( [in] AlertSubscriptionHandleType SubscriptionHandle

);


Parameters Input parameter SubscriptionHandle specifies the subscription to cancel. If successful, alert subscription is canceled.



204

Field Description


PT_STATUS_INVALID_PARAMETER Invalid subscription identifier. Subscription may not exist.


PT_STATUS_NOT_PERMITTED User in not allowed to cancel this event as this record is not owned by this user (Administrator is privileged for all records).

Remarks

For Intel AMT 2.5 - Users can cancel only the events they created themselves (Administrators may access all records). Canceling subscriptions made through SubscribeForAlert() should be allowed to all EventManager Realm users (no change in behavior due to backwards compatibility requirements).

7.7.1.5 EnumerateAlertPolicies Applications can use this operation to enumerate all the alert policies in the Intel AMT device.

Header PT_STATUS EnumerateAlertPolicies(

[in] uint32 StartIndex, [out] uint32 TotalPolicyCount, [out] uint32 PoliciesReturned, [out] AlertSubscriptionPolicyIDArrayType PolicyHandles );


Parameters The input parameter StartIndex identifies the position (in the complete list of policies) of the first policy to retrieve. The first time the message is sent, the sending application should specify 1 for this field. If the response indicates that an incomplete list has been provided, then the application can send another message, this time specifying the position in the list after the last handle returned in the previous response.

If no alert policies exist, then the function will always return PT_STATUS_SUCCESS with an empty list and TotalPolicyCount = PoliciesReturned = 0.

If successful, then the output parameter TotalPolicyCount gives the total number of alert policies in the Intel AMT device.


205

The output parameter PoliciesReturned contains the total number of policies returned in the PolicyHandles array.


Field Description




7.7.1.6 SetAlertCommunityString This function sets the community string used in PET alerts sent from the Intel AMT device. If this value is not set, then the Intel AMT device will use “public” as the community string.

Header PT_STATUS SetAlertCommunityString( [in] UINT8 Length, [in] ByteStr CommunityString

);


Parameters The input parameter Length contains the length in bytes of the community string. The string is not Null-terminated.

The input parameter CommunityString contains the community string to be used on PET alerts.


Field Description


PT_STATUS_INVALID_PARAMETER Invalid parameter used for CommunityString.




206

7.7.1.7 GetAlertCommunityString This function gets the community string used in PET alerts sent from the Intel AMT device.

Header PT_STATUS GetAlertCommunityString( [out] UINT8 Length, [out] ByteStr CommunityString

);


Parameters The output parameter Length contains the length in bytes of the community string. The string is not Null-terminated.

The output parameter CommunityString contains the community string used on PET alerts.


Field Description



7.7.1.8 AddEventFilter Applications can use this operation to add a new event filter. The EventFilter defines a set of criteria that allows matching of an incoming Platform Event with actions and event subscriptions. The EventFilter is applied to each incoming Platform Event, and the actions described by the filter are applied to selected events. In the case of an Alert Action, the alert is sent to each destination described by an Event Subscription associated with the EventFilter.

Note: If multiple alert subscriptions contain an identical destination address then a single PET message will be send to this destination.

Header PT_STATUS AddEventFilter( [in] EventFilterType EventFilter, [out] EventFilterHandleType EventFilterHandle

);



207

Parameters Input parameter EventFilter defines the filter to add.

If successful, then the output parameter EventFilterHandle contains a unique identifier for the new event filter.


Field Description


PT_STATUS_MAX_LIMIT_REACHED Internal filter list is full.


1.OEM Predefined Event Filter was specified. The FilterConfiguration field indicates that the current filter is an OEM Pre-Configured filter. However, adding such filters using this Interface is not supported.

2. The Severity field value does not represent a valid severity type as defined in the EventFilterType.

3. Cannot create a Not-Configurable Filter

PT_STATUS_DUPLICATE

The event filter specified already exists. Identical event filters are filters which contain the same values for the following fields: AlertSubscriptionPolicyID, DeviceAddress, EventSensorType , EventType, EventOffset, EventSourceType, EventSeverity, SensorNumber, Entity, EntityInstance.



7.7.1.9 EnumerateEventFilters Applications can use this operation to enumerate all the event filters. Enumeration can be done based on a subscription or on all the event filters.

Header PT_STATUS EnumerateEventFilters( [in] uint32 StartIndex, [in, optional] AlertSubscriptionPolicyIDType AlertSubscriptionPolicyID, [out] uint32 TotalEventFilterCount, [out] uint32 FiltersReturned,


208

[out] EventFilterHandleArrayType FilterArray );


Parameters The input parameter StartIndex identifies the position of the first filter to retrieve. The first time this message is sent, the sending application should specify 1 for this field. If the response indicates that an incomplete list has been provided, then the application can send another message, this time specifying the position in the list after the last handle returned in the previous response.

If the no event filters exist, then the function will always return PT_STATUS_SUCCESS with an empty list and TotalEventFilterCount = FiltersReturned = 0.

If AlertSubscriptionPolicyID is present, then it is used to limit the enumeration to subscriptions that have the specified subscription policy ID.

If successful, then the output parameter TotalEventFilterCount gives total number of event subscriptions (either for a specific subscription policy or for the complete list if AlertSubscriptionPolicyID is not specified).

The output parameter FiltersReturned contains number of subscriptions returned in the FilterArray.


Field Description




7.7.1.10 GetEventFilter Applications can use this operation to get attributes of an event filter.

Header PT_STATUS GetEventFilter( [in] EventFilterHandleType EventFilterHandle, [out] EventFilterType EventFilter

);


209


Parameters Input parameter EventFilterHandle specifies the event filter.

The output parameter EventFilter contains attributes of the requested event filter.


Field Description


PT_STATUS_INVALID_PARAMETER Invalid event filter handle


7.7.1.11 UpdateEventFilter Applications can use this operation to update attributes of an event filter.

Header PT_STATUS UpdateEventFilter( [in] EventFilterHandleType EventFilterHandle, [in] EventFilterType *EventFilter

);


Parameters Input parameter EventFilterHandle specifies the event filter to update.

The parameter EventFilter contains attributes of the requested event filter.


Field Description



210


1. OEM Predefined Event Filter was specified. The FilterConfiguration field indicates that the current filter is an OEM pre-configured filter. However, updating such filters using this Interface is not supported.

2. The Severity field value does not represent a valid severity type as defined in the EventFilterType.

3. Configurable Filter can not be changed to Not-Configurable Filter

PT_STATUS_DUPLICATE

The event filter specified already exists. Identical event filters are filters which contain the same values for all the following fields: AlertSubscriptionPolicyID, DeviceAddress, EventSensorType, EventType, EventOffset, EventSourceType, EventSeverity, SensorNumber, Entity, EntityInstance.



7.7.1.12 RemoveEventFilter Applications can use this operation to remove an event filter, and the filter is removed even if it is associated to event subscriptions.

Header PT_STATUS RemoveEventFilter( [in] EventFilterHandleType EventFilterHandle

);


Parameters The input parameter EventFilterHandle identifies the filter to be removed.

If successful, then the specified filter is removed.


Field Description



211

PT_STATUS_INVALID_PARAMETER Invalid event filter handle. This error includes the case of manufacturer pre-configured filters.


7.7.1.13 GetEventLogStatus This operation gets the attributes of the event log status.

Header PT_STATUS GetEventLogStatus( [out] uint32 NumberOfFreeRecords, [out] uint32 NumberOfRecords, [out] EventLogTimeStampType Time, [out] Boolean IsFrozen;

);


Parameters NumberOfFreeRecords indicates how many records need to be logged before the event log is full (which will cause deletion of the first entries).

NumberOfRecords indicates how many records presently are in the log.

Time indicates the timestamp of the most recent entry. If the log is empty, the timestamp will be equal to 0.

IsFrozen is set to TRUE if the log is currently frozen. Otherwise it is set to FALSE.


Field Description



7.7.1.14 ReadEventLogRecords Applications can use this operation to enumerate all the event log records.

Header PT_STATUS ReadEventLogRecords( [in] uint32 StartIndex, [out] uint32 TotalRecordCount,


212

[out] uint32 RecordsReturned, [out] EventLogRecordArrayType EventRecords

);


Parameters The input parameter StartIndex identifies the position of the first record to retrieve. The first time the message is sent, the sending application should specify 1 for this field. If the response indicates that an incomplete list has been provided, then the application can send another message, this time specifying the position in the list after the last handle returned in the previous response. Records are returned in historical order. The first event record in the returned array is the newest record stored in Intel AMT.

If no event log records exist, then the function will always return PT_STATUS_SUCCESS with an empty list and TotalRecordCount = RecordsReturned = 0.

If successful, then the output parameter TotalRecordCount gives the total number of event records in the event log.

The output parameter RecordsReturned contains the number of event records returned in the EventRecords array.


Field Description




Remarks Users that have EventLogReader realm permissions will also be able to execute this API and get a response.

7.7.1.15 ClearEventLog Applications can use this operation to remove all records from the event log.

Header PT_STATUS ClearEventLog(

);


213



Field Description


PT_STATUS_EVENTLOG_FROZEN The event log is frozen and cannot be cleared.



7.7.1.16 FreezeEventLog Applications can use this operation to freeze and unfreeze the event log in order to prevent records from being added or cleared while reading the log.

Header PT_STATUS FreezeEventLog( [in] boolean NewState

);


Parameters NewState is the new state that the event log should enter. If NewState is TRUE, then the log will be frozen. If it is FALSE, then the log will be unfrozen.

If successful, then the event log enters the new state.

Events occurring while the event log is frozen will not be logged.

Note: In case of power loss (e.g. electrical cord disconnection), the event log will become unfrozen.


Field Description




214


7.7.1.17 SetEventLogTimestampClock Sets the event log timestamp clock.

Header PT_STATUS SetEventLogTimestampClock( [in] EventLogTimeStampType Time

);

Compatibility This function is compatible with Intel AMT Release 1.0. It is deprecated in Intel AMT Release 2.0 in favor of SetHighAccuracyTimeSynch().

Parameters Time is an unsigned 32-bit value representing the local time as the number of seconds from 00:00:00, January 1, 1970 UTC. The format is sufficient to maintain timestamps with one-second resolution past the year 2100 and is based on a longstanding UNIX*-based standard for timekeeping, which represents time as the number of seconds from 00:00:00, January 1, 1970 UTC. Similar time formats are used in ANSI C. Intel AMT Release 2.0 constrains this value to a range between January 1 2004 and 4 Janauary 2021 18:48:31.


Code Description



Time contains an invalid or out-of-range value. For some product versions, setting a Time value which is earlier than the product release date is not allowed and is considered an invalid setting.


PT_STATUS_NOT_PERMITTED Caller is not permitted to use this command under the current configuration settings.



215

Remarks

When Kerberos Authentication is enabled, this interface will be disabled. (Calls to this command will return PT_STATUS_ NOT_PERMITTED.)

7.7.1.18 GetEventLogTimestampClock GetEventLogTimestampClock returns the current value in the event log timestamp clock.

Header PT_STATUS GetEventLogTimestampClock( [out] EventLogTimeStampType Time

);


Parameters Time is the local time of the Intel AMT device.


Code Description


PT_STATUS_INVALID_TIME Timestamp has not been initialized.


7.7.1.19 EnumerateSensors EnumerateSensors returns a list of sensor handles, each of which subsequently can be used to retrieve sensor data (GetSensorAttributes). Each returned handle corresponds to a logical sensor. The logical model allows sensors to be classified according to type regardless of the physical devices that implement them. Thus, a single physical sensor device can implement logical sensors of different types, such as temperature and voltage sensors.

Header PT_STATUS EnumerateSensors( [in] uint32 StartIndex, [out] uint32 TotalCount, [out] uint32 HandlesCount, [out] SensorHandleArrayType Handles

);


216


Parameters StartIndex indicates the first sensor handle to retrieve. To enumerate the entire list, an application sends this message with StartIndex set to 1. If TotalCount is greater than HandlesCount (which indicates that an incomplete list has been returned), then the application can send additional messages to retrieve the remainder of the list, each time setting StartIndex to point to the handle that follows the last one returned in the previous message.

If no sensors exist, then the function will always return PT_STATUS_SUCCESS with an empty list and TotalCount = HandlesCount = 0.

If the request succeeds, then TotalCount contains the total number of sensors and Handles contains the list of HandlesCount sensor handles.


Code Description




7.7.1.20 GetSensorAttributes GetSensorAttributes returns the attributes associated with a single logical sensor. The logical model classifies sensors according to type regardless of the physical devices that implement them. Thus, a single physical sensor device can implement logical sensors of different types, such as temperature and voltage sensors.

Header PT_STATUS GetSensorAttributes( [in] SensorHandleType Handle, [out] SensorAttributesType Attributes

);


Parameters Handle contains a handle returned by EnumerateSensors.

Attributes contains the attributes of the logical sensor.


217

The Attributes output parameter contains data that is sent in a PET alert. The Attributes parameter, therefore, is optional, but must be returned whenever the data are provided in the corresponding SMBus (System Management Bus) response message.


Code Description


PT_STATUS_INVALID_PARAMETER An invalid handle was sent.


7.7.1.21 SubscribeForGeneralAlert

This command allows creation of an alert that can be reported either in SNMP PET format targeted to an IP address or as a SOAP message targeted to a URL.

Header PT_STATUS SubscribeForGeneralAlert(

[in] AlertSubscriptionGeneralType SubscriptionInfo, [out] AlertSubscriptionHandleType SubscriptionHandle );


Parameters

SubscriptionInfo

Subscription information

SubscriptionHandle

Subscription handle


Code Description



218


PT_STATUS_FLASH_WRITE_LIMIT_EXCEEDED Wear out protection failure, or registration rate exceeded.

PT_STATUS_MAX_LIMIT_REACHED Subscription list is full or max quota limit per user reached.

PT_STATUS_INVALID_PARAMETER Parameter supplied by SubscriptionInfo is invalid (may also be an invalid node destination address.)

PT_STATUS_DUPLICATE Returned when the user attempted to register more than once with the same fields of SubscriptionInfo.

PT_STATUS_UNSUPPORTED Subscription Type not supported

PT_STATUS_NOT_PERMITTED Returned if local user registrations rate is limited (see section 7.7 for details).

Remarks For backwards compatibility, the new supported API handles are not enumerable by EnumerateAlertSubscriptions() which should be deprecated.

Every user who is a member of the LocalUN Realm (and not the EventManager Realm) is limited to registering a maximum of two events.

LocalUN Realm is limited to local event registration (it cannot register network nodes)

Local User notification supports only AlertSubscriptionSoapType registrations. Other registration formats may fail.

7.7.1.22 EnumerateGeneralAlertSubscriptions

This command enumerates alert subscriptions that were created using SubscribeForGeneralAlert(), as well as subscriptions created with SubscribeForAlert().

Header PT_STATUS EnumerateGeneralAlertSubscriptions (

[in, optional] AlertSubscriptionPolicyIDType PolicyID, [out] AlertSubscriptionHandleType SubscriptionHandles[] );


Parameters


219

PolicyID

Policy ID.

SubscriptionHandles

A list of subscription handles.


Code Description



Remarks This enumeration deprecates the API EnumerateAlertSubscriptions()

Legacy API subscriptions should be able to be enumerated by this API by all users. Note: enumerations performed by the legacy API EnumerateAlertSubscriptions() will not be able to observe any of the subscribers using the new subscription API SubscribeForGeneralAlert().

Users can enumerate only the events they created themselves. Administrators can enumerate all user events.

7.7.1.23 GetGeneralAlertSubscription

This command returns the details of an alert subscription, given the handle of the subscription.

Header PT_STATUS GetGeneralAlertSubscription(

[in] AlertSubscriptionHandleType SubscriptionHandle, [out] AlertSubscriptionGeneralType SubscriptionInfo );


Parameters

SubscriptionHandle

Subscription handle


220

SubscriptionInfo

Subscription information


Code Description



PT_STATUS_NOT_PERMITTED User in not allowed to read this event as this record is not owned by this user (Administrator may is privileged for all records).

PT_STATUS_INVALID_PARAMETER Subscription Handle is invalid.

Remarks Caller should expect to fail getting an entry (parse error) if the AlertSubscriptionGeneralType is extended in future versions to support more subscription types (old types should be preserved).

Users can retrieve information only about the events they created themselves (Administrators may access all records). Note: A Get performed using the legacy API GetAlertSubscription() will not be able to see any of the subscribers using the new subscription API (SubscribeForGeneralAlert())

7.7.2 Intel AMT Client Initiated APIs

7.7.2.1 SoapAlert

Header PT_STATUS SoapAlert(

[in] EventLogRecordType SoapAlertRecords[] );


Realm:

No Realm when acting as a client


221

Parameters

SoapAlertRecord

A list of events for an event subscriber.


Code Description



Remarks

This API should be implemented on the MMC or event Sink application.

Please note that this API allows batching events together as in WS-Management.

7.7.3 Service Data Types The sections below describe the data structures used by operations in the Event Manager Service. The data types are defined under the namespace: http://schemas.intel.com/platform/client/EventManager/2004/01

7.7.3.1 EventLogRecordType The EventLogRecordType structure defines attributes that describe a Platform Event that has occurred in the Intel AMT PC.

typedef struct _EventLogRecordType { EventLogTimeStampType TimeStamp; uint8 DeviceAddress; uint8 EventSensorType; uint8 EventType; uint8 EventOffset; uint8 EventSourceType; EventSeverityType EventSeverity; uint8 SensorNumber; uint8 Entity; uint8 EntityInstance; uint8 EventData[8]; } EventLogRecordType;

http://schemas.intel.com/platform/client/EventManager/2004/01


222

Field Description

TimeStamp Describes the time of the event as a 4-byte field; logged LSB first. If TimeStamp value is 0, it specifies that the Intel AMT device’s timestamp has not been initialized.

DeviceAddress The SMBus address of the physical sensor device that implements the logical sensor.

EventSensorType The value to be set into the alert’s Event Sensor Type field (see [PET] for definitions.)

EventType The value to be set into the alert’s Event Type field (see [PET] for definitions.)

EventOffset The value to be set into the alert’s Event Offset field (see [PET] for definitions.)

EventSourceType The value to be set into the alert’s Event Source Type field (see [PET] for definitions.)

EventSeverity

This field can be used to fill in the Event Severity field in a PET alert. The severity values are based on the ‘DMI’ severity values used for the generic sensor event/reading type code.

00h = unspecified

01h = Monitor 00 0001

02h = Information 00 0010

04h = OK (return to OK condition) 00 0100

08h = Non-critical condition 00 1000 a.k.a. ‘warning’

10h = Critical condition 01 0000

20h = Non-recoverable condition 10 0000

SensorNumber The value to be set into the alert’s Sensor Number field (see [PET] for definitions.)

Entity The value to be set into the alert’s Entity field (see [PET] for definitions.)

EntityInstance The value to be set into the alert’s Entity Instance field (see [PET] for definitions.)

EventData Describes optional event data sent in the PET packet. The values are defined in the ASF specification [ASF].

7.7.3.2 EventLogRecordArrayType Typedef struct _EventLogRecordArrayType {

EventLogRecordType EventLogRecord[]; } EventLogRecordArrayType;


223

Field Description

EventLogRecordArrayType An array of event log records. An instance of this type is returned by ReadEventLogRecords.

7.7.3.3 TimeType typedef uint32 TimeType;

Field Description

TimeType

An unsigned 32-bit value representing the local time as the number of seconds from 00:00:00, January 1, 1970 UTC. This format is sufficient to maintain time stamps with one-second resolution past the year 2100. This is based on a longstanding UNIX-based standard for timekeeping, which represents time as the number of seconds from 00:00:00, January 1, 1970 UTC. Similar time formats are used in ANSI C. Intel AMT Release 2.0 constrains this value to a range between January 1 2004 and 4 Janauary 2021 18:48:31.

In Enterprise mode the Intel AMT time must be set to UTC time using the SOAP interface.

In Small Business mode and in Legacy mode, the time maintained by Intel AMT internally is synchronized to the BIOS time. Each time the platform reboots, Intel AMT synchronizes to the BIOS time. In this case, the time may be local time or may be UTC, depending on the actions of the operator who set it. When a function responds with a time value or a message has a timestamp, it will be based on this internal value without an explicit compensation for time zone.

7.7.3.4 EventLogTimeStampType typedef TimeType EventLogTimeStampType;

Field Description

EventLogTimeStampType Represents the time at which an event occurred. TimeType describes the format of timestamps.

7.7.3.5 EventFilterType The EventFilter class attributes define a set of criteria that allows matching of an incoming Platform Event with actions and event subscriptions. The EventFilter is applied to each incoming Platform Event and the actions described by the filter are applied to selected events. In the case of an Alert Action, the alert is sent to each destination described by an EventSubscription associated with the EventFilter.

typedef struct _EventFilterType { uint8 FilterConfiguration; uint8 FilterAction;


224

AlertSubscriptionPolicyIDType AlertSubscriptionPolicyID; uint8 DeviceAddress; uint8 EventSensorType; uint8 EventType; uint8 EventOffset; uint8 EventSourceType; EventSeverityType EventSeverity; uint8 SensorNumber; uint8 Entity; uint8 EntityInstance; } EventFilterType;

Field Description

FilterConfiguration

[7] - 1b = enable filter

0b = disable filter

[6:5] - 11b = reserved

10b = manufacturer pre-configured filter. The filter entry has been configured by the system integrator and cannot be altered by software (updated, enabled, disabled or removed).

01b = reserved

00b = software configurable filter. The filter entry is available for configuration by system management software.

[4:0] - reserved (must be zero; if non-zero, functionality is undefined).

FilterAction

[7] - 1b = Log Event

0b = Do not Log Event

[6: 1 ] - reserved (must be zero; if non-zero, functionality is undefined).

[0] - 1b = Alert

0b = no Alert

AlertSubscriptionPolicyID Used to select subscriptions to send alerts to.


FFh – match all.


FFh – match all.


FFh – match all.


225

Field Description


0Fh – match all.


FFh – match all.

EventSeverity

This field can be used to fill in the Event Severity field in a PET alert. The severity values are based on the ‘DMI’ severity values used for the generic sensor event/reading type code. In the case that more than one event filter match occurs for a given Alert Policy Number, the numerically highest severity value between matching filters will be used. If the raw event data contains severity value, then it will only be considered if the severity field in all matching filters is set to 'unspecified.' (Note: this field is not used for filtering incoming events).

00h = unspecified

01h = Monitor 00 0001

02h = Information 00 0010

04h = OK (return to OK condition) 00 0100

08h = Non-critical condition 00 1000 a.k.a. ‘warning’

10h = Critical condition 01 0000

20h = Non-recoverable condition 10 0000


FFh – match all

Entity The value to be set into the alert’s Entity field (see [PET] for definitions.)

00h – match all

EntityInstance The value to be set into the alert’s Entity Instance field (see [PET] for definitions.)

00h – match all

7.7.3.6 EventSeverityType typedef enum<uint8> _EventSeverityType { Unspecified = 0, Monitor = 1, Information = 2, OK = 4, NonCriticalCondition = 8, CriticalCondition = 16,


226

NonRecoverableCondition = 32 } EventSeverityType;

Field Description

Unspecified Event severity is unknown or undefined.

Monitor An informational event

Information An informational event

OK Indicates that system has returned to OK condition.

NonCriticalCondition Indicates a warning.

CriticalCondition Indicates a critical but possibly recoverable condition.

NonRecoverableCondition Indicates a critical, non-recoverable condition.

7.7.3.7 EventFilterHandleType typedef uint32 EventFilterHandleType;

Field Description

EventFilterHandleType

A handle to an event filter. Such a handle can be used in calls to GetEventFilter, UpdateEventFilter and RemoveEventFilter. Event filter handles are returned by AddEventFilter and EnumerateEventFilters.

7.7.3.8 EventFilterHandleArrayType typedef struct _EventFilterHandleArrayType {

EventFilterHandleType EventFilterHandle[]; } EventFilterHandleArrayType;

Field Description

EventFilterHandleArrayType

An array of event filter subscription handles, each of which can be used in calls to GetEventFilter, UpdateEventFilter and RemoveEventFilter. An instance of this type is returned by EnumerateEventFilters.

7.7.3.9 AlertSubscriptionType The AlertSubscription Class defines a destination for the Alert Action (send PET Frame) of associated Event Filters.

typedef struct _AlertSubscriptionType { AlertSubscriptionPolicyIDType AlertSubscriptionPolicyID;


227

IPv4AddressType Address; } AlertSubscriptionType;

Field Description

AlertSubscriptionPolicyID

A numeric identifier that is used to associate alert subscriptions and event filters. Alert subscriptions and event filters that have the same value in the AlertSubscriptionPolicyID field are associated.

Address IP Address of the subscribed PET Collector. Addresses are maintained per [IP] definition i.e. value: 0x01020304

IP Address: 1.2.3.4

7.7.3.10 AlertSubscriptionPolicyIDType typedef uint8 AlertSubscriptionPolicyIDType;

Field Description

AlertSubscriptionPolicyIDType

Type that defines a numeric identifier that is used to associate alert subscriptions and event filters. Alert subscriptions and event filters that have the same value in the AlertSubscriptionPolicyID field are associated.

7.7.3.11 AlertSubscriptionPolicyIDArrayType typedef struct _AlertSubscriptionPolicyIDArrayType { AlertSubscriptionPolicyIDType AlertSubscriptionPolicyID[]; } AlertSubscriptionPolicyIDArrayType;

Field Description

AlertSubscriptionPolicyIDType An array of alert subscription numbers, used in EnumerateAlertPolicies.

7.7.3.12 AlertSubscriptionHandleType typedef uint32 AlertSubscriptionHandleType;

Field Description

AlertSubscriptionHandleType

A handle to an alert subscription that can be used in calls to GetAlertSubscription and CancelAlertSubscription. Alert subscription handles are returned by SubscribeForAlert and EnumerateAlertSubscriptions.


228

7.7.3.13 AlertSubscriptionHandleArrayType typedef struct _AlertSubscriptionHandleArrayType {

AlertSubscriptionHandleType AlertSubscriptionHandle[]; } AlertSubscriptionHandleArrayType;

Field Description

AlertSubscriptionHandleArrayType

An array of alert subscription handles, each of which can be used in calls to GetAlertSubscription and CancelAlertSubscription. An instance of this type is returned by EnumerateAlertSubscriptions.

7.7.3.14 SensorHandleType typedef uint32 SensorHandleType;

Field Description

SensorHandleType A handle to a logical sensor. Sensor handles are returned by EnumerateSensors can be used in calls to GetSensorAttributes.

7.7.3.15 SensorHandleArrayType typedef struct _SensorHandleArrayType { SensorHandleType *Handles; } SensorHandleArrayType;

Field Description

Handles An array of sensor handles, each of which can be used in calls to GetSensorAttributes. An instance of this type is returned by EnumerateSensors.

7.7.3.16 SensorAttributesType typedef _SensorAttributesType { boolean IsLegacySensor; boolean AssertionEvent; boolean DeassertionEvent; uint8 Index; uint8 DeviceAddress uint8 EventSensorType;


229

uint8 EventType; uint8 EventOffset; uint8 EventSourceType; uint8 EventSeverity; uint8 SensorNumber; uint8 Entity; uint8 EntityInstance; } SensorAttributesType;

Field Description

IsLegacySensor

The value in this field is TRUE if this is a legacy sensor described in the ACPI ‘ASF!’ table or FALSE if this is an ASF sensor. The value in this field is used in determining how to poll the status of the device on the SMBus.

AssertionEvent TRUE if the assertion event is sent internally to the event handler. The event handler manages policies regarding whether the resulting event is sent in a PET frame and/or logged in the NV event log.

DeassertionEvent TRUE if the de-assertion event is sent internally to the event handler. The event handler manages policies regarding whether the resulting event is sent in a PET frame and/or logged in the NV event log.

Index

If this is a legacy sensor, then this field contains the 0-based index of the ASF_ALERTDATA structure in the Device Array of the ASF_ALRT structure in the ACPI ‘ASF!’ structure.

If this is an ASF sensor, then this field contains the value of the Event Status Index required for a Get Event Status cycle on the SMBus.

The value in this field is used in determining how to poll the status of the device on the SMBus.






EventSeverity The value to be set into the alert’s Event Severity field (see [PET] for definitions.)


7.7.3.17 ByteStr typedef struct _ByteStr


230

{ byte Byte[]; } ByteStr;

Field Description

Byte String represented as a byte array. The maximum size of the string is 16 single bytes. Only printable characters are allowed.

7.7.3.18 AlertSubscriptionGeneralType

typedef struct {

AlertSubscriptionPolicyIDType PolicyID; choice { AlertSubscriptionSNMPType AlertSubscriptionSNMP; AlertSubscriptionSoapType AlertSubscriptionSoap; };

} AlertSubscriptionGeneralType ;

7.7.3.19 AlertSubscriptionSNMPType

typedef struct {

NodeAddressType Address; [optional] string CommunityString;

} AlertSubscriptionSNMPType ;

Note: • Subscribers that use a IPv4 address should get an IPv4 SNMP trap • Subscribers that use a IPv6 address should get an IPv6 SNMP trap • Subscribers that use host name should get an IPv6 or IPv4 trap depending on the IP stack

configurations. • Currently there are no plans to support IPv6. • CommunityString is limited to 16 printable characters.

If this value is Null, the global setting of community String will be used.

7.7.3.20 AlertSubscriptionSoapType

typedef struct {

URL Address ; [optional] 7CertificateHandleType ClientCredentials ; [optional] AlertCredentialsType UserCredentials ; AlertAuthOptionsType AlertAuthOptions[] ;

} AlertSubscriptionSoapType ;


231

Field Description

Address

ClientCredentials User credentials.

UserCredentials

AlertAuthOptions A list of authentications allowed for this event. The priority of authentications is given by the order of the list.

Remarks

Currently, there is no support for notifications over TLS.

7.7.3.21 AlertAuthOptionsType

typedef enum<string> { Kerberos, Digest, Basic } AlertAuthOptionsType;

Field Description

Kerberos Currently unsupported

Digest

Basic Currently unsupported

7.7.3.22 AlertCredentialsType

typedef struct { string Username ; string Password ; } AlertCredentialsType;

Field Description

Username Username


232

Password Password (this field may be set, however on query this field may contain '*' chars to signify an unusable password)


233

7.8 Agent Presence

7.8.1 Service APIs - Remote Interface Namespace : http://schemas.intel.com/2004/12/management/PC/AgentWatcgdogRemote Port : http://hostname:port/AgentWatchdogRemoteService


Local Access −

Network Access √

The Agent Presence Interface gives third-party applications the ability to register to application Watchdog services of Intel AMT. These services allow tracking heartbeat events from registered applications while applying Circuit Breaker and Event Manager Policies when application state changes.

The interface may also be used by a Remote side console to create entries for applications and the associated events for tracking agent state remotely. Due to various security and design considerations, remote side agent creation should occur before local software registration.

Method Description

ConsoleWatchdogCreate Creates an entry for an application to be monitored.

ConsoleWatchdogDelete Removes a previously created entry.

ConsoleWatchdogEnumerate Enumerates created applications.

ConsoleWatchdogSetActions Sets the monitoring state table for a given application.

ConsoleWatchdogGetActions Gets the monitoring state table for a given application.

ConsoleWatchdogSetCbPolicy Sets a global Circuit Breaker policy (may be activated upon watchdog state transition).

ConsoleWatchdogGetCbPolicy Gets a global Circuit Breaker policy (may be activated upon watchdog state transition).

ConsoleWatchdogQueryCapabilities Query the capabilities of the AgentPresence feature.

7.8.1.1 ConsoleWatchdogCreate

Creates an entry for an application to be monitored.

Header PT_STATUS ConsoleWatchdogCreate( [in] GUID AgentID, [in, optional] string AgentDescription,


234

[in] uint16 AgentHeartbeatTime, [in] uint16 AgentStartupTime

);


Parameters

AgentID

A globally unique application identifier. (A given application should be registered using the same value on different machines.)

AgentDescription

An optional Null-terminated text that describes the application. Contains 7-bit ASCII characters, in the range of 33 to 126 excluding ‘:’, ‘,’, '>', '<', '&', and ‘”’ characters. String length is limited to 16 characters.

AgentHeartbeatTime

A seconds timer value which specifies the maximum time allowed between application heartbeat calls. Must be non-zero.

AgentStartupTime

A seconds timer value which specifies the maximum time for an application to load when the system starts (or after creation) and then start sending heartbeat calls. Must be non-zero.


Code Description



PT_STATUS_DUPLICATE An application entry, with the same AgentID, already exists.


PT_STATUS_MAX_LIMIT_REACHED No space is left on flash for this operation.


Invalid parameter (invalid input string, or a field that should contain nonzero value but is set to zero: AgentHeartbeatTime or AgentStartupTime)

PT_STATUS_INVALID_NAME An invalid character was used in AgentDescription.


235

Remarks

This call typically is issued by a remote console that wishes to track the state of an application on the target system. The state of the application is reported by the local system using the local agent presence interface.

7.8.1.2 ConsoleWatchdogDelete

Removes an application watchdog entry and all its associated actions.

Header PT_STATUS ConsoleWatchdogDelete( [in] GUID AgentID,

);


Parameters

AgentID is globally unique application identifier (as specified in ConsoleWatchdogCreate)


Code Description




PT_STATUS_INVALID_HANDLE Specified AgentID does not exist

Remarks

This call typically is issued by a remote console to remove an application watchdog entry. Calling this function erases all the associated watchdog actions

7.8.1.3 ConsoleWatchdogEnumerate

Enumerates application watchdog entries.


236

Header PT_STATUS ConsoleWatchdogEnumerate( [out] ConsoleWatchdogEntryType ConsoleWatchdogEntries[]

);


Parameters

The ConsoleWatchdogEntries parameter returns an array of ConsoleWatchdogEntryType elements. Return Values One of the following status codes MUST be returned by this method:

Code Description



Remarks

This call typically is issued by a remote console to enumerate all the application watchdog entry. Calling this function returns entries which may have been created by other remote consoles.

7.8.1.4 ConsoleWatchdogSetActions

Sets actions for a given application watchdog entry.

Header PT_STATUS ConsoleWatchdogSetActions( [in] GUID AgentID, [in] ConsoleWatchdogActionType ConsoleWatchdogActions[]

);


Parameters

AgentID is a globally unique application identifier (as specified in ConsoleWatchdogCreate).

The ConsoleWatchdogActions parameter specifies an action state transition table, which is provided by the caller. Return Values One of the following status codes MUST be returned by this method:


237

Code Description




PT_STATUS_INVALID_HANDLE Specified handle does not exist

PT_STATUS_MAX_LIMIT_REACHED Not enough space for the specified watchdog actions

PT_STATUS_INVALID_PARAMETER Specified parameter is malformed

Remarks

This call is issued by a remote console that wishes to associate actions with a given application entry.

The number of actions that can be assigned to a particular agent is a function of three parameters:

The maximum number of agent entries.

The guaranteed minimum number of actions per entry.

The maximum total number of actions.

Therefore, the number of actions available beyond the minimum that can be allocated to the agents is:

Max. number of actions – (the max. number of agents * guaranteed minimum)

For example, say the maximum number of actions is 64, the maximum number of agents is 16 and the minimum number of actions per agent is 3 (see Section 10.1 for the actual values). The number of actions available for allocation is 64 –16 * 3 = 16 actions in the pool. When an agent is allocated more than 3 actions, the excess over 3 is removed from the pool of available actions.

MaxActionListForAgentX = MAX(ActionListOfAgentX, 3) + CurrentNumActionsInPool

ConsoleWatchdogGetActions returns the actions currently assigned to an agent. ConsoleWatchdogQueryCapabilities returns the values of the three parameters.

7.8.1.5 ConsoleWatchdogGetActions

Gets actions from a given application watchdog entry.

Header PT_STATUS ConsoleWatchdogGetActions( [in] GUID AgentID, [out] ConsoleWatchdogActionType ConsoleWatchdogActions[]

);


238


Parameters

AgentID is a globally unique application identifier (as specified in ConsoleWatchdogCreate).

The ConsoleWatchdogActions parameter returns the previously set action state transition table. Return Values One of the following status codes MUST be returned by this method:

Code Description




Remarks

This call typically is issued by a remote console to get the actions that are associated with a given application entry.

Note that associated CircuitBreaker actions may be deleted through the CircuitBreaker API.

7.8.1.6 ConsoleWatchdogSetCbPolicy

Sets a global Circuit Breaker policy which may be activated by the Agent Presence module.

Header PT_STATUS ConsoleWatchdogSetCbPolicy( [in] CircuitBreakerHardwarePolicyType HwPolicies[]

);


Parameters

HwPolicies is a list of types describing one or more hardware interfaces and an associated policy for that hardware interface(s). (Specifying more than one policy per hardware interface is invalid.) Specifying a partial or empty list will remove association of Circuit Breaker policies with the missing hardware interfaces.


239


Code Description



PT_STATUS_INVALID_PARAMETER Specified parameter is malformed.


Remarks

This call typically is issued by a remote console to set a common policy which may be activated by the local Agent Presence module. (This requires a state transition which is configured to enable a circuit breaker policy.)

If a local agent already performed a transition to a state that enables a policy, calling ConsoleWatchdogSetCbPolicy to define a policy will immediately enable this policy. If it has the highest priority among the enabled policies, this policy will become the active policy.

Note that all Agent Presence instances share the same policy. This reflects a logical relation to policy enablement. That is, that the Circuit Breaker module aggregates the policy enablement requests from all of the instantiated Agent Presence applications and keeps the policy enabled as long as there is at least a single application with requests to do so.

7.8.1.7 ConsoleWatchdogGetCbPolicy

Gets a global Circuit Breaker policy which may be activated by the Agent Presence module.

Header PT_STATUS ConsoleWatchdogGetCbPolicy( [out] CircuitBreakerHardwarePolicyType HwPolicies[]

);


Parameters

HwPolicies is a list of types describing one or more hardware interfaces and the associated policy for that hardware interface(s). If the list is empty or does not specify existing interfaces, then the missing interfaces effectively have no associated Circuit Breaker policies.



240

Code Description



Remarks

This call typically is issued by a remote console to get a common policy which may be activated by the local Agent Presence module.

This call should return the factory default configured into the device or the last value set during ConsoleWatchdogSetCbPolicy().

7.8.1.8 ConsoleWatchdogQueryCapabilities

Queries the capabilities of the Agent Presence feature.

Header PT_STATUS ConsoleWatchdogQueryCapabilities( [out] AgentPresenceCapabilitiesType Capabilities

);


Parameters

Capabilities is a structure describing the capabilities of the current Agent Presence feature


Code Description



Remarks

This call typically is issued by a remote console to query the capabilities of the Agent Presence feature.


241

7.8.2 Service APIs - Local Interface Namespace : http://schemas.intel.com/2004/12/management/PC/AgentWatchdogLocal Port : http://hostname:port/AgentWatchdogLocalService


Local Access √

Network Access −

The Local Agent Presence interface is used by registered applications (on the local host) to report the presence of the associated application (over the Intel Management Engine Interface).

Method Description

AgentWatchdogRegister Application watchdog registration

AgentWatchdogHeartbeat Application watchdog update

AgentWatchdogShutdown Application Termination update

7.8.2.1 AgentWatchdogRegister

This call is issued by applications that wish to start reporting their running state.

Header PT_STATUS AgentWatchdogRegister( [in] GUID AgentID, [out] uint32 SessionSequenceNumber, [out] uint16 AgentHeartbeatTime

);


Parameters

The AgentID parameter is a globally unique application identifier. (A given application should register using the same value on different machines).

SessionSequenceNumber is a random sequence number returned by the Intel AMT device. This number should be incremented by one in subsequent calls (when provided). After the counter reaches its highest possible value, it is rolled to zero. The sequence number is used to enforce detection of crashed applications which may have lost their handles. The sequence number is not intended to provide any form of security for this flow.

AgentHeartbeatTime is a seconds timer value which specifies the maximum time allowed between application heartbeat calls.


242


Code Description



PT_STATUS_INVALID_HANDLE The specified AgentID does not exist (i.e., it may have been removed or never been created by the remote console).

Remarks

Note: re-registration of a running application is allowed but may be interpreted by the Intel AMT device as an application that has gone through a crash/restart state. Since the state for crash/restart does not exist in the application state list, Intel AMT defines this to be a transition from “running” to “stopped” to “running.”

7.8.2.2 AgentWatchdogHeartbeat

This call is issued periodically by an application to report its running state.

Header PT_STATUS AgentWatchdogHeartbeat( [in] GUID AgentID, [in] uint32 SessionSequenceNumber

);


Parameters

AgentID is a globally unique application identifier (as specified in AgentWatchdogRegister).

SessionSequenceNumber is a random sequence number returned by the Intel AMT device when the agent last called AgentWatchdogRegister. This number is incremented after each call to a local Agent Presence function. After the counter reaches its highest possible value, it is rolled to zero. The sequence number is used to detect crashed applications which may have lost their sequence. The sequence number is not intended to provide security for this flow.



243

Code Description


PT_STATUS_INTERNAL_ERROR

An internal error occurred in the Intel AMT device during this operation. Agent should try recovering by re-registering. This error will be returned if the agent has not been registered since the last time it was in the NotStarted state.

PT_STATUS_INVALID_HANDLE The specified AgentID does not exist and may have been removed or never created by the remote console.

Remarks

Note: the Intel AMT device ignores calls to this routine with a malformed SessionSequenceNumber. (The return status is PT_STATUS_SUCCESS, but Intel AMT marks the application as not being updated). The device ignores the call so that an invalid agent trying to “scan” for the current sequence number receives a minimum amount of information. When Intel AMT has lost the ability to track SessionSequenceNumber (after System Shutdown) a PT_STATUS_INTERNAL_ERROR will be returned, and the software agent is expected to re-register.

If the Agent fails to send a heartbeat on time, the actions associated with the agent will be performed. In the event of an operating system crash, an agent presence watchdog timer may time out before the operating system watchdog timer times out. Console programs should take this possibility into account.

7.8.2.3 AgentWatchdogShutdown

This call is issued by applications to report their termination state.

Header PT_STATUS AgentWatchdogShutdown( [in] GUID AgentID, [in] uint32 SessionSequenceNumber

);


Parameters

AgentID is a globally unique application identifier as specified in AgentWatchdogRegister.

SessionSequenceNumber is a random sequence number returned by the Intel AMT device on the former AgentWatchdogRegister call. The number is incremented by one since it was last referenced by an Agent Presence call. A sequence number is used to enforce detection of crashed applications which may have lost the sequence. This sequence number is not intended to provide any


244

form of security for this flow. If a call is made with a bad sequence number, it will be ignored so that an invalid agent trying to “scan” for the current sequence number receives a minimum amount of information.


Code Description


PT_STATUS_INTERNAL_ERROR An internal error occurred in the Intel AMT device during this operation. This error will be returned if the agent has not been registered since the last time it was in the NotStarted state.

PT_STATUS_INVALID_HANDLE The specified AgentID does not exist and may have been removed or never created by the remote console.

Remarks

Note: the Intel AMT device ignores any call to this routine with a malformed SessionSequenceNumber. The return status appears successful, but the software tracked state is not being updated.

After this call succeeds (in such a way that the command is not ignored), the SessionSequenceNumber is no longer valid and subsequent calls cannot be issued until reregistering.

When Intel AMT has lost the ability to track SessionSequenceNumber (after System Shutdown) a PT_STATUS_INTERNAL_ERROR will be returned, and the software agent is expected to re-register.

This command should be used by applications to expedite state tracking of the software component. This call also may indicate a clean termination phase (i.e., the application was closed and didn’t crash).

Applications that are being terminated as a part of a global system shutdown don’t have to avoid calling this routine. Intel AMT should detect that the system is transitioning to a different system state and stop decrementing the application heartbeat counter.


7.8.3.1 GUID This structure is defined to represent Globally Unique Identifiers (GUIDs).

typedef byte[16] Guid;

Field Description

Guid A 16 byte array representing a Globally Unique Identifier.


245

7.8.3.2 ConsoleWatchdogEntryType

typedef struct _ConsoleWatchdogEntryType { GUID AgentID ; string AgentDescription ; uint16 AgentHeartbeatTime ; uint16 AgentStartupTime ; uint32 NumActions ; WatchdogState AgentCurrentState; } ConsoleWatchdogEntryType;

Field Description

AgentID Globally unique application identifier

AgentDescription Application description string

AgentHeartbeatTime A seconds timer value which specifies the maximum time allowed between application heartbeat calls

AgentStartupTime

A seconds timer value which specifies the maximum time allowed for an application to start up and start sending application heartbeat calls (i.e., the time after system restart or after creating a new Agent definition)

NumActions Number of actions associated with the application

AgentCurrentState The current known state of the Agent

7.8.3.3 ConsoleWatchdogActionType

typedef struct _ConsoleWatchdogActionType { WatchdogState OldState ; WatchdogState NewState ; boolean ActionEventOnTransition ; [optional] CbActionType ActionCB ; } ConsoleWatchdogActionType ;

Field Description

OldState The last state of the application watchdog. This state may be set to a value containing a logical OR of watchdog states.

NewState The current state of the application watchdog. This state may be set to a value containing a logical OR of watchdog states.


246

ActionEventOnTransition Specifies whether an Event should be created in the Event Manager when the application watchdog transitions from OldState to NewState.

ActionCB

A Circuit Breaker Action which may be applied, when the application watchdog transitions from OldState to NewState. If the caller did not specify a policy using ConsoleWatchdogSetCbPolicy() no policy will be activated, however if the caller used the ConsoleWatchdogSetCbPolicy() to specify a policy at later time, the policy may be activated immdiatly according to the logical state which is currently maintained by the Agent Presence feature.

Remarks If ActionEventOnTransition is set to false, then ActionCB must be provided.

Invalid transitions (for example, from the same state to itself or between two states which can never happen) are ignored by Intel AMT.

7.8.3.4 WatchdogState

typedef enum<uint16> _WatchdogState { WatchdogStateNotStarted = 0x0001, WatchdogStateStopped = 0x0002, WatchdogStateRunning = 0x0004, WatchdogStateExpired = 0x0008, WatchdogStateSuspended = 0x0010, WatchdogStateAny = 0x00FF, } WatchdogState;

Code Description

WatchdogStateNotStarted The associated application was not started

WatchdogStateStopped The associated application is stopped

WatchdogStateRunning The associated application is running

WatchdogStateExpired The associated application failed to reset the watchdog expiration timer

WatchdogStateSuspended The host platform running the application is in an Sx state

Note: This type may also contain values which are combined using a logical OR of the enumerated values. Such values are valid and are meant to simplify the description of combined state transitions.

7.8.3.5 CbActionType


247

typedef enum<uint16> _CbActionType { ActivateCbPolicy, DeactivateCbPolicy } CbActionType ;

Field Description

ActivateCbPolicy Specifies that a Circuit Breaker policy should be activated.

DeactivateCbPolicy Specifies that a Circuit Breaker policy should be deactivated. Note: only after all agents have been deactivating the policy, the active policy may get back to normal.

7.8.3.6 AgentPresenceCapabilitiesType typedef struct _AgentPresenceCapabilitiesType { uint MaxTotalAgents; uint MaxTotalActions; uint MinGuaranteedActionListSize; } AgentPresenceCapabilitiesType ;

Field Description

MaxTotalAgents The maximum number of agents that can be registered on the Intel AMT device.

MaxTotalActions The maximum number of actions that can be defined (altogether) on the Intel AMT device.

MinGuaranteedActionListSize The minimum number of actions that is guaranteed for every Agent on the Intel AMT device.

Remarks Note: the minimum number of actions available for each Agent is guaranteed to be the value MinGuaranteedActionListSize. The maximum action list size for any agent is defined by calculating:

Available Actions = MaxTotalActions – (MaxTotalAgents X MinGuaranteedActionListSize)

The maximum is Available Actions +MinGuaranteedActionListSize.

Any actions assigned to an agent beyond MinGuaranteedActionListSize reduce the pool in Available Actions available to other agents.

See Section 10.1 for the values of these parameters in the current release.


248

7.9 Circuit Breaker Interface Namespace : http://schemas.intel.com/2004/12/management/PC/CircuitBreaker Port : http://hostname:port/CircuitBreakerService


Local Access −

Network Access √

The Circuit Breaker interface (also known as System Defense) is used by remote or local applications (i.e., management consoles, agent presence, environment detection, and also NAC / 802.1X) to apply filters to the network traffic.

Method Description

CbPolicyCreate Creates a Circuit Breaker Policy.

CbPolicyGet Reads a Circuit Breaker Policy.

CbPolicyDelete Deletes a Circuit Breaker Policy.

CbPolicyEnumerate Enumerates Circuit Breaker Policies.

CbPolicyEnable Enables a Circuit Breaker Policy.

CbPolicyDisable Disables a Circuit Breaker Policy.

CbPolicyGetEnabled Reads enabled CircuitBreaker Policies.

CbPolicyGetActiveStatistics Reads the statistics associated with a Circuit Breaker policy.

CbFilterCreate Creates a Circuit Breaker Filter.

CbFilterGet Reads a Circuit Breaker Filter.

CbFilterDelete Deletes a Circuit Breaker Filter.

CbFilterEnumerate Enumerates Circuit Breaker Filters.

CbQueryCapabilities Queries Circuit Breaker capabilities.

7.9.1 Service APIs

7.9.1.1 CbPolicyCreate

This call creates a CircuitBreaker Policy.


249

Header PT_STATUS CbPolicyCreate(

[in] CircuitBreakerPolicyType Policy, [out] uint32 PolicyCreationHandle );


Parameters

The Policy parameter describes the policy that should be created.

PolicyCreationHandle returns the handle to be used in the subsequent calls in this section. Note: the returned handle is always unique (i.e., the handle value is never reused after deletion) unless the system has been returned to Factory Setup Mode.


Code Description



PT_STATUS_MAX_LIMIT_REACHED No space is left on flash for this operation.


Flash wear-out limit reached. Caller may try repeating this operation at a later time.


This status may be returned when the policy is configured incorrectly, such as when:

- Guidelines in filling the CircuitBreakerPolicyType structure may have not been followed.

- The hardware cannot support the specified configuration.

PT_STATUS_INVALID_HANDLE One of the filter handles which was specified in the Policy variable is invalid.

Remarks

This call is typically issued by a remote console that wishes to create a CircuitBreaker policy for the Intel AMT device.

This call does not check for similarity or duplication of policies. It is the caller’s responsibility to optimize for better policy usage.


250

7.9.1.2 CbPolicyGet

This call reads a specified CircuitBreaker Policy. Header PT_STATUS CbPolicyGet( [in] uint32 PolicyCreationHandle, [out] CircuitBreakerPolicyType Policy

);


Parameters

PolicyCreationHandle is a handle indicating a previously created policy.


Code Description



PT_STATUS_INVALID_HANDLE Specified handle does not exist.

Remarks

This call is typically issued by a remote console to read a CircuitBreaker policy from the Intel AMT device.

7.9.1.3 CbPolicyDelete

This call deletes a specified CircuitBreaker Policy.

Header PT_STATUS CbPolicyDelete( [in] uint32 PolicyCreationHandle

);



251

Parameters

PolicyCreationHandle is a handle indicating a previously created policy.


Code Description





Remarks

This call typically is issued by a remote console to remove a CircuitBreaker policy from the Intel AMT device.

Note: this call may remove any references of this policy from other features which may be using it, such as an action state of the Agent Presence feature.

Active policies are allowed to be deleted, and when they are, the next enabled policy with the highest priority is activated.

7.9.1.4 CbPolicyEnumerate

This call enumerates all CircuitBreaker Policies.

Header PT_STATUS CbPolicyEnumerate( [out] CircuitBreakerPolicyInfoType Policies[]

);


Parameters

Policies returns an array of structures that describe each Policy.



252

Code Description



Remarks

This call typically is issued by a remote console to enumerate CircuitBreaker policies that exist for the Intel AMT device.

7.9.1.5 CbPolicyEnable

This call enables a CircuitBreaker Policy. The policy is active when it has the highest precedence among the enabled policies.

Header PT_STATUS CbPolicyEnable( [in] CircuitBreakerHardwarePolicyType EnablePolicies[], [out] CircuitBreakerHardwarePolicyType ActivePolicies[]

);


Parameters

EnablePolicies describes one or more hardware interfaces and the associated policies. (Specifying more than one policy per hardware interface is invalid.)

On successful return, the ActivePolicies parameter contains an array of associated hardware interfaces and their active policies. (Hardware interfaces with no active policies do not appear on this list.)


Code Description




PT_STATUS_INVALID_PARAMETER Bad input parameter.


253

Remarks

This call typically is issued by a management console to enable a policy for a specified hardware interface. Calling this routine more than once for the same interface will override previous settings.

Note: Among all the enabled policies that can be enabled by different components within Intel AMT, only the policy with the highest priority will be chosen to be the active policy. A policy with a lower precedence value will become active only when the remaining policies with higher priority are disabled (See CbPolicyDisable() and ConsoleWatchdogSetCbPolicy()).

7.9.1.6 CbPolicyDisable

This call disables a CircuitBreaker Policy.

Header PT_STATUS CbPolicyDisable( [in, optional] uint32 HardwareID

);


Parameters

When HardwareID is missing, this command applies to all interfaces. When present, this command will be applied to the specified interface. See CbQueryCapabilities to understand how to submit a valid HardwareID.


Code Description




PT_STATUS_INVALID_PARAMETER Bad HardwareID.

Remarks

This command disables the policy associated with the AppTypeCircuitBreaker application type. (Every application type can have only one enabled policy).

Note: a new active policy is selected from the remaining active policies based on priority.


254

7.9.1.7 CbPolicyGetEnabled

This call returns the current enabled CircuitBreaker Policies.

Header PT_STATUS CbPolicyGetEnabled( [in, optional] CircuitBreakerApplicationType AppType [out] CircuitBreakerHardwarePolicyType HwPolicies[]

);


Parameters

AppType specifies the application whose enabled policies will be returned. When no application is specified, the function returns the current active policy for each interface.

On successful return, the HwPolicies parameter contains a list of hardware interfaces and their associated enabled or active policies, depending on the AppType parameter. A hardware interface with no associated policy will not appear on the returned list. Return Values One of the following status codes MUST be returned by this method:

Code Description



PT_STATUS_INVALID_HANDLE Invalid application type entered.

Remarks

This call typically is issued by a remote console to observe the state of enabled policies as requested by a specific application type.

Note: this call differs from CbPolicyEnable in the caller’s options for observing a specific application type state (CbPolicyEnable uses the state of AppTypeCircuitBreaker. See CircuitBreakerApplicationType.)

7.9.1.8 CbPolicyGetActiveStatistics

This call reads Filter statistics from the active CircuitBreaker policy.


255

Header PT_STATUS CbPolicyGetActiveStatistics( [in] uint32 HardwareID , [in] boolean ResetStatisticsOnRead , [out] uint32 PolicyCreationHandle , [out] TimeType ActivationTime , [out] TimeType LastResetTime , [out] CircuitBreakerFilterStatisticsType Statistics[]

);


Parameters

HardwareID is an identifier for the CircuitBreaker hardware interface. See CbQueryCapabilities to understand how to find the appropriate HardwareID.

ResetStatisticsOnRead determines if statistics are being reset after Read.

When the call succeeds, the PolicyCreationHandle parameter contains the creation handle of the active policy associated with the specified hardware interface. A value of 0xFFFFFFFF indicates that there is no active policy.

When the call succeeds, the ActivationTime parameter contains the time that the current active policy last became active. This parameter should be ignored when there is no active policy.

When the call succeeds, the LastResetTime parameter contains a time value that specifies the last time the statistics were reset in the specified policy. This parameter should be ignored when there is no active policy.

When the call succeeds, the Statistics parameter contains a list of filter statistics included in the active Policy. This parameter should be ignored when there is no active policy.


Code Description



PT_STATUS_INVALID_PARAMETER HardwareID is invalid

Remarks

This call typically is issued by a remote console to read CircuitBreaker filter statistics from the Intel AMT device.

Note:


256

• There may be a difference between the number of the filtered packets and the actual statistics count values due to the overhead involved with statistics management. This includes differences which may appear between similar filters.

• Statistics are lost if the machine enters the Moff state,power source is disconnected or if the power policy is changed.

7.9.1.9 CbFilterCreate

This call creates a CircuitBreaker Filter.

Header PT_STATUS CbFilterCreate( [in] CircuitBreakerFilterType Filter, [out] uint32 FilterCreationHandle

);


Parameters

This Filter parameter describes the Filter that should be created.

FilterCreationHandle returns a handle to be used in the subsequent calls in this section.

The returned handle always is unique (i.e., the handle value is never being reused after deletion) unless the system has been returned to Factory Setup Mode.


Code Description




PT_STATUS_MAX_LIMIT_REACHED No space left is left on flash for this operation.

PT_STATUS_INVALID_PARAMETER May be returned if the Filter is set incorrectly or if the hardware cannot support the specified configuration


257

Remarks

This call typically is issued by a remote console to create a CircuitBreaker filter for the Intel AMT device. This call does not check for Filter similarity or duplication. It is the caller’s responsibility to optimize for better Filter usage.

7.9.1.10 CbFilterGet

This call reads a CircuitBreaker Filter.

Header PT_STATUS CbFilterGet( [in] uint32 FilterCreationHandle , [out] CircuitBreakerFilterType Filter

);


Parameters

FilterCreationHandle is a previously created filter handle.

Filter is a returned Filter description.


Code Description




Remarks

This call typically is issued by a remote console to read a CircuitBreaker filter from the Intel AMT device.

7.9.1.11 CbFilterDelete

This call deletes a specified CircuitBreaker Filter.


258

Header PT_STATUS CbFilterDelete( [in] uint32 FilterCreationHandle

);


Parameters

FilterCreationHandle is a previously created filter handle.


Code Description





PT_STATUS_NOT_PERMITTED Filter exists in a Policy and cannot be deleted as such.

Remarks

This call typically is issued by a remote console to delete a CircuitBreaker filter from the Intel AMT device.

7.9.1.12 CbFilterEnumerate

This call enumerates all CircuitBreaker Filters.

Header PT_STATUS CbFilterEnumerate( [out] CircuitBreakerFilterInfoType Filters[]

);



259

Parameters

Filters is a returned array of Filter descriptions.


Code Description



Remarks

This call typically is issued by a remote console to enumerate all the CircuitBreaker filters on the Intel AMT device.

7.9.1.13 CbQueryCapabilities

This call queries CircuitBreaker capabilities.

Header PT_STATUS CbQueryCapabilities( [out] uint32 MaxSupportedPolicies , [out] uint32 MaxSupportedFilters , [out] CircuitBreakerCapabilitiesType Capabilities[]

);


Parameters

MaxSupportedPolicies specifies the maximum number of supported policies allocated by the Intel AMT device.

MaxSupportedFilters specifies the maximum number of supported filters allocated by the Intel AMT device.

Capabilities returns CircuitBreaker capabilities structures for each hardware resource that supports CircuitBreaker.



260

Code Description



Remarks

This call typically is issued by a remote console to query the CircuitBreaker capabilities of the Intel AMT device.

7.9.2 Service APIs (Heuristics Circuit Breaker) This section describes various APIs related to the Heuristics Circuit Breaker feature.

This feature allows an IT administrator to create policies to monitor a network interface and associate actions if policies are breached.

7.9.2.1 SetHcbOptions

Header PT_STATUS SetHcbOptions(

[in] 8InterfaceHandleType InterfaceHandle, [in, optional] HcbOptionsType HcbOptions );


Parameters

InterfaceHandle

A handle to interface descriptor

HcbOptions

Heuristics Circuit Breaker configuration settings or Null value to turn off HCB settings



261

Code Description



PT_STATUS_UNSUPPORTED Configuration is not supported by the interface

PT_STATUS_INVALID PARAMETER Invalid settings


Remarks

Note: Setting new HCB Options may cause the active HCB action to be cleared as if ClearHcbState() was called.

7.9.2.2 GetHcbOptions

Header PT_STATUS GetHcbOptions(

[in] 8InterfaceHandleType InterfaceHandle, [out, optional] HcbOptionsType HcbOptions );


Parameters

InterfaceHandle


HcbOptions

Heuristics Circuit Breaker configuration settings. When this parameter is Null, heuristics circuit Breaker is disabled for the interface.



262

Code Description



7.9.2.3 ClearHcbState

Header PT_STATUS ClearHcbState(

[in] InterfaceHandleType InterfaceHandle );


Parameters

InterfaceHandle



Code Description



PT_STATUS_NOT_PERMITTED HCB is currently disabled.

PT_STATUS_INVALID_PARAMETER Interface handle is invalid

Remarks

This API clears the state of an activated Heuristics Circuit Breaker action. On successful execution of this command, the HCB should be in HcbStateRunning state.

HCB will be restarted again after this call.


263

7.9.2.4 GetHcbState

This command returns the state of the heuristic circuit breaker mechanism for a selected interface. Header PT_STATUS GetHcbState(

[in] InterfaceHandleType InterfaceHandle, [out] HcbStateType HcbState, [out] boolean BlockedAll, [out, optional] TimeType TimeStamp, [out, optional] HcbTriggerReasonType HcbTriggerReason, [out, optional] BlockedPortInfoType BlockedPortInfo, [out, optional] uint32 EnabledCBPolicy );


Parameters

InterfaceHandle


HcbState

The state of HCB state machine.

BlockedAll

Indicates whether all Tx traffic was blocked as a result of an HCB action

TimeStamp

A time stamp of the last transition to the current state or when the blocking policy (ports or protocols) changes. This parameter is Null when the current state is HcbStateRunning or HcbStateDisabled.

HcbTriggerReason

This parameter contains the reason that caused the last transition from running state. This parameter is Null when the current state is HcbStateRunning. This parameter is Null when the current state is HcbStateRunning or HcbStateDisabled.

BlockedPortInfo

If the triggered action was a block of the offending port, this parameter will be set to hold information about the port.


264

This parameter describes the blocked port information in case this action was triggered by HCB. When this parameter is Null, no port-blocking is applied by HCB. This parameter is Null when the current state is HcbStateRunning or HcbStateDisabled.

EnabledPolicy

This parameter specifies a Circuit Breaker policy handle, which was enabled by HCB. When this parameter is Null, no Circuit Breaker policy was applied by HCB. This parameter is Null when the current state is HcbStateRunning or HcbStateDisabled.


Code Description



PT_STATUS_UNSUPPORTED Configuration is not supported by the interface

PT_STATUS_INVALID PARAMETER Invalid settings

Remarks

The time remaining in encounter mode is not saved in Flash, so an internal reset or a power disconnect will cause the engine of the heuristics to start from running state.


7.9.3.1 CircuitBreakerPolicyType

typedef struct _CircuitBreakerPolicyType {

[optional] string PolicyName ; uint32 PolicyPrecedence ; [optional] CircuitBreakerAntiSpoofingFilterType AntiSpoofingFilter; uint32 FilterCreationHandles[]; CircuitBreakerDefaultFilterType DefaultTxFilter; CircuitBreakerDefaultFilterType DefaultRxFilter;

} CircuitBreakerPolicyType ;


265

Field Description

PolicyName

Policy name string is optional.

Contains 7-bit ASCII characters, in the range of 33 to 126 excluding ‘:’, ‘,’, '>', '<', '&', and ‘”’ characters. String length is limited to 16 characters.

PolicyPrecedence In case multiple policies are being activated simultaneously, the policy with the highest precedence value takes effect. (Policies with the same precedence are chosen arbitrarily).

AntiSpoofingFilter

When specified, Anti Spoofing will be enabled. Note: this option consumes extra TX filters (IPv4 or IPv6). If enabled, then the maximum list size of FilterCreationHandles is reduced by the number of filters that is defined for Anti Spoofing.

Anti Spoofing has the highest priority for blocking. Any packet that does NOT pass AS filter will not be transmitted even if it passes other filters. Any packet that does pass the AS filter is subject to the rest of the CB filters before it is transmitted.

Note: Anti Spoofing cannot handle configurations in which the machine uses multiple IP addresses. In such cases, Anti Spoofing has to be disabled and the relevant filters should be configured separately.

Note: Intel AMT Release 2.0 requires an IPv4 IP address. Further, anti-spoofing is allowed only when Intel AMT shares an IP address with the host (DHCP-configured IP). Therefore, a host configured with an IPv6 address is incompatible with anti-spoofing.

FilterCreationHandles

A list of Filter Creation-Handles to be included in the Policy. If filter definitions for Transmit or Receive are excluded, then the DefaultTxFilter and DefaultRxFilter will be used, respectively.

DefaultTxFilter Default Unmatched filter for Transmit.

DefaultRxFilter Default Unmatched filter for Receive.

7.9.3.2 CircuitBreakerPolicyInfoType

typedef struct _CircuitBreakerPolicyInfoType { struct CircuitBreakerPolicyType Policy ; uint32 PolicyCreationHandle ; } CircuitBreakerPolicyInfoType ;

Field Description

Policy A Policy description


266

Field Description

PolicyCreationHandle A Policy associated handle

7.9.3.3 CircuitBreakerFilterType

typedef struct _CircuitBreakerFilterType { [optional] string FilterName ; CircuitBreakerFilterDirectionType FilterDirection ; CircuitBreakerFilterProfileType FilterProfile ; uint32 FilterProfileData ; CircuitBreakerPacketType FilterPacket ;

boolean ActionEventOnMatch ; } CircuitBreakerFilterType ;

Field Description

FilterName

Filter name string is optional.

Contains 7-bit ASCII characters, in the range of 33 to 126 excluding ‘:’, ‘,’, '>', '<', '&', and ‘”’ characters. String length is limited to 16 characters.

FilterDirection Indicates whether this is a TX or RX filter.

FilterProfile Determines whether the filter is Statistics / Drop / Pass or Rate limit.

FilterProfileData

An extra data parameter which is used depending on the FilterProfile- for Drop/Pass/Statistics filter, it is not used - for rate limit, it indicates the max number of packets per second (should be greater than 0). Rate limits are not exact. Typically several more packets than the number in the rate limit will be allowed to pass before traffic is blocked. If the boundary is critical, set the maximum number of events to a lower value.

FilterPacket Describes the packet that should be filtered

ActionEventOnMatch

Specifies whether an Event should be created in the Event Manager when this filter is matched. Note: - The event will be generated once and will be generated again only after statistics are read. - The creation of an event log record and the transmission of a PET packet is subject to the rules configured into the Event Manager

7.9.3.4 CircuitBreakerDefaultFilterType

typedef struct _CircuitBreakerDefaultFilterType {

boolean ActionDrop ; boolean ActionEventOnMatch ;


267

boolean ActionCount ; } CircuitBreakerDefaultFilterType ;

Field Description

ActionDrop Specifies whether the packet should be dropped on filter match.

ActionEventOnMatch Specifies whether an Event should be created in the Event Manager when this filter is matched. (The event will be generated once and will be allowed again only after statistics are read)

ActionCount Specifies whether to count filter matches. (Specifying TRUE in this action will consume one extra counter from the counter resources of the Policy.)

7.9.3.5 CircuitBreakerAntiSpoofingFilterType typedef struct _CircuitBreakerAntiSpoofingFilterType {

boolean ActionEventOnMatch ; boolean ActionCount ;

} CircuitBreakerAntiSpoofingFilterType ;

Field Description

ActionEventOnMatch Specifies whether an Event should be created in the Event Manager when this filter is matched. (The event will be generated once, and will be allowed again only after statistics are read.)

ActionCount Specifies whether to count filter matches. (Specifying TRUE in this action will consume one extra counter from the counter resources of the Policy.)

7.9.3.6 CircuitBreakerFilterInfoType

typedef struct _CircuitBreakerFilterInfoType { struct CircuitBreakerFilterType Filter; uint32 FilterCreationHandle; } CircuitBreakerFilterInfoType ; Field Description

Filter A filter description

FilterCreationHandle A Filter associated handle


268

7.9.3.7 CircuitBreakerFilterProfileType

typedef enum<uint16> _CircuitBreakerFilterProfileType { FilterProfileStatisticsPass = 0, FilterProfileStatisticsDrop , FilterProfileRateLimit , FilterProfilePass , FilterProfileDrop } CircuitBreakerFilterProfileType;

Note:

• In case there is a collision between two rules, the drop rule will surpass the pass rule. However the filter statistics will still be collected.

• Rate limit filters should not overlap in their definitions of packet type (for example, ranges of source IP that overlap) such that a packet may match the conditions of more than one filter. The filters are not completely independent of each other and more traffic will be blocked or passed than was intended.

Field Description

FilterProfileStatisticsPass Indicates that the filter is a “statistics” filter Note: this also will be considered as a “pass filter”

FilterProfileStatisticsDrop Indicates that the filter is a “statistics” filter Note: this also will be considered as a “drop filter”

FilterProfileRateLimit Indicates that the filter is a “rate-limit” filter

FilterProfilePass Indicates that the filter is a “filter pass” filter

FilterProfileDrop Indicates that the filter is a “filter drop” filter

7.9.3.8 CircuitBreakerCapabilitiesType

typedef struct _CircuitBreakerCapabilitiesType { string HardwareDescription; uint32 HardwareID; uint16 IPv4_MaxTxFilters ; uint16 IPv4_MaxTxCounters ; uint16 IPv4_MaxRxFilters ; uint16 IPv4_MaxRxCounters ; boolean IPv4_AntiSpoofingCapable ; uint16 IPv6_MaxTxFilters ; uint16 IPv6_MaxTxCounters ; uint16 IPv6_MaxRxFilters ; uint16 IPv6_MaxRxCounters ;


269

boolean IPv6_AntiSpoofingCapable ; uint16 IPv6_to_IPv4_Ratio ; } CircuitBreakerCapabilitiesType ; Field Description

HardwareDescription A string identifying the associated hardware entity

HardwareID An identification handle associated with this hardware.

IPv4_MaxTxFilters Maximum number of active IPv4 Transmit filters (note: this number includes default filters).

IPv4_MaxTxCounters Maximum number of active IPv4 Transmit counters (a counter is used in Statistics or Rate Limit filters)

IPv4_MaxRxFilters Maximum number of active IPv4 Receive filters (note: this number includes default filters).

IPv4_MaxRxCounters Maximum number of active IPv4 Receive counters

IPv4_AntiSpoofingCapable Indicates whether the device supports Anti Spoofing filter for IPv4

IPv6_MaxTxFilters Maximum number of active IPv6 Transmit filters

IPv6_MaxTxCounters Maximum number of active IPv6 Transmit counters (this value specifies how many transmit filters may be configured as counter filters)

IPv6_MaxRxFilters Maximum number of active IPv6 Receive filters

IPv6_MaxRxCounters Maximum number of active IPv6 receive counters

IPv6_AntiSpoofingCapable Indicates whether the device supports Anti Spoofing filter for IPv6

IPv6_to_IPv4_Ratio Indicates how many IPv4 filters (or counters) are approximately occupied by an IPv6 filter (or counter, respectively).

See Quantitative Properties and Capabilities for default values for many of these parameters.

Additional notes: Ethernet filters or counters consume the same amount of resources as IPv4 filters or counters respectively.

All IPv4 Rx counters and all IPv4 Tx counters can be assigned to the same policy, but only if one IPv4 counter is assigned to the “else” filter.

Combinations of IPv4 and IPv6 Tx counters or IPv4 and IPv6 Rx counters do not require use of the “else” filter.

7.9.3.9 CircuitBreakerFilterDirectionType typedef enum<uint16> _CircuitBreakerFilterDirectionType { FilterDirectionTransmit = 0, FilterDirectionReceive } CircuitBreakerFilterDirectionType ;


270

Field Description

FilterDirectionTransmit Indicates that the filter is associated with the Transmit flow

FilterDirectionReceive Indicates that the filter is associated with the Receive flow

7.9.3.10 CircuitBreakerFilterIPAddressDirectionType

typedef enum<uint16> _CircuitBreakerFilterIPAddressDirectionType { FilterDirectionSource = 0, FilterDirectionDestination } CircuitBreakerFilterIPAddressDirectionType ;

Field Description

FilterDirectionSource Indicates that the IP is filtered based on the source address

FilterDirectionDestination Indicates that the IP is filtered based on the destination address

7.9.3.11 CircuitBreakerFilterStatisticsType

typedef struct _CircuitBreakerFilterStatisticsType { uint32 FilterCreationHandle , uint32 ReadCount , boolean FilterMatched } CircuitBreakerFilterStatisticsType ;

Field Description

FilterCreationHandle

An identifier of the filter being reported. A value of 0xFFFFFFFA indicates that this is the Anti Spoofing (TX) filter,

A value of 0xFFFFFFFC indicates that this is the default (unmatched) TX filter,

A value of 0xFFFFFFFD indicates that this is the default (unmatched) RX filter

ReadCount

Filter read count (since last statistics reset). This field should be treated only if the defined filter is of type FilterProfileStatisticsPass / FilterProfileStatisticsDrop or if ‘ActionCount’ was set to TRUE in the Policy default (unmatched) or AntiSpoofing filter.

FilterMatched Indicates whether this filter was matched since last statistics reset (This includes rate limit filter that was past its threshold value).


271

7.9.3.12 CircuitBreakerPacketType

typedef struct _CircuitBreakerPacketType { choice { CircuitBreakerPacketIPType PacketIP ; CircuitBreakerPacketUDPType PacketUDP ; CircuitBreakerPacketTCPType PacketTCP ; CircuitBreakerPacketETHType PacketETH ; } u ; } CircuitBreakerPacketType ;

Field Description

PacketIP Describes an IP packet filter

PacketUDP Describes a UDP filter

PacketTCP Describes a TCP filter

PAcketETH Describes an Ethernet filter

7.9.3.13 CircuitBreakerPacketIPType

typedef struct _CircuitBreakerPacketIPType { CircuitBreakerIPPacketType IPPacket; [optional] uint8 NextProtocol ; } CircuitBreakerPacketIPType ;

Field Description

IPAddress An IP address descriptor

NextProtocol Next protocol type (see IANA protocol type definitions referred to in Reference Documents)

7.9.3.14 CircuitBreakerIPPacketType

typedef struct _CircuitBreakerIPPacketType { choice {

CircuitBreakerIPv4Type IPv4; CircuitBreakerIPv6Type IPv6; } u ;

} CircuitBreakerIPPacketType;


272

Field Description

IPv4 An IPv4 filter description

IPv6 An IPv6 filter description

7.9.3.15 CircuitBreakerIPv4Type This structure is used to define a filter for capturing IPv4 traffic.

typedef struct _CircuitBreakerIPv4Type {

[optional] CircuitBreakerIPv4AddressAndMaskType IPv4Desc ; } CircuitBreakerIPv4Type ;

Field Description

IPv4Desc

If this value is NULL, then the containing struct describes a general IPv4 filter. If this value is specified, then the containing struct describes an IPv4 filter which is described by this variable.

7.9.3.16 CircuitBreakerIPv6Type This structure is used to define a filter for capturing IPv6 traffic.

typedef struct _CircuitBreakerIPv6Type {

[optional] CircuitBreakerIPv6AddressAndMaskType IPv6Desc ; } CircuitBreakerIPv6Type ;

Field Description

IPv6Desc If this value is NULL, the containing struct describes a general IPv6 filter. If this value is specified, the containing struct describes an IPv6 filter which is described by this variable.

7.9.3.17 CircuitBreakerIPv4AddressAndMaskType

typedef struct _CircuitBreakerIPv4AddressAndMaskType { CircuitBreakerFilterIPAddressDirectionType IPAddressDirection ; IPv4AddressStringType Address; IPv4AddressStringType AddressMask; } CircuitBreakerIPv4AddressAndMaskType;


273

Field Description

Direction Indicates which field in the IP address this description applies to (source / destination)

Address Address description

AddressMask Mask description. Note: only leading 1’s should be respected

7.9.3.18 CircuitBreakerIPv6AddressAndMaskType

typedef struct _CircuitBreakerIPv6AddressAndMaskType { CircuitBreakerFilterIPAddressDirectionType IPAddressDirection; IPv6AddressStringType Address ; IPv6AddressStringType AddressMask ; } CircuitBreakerIPv6AddressAndMaskType;

Field Description

Direction Indicates which field in the IP address this description applies to (receive / transmit)

Address Address description

AddressMask Mask description. Note: only trailing or leading 1’s should be respected

7.9.3.19 CircuitBreakerPacketUDPType

typedef struct _CircuitBreakerPacketUDPType { CircuitBreakerIPPacketType IPPacket ; [optional] CircuitBreakerIPLayeredPortType IPLayeredPort ; } CircuitBreakerPacketUDPType ;

Field Description

IPAddress IP address descriptor

IPLayeredPort Port descriptor

7.9.3.20 CircuitBreakerIPLayeredPortType

typedef struct _CircuitBreakerIPLayeredPortType { choice { CircuitBreakerIPLayeredPortSimpleType IPLayeredPortSimple ;


274

CircuitBreakerIPLayeredPortRangeType IPLayeredPortRangeSource ; CircuitBreakerIPLayeredPortRangeType IPLayeredPortRangeDestination ; } u ; } CircuitBreakerIPLayeredPortType ;

Field Description

IPLayeredPortSimple Simple port descriptor

IPLayeredPortRangeSource Range port descriptor for source

IPLayeredPortRangeDestination Range port descriptor for target

7.9.3.21 CircuitBreakerIPLayeredPortSimpleType

typedef struct _CircuitBreakerIPLayeredPortSimpleType { uint16 SourcePort ; uint16 DestinationPort ; } CircuitBreakerIPLayeredPortSimpleType ;

Field Description

SourcePort Source port number

DestinationPort Destination port number

7.9.3.22 CircuitBreakerIPLayeredPortRangeType

typedef struct _CircuitBreakerIPLayeredPortRangeType { uint16 PortMin ; uint16 PortMax ; } CircuitBreakerIPLayeredPortRangeType ;

Field Description

PortMin Minimum port number

PortMax Maximum port number

7.9.3.23 CircuitBreakerPacketTCPType


275

typedef struct _CircuitBreakerPacketTCPType { CircuitBreakerIPPacketType IPPacket; [optional] CircuitBreakerIPLayeredPortType IPLayeredPort ; [optional] CircuitBreakerIPLayeredTcpFlagsType TcpFlags ; } CircuitBreakerPacketTCPType ;

Field Description

IPAddressType IP address descriptor

IPLayeredPort Port descriptor

TcpFlags TCP flags descriptor

7.9.3.24 CircuitBreakerIPLayeredTcpFlagsType

typedef struct _CircuitBreakerIPLayeredTcpFlagsType { [optional] boolean TCP_FLAG_FIN ; [optional] boolean TCP_FLAG_SYN ; [optional] boolean TCP_FLAG_RST ; [optional] boolean TCP_FLAG_PUSH ; [optional] boolean TCP_FLAG_ACK ; [optional] boolean TCP_FLAG_URG ; [optional] boolean TCP_FLAG_ECNE ; [optional] boolean TCP_FLAG_CWR ; [optional] boolean TCP_FLAG_NS ; [optional] boolean TCP_FLAG_Reserved1 ; [optional] boolean TCP_FLAG_Reserved2 ; [optional] boolean TCP_FLAG_Reserved3 ; } CircuitBreakerIPLayeredTcpFlagsType ;

Field Description

TCP_FLAG_FIN FIN flag (see TCP RFC describing this flag and the following)

TCP_FLAG_SYN SYN flag

TCP_FLAG_RST RST flag

TCP_FLAG_PUSH PUSH flag

TCP_FLAG_ACK ACK flag

TCP_FLAG_URG URG flag

TCP_FLAG_ECNE ECNE flag

TCP_FLAG_CWR CWR flag

TCP_FLAG_NS NS flag

TCP_FLAG_Reserved1 Reserved for future usage (unsupported)


276



7.9.3.25 CircuitBreakerPacketETHType

typedef struct _CircuitBreakerPacketETHType { uint16 EthernetFrameType ; } CircuitBreakerPacketETHType ;

Field Description

EthernetFrameType Ethernet frame descriptor

7.9.3.26 IPv4AddressStringType

typedef string IPv4AddressStringType;

Field Description

IPv4AddressStringType A standard string representation of an IPv4 address. example: “1.2.3.4”

7.9.3.27 IPv6AddressStringType

typedef string IPv6AddressStringType;

Field Description

IPv6AddressStringType

A standard string representation of an IPv6 address (according to RFC 2373, Section 2.2). examples: - “0102:0304:0506:0708:0A01:0A02:0A03:0A04”

- “0102:0304:0506:0708:0A01:0A02:1.2.3.4”

7.9.3.28 CircuitBreakerApplicationType

typedef enum<uint16> _CircuitBreakerApplicationType { AppTypeCircuitBreaker = 0, AppTypeAgentPresence = 1, AppTypeEnvironmentDetection = 3,


277

AppTypeHeuristicCircuitBreaker = 4 } CircuitBreakerApplicationType;

Field Description

AppTypeCircuitBreaker Circuit Breaker application type

AppTypeAgentPresence Agent Presence application type

AppTypeEnvironmentDetection Environment detection application type

AppTypeHeuristicCircuitBreaker Heuristic Circuit Breaker application type

7.9.3.29 CircuitBreakerHardwarePolicyType

typedef struct _CircuitBreakerHardwarePolicyType { uint32 HardwareID , uint32 PolicyCreationHandle } CircuitBreakerHardwarePolicyType ;

Field Description

HardwareID An identifier for the CircuitBreaker hardware interface. See CbQueryCapabilities to understand how to find the appropriate HardwareID.

PolicyCreationHandle A previously created handle

7.9.3.30 HcbOptionsType

typedef struct {

// Conditions [optional] TimedCounterType FastConnectionRate ; [optional] TimedCounterType SlowConnectionRate ; // Actions boolean BlockAll ; boolean BlockOffensivePort ; [optional] uint32 PolicyCreationHandle ; // Options uint16 EncounterTimeout ;

} HcbOptionsType ;


278

Field Description

FastConnectionRate

Specifies how many “fast connections” are permitted per a unit of time. Clear time is in units of milliseconds, and the permitted range is between 10 milliseconds to 1000 milliseconds. The recommended values for these parameters are: 8 unique connections in 10 milliseconds.

An alternate recommended value set is: 16 unique connections in 50 milliseconds.

SlowConnectionRate

Specifies how many “slow connections” are permitted per a unit of time. Clear time is in units of milliseconds, and the permitted range is between 1 second to 50 seconds. The recommended values for these parameters are: 64 unique connections in 50 seconds.

An alternate recommended value set is: 32 unique connections in 1 second.

BlockAll Block All TX traffic

BlockOffensivePort

Specifies whether the offending TX port should be blocked if one of the conditions applies. This can be a TCP port or a UDP port, depending on the protocol in the offending messages.

PolicyCreationHandle

Specifies whether a Circuit Breaker Policy should be enabled if one of the conditions applies. The Circuit Breaker Policy will be active only if it has the highest priority among the enabled policies.

EncounterTimeout

A Timer value (in seconds) which defines how long the Intel AMT device will stay in "Encounter" mode (activating configured actions). At the expiration of the timer value, the Intel AMT device will transition to "running" mode and send a "system clean" alert.

The minimum value for EncounterTimeout is 20 seconds. 0 has a special meaning – "move immediately to stopped mode if a trigger occurs".

Remarks • An event is always fired if one of the policies applies; please refer to the PET definition

section. • At least one of the timers must be defined. • Supported Actions:

o Block All TX Traffic o Block Offending Port for the protocol where the problem was detected-UDP or TCP o Enable policy o Block Offending Port and Enable Policy.


279

o There is no reason to Block all TX traffic and add the BlockOffensivePort action, as the "other" action will be ignored.

7.9.3.31 TimedCounterType

typedef struct {

uint32 ThresholdCounter ; uint32 ClearTime ;

} TimedCounterType ;

Field Description

ThresholdCounter Specifies how many match conditions can occur and the respective threshold from which the actions should occur.

ClearTime

Can be either in units of seconds or milliseconds, depending on the context of the use context. At the end of the clear time, the counter is cleared and count begins from zero.

7.9.3.32 BlockedPortInfoType

typedef struct {

uint16 PortBlocked ; uint16 ProtocolBlocked ;

} BlockedPortInfoType ;

Field Description

PortBlocked Number of blocked port

ProtocolBlocked Blocked protocol information – 6 for TCP, 17 for UDP.

7.9.3.33 HcbStateType

typedef enum<uint16> _HcbStateType { HcbStateRunning = 0, HcbStateTimedEncounter = 1, HcbStatePermanentEncounter = 2,


280

HcbStateDisabled = 3, } HcbStateType;

Field Description

HcbStateRunning The Heuristics Circuit Breaker state machine is in the "running" state. No traffic is filtered by this feature.

HcbStateTimedEncounter

The Heuristics Circuit Breaker state machine has been moved to "encounter" state. Part or all of the host traffic may be filtered. Caller may reset this state by calling ClearHcbState() or wait for the "encounter timeout" value which was configured. Note: the "encounter timeout" timer is active only when the host machine is in the S0 state. Note: this state might not be restored after power outage.

HcbStatePermanentEncounter

The Heuristics Circuit Breaker state machine has been moved to "stop" state. Part or all of the host traffic may be filtered. Caller may reset this state by calling ClearHcbState() Note: this state will be restored after power loss.

HcbStateDisabled The Heuristics Cuircuit Breaker machine is not active. The feature may be disabled. Note: this state will be restored after power loss.

7.9.3.34 HcbTriggerReasonType

typedef enum<uint16> _HcbTriggerReasonType { SlowWormDetection = 0, FastWormDetection = 1, DoSDetection = 2, } HcbTriggerReasonType;

Field Description

SlowWormDetection An Hcb triggered by a slow connection rate condition.

FastWormDetection An Hcb triggered by a fast connection rate condition.

DosDetection An Hcb triggered by an internal DoS detection mechanism (host attempts to open 100 connections in 10milliseconds).


281

7.10 Redirection Interface Namespace : http://schemas.intel.com/2004/12/management/PC/Redirection Port : http://hostname:port/RedirectionService


Local Access −

Network Access √

The Redirection Interface is built for remote redirection applications, such as management consoles or redirection utilities.

Method Description

SetRedirectionListenerState Enables/Disables the Redirection service listener.

GetRedirectionListenerState Gets the Redirection service listener state (enabled/disabled).

GetIderSessionLog Reads the current IDER session log.

7.10.1 Service APIs

7.10.1.1 SetRedirectionListenerState

This call enables/disables the Redirection service listener.

Header PT_STATUS SetRedirectionListenerState(



Parameters

Enabled specifies whether the listener for Redirection Services is active. Return Values One of the following status codes MUST be returned by this method:


282

Code Description




PT_STATUS_NOT_PERMITTED Enabling the listener is not permitted as SOL and IDER are disabled through the SetEnabledInterfaces() command.

Remarks

Even if this call succeeds, the enabled redirection service is overridden by the Security Administration Interface. For details, please refer to the command SetEnabledInterfaces() .

7.10.1.2 GetRedirectionListenerState

This call gets the enabled/disabled the Redirection service listener state.

Header PT_STATUS GetRedirectionListenerState(



Parameters

Enabled specifies whether the listener for Redirection Services is active.


Code Description




283

Remarks

Note that the returned parameter is ‘true’ only if SOL or IDER was enabled by SetEnabledInterfaces() and by SetRedirectionListenerState().

7.10.1.3 GetIderSessionLog

This call reads the IDER session log. Header PT_STATUS GetIderSessionLog(

[out] IderSessionLogEntryType LogData[] );


Parameters

LogData provides a list of session log entries. Return Values One of the following status codes MUST be returned by this method:

Code Description



Remarks

This call returns the IDER session log history.


7.10.2.1 IderSessionLogEntryType

typedef struct _IderSessionLogEntryType {

IPv4AddressType ConsoleAddress; uint16 Port; TimeType TimeStamp;

} IderSessionLogEntryType ;


284

Field Description

ConsoleAddress Remote console address

Port Port from which the remote console initiated the session

TimeStamp Time stamp of creating this record


285

7.11 Network Time Interface Namespace : http://schemas.intel.com/2004/12/management/PC/NetworkTime Port : http://hostname:port/NetworkTimeService


Local Access −

Network Access √

The NetworkTime Interface is built for remote time configuration by management console. Newer management applications should use this interface instead of using SetEventLogTimestampClock().

Method Description

GetLowAccuracyTimeSynch Gets low accuracy time value.

SetHighAccuracyTimeSynch Sets high accuracy time value.

7.11.1 Service APIs

7.11.1.1 GetLowAccuracyTimeSynch

This call gets a low accuracy timestamps. The function is used by a management console to query time values (set later by SetHighAccuracyTimeSynch).

Header PT_STATUS GetLowAccuracyTimeSynch( [out] TimeType Ta0

);


Parameters

Ta0 provides the local time on the Intel AMT device.



286

Code Description



Remarks

This routine is used for reading the Intel AMT internal clock. Please refer to the algorithm described in the next section on how to set time in the Intel AMT device.

7.11.1.2 SetHighAccuracyTimeSynch

This call sets the local time on the Intel AMT device. Header PT_STATUS SetHighAccuracyTimeSynch( [in] TimeType Ta0, [in] TimeType Tm1, [in] TimeType Tm2

);


Parameters

Ta0

Is the time value received from Intel AMT after calling GetLowAccuracyTimeSynch().

Tm1

Is the management console timestamp after getting a response from GetLowAccuracyTimeSynch().

Tm2

Is the management console timestamp before calling this routine.


Code Description




287

PT_STATUS_INVALID_PARAMETER Specified parameter is invalid (Returned when Ta0 > Ta3) or if any of the time values fall outside the valid TimeType range



Remarks

This routine is used for setting the Intel AMT internal clock.

By using GetLowAccuracyTimeSynch() and SetHighAccuracyTimeSynch(), a management console can set the Intel AMT time similar to the method used by network time protocols (i.e. RFC 2030).

Here is the flow of setting a time in Intel AMT

1. Management console calls GetLowAccuracyTimeSynch() Ta0 is the time returned by Intel AMT, and Tm1 is the timestamp of receiving the message.

2. Management console marks the current timestamp, Tm2, and calls SetHighAccuracyTimeSynch() with (Ta0, Tm1, Tm2). Note that usually Tm1=Tm2.

3. The Intel AMT device:

• Marks the current timestamp Ta3

• Computes d = ((Tm2+Tm1) – (Ta0 +Ta3)) /2

• Adds the computed offset to the current time (sets the local time to: [d + Ta3]).

Note: the GetLowAccuracyTimeSynch() and SetHighAccuracyTimeSynch() routines are used instead of SetEventlogTimeStampClock() which is unavailable when Kerberos authentication is enabled.

7.11.2 Service Data Types See Section 7.7.3.3, for the Network Time TimeType definition.


288

7.12 GeneralInfo Interface Namespace : http://schemas.intel.com/2004/12/management/PC/GeneralInfo Port : http://hostname:port/GeneralInfoService


Local Access √

Network Access √

The GeneralInfo Interface provides general (read only) information for various (local or network access) management applications.

Method Description

GetCoreVersion Reads the firmware version information from the Intel AMT.

GetCodeVersions Reads the BIOS and firmware information from the Intel AMT.

GetProvisioningMode Gets the current provisioning mode.

GetProvisioningState Gets the current provisioning (configuration) state.

GetVlanParameters Gets the VLAN mode and ID used by the Intel AMT device.

GetHostName Gets the host name currently used by the Intel AMT device.

GetConfigServerInfo Gets Configuration Server Information.

GetAdminAclEntryStatus Reads Admin ACL entry status.

GetAdminNetAclEntryStatus Reads remote Network Admin ACL entry status.

GetPasswordModel Gets the BIOS password mode of work.

GetEnabledInterfaces Gets enabled interfaces information.

GetNetworkState Reads network state information for an Intel AMT network connection.

GetSecurityParameters Reads Intel AMT local interface security parameters.

GetIderSessionLog Reads the current IDER session log.


289

7.12.1 Service APIs

7.12.1.1 GetCoreVersion The documentation for this command is covered by the GetCoreVersion() command at the SecurityAdmin Realm.

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetInterfaceVersion, which is defined in the BIOS writer’s documentation.

7.12.1.2 GetCodeVersions

Reads version information from Intel AMT.

Header PT_STATUS GetCodeVersions( [out] string BiosVersion, [out] FirmwareVersionType Versions[]

);


Parameters

BiosVersion

Gives BIOS Version information.

Versions

An array providing firmware version information.


Code Description



Remarks

This routine is used to read BIOS/Firmware version information from Intel AMT.


290

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetCodeVersions, which is defined in the BIOS writer’s documentation.

Returned Versions could be in the form:

Description text Version format

“Flash” XX.YY.ZZZZ where X, Y, Z are decimal digits

Reported in Intel AMT Release 2.0 and Intel Intel AMT Release 1.0.

“Netstack” XX.YY.ZZZZ where X, Y, Z are decimal digits

Reported in Intel AMT Release 2.0and Intel Intel AMT Release 1.0.

“AMTApps” XX.YY.ZZZZ where X, Y, Z are decimal digits

Reported in Intel AMT Release 2.0 and Intel AMT Release 1.0.

“AMT” XX.YY.ZZZZ where X, Y, Z are decimal digits

Reported in Intel AMT Release 2.0.

“Sku” X where X is a decimal digit with the value of: 0 = AMT + ASF + QST SKU 1 = ASF + FSC SKU 2 = FSC SKU For Intel AMT Release 2.5 or later releases, this is a bit combination: 0x2 – iQST 0x4 – ASF 0x8 – AMT For example: 12 = AMT + ASF


“VendorID” Identifier of Vendor ID. For example: “8086” = Intel Corp. “04b3” = IBM Corp.


“Build Number” XXXX Where X is a decimal digit. Describes the build number of the current build:


291

Description text Version format


“Recovery Version” XX.YY.ZZZZ Where X, Y, Z are decimal digits. Describes the version of the recovery partition. The reported version might also be “unknown” if recovery partition update fails.

Reported in Intel AMT Release 2.0

“Recovery Build Num” XXXX Where X is a decimal digit.

Describes the build number of the recovery partition. The reported number might also be “unknown” if recovery partition update fails.

Reported in Intel AMT Release 2.0

“Legacy Mode” “True” or “False”

Indicates whether Intel AMT Release 2.0 (or later) is operating in Intel AMT Release 1.0 Legacy mode. For more information, please refer to Section 10.3

Reported in Intel AMT Release 2.0 or later

7.12.1.3 GetProvisioningMode The documentation for this command is covered by the GetProvisioningMode() command at the SecurityAdmin Realm.

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetProvisioningMode, which is defined in the BIOS writer’s documentation.

7.12.1.4 GetProvisioningState

Reads the provisioning (configuration) state from Intel AMT.

Header PT_STATUS GetProvisioningState( [out] ProvisioningStateType ProvisioningState

);



292

Parameters

ProvisioningState provides configuration state information.


Code Description



Remarks

This routine is used to read the configuration state information from Intel AMT.

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetProvisioningState, which is defined in the BIOS writer’s documentation.

7.12.1.5 GetVlanParameters The documentation for this command is covered by the GetVlanParameters() command at the NetworkAdmin Realm.

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetVlanParameters, which is defined in the PTHI documentation.

7.12.1.6 GetHostName The documentation for this command is covered by the GetHostName() command at the NetworkAdmin Realm.

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetHostName, which is defined in the PTHI documentation.

7.12.1.7 GetConfigServerInfo

Reads the Configuration server information from Intel AMT.

Header PT_STATUS GetConfigServerInfo( [out] IPv4AddressType Ip, [out] uint16 Port

);


293


Parameters

Ip provides the currently defined Ip address of the configuration server.

Port provides the currently defined Port number of the configuration server


Code Description



Remarks

This command is available while configuration is not finished.

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetConfigServerInfo, which is defined in the BIOS writer’s documentation.

7.12.1.8 GetAdminAclEntryStatus

Reads the Admin ACL Entry status from Intel AMT. The return state changes as a function of the admin password. Header PT_STATUS GetAdminAclEntryStatus( [out] boolean IsDefault

);


Parameters

IsDefault is TRUE if the admin ACL entry (admin password) was never changed by the user. Otherwise, the parameter is FALSE. Return Values One of the following status codes MUST be returned by this method:


294

Code Description



Remarks

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetAdminACLEntryStatus, which is defined in the BIOS writer’s documentation.

7.12.1.9 GetAdminNetAclEntryStatus

Reads the remote Admin ACL Entry status from Intel AMT. The return state changes as a function of the remote admin password.

Header PT_STATUS GetAdminNetAclEntryStatus( [out] boolean IsDefault

);


Parameters

IsDefault is TRUE if the remote admin ACL entry (remote admin password) was never changed by the user. Otherwise, the parameter is FALSE. Return Values One of the following status codes MUST be returned by this method:

Code Description



Remarks

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetAdminNetACLEntryStatus, which is defined in the BIOS writer’s documentation.


295

7.12.1.10 GetPasswordModel

Reads Password model information from Intel AMT.

Header PT_STATUS GetPasswordModel( [out] PasswordModelType PasswordModel

);


Parameters

PasswordModel provides the current password model. Return Values One of the following status codes MUST be returned by this method:

Code Description



Remarks

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetPasswordModel, which is defined in the BIOS writer’s documentation.

7.12.1.11 GetEnabledInterfaces The documentation for this command is covered by the GetEnabledInterfaces() command at the SecurityAdmin Realm.

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetSolIderState, which is defined in the BIOS writer’s documentation.

7.12.1.12 GetNetworkState

Reads Network State information from Intel AMT.

Header PT_STATUS GetNetworkState( [out] boolean IsEnabled


296

);


Parameters

IsEnabled is TRUE if the network is in enabled state. Return Values One of the following status codes MUST be returned by this method:

Code Description



Remarks

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetNetworkState, which is defined in the BIOS writer’s documentation.

7.12.1.13 GetSecurityParameters Reads local interface security parameters.

Header PT_STATUS GetSecurityParameters( [out] boolean EnterpriseMode, [out] boolean TlsEnabled, [out] boolean HwCryptoEnabled, [out] ProvisioningStateType ProvisioningState, [out] boolean NetworkInterfaceEnabled, [out] boolean SOLEnabled, [out] boolean IDEREnabled, [out] boolean FWUpdateEnabled, [out] boolean LinkIsUp

);


Parameters

EnterpriseMode


297

Indicates whether Intel AMT operates in Enterprise-mode.

TlsEnabled

Indicates whether TLS authentication is enabled.

HwCryptoEnabled

Indicates whether Intel AMT has hardware crypto is enabled.

ProvisioningState

Provides the current configuration state.

NetworkInterfaceEnabled

Indicates whether the network interface is enabled.

SOLEnabled

Indicates whether Serial Over LAN is enabled.

IDEREnabled

Indicates whether IDE Redirection is enabled.

FWUpdateEnabled

Indicates whether FW Update over HTTP is enabled.

LinkIsUp

Indicates whether the Intel AMT device has a link up on a wired interface.


Code Description



Remarks

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetSecurityParameters, which is defined in the BIOS writer’s documentation.

7.12.1.14 GetIderSessionLog The documentation for this command is covered by the GetIderSessionLog() command at the Redirection Realm.


298

KCS/Intel Management Engine Interface Porting Note: Local applications should use this command instead of CFG_GetIDERSessionLog, which is defined in the BIOS writer’s documentation.


299


7.12.2.1 FirmwareVersionType typedef struct _FirmwareVersionType { string Description; string Version; } FirmwareVersionType; Field Description

Description Description of the firmware version

Version Version information

7.12.2.2 ProvisioningStateType typedef enum<string> _ProvisioningStateType { “ProvisioningStatePre”, “ProvisioningStateIn”, “ProvisioningStatePost” } ProvisioningStateType; Field Description

ProvisioningStatePre “Pre Provisioning” state, or Factory Mode

ProvisioningStateIn “In Provisioning” state, or Setup Mode

ProvisioningStatePost “Post Provisioning” state, or Operational Mode

7.12.2.3 PasswordModelType typedef enum<string> _PasswordModelType { “PasswordModelCoupled”, “PasswordModelSeperate”, “PasswordModelSeperateHash” } PasswordModelType;


300

Field Description

PasswordModelCoupled Coupled password model (the password of the network and the local interfaces are identical)

PasswordModelSeperate Separate password model (the password of the network and the local interfaces are separate)

PasswordModelSeperateHash Separate-Hash password model


301

7.13 FirmwareUpdate Interface Namespace : http://schemas.intel.com/2004/12/management/PC/FirmwareUpdate Port : http://hostname:port/FirmwareUpdateService


Local Access √

Network Access √*

The FirmwareUpdate interface provides various APIs for local or remote firmware updates.

The FirmwareUpdate interface is used only by OEMs via Intel-supplied tools and is not intended for use in ISV applications.

*From Intel AMT Release 2.5 and onwards, this interface is enabled for Local Access only.

Method Description

GetCoreVersion Reads the firmware version information from the Intel AMT device.

GetCodeVersions Reads the code version from the Intel AMT device.

GetFirmwareUpdateState Reads the recent firmware update state.

7.13.1 Service APIs

7.13.1.1 GetCoreVersion The documentation for this command is covered by the GetCoreVersion() command at the SecurityAdmin Realm.

7.13.1.2 GetCodeVersions The documentation for this command is covered by the GetCodeVersions() command at the GeneralInfo Realm.

7.13.1.3 GetFirmwareUpdateState

Gets the recent firmware update state.

Header PT_STATUS GetFirmwareUpdateState( [out] FirmwareUpdateStateType FirmwareUpdateState


302

);


Parameters

The FirmwareUpdateState value reflects the state of the recent firmware update.


Code Description



Remarks

This call may be used by the firmware update tool to retrieve the progress and state information of the firmware update process.

7.13.1.4 HTTP File Upload Interface


Remarks

HTTP File upload interface is used to upload a new and signed Intel AMT Firmware image. Image uploads should be directed to the “/IntelAMTFirmwareUpdate” URI after performing the required HTTP authentication. File uploads should be done according to the HTTP1.1 specification. The supported MIME type for file upload is “Content-Type: application/octet-stream”, further information may be found in RFC 1867.

Note: When Intel AMT is configured to disable Firmware update from the BIOS, an HTTP 404 “Not Found” error will be returned when trying to access the “/IntelAMTFirmwareUpdate” URI.



303

7.13.2.1 FirmwareUpdateStateType typedef enum<string> _FirmwareUpdateStateType { “FirmwareStatusSuccess”, “FirmwareUpdateRejectedSkuFailure”, “FirmwareUpdateRejectedVersionFailure”, “FirmwareUpdateRejectedSignatureFailure”, “FirmwareUpdateRejectedGeneralFailure”, “FirmwareLoadingImage”, “FirmwareAuthenticatingImage”, “FirmwareProcessing”, “FirmwareUpdatingCodePartition”, “FirmwareUpdatingRecoveryPartition”, “FirmwareFlashPartitionCodeInvalid”, “FirmwareFlashPartitionRecoveryInvalid” } FirmwareUpdateStateType;

Field Description

FirmwareStatusSuccess

Recent Firmware update completed successfully. This is also the value returned when a firmware update was not performed and there are no problems with the current firmware image.

FirmwareUpdateRejectedSkuFailure Recent firmware update rejected, Sku does not match.

FirmwareUpdateRejectedVersionFailure Recent firmware update rejected, Version does not match.

FirmwareUpdateRejectedSignatureFailure Recent firmware update rejected, Signature does not match.

FirmwareUpdateRejectedGeneralFailure Recent firmware update rejected (general internal failure).

FirmwareLoadingImage Firmware currently loading.

FirmwareAuthenticatingImage Firmware currently authenticating image.

FirmwareProcessing Firmware processing image.

FirmwareUpdatingCodePartition Firmware is currently updating the code partition.

FirmwareUpdatingRecoveryPartition Firmware is currently updating the recovery partition.

FirmwareFlashPartitionCodeInvalid Firmware update failure, the code partition is invalid.Firmware update tool may be retried only from the local host.

FirmwareFlashPartitionRecoveryInvalid

Firmware update failure, the recovery partition is invalid. Firmware update tool may be retried from the network (not applicable to Release 2.5 or greater), or from the local host.


304

7.14 EIT Interface Namespace : http://schemas.intel.com/2004/12/management/PC/EIT Port : http://hostname:port/EITService


Local Access √

Network Access -

The EIT interface is used only by Embedded IT service and is not intended for use in ISV applications.

Method Description

ReadBuff Read buffer from a specified region.

WriteBuff Write buffer to a specified region.

7.14.1 Service APIs

7.14.1.1 ReadBuff

Read buffer from a specified region. Header PT_STATUS ReadBuff( [in] EitRegionType Region, [in] uint32 Offset, [in] uint32 Length, [out] BinaryData Data );

Compatibility This routine is supported by Intel AMT Release 2.0/2.1 and Intel AMT Release 3.0.

Parameters

Region Specifies the region to be read from (A or B).

Offset Offset in bytes from the beginning of region.

Length


305

Length of the buffer to be read in bytes.

Data A returned data buffer. The length of the data buffer indicates actual bytes read.


Code Description



PT_STATUS_NOT_PERMITTED Access to the specified region is not permitted.

PT_STATUS_INVALID_PARAMETER Input parameter is invalid (region or offset)

Remarks

Access to region A is currently disabled for all interfaces, this may be enabled by future versions when authenticating through a dedicated Realm.

7.14.1.2 WriteBuff

Writes buffer to a specified region.

Header PT_STATUS WriteBuff( [in] EitRegionType Region, [in] uint32 Offset, [in] BinaryData Data

);

Compatibility This routine is supported by Intel AMT Release 2.0/2.1 and Intel AMT Release 3.0.

Parameters

Region Specifies the region to be read from.

Offset Offset in bytes from the beginning of region.


306

Length Length of the buffer to be written in bytes.

Data A returned data buffer. The length of the data buffer indicates actual bytes read.


Code Description



PT_STATUS_NOT_PERMITTED Access to the specified region is not permitted.


Input parameter is invalid (region, offset, or length exceeds boundary of region)

Remarks

Access to region A is currently disabled for all interfaces, this may be enabled by future versions when authenticating through a dedicated Realm.


7.14.2.1 EitRegionType typedef enum<uint32> _EitRegionType { RegionA = 0, RegionB = 1 } EitRegionType;

Code Description

RegionA Region A (reserved for future use)

RegionB Region B


307

7.15 Wireless Configuration Interface Namespace : http://schemas.intel.com/2004/12/management/PC/WirelessConfiguration Port : http://hostname:port/WirelessConfigurationService


Local Access -

Network Access √

The WirelessConfiguration interface is used for embedding wireless profiles into Intel AMT as well as for reading general wireless configuration settings.

Although this interface operates on a dedicated URI, it enforces access permissions as in the NetworkAdmin Interface.

Method Description

AddWirelessProfile Adds a new wireless profile to the Intel AMT device

GetWirelessProfile Retrieves a wireless profile based on the profile name

RemoveWirelessProfile Deletes a wireless profile

UpdateWirelessProfile Modifies the settings of an existing wireless profile

EnumerateWirelessProfiles Retrieves the the names of the defined wireless profiles

GetWirelessCapabilities Returns the 802.11 subparagraph capabilities of the wireless interface

GetWirelessSettings Identifies the active wireless profile and whether the wireless interface is active

7.15.1 Service APIs

7.15.1.1 AddWirelessProfile

This command adds a new wireless profile to the store of profiles in the Intel AMT device. Header PT_STATUS AddWirelessProfile(

[in] ProfileType Profile );


308


Parameters

Profile

A profile descriptor.


Code Description




PT_STATUS_DUPLICATE A profile with this name already exists

PT_STATUS_INVALID_PRIORITY A profile with the same priority already exists or priority not in range.

PT_STATUS_UNSUPPORTED Specified profile is not supported (usually returned if EAP GTC was specified).

PT_STATUS_MAX_LIMIT_REACHED Not enough space

PT_STATUS_INVALID_CERT Invalid certificate handle

PT_STATUS_INVALID_PASSPHRASE Invalid passphrase (see type definition)

PT_STATUS_INVALID_CREDENTIALS Invalid credentials (see type definition)

PT_STATUS_INVALID_PARAMETER Input parameter is invalid (general error, in case schema validation was not used).

Remarks

Since the name of the profile uniquely identifies the profile, it should not be possible to add two profiles with an identical name.

7.15.1.2 GetWirelessProfile

This command retrieves a profile from the Intel AMT device store based on profile name.


309

Header PT_STATUS GetWirelessProfile(

[in] ProfileNameType ProfileName, [out] ProfileType Profile );


Parameters

ProfileName

A Profile name to be read

Profile

A returned profile


Code Description



PT_STATUS_INVALID_PARAMETER Profile could not be found or profile name is invalid

Remarks

Confidential information such as keys and passwords are not returned by the Get operation.

7.15.1.3 RemoveWirelessProfile

This command deletes an existing profile from the Intel AMT device wireless profile store. Header PT_STATUS RemoveWirelessProfile(

[in] ProfileNameType ProfileName );



310

Parameters

ProfileName

Name of the profile to be deleted


Code Description



PT_STATUS_NOT_FOUND Profile name was not found.

PT_STATUS_NOT_PERMITTED The specified profile is active and cannot be deleted.

Remarks

Removing a wireless profile should de-reference internal locked dependent entities (possibly referenced in 802.1X configuration certificate handles).

Removing a profile should succeed regardless of the flash wear-out state.

7.15.1.4 UpdateWirelessProfile

This command is used to revise an existing wireless profile. Header PT_STATUS UpdateWirelessProfile(

[in] ProfileType Profile );


Parameters

Profile

The name of an existing wireless profile


311


Code Description




PT_STATUS_NOT_FOUND Profile name was not found.

PT_STATUS_INVALID_PRIORITY A profile with the same priority already exists

PT_STATUS_NOT_PERMITTED The specified profile is active and cannot be modified.

PT_STATUS_UNSUPPORTED Specified profile is not supported (usually returned if EAP GTC was specified).

PT_STATUS_INVALID_CERT Invalid certificate handle

PT_STATUS_INVALID_PASSPHRASE Invalid passphrase (see type definition)

PT_STATUS_INVALID_CREDENTIALS Invalid credentials (see type definition)

PT_STATUS_INVALID_PARAMETER Input parameter is invalid (general error, in case schema validation was not used).

Remarks

If the device is connected through an active profile, an update is not possible. Similarly, deletion of an active profile is not allowed. In case of an update error, the previous profile name should not be changed.

7.15.1.5 EnumerateWirelessProfiles

This command returns a list of the wireless profile names in the Intel AMT device store. Header PT_STATUS EnumerateWirelessProfiles(

[out] ProfileNameType ProfileNames[] );



312

Parameters

ProfileNames

A returned list of currently configured profile names.


Code Description



7.15.1.6 GetWirelessCapabilities

This command returns the 802.11-defined modulation techniques that the wireless interface supports. Header PT_STATUS GetWirelessCapabilities(

[out] WirelessCapabilitiesType WirelessCapabilities );


Parameters

WirelessCapabilities

Wireless capabilities descriptor


Code Description




313

7.15.1.7 GetWirelessSettings

This command returns the current active profile and whether the radio in the interface is on or not. Header PT_STATUS GetWirelessSettings(

[out] WirelessSettingsType WirelessSettings );


Parameters

WirelessSettings

Wireless settings descriptor


Code Description



7.15.2 Type definitions

7.15.2.1 ProfileType

typedef struct {

ProfileNameType ProfileName ; ProfilePriorityType Priority ; [optional] BinaryData SSID ; ProfileSecuritySettingsType Security ;

} ProfileType ;

Field Description

ProfileName Profile name


314

Priority Profile priority. Profile priorities must be unique among the defined profiles on an Intel AMT device

SSID Service Set Identifier: A 1 to 32 character string used as a WLAN identifier

Security Specifies the encryption and authentication mechanisms and parameters

7.15.2.2 ProfileNameType

typedef string ProfileNameType ;

Remarks

String with minimum length of 1 character, maximum length of 35 characters. The string cannot contain these characters: \ / : * ? < > | "

7.15.2.3 ProfilePriorityType

typedef uint8 ProfilePriorityType ;

Remarks

Valid range is 0-255

7.15.2.4 ProfileSecuritySettingsType

typedef struct {

choice { ProfileSecuritySettingWPAType WPA ; ProfileSecuritySettingRSNType RSN ;

};

} ProfileSecuritySettingType ;

Field Description

WPA Specifies encryption and authentication used with WPA key management.

RSN Specifies encryption and authentication used with RSN key management.


315

7.15.2.5 ProfileSecuritySettingWPAType

typedef struct {

choice { DataEncryptionTKIPType DataEncryptionTKIP ; DataEncryptionCCMPType DataEncryptionCCMP;

};

} ProfileSecuritySettingWPAType ;

Field Description

DataEncryptionTKIP Specifies authentication used with TKIP encryption

DataEncryptionCCMP Specifies authentication used with CCMP encryption

7.15.2.6 ProfileSecuritySettingRSNType

typedef struct {

choice { DataEncryptionTKIPType DataEncryptionTKIP ; DataEncryptionCCMPType DataEncryptionCCMP;

};

} ProfileSecuritySettingRSNType ;

Field Description

DataEncryptionTKIP Specifies authentication used with TKIP encryption

DataEncryptionCCMP Specifies authentication used with CCMP encryption

7.15.2.7 DataEncryptionTKIPType

typedef struct {

choice { PassPhrase63Type PassPhrase ; RawKey256Type RawKey ; XProfileType XProfile ;


316

};

} DataEncryptionTKIPType ;

Field Description

PassPhrase

8 to 63-character passphrase.

Contains 7-bit ASCII characters, in the range of 32-126, excluding ‘:’, ‘,’ and ‘”’ characters.

Limitations:

Passphrase Complexity: Passphrase must include:




RawKey 256 bit key

XProfileHandle 802.1X profile

Remarks

Specifies the authentication mechanism to be used with TKIP encryption.

7.15.2.8 DataEncryptionCCMPType

typedef struct {

choice { PassPhrase63Type PassPhrase ; RawKey256Type RawKey ; XProfileType XProfile ;

};

} DataEncryptionCCMPType ;


317

Field Description

PassPhrase

8 to 63-character passphrase.


Limitations:





RawKey 256 bit key

XProfileHandle 802.1X profile

Remarks

Specifies the authentication mechanism to be used with CCMP encryption.

7.15.2.9 PassPhrase63Type

typedef string PassPhrase63Type ;

Remarks A string of length 8 to 63 characters.


Limitations:





7.15.2.10 RawKey256Type

typedef BinaryData RawKey256Type ;


318

Remarks

A 32 byte buffer representing a 256 bit key.

7.15.2.11 WirelessCapabilitiesType

typedef struct { FeatureType SupportedFeatures[] ; } WirelessCapabilitiesType ;

Field Description

SupportedFeatures A list of supported features

7.15.2.12 FeatureType

typedef enum<string> { "802.11a", "802.11b", "802.11g", "802.11n", } FeatureType ;

Field Description

802.1a 802.1a is supported

802.1b 802.1b is supported

802.1g 802.1g is supported

802.1n 802.1n is supported

7.15.2.13 WirelessSettingsType

typedef struct { boolean RadioOn ;


319

string ActiveProfile ;

} WirelessSettingsType ;

Field Description

RadioOn Indicates whether the Radio is enabled or disabled

ActiveProfile Specifies the active profile (Null if unknown).


320

7.16 Endpoint Access Control Admin Interface Namespace : http://schemas.intel.com/platform/client/EACAdmin/2006/01 Port : http://hostname:port/EndpointAccessControlAdminService


Local Access −

Network Access √

The EAC Admin interface is used to remotely configure and manage the Endpoint Access Control Admin capabilities.

Method Description

SetPostureSigner Identifies the certificate used to sign postures.

GetPostureSigner Returns a handle for the certificate used to sign postures.

GetEACStatus Returns the enabled/disabled status of the local EAC capability.

EnableEAC Enables the local EAC capability.

UpdatePostureState Tells the Intel AMT device to reset its boot counters.

7.16.1 Service APIs

7.16.1.1 SetPostureSigner

This command identifies the certificate to be used to sign EAC postures in response to a GetPosture request. Header PT_STATUS SetPostureSigner(

[in, optional] CertificateHandleType SignCertificateHandle );


Parameters

SignCertificateHandle


321

Handle to a certificate with a key pair. If this parameter is Null, the previous certificate will be disassociated from this feature and can be removed later.


Code Description




PT_STATUS_INVALID_PARAMETER Certificate handle is invalid or Corresponding Private Key not found

PT_STATUS_NOT_PERMITTED Caller can not disassociate a certificate while the feature is enabled.

Remarks

This API is used to associate or disassociate a certificate with matching key pair to the EAC feature.

7.16.1.2 GetPostureSigner

This command retrieves the handle of the certificate associated with the EAC posture feature. Header PT_STATUS GetPostureSigner(

[out] 9CertificateHandleType SignCertificateHandle );


Parameters

SignCertificateHandle

Handle to key pair.



322

Code Description



7.16.1.3 GetEACStatus

This command is identical to the command defined in the EAC interface.

7.16.1.4 EnableEAC

This command is used to enable or disable the local interface EAC capability. Header PT_STATUS EnableEAC(



Parameters

Enabled

State of the EAC feature


Code Description




PT_STATUS_NOT_PERMITTED Can not enable EAC as a signing certificate was not set (using SetPostureSigner() )

Remarks


323

Enables or disables the NAC feature

7.16.1.5 UpdatePostureState

This command tells the Intel AMT device to reset its boot counters. Header PT_STATUS UpdatePostureState(

[in] PostureUpdateType PostureUpdate, );


Parameters

PostureUpdate

Posture update type definition.


Code Description





7.16.2.1 PostureUpdateType typedef enum <string> {

PostureUpdateBootCounters } PostureUpdateType;

Field Description

PostureUpdateBootCounters Intel AMT should reset its internal boot counter state.


324


325

7.17 Endpoint Access Control Interface Namespace : http://schemas.intel.com/platform/client/EAC/2006/01 Port : http://hostname:port/EndPointAccessControlService


Local Access √

Network Access −

This section defines the functionality that supports Endpoint Access Control capabilities. It is a read-only local interface.

Method Description

GetEACStatus Returns the enabled/disabled state of the EAC capability.

GetPosture Returns an encrypted posture of the Intel AMT device.

GetPostureHash Returns a hash of the current posture.

7.17.1 Service APIs

7.17.1.1 GetEACStatus

This command returns the enabled/disabled status of the local EAC interface. Header PT_STATUS GetEACStatus(



Parameters

Enabled

State of the EAC feature.



326

Code Description



Remarks

If EAC is not enabled, the GetPosture and GetPostureHash commands will fail.

7.17.1.2 GetPosture

This command returns posture information interpretable by a properly configured NAC device. Header PT_STATUS GetPosture(

[in] PostureTypeType PostureType, [out] 9BinaryData SignedPosture, [out] BinaryData PostureChangeHash );


Parameters

PostureType

Posture type definition.

SignedPosture

Buffer representation of a Digital Signature document that contains Signed NAC Posture information.

PostureChangeHash

A computed hash value over the posture data (fields such as “current time” are omitted).

This hash can be used to check if the posture was changed, by comparing to the last computed hash value.



327

Code Description



PT_STATUS_NO_ASSOCIATION Need to associate a key pair with signing Key pair handle using SetPostureSigner().

Remarks

This API is operable only from the local interface.

7.17.1.3 GetPostureHash

This command returns only the hash of the current posture. Header PT_STATUS GetPostureHash(

[in] PostureTypeType PostureType, [out] BinaryData PostureChangeHash );


Parameters

PostureType

Posture type definition.

PostureChangeHash

A computed hash value over the posture data (fields such as current time are omitted).


Code Description




328

PT_STATUS_NO_ASSOCIATION Need to associate a key pair with signing Key pair handle using SetPostureSigner().

Remarks

This hash can be used to check if the posture was changed, by comparing to the last computed hash value.


7.17.2.1 PostureTypeType

typedef enum <string> { PostureAvpTypeFull

} PostureTypeType;

Field Description

PostureAvpTypeFull Full posture information type.


329

7.18 User Notification Interface Namespace : http://schemas.intel.com/platform/client/UserNotification/2006/01 Port : http://hostname:port/UserNotificationService


Local Access √

Network Access −

The User Notification Interface exposes user notification registration functionality for local applications. This capability applies to Intel AMT Releases 2.5 and 3.0.

Method Description

SubscribeForGeneralAlert See corresponding section in Event Manager Interface

EnumerateGeneralAlertSubscriptions See corresponding section in Event Manager Interface

GetGeneralAlertSubscription See corresponding section in Event Manager Interface

CancelAlertSubscription See corresponding section in Event Manager Interface

7.18.1 Service APIs

7.18.1.1 SubscribeForGeneralAlert See SubscribeForGeneralAlert in Event Manager Interface

7.18.1.2 EnumerateGeneralAlertSubscriptions See EnumerateGeneralAlertSubscriptions in Event Manager Interface

Remarks

Although this command is similar to the Event Manager Interface EnumerateGeneralAlertSubscriptions command, it will not return legacy subscriptions.

7.18.1.3 GetGeneralAlertSubscription See GetGeneralAlertSubscription in Event Manager Interface

7.18.1.4 CancelAlertSubscription See CancelAlertSubscription in Event Manager Interface


330

7.18.2 Client Initiated APIs See corresponding chapter in Event Manager Interface

7.18.3 Type definitions See corresponding chapter in Event Manager Interface

8 Common Data Types This section describes the data types used by the Intel AMT Network interface.


331

8.1 General data structures

8.1.1 INVALID_HANDLE This value constitutes and invalid handle for every handle type in the system.

#define INVALID_HANDLE (UINT32) 0xFFFFFFFF

8.1.2 PT_STATUS typedef enum<UINT32> _PT_STATUS { PT_STATUS_SUCCESS = 0x0, PT_STATUS_INTERNAL_ERROR = 0x1, PT_STATUS_INVALID_PT_MODE = 0x3, PT_STATUS_INVALID_NAME = 0xC, PT_STATUS_INVALID_BYTE_COUNT = 0xF, PT_STATUS_NOT_PERMITTED = 0x10,

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_NETWORK_IF_ERROR_BASE = 0x800, 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, PT_STATUS_INVALID_PASSPHRASE = 0x816,


332

PT_STATUS_NO_ASSOCIATION = 0x818, } PT_STATUS;

Code Description

PT_STATUS_SUCCESS Operation completed successfully.

PT_STATUS_INTERNAL_ERROR An internal error occurred while performing the operation.

PT_STATUS_INVALID_PT_MODE Specified mode of operation is invalid.

PT_STATUS_INVALID_NAME Specified name is invalid.

PT_STATUS_INVALID_BYTE_COUNT Specified byte count invalid.

PT_STATUS_NOT_PERMITTED Operation not permitted.

PT_STATUS_MAX_LIMIT_REACHED No available storage in the specified structure.

PT_STATUS_INVALID_AUTH_TYPE Specified Key algorithm is invalid.

PT_STATUS_INVALID_DHCP_MODE Specified DHCP mode is invalid.

PT_STATUS_INVALID_IP_ADDRESS Specified IP address is invalid.

PT_STATUS_INVALID_DOMAIN_NAME Specified Domain name is invalid.

PT_STATUS_INVALID_PROVISIONING_STATE Specified provisioning state is not valid.

PT_STATUS_INVALID_TIME Specified time is not valid.

PT_STATUS_INVALID_INDEX Specified index is not valid.

PT_STATUS_INVALID_PARAMETER Invalid input parameter.

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_NETWORK_IF_ERROR_BASE The status codes before this one are common to both the Host interface and Network interface.

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

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

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


333

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_HANDLE The handle specified in the command is invalid.

PT_STATUS_INVALID_PASSWORD The password specified in the User ACL is invalid.

PT_STATUS_INVALID_REALM The realm specified in the User ACL is invalid.

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_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_PKI_MISSING_KEYS Reserved for future use.

PT_STATUS_PKI_GENERATING_KEYS Reserved for future use.

PT_STATUS_INVALID_KEY Invalid RSA Key

PT_STATUS_INVALID_CERT Invalid X.509 Certificate or invalid certificate handle

PT_STATUS_CERT_KEY_NOT_MATCH Key pair does not match


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_UNSUPPORTED Setting is not supported by this product

PT_STATUS_INVALID_PRIORITY Priority setting is invalid

PT_STATUS_NOT_FOUND Unable to find specified element

PT_STATUS_INVALID_CREDENTIALS Invalid User credentials

PT_STATUS_INVALID_PASSPHRASE Passphrase is invalid

PT_STATUS_NO_ASSOCIATION Need to associate a key pair with signing Key pair handle

8.1.3 IPv4AddressType typedef uint32 IPv4AddressType;


334

Field Description

IPv4AddressType An IPv4 address. Addresses are maintained per [IP] definition i.e. value: 0x01020304 IP Address: 1.2.3.4

8.1.4 BinaryData This type represents a sized binary array. This definition is similar to the usage of base64Binary elements in XML schemas which may be used when defining respective SOAP functionality.

The Intel AMT device is capable of sending Event (IPMI Platform Event Trap) events to report various events to a Management console. The following section details the various fields on each PET type, please refer to the PET specification listed in the Reference Documents.

8.1.5 URL typedef string URL;

Where URL is a string with a Host Name or IP address, Port(optional) and URI (optional)

For example: - HTTP://IPv4Address:port/Uri - HTTP://host/Uri - HTTP://host:port/Uri - HTTPS://host:port/Uri

If no port is specified: - HTTP should work over port 80 - HTTPS should work over port 443

Note: currently, only "localhost" host name or "127.0.0.1" IPv4 address is supported, Any other host names may return an error.

8.1.6 NodeAddressType typedef struct {

choice { string HostName ; string IPv4Address ; string IPv6Address ; };

} NodeAddressType;


335

Remarks - Hostname – currently unsupported but kept for future compatibility. - IPv6

A standard string representation of an IPv6 address (according to RFC 2373, section 2.2). examples:

o “0102:0304:0506:0708:0A01:0A02:0A03:0A04” o “0102:0304:0506:0708:0A01:0A02:1.2.3.4”

- IPv4 A standard string representation of an IPv4 address. examples:

o “123.143.22.11”

9 Self Generated Platform Event Trap Definitions This section reviews the Platform Event Traps which may be generated by an Intel AMT device or components.

The section does not cover other platform events which may be generated by other components or sensors of the platform (for example: sensor polling events and BIOS push messages).


336

9.1 Link Up Event Compatibility This event is supported by Intel AMT Release 1.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 27h (LAN)

Event Type 0Ah (Discrete)

Event Offset 03h (Trans. To Online)

Variable Binding Info

Event Source Type 68h (ASF 1.0)

Event Severity 01h (Monitor)

Sensor Device FFh (NS)

Sensor Number 02h

Entity 26h (Mgmt Device)

Entity Instance 61h (port #1 (LAN port))

EventData[1...8] {} Remarks

This Event is sent to all Event subscribers that specified a matching Event Filter. This Event is NEVER logged regardless of any Event Filter state.


337

9.2 Watchdog Events

9.2.1 Default Watchdog Event Compatibility This event is supported by Intel AMT Release 1.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 23h (WD 2)

Event Type 6Fh (Sensor Specific)

Event Offset 00h (Timer Expired)



Event Severity 10h (Critical)


Sensor Number FFh (NS)

Entity 00h

Entity Instance 00h (NS)

EventData[1...8] 40h (ED2 valid), 06h (Boot Failure)

Remarks

This Event is sent to all Event subscribers that specified a matching Event Filter. This Event is logged depending on the Event Filter configuration.

9.2.2 OS Hang Watchdog Event Compatibility This event is supported by Intel AMT Release 1.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 20h (OS Critical stop)


338


Event Offset 01h (Run-time stop)






Entity 23h (OS)

Entity Instance 61h (#1)

EventData[1...8] {} Remarks



339

9.3 Password Attack Event Compatibility This event is supported by Intel AMT Release 1.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 06h (Platform Security Violation attempt)


Event Offset 05h (Password violation)






Entity 26h (Remote (Out of Band) Management Communication Device)

Entity Instance 61h (#1)

EventData[1...8] AAh (ED2-5 valid), NN (Attack counter), NN (Attack counter), NN (Attack counter), NN (Attack counter)

Remarks



340

9.4 Circuit Breaker Event Compatibility This event is supported by Intel AMT Release 2.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 24h (Platform Alert)


Event Offset 01h (Platform generated LAN alert)


Event Source Type 58h (System MNG card)





Entity Instance 61h (port #1 (LAN port)) or 62h (port #1 (WLAN port))

EventData[1...8] AAh (ED2-5 valid), Bytes 2..5 contains a network order representation of the uint32 handle of the Circuit Breaker filter

Remarks



341

9.5 Agent Presence Event Compatibility This event is supported by Intel AMT Release 1.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 12h (System Event)


Event Offset 00h (System Reconfigured)








EventData[1...8] AAh (ED2-5 valid) Bytes 2..7 contain the truncated UUID of the agent being reported.

Byte 8 contains the state of the agent after the transition (NotStarted= 0x01, Stopped= 0x02, Running= 0x04, Expired= 0x08, Suspended= 0x10)

Remarks



342

9.6 Firmware Update Event Compatibility This event is supported by Intel AMT Release 1.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 26h (MNG subsystem health)

Event Type 01h (Generic)

Event Offset 00h








EventData[1...8] AAh (ED2-5 valid), NN (Update status), NN (Update status), NN (Update status), NN (Update status)

Remarks


9.6.1 Update Status Structure This section defines the format of the FWUpdate structure that resides in the first 4 bytes of the Event Data field of a PET packet.

#Byte Name Bits Description

0 Status 0-3 Status of last running, see Section 9.6.2.

0 Changed flash

4 When set to 1 the flash device was changed by the firmware update.

0 Active application

5-6 Active application update:


343


update 00 = no update. 10 = application A 11 = application B

For Intel AMT Release 2.0 and on, this value should be 0b11.

0 Reserved 7 Reserved

1 Step 0-3 Last step executed. This is a 1-based counter. The value 0 means no step has been successfully executed (Used only by Intel AMT Release 1.0).

1 Failure counter

4-7 Counts number of failures of next step (Used only by Intel AMT Release 1.0).

2 Failure reason

0-3 See Section 9.6.3

2 Failure sub-reason

4-7 See Section 9.6.3

3 Bad file number

0-7 The numeric value of the bad step file (if the failure reason indicates a corrupted step file), or fragment file (if the reason is a corrupted fragment file). The value of this field will be 0 for other failure reasons (Used only by Intel AMT Release 1.0).

Table 1 – Firmware update status structure

9.6.2 Update Status Codes This section defines the valid status code that can appear in a PET’s firmware update status structure, in the status field.

Name Description

2 Success The firmware loader has finished loading all fragments of the new image. No errors occurred.

3 Partial Partial completion, actual step is spelled out in the status indication. For Intel AMT Release 1.0 - Magic packet is needed to resume.

4 Failure Failure, no change in loadable flash area. No need of magic packets.

Table 2 – Firmware update status indication

9.6.3 Update Failure Reason Codes This section defines the valid failure reason codes that can appear in a PET Firmware Update status structure, in the failure reason and failure sub-reason fields.


344

Valid failure reasons:

ID Description Sub-reason

0 Reserved N/A

1 DHCP failure N/A (Used only by Intel AMT Release 1.0)

0 Name Server was unable to perform query

1 Domain name does not exist

2 No answer from the name server

3 An error occurred with one or more of the socket calls within the function.

2 DNS failure (Used only by Intel AMT Release 1.0)

4 Error in parameters (Invalid host name string or IP pointer)

0 A session is already in progress. Only one session may be in progress at a time.

1 The buffer is not large enough to hold the received file.

2 An error occurred with one or more of the socket calls within the function.

3 Error in parameters (Error in file type or blocking mode)

4 Undefined error code

5 File not found

6 Access violation

3 TFTP failure (Used only by Intel AMT Release 1.0)

7 Invalid TFTP operation

0 Bad magic

1 Bad signature

4 Corrupted content file

(Used only by Intel AMT Release 1.0)

2 Bad versions info


345


3 Mismatch between conf and content about HMAC usage.

4 Invalid steps number (over the maximal allowed).

5 ROM/stack firmware version out of range.

6 Invalid content file size.

0 Bad magic

1 Bad signature

2 Bad versions info

3 Step file number mismatches with step file content

5 Corrupted step file (Bad File Number field indicates number of corrupted step file)


4 Invalid step file size

0 Bad magic

1 Bad signature

2 Bad versions info

3 Fragment file number mismatches with fragment file content

4 Fragment payload size is over the maximal allowed (64K)

5 Fragment pointer not sector (4KB) aligned.

6 Invalid fragment file size

6 Corrupted fragment file (Bad File Number field indicates number of corrupted fragment file)


7 Fragment write to flash failed

0 Update rejected – Sku failure.

1 Update rejected – Version failure.

7

Failed to update image (Used only by Intel AMT Release 2.0)

2 Update rejected – Signature Failure.


346


3 Update rejected – General Failure.

4 Update failure – Code partition invalid.

5 Update failure – Recovery partition invalid.

8-15 Reserved Reserved

Table 3 – Firmware update failure codes


347

9.7 Network Adapter State Tampered Compatibility This event is supported by Intel AMT Release 2.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 26h (MNG subsystem health)


Event Offset 00h







Entity Instance 61h (port #1 (LAN port))

EventData[1...8] {40h, 01, 00, 00, 00, 00, 00, 00} or

{40h, 00, 00, 00, 00, 00, 00, 00}

or {40h, 02, 00, 00, 00, 00, 00, 00}

Remarks

This Event is sent when the Intel AMT subsystem recognizes malicious software running on the host attempting to sabotage health of the Intel AMT device in order to disconnect Intel AMT or the host from the enterprise network.

When EventData[1] equals to 0, the Event indicates that the host software is trying to sabotage the link but Intel AMT was able to restore it.

When EventData[1] equals to 1, the Event indicates that the host software tried to sabotage the link 5 times in an hour time frame. This indicates that Intel AMT blocked the host from connecting to the network in order to prevent the malicious software from continuing to tamper with the link (Intel AMT will still be able to connect to the network). The IT administrator may perform a platform reset (manually or through RCO commands) in order to restore the link to the host, after inspecting the tampering software.

When EventData[1] equals to 2, the Event indicates that the Intel AMT was not able to maintain its Protected Clock as the user may have removed the battery or caused a Flash wear out while


348

the BIOS time was changed too many times. In this case the the IT administrator is advised to reset the Flash wear out protection and set the Intel AMT time again, after inspecting the tampering software. This Event is sent to all Event subscribers that specified a matching Event Filter. This Event is logged depending on the Event Filter configuration.


349

9.8 Bringup Events

9.8.1 CPU Missing Event Compatibility This event is supported by Intel AMT Release 2.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 07h (Processor)


Event Offset 04h (FRB3/Processor Startup/Initialization failure (CPU didn’t start))


Event Source Type 68h (ASF1.0 Implementation)




Entity 09h (Processor module)

Entity Instance 60h (for instance #0), 61h (for instance #1), …

EventData[1...8] {00, 00, 00, 00, 00}

Remarks

This Event is sent to all Event subscribers regardless of any Event Filter state. This Event is logged regardless of any Event Filter state.

9.8.2 CPU Dead On Arrival Event Compatibility This event is supported by Intel AMT Release 2.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 07h (Processor)


Event Offset 03h (FRB2/Hang in POST failure (used hang is believed to be due or related to a processor failure. Use System


350

Firmware Progress sensor for other BIOS hangs.)






Entity 03h (Processor)

Entity Instance 60h (for instance #0), 61h (for instance #1), …

EventData[1...8] {00, 00, 00, 00, 00}

Remarks


9.8.3 DIMM Missing or Not Functional Event Compatibility This event is supported by Intel AMT Release 2.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 0Fh (System Firmware Error or Progress)


Event Offset 00h (System Firmware Error)






Entity 32d (Memory Device)

Entity Instance 60h (for instance #0)

EventData[1...8] {40h, 01h}


351

Remarks


9.8.4 BIOS Hang Event Compatibility This event is supported by Intel AMT Release 2.0 and later releases.

Trap Definition

Specific Trap Info

Event Sensor Type 0Fh (System Firmware Error or Progress)


Event Offset 01h (System Firmware Hang (uses same Event Data 2 definition as following System Firmware Progress offset)






Entity 00h (Unspecified)

Entity Instance 26h (Remote OOB MGMT)

EventData[1...8] {40h, 01h}

Remarks

This event is sent when the BIOS hangs prior to / during memory initialization (BIOS flash corruption).



352

9.9 Circuit Breaker Heuristics notification Compatibility This event is supported by Intel AMT Release 3.0.

Trap Definition

Specific Trap Info

Event Sensor Type 06h (Platform Security Violation attempt)


Event Offset 0Ah (Unallocated – Network analysis module)







Entity Instance 61h (port #1 (LAN port)) or 62h (port #1 (WLAN port))

EventData[1...8] AAh (ED2-5 valid), NN (Report state, byte #0), NN (Report state, byte #1), NN (Report state, byte #2), NN (Report state, byte #3)

9.9.1 Report state

This section defines the format of the Report state structure that resides in the first 4 bytes of the Event Data field of a PET packet.


0 Version 0-3 Must be zero

0 Reason 4-7 0h – Slow threshold trespassed.


353


1h – Fast threshold trespassed. 2h – Factory defined threshold trespassed. 3h – Encounter timeout expired (system clean) … - Reserved

1 Action 0-5 0b000001 – Blocked all Transmit ports. 0b000010 – Blocked offending port (TCP). 0b000100 – Blocked offending port (UDP). 0b001000 – Enabled preconfigured CB policy. 0b010000 – Removed restricting filters. … – Reserved.

1 Reserved 6-7 Reserved

2 Additional Info

0-7 If Action is 0b000010 or 0b000100 then this field contains the MSB (8 bits) of the offending port.

3 Additional Info

0-7 If Action is 0b000010 or 0b000100 then this field contains the LSB (8 bits) of the offending port.

Table 4 – CB Heuristics state structure


354

9.10 User Notification Alert Compatibility This event is supported by Intel AMT Release 2.5.

Trap Definition

Specific Trap Info

Event Sensor Type C0h (OEM Reserved – User Notification)

Event Type 70h (OEM Discrete – User notification)

Event Offset 00h



Event Severity 02h (Information)




Entity Instance 61h (port #1 (LAN port)) or 62h (port #1 (WLAN port)) or 00h (NS)

EventData AAh (ED2-5 valid), NN (Report state, byte #0), NN (Report state, byte #1), NN (Report state, byte #2), NN (Report state, byte #3)

Remarks

A local service that wishes to receive a user notification alert should subscribe for an alert with a PolicyID field equal to 0x86.

9.10.1 Report state

This section defines the format of the Report state structure that resides in the following data bytes of the Event Data field of a PET packet.


355



0 Reason 4-7 0h – General Notification 1h – Circuit Breaker notification. 2h – EAC notification. (Reserved). 3h – Remote diagnostics. 4h – WLAN notification. 5h… Fh – Reserved.

1-3 Reason Info Data formatted according to Reason code

Reason Info for General Notification structure (Reason = 0)


0 Notification Code

0-7 Reserved



Reason Info for Circuit Breaker structure (Reason = 1)

Note: Circuit Breaker events are mitigated, since these events can flood the event sink. The mitigation algorithm allows the first event of its kind to pass to the sink, but will block new events until a timeout of 5 minutes has passed.


0 Notification Code

0-7 0h – CB Drop TX filter hit. 1h – CB Rate Limit TX filter hit. 2h – CB Drop RX filter hit. 3h – CB Rate Limit RX filter hit.



Reason Info for EAC structure (Reason = 2)


0 Notification Code

0-7 Reserved


356




Reason Info for Remote Diagnostics structure (Reason = 3)


0 Notification Code

0-7 0h – Remote Redirection session started (SOL). 1h – Remote Redirection session stopped (SOL). 2h – Remote Redirection session started (IDE-R). 3h – Remote Redirection session stopped (IDE-R).



Reason Info for WLAN structure (Reason = 4)


0 Notification Code

0-7 2h – Host profile mismatch. Management Interface ignored. 3h – Management device overrides host Radio. 4h – Host profile security mismatch (SSID match, but the security parameters of the profile aren't). Management Interface ignored. 5h – Management device relinquishes control over host Radio.




357

9.11 AMT Diagnostic Alert This alert is preconfigured into the Intel AMT device (by default alert is logged into the event log). It is used to track various device failure codes which can assist a local user tools or a remote IT administrator with resolving configuration errors which are reported in the fields of this alert.

Currently, this alert is reported by the 802.1X module, but can be later used by other modules.

Compatibility This event is supported by Intel AMT Releases 2.6 and 3.0.

Trap Definition

Specific Trap Info

Event Sensor Type C1h (OEM Reserved)

Event Type 71h (OEM Discrete)

Event Offset 00h



Event Severity 02h (Information)




Entity Instance 61h (port #1 (LAN port)) or 62h (port #1 (WLAN port)) or 00h (NS)

EventData AAh (ED2-5 valid), NN (Report state, byte #0), NN (Report state, byte #1), NN (Report state, byte #2), NN (Report state, byte #3)

Remarks

A local service that wishes to receive a user notification alert should subscribe for an alert with a PolicyID field equal to 0x87.


358

9.11.1.1 Report state

This section defines the format of the Report state structure that resides in the following data bytes of the Event Data field of a PET packet.



0 Reason 4-7 2h – AMT Diagnostic

1 ReasonCode 0h – Certificate error 1h – TLS Handshake error. 2h – 802.1X error 3h – EAC error 4h… Fh – Reserved.

2-3 Reason Info Data formatted according to Reason code

Reason Info for "Certificate error" (ReasonCode = 0)


0 Notification Code

0-7 0 – General certificate error

1 - Certificate expired

2 - Missing trusted root certificate

3 - Failed to validate certificate chain

4 - Certificate revoked

5 - RSA exponent too big

6 - RSA modulus too big

7 - Unsupported digest

8 - Distinguished name too long

9 - Key usage missing

10…255 - Reserved


Reason Info for "TLS Handshake error" (ReasonCode = 1)


0 Notification Code

0-7 0 – General SSL handshake error

1…255 – Reserved


359



Reason Info for "802.1X error" (ReasonCode = 2)


0 Notification Code

0-7 0 – General 802.1X error



Reason Info for "EAC error" (ReasonCode = 3)


0 Notification Code

0-7 0 – General NAC error

1 - Attempt to get a posture while NAC in Intel AMT is disabled.

2 - Attempt to get posture of unsupported type.



10 Product Capabilities This section describes some of the capabilities and differences between generations of the Intel AMT device. Most of the capabilities and differences are visible through designated API calls, and the caller is encouraged not to assume that the values which are presented in this chapter are guaranteed.


360

10.1 Quantitative Properties and Capabilities

10.1.1 Agent presence (supported as of Intel AMT Release 2.0) • Total number of Agents: 16

• Total number of actions: 64

• Minimum guaranteed actions per Agent: 3

10.1.2 System Defense (Circuit Breaker) (supported as of Intel AMT Release 2.0)

• Total number of policies: 8

• Total number of filters: 80

• Maximum IPv4 Transmit filters: 31

• Maximum IPv4 Receive filters: 32

• Maximum IPv4 Transmit counters: 16

• Maximum IPv4 Receive counters: 16

• Maximum Combined IPv4 Transmit and Receive counters in a single policy: 31

• Maximum IPv6 Transmit filters: 7

• Maximum IPv6 Transmit counters: 4

• Maximum IPv6 Receive filters: 7

• Maximum IPv6 Receive counters: 4

• IPv4 to IPv6 size ratio: 1:4

• AntiSpoofing support: IPv4

• HardwareID: 0 – “Wired NIC”, 1 – “Wireless NIC”

• Supported TCP Flags in filter: SYN, RST, PUSH, ACK, URG, FIN (other flags are not supported)

10.1.3 PKI • Intel AMT Release 1.0:

o CertChainMaxSize: 3600 bytes

o Supported Key Lengths (server side): 1536 bits

o TLS Support: Network Only (Server Certificate)

• Intel AMT Release 2.5 or later:

o CertChainMaxSize: 4100 bytes

o Supported Key Lengths (server side): 1024, 1536, 2048 bits

o Supported Key Lengths (mutually authenticated client): 1024, 1536, 2048 bits

o TLS Support: Network or Local using Server Certificate or Mutual authentication. TLS enablement applies to both interfaces

o CRL Store Size (Maximum Root Certificate Size: 4100 bytes


361

o Maximum Root Certificate Size: 1500 bytes

o Maximum Root Certificate Instances: 4

o FqdnSuffixMaxEntries: 4

o FqdnSuffixMaxEntryLength: 50

o Supported Key Lengths (mutually authenticated client): 1024, 1536, 2048 bits

10.1.4 User ACL • Before Intel AMT Release 3.0:

o Maximum ACL entries for Digest authenticated users: 1 (Admin) + 7 Users

o Maximum ACL entries for Kerberos authenticated users (from Intel AMT Release 2.0 or later): 32


o 2 additional system accounts: "$$uns" and "$$eac" These accounts are members of the LocalUN and EndpointAccessControl realms respectively. The accounts cannot be deleted but the account password may be changed.

10.1.5 Event Manager • Before Intel AMT Release 2.5:

o Maximum User subscriptions: 8

o Maximum number of filters: 16


o Maximum User subscriptions: 16 (up to 14 SNMP and up to 8 SOAP)


o Maximum number of filters: 17 (increased by one to include the default "AMT Diagnostic" preconfigured event).


362

10.2 TLS Certificates and Authentication

10.2.1 Server Side Authentication Intel AMT provides HTTPS and IDE-R services over ports 16993 and 16995 respectively.

These ports are secured by TLS (SSL 3.0 and SSL 3.1(TLS1.0)) while authenticating the server side using an x509 certificate. The server’s certificate is used to encrypt the traffic and authenticate the server side.

Supported cipher suites:

• After Configuration (ProvisioningState is ProvisioningStatePost, or Operational Mode)

o RC4-128-SHA1

o AES-128-CBC-SHA1

• During Configuration (ProvisioningState is ProvisioningStateIn, or Setup Mode)

o AES-128 CBC-SHA1 over TLS PSK

• For Intel AMT devices that have crypto hardware disabled the following cipher suite may be supported:

o NULL-SHA1

A typical server authentication (performed by the client) may include:

• Checking that the server certificate is signed by a root Certificate authority which is trusted by the client application

• Checking that the server certificate is issued to the network address or name that matches the destination address

• Checking that the server certificate is not revoked

• Checking that the server certificate has not expired

In Intel AMT Release 1.0 and Intel AMT Release 2.0/2.1, when configured in Small Business mode – TLS cannot be enabled.

10.2.2 Client Side Authentication Intel AMT Release 2.0 may be configured to require a client side certificate during SSL negotiation.

A client authentication (performed by Intel AMT) involves:

• Checking that the client certificate is not revoked. By default, none of the client side certificates is revoked. It is possible to configure a revocation list by using the SetCRL() command.

• Checking that the client certificate is signed by a Root Certificate authority. Setting a root of trust is essential for client certificate validation. It is possible to add trusted root certificates using the AddTrustedRootCertificate() command.

• Checking that the client certificate has not expired. This validation is made every time a certificate is sent by the client side.


363

The internal clock is used to track the date and time of Intel AMT. Setting the current time is very important for this test to pass.

• Checking the credentials embedded into the client certificate Intel AMT expects to read certain OIDs in the client certificate.

o If a client certificate is submitted over the remote host interface, the certificate is expected to contain these OIDs: 1.3.6.1.5.5.7.3.2 + 2.16.840.1.113741.1.2.1

o If a client certificate is submitted over the local host interface, the certificate is expected to contain these OIDs: 1.3.6.1.5.5.7.3.2 + 2.16.840.1.113741.1.2.2

• Checking the size of the incoming certificate: Please refer to the section describing the Quantitative properties and capabilities

• Checking that the client certificate belongs to a trusted FQDN. If a corporate configures a public trusted root certificate (such as Verisign), it is encouraged to specify the trusted domain name to be compared against the certificate Subject.CN field. This test could assist with rejecting certificates which are signed by public trusted entities but do not belong to the local domain. Please refer to the SetTrustedFqdnCN() command for additional information.


364

10.3 Intel AMT Release 2.0 Reduced Functionality

10.3.1 Introduction Intel AMT Release 2.0 is required to interoperate with legacy Configuration servers (that lack the TLS PSK functionality). Since this mode is discouraged due to various security reasons, it is decided to limit the product feature set when configured by legacy configuration servers.

Re-enabling the full feature set is possible only after performing a full Unprovision–Reprovision process, which includes manual key setup and restarting configuration over TLS-PSK.

The limitations are similar in later Intel AMT releases through Release 3.0.

This section describes the functionality limitations which are inherited by this requirement.

10.3.2 Detailed Description of Unsupported Features and Functions

Interface SOAP call Behavior

AddUserAclEntry Functionality change

UpdateUserAclEntry Functionality change

AddUserAclEntryEx SOAP fault

GetUserAclEntryEx SOAP fault

UpdateUserAclEntryEx SOAP fault

SetAdminAclEntryEx SOAP fault

GetDigestRealm SOAP fault

SetKerberosOptions SOAP fault

GetKerberosOptions SOAP fault

SetEnabledInterfaces SOAP fault

GetEnabledInterfaces SOAP fault

SetTlsOptions SOAP fault

GetTlsOptions SOAP fault

AddTrustedRootCertificate SOAP fault

GetTrustedRootCertificate SOAP fault

DeleteTrustedRootCertificate SOAP fault

EnumerateTrustedRootCertificates SOAP fault

SetTrustedFqdnCN SOAP fault

GetTrustedFqdnCN SOAP fault

SetCRL SOAP fault

GetCRL SOAP fault

GetServerCertificateReq SOAP fault

Security & Network Administration Interface

GetPkiCapabilities SOAP fault


365

Interface SOAP call Behavior

GetPowerSavingOptions SOAP fault

SetPowerSavingOptions SOAP fault

PartialUnprovision SOAP fault

SetTLSPSK SOAP fault

SetDomainName SOAP fault

GetDomainName SOAP fault

Circuit Breaker Interface All calls HTTP Error

Local Agent Presence Interface All calls HTTP Error

Remote Agent Presence Interface All calls HTTP Error

General Info Interface All calls HTTP Error

Network Time Interface All calls HTTP Error

Redirection Interface All calls HTTP Error

10.3.2.1 Functionality Changes Some functionality changes may apply to the interface. For example, specifying unsupported realms in the Realm types may cause failure to comply (error return code may be PT_STATUS_INVALID_PARAMETER).

Unsupported Realms in Intel AMT Release 1.0 mode are:

• Redirection Interface

• Local Agent Presence

• Remote Agent Presence

• Circuit Breaker Interface

• NetworkTime Interface

• GeneralInfo Interface

10.3.2.2 HTTP Errors Unsupported Interfaces should return a HTTP Error 404 – Page not found.

10.3.2.3 SOAP Faults Unsupported SOAP calls in supported Interfaces should return a SOAP fault which will indicate the SOAP call cannot be parsed.

10.3.3 Additional Compatibility Notes When Intel AMT Release 2.0 and later releases operate in Intel AMT Release 1.0 Legacy mode, the legacy WMI interface will be exposed to the Host OS. All local network interfaces are disabled.


366

10.4 Power Packages Intel AMT Releases 2.5 and 3.0 introduce the concept of power packages. A power package defines the lowest power state at which Intel AMT can operate and whether Wake on LAN is enabled or not. Each power package has a well-known GUID and a descriptive string. The following table lists the power packages for releases 2.5 and 3.0. The Management Engine is off for S-states not listed in the table. An OEM can selectively delete those power packages that are noted in the table as optional.

WoL in the descriptive string indicates that when the host in one of the indicated S states, the Management Engine will enter a sleep state after a period of inactivity. Traffic addressed to Intel AMT will wake up the Management Engine. The SetGlobalPowerPolicy command defines the period of inactivity.

The “AC” in the Release 2.5 descriptive strings indicates that the Management Engine and Intel AMT are active only when the platform is connected to AC power. Intel AMT is never active when the platform is running from a battery.

The last two packages for release 3.0 contain “” in their descriptive strings. The packages support Wake on LAN but the Management Engine will not wake up after a power failure. This option reduces the possibility of a surge after restoration of power when many machines attempt to power up simultaneously.

Note: The GUIDs are recorded in the firmware and transmitted as a byte array in the format shown in the table. GUIDs are often represented as a four-byte word, two two-byte words and eight single bytes. The bytes in the three words are then shown in network order. For example the first GUID in the table would be represented as {11DEB642-FF25-CA43-A638DBDEAF30C5E9}.

Intel AMT

Release

Required/ Optional Descriptive String GUID

Required Mobile: ON in S0 {42B6DE11-25FF-43CA-A638 DBDEAF30C5E9}

Required Mobile: ON in S0, S3/AC {C6E1E4AE-8671-4D83-ABB4 F77320F24B3F}

Required Mobile: ON in S0, S3/AC, S4-5/AC {807D2EE9-B5E4-4501-B84D 241AD7F30A74}

Optional Mobile: ON in S0; ME WoL in S3/AC

{0FB599F7-1DC8-44CB-880ECBB3C67A3E25}

2.5

Optional Mobile: ON in S0; ME WoL in S3/AC, S4-5/AC

{1FB9C261-286F-485C-B2679288FF3A0A91}

Required Desktop: ON in S0 {944F8312-FB10-4FDC-968E1E232B0C9065}

Required Desktop: ON in S0, S3 {A18600AB-9A7F-4C42-A6E6BB243A295D9E}

Required Desktop: ON in S0, S3, S4-5 {7286ABAC-96B4-48E2-9B9E9B7DF91C7FD4}

Optional Desktop: ON in S0; ME WoL in S3 {7B32CD4D-6BBE-4389-A62A4D7BD8DBD026}

3.0

Optional Desktop: ON in S0; ME WoL in S3, S4-5

{73227346-23DC-432F-A98A13D37982D855}


367

Optional Desktop: ON in S0, S3, S4-5, OFF After Power Loss

{C519A4BA-6E6F-8D4D-B227517F7E4595DB}

Optional Desktop: ON in S0, ME WoL in S3, S4-5, OFF After Power Loss

{D60BE3ED-04C5-2C46-B772D18018EE2FC4}

11 New APIs and Deprecated APIs The following table summarizes the URIs, APIs, and the Intel AMT releases that support them.

'd' – deprecated '√' – supported

'−' – unsupported

Features supported in point releases are indicated in the appropriate column.

Intel AMT Release URI API Name 1.0 2.0 2.5 3.0

AddUserAclEntry √ d d d

AddUserAclEntryEx − √ √ √

EnumerateUserAclEntries √ √ √ √

GetUserAclEntry √ d d d

GetUserAclEntryEx − √ √ √

UpdateUserAclEntry √ d d d

UpdateUserAclEntryEx − √ √ √

RemoveUserAclEntry √ √ √ √

SetAdminAclEntry √ √ √ √

SetAdminAclEntryEx − √ √ √

GetAdminAclEntry √ √ √ √

GetDigestRealm − √ √ √

SetKerberosOptions − √ √ √

SetAclEnabledState − − − √

GetAclEnabledState − − − √

GetKerberosOptions − √ √ √

/SecurityAdministrationService

SetEnabledInterfaces − √ √ √


368


GetEnabledInterfaces − √ √ √

SetTlsEnabled √ d d d

SetTlsOptions − √ √ √

GetTlsOptions − √ √ √

SetTLSKeyAndCertificate √ √ d d

SetTLSPSK − √ √ √

SetRngKey √ √ √ d

SetTLSCertificate √ √ d d

GetTLSCertificate √ √ d d

AddTrustedRootCertificate − √ √ √

GetTrustedRootCertificate − √ √ √

DeleteTrustedRootCertificate − √ √ √

EnumerateTrustedRootCertificates − √ √ √

SetTrustedFqdnCN − √ √ √

GetTrustedFqdnCN − √ √ √

SetCRL − √ √ √

GetCRL − √ √ √

GetServerCertificateReq − √ d d

GetPkiCapabilities − √ √ √

UpdateCoreFromUrl √ − − −

GetProvisioningMode √ √ √ √

SetProvisioningMode √ √ √ √

CommitChanges √ √ √ √

Unprovision √ √ √ √

PartialUnprovision − √ √ √

ResetFlashWearOutProtection √ √ √ √

GetCoreVersion √ √ √ √


369


SetPowerSavingOptions − √ d d

GetPowerSavingOptions − √ d d

EnumeratePowerPackages − − √ √

GetActivePowerPackage − − √ √

GetPowerPackage − − √ √

SetActivePowerPackage − − √ √

SetGlobalPowerPolicy − − √ √

GetGlobalPowerPolicy − − √ √

CertStoreAddKey − − √ √

CertStoreGetKey − − √ √

CertStoreEnumerateKeys − − √ √

CertStoreRemoveKey − − √ √

CertStoreAddCertificate − − √ √

CertStoreGetCertificate − − √ √

CertStoreEnumerateCertificates − − √ √

CertStoreRemoveCertificate − − √ √

CertStoreGetPKCS10Request − − √ √

CertStoreUpdateCertificate − − √ √

SetTLSCredentials − − √ √

GetTLSCredentials − − √ √

EnableVPNRouting − − √ −

SetEnvironmentDetection − − √ √

GetEnvironmentDetection − − √ √

SetRealmAuthOptions − − √ √

GetRealmAuthOptions − − √ √

SetMEBxPassword − 2.2 2.6 √

SetProvisioningServerOTP − 2.2 2.6 √


370


GetProvisioningServerOTP − 2.2 2.6 √

EnumerateCertificateHashEntries − 2.2 2.6 √

GetCertificateHashEntry − 2.2 2.6 √

AddCertificateHashEntry − 2.2 2.6 √

DeleteCertificateHashEntry − 2.2 2.6 √

EnableCertificateHashEntry − 2.2 2.6 √

GetZeroTouchConfigurationMode − 2.2 2.6 √

SetZeroTouchConfigurationMode − 2.2 2.6 √

GetProvisioningAuditRecord − 2.2 2.6 √

GetProvisioningPID − 2.2 2.6 √

ExtendProvisioningPeriod − 2.2 2.6 √

SetConfigurationServerFQDN − − − √

GetConfigurationServerFQDN − − − √

SetTcpIpParameters √ √ d d

GetTcpIpParameters √ √ d d

SetHostName √ √ √ √

GetHostName √ √ √ √

SetDomainName − √ √ √

GetDomainName − √ √ √

SetVlanParameters √ √ √ √

GetVlanParameters √ √ √ √

SetPingResponse √ √ √ √

GetPingResponse √ √ √ √

EnumerateInterfaces − − √ √

GetInterfaceSettings − − √ √

SetInterfaceSettings − − √ √

/NetworkAdministrationService

Set8021XWiredProfile − − √ √


371


Get8021XWiredProfile − − √ √

Set8021XActiveS0 − − 2.6 √

Get8021XActiveS0 − − 2.6 √

Get8021XPxeTimeout − − 2.6 −

Set8021XPxeTimeout − − 2.6 −

GetGlobalStorageAttributes √ √ √ √

SetGlobalStorageAttributes √ √ √ √

AdminGetRegisteredApplications √ √ √ √

AdminGetApplicationAttributes √ √ √ √

AdminRemoveApplication √ √ √ √

AddStorageEaclEntry √ √ √ √

EnumerateStorageEaclEntries √ √ √ √

GetStorageEaclEntry √ √ √ √

RemoveStorageEaclEntry √ √ √ √

AddStorageFpaclEntry √ √ √ √

EnumerateStorageAllocEntries √ √ √ √

GetStorageAllocEntry √ √ √ √

UpdateStorageFpaclEntry √ √ √ √

/StorageAdministrationService

RemoveStorageFpaclEntry √ √ √ √

EnumerateAssetTypes √ √ √ √ /HardwareAssetService

GetAssetData √ √ √ √

GetRemoteControlCapabilities √ √ √ √

RemoteControl √ √ √ √

/RemoteControlService

GetSystemPowerState √ √ √ √

/StorageService ExecuteStorageOperation √ √ √ √


372


SubscribeForAlert √ √ d d

EnumerateAlertSubscriptions √ √ d d

GetAlertSubscription √ √ √ √

CancelAlertSubscription √ √ √ √

EnumerateAlertPolicies √ √ √ √

SetAlertCommunityString √ √ √ √

GetAlertCommunityString √ √ √ √

AddEventFilter √ √ √ √

EnumerateEventFilters √ √ √ √

GetEventFilter √ √ √ √

UpdateEventFilter √ √ √ √

RemoveEventFilter √ √ √ √

GetEventLogStatus √ √ √ √

ReadEventLogRecords √ √ √ √

ClearEventLog √ √ √ √

FreezeEventLog √ √ √ √

SetEventLogTimestampClock √ d d d

GetEventLogTimestampClock √ √ √ √

EnumerateSensors √ √ √ √

GetSensorAttributes √ √ √ √

SubscribeForGeneralAlert − − √ √

EnumerateGeneralAlertSubscriptions − − √ √

/EventManagerService

GetGeneralAlertSubscription − − √ √

ConsoleWatchdogCreate − √ √ √ /AgentWatchdogRemoteService

ConsoleWatchdogDelete − √ √ √


373


ConsoleWatchdogEnumerate − √ √ √

ConsoleWatchdogSetActions − √ √ √

ConsoleWatchdogGetActions − √ √ √

ConsoleWatchdogSetCbPolicy − √ √ √

ConsoleWatchdogGetCbPolicy − √ √ √

ConsoleWatchdogQueryCapabilities − √ √ √

AgentWatchdogRegister − √ √ √

AgentWatchdogHeartbeat − √ √ √

/AgentWatchdogLocalService

AgentWatchdogShutdown − √ √ √

CbPolicyCreate − √ √ √

CbPolicyGet − √ √ √

CbPolicyDelete − √ √ √

CbPolicyEnumerate − √ √ √

CbPolicyEnable − √ √ √

CbPolicyDisable − √ √ √

CbPolicyGetEnabled − √ √ √

CbPolicyGetActiveStatistics − √ √ √

CbFilterCreate − √ √ √

CbFilterGet − √ √ √

CbFilterDelete − √ √ √

CbFilterEnumerate − √ √ √

CbQueryCapabilities − √ √ √

SetHcbOptions − − − √

GetHcbOptions − − − √

/CircuitBreakerService

ClearHcbState − − − √


374


GetHcbState − − − √

SetRedirectionListenerState − √ √ √

GetRedirectionListenerState − √ √ √

/RedirectionService

GetIderSessionLog − √ √ √

GetLowAccuracyTimeSynch − √ √ √ /NetworkTimeService

SetHighAccuracyTimeSynch − √ √ √

GetCoreVersion − √ √ √

GetCodeVersions − √ √ √

GetProvisioningMode − √ √ √

GetProvisioningState − √ √ √

GetVlanParameters − √ √ √

GetHostName − √ √ √

GetConfigServerInfo − √ √ √

GetAdminAclEntryStatus − √ √ √

GetAdminNetAclEntryStatus − √ √ √

GetPasswordModel − √ √ √

GetEnabledInterfaces − √ √ √

GetNetworkState − √ √ √

GetSecurityParameters − √ √ √

/GeneralInfoService

GetIderSessionLog − √ √ √

GetCoreVersion − √ √ √

GetCodeVersions − √ √ √

/FirmwareUpdateService

GetFirmwareUpdateState − √ √ √

AddWirelessProfile − − √ −

GetWirelessProfile − − √ −

/WirelessConfigurationService

RemoveWirelessProfile − − √ −


375


UpdateWirelessProfile − − √ −

EnumerateWirelessProfiles − − √ −

GetWirelessCapabilities − − √ −

GetWirelessSettings − − √ −

SetPostureSigner − − √ √

GetPostureSigner − − √ √

EnableEAC − − √ √

UpdatePostureState − − √ √

/EndpointAccessControlAdminService

GetEACStatus − − √ √

GetEACStatus − − √ √

GetPosture − − √ √ /EndpointAccessControlService

GetPostureHash − − √ √

SubscribeForGeneralAlert − − √ √

EnumerateGeneralAlertSubscriptions − − √ √

GetGeneralAlertSubscription − − √ √

/UserNotificationService

CancelAlertSubscription − − √ √