Class IPS_HostBasedSetupService

Used in features: Provisioning
Compatible with the following Intel AMT Releases: 6.1, 6.2, 7.0, 8.0, 8.1, 9.0, 9.5, 10.0, 11.0
CIM_ManagedElement
   extended by CIM_ManagedSystemElement
      extended by CIM_LogicalElement
         extended by CIM_EnabledLogicalElement
            extended by CIM_Service
               extended by CIM_SecurityService
                  extended by IPS_HostBasedSetupService


class IPS_HostBasedSetupService
extends CIM_SecurityService

General Information:
Describes the Host Based Setup Service, which is the logic in Intel(R) AMT that responds to setup requests initiated from the host using OS Administrator credentials. Also provides a method to upgrade to Admin Control mode that can be initiated remotely.

Qualifiers:
-------------
Experimental
Version=8.0.0


Supported Fields Summary
 string ElementName
A user-friendly name for the object . . .
 string SystemCreationClassName Key
The CreationClassName of the scoping System.
 string SystemName Key
The Name of the scoping System.
 string CreationClassName Key
CreationClassName indicates the name of the class or the subclass that is used in the creation of an instance . . .
 string Name Key
The Name property uniquely identifies the Service and provides an indication of the functionality that is managed . . .
 uint8 CurrentControlMode
An enumeration value that indicates the control mode of the Intel(R) AMT subsystem after provisioning . . .
 uint8[2] AllowedControlModes
An array of values that indicates which control modes this machine is allowed to be in . . .
 uint8[20] ConfigurationNonce
Nonce value randomly generated by Intel(R) AMT, used as input to the Setup APIs . . .
 uint8 CertChainStatus
Status of "AddNextCertInChain" progress . . .

Methods Summary
 uint32 Setup(NetAdminPassEncryptionType, NetworkAdminPassword, McNonce, Certificate, SigningAlgorithm, DigitalSignature)
Setup Intel(R) AMT from local host . . .
 uint32 AddNextCertInChain(NextCertificate, IsLeafCertificate, IsRootCertificate)
Add a certificate to the provisioning certificate chain, to be used by AdminSetup or UpgradeClientToAdmin methods.
 uint32 AdminSetup(NetAdminPassEncryptionType, NetworkAdminPassword, McNonce, SigningAlgorithm, DigitalSignature)
Setup Intel(R) AMT from the local host, resulting in Admin Setup Mode . . .
 uint32 UpgradeClientToAdmin(McNonce, SigningAlgorithm, DigitalSignature)
Upgrade Intel(R) AMT from Client to Admin Control Mode . . .
 uint32 DisableClientControlMode()
Do not allow provisioning the machine in Client Control mode.
  Get(Instance)
Gets the representation of the instance
  Pull(EnumerationContext, MaxElements)
Pulls instances of this class, following an Enumerate operation
  Enumerate()
Enumerates the instances of this class

Field Detail

ElementName

public string ElementName
General Information:
A user-friendly name for the object. This property allows each instance to define a user-friendly name in addition to its key properties, identity data, and description information.
Note that the Name property of ManagedSystemElement is also defined as a user-friendly name. But, it is often subclassed to be a Key. It is not reasonable that the same property can convey both identity and a user-friendly name, without inconsistencies. Where Name exists and is not a Key (such as for instances of LogicalDevice), the same information can be present in both the Name and ElementName properties. Note that if there is an associated instance of CIM_EnabledLogicalElementCapabilities, restrictions on this properties may exist as defined in ElementNameMask and MaxElementNameLen properties defined in that class.

Qualifiers:
-------------
MaxLen=40


SystemCreationClassName Key

public string SystemCreationClassName
General Information:
The CreationClassName of the scoping System.

Qualifiers:
-------------
Key
MaxLen=32
Propagated=CIM_System.CreationClassName


SystemName Key

public string SystemName
General Information:
The Name of the scoping System.

Qualifiers:
-------------
Key
MaxLen=15
Propagated=CIM_System.Name


CreationClassName Key

public string CreationClassName
General Information:
CreationClassName indicates the name of the class or the subclass that is used in the creation of an instance. When used with the other key properties of this class, this property allows all instances of this class and its subclasses to be uniquely identified.

Qualifiers:
-------------
Key
MaxLen=28


Name Key

public string Name
General Information:
The Name property uniquely identifies the Service and provides an indication of the functionality that is managed. This functionality is described in more detail in the Description property of the object.

Qualifiers:
-------------
Key
Override=Name
MaxLen=40


CurrentControlMode

public uint8 CurrentControlMode
General Information:
An enumeration value that indicates the control mode of the Intel(R) AMT subsystem after provisioning. This property is read-only

Qualifiers:
-------------
ValueMap={0, 1, 2, ..}
Values={Not provisioned, Client, Admin, Reserved}


AllowedControlModes

public uint8[2] AllowedControlModes
General Information:
An array of values that indicates which control modes this machine is allowed to be in. This property is read-only. "Client" can only be removed using the "DisableClientControlMode" method.

