CFG_StartConfigurationHBased

Note: This command is available starting Intel CSME 14.0. Starting Intel CSME 15.0 it uses the On-Die Certification Authority (ODCA).

When this API is invoked by the OS Agent, the Intel AMT firmware transitions to the IN_PROVISIONING State and waits for an incoming TLS session. If HostVPNEnable was set to True, Intel AMT also sets up the Host VPN for LMS port forwarding, to enable In-Band MTLS (mutual TLS authentication) on a local WS-MAN TLS port.

The Configuration Server can now open an MTLS session to Intel AMT via a local agent or LMS and pass its certificate chain to Intel AMT.

Unlike CFG_StartConfigurationEx, this command does not open the Intel AMT remote out-of-band port filters, as it is an In-Band Host Based Provisioning session.

CFG_StartConfigurationHBased_Request

typedef struct _CFG_StartConfigurationHBased_Request

{

    PTHI_MESSAGE_HEADER     Header;

    CERT_HASH_ALGORITHM      ServerHashAlgorithm;

    UINT8[SHA_512_KEY_SIZE] ServerCertHash;

    AMT_BOOLEAN     HostVPNEnable;

    UINT32     SuffixListLen;

    CHAR[320]     NetworkDnsSuffixList;

} CFG_StartConfigurationHBased_Request;

 

Field

Description

Header.Version

Major and minor interface version.

Header.Reserved

0000h

Header.Command

0x400008b

Header.Length

Message Length, excluding the message header.

ServerHashAlgorithm

The hash algorithm for the ServerCertHash field.
Supported:
CERT_HASH_ALGORITHM_SHA256, CERT_HASH_ALGORITHM_SHA384
Not supported:
CERT_HASH_ALGORITHM_SHA224, CERT_HASH_ALGORITHM_SHA512

ServerCertHash

Server leaf certificate hash that Intel AMT is allowed to accept for the Host Based Mutual TLS session.

HostVPNEnable

Enables Host VPN in In-Provisioning State. This enables in-band TCP/IP forwarding from configuration server to AMT via LMS for an in-band mutual TLS session.
FALSE: Disable VPN
TRUE: Enable VPN

SuffixListLen

(Optional)
Length of the DNS Suffix List. Maximum length: 320

NetworkDnsSuffixList

(Optional)
List of suffixes separated by a NULL terminator. Up to 5 DNS suffixes, up to 64 bytes each suffix.
When Host VPN is enabled, and the list is specified, Intel AMT enables environment detection during the In-Provisioning state.
LMS will forward connections only from interfaces that match the configured enterprise DNS suffix list.
When no list is set, LMS will forward connections from all interfaces.

CFG_StartConfigurationHBased Response

typedef struct _CFG_StartConfigurationHBased_Response

{

    PTHI_MESSAGE_HEADER     Header;

    AMT_STATUS              Status;

    CERT_HASH_ALGORITHM HashAlgorithm;

    UINT8[SHA_512_KEY_SIZE] AMTCertHash;

} CFG_StartConfigurationHBased_Response;

 

Field

Description

Header.Version

Major and minor interface version.

Header.Reserved

0000h

Header.Command

0x400008b

Header.Length

Message Length, excluding the message header.

Status

A status code returned in a response message that indicates whether the operation specified in the corresponding request message succeeded or failed. If the operation failed, this code indicates the specific reason for failure.

HashAlgorithm

The hash algorithm used for hashing the Intel AMT self-signed certificate – AMTCertHash.
CERT_HASH_ALGORITHM_SHA256 and CERT_HASH_ALGORITHM_SHA384 are supported.
CERT_HASH_ALGORITHM_SHA224 and CERT_HASH_ALGORITHM_SHA512 are not supported by the command.

AMTCertHash

The Intel AMT FW certificate hash (certificate fingerprint) used by Intel AMT in the Mutual TLS session (hashed with HashAlgorithm) .

CFG_StartConfigurationHBased Status Codes

Status

Description

AMT_STATUS_SUCCESS

Request succeeded.

AMT_STATUS_INTERNAL_ERROR

An internal error in the Intel AMT device has occurred

AMT_STATUS_NOT_READY

Management controller has not progressed far enough in its initialization to process the command.

AMT_STATUS_RNG_NOT_READY

Returned if RNG seed does not yet exist for establishing the Mutual TLS session

AMT_STATUS_CERTIFICATE_NOT_READY

Returned when Intel AMT certificate does not yet exist

AMT_STATUS_INVALID_AMT_MODE

Returned when firmware is not in pre-provision state

AMT_STATUS_INVALID_MESSAGE_LENGTH

Length field of header is invalid.

CERT_HASH_ALGORITHM

typedef enum

{

    CERT_HASH_ALGORITHM_MD5     = 0,

    CERT_HASH_ALGORITHM_SHA1 = 1,

    CERT_HASH_ALGORITHM_SHA256 = 2,

    CERT_HASH_ALGORITHM_SHA384 = 3,

    CERT_HASH_ALGORITHM_SHA224 = 4,

    CERT_HASH_ALGORITHM_SHA512 = 5,

} CERT_HASH_ALGORITHM;


Note: sizeof (enum) is sizeof (UINT8) = 1 byte.

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