Skip to content

Wireless Profile Management Architecture

Jump to bottom
shaoboon edited this page Jun 10, 2026 · 1 revision

This document describes the architecture introduced by the wireless profile management feature in Console. It lets an operator perform CRUD operations on the WiFi profiles stored on an Intel® AMT managed device.

1. High-level architecture

Two systems are involved: Console (the management application) and the AMT Device (the managed endpoint). Console exposes a user-facing REST API on one side and talks to the device over WS-Management (WSMAN) on the other, using the Intel® AMT SDK semantics implemented by the go-wsman-messages library.

flowchart LR
    subgraph CLIENT["API Consumer"]
        UI["Operator / Web UI / curl"]
    end

    subgraph CONSOLE["Console (management application)"]
        direction TB
        API["User-facing REST API<br/>(HTTP/JSON, gin)<br/>/api/v1/amt/networkSettings/wireless/profile"]
        UC["Devices Use Case<br/>(business rules, validation,<br/>cert orchestration)"]
        WSMAN["WSMAN Management interface<br/>(ConnectionEntry adapter)"]
        API --> UC --> WSMAN
    end

    subgraph DEVICE["AMT Device (managed endpoint)"]
        direction TB
        WPCS["AMT_WiFiPortConfigurationService"]
        WES["CIM_WiFiEndpointSettings"]
        X1["CIM_IEEE8021xSettings"]
        PKMS["AMT_PublicKeyManagementService<br/>(certs / private keys)"]
    end

    UI -- "HTTPS + Bearer token" --> API
    WSMAN -- "WS-Management (SOAP/XML over HTTPS)<br/>via go-wsman-messages v2 (Intel AMT SDK)" --> WPCS
    WPCS --- WES
    WPCS --- X1
    WSMAN -. "802.1x cert provisioning" .-> PKMS
Loading

AMT SDK in use: github.com/device-management-toolkit/go-wsman-messages/v2 (pinned at v2.47.2 in go.mod). This is the Go implementation of the Intel® AMT WS-Management class model; the WiFi feature drives the AMT_WiFiPortConfigurationService class and its associated CIM_WiFiEndpointSettings / CIM_IEEE8021xSettings instances.

2. Console interfaces

Console has exactly two external interfaces relevant to this feature.

2.1 User-facing API (north-bound)

REST/JSON endpoints registered in internal/controller/httpapi/v1/devicemanagement.go, handled in internal/controller/httpapi/v1/wifiprofile.go:

Method Path Handler Success
GET /api/v1/amt/networkSettings/wireless/profile/:guid getWirelessProfiles 200 OK + sanitized list
POST /api/v1/amt/networkSettings/wireless/profile/:guid addWirelessProfile 204 No Content
PATCH /api/v1/amt/networkSettings/wireless/profile/:guid updateWirelessProfile 204 No Content
DELETE /api/v1/amt/networkSettings/wireless/profile/:guid/:profileName deleteWirelessProfile 204 No Content

Request binding and validation:

  • Payload type WirelessProfileRequest in internal/entity/dto/v1/wifiprofile.go.
  • Custom validator wirelessprofile (dto.ValidateWirelessProfile) registered in internal/controller/httpapi/router.go; it checks profile name charset, SSID, priority range (1–255), and that the authentication/encryption methods and credentials are mutually consistent (PSK requires a password; 802.1x requires an IEEE8021x block).
  • Responses are sanitized: WirelessProfileResponse intentionally omits passwords, certificates, and private keys. Only username and authenticationProtocol are surfaced for 802.1x profiles.

2.2 Device interface (south-bound) — Intel AMT SDK

Console talks to the device through the wsman.Management interface in internal/usecase/devices/wsman/interfaces.go, implemented by ConnectionEntry in internal/usecase/devices/wsman/message.go. Each method is a thin wrapper over a go-wsman-messages call. The WiFi-relevant operations:

