Intel Confidential Intel® Active Management Technology (Intel® AMT) Reference Design Kit (RDK) Building Block API Guide Revision 1.0 September 15, 2006
Intel Confidential
Intel® Active Management Technology (Intel® AMT) Reference Design Kit (RDK)
Building Block API Guide
Revision 1.0 September 15, 2006
2 Intel Confidential
Revision History
Version Version Information Date Author
1.0 Initial release of document. Sept. 2006 Intel Corporation
Intel® AMT RDK API Guide
Intel Confidential 3
Table of Contents 1.0 INTRODUCTION......................................................................................................................................................6
1.1 SCOPE....................................................................................................................................................................................7 1.2 REFERENCES..........................................................................................................................................................................7
2.0 INTEL® AMT RDK BUILDING BLOCKS................................................................................................................8 2.1 BUILDING BLOCK OVERVIEW................................................................................................................................................8 2.2 COMMONDEF ........................................................................................................................................................................8
2.2.1 API tables.........................................................................................................................................................................8 2.3 PTSTATUS .............................................................................................................................................................................9
2.3.1 API tables : ......................................................................................................................................................................9 2.4 DEBUGMGR...........................................................................................................................................................................9
2.4.1 API tables : ......................................................................................................................................................................9 2.5 NETWORKPARAMDEFS..........................................................................................................................................................9
2.5.1 API tables : ......................................................................................................................................................................9 2.6 VLANPARAM .....................................................................................................................................................................10
2.6.1 API tables : ....................................................................................................................................................................10 2.7 GENERALINFOINTERFACE ...................................................................................................................................................11
2.7.1 API table :......................................................................................................................................................................11 2.8 CAPABILITYDISCOVERY......................................................................................................................................................12
2.8.1 API table :......................................................................................................................................................................12 2.8.2 Usage Example: .............................................................................................................................................................12
2.9 REMOTE CONTROL ..............................................................................................................................................................13 2.9.1 API table :......................................................................................................................................................................13 2.9.2 Usage Example: .............................................................................................................................................................16
2.10 HARDWARE ASSET ..............................................................................................................................................................17 2.10.1 API table : .................................................................................................................................................................17 2.10.2 Usage Example: ........................................................................................................................................................17
2.11 NETWORK ADMIN ...............................................................................................................................................................18 2.11.1 API table: ..................................................................................................................................................................18 2.11.2 Usage Example: ........................................................................................................................................................19
2.12 SECURITY ADMIN ................................................................................................................................................................20 2.12.1 API table: ..................................................................................................................................................................20
2.13 STORAGE ADMIN.................................................................................................................................................................21 2.13.1 API table : .................................................................................................................................................................21 2.13.2 Usage Example: ........................................................................................................................................................22
2.14 EVENT MANAGEMENT.........................................................................................................................................................23 2.14.1 API Tables: ...............................................................................................................................................................23 2.14.2 Limitation:.................................................................................................................................................................30 2.14.3 Usage Example: ........................................................................................................................................................30
2.15 SYSTEM DEFENSE (ALSO KNOWN AS CIRCUIT BREAKER) ....................................................................................................32 2.15.1 API Table ..................................................................................................................................................................35
2.15.1.1 Data Structures ........................................................................................................................................................................38 2.15.2 Usage Examples ........................................................................................................................................................38
2.15.2.1 Default Mode Usage................................................................................................................................................................38 2.15.2.2 AP Mode Usage.......................................................................................................................................................................39 2.15.2.3 Expert Mode Usage (Joint-usage on the Three Operating Modes) ..........................................................................................39
2.16 LOCAL AGENT PRESENCE....................................................................................................................................................41 2.16.1 API Table ..................................................................................................................................................................41 2.16.2 Application Notes ......................................................................................................................................................41 2.16.3 Usage Example .........................................................................................................................................................42
2.17 REMOTE AGENT PRESENCE .................................................................................................................................................42 2.17.1 API Table : ................................................................................................................................................................42 2.17.2 Application Notes :....................................................................................................................................................45 2.17.3 Usage Example : .......................................................................................................................................................45
2.18 STORAGE INTERFACE ..........................................................................................................................................................46 2.18.1 API table: ..................................................................................................................................................................46
Intel® AMT RDK API Guide
4 Intel Confidential
2.18.2 Usage Example: ........................................................................................................................................................46 2.19 REDIRECTION INTERFACE....................................................................................................................................................47
2.19.1 API table: ..................................................................................................................................................................47 2.19.2 Usage Example: ........................................................................................................................................................48
3.0 GRAPHICAL USER INTERFACE (GUI) ...............................................................................................................49 3.1 AMTGUI CLASS ...................................................................................................................................................................49
3.1.1 API Table .......................................................................................................................................................................49 3.2 AMTGUI<BUILDINGBLOCK>HANDLER CLASSES................................................................................................................50
3.2.1 API tables.......................................................................................................................................................................50
Intel® AMT RDK API Guide
Intel Confidential 7
The Intel® Active Management Technology (Intel® AMT) Reference Design Kit (RDK) provides reusable building blocks in the form of Java* classes which can be used to rapidly integrate Intel AMT capabilities into Java-based management applications.
1.1 Scope This document provides details of the Application Programming Interfaces (APIs) exported by the RDK building blocks. It is intended for use by developers building Intel AMT-enabled applications using the RDK building blocks.
1.2 References Document Version Comments Intel® Active Management Technology SDK 3.2 Consult Intel AMT SDK documentation if
you would like to develop code that interacts directly with the SOAP/Library based interfaces provided by Intel AMT.
Intel® Active Management Technology RDK User Guide
TBD Consult this document for details of how to use the RDK as an utility application for exploring capabilities of Intel AMT-enabled platforms.
Intel® AMT RDK API Guide
8 Intel Confidential
2 .0 In te l® AMT RDK Bui ld ing Blocks Intel® AMT RDK Building Blocks are reusable Java classes that encapsulate Intel AMT SDK provided libraries. This section provides details of the interfaces exposed by the various building blocks provided in the Intel AMT RDK.
2.1 Building Block Overview Architecture of typical building block ( as an e.g. Remote Control ) :
Common Class- Private data members
- Private methods
DefaultConstructor
OverloadedConstructor
CommonDefs - Username- Password- IP address
APIs exposed from Remote Control Building Block:
InitializeUnintializegetSystemPowerStategetRemoteControlCapabilitiesResetpowerOffpowerOnpowerCycleResetforcePXEBootforceHDDBootforceHDDSafeModeBootforceDiagnosticsBootforceCdOrDvdBoot
Every building block has default and overloaded constructors. An overloaded constructor takes an object of type “CommonDef” as its parameter. CommonDef is the common class which encapsulates username, password, and ipaddress. Those parameters are required by every building block in order to talk to the Intel AMT subsystem (locally and remotely).
2.2 CommonDef Description - This common class encapsulates all necessary authentication parameters. The current implementation provides get/set methods for username, password, and IP address. It is used in all the building blocks. This class can be easily extended to incorporate TLS support.
2.2.1 API tables Name Description Input
Parameter Returns
getUsername It returns the username None String getPassword It returns the password None String getIPaddr It returns the IP address of machine None String
Intel® AMT RDK API Guide
Intel Confidential 9
2.3 PtStatus Description :This common class keeps a mapping of status code to a meaningful interpretation. It provides a method to have the description of status code returned by execution of WSDL interface. It is used in all the building blocks. This class can be easily extended to incorporate more status codes.
2.3.1 API tables : Name Description Input
Parameter Returns
getStatusString Takes a status code as its input argument and returns a meaningful description.
int String
2.4 DebugMgr Description :This common class provides a consistent way of handling debug messages. It provides a method for toggle debugging in your application, as well as a method to write a log. It is used in all the building blocks. The current implementation writes information to standard output, but in the future it will be enhanced to write to a log file. This is a static class so it does not require instantiation.
2.4.1 API tables : Name Description Input
Parameter Returns
dbgMsg Should be used by application to write logs.
String None
toggle This is a overloaded method, if passed without argument then it will toggle the debugging on/off.
None None
toggle Same as above but it takes an explicit Boolean argument to turn the debugging on/off [true - on| false - off]
Boolean (true/false)
None
2.5 NetworkParamDefs Description :This common class encapsulates all necessary parameters for Ipv4 setting. This class provides get/set methods for all those parameters. It is used in Network Admin building block.
2.5.1 API tables : Name Description Input
Params Returns
getCount Returns count of object instantiated of this class.
None Int
Equals Overloaded “equals” method Object Boolean toString Overloaded “toString” method None String getDhcpMode Returns DHCP mode of Intel AMT
subsystem Int None
getDomainName This method returns domain name of Intel AMT subsystem
String None
Intel® AMT RDK API Guide
10 Intel Confidential
getLocalAddr Returns local address of Intel AMT subsystem
String None
getSubnetMask Returns subnet mask of Intel AMT subsystem
String None
getGatewayAddr Returns gateway address of Intel AMT subsystem
String None
getPrimaryDNSAddr Returns address of primary DNS of Intel AMT subsystem
String None
getSecondaryDNSAddr Returns address of secondary DNS of Intel AMT subsystem
String None
setDhcpMode Sets DHCP mode for Intel AMT subsystem
None int
setDomainName Sets domain name for Intel AMT subsystem
None String
setLocalAddr Sets local address for Intel AMT subsystem
None String
setSubnetMask Sets subnet & mask for Intel AMT subsystem
None String
setGatewayAddr Sets gateway address for Intel AMT subsystem
None String
setPrimaryDNSAddr Sets address of primary DNS for Intel AMT subsystem
None String
setSecondaryDNSAddr Sets address of secondary DNS for Intel AMT subsystem
None String
getLocalAddsAsBytes Returns local address as array of bytes in network order
None Bytes[]
getSubnetMaskAsBytes Returns subnet & mask as array of bytes in network order
None Bytes[]
getGatewayAddrAsBytes Returns gateway address as array of bytes in network order
None Bytes[]
getPrimaryDNSAsBytes Returns address of primary DNS as array of bytes in network order
None Bytes[]
getSecondaryDNSAsBytes Returns address of secondary DNS as array of bytes in network order
None Bytes[]
getLocalAddrAsLong Returns local address as long (32 bit value for little endian architecture)
None long
getSubnetMaskAsLong Returns subnet and mask as long (32 bit value for little endian architecture)
None long
getGatewayAddrAsLong Returns gateway address as long (32 bit value for little endian architecture)
None long
getPrimaryDNSAsLong Returns address of primary DNS as long (32 bit value for little endian architecture)
None long
getSecondaryDNSAsLong Returns address of secondary DNS as long (32 bit value for little endian architecture)
None long
2.6 VLANParam Description: This class encapsulates functionality and data required for VLAN such as VLAN status and VLAN tag ( VLAN tag is VLAN ID which is in the range of 0-1023). This common class is used in Network Admin building block to return VLAN info.
2.6.1 API tables :
Intel® AMT RDK API Guide
Intel Confidential 11
Name Description Input Params
Returns
getCount Returns count of object instantiated of this class
None Int
Equals Overloaded “equals” method Object Boolean toString Overloaded “toString” method None String getStatus Returns current status of VLAN for a
given connection such as VLAN is disabled/enabled
None Boolean True – VLAN enabled False – VLAN disabled
getTagValue Returns VLAN tag value which is in the range of 0-1023
None Int – VLAN tag value
setStatus Sets VLAN status (enabled/disabled) for a given connection
Boolean void
setTagValue Sets tag value for a VLAN Int void
2.7 GeneralInfoInterface Description : This building block encapsulates all the functionality offered by GeneralInfo Interface of Intel AMT. GeneralInfo Interface is part of both in-band and out-of-band functionality of Intel AMT. It exposes user friendly APIs to perform specific operation and hides all communication details with Intel AMT subsystem. It offers default and overloaded constructors. The overloaded constructor takes username, password, and IP address as input parameters. Every API offered throws an exception if it occurs.
2.7.1 API table : Name Description Input
Params Returns
Initialize Initializes GeneralInfo interface and its private data members
Username: String Password : String IPAddr : String Or CommonDef
None
getCoreVersion Gets the core version information of Intel AMT
None String
getCodeVersions Returns more detailed version information of various Intel AMT subsystems, which includes BIOS, Build number, revision, etc.
None String
getProvisioningMode Returns the current provisioning mode of Intel AMT
None String
getProvisioningState Returns the current provisioning state of a machine.
None String
getHostName Returns the host name of the machine
None String
GetConfigServerInfo Reads the Configuration server information from Intel Intel AMT.
None String
GetAdminAclEntryStatus Reads the Admin ACL Entry status from Intel Intel AMT.
None Boolean
GetAdminNetAclEntryStatus Reads the Admin NET ACL Entry status from Intel Intel AMT
None Boolean
GetEnabledInterface Gets the enabled state of various features or interfaces of the Intel Intel AMT device.
None String
getNetworkState Reads Network State information from Intel Intel AMT.
None Boolean
getSecurityParameters Reads local interface security None SecurityParam
Intel® AMT RDK API Guide
12 Intel Confidential
parameters getIderSessionLog Reads the IDER session log None String getVLANParameters Reads VLAN parameters None string
2.8 CapabilityDiscovery Description : This building block encapsulates functionality such as identifying an Intel AMT enabled machine ( locally and from the remote side also ). This building block uses two interfaces of Intel AMT such as the GeneralInfo interface and the SecurityAdmin interface. The reason it uses two interfaces is because the GeneralInfo interface is not available for Intel AMT 1.0. Both interfaces offer APIs such as GetCoreVersion. This building block parses data returned by GetCoreVersion and makes the decision whether the querying machine is Intel AMT-enabled or not. It offers default and overloaded constructors. The overloaded constructor takes username, password, and IP address as input parameters. Every API offered throws and exception if it occurs.
2.8.1 API table : Name Description Input
Params Returns
IsMachineAMTEnabled_GI This method checks the machine’s Intel AMT capabilities using GeneralInfo interface. It returns true if the machine is Intel AMT enabled, otherwise false. This API is designed to work on local Intel AMT machines as well as on remote Intel AMT machines. Use this API on machines with Intel AMT 2.0 or greater only.
None Int
IsMachineAMTEnabled_SA This method checks the machine’s Intel AMT capabilities using SecurityAdmin interface. It returns true if machine is Intel AMT enabled otherwise false. This API is designed to work only from a remote machine since the SecurityAdmin interface is available from remote side for Intel AMT 1.0. This API can be used on any Intel AMT.
None Int
getMajorVersion This method returns the Intel AMT major version. This API should be called only after successful return of above two API to get the AMT version.
None Int
2.8.2 Usage Example: String Username= new String(”admin”); String Password= new String(”P@ssw0rd”); String IPAddress= new String(”192.168.0.6”); try { CapabilityDiscovery cd = new CapabilityDiscovery(Username, Password, IPAddress); boolean bRet = cd. IsMachineAMTEnabled_SA();
Intel® AMT RDK API Guide
Intel Confidential 13
int status = cd.getStatusCode(); PtStatus pt = new PtStatus(); if(status == 0 && bRet == true) { // This is Intel AMT enabled machine } else if(status == 0) { // This machine does not support Intel AMT (Intel® vPro technology) } else { // Generally error condition. Error occurred. String str = pt.getStatusString(status); } } catch(Exception e) { e.printStackTrace(); }
2.9 Remote Control Description : This building block encapsulates all the functionality offered by the Remote Control Interface of Intel AMT. The Remote Control Interface is part of the Out-of-band functionality of Intel AMT. It exposes user friendly APIs to perform specific operations and hides all communication details with the Intel AMT subsystem. It offers default and overloaded constructors. The overloaded constructor takes username, password, and IP address as input parameters. Every API offered throws an exception if it occurs.
2.9.1 API table : Name Description Input
Params Returns
Initialize Initializes remote control out-of-band interface and private data members
Username: String Password : String IPAddr : String
None
Uninitialize Uninitialized private data members None None getSystemPowerState Returns current system power state None Int getRemoteControlCapabilities Returns remote control capabilities
reported by Intel AMT subsystem ( such as command, special command, system FW capabilities supported, etc…)
None String
Reset Issues reset commands to Intel AMT subsystem. Causes low latency reset of the system ( resets host processor and causes PCI Reset# to be asserted )
None Int
powerOff Issues unconditional power down function to Intel AMT subsystem which forces system to enter in S5 state
Non Int
powerOn Issues power ON to Intel AMT subsystem which puts sleeping system in S0/G0 “working state”
None Int
powerCycleReset Issues hard reset to the Intel AMT subsystem followed by power op command
None Int
forcePXEBoot Issues PXE boot command to Intel AMT subsystem followed by
None Int
Intel® AMT RDK API Guide
14 Intel Confidential
“Reset” command. On next boot, Intel AMT system will boot from PXE ROM image
forceHDDBoot Issues special command with special command parameter as 2 which identifies boot media index for managing client, followed by “Reset” so that on next boot, Intel AMT system will be forced to boot from Hard Drive
None Int
forceHDDSafeModeBoot Issues special command with special command parameter as 0 (default hard drive is booted in safe mode) for managed client followed by “Reset” so that on next boot, Intel AMT system will be forced to boot from Hard Drive in safe mode
None Int
forceDiagnosticsBoot Issues special command to boot from diagnostics media followed by “Reset” command.
None Int
forceCdOrDvdBoot Issues special command to boot from local CD or DVD drive for managed client followed by “Reset” command
None Int
useSOL_BIOS_Pause Issues special command to redirect BIOS on management console (machine from which SOL session is established) and pause into BIOS
None Int
useSOL_BIOS_Setup Issues special command to redirect BIOS on management console (machine from which SOL session is established) and enter into BIOS setup
None Int
useIDER_floppy Issues special command to boot from redirected floppy device . An IDE-R session must be established before calling this API. As a result of this method, the managed machine(node) will boot from the image in the floppy drive of management console.
None Int
useIDER_CD Issues special command to boot from redirected CD device . An IDE-R session must be established before calling this API. As a result of this method, managed machine(node) will boot from the image in the CD drive of management console.
None Int
useSOL_IDER_Floppy Precondition : Make sure SOL and IDE-R session are established with managed node. This API issues a command to the managed node to boot from a redirected floppy device and redirect serial terminal and display on management console
None Int
useSOL_IDER_CD Precondition : Make sure SOL and IDER session are established with managed node. This API issues a command to the
None Int
Intel® AMT RDK API Guide
Intel Confidential 15
managed node to boot from a redirected CD device and redirect serial terminal and display on management console
Intel® AMT RDK API Guide
16 Intel Confidential
2.9.2 Usage Example: String Username= new String(”admin”); String Password= new String(”P@ssw0rd”); String IPAddress= new String(”192.168.0.6”); try { RemoteControl rc = new RemoteControl(Username, Password, IPAddress); String strCap = rc.getRemoteControlCapabilities(); if(strCap.length() > 0) { // do something with return string } else { // error condition long errcode = rc.getErrorCode(); // Using that error code fetch appropriate error message from PtStaus // helper class } } catch(Exception e) { e.printStackTrace(); }
Intel® AMT RDK API Guide
Intel Confidential 17
2.10 Hardware Asset Description : This building block encapsulates all the functionality offered by the Hardware Asset Interface of Intel AMT, which is a part of Intel AMT’s out-of-band functionality. It exposes user friendly APIs to perform specific operation and hides all communication details with the Intel AMT enabled platform. It offers default and overloaded constructors. The overloaded constructor takes username, password, and IP address as input parameters. All API offered throw an exception if it occurs.
2.10.1 API table : Name Description Input
Parameters Returns
Initialize Initializes hardware asset out-of-band interface and private data members. This is a overloaded method.
Username: String Password : String IPAddr : String Or CommonDef : object
None
hwAssetDisplayAll Returns Hardware Asset Information of all Asset Types such as BIOS, Processor, Memory, Field Replaceable Units, Baseboard, etc...
None Asset : String (null in case of error)
hwAssetDisplay Returns Hardware Asset Information of given asset type
Type : Int Asset : String (null in case of error)
getStatusCode Returns status code return by previously executed API. This API should be called if previous API returns an unexpected result (e.g. if hwAssetDisplay returns null then application should call this API to determine the reason of error).
None Status : int
getCount Returns the total instance of this class. This API is provided to help debugging the application
None Count : Int
2.10.2 Usage Example: String Username= new String(”admin”); String Password= new String(”P@ssw0rd”); String IPAddress= new String(”192.168.0.6”); try { DebugMgr.dbgMsg(“Invoking Hardware Asset Interface”); HardwareAssetInterface sa = new HardwareAssetInterface(Username, Password, IPAddress); String hwAsset = sa.hwAssetDisplayAll(); if(hwAsset.length() > 0) { // do something with return string DebugMgr.dbgMsg(“Successfully retrieved Hardware Asset”); } else { // error condition long errcode = sa.getStatus();
Intel® AMT RDK API Guide
18 Intel Confidential
// Using that error code fetch appropriate error message from PtStaus // helper class PtStatus pt = new PtStatus(); System.out.println(pt.getStatusString(errcode)); } } catch(Exception e) { e.printStackTrace(); }
2.11 Network Admin Description : This building block encapsulates all the functionality offered by the Network Administration Interface of Intel AMT. The Network Administration Interface is part of the Out-of-band functionality of Intel AMT. It abstracts communication details with the Intel AMT subsystem. Every API offered by this building block throws an exception if it occurs. This building block is intended to be use while changing any of the Ipv4 parameters of the Intel AMT subsystem. Once the API is used from this building block, use the API of “Security Admin” building block to commit changes.
2.11.1 API table: Name Description Input
Params Returns
Initialize Initializes remote control out-of-band interface and private data members
Username: String Password : String IPAddr : String
None
Uninitialize Uninitialized private data members None None getHostName Returns a host name of Intel AMT
sysbsystem None String
setHostName Ssets host name for Intel AMT subsystem
String int
setPingResponse Sets ping response for Intel AMT subsystem (how Intel AMT subsystem should respond to ping request)
Boolean int
setVLANParameters Sets VLAN parameters for Intel AMT subsystem such as VLAN enabled/disabled and, if VLAN is enabled, then sets VLANtag value
Boolean Int
int
setIPv4Parameters Sets IPv4 parameters for the Intel AMT subsystem such as DHCP mode, domain name, localaddress, etc...
int dhcpmode, String domainname, String localaddress, String subnetmask, String gatewayaddress, String primaryDNS, String secondaryDNS
int
setIPv4Parameters This is an overloaded method to set IPv4 parameters for the Intel AMT subsystem such as DHCP mode, domain name, localaddress, etc...
NetworkParamDefs (instance of this common class)
int
getVLANParameters Sets IPv4 parameters for the Intel AMT sybsystem such as DHCP mode, domain name, localaddress, etc...
None VLANParam (instance of VLANParam common class)
getPingResponse Gets ping response from the Intel AMT subsystem.
None Boolean
getIPv4Settings Returns Ipv4 parameters such as None NetworkParamDefs
Intel® AMT RDK API Guide
Intel Confidential 19
DHCP mode, domain name, local address, etc
2.11.2 Usage Example: try { NetworkAdminInterface networkSettings = new NetworkAdminInterface("192.168.0.6","admin", "P@ssw0rd"); SecSettings ss = new SecSettings("192.168.0.6","admin", "P@ssw0rd"); int ret = networkSettings.setHostName("amtMachine1"); if(ret == 1) { System.out.println("Success : networkSettings.SetHostName"); // commit changes via. security admin interface method ret = ss.SaveChanges(); if(ret == 1) { System.out.println("Success : ss.SaveChanges"); System.out.println("Verify that Host name has really changes"); // confirm the changes String str = networkSettings.getHostName(); System.out.println("Success : New host name " + str + "\n"); } } } catch(Exception e) { e.printStackTrace(); }
Intel® AMT RDK API Guide
20 Intel Confidential
2.12 Security Admin Description : This building block encapsulates functionality offered by the Security Admin interface and provides a higher level of abstraction in terms of API. Currently it is scoped to provide only one API to commit changes to network parameters (TCP and TLS parameters). It does not offer APIs to perform any changes to TLS parameters. It can be extended to provide relevant APIs to perform any changes to TLS parameters.
2.12.1 API table: Name Description Input
Params Returns
public int SaveChanges() throws Exception
This API will commit changes made for network parameters such as TCP/IP settings (DHCP mode, domain name, local addres, subnet mask, etc.. ), and TLS parameters
None Int – status, returns 1 if successful otherwise errorcode
Intel® AMT RDK API Guide
Intel Confidential 21
2.13 Storage Admin Description : This building block encapsulates all the functionality offered by Storage Admin Interface of Intel AMT, which is a part of Intel AMT’s out-of-band functionality. It exposes user friendly APIs to perform specific operation and hides all communication details with the Intel AMT enabled platform. It offers default and overloaded constructors. The overloaded constructor takes username, password, and IP address as input parameters. All APIs offered throw an exception if it occurs. The API exposed by this building block can be used to build a storage audit capability in the management console. It exposes an API to list registered enterprise, factory partner, and registered applications. It also provides the capability to add, delete and modify the entries. This block provides a utility method to facilitate data caching in local data structures for faster response.
2.13.1 API table : Name Description Input
Parameters Returns
Initialize Initializes storage admin out-of-band interface and private data members. It is a overloaded method.
Username: String Password : String IPAddr : String Or CommonDef : object
None
listStorageEaclEntries Returns a list of all the EACL entries that exist in 3PDS, along with Handles. It may return a null object in case of error during execution. Call getStatusCode API to get the status code. It returns “” string if no entry exists.
None List : String (null in case of error)
addStorageEaclEntery Adds an entry for enterprise into 3PDS, and returns status of execution.
Enterprise Name : String
Status : int
removeStorageEaclEntery Removes an existing enterprise entry from 3PDS, and returns status of execution.
Handle : int Status: int
listStorageAllocEntries Returns a list of all the FACL entries exist in 3PDS, along with handles. It may return a null object in case of error during execution. Call getStatusCode API to get the status code. It returns “” string if no entry exists.
None List : String (null in case of error)
addStorageFpaclEntery Adds an entry for FPACL into 3PDS, and returns status of execution.
Vendor Name : String App Name : String Allocation size : int (Multiple of 4KB)
Status : int
removeStorageFpaclEntery Removes an existing FPACL entry from 3PDS, and returns status of execution.
Handle : Int Status : int
updateStorageFpaclEntery Updates an existing FPACL entry into 3PDS, and returns status of execution.
Handle : int Allocation size : int (multiple of 4KB)
Status : int
getGlobalStorageAttributes Returns the list of 3PDS attributes. It may return a null object in case of an
None List : String (null in case of
Intel® AMT RDK API Guide
22 Intel Confidential
error in execution of API. Call getStatusCode API to get the status code.
error)
setGlobalStorageAttributes Updates the allocation size for Partner and Non-partner storage area. Returns the status of this API.
Max partner area : int Max non-partner area : short
Status : int
listRegisteredApplications Returns a list of all the registered applications into 3PDS, along with Handles. It may return a null object in case of error during execution. Call getStatusCode API to get the status code. It returns “” string if no entry exists.
None List : String (null in case of error)
adminRemoveApplication Removes the entry for a registered application from 3PDS, and returns the status of execution.
Handle : int Status : int
loadData This is a utility API. It loads the EACL, FPACL, and registered application data into local cache for future use.
None Status : int
getEnames Returns a list of enterprises registered on a given machine.
None Enterprise list : Object [EntEntry]
getFpacl Returns a list of vendor and application names for a given machine.
None List : Object [FpaclEntry]
getRegApp Returns a list of all registered applications along with the details
None List : Object [RegAppEntry]
getStatusCode Returns status code returned by previously executed API. This API should be called if previous API returned an unexpected result (e.g. if listStorageEaclEntries returns null then the application should call this API to determine the reason for the error).
None int
getCount Returns the total instance of this class. This API is provided to help with debugging the application.
None Int
2.13.2 Usage Example: String Username= new String(”admin”); String Password= new String(”P@ssw0rd”); String IPAddress= new String(”192.168.0.6”); try { DebugMgr.dbgMsg(“Invoking Storage Admin Interface”); StorageAdminInterface sa = new StorageAdminInterface(Username, Password, IPAddress); PtStatus pt = new PtStatus (); int a = sa.loadData(); System.out.println(pt.getStatusString(a)); for (int i =0; i <sa.getEnames().length; i++){ System.out.println(sa.getEnames()[i].getEname()); } String flist;
Intel® AMT RDK API Guide
Intel Confidential 23
if ((flist = sa.listStorageAllocEntries()) == null){ System.out.println("Status: " + pt.getStatusString(sa.getStatusCode())); } System.out.println(flist); } catch(Exception e) { e.printStackTrace(); }
2.14 Event Management Description: This Event Manager building block presents an interface to access Intel® AMT event manager service for configuring and monitoring event behavior of the managed Intel AMT clients. The interface is presented in Java classes for supporting both Windows* and Linux* platforms. EventManager is the main class for accessing most of the event functions, such as configuring event filters, monitoring event logs, etc. EventAlertAdapter embeds an alert (SNMP/PET) daemon, which runs in a separate thread, to receive the alerts sent from managed Intel AMT clients and provides a mechanism for customizing how to handle the alerts. To do that, an implementation of EventAlertListener interface needs to be created and registered into EventAlertAdapter. Besides, a set of classes are defined for accessing the common data structures used in this building block, i.e. EventAlertSubscription, EvengLogStatus, EventFilter, EventSensor, EventLog, and EventAlert.
2.14.1 API Tables: • EventManager – function class
Name Description Input Params Returns
EventManager Initializes an EventManager instance and sets target Intel AMT client to “target”. All the information for establishing connection to “target” is encapsulated in CommonDef class.
target: CommonDef
setTarget Sets target Intel AMT client to “target”. All the information for establishing connection to “target” is encapsulated in CommonDef class.
target: CommonDef
void
enumerateEventFilters Returns all event filters configured. The two parameters are optional. If they are present, just returns a range (totally “number” from “start”). Otherwise return all.
start: int number: int
EventFilter[]
Intel® AMT RDK API Guide
24 Intel Confidential
addEventFilter Adds a new event filter, and presents the filter handle in the returned EventFilter instance.
filter: EventFilter EventFilter
updateEventFilter Updates an existed event filter specified by the handle in the filter parameter.
filter: EventFilter void
removeEventFilter Removes an existed event filter specified by the handle in the filter parameter.
filter: EventFilter void
removeAllEventFilters Removes all event filters. None void enumerateAlertSubscriptions Returns alert subscriptions.
The two parameters are optional. If they are present, just returns a range (totally “number” from “start”). Otherwise return all.
start: int number: int
AlertSubscription[]
addAlertSubscription Adds a new alert subscription – register the address to the specified policyID.
policyID: int address: String
void
removeAlertSubscription Removes an alert subscription – unregister the address from the specified policyID.
policyID: int address: String
void
removeAllAlertSubscriptions Removes all alert subscriptions. None void getEventLogStatus Returns event log status, which contains the
number of records, the number of free records, most recent log record timestamp, and whether the event logging is enabled.
None EventLogStatus
enumerateEventLogRecords Returns event log records. The two parameters are optional. If they are present, just returns a range (totally “number” from “start”). Otherwise return all.
start: int number: int
EventLog[]
clearEventLog Removes all event log records. None void freezeEventLog Disables/Enables event logging. freeze: boolean void enumerateSensors Returns the attributes of the sensors of the
Intel AMT client. The two parameters are optional. If they are present, just returns a range (totally “number” from “start”). Otherwise return all.
start: int number: int
EventSensor[]
getEventLogTimestampClock Returns current time of event log timestamp clock.
None int
setEventLogTimestampClock Sets event log timestamp clock. int void getAlertCommunityString Returns community string. Community
String will be used in event alert. None String
setAlertCommunityString Sets community string. Community String will be used in event alert.
communityString: String
void
• EventAlertListener – interface
Name Description Input Params Returns
handleAlert Invoked by the EventAlertAdapter class to handles the arriving event alert. This is an interface method which must be implemented by the developers who use this feature.
alert: EventAlert void
• EventAlertAdapter – function class
Name Description Input Params Returns
addAlertListener Registers a new alert listener. Listener: EventAlertListener
void
removeAlertListener Removes a specified alert listener which is already registered.
Listener: EventAlertListener
void
removeAllAlertListener Removes all alert listener registered. None void isActive Returns whether the alert (SNMP/PET)
daemon is active. None boolean
startReceive Starts the alert (SNMP/PET) daemon. None void stoptReceive Stops the alert (SNMP/PET) daemon. None void
Intel® AMT RDK API Guide
Intel Confidential 25
• AlertSubscription – data structure class
Name Description Input Params Returns
getPolicyID Returns the policyID of the alert subscription. None int getDestinationAddresses Returns the destination addresses for the
alert subscription. None String[]
• EventLogStatus – data structure class
Name Description Input Params Returns
getNumberOfRecords Returns the number of existed log records. None int getNumberOfFreeRecords Returns the number of free entries for log
records. None int
getMostRecentTimestamp Returns timestamp of the most recent log record.
None int
isFrozen Returns whether the logging is disabled. None boolean • EventFilter – data structure class
Name Description Input Params Returns
getNumberOfFields Returns the number of the fields defined in EventFilter class. It is a static method.
None int
getFieldName Returns the name of the field specified by index in FIELD_NAME (enum type) for EventFilter class. It is a static method.
index: int FIELD_NAME
getFieldNameString Returns the name of the field specified by index in String for EventFilter class. It is a static method.
index: int String
getFieldType Returns the value type of the field specified by field name for EventFilter class. It is a static method.
name: FIELD_NAME FIELD_TYPE
getFieldValue Returns the value of the field specified by field name for an EventFilter instance.
name: FIELD_NAME Object
getFieldInterpretation Returns the interpretation of the field specified by field name for an EventFilter instance.
name: FIELD_NAME String
getDescription Returns the general description for an EventFilter instance.
None String
getEventSensorType Returns value of event sensor type field. None int setEventSensorType Sets value of event sensor type field. value: int void getEventType Returns value of event type field. None int setEventType Sets value of event type field. value: int void getEventOffset Returns value of event offset field. None int setEventOffset Sets value of event offset field. value: int void getEventSourceType Returns value of event source type field. None int setEventSourceType Sets value of event source type field. value: int void getEventSeverity Returns value of event severity field. None int setEventSeverity Sets value of event severity field. value: int void getSensorDevice Returns value of sensor device field. None int setSensorDevice Sets value of sensor device field. value: int void getSensorNumber Returns value of sensor number field. None int setSensorNumber Sets value of sensor number field. value: int void getEntity Returns value of entity field. None int setEntity Sets value of entity field. value: int void getEntityInstance Returns value of entity data field. None int setEntityInstance Sets value of entity data field. value: int void isEnabled Returns whether the event filter is enabled. None boolean setEnabled Sets whether the event filter is enabled. value: boolean void
Intel® AMT RDK API Guide
26 Intel Confidential
isLogEnabled Returns whether the matched events will be logged.
None boolean
setLogEnabled Sets whether the matched events will be logged.
value: boolean void
isAlertEnabled Returns whether the matched events will be sent for alert.
None boolean
setLogEnabled Sets whether the matched events will be sent for alert.
value: boolean void
getConfigureType Returns value of configure type field. None int setConfigureType Sets value of configure type field. value: int void getAlertSubscriptionPolicyID Returns value of alert subscription policy
ID field. None int
setAlertSubscriptionPolicyID Sets value of alert subscription policy ID field.
value: int void
getHandle Returns value of event filter handle field. None int setHandle Sets value of event filter handle field. value: int void EventFilter Create an EventFilter instance to match a
specific event defined in Event.EVENT (enum type). If the optional event parameter is missing, a default match-all event will be used.
event: Event.EVENT (optional)
setFieldValue Sets the value of the field specified by field name for an EventFilter instance.
name: FIELD_NAME value: Object
void
getFieldInterpretationList Returns all possible value of the specified field for an EventFilter instance. Typically it can be used to display the possible value entries in a ComboBox and allow the user to select the entry of interest.
name: FIELD_NAME String[]
isFieldMatchAll Returns whether the specified field allows a single value to match all.
name: FIELD_NAME
boolean
getFieldValueIndex Gets the value index of the field specified by field name for an EventFilter instance. The index is to the value array got from getFieldInterpretationList() method.
name: FIELD_NAME
int
setFieldValueIndex Sets the value of the field specified by field name for an EventFilter instance. The input value is an index to the value array got from getFieldInterpretationList() method.
name: FIELD_NAME valueIndex: int
void
• EventSensor – data structure class
Name Description Input Params Returns
getNumberOfFields Returns the number of the fields defined in EventSensor class. It is a static method.
None int
getFieldName Returns the name of the field specified by index in FIELD_NAME (enum type) for EventSensor class. It is a static method.
index: int FIELD_NAME
getFieldNameString Returns the name of the field specified by index in String for EventSensor class. It is a static method.
index: int String
getFieldType Returns the value type of the field specified by field name for EventSensor class. It is a static method.
name: FIELD_NAME
FIELD_TYPE
getFieldValue Returns the value of the field specified by field name for an EventSensor instance.
name: FIELD_NAME
Object
getFieldInterpretation Returns the interpretation of the field specified by field name for an EventSensor instance.
name: FIELD_NAME
String
getDescription Returns the general description for an EventSensor instance.
None String
Intel® AMT RDK API Guide
Intel Confidential 27
getEventSensorType Returns value of event sensor type field. None int getEventType Returns value of event type field. None int getEventOffset Returns value of event offset field. None int getEventSourceType Returns value of event source type field. None int getEventSeverity Returns value of event severity field. None int getSensorDevice Returns value of sensor device field. None int getSensorNumber Returns value of sensor number field. None int getEntity Returns value of entity field. None int getEntityInstance Returns value of entity data field. None int isLegacySensor Returns whether it is a legacy sensor. None boolean isAssertionEvent Returns whether it generates assertion event. None boolean isDeassertionEvent Returns whether it generates de-assertion
events. None boolean
getIndex Returns value of index field. None int • EventLog – data structure class
Name Description Input Params Returns
getNumberOfFields Returns the number of the fields defined in EventLog class. It is a static method.
None Int
getFieldName Returns the name of the field specified by index in FIELD_NAME (enum type) for EventLog class. It is a static method.
index: int FIELD_NAME
getFieldNameString Returns the name of the field specified by index in String for EventLog class. It is a static method.
index: int String
getFieldType Returns the value type of the field specified by field name for EventLog class. It is a static method.
name: FIELD_NAME
FIELD_TYPE
getFieldValue Returns the value of the field specified by field name for an EventLog instance.
name: FIELD_NAME
Object
getFieldInterpretation Returns the interpretation of the field specified by field name for an EventLog instance.
name: FIELD_NAME
String
getDescription Returns the general description for an EventLog instance.
None String
getEventSensorType Returns value of event sensor type field. None int getEventType Returns value of event type field. None int getEventOffset Returns value of event offset field. None int getEventSourceType Returns value of event source type field. None int getEventSeverity Returns value of event severity field. None int getSensorDevice Returns value of sensor device field. None int getSensorNumber Returns value of sensor number field. None int getEntity Returns value of entity field. None int getEntityInstance Returns value of entity data field. None int getEventData Returns value of event data field. None byte[] getTimestamp Returns value of timestamp field. None int • EventAlert – data structure class
Name Description Input Params Returns
getNumberOfFields Returns the number of the fields defined in EventAlert class. It is a static method.
None int
getFieldName Returns the name of the field specified by index in FIELD_NAME (enum type) for EventAlert class. It is a static method.
index: int FIELD_NAME
getFieldNameString Returns the name of the field specified by index in String for EventAlert class. It is a
index: int String
Intel® AMT RDK API Guide
28 Intel Confidential
static method. getFieldType Returns the value type of the field specified
by field name for EventAlert class. It is a static method.
name: FIELD_NAME
FIELD_TYPE
getFieldValue Returns the value of the field specified by field name for an EventAlert instance.
name: FIELD_NAME
Object
getFieldInterpretation Returns the interpretation of the field specified by field name for an EventAlert instance.
name: FIELD_NAME
String
getDescription Returns the general description for an EventAlert instance.
None String
getEventSensorType Returns value of event sensor type field. None int getEventType Returns value of event type field. None int getEventOffset Returns value of event offset field. None int getEventSourceType Returns value of event source type field. None int getEventSeverity Returns value of event severity field. None int getSensorDevice Returns value of sensor device field. None int getSensorNumber Returns value of sensor number field. None int getEntity Returns value of entity field. None int getEntityInstance Returns value of entity data field. None int getEventData Returns value of event data field. None byte[] getSNMPVersion Returns value of SNMP version field. None int getSNMPCommunityString Returns value of SNMP community string
field. None String
getSNMPEnterprise Returns value of SNMP enterprise OID field. None String getSNMPAgentAddress Returns value of SNMP agent address field. None String getSNMPTimestamp Returns value of SNMP timestamp field. None int getGUID Returns value of GUID field. None byte[] getSequence Returns value of sequence field. None int getLocalTimestamp Returns value of local timestamp field. None int getUTCOffset Returns value of UTC offset field. None int getTrapSourceType Returns value of trap source type field. None int getLanguageCode Returns value of language code field. None int getManufacturerID Returns value of manufacturer ID field. None int getSystemID Returns value of system ID field. None int getOEMCustomerFields Returns value of “OEM customer fields” field. None byte[] • Event.EVENT – enum Enumeration for pre-defined events supported in this Event Manager building block. This can be used to create specific event filters. All AMT 2.0 events are supported in this version (refer to Section 8.0 in Network Design Guide document in SDK) Name Description MATCH_ALL The default to match all events. AMT_LINK_UP AMT self generated link up event. AMT_WATCHDOG_DEFAULT AMT self generated default watch dog event. AMT_WATCHDOG_OS_HANG AMT self generated OS hang watch dog event. AMT_PASSWORD_ATTACK AMT self generated password attack event. AMT_CIRCUIT_BREAKER_ALERT AMT self generated circuit breaker event. AMT_AGENT_PRESENCE_ALERT AMT self generated agent presence event. AMT_NETWORK_ADAPTER_STATE_TAMPERED AMT self generated network adapter state
tampered event. AMT_FIRMWARE_UPDATE AMT self generated firmware update event. AMT_BRING_UP_CPU_MISSING AMT self generated bring up event – CPU missing. AMT_BRING_UP_CPU_DEAD_ON_ARRIAVL AMT self generated bring up event – CPU dead on
arrival. AMT_BRING_UP_DIMM_MISSING_OR_NOT_FUNCTIONAL AMT self generated bring up event – DIMM missing
or not functional. AMT_BRING_UP_BIOS_HANG AMT self generated bring up event – BIOS hang.
Intel® AMT RDK API Guide
Intel Confidential 29
• Event.FIELD_NAME – enum Enumeration for the name of various fields defined in the event data structures (EventFilter, EventSensor, EvengLog and EventAlert). Name Description Event_Sensor_Type EventFilter/EventSensor/EventLog/EventAlert –
event sensor type. Refer to PET specification. Event_Type EventFilter/EventSensor/EventLog/EventAlert –
event type. Refer to PET specification. Event_Offset EventFilter/EventSensor/EventLog/EventAlert –
event offset. Refer to PET specification. Event_Source_Type EventFilter/EventSensor/EventLog/EventAlert –
event source type. Refer to PET specification. Event_Severity EventFilter/EventSensor/EventLog/EventAlert –
event severity. Refer to PET specification. Sensor_Device EventFilter/EventSensor/EventLog/EventAlert –
sensor device. Refer to PET specification. Sensor_Number EventFilter/EventSensor/EventLog/EventAlert –
sensor number. Refer to PET specification. Entity EventFilter/EventSensor/EventLog/EventAlert –
entity. Refer to PET specification. Entity_Instance EventFilter/EventSensor/EventLog/EventAlert –
entity instance. Refer to PET specification. Enabled EventFilter – whether the filter is enabled. Log_Enabled EventFilter – whether the events match this filter
will be logged in AMT client. Alert_Enabled EventFilter – whether the events match this filter
will trigger alerts to the subscribers. Configure_Type EventFilter – configuration type. Alert_Policy_ID EventFilter – alert policy ID. Alerts will be sent to all
subscribers registered for this policy. Legacy_Sensor EventSensor – whehter this sensor is a legacy
sensor. Assertion_Event EventSensor – assertion event. Deassertion_Event EventSensor – de-assertion event. Index EventSensor – index. Timestamp EventLog – timestamp. Event_Data EventLog/EventAlert – event data, to provide
additional parameters. SNMP_Version EventAlert – SNMP version. SNMP_Community_String EventAlert – SNMP community string. SNMP_Enterprise EventAlert – SNMP enterprise OID. SNMP_Agent_Address EventAlert – SNMP agent address. SNMP_Timestamp EventAlert – SNMP timestamp. GUID EventAlert – GUID. Sequence EventAlert – sequence. Local_Timestamp EventAlert – local timestamp. UTC_Offset EventAlert – UTC offset. Trap_Source_Type EventAlert – trap source type. Language_Code EventAlert – language code. Manufacturer_Id EventAlert – manufacturer ID. System_Id EventAlert – system ID. OEM_Custom_Fields EventAlert – OEM customer fields. • Event.FIELD_TYPE – enum Enumeration for the value type of various fields defined in the event data structures (event filter, event sensor, event log and event alert). Name Description BOOLEAN Value type of the field is boolean. INTEGER Value type of the field is integer.
Intel® AMT RDK API Guide
30 Intel Confidential
BYTEARRAY Value type of the field is byte[]. STRING Value type of the field is String. • Constants Name Type Value Description SEVERITY_UNSPECFIED public static final int 0x00 Event severity is not specified. SEVERITY_MONITOR public static final int 0x01 Event severity is monitor. SEVERITY_INFORMATION public static final int 0x02 Event severity is information. SEVERITY_OK public static final int 0x04 Event severity is OK. SEVERITY_NON_CRITICAL_CONDITION public static final int 0x08 Event severity is non-critical. SEVERITY_CRITICAL_CONDITION public static final int 0x10 Event severity is critical. SEVERITY_NON_RECOVERABLE_CONDITION public static final int 0x20 Event severity is non-
recoverable.
2.14.2 Limitation: 1. Certain methods for event manager interface need to interact with the managed client more than once for a specific
task (e.g. enumrateEventFilter can only get no more than 10 entries in one round interaction). Therefore, it cannot guarantee operation successful in case of other managed consoles work on event manager interface simultaneously.
2. For event alerting which is encapsulated in SNMP/PET packets, this building block will provide a simple SNMP/PET datagram handler while it may conflict with other running SNMP handler daemon. Therefore, this building block assumes that there is no other SNMP handler daemon is running on the system; otherwise it assumes that the currently running SNMP handler daemon will also handle the PET/event alert packets.
2.14.3 Usage Example: String Username = "admin"; String Password = "P@ssw0rd"; String ClientAddress = "192.168.0.6"; try { int policyID = 100; String localAddress = InetAddress.getLocalHost().getHostAddress(); /* create EventManager object for access AMT features (SMB mode) */ CommonDef cd = new CommonDef(ClientAddress, Username, Password); EventManager em = new EventManager(cd); /* start alert (SNMP/PET) daemon and register alert listener */ EventAlertAdapter alertDaemon = new EventAlertAdapter(); EventAlertListener alertListener = new EventAlertListener() { /* create an implementation of EventAlertListener to handle the alerts */ public void handleAlert(EventAlert alert) { for (int i = 0; i < EventAlert.getNumberOfFields(); i++) { Event.FIELD_NAME name = EventAlert.getFieldName(i); System.out.println(EventAlert.getFieldNameString(name) + ": " + alert.getFieldValue(name)); } } }; alertDaemon.addAlertListener(alertListener); alertDaemon.startReceive(); /* configure one event filter (matches all events) to log and * send alert (to local host) for all events */ EventFilter filter = new EventFilter(); filter.setAlertSubscriptionPolicyID(policyID); filter = em.addEventFilter(filter);
Intel® AMT RDK API Guide
Intel Confidential 31
em.addAlertSubscription(policyID, localAddress); /* enumerate existing event log records */ EventLog[] logs = em.enumerateEventLogRecords(); for (int i = 0; i < logs.length; i++) { for (int j = 0; j < EventLog.getNumberOfFields(); j++) { Event.FIELD_NAME name = EventLog.getFieldName(j); System.out.println(EventLog.getFieldNameString(name) + ": " + logs[j].getFieldValue(name) + "\n"); } } /* remove the filter */ em.removeEventFilter(filter); /* remove the alert subscription */ em.removeAlertSubscription(policyID, localAddress); } catch(Exception e) { e.printStackTrace(); }
Intel® AMT RDK API Guide
32 Intel Confidential
2.15 System Defense (also known as Circuit Breaker) Description: This building block encapsulates all the functionality offered by the Circuit Breaker Interface of Intel AMT. The Circuit Breaker Interface is part of the Out-of-band functionality of Intel AMT. It hides low level details of the Web Service interfaces provided by the Intel AMT Circuit Breaker module, abstracts those interfaces, and provides some high level, easier-to-use APIs which cover all of the functionalities of Circuit Breaker feature. Each API function offered by this building block throws an exception if it occurs. The building block generally provides three types of operating modes:
• Default mode Under Default Mode, all filters will take effect immediately after they are enabled.
To Enter Default Mode, the user calls setOpType(CircuitBreakerInterface.OPTYPE_CB);
• Agent Presence (AP) mode
Under AP mode, all filters will NOT take effect immediately after they are enabled. Instead, they will take effect when the state of a specific agent is changed.
To Enter AP Mode, the user calls setOpType(CircuitBreakerInterface.OPTYPE_AP);
• Expert mode
The building block also has an internal operating mode called Expert mode which is used to create and modify customized policies. (A policy is defined as a series of filters.) The upper layer application can switch between the expert mode, default mode, and AP mode. When the building block is running in the expert mode all filter operations are mapped and used to create policies. To enter and exit Expert mode and create custom policies, the user calls beginCreatePolicy(); // Filter creations… int policyCreated = endCreatePolicy(); After that the operating mode will be restored to the original one before switching into Expert mode.
The building block provides several API functions to let the user get or set current operating mode. The operating mode is maintained inside the CB building block and acts as one of the guidance parameters when a specific filter is being enabled and added to the Intel AMT client. For detailed information about these two functions see the API table below. From the functionality perspective regarding the filters themselves, the building block provides three types of functions:
• Information retrieval o The building block provides a series of APIs for information retrieval, including:
Get all Hardware capacities of the managed client Get all policies Get all filters in the active policy Get all filters in a specific policy Get information of a specific filter
• Monitoring The building block provides some monitoring functionalities by utilizing low level Web Service methods provided by the Circuit Breaker interface, such as retrieving the statistical data of the network traffic passing through a specific port or the traffic to or from a specific IP address. This type of functions does not change the behavior of the managed client. The following functions are provided by this building block:
Intel® AMT RDK API Guide
Intel Confidential 33
• Enable monitoring the entire network traffic • Enable monitoring the network traffic of a TCP port • Enable monitoring the network traffic of a UDP port • Enable monitoring the network traffic from an IP address • Enable monitoring the network traffic of a TCP connection from (IP : port) • Enable monitoring the network traffic of a UDP service from (IP : port) • Get statistical monitoring data • Disable a specific monitor • Disable all monitors
• Filtering
The building block provides some filtering functionalities by utilizing low level Web Service methods provided by the Circuit Breaker interface, such as banning/allowing a specific TCP port of the managed client, and limiting the transmission rate of the network traffic of that client. This type of function changes the behavior of the managed client: packets going through the managed client might be dropped according to the rules created by the up-layered management applications utilizing this building block. Following functions are provided by this building block:
• Open network (clear all filters; “open”) • Isolate from network (“closed”) • Get all filter handlers • Get information of a specific handler • Allow/Ban a TCP port • Allow/Ban a UDP port • Allow/Ban a remote IP address • Allow/Ban a TCP connection from (IP : port) • Allow/Ban a UDP service from (IP : port) • Limit Rate of a TCP port • Limit Rate of a UDP port • Limit Rate of a remote IP address • Limit Rate of a TCP connection from (IP : port) • Limit Rate of a UDP service from (IP : port)
Intel® AMT RDK API Guide
34 Intel Confidential
Filter Policy Operations The following figure illustrates a typical working flow of a certain operation when adding a filter:
For the policy operations including getting and setting default policies for “AP” mode two APIs from the Remote Agent Presence building block are used to get and set the AP watchdog policy:
UnsignedInt consoleWatchdogSetCbPolicy(UnsignedInt[] hwID, UnsignedInt[] handles); Set default policy for AP watchdog. UnsignedInt[] consoleWatchdogGetCbPolicy(UnsignedIntHolder status); Get default policy for AP watchdog.
Check current operating mode
Default mode AP mode
Get default policy and filter list from CB module
Get default policy and filter list from AP module
Generate new filters according to the input parameters
Create a new policy and add the original and the generated filters to the filter list
Default mode AP mode
Check current operating mode
End
Expert mode
Get default policy and filter list from expert policy module
Expert mode
Set the new policy as the default policy of CB module
Set the new policy as the default policy of AP module
Set the new policy as the default policy of expert policy module
Intel® AMT RDK API Guide
Intel Confidential 35
2.15.1 API Table NOTE: All filter operating functions have two common output parameters in the parameter list of type UnsignedIntHolder, which are used to store the handlers of send and receive filters just created inside the functions. Constructors, destructors and other general APIs Information retrieval APIs Filtering APIs Monitoring APIs Name Description Input
Params Returns
Initialize Initializes remote control out-of-band interface and private data members
IPAddr : String Username: String Password : String
None
Uninitialize Uninitialized private data members
None None
getOpType Gets current operating mode. None Int setOpType Sets current operating mode. Int optype; None beginCreatePolicy Enters Expert mode and get
ready for create a new policy None None
endCreatePolicy Exits Expert mode and returns the created policy
None Int
getPolicy Gets the default policy of current operating mode
None Int
setPolicy Sets the default policy of current operating mode
Int policy_handler; None
removePolicy Removes a specific policy from the managed client
Int policy_handler; None
removeAllFiltersInPolicy Removes all filters in the specified policy
Int policy_handler; None
addFiltersInPolicy Adds a list of filters in the specified policy; returns the new policy handler; the old handler is not valid any more.
Int policy_handler; Int[] filters
Int
removeFiltersInPolicy Removes a list of filters in the specified policy; returns the new policy handler; the old handler is not valid any more.
Int policy_handler; Int[] filters
Int
getHardwareID Gets current hardware ID in use None Int setHardwareID Sets current hardware ID Int None getAllCapacities Gets all hardware capacities in
terms of Circuit Breaker perspective
None CircuitBreaker- Capabilities[]
getAllFiltersInPolicy Gets all filters of the specified policy
Int policy_handler; Int[]
getAllPolicies Gets all policies in the managed client
None Int[]
getAllFilters Gets all filters contained in the Intel AMT client
None Int[]
getFilterInfo Retrieves info of the filter of the given handler. Handler is the input parameter. The information of the filter specificed by the handler is
int handler, UnsignedIntHolder transmit, UnsignedIntHolder profile, UnsignedIntHolder profileData,
None
Intel® AMT RDK API Guide
36 Intel Confidential
retrieved. UnsignedIntHolder type, UnsignedIntHolder portMin, UnsignedIntHolder portMax, String[] addrmask
clearAllFilters Clears all CB filters of the managed client
[out] sendHandler; [out] recvHandler;
None
isolateFromNetwork Isolates the managed client from the network
[out] sendHandler; [out] recvHandler;
None
allowTCPPort Allows the traffic through the specific TCP port of the managed client
int portMin, int portMax [out] sendHandler; [out] recvHandler;
None
banTCPPort Bans the traffic through the specific TCP port of the managed client
int portMin, int portMax [out] sendHandler; [out] recvHandler;
None
allowUDPPort Allows the traffic through the specific UDP port of the managed client
int portMin, int portMax [out] sendHandler; [out] recvHandler;
None
banUDPPort Bans the traffic through the specific UDP port of the managed client
int portMin, int portMax [out] sendHandler; [out] recvHandler;
None
allowRemoteAddress Allows the traffic from/to the specific remote address/subnet of the managed client
String address, String netmask [out] sendHandler; [out] recvHandler;
None
banRemoteAddress Bans the traffic from/to the specific remote address/subnet of the managed client
String address, String netmask [out] sendHandler; [out] recvHandler;
None
allowTCPConnection Allows the traffic through the specific IP : TCP port of the managed client
int portMin, int portMax, String address, String netmask [out] sendHandler; [out] recvHandler;
None
banTCPConnection Bans the traffic through the specific IP : TCP port of the managed client
int portMin, int portMax, String address, String netmask [out] sendHandler; [out] recvHandler;
None
allowUDPService Allows the traffic through the specific IP : UDP port of the managed client
int portMin, int portMax, String address, String netmask [out] sendHandler; [out] recvHandler;
None
BanUDPService Bans the traffic through the specific IP : UDP port of the managed client
int portMin, int portMax, String address, String netmask [out] sendHandler; [out] recvHandler;
None
limitRateOfTCPPort Limits the rate of the traffic through the specific TCP port of
int portMin, int portMax,
None
Intel® AMT RDK API Guide
Intel Confidential 37
the managed client int rate [out] sendHandler; [out] recvHandler;
limitRateOfUDPPort Limits the rate of the traffic through the specific UDP port of the managed client
int portMin, int portMax, int rate [out] sendHandler; [out] recvHandler;
None
limitRateOfRemoteAddress Limits the rate of the traffic from the specific remote IP address of the managed client
String address, String netmask, int rate [out] sendHandler; [out] recvHandler;
None
limitRateOfTCPConnection Limits the rate of the traffic through the specific IP : TCP port of the managed client
int portMin, int portMax, String address, String netmask, int rate [out] sendHandler; [out] recvHandler;
None
limitRateOfUDPService Limits the rate of the traffic through the specific IP : UDP port of the managed client
int portMin, int portMax, String address, String netmask, int rate [out] sendHandler; [out] recvHandler;
None
addFilters Adds a list of filters Int[] filters None removeFilters Removes a list of filters Int[] filters None removeAllFilters Removes all of the filters None None enableNetworkMonitor Enables the monitoring of the
entire network traffic of the managed client
[out] sendHandler; [out] recvHandler;
int
enableTCPPortMonitor Enables the monitoring of the network traffic through a specific TCP port of the managed client
int portMin, int portMax [out] sendHandler; [out] recvHandler;
Int
enableUDPPortMonitor Enables the monitoring of the network traffic through a specific UDP port of the managed client
int portMin, int portMax [out] sendHandler; [out] recvHandler;
Int
enableTCPConnectionMonitor Enables the monitoring of the network traffic through a specific IP : TCP port of the managed client
int portMin, int portMax, String address, String netmask [out] sendHandler; [out] recvHandler;
Int
enableUDPServiceMonitor Enables the monitoring of the network traffic through a specific IP : UDP port of the managed client
int portMin, int portMax, String address, String netmask [out] sendHandler; [out] recvHandler;
Int
getStatistics Gets the monitoring statistics of a specific monitor
int handler [out] sendHandler; [out] recvHandler;
StatisticalData
disableMonitor Disables (removes) a specific monitor
int handler [out] sendHandler; [out] recvHandler;
None
disableAll Disables (removes) all monitors None None
Intel® AMT RDK API Guide
38 Intel Confidential
2.15.1.1 Data Structures
• CircuitBreakerCapacities Type Name Description Int Id Hardware ID String Description Hardware description Int maxRxCountersV4 Maximum Rx Counters (IPv4) Int maxRxFiltersV4 Maximum Rx Filters (IPv4) Int maxTxCountersV4 Maximum Tx Counters (IPv4) Int maxTxFiltersV4 Maximum Tx Filters (IPv4) Int maxRxCountersV6 Maximum Rx Counters (IPv6) Int maxRxFiltersV6 Maximum Rx Filters (IPv6) Int maxTxCountersV6 Maximum Tx Counters (IPv6) Int maxTxFiltersV6 Maximum Tx Filters (IPv6) Int V6ToV4Ratio IPv6 to IPv4 ratio Boolean isAntiSpoofingCapableV4 Is anti-spoofing capable (IPv4) Boolean isAntiSpoofingCapableV6 Is anti-spoofing capable (IPv6)
• Constant Field Values : Type Name Value Description public static final int CIRCUITBREAKER_FILTER_ALLOW 3 Filter type (allow/pass) public static final int CIRCUITBREAKER_FILTER_BAN 1 Filter type (ban/drop) public static final int CIRCUITBREAKER_FILTER_RATELI
MIT 2 Filter type (limit rate)
public static final int CIRCUITBREAKER_FILTER_STATISTICS
0 Filter type (statistics)
public static final int FILTER_SEND 0 Filter direction (send) public static final int FILTER_RECV 1 Filter direction (recv) public static final int FILTER_TYPE_IP 1 Filter packet type (IP) public static final int FILTER_TYPE_TCP 2 Filter packet type (TCP) public static final int FILTER_TYPE_UDP 3 Filter packet type (UDP) public static final int OPTYPE_CB 1 Operating mode (default) public static final int OPTYPE_AP 2 Operating mode (AP) public static final int OPTYPE_EXPERT 0x10 Operating mode (Expert)
2.15.2 Usage Examples
2.15.2.1 Default Mode Usage try { CircuitBreakerInterface cbi = new CircuitBreakerInterface ("192.168.0.6", "admin", "P@ssw0rd"); cbi.clearAllFilters(); // the client is fully enabled for network communications cbi.isolateFromNetwork(); // the client is isolated
Intel® AMT RDK API Guide
Intel Confidential 39
cbi.allowRemoteAddress(“192.168.0.1”, “255.255.255.255”); // only the traffic to/from // the gateway 192.168.0.1 is allowed cbi.allowRemoteAddress(“192.168.0.0”, “255.255.0.0”); // Good! The whole local subnet // is allowed! cbi.clearAllFilters();// the client is fully enabled for network communications cbi.banTCPPort(80, 80); // HTTP port is banned cbi.banTCPPort(1000, 65535); // ports 1000-65535 are banned cbi.banRemoteAddress(“192.168.1.2”, “255.255.255.255”); // ban the remote address!! } } catch(Exception e) { e.printStackTrace(); }
2.15.2.2 AP Mode Usage try { CircuitBreakerInterface cbi = new CircuitBreakerInterface ("192.168.0.6", "admin", "P@ssw0rd"); cbi.setOpType(OPTYPE_AP); // set operating mode to AP mode cbi.clearAllFilters(); // the client is fully enabled for network communications cbi.isolateFromNetwork(); // the client is isolated ////// // Here places the codes to define the actions of agent state transition. // The above codes won’t take effect until a specified state transition // occurs. // For example, when a specific agent expires (RUNNING EXPIRED) // the managed Intel AMT client is isolated from the network. ////// } } catch(Exception e) { e.printStackTrace(); }
2.15.2.3 Expert Mode Usage (Joint-usage on the Three Operating Modes) The upper layer application creates a policy and its filters between the beginCreatePolicy and endCreatePolicy block. After that it can also modify the created policy and/or set it as the default policy of default mode or AP mode. The typical way to create a policy: // Enter Expert mode and create a policy cbi.beginCreatePolicy(); { // In this block it creates the filters of the policy to be created
Intel® AMT RDK API Guide
40 Intel Confidential
cbi.openNetwork(); cbi.banUDPService(0,1000); cbi.banRemoteAddress(“192.168.0.0”,”255.255.0.0”); } int myPolicy = cbi.endCreatePolicy(); // Till now it exits Expert mode and returns to the original mode // A policy is created and its handler is stored in myPolicy A joint sample of using three operating modes: try { CircuitBreakerInterface cbi = new CircuitBreakerInterface ("192.168.0.6", "admin", "P@ssw0rd"); // Set operating mode to default mode cbi.setOpType(OPTYPE_CB); // Do some filter operations cbi.isolateFromNetwork(); // the client is isolated cbi.allowRemoteAddress(“192.168.0.1”, “255.255.255.255”); // only the traffic to/from // the gateway 192.168.0.1 is allowed cbi.allowRemoteAddress(“192.168.0.0”, “255.255.0.0”); // Good! The whole local subnet // is allowed! // Set operating mode to AP mode cbi.setOpType(OPTYPE_AP); cbi.openNetwork();// the client is fully enabled for network communications cbi.banTCPPort(80, 80); // HTTP port is banned cbi.banTCPPort(1000, 65535); // ports 1000-65535 are banned cbi.banRemoteAddress(“192.168.1.2”, “255.255.255.255”); // ban the remote address!! // Enter Expert mode and create a policy cbi.beginCreatePolicy(); { // In this block it creates a policy cbi.openNetwork(); cbi.banUDPService(0,1000); cbi.banRemoteAddress(“192.168.0.0”,”255.255.0.0”); } int myPolicy = cbi.endCreatePolicy(); // Till now it exits Expert mode and returns to the original mode // A policy is created and its handler is stored in myPolicy // Now myPolicy is created // Set it as the default policy for AP mode cbi.setOpType(OPTYPE_AP); cbi.setPolicy(myPolicy); // Get the default policy of Default Mode cbi.setOpType(OPTYPE_CB); int myPolicy2 = cbi.getPolicy(); // Add all filters of myPolicy into the default policy of Default Mode myPolicy2 // NOTE the value of myPolicy2 is updated after the following two lines of codes. int[] filters = cbi.getAllFiltersInPolicy(myPolicy); myPolicy2 = cbi.addFiltersInPolicy(myPolicy2, filters); // And reset it as the default policy of Default mode cbi.setPolicy(myPolicy2);
Intel® AMT RDK API Guide
Intel Confidential 41
} } catch(Exception e) { e.printStackTrace(); }
2.16 Local Agent Presence Description: This building block encapsulates all the functionality offered by the Local Agent Presence Interface of Intel AMT. The Local Agent Presence Interface is an in-band Intel AMT feature which is used by registered applications running on the local host to report the presence of the associated application. It automatically handles the low level details of periodically sending heartbeat messages to the underlying watchdog and provides some high level, easier-to-use APIs which cover all of the functionalities of the Local Agent Presence feature. Every API function offered by this building block throws an exception if it occurs. Inside of local agent presence building block, a separate heartbeat thread will be created and start running after users register their agent application with registerWatchdog. The heartbeat thread automatically handles all the low level details of periodically sending heartbeat messages to the underlying Intel AMT device at fixed intervals specified by management console with session number incremented between each heartbeat calls. The heartbeat thread will be reaped when user’s agent application calls unregisterWatchdog to report termination state. Since the Java platform guarantees that no single thread can be compromised individually without terminating the whole process, it won’t be the case for the main thread of user’s agent application to be killed with the heartbeat thread still running. To be further defensive, the heartbeat thread is marked as a daemon thread so that the Java virtual machine will still exit and management console won’t continue to assume the registered agent is still running when the user’s agent application forgets to call unregisterWatchdog and then exit.
2.16.1 API Table Name Description Input
Params Returns
Initialize Initializes local agent presence interface and private data members
ipAddr : String username: String password : String
None
Uninitialize Uninitializes private data members
None None
registerWatchdog This method is called by applications that wish to start reporting their running state
int[] agentID: Globally unique application identifier(A 16 byte array representing a GUID)
None
unregisterWatchdog This call is issued by applications to report their termination state.
None None
2.16.2 Application Notes 1. Use of “localhost” as the address is allowed when creating AgentWatchdogLocalInterface instances. 2. Each agent is identified by an agent ID. The agent ID value is shared between the agent and the management console application. After the management console application creates an Agent Presence instance in the Intel AMT device using createWatchdog, the software agent can register using registerWatchdog.
Intel® AMT RDK API Guide
42 Intel Confidential
3. The possible values of agent ID range from 0x00 to 0xFF and an exception will be thrown if invalid values are provided. The parameter agentID is of type int[] instead of byte[] to make it more convenient for users to initialize agent ID values. Values ranging from 0x80 to 0xFF can be written as below: int[] agentID = {0x80, 0x90, 0xA0, 0xB0, 0xC0, 0xD0, 0xE0, 0xF0, 0x8F, 0x9F, 0xAF, 0xBF, 0xCF, 0xDF, 0xEF, 0xFF}; instead of byte[] agentID = {(byte)0x80, (byte)0x90, (byte)0xA0, (byte)0xB0, (byte)0xC0, (byte)0xD0, (byte)0xE0, (byte)0xF0, (byte)0x8F, (byte)0x9F, (byte)0xAF, (byte)0xBF, (byte)0xCF, (byte)0xDF, (byte)0xEF, (byte)0xFF};
2.16.3 Usage Example // Each agent is identified by a globally unique application identifier of 16 bytes. Note the agent // ID should be the same as the one used in createWatchdog calls on the MC side. int[] agentID = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f}; try { AgentWatchdogLocalInterface awli = new AgentWatchdogLocalInterface ("localhost", "admin", "P@ssw0rd"); awli.registerWatchdog (agentID); // Sleep for 100 seconds. ISVs should do some stuff here instead of just sleeping;-) Thread.sleep(100000); awli.unregisterWatchdog (); } catch (Exception e) { e.printStackTrace(); }
2.17 Remote Agent Presence Description: This building block encapsulates all the functionality offered by the Remote Agent Presence Interface of Intel AMT. The Remote Agent Presence Interface is used by the remote side console to register applications and the associated events for tracking agent state remotely. It hides low level details of Web Service interfaces provided by Intel AMT Remote Agent Presence module, abstracts those interfaces, and provides some high level, easier-to-use APIs which cover all of the functionalities of the Remote Agent Presence feature. Every API function offered by this building block throws an exception if it occurs. Remote Agent Presence is always combined with another Intel AMT feature, System Defense, to enable network isolation capabilities when local users try to compromise the agent either by killing the process or stopping the service. Users can define an applicable System Defense policy via the interfaces provided by System Defense module.
2.17.1 API Table : Name Description Input
Params Returns
Initialize Initializes remote agent presence interface and private data members
ipAddr : String username: String password : String
None
Uninitialize Uninitializes private data members
None None
createWatchdog Creates an entry for an int[] agentID: Globally WatchdogAction[]
Intel® AMT RDK API Guide
Intel Confidential 43
application to be monitored and initializes the action settings for the specified agent. Returns previous action settings if there’s an existing agent with the same agent ID, or null if a brand new entry gets created. The field actionHandle of an WatchdogAction entry in the return value can be used as actionHandle argument in successive removeWatchdogAction calls.
unique application identifier(a 16 byte array representing a GUID) String description: A text which describes the application(16 characters max) short heartbeatTime: A seconds timer value which specifies the maximum time allowed between application heartbeat calls short startupTime: A seconds timer value which specifies the maximum time for an application to load when system starts, and then start sending heartbeat calls
deleteWatchdog Removes an application watchdog entry and all its associated actions.
int[] agentID: Globally unique application identifier(A 16 byte array representing a GUID)
None
enumerateWatchdog Enumerates application watchdog entries and initializes the action settings for these watchdogs. Returns Application watchdog entries registered on the given Intel AMT machine, or null if there's no such entry.
None WatchdogEntry[]
addWatchdogAction Adds an action for a given watchdog entry. Returns the handle of the new action which can be used as actionHandle argument in successive removeWatchdogAction calls, or -1 if specified agent does not exist.
int[] agentID: Globally unique application identifier(a 16 byte array representing a GUID) int oldState: The last state of the application watchdog int newState: The current state of the application watchdog int actionCB: whether to activate the global Circuit Breaker (aka. System Defense) policy for Agent Presence module
int
removeWatchdogAction Removes an action set previously. Nothing will happen if either agentID or actionHandle is invalid.
int[] agentID: Globally unique application identifier(A 16 byte array representing a GUID) int actionHandle: Action handle returned by previous calls to createWatchdog, addWatchdogAction or getAllWatchdogActions
None
removeAllWatchdogActions Removes all actions set previously. Nothing will happen
int[] agentID: Globally unique application
None
Intel® AMT RDK API Guide
44 Intel Confidential
if the specified agentID does not exist.
identifier(A 16 byte array representing a GUID)
getAllWatchdogActions Gets all actions set previously. Returns the action settings for the specified agent, or null if there is no such agent. The field actionHandle of an WatchdogAction entry in the return value can be used as actionHandle argument in successive removeWatchdogAction calls.
Int[] agentID: Globally unique application identifier(A 16 byte array representing a GUID)
WatchdogAction[]
commitWatchdogActions Commits the action settings to Intel AMT device so that they begin to take effect. Nothing will happen if the specified agentID does not exist.
int[] agentID: Globally unique application identifier(A 16 byte array representing a GUID)
None
Constant Field Values : Type Name Valu
e Description
public static final int WATCHDOG_STATE_NOT_STARTED
0x01 Agent is no started
public static final int WATCHDOG_STATE_STOPPED 0x02 Agent is stopped public static final int WATCHDOG_STATE_RUNNING 0x04 Agent is running public static final int WATCHDOG_STATE_EXPIRED 0x08 Timers associated with the agent
expired public static final int WATCHDOG_STATE_SUSPENDE
D Ox10 System entered suspend state
public static final int WATCHDOG_STATE_ANY 0xFF Don’t care for the old state public static final int WATCHDOG_ACTIVATE_CB_POLI
CY 0 Activate CB Policy
public static final int WATCHDOG_DEACTIVATE_CB_POLICY
1 Deactivate CB Policy
Auxiliary Class WatchdogEntry : Type Name Description public final int[]
agentID Globally unique application identifier
public final String agentDescription Application description string public final short agentHeartbeatTime The maximum time allowed
between application heartbeat calls public final short agentStartupTime The maximum time allowed for
an application to start up and start sending application heartbeat calls
public final int numActions Number of actions associated with the application
public final int agentCurrentState The current state of the application Auxiliary Class WatchdogAction : Type Name Description public final int actionHandle Handle of this action public final int
oldState The last state of the application watchdog
public final int newState The current state of the application watchdog
Intel® AMT RDK API Guide
Intel Confidential 45
public final int actionCB A Circuit Breaker Action which may be applied, when the application watchdog transitions from OldState to NewState
2.17.2 Application Notes : 1. System defense policy associated with agent presence can only be set after users call the setOpType (OPTYPE_AP) method of CircuitBreakerInterface. 2. Each agent is identified by an agent ID. The agent ID value is shared between the agent and the management console application. After the management console application creates an Agent Presence instance in the Intel AMT device using createWatchdog, the software agent can register using registerWatchdog. 3. Users should always remember to call commitWatchdogActions for all the actions previously set by addWatchdogAction, removeWatchdogAction and removeAllWatchdogActions to take effect. 4. If there is an existing agent with the same agentID on the remote Intel AMT device, createWatchdog initializes the action settings by retrieving the previous action settings from remote Intel AMT machine.
2.17.3 Usage Example : // Each agent is identified by a globally unique application identifier of 16 bytes. Note the agent // ID should be the same as the one used in registerWatchdog calls on the Intel AMT client side int[] agentID = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f}; try { // Isolate the AMT machine from network if specific state transition happens CircuitBreakerInterface cbi = new CircuitBreakerInterface ("192.168.0.6", "admin", "P@ssw0rd"); cbi.setOpType (OPTYPE_AP); cbi.isolateFromNetwork (); AgentWatchdogRemoteInterface awri = new AgentWatchdogRemoteInterface ("192.168.0.6", "admin", "P@ssw0rd"); // Local agent must register itself within 60 seconds after system starts and send //heartbeat messages every 20 seconds awri.createWatchdog (agentID, “FOO_AGENT”, 20, 60); // Deactivate system defense policy (i.e. isolate the AMT machine from network) when //agent gets up-running awri.addWatchdogAction (agentID, WATCHDOG_STATE_ANY, WATCHDOG_STATE_RUNNING, WATCHDOG_DEACTIVATE_CB_POLICY); // Activate the system defense policy (i.e. isolate the AMT machine from network) set // //previously when one of the specified state transition occurs awri.addWatchdogAction (agentID, WATCHDOG_STATE_ANY, WATCHDOG_STATE_NOT_STARTED | WATCHDOG_STATE_STOPPED | WATCHDOG_STATE_EXPIRED | WATCHDOG_STATE_SUSPENDED, WATCHDOG_ACTIVATE_CB_POLICY); // Enables all the actions set above awri.commitWatchdogActions (agentID); } catch (Exception e) { e.printStackTrace(); }
Intel® AMT RDK API Guide
46 Intel Confidential
2.18 Storage Interface Description : This building block encapsulates functionality offered by the storage library and provides higher level of abstraction. This building block is a wrapper around a C-based application which links with storage library of Intel AMT SDK. This building block offers functionality such as enumerating allocated blocks for a given tuple (Enterprise-Vendor-Application), deallocating a specific block, allocating and writing a block with either user-defined data or pre-populated data, reading a content of specific block, etc.
2.18.1 API table: Name Description Input
Params Returns
enumAllocatedBlocks Enumerates all allocated blocks for a given tuple (Enterprise-Vendor-Application) name. C wrapper application which will get invoked as a result of this API, will write those block name in a file and this API will read the content of that file which will be block names if successful otherwise it will return NULL string object.
String – entName String – venName String – appName
String – enterprise names separated by new line character
deallocateBlock Locates (using a C wrapper) the block identified using block name for a given tuple (Enterprise-Vendor-Application). Once it located the block, it will deallocate that specific block.
String – entName String – venName String – appName String – blockName
Int – status (if returns 1 then Successful otherwise Error )
readBlock Locates (using a C wrapper) the block identified using block name for a given tuple (Enterprise-Vendor-Application). Once it located the block, then it will read the contents of that block and return those contents to the caller.
String – entName String – venName String – appName String – blockName
String – content of the requested block otherwise NULL string object
writeBlock
Allocates (using a C wrapper) the block identified using block name if it doesn’t exist for a given tuple (Enterprise-Vendor-Application). Once it allocates block, then it will fill up contents for that block as supplied in input parameters and then write that block into NV store. If the block exist, then this API will update the contents of that block and commit changes into NV store. This API has a two purpose : 1. Allocate new block and write to it 2. Update the contents of exitsing block
String – entName String – venName String – appName String – blockName
Int – return 1 if successful otherwise return code.
deallocateAllBlocks Locates (using a C wrapper) all the blocks for a given tuple (Enterprise-Vendor-Application) and will deallocate them.
String – entName String – venName String – appName String – blockName
Int – status (returns 1 if successful otherwise errorcode)
2.18.2 Usage Example: try {
Intel® AMT RDK API Guide
Intel Confidential 47
String entName=”Intel”; String vntName=”McAfee”; String appName=”VirusAgent”; StorageAccess saccess = new StorageAccess(("192.168.0.6","admin", "P@ssw0rd”); // entName, venName, appName are input parameters, make sure it contains // valid data. String str = saccess.EnumerateBlocks(entName, venName, appName); if((str != null) && (str.length() > 0)) { StringTokenizer st = new StringTokenizer(str, ","); while(st.hasMoreTokens()) { // Get block name. Every token is a block name String bname = st.nextToken(); } }else { // Get Error STring String str = saccess.getErrString()); } } catch(Exception e) { e.printStackTrace(); }
2.19 Redirection Interface Description : This building block encapsulates the functionality offered by the redirection library and provides a higher level of abstraction. This building block is a wrapper around a C-based application which in turn links with the redirection library of Intel AMT SDK. This building block offers functionality such as establishing Serial Over LAN (SOL), establishing IDER, and establishing both (SOL & IDER) sessions. This method launches a new thread every time the user invokes any of the APIs offered. This building block offers an API to stop the currently executing thread. It offers default and overloaded constructors.
2.19.1 API table: Name Description Input
Params Returns
EstablishSOL Launches a separate thread. This worker thread runs the method and launches a C wrapper application with the appropriate command line option for establishing an SOL session. As a result, an SOL session gets established with the specified Intel AMT managed node.
None Int
EstablishIDER Launches a separate thread. This worker thread runs the method and launches a C wrapper application with the appropriate command line option for establishing an IDER session. As a result, an IDER session gets established with the specified Intel AMT managed node.
None Int
EstablishSOLIDER Launches a separate thread. This worker thread runs the method and launches a C wrapper application with
None Int
Intel® AMT RDK API Guide
48 Intel Confidential
the appropriate command line option for establishing SOL and IDER sessions. As a result, SOL and IDER sessions get established with the specified Intel AMT managed node. NOTE : This is not currently implemented
2.19.2 Usage Example: try { // For Linux RedirectionAccess ra = new RedirectionAccess(“192.168.0.10”, “admin”, “admin” , false, true, false, “TCP”, “/dev/fd0”, “/dev/cdrom”); // For Windows // RedirectionAccess ra = new RedirectionAccess(“192.168.0.10”, “admin”, // “admin” , false, true, false, “TCP”, “[-a-]”, “[-d-]”); // Establishing IDER session, converting return code into string and // displaying on the status bar of GUI. int status = ra.EstablishIDER(); } catch(Exception e) { e.printStackTrace(); }
Intel® AMT RDK API Guide
Intel Confidential 49
3 .0 Graphica l User In ter face (GUI) This section describes the Graphical User Interface (GUI) which provides an easy mechanism for exercising the building blocks. The GUI consists of a menu at the top, body in the middle, and a status bar at the bottom, refer RDK user guide for GUI details. The menu consists of two items: File and Help. The “File” Menu consists of an “Exit” menu item. The “Help” Menu consists of an “About” menu item. The body consists of a notebook-style tabbed panel in which each tab is a different building block. There are two additional tabs, Intro and Login, which are used to support the building blocks. When the GUI starts, only the Intro and Login tabs are enabled and the other building block tabs are disabled. The Intro tab is shown as the default tab at start up. It describes what this GUI is used for along with the version, release and copyright information. The GUI design consists of two major parts:
• AmtGui class • AmtGuiHandler classes
3.1 AmtGui Class Description: The AmtGui class consists of several methods that create the different parts of the GUI. It starts by creating the main window then the menu bar with menu items, and then the status bar. Then a tab is created for each building block plus an Intro and Login tabs. Each method creates a panel and then adds the components until they match the functionality shown in the Appendix. The major actions to create the GUI consist of: Divide the frame using a Layout Manager:
While more panels Add panel to specific area Divide the panel using a Layout Manager While more components
Add component to specific area
3.1.1 API Table The AmtGui class methods are listed in the following table: Name Description Input
Params Returns
main Starting point for Intel AMT GUI executable
None None
AmtGui Drives the creation the Intel AMT GUI and all it’s components
None None
createFrame Creates the main GUI window None JFrame createMenuBar Creates the MenuBar with Menus
and MenuItems at top of window JFrame None
createStatusBar Creates StatusBar at bottom of window
JFrame None
createTabbedPane Creates a NoteBook Tabbed style container in middle of window
JFrame JTabbedPane
createIntroTabPanel Creates Intro Tab and Panel contents
JTabbedPane None
createLoginTabPanel Creates Login Tab and Panel contents
JTabbedPane None
createHardwareAssetsTabPanel Creates Hardware Assets Building Block Tab and Panel contents
JTabbedPane None
createEventMgmtTabPanel Creates Event Management Building Block Tab and Panel
JFrame, JTabbedPane
None
Intel® AMT RDK API Guide
50 Intel Confidential
contents createNetworkAdminTabPanel Creates Network Administration
Building Block Tab and Panel contents
JTabbedPane None
createRemoteControlTabPanel Creates Remote Control Building Block Tab and Panel contents
JTabbedPane None
createSystemDefenseTabPanel Creates System Defense (aka Circuit Breaker) Building Block Tab and Panel contents
JFrame, JTabbedPane
None
createStorageTabPanel Creates Storage Building Block Tab and Panel contents
JTabbedPane None
createRedirectionTabPanel Creates Redirection Building Block Tab and Panel contents
JTabbedPane None
createAgentPresenceTabPane Creates Agent Presence Building Block Tab and Panel contents
JFrame, JTabbedPane
None
3.2 AmtGui<BuildingBlock>Handler Classes Description: The AmtGui<BuildingBlock>Handler classes consist of the interface code for manipulating the buttons, radio buttons, text fields and text areas, etc. on the various tabs. A file is created for each tab and its name format is: AmtGui<BuildingBlock>Handler.java. Within each Handler, the code is divided up by the various buttons that can be selected and the text fields and areas are adjusted appropriately. The initial code in each Handler shows an example of how and what can be done. NOTE: It is up to each Building Block owner to modify the AmtGui<BuildingBlock>Handler code to obtain their desired results and/or operations.
3.2.1 API tables AmtGuiHandlers Name Description Input
Params Returns
AmtGui AgentPresence * Handler Implements an Action Listener that controls the GUI components for the Agent Presence Building Block * Panel
ActionEvent None
AmtGui EventMgmt * Handler Implements an ActionListener that
controls the GUI components on the Event Management Building Block * Tab
ActionEvent None
AmtGui HardwareAssets Handler Implements an ActionListener that controls the GUI components on the Hardware Assets Building Block Tab
ActionEvent None
AmtGui Login Handler Implements an ActionListener that controls the GUI components on the Login Tab that is common for all Building Blocks
ActionEvent None
AmtGui NetworkAdmin * Handler Implements an ActionListener that controls the GUI components on the Network Administration Building Block for Hostname subTab
ActionEvent None
AmtGui Redirection Handler Implements an ActionListener that controls the GUI components on the Redirection Building Block Tab
ActionEvent None
AmtGui RemoteControl * Handler Implements an ActionListener that ActionEvent None
Intel® AMT RDK API Guide
Intel Confidential 51
controls the GUI components on the Remote Control Building Block for Capabilities subTab
AmtGui Storage * Handler Implements an ActionListener that controls the GUI components on the Storage Building Block Tab
ActionEvent None
AmtGui SystemDefense * Handler Implements an ActionListener that controls the GUI components on the SystemDefense (aka Circuit Breaker) Building Block * Tab
ActionEvent None
AmtGui * Tab Handler Implements a ChangeListener that controls the GUI components on * Tab for whenever the user changes tabs
ChangeListener None
EventMgmt * TableModel Implements the TableModel that controls the GUI JTable components of Event Management Building Block and Tabs.
varies JTable changes
Intel® AMT RDK API Guide
52 Intel Confidential
INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL® PRODUCTS. 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 Corporation may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights that relate to the presented subject matter. The furnishing of documents
and other materials and information does not provide any license, express or implied, by estoppel or otherwise, to any such patents, trademarks, copyrights, or other intellectual property rights.
Intel products are not intended for use in medical, life-saving, life-sustaining, critical control or safety systems, or in nuclear-facility applications.
Intel may make changes to dates, specifications, product descriptions, and plans referenced in this document at any time, without notice.
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® PXA27x Processor and Intel® PXA9xx Cellular Processor Family 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 Binary Library ("Software") is furnished under license and may only be used or copied in accordance with the terms of that license. No license, express or implied, by estoppel or otherwise, to any
intellectual property rights is granted by this document. The Software is subject to change without notice, and should not be construed as a commitment by Intel Corporation to market, license, sell or
support any product or technology. Unless otherwise provided for in the license under which this Software is provided, the Software is provided AS IS, with no warranties of any kind, express or implied.
Except as expressly permitted by the Software license, neither Intel Corporation nor its suppliers assumes any responsibility or liability for any errors or inaccuracies that may appear herein. Except as
expressly permitted by the Software license, no part of the Software may be reproduced, stored in a retrieval system, transmitted in any form, or distributed by any means without the express written
consent of Intel Corporation.
The source code contained or described herein and all documents related to the source code ("Material") are owned by Intel Corporation or its suppliers or licensors. Title to the Material remains with Intel
Corporation or its suppliers and licensors. The Material may contain trade secrets and proprietary and confidential information of Intel Corporation and its suppliers and licensors, and is protected by
worldwide copyright and trade secret laws and treaty provisions. No part of the Material may be used, copied, reproduced, modified, published, uploaded, posted, transmitted, distributed, or disclosed
in any way without Intel’s prior express written permission.
No license under any patent, copyright, trade secret or other intellectual property right is granted to or conferred upon you by disclosure or delivery of the Materials, either expressly, by implication,
inducement, estoppel or otherwise. Any license under such intellectual property rights must be express and approved by Intel in writing.
Unless otherwise agreed by Intel in writing, you may not remove or alter this notice or any other notice embedded in Materials by Intel or Intel’s suppliers or licensors in any way.
JPEG, H.263, H.264, MPEG-4, G.729, G.723, AMR-WB, AMR-NB, AAC, MP3, MIDI, SBC are international standards. Implementations of JPEG, H.263, H.264, MPEG-4, G.729, G.723, AMR-WB, AMR-NB,
AAC, MP3, MIDI, SBC codecs, or JPEG, H.263, H.264, MPEG-4, G.729, G.723, AMR-WB, AMR-NB, AAC, MP3, MIDI, SBC enabled platforms may require licenses from various entities, including Intel
Corporation.
This document and any 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 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 Web site at http://www.intel.com.
Intel, the Intel logo, and Leap Ahead are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
Bluetooth is a trademark owned by its proprietor and used by Intel Corporation under license.
*Other names and brands may be claimed as the property of others.
INTEL CONFIDENTIAL
Copyright © 2006, Intel Corporation. All rights reserved.