pthi_wsman_lms_flow

PTHI vs WSMAN (and LME) Primer

Overview

This document describes the three key protocols used for Intel AMT management in rpc-go:

• PTHI: Direct binary protocol for basic state queries and control
• WSMAN: Full-featured HTTP/SOAP management protocol for provisioning
• LME: APF tunnel transport used when LMS is unavailable

Protocol Roles

PTHI (Platform Interface)

• Purpose: Direct binary protocol over MEI for basic operations
• Capabilities: Control/state queries, basic toggles (enable/disable AMT), device info (UUID, firmware versions), local credentials, unprovision
• Limitations: Cannot upload certificates/keys, cannot perform provisioning, cannot manage network settings
• Transport: Direct MEI communication using MEI_IAMTHIF GUID
• Implementation: pkg/pthi/commands.go, pkg/amt/commands.go

WSMAN (WS-Management)

• Purpose: Full-featured management protocol based on HTTP/SOAP standards
• Capabilities: Complete provisioning (CCM/ACM), certificate/key management, TLS contexts, network/Wi-Fi configuration, KVM/redirection, remote access policies
• Transport: HTTP over TCP (via LMS) or HTTP over APF tunnel (via LME)
• Implementation: internal/local/amt/wsman.go using go-wsman-messages library

LME (Local Management Engine)

• Purpose: APF tunnel transport when LMS (Local Management Service) is unavailable
• Function: Encapsulates WSMAN HTTP traffic over APF protocol channels on MEI
• Transport: MEI communication using MEI_LMEIF GUID
• Implementation: internal/lm/engine.go

Quick Reference: Protocol Stacks

PTHI Stack (Direct)

Application (pkg/amt/commands.go)
    ↓
PTHI Protocol (pkg/pthi/commands.go)
    ↓
MEI Driver (pkg/heci/linux.go) - GUID: MEI_IAMTHIF
    ↓
/dev/mei0 → Intel ME Firmware

WSMAN Stack (via LME)

Application (internal/local/amt/wsman.go)
    ↓
go-wsman-messages (HTTP/SOAP)
    ↓
LocalTransport (when LMS unavailable)
    ↓
LME Engine (internal/lm/engine.go) - APF Protocol
    ↓
MEI Driver (pkg/heci/linux.go) - GUID: MEI_LMEIF
    ↓
/dev/mei0 → Intel ME Firmware

WSMAN Stack (via LMS)

Application (internal/local/amt/wsman.go)
    ↓
go-wsman-messages (HTTP/SOAP)
    ↓
LMS Service :16992 (Intel Management Service)
    ↓
Intel ME Firmware

MEI Device Access

Device Constraints

• Device: /dev/mei0 (Linux) or HECI driver (Windows)
• Exclusivity: Only one file descriptor per process; PTHI and LME use different GUIDs but share the same device node
• Best Practice: Always close one connection before opening another to avoid EBUSY errors

GUID Usage

GUID	Purpose	Used By
MEI_IAMTHIF	PTHI protocol	Direct state/control operations
MEI_LMEIF	LME tunnel	APF channel for WSMAN when LMS unavailable
MEI_WDIF	Watchdog	Operational state checks

Operation Catalog

PTHI Operations

State/Info

• GetControlMode - Check provisioning state (pre-provisioned/CCM/ACM)
• GetUUID - Device unique identifier
• GetCodeVersions - Firmware version information
• GetDNSSuffix - DNS configuration
• GetLocalSystemAccount - Get admin username/password for CCM
• GetCertificateHashes - Read provisionable hash list

Control

• EnableAMT / DisableAMT - Toggle operational state
• Unprovision - Factory reset AMT configuration
• StopConfiguration - Halt provisioning process

WSMAN Operations

Provisioning

• HostBasedSetupService - CCM (Client Control Mode) activation
• HostBasedSetupServiceAdmin - ACM (Admin Control Mode) upgrade
• SetupAndConfigurationService.CommitChanges - Finalize configuration