Console interface method AMT SDK call (go-wsman-messages) AMT class / method
GetWiFiSettings() enumerate/pull WiFi endpoint settings CIM_WiFiEndpointSettings
GetCIMIEEE8021xSettings() enumerate/pull 802.1x settings CIM_IEEE8021xSettings
GetConcreteDependencies() enumerate associations CIM_ConcreteDependency
AddWiFiSettings(...) AMT.WiFiPortConfigurationService.AddWiFiSettings AMT_WiFiPortConfigurationService.AddWiFiSettings
UpdateWiFiSettings(...) AMT.WiFiPortConfigurationService.UpdateWiFiSettings AMT_WiFiPortConfigurationService.UpdateWiFiSettings
DeleteWiFiSetting(id) delete WiFi endpoint settings instance CIM_WiFiEndpointSettings
AddTrustedRootCert(...) AMT.PublicKeyManagementService.AddTrustedRootCertificate AMT_PublicKeyManagementService
AddClientCert(...) add client certificate AMT_PublicKeyManagementService
AddPrivateKey(...) add private key AMT_PublicKeyManagementService

Transport: WS-Management (SOAP/XML) over HTTPS to the device, established via SetupWsmanClient before each operation.

3. Business logic layer (Devices Use Case)

Implemented in internal/usecase/devices/wifiprofile.go. Responsibilities that sit between the API and the SDK:

  • Setup — setupWirelessProfileManagement loads the device by GUID and opens a WSMAN client.
  • Uniqueness rules — on add/update, reject duplicate profile names and duplicate priorities (findWirelessSettingByProfileName, findWirelessSettingByPriority).
  • Read assembly — getWirelessProfilesFromDevice merges WiFi endpoint settings with their associated 802.1x settings by walking CIM_ConcreteDependency associations (with profile-name fallbacks).
  • 802.1x certificate orchestration — when a profile carries an IEEE8021x block, prepareWirelessProfileForApply → configureIEEE8021xCertificates resolves or provisions the private key, client cert, and CA cert on the device (via AddPrivateKey / AddClientCert / AddTrustedRootCert), reusing existing handles when present. A short pause (waitForAMTCertificateHandling) is applied before the apply when new certificate material was added.
sequenceDiagram
    participant C as API Consumer
    participant A as Console API (gin)
    participant U as Devices Use Case
    participant W as WSMAN adapter (go-wsman-messages)
    participant D as AMT Device

    C->>A: POST /wireless/profile/{guid} (JSON)
    A->>A: Bind + validate (wirelessprofile)
    A->>U: AddWirelessProfile(guid, profile)
    U->>W: GetWiFiSettings()
    W->>D: WSMAN enumerate CIM_WiFiEndpointSettings
    D-->>W: existing settings
    U->>U: check duplicate name / priority
    alt profile uses 802.1x
        U->>W: AddPrivateKey / AddClientCert / AddTrustedRootCert
        W->>D: WSMAN AMT_PublicKeyManagementService
        U->>U: pause for cert handling
    end
    U->>W: AddWiFiSettings(wifi, 8021x, endpoint, certHandles)
    W->>D: WSMAN AMT_WiFiPortConfigurationService.AddWiFiSettings
    D-->>W: result
    W-->>U: ok
    U-->>A: nil error
    A-->>C: 204 No Content
Loading

4. AMT Device side

The device exposes the WS-Management class model the SDK targets:

  • AMT_WiFiPortConfigurationService — service that adds/updates wireless profiles (AddWiFiSettings, UpdateWiFiSettings).
  • CIM_WiFiEndpointSettings — one instance per wireless profile (SSID, priority, authentication/encryption method).
  • CIM_IEEE8021xSettings — the 802.1x/EAP settings linked to an endpoint settings instance via CIM_ConcreteDependency.
  • AMT_PublicKeyManagementService — stores the certificates and private keys referenced by 802.1x profiles.

Per the Intel AMT SDK, AddWiFiSettings / UpdateWiFiSettings are gated by realm (ADMIN_SECURITY_ADMINISTRATION_REALM, ADMIN_SECURITY_LOCAL_SYSTEM_REALM) — not by control mode — so the operations are accepted in both Admin Control Mode (ACM) and Client Control Mode (CCM) when the caller holds an admin credential.

5. Key files

Concern File
HTTP handlers internal/controller/httpapi/v1/wifiprofile.go
Route registration internal/controller/httpapi/v1/devicemanagement.go
Validator registration internal/controller/httpapi/router.go
DTO + validators internal/entity/dto/v1/wifiprofile.go
Use case (business logic) internal/usecase/devices/wifiprofile.go
WSMAN interface internal/usecase/devices/wsman/interfaces.go
WSMAN adapter (SDK calls) internal/usecase/devices/wsman/message.go
AMT SDK dependency go.mod — go-wsman-messages/v2 v2.47.2

Console Wiki

ADRs

Clone this wiki locally