Intel Active Management Technology Release 1.0 Host Interface Design Guide Version 4.0.0 February 2008
Information in this document is provided in connection with Intel products. No license, express or implied, by estoppels or otherwise, to any intellectual property rights is granted by this document. Except as provided in Intel s Terms and Conditions of Sale for such products, Intel assumes no liability whatsoever, and Intel disclaims any express or implied warranty, relating to sale and/or use of Intel products including liability or warranties relating to fitness for a particular purpose, merchantability, or infringement of any patent, copyright or other intellectual property right. Intel products are not intended for use in medical, life saving, or life sustaining applications. Intel may make changes to specifications and product descriptions at any time, without notice. The API and software may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. This document and the software described in it are furnished under license and may only be used or copied in accordance with the terms of the license. The information in this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Intel Corporation. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this document or any software that may be provided in association with this document. Except as permitted by such license, no part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written consent of Intel Corporation. Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order. Copies of documents which have an ordering number and are referenced in this document or other Intel literature may be obtained by calling 1-800-548-4725 or by visiting Intel s website at http://www.intel.com. Copyright 2006-2008 Intel Corporation. All rights reserved. * Third party other names and brands may be claimed as the property of others. 2
1 Introduction This document describes the Intel Active Management Technology (Intel AMT) Release 1.0 Host Information Interface APIs, which are provided to Independent Software Vendors (ISV) for their applications. These APIs allow an ISV application to collect information about Intel AMT in the OS-present state. These APIs do not operate through the Intel-provided storage library, but do require the presence of the Keyboard Controller Style (KCS) driver (Intel AMT Release 1.0) or the Intel Management Engine Interface (Intel AMT Release 2.0) driver in order to function. The KCS driver operates on either a Windows or a Linux platform, while the Intel Management Engine Interface driver is compatible only with Windows. Moreover, these APIs are designed to operate only on a local system; there is no provision for a remote method of invocation. NOTE: This interface is an Intel AMT Release 1.0 interface. It is supported for Intel AMT Release 2.0 or later releases only when configured for Legacy Mode. For interfaces supported by Intel AMT Release 2.0 and later releases refer to the Network Interface Guide. 2 ISV Application ISVs can use these APIs to provide configuration information for Intel AMT-enabled hardware. Throughout this document, the ISV application is local. Interfacing with the ISV application is accomplished via a C language based-api (C-API) interface. The code for the C-API is provided as sample code for ISVs and the code can be used in its entirety in ISV applications without additional licensing. The interface was chosen so as to enhance portability regarding any OSspecific mechanisms, such as COM or WMI. Note: In the Windows implementation, COM is used and should be initialized by the calling application. Note: If an ISV application links both with the Host Information interface and with the Storage Library, perform the following so that linker errors do not occur: For a Windows application, in Visual Studio.NET, go to Project properties->linker->input- >Ignore Specific Library field and type LIBCD.lib (for debug version) or LIBC.lib (for release version) For a Linux application, compile the application with a lssl flag. 3 Function and Data Types Naming Input: Input parameters in API functions Output: Output parameters in API functions Input/Output: Input/Output parameters in API functions. A fixed-width font is used to distinguish pseudo-code from other text. 3.1 PT_ Data Types Prefix All Data Types prefixed with PT_ describe general Intel AMT data types. 3.2 CFG_ Data Types Prefix All Data Types prefixed with CFG_ describe general Intel AMT data types. 3
3.3 PTSDK_ Data Types Prefix All Data Types prefixed with PTSDK_ describe specific data types used by the Host Information API. 3.4 Data Structures 3.4.1 PT_VERSION_TYPE PT_VERSION_TYPE represents the version of Intel AMT firmware component. typedef struct _PT_VERSION_TYPE PT_UNICODE_STRING Description; PT_UNICODE_STRING Version; } PT_VERSION_TYPE; Description Version The firmware component description string. The string that contains the firmware component version. Notes: Version defined as an at-most 11-byte long null terminated string, with three groups of numbers, separated by periods as follows: "X.Y.Z", where: X major version (at most two characters). Y minor version (at most two characters). Z micro version (at most four characters). For forward compatibility, each version string will be accompanied by a description string and a counter signifying the actual number of versions returned. See the following table: Version type ROM Flash (NetStack + AMTApps + Patches) Netstack AMTApps Patch1 Patch2 Description string "ROM" Flash "Netstack" "AMTApps" "Patch1" "Patch2" 3.4.2 CODE_VERSIONS CODE_VERSION represents a list of versions of all Intel AMT firmware components and the BIOS version. typedef struct _CODE_VERSIONS UINT8 BiosVersion[65]; UINT32 VersionsCount; PT_VERSION_TYPE Versions[6]; } CODE_VERSIONS; 4
BiosVersion Version of BIOS. This is defined by [SMBIOS] as a free format string of 64 bytes. VersionsCount The number of component versions. Versions Array of component versions 3.4.3 SECURITY_PARAMS SECURITY_PARAMS represents a list of relevant configurations of Intel AMT firmware. typedef struct _SECURITY_PARAMS PT_BOOLEAN EnterpriseMode; PT_BOOLEAN TLSEnabled; PT_BOOLEAN HWCryptoEnabled; PT_PROVISIONING_STATE ProvisioningState; PT_BOOLEAN NetworkInterfaceEnabled; PT_BOOLEAN SOLEnabled; PT_BOOLEAN IDEREnabled; PT_BOOLEAN FWUpdateEnabled; PT_BOOLEAN LinkIsUp; } SECURITY_PARAMS; EnterpriseMode TLSEnabled HWCryptoEnabled ProvisioningState NetworkInterfaceEnabled SOLEnabled IDEREnabled FWUpdateEnabled LinkIsUp TRUE Intel AMT is in Enterprise mode; FALSE SMB. TRUE TLS enabled; FALSE TLS disabled. TRUE Crypto fuse is burned, FALSE crypto fuse is not burned (no HW crypto). Indicated configuration state (according to ENUM). TRUE network interface enabled; FALSE network interface disabled. TRUE SOL device enabled; FALSE SOL device disabled. TRUE IDER device enabled; FALSE IDER device disabled. TRUE FWUpdate feature enabled; FALSE FWUpdate feature disabled. TRUE Link is up; FALSE Link is down. 3.4.4 IDER_SESSION_LOG IDER_SESSION_LOG represents a cyclic list of up to 16 entries of IDER sessions. typedef struct _IDER_SESSION_LOG CFG_IDER_SESSION_LOG_ENTRY LogData[16]; PT_BOOLEAN WrapAround; UINT8 Index; } IDER_SESSION_LOG; LogData Hold the last 16 records of opened IDER sessions. 5
WrapAround Index TRUE indicates that there were more than 16 IDER sessions, and that the log contains only the last 16. FALSE there were less than 17 IDER sessions. Index - points to the last valid entry +1. If the WrapAround flag is FALSE, then the valid entries in the log are 0 to Index 1. If the WrpaAround flag is TRUE, the valid entries are from Index to 15 and from 0 to Index 1. 3.4.5 CFG_IDER_SESSION_LOG_ENTRY CFG_IDER_SESSION_LOG_ENTRY represents a list of up to 16 entries of IDER sessions. typedef struct _CFG_IDER_SESSION_LOG_ENTRY CFG_IPv4_ADDRESS ConsoleAddress; CFG_TIMESTAMP TimeStamp; CFG_TCPIP_PORT Port; } CFG_IDER_SESSION_LOG_ENTRY; ConsoleAddress TimeStamp Port Remote console IP address. Timestamp (when session opened) Remote console TCP port. Note: Empty entries will have Timestamp = 0x0. IDER session log timestamp may not be set (Example: if the AMTBx BIOS extension is not enabled). 3.4.6 CFG_TIMESTAMP CFG_TIMESTAMP represents the number of seconds elapsed since 00:00 hours, Jan 1, 1970 UTC according the clock set into Intel AMT by the BIOS. typedef UINT32 CFG_TIMESTAMP; 3.4.7 CFG_TCPIP_PORT CFG_TCPIP_PORT represent TCP port. typedef UINT16 CFG_TCPIP_PORT; 3.4.8 CFG_IPv4_ADDRESS CFG_IPv4_ADDRESS represents IP version 4 addresses. Addresses are represented per [IP] i.e. value: 0x01020304 maps to IP address: 1.2.3.4 typedef UINT32 CFG_IPv4_ADDRESS; 3.4.9 PT_PROVISIONING_STATE PT_PROVISIONING_STATE represents the configuration mode of Intel AMT firmware. 6
typedef enum _PT_PROVISIONING_STATE PROVISIONING_STATE_PRE = 0, PROVISIONING_STATE_IN = 1, PROVISIONING_STATE_POST = 2, } PT_PROVISIONING_STATE; PROVISIONING_STATE_PRE PROVISIONING_STATE_IN PROVISIONING_STATE_POST Factory Setup Mode Setup Mode Operational Mode 3.4.10 PT_UNICODE_STRING PT_UNICODE_STRING represents a Unicode string in UTF-8 format. Unicode strings are used by Intel AMT to describe Version type and Version description. typedef struct _PT_UNICODE_STRING UINT16 Length; UINT8 String[20]; } PT_UNICODE_STRING; Length String The length in bytes of the string stored in String. Length does not include the trailing NULL, if exists. The buffer used to contain an array of characters. 3.4.11 PT_BOOLEAN PT_BOOLEAN defined to represent Boolean values true and false. typedef UINT32 PT_BOOLEAN; const PT_BOOLEAN PT_FALSE = 0; const PT_BOOLEAN PT_TRUE = 1; PT_FALSE PT_TRUE Boolean False. Boolean True. 3.4.12 PT_STATUS PT_STATUS defines status codes that are returned by the Host Information API calls. typedef UINT32 PT_STATUS; static const PT_STATUS PT_STATUS_SUCCESS = 0; static const PT_STATUS PT_STATUS_INTERNAL_ERROR = 0x0001; static const PT_STATUS PT_STATUS_INVALID_MESSAGE_LENGTH = 0x0004; static const PT_STATUS PTSDK_STATUS_INTERNAL_ERROR = 0x1000; static const PT_STATUS PTSDK_STATUS_INVALID_PARAM = 0x1003; static const PT_STATUS PTSDK_STATUS_RESOURCES = 0x1004; 7
static const PT_STATUS PTSDK_STATUS_HARDWARE_ACCESS_ERROR = 0x1005; 3.4.12.1 Error s Unless stated otherwise each function call can return the following error codes: PT_STATUS_SUCCESS PT_STATUS_INTERNAL_ERROR PT_STATUS_INVALID_MESSAGE_LENGTH PTSDK_STATUS_INTERNAL_ERROR PTSDK_STATUS_HARDWARE_ACCESS_ERROR PTSDK_STATUS_RESOURCES PTSDK_STATUS_INVALID_PARAM The requested operation was successfully executed. Intel AMT has identified an internal HW error. Length field of header is invalid. An internal Host Information API error occurred. The Host Information has identified a HW Internal error. This can include: Intel AMT not preset, Intel Management Engine Interface or KCS driver not loaded, or version of Intel AMT that doesn t identify this command. The Host Information API could not allocate sufficient resources to complete the operation. One of the parameters is invalid (usually indicates a NULL) 3.5 Host Information API 3.5.1 GetSecurityParameters GetSecurityParameters is called by the ISV application to retrieve a list of the current security settings and other relevant configurations parameters: Mode of operation (SMB / Enterprise) TLS state (Enabled / Disabled) Crypto enable fuse state (Enabled / Disabled) Provisioning state (Factory Setup Mode, Setup Mode, Operational Mode) Network interface (Enabled / Disabled) IDER state (Enabled / Disabled) SOL state (Enabled / Disabled) FW Update (Enabled / Disabled) Link state (Connected / Disconnected) PT_STATUS GetSecurityParameters(SECURITY_PARAMS *securityparams); Function Parameters Parameters Input/output Description securityparams Input/Output Input. The pointer to the pre-allocated SECURITY_PARAMS structure. Output. The structure, containing the current Intel AMT firmware configuration parameters. 8
Function Return Status PT_STATUS_SUCCESS PT_STATUS_INTERNAL_ERROR PT_STATUS_INVALID_MESSAGE_LENGTH PTSDK_STATUS_INTERNAL_ERROR PTSDK_STATUS_HARDWARE_ACCESS_ERROR PTSDK_STATUS_RESOURCES PTSDK_STATUS_INVALID_PARAM The requested operation was successfully executed. Intel AMT has identified an internal HW error. Length field of header is invalid. An internal Host Information API error occurred. The Host Information has identified a HW Internal error. This can include: Intel AMT not preset, Intel Management Engine Interface driver or KCS driver not loaded, or version of Intel AMT that doesn t identify this command. The Host Information API could not allocate sufficient resources to complete the operation. One of the parameters is invalid (usually indicates a NULL) 3.5.2 GetVersions GetVersions is called by the ISV application to retrieve a list of versions of Intel AMT firmware components and the BIOS version. PT_STATUS GetVersions (CODE_VERSIONS *codeversions); Function Parameters Parameters Input/output Description codeversions Input/Output Input. The pointer to the pre-allocated CODE_VERSIONS structure. Output. The structure, containing a list of versions of Intel AMT firmware components and the BIOS version. Function Return Status PT_STATUS_SUCCESS PT_STATUS_INTERNAL_ERROR PT_STATUS_INVALID_MESSAGE_LENGTH PTSDK_STATUS_INTERNAL_ERROR PTSDK_STATUS_HARDWARE_ACCESS_ERROR PTSDK_STATUS_RESOURCES The requested operation was successfully executed. Intel AMT has identified an internal HW error. Length field of header is invalid. An internal Host Information API error occurred. The Host Information API has identified a HW Internal error. This can include: Intel AMT not preset, Intel Management Engine Interface driver or KCS driver not loaded, or version of Intel AMT that doesn t identify this command. The Host Information API could not allocate sufficient resources to complete the operation. 9
PTSDK_STATUS_INVALID_PARAM One of the parameters is invalid (usually indicates a NULL) 3.5.3 GetIderSessionLog GetVersions is called by the ISV application to retrieve the IDER session log. PT_STATUS GetIderSessionLog(IDER_SESSION_LOG *idersessionlog); Function Parameters Parameters Input/output Description idersessionlog Input/Output Input. The pointer to the pre-allocated IDER_SESSION_LOG structure. Output. The structure, containing a cyclic list of up to 16 entries of IDER sessions. Function Return Status PT_STATUS_SUCCESS PT_STATUS_INTERNAL_ERROR PT_STATUS_INVALID_MESSAGE_LENGTH PTSDK_STATUS_INTERNAL_ERROR PTSDK_STATUS_HARDWARE_ACCESS_ERROR PTSDK_STATUS_RESOURCES PTSDK_STATUS_INVALID_PARAM The requested operation was successfully executed. Intel AMT has identified an internal HW error. Length field of header is invalid. An internal Host Information API error occurred. The Host Information API has identified a HW Internal error. This can include: Intel AMT not preset, Intel Management Engine Interface driver or KCS driver not loaded, or version of Intel AMT that doesn t identify this command. The Host Information API could not allocate sufficient resources to complete the operation. One of the parameters is invalid (usually indicates a NULL) 4 Reference Documents The following documents are companion and supporting specifications for the Host Information API: Document Description [IP] IETF RFC 791 [SMBIOS] System Management BIOS (SMBIOS) Reference Specification, v2.3.4, December 6, 2002. 10