Certificates & Keys

• PublicKeyCertificate - Enumerate/add certificates via AddNextCertInChain
• PublicPrivateKeyPair - Manage key pairs
• TLSCredentialContext - TLS credential configuration
• GeneratePKCS10RequestEx - Certificate signing request generation

Network Configuration

• AMT_GeneralSettings - General AMT settings
• AMT_EthernetPortSettings - Ethernet configuration
• IPS_WiFiPortConfigurationService - Wi-Fi configuration service
• WiFiEndpointSettings, IEEE8021xSettings - Wi-Fi profiles

Remote Management

• IPS_RedirectionService - Serial/IDE-R redirection
• IPS_OptInService - User opt-in management
• AMT_KVMRedirectionSAP - KVM redirection settings
• IPS_RemoteAccessPolicyRule, IPS_MPS, IPS_RemoteAccessPolicyAppliesToMPS - Remote access policies

Other Services

• IPS_TimeSynchronizationService - Time synchronization
• AuthorizationService.SetAdminAclEntryEx - Password management

Activation Workflows Details

Local Activation Path

sequenceDiagram
    participant App as Activate Command
    participant AMT as AMT Commands
    participant PTHI as PTHI Protocol
    participant WSMAN as WSMAN Client
    participant LME as LME Engine
    participant ME as Intel ME Firmware

    Note over App,ME: Phase 1: State Check via PTHI
    App->>AMT: Activate()
    AMT->>PTHI: GetControlMode()
    PTHI->>ME: Binary request (MEI_IAMTHIF)
    ME-->>PTHI: Pre-provisioned state
    PTHI-->>AMT: Control mode
    AMT->>PTHI: GetLocalSystemAccount()
    PTHI->>ME: Binary request
    ME-->>PTHI: admin credentials
    PTHI-->>AMT: username/password
    Note over AMT,PTHI: Close PTHI connection

    Note over App,ME: Phase 2: Provisioning via WSMAN
    AMT->>WSMAN: HostBasedSetupService()
    alt LMS available
        WSMAN->>ME: HTTP :16992 via LMS
    else LMS unavailable
        WSMAN->>LME: HTTP over APF
        LME->>ME: APF tunnel (MEI_LMEIF)
    end
    ME-->>WSMAN: CCM activated
    
    AMT->>WSMAN: AddNextCertInChain()
    WSMAN->>ME: Upload certificates
    ME-->>WSMAN: Cert installed
    
    AMT->>WSMAN: CommitChanges()
    WSMAN->>ME: Finalize config
    ME-->>WSMAN: Success
    WSMAN-->>AMT: Complete
    AMT-->>App: Device activated

Loading

Remote (RPS) Activation Path

sequenceDiagram
    participant RPS as RPS Server
    participant Executor as RPS Executor
    participant LME as LME Engine
    participant MEI as MEI Driver
    participant ME as Intel ME Firmware

    Note over RPS,ME: No PTHI - LME only
    
    RPS->>Executor: Provisioning request
    Executor->>LME: Open APF tunnel
    LME->>MEI: Open MEI_LMEIF
    MEI-->>LME: Connected
    
    loop APF Protocol Exchange
        Executor->>LME: APF control messages
        LME->>ME: APF protocol
        ME-->>LME: APF responses
        LME-->>Executor: Status
    end
    
    loop WSMAN Operations
        RPS->>Executor: WSMAN payload
        Executor->>LME: Forward via APF
        LME->>ME: WSMAN over APF tunnel
        ME-->>LME: WSMAN response
        LME-->>Executor: Response payload
        Executor-->>RPS: WSMAN result
    end
    
    Note over Executor,ME: All provisioning via WSMAN/APF
    Executor->>LME: Close tunnel
    LME->>MEI: Close

Loading

Protocol Call Flow Diagrams