Qualifiers:
-------------
ValueMap={0, 1, 2, ..}
Values={Not provisioned, Client, Admin, Reserved}


ConfigurationNonce

public uint8[20] ConfigurationNonce
General Information:
Nonce value randomly generated by Intel(R) AMT, used as input to the Setup APIs. This value will be regenerated following an unprovision event and after a successful setup.It may also be regenerated following ME resets.

Qualifiers:
-------------
OctetString


CertChainStatus

public uint8 CertChainStatus
General Information:
Status of "AddNextCertInChain" progress. This property is read-only.

Qualifiers:
-------------
ValueMap={0, 1, 2, ..}
Values={Not Started, Chain In-Progress, Chain Complete, Reserved}


Method Detail

Setup

public uint32 Setup([IN]uint16 NetAdminPassEncryptionType, [IN]string NetworkAdminPassword[], [IN]uint8 McNonce[], [IN]uint8 Certificate[], [IN]uint16 SigningAlgorithm, [IN]uint8 DigitalSignature[])
Permission Information:
Permitted realms: ADMIN_SECURITY_LOCAL_SYSTEM_REALM, ADMIN_SECURITY_ADMINISTRATION_REALM

General Information:
Setup Intel(R) AMT from local host. This function requires OS administrator rights, and moves Intel(R) AMT from "Pre Provisioned" state to "Post Provisioned" state. The control mode after this method is run will be "Client". This method also allows the configuring agent to sign the setup operation with a certificate. The certificate hash will be kept in the corresponding provisioning record

Qualifiers:
-------------
ValueMap={0, 1, 2, 3, 4, 5, 6, ..}
Values={SUCCESS, INTERNAL ERROR, INVALID STATE, INVALID PARAM, METHOD DISABLED, AUTH_FAILED, FLASH_WRITE_LIMIT_EXCEEDED, Reserved}


Parameters:
--------------
NetAdminPassEncryptionType
General Information:
The encryption type of the network admin password. Only HTTP-MD5 is supported. The values are the same as the CIM_Account.UserPasswordEncryptionAlgorithm field

Qualifiers:
-------------
Required
IN
ValueMap={0, 1, 2, ..}
Values={None, Other, HTTP Digest MD5(A1), DMTF Reserved}

NetworkAdminPassword
General Information:
New network admin password to be set by this command, encrypted using the encryption type algorithm

Qualifiers:
-------------
Required
IN
OctetString

McNonce
General Information:
A random nonce value generated by the configuration agent.Required if the digital signature is provided.needs to be concatenated after the configuration nonce and signed together with the attached certificate's private key

Qualifiers:
-------------
IN
OctetString

Certificate
General Information:
The certificate used to sign the setup operation. If the digital signature is provided, Intel(R) AMT will only validate the format of the certificate and that it was used to sign the nonces. If the operation is successful it will save the certificate hash in the corresponding provisioning record

Qualifiers:
-------------
IN
OctetString

SigningAlgorithm
General Information:
The signing algorithm used to sign the setup operation.

Qualifiers:
-------------
IN
ValueMap={0, 1, 2, ..}
Values={None, Other, RSA_SHA-2_256, DMTF Reserved}

DigitalSignature
General Information:
A digital signature of the ConfigurationNonce and the McNonce concatenated. If this information is provided, AMT will validate the signature before accepting the command.

Qualifiers:
-------------
IN
OctetString



AddNextCertInChain

public uint32 AddNextCertInChain([IN]uint8 NextCertificate[], [IN]boolean IsLeafCertificate, [IN]boolean IsRootCertificate)
Permission Information:
Permitted realms: ADMIN_SECURITY_ADMINISTRATION_REALM, ADMIN_SECURITY_LOCAL_SYSTEM_REALM

General Information:
Add a certificate to the provisioning certificate chain, to be used by AdminSetup or UpgradeClientToAdmin methods.

Product Specific Usage:
Additional Notes:
1) When Intel(R) AMT is in client mode this method is permitted only for users with ADMIN_SECURITY_ADMINISTRATION_REALM
2) When Intel(R) AMT is in not provisioned this method is permitted only for users with ADMIN_SECURITY_LOCAL_SYSTEM_REALM


Qualifiers:
-------------
ValueMap={0, 1, 2, 3, 4, 5, ..}
Values={SUCCESS, INVALID PARAM, INTERNAL_ERROR, INVALID STATE, CERT_VERIFY_FAILED, CERT_CHAIN_LENGTH_EXCEEDED, Reserved}


Parameters:
--------------
NextCertificate
General Information:
The next certificate to add to the chain

Qualifiers:
-------------
Required
IN
OctetString

IsLeafCertificate
General Information:
true, when the current certificate is leaf certificate

Qualifiers:
-------------
IN

IsRootCertificate
General Information:
true, when the current certificate is root. Marks end of the certificate chain

Qualifiers:
-------------
IN