PTHI Direct Communication

sequenceDiagram
    participant App as Application<br/>(pkg/amt/commands.go)
    participant PTHI as PTHI Protocol<br/>(pkg/pthi/commands.go)
    participant MEI as MEI Driver<br/>(pkg/heci/linux.go)
    participant Dev as /dev/mei0
    participant ME as Intel ME Firmware

    App->>PTHI: GetControlMode()
    PTHI->>MEI: Open(MEI_IAMTHIF)
    MEI->>Dev: Open device
    Dev-->>MEI: File descriptor
    PTHI->>MEI: Write(binary request)
    MEI->>Dev: ioctl/write
    Dev->>ME: Binary protocol
    ME-->>Dev: Binary response
    Dev-->>MEI: Read data
    MEI-->>PTHI: Response bytes
    PTHI-->>App: Control mode result
    PTHI->>MEI: Close()
    MEI->>Dev: Close device

Loading

WSMAN via LME Tunnel

sequenceDiagram
    participant App as Application<br/>(internal/local/amt/wsman.go)
    participant WSMAN as go-wsman-messages<br/>(HTTP/SOAP)
    participant LT as LocalTransport
    participant LME as LME Engine<br/>(internal/lm/engine.go)
    participant MEI as MEI Driver<br/>(pkg/heci/linux.go)
    participant Dev as /dev/mei0
    participant ME as Intel ME Firmware

    App->>WSMAN: HostBasedSetupService()
    WSMAN->>LT: HTTP POST request
    Note over LT: LMS unavailable
    LT->>LME: Send via APF channel
    LME->>MEI: Open(MEI_LMEIF)
    MEI->>Dev: Open device
    LME->>MEI: Write(APF protocol)
    MEI->>Dev: ioctl/write
    Dev->>ME: APF tunnel with HTTP payload
    ME-->>Dev: APF response with HTTP
    Dev-->>MEI: Read data
    MEI-->>LME: APF response bytes
    LME-->>LT: Extract HTTP response
    LT-->>WSMAN: HTTP response
    WSMAN-->>App: SOAP result
    LME->>MEI: Close()
    MEI->>Dev: Close device

Loading

WSMAN via LMS (Direct Network)

sequenceDiagram
    participant App as Application<br/>(internal/local/amt/wsman.go)
    participant WSMAN as go-wsman-messages<br/>(HTTP/SOAP)
    participant LMS as LMS Service<br/>(Intel Service)
    participant ME as Intel ME Firmware

    App->>WSMAN: HostBasedSetupService()
    WSMAN->>LMS: HTTP POST :16992
    Note over LMS: LMS running
    LMS->>ME: Forward to AMT
    ME-->>LMS: SOAP response
    LMS-->>WSMAN: HTTP response
    WSMAN-->>App: SOAP result

Loading

Error Handling

MEI Access Errors

• EBUSY: Device already in use; ensure proper connection closure between PTHI and LME operations
• Solution: Always close one protocol handler before opening another

Timeout Behavior

• LME Read Timeouts: 30-second poll timeouts are informational only
• APF Inactivity: Real timeout enforcement is 10 seconds, managed by APF protocol timer in the engine
• Best Practice: Monitor both timeout types for proper error diagnosis

Key Implementation Files

Component	File Path
PTHI Protocol	pkg/pthi/commands.go
MEI Driver (Linux)	pkg/heci/linux.go
AMT Commands	pkg/amt/commands.go
LME Engine	internal/lm/engine.go
WSMAN Client	internal/local/amt/wsman.go
RPS Executor	internal/rps/executor.go

Summary

PTHI = Direct binary protocol for quick state queries and basic control (like assembly language to ME firmware)

WSMAN = Standard HTTP/SOAP web service for complete provisioning and management (follows WS-Management specification)

LME = APF tunnel that carries WSMAN when LMS is unavailable (transparent transport layer)