AdminSetup

public uint32 AdminSetup([IN]uint16 NetAdminPassEncryptionType, [IN]string NetworkAdminPassword[], [IN]uint8 McNonce[], [IN]uint16 SigningAlgorithm, [IN]uint8 DigitalSignature[])
Permission Information:
Permitted realms: ADMIN_SECURITY_LOCAL_SYSTEM_REALM

General Information:
Setup Intel(R) AMT from the local host, resulting in Admin Setup Mode. Requires OS administrator rights, and moves Intel(R) AMT from "Pre Provisioned" state to "Post Provisioned" state. The control mode after this method is run will be "Admin".

Qualifiers:
-------------
ValueMap={0, 1, 2, 3, 4, 5, 6, ..}
Values={SUCCESS, INTERNAL ERROR, INVALID STATE, INVALID PARAM, Reserved0, AUTH_FAILED, FLASH_WRITE_LIMIT_EXCEEDED, Reserved}


Parameters:
--------------
NetAdminPassEncryptionType
General Information:
The encryption type of the network admin password. Only HTTP-MD5 is supported. The values are the same as the CIM_Account.UserPasswordEncryptionAlgorithm field

Qualifiers:
-------------
Required
IN
ValueMap={0, 1, 2, ..}
Values={None, Other, HTTP Digest MD5(A1), DMTF Reserved}

NetworkAdminPassword
General Information:
New network admin password to be set by this command, encrypted using the encryption type algorithm

Qualifiers:
-------------
Required
IN
OctetString

McNonce
General Information:
A random nonce value generated by the configuration agent.Required if the digital signature is provided.needs to be concatenated after the configuration nonce and signed together with the attached certificate's private key

Qualifiers:
-------------
IN
OctetString

SigningAlgorithm
General Information:
The signing algorithm used to sign the setup operation.

Qualifiers:
-------------
IN
ValueMap={0, 1, 2, ..}
Values={None, Other, RSA_SHA-2_256, DMTF Reserved}

DigitalSignature
General Information:
A digital signature of the ConfigurationNonce and the McNonce concatenated. If this information is provided, AMT will validate the signature before accepting the command.

Qualifiers:
-------------
IN
OctetString



UpgradeClientToAdmin

public uint32 UpgradeClientToAdmin([IN]uint8 McNonce[], [IN]uint16 SigningAlgorithm, [IN]uint8 DigitalSignature[])
Permission Information:
Permitted realms: ADMIN_SECURITY_ADMINISTRATION_REALM

General Information:
Upgrade Intel(R) AMT from Client to Admin Control Mode. Requires AMT administrator rights, and that the machine has been previously provisioned in Client control mode.

Qualifiers:
-------------
ValueMap={0, 1, 2, 3, 4, 5, 6, ..}
Values={SUCCESS, INTERNAL ERROR, INVALID STATE, INVALID PARAM, Reserved, AUTH_FAILED, FLASH_WRITE_LIMIT_EXCEEDED, Reserved}


Parameters:
--------------
McNonce
General Information:
A random nonce value generated by the configuration agent.Required if the digital signature is provided.needs to be concatenated after the configuration nonce and signed together with the attached certificate's private key

Qualifiers:
-------------
IN
OctetString

SigningAlgorithm
General Information:
The signing algorithm used to sign the setup operation.

Qualifiers:
-------------
IN
ValueMap={0, 1, 2, ..}
Values={None, Other, RSA_SHA-2_256, DMTF Reserved}

DigitalSignature
General Information:
A digital signature of the ConfigurationNonce and the McNonce concatenated.If this information is provided, AMT will validate the signature before accepting the command.

Qualifiers:
-------------
IN
OctetString



DisableClientControlMode

public uint32 DisableClientControlMode()
Permission Information:
Permitted realms: ADMIN_SECURITY_ADMINISTRATION_REALM, ADMIN_SECURITY_LOCAL_SYSTEM_REALM

General Information:
Do not allow provisioning the machine in Client Control mode.

Qualifiers:
-------------
ValueMap={0, 1, ..}
Values={SUCCESS, INTERNAL ERROR, Reserved}


Get

public  Get([OUT]IPS_HostBasedSetupService Instance)
Permission Information:
Permitted realms: ADMIN_SECURITY_ADMINISTRATION_REALM, ADMIN_SECURITY_LOCAL_SYSTEM_REALM, ADMIN_SECURITY_GENERAL_INFO_REALM, ADMIN_SECURITY_LOCAL_APPS_REALM

General Information:
Gets the representation of the instance

Pull

public  Pull([IN]String EnumerationContext, [IN]String MaxElements)
Permission Information:
All users permitted to use method, only instances to whom the user has permissions will be returned

General Information:
Pulls instances of this class, following an Enumerate operation

Enumerate

public  Enumerate()
Permission Information:
All users permitted to use method

General Information:
Enumerates the instances of this class

Copyright © 2006-2022, Intel Corporation. All rights reserved.