AKM SDK - AMM Integration

AMM HMI API Integration

The AMM (AKM Management Module) provides a binary TCP interface for endpoint provisioning and trust relationship management. This guide shows how to connect directly to AMM using the HMI (Human-Machine Interface) API.

Connection: TCP port 49200 - Binary protocol with message headers

Protocol Overview

Message Header (12 bytes)

All messages to/from AMM are prefixed with a 12-byte header:

Offset	Size	Field	Value
0	4	Start of Message	`0xA55A5AA5`
4	1	Major Version	`0x01`
5	1	Minor Version	`0x00`
6	2	Message Length	Payload size (U16, little-endian)
8	2	Length Complement	~Message_Length & 0xFFFF
10	2	Reserved	`0x0000`

Request Types

Code	Name	Response
`0x01`	LIST_ENDPOINTS_REQUEST	`0x41`
`0x02`	GET_ENDPOINT_DETAILS_REQUEST	`0x42`
`0x03`	PROVISION_ENDPOINT_REQUEST	`0x43`
`0x04`	CREATE_OPERATIONAL_ATR_REQUEST	`0x44`
`0x05`	LIST_ATRS_REQUEST	`0x45`
`0x06`	DELETE_ENDPOINT_REQUEST	`0x46`
`0x07`	DELETE_ATR_REQUEST	`0x47`

Connection Setup

Connect to AMM using a TCP socket on port 49200:

Connection Setup

import socket
import struct

AMM_PORT = 49200
AMM_HOST = "172.31.7.13"
AMM_HMI_SOM = 0xA55A5AA5
MAX_ENDPOINTS = 32
MAX_ATRS = 64

class AMMClient:
    def __init__(self, host: str, port: int = AMM_PORT):
        self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        self.sock.connect((host, port))

    def close(self):
        self.sock.close()

    def _build_header(self, payload_len: int) -> bytes:
        """Build 12-byte AMM message header."""
        length_comp = (~payload_len) & 0xFFFF
        return struct.pack(
            "<IBBHHH",
            AMM_HMI_SOM,  # SOM
            0x01,         # Major version
            0x00,         # Minor version
            payload_len,
            length_comp,
            0x0000        # Reserved
        )

    def _recv_exact(self, size: int) -> bytes:
        """Receive exactly size bytes."""
        data = b""
        while len(data) < size:
            chunk = self.sock.recv(size - len(data))
            if not chunk:
                raise ConnectionError("Connection closed")
            data += chunk
        return data

# Connect to AMM
client = AMMClient(AMM_HOST)
print("[*] Connected to AMM")

#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>

#define AMM_PORT 49200
#define AMM_HMI_SOM 0xA55A5AA5
#define MAX_ENDPOINTS 32
#define MAX_ATRS 64

#pragma pack(push, 1)
typedef struct {
    uint32_t som;
    uint8_t  major_version;
    uint8_t  minor_version;
    uint16_t msg_length;
    uint16_t msg_length_comp;
    uint16_t reserved;
} amm_header_t;
#pragma pack(pop)

void init_header(amm_header_t* hdr, uint16_t payload_len) {
    hdr->som = AMM_HMI_SOM;
    hdr->major_version = 0x01;
    hdr->minor_version = 0x00;
    hdr->msg_length = payload_len;
    hdr->msg_length_comp = ~payload_len & 0xFFFF;
    hdr->reserved = 0;
}

int recv_exact(int sock, void* buf, size_t len) {
    size_t received = 0;
    while (received < len) {
        ssize_t n = recv(sock, (char*)buf + received, len - received, 0);
        if (n <= 0) return -1;
        received += n;
    }
    return 0;
}

int amm_connect(const char* host, uint16_t port) {
    int sock = socket(AF_INET, SOCK_STREAM, 0);
    if (sock < 0) return -1;

    struct sockaddr_in addr = {0};
    addr.sin_family = AF_INET;
    addr.sin_port = htons(port);
    inet_pton(AF_INET, host, &addr.sin_addr);

    if (connect(sock, (struct sockaddr*)&addr, sizeof(addr)) < 0) {
        close(sock);
        return -1;
    }
    return sock;
}

// Connect to AMM
int sock = amm_connect("172.31.7.13", AMM_PORT);
printf("[*] Connected to AMM\n");

#include <cstdint>
#include <string>
#include <vector>
#include <stdexcept>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <unistd.h>

namespace akm {

constexpr uint16_t AMM_PORT = 49200;
constexpr uint32_t AMM_HMI_SOM = 0xA55A5AA5;
constexpr size_t MAX_ENDPOINTS = 32;
constexpr size_t MAX_ATRS = 64;

#pragma pack(push, 1)
struct MsgHeader {
    uint32_t som;
    uint8_t major_version;
    uint8_t minor_version;
    uint16_t msg_length;
    uint16_t msg_length_comp;
    uint16_t reserved;

    void init(uint16_t payload_len) {
        som = AMM_HMI_SOM;
        major_version = 1;
        minor_version = 0;
        msg_length = payload_len;
        msg_length_comp = ~payload_len & 0xFFFF;
        reserved = 0;
    }
};
#pragma pack(pop)

class AMMClient {
public:
    AMMClient() : sock_(-1) {}
    ~AMMClient() { disconnect(); }

    void connect(const std::string& host, uint16_t port = AMM_PORT) {
        sock_ = socket(AF_INET, SOCK_STREAM, 0);
        if (sock_ < 0) throw std::runtime_error("socket() failed");

        sockaddr_in addr{};
        addr.sin_family = AF_INET;
        addr.sin_port = htons(port);
        inet_pton(AF_INET, host.c_str(), &addr.sin_addr);

        if (::connect(sock_, (sockaddr*)&addr, sizeof(addr)) < 0) {
            close(sock_);
            throw std::runtime_error("connect() failed");
        }
    }

    void disconnect() {
        if (sock_ >= 0) { close(sock_); sock_ = -1; }
    }

private:
    int sock_;
};

} // namespace akm

// Connect to AMM
akm::AMMClient client;
client.connect("172.31.7.13");
std::cout << "[*] Connected to AMM" << std::endl;

use std::net::TcpStream;
use std::io::{Read, Write, Result};

const AMM_PORT: u16 = 49200;
const AMM_HMI_SOM: u32 = 0xA55A5AA5;
const MAX_ENDPOINTS: usize = 32;
const MAX_ATRS: usize = 64;

pub struct AMMClient {
    stream: TcpStream,
}

impl AMMClient {
    pub fn connect(host: &str, port: u16) -> Result<Self> {
        let stream = TcpStream::connect((host, port))?;
        Ok(Self { stream })
    }

    fn build_header(&self, payload_len: u16) -> [u8; 12] {
        let length_comp = !payload_len;
        let mut header = [0u8; 12];

        header[0..4].copy_from_slice(&AMM_HMI_SOM.to_le_bytes());
        header[4] = 0x01;  // Major version
        header[5] = 0x00;  // Minor version
        header[6..8].copy_from_slice(&payload_len.to_le_bytes());
        header[8..10].copy_from_slice(&length_comp.to_le_bytes());
        header[10..12].copy_from_slice(&0u16.to_le_bytes());

        header
    }

    fn recv_exact(&mut self, buf: &mut [u8]) -> Result<()> {
        let mut received = 0;
        while received < buf.len() {
            let n = self.stream.read(&mut buf[received..])?;
            if n == 0 {
                return Err(std::io::Error::new(
                    std::io::ErrorKind::UnexpectedEof,
                    "connection closed"
                ));
            }
            received += n;
        }
        Ok(())
    }
}

// Connect to AMM
let client = AMMClient::connect("172.31.7.13", AMM_PORT)?;
println!("[*] Connected to AMM");

List Endpoints

Query AMM for all provisioned endpoints:

List Endpoints

# Request codes
LIST_ENDPOINTS_REQUEST = 0x01
ENDPOINT_LIST_RESPONSE = 0x41

def list_endpoints(self, filter_type: int = 0) -> list:
    """List all endpoints from AMM."""
    # Build request: header + api_request (4) + filter (4)
    payload = struct.pack("<II", LIST_ENDPOINTS_REQUEST, filter_type)
    request = self._build_header(len(payload)) + payload

    self.sock.sendall(request)

    # Response: header(12) + api_response(4) + confirmation(4) + num(4) + endpoints(32*16)
    response = self._recv_exact(12 + 4 + 4 + 4 + MAX_ENDPOINTS * 16)

    # Parse header
    som, = struct.unpack("<I", response[0:4])
    if som != AMM_HMI_SOM:
        raise ValueError(f"Invalid SOM: 0x{som:08X}")

    # Parse payload
    api_response, confirmation, num_endpoints = struct.unpack("<III", response[12:24])

    endpoints = []
    offset = 24
    for i in range(min(num_endpoints, MAX_ENDPOINTS)):
        lower64, upper64 = struct.unpack("<QQ", response[offset:offset+16])
        endpoints.append({"lower64": lower64, "upper64": upper64})
        offset += 16

    return endpoints

# Usage
client = AMMClient(AMM_HOST)
endpoints = client.list_endpoints()
print(f"Found {len(endpoints)} endpoints:")
for i, ep in enumerate(endpoints):
    print(f"  [{i}] 0x{ep['lower64']:016X}")

#define LIST_ENDPOINTS_REQUEST 0x01
#define ENDPOINT_LIST_RESPONSE 0x41

#pragma pack(push, 1)
typedef struct {
    uint64_t lower64;
    uint64_t upper64;
} endpoint_id_t;

typedef struct {
    amm_header_t header;
    uint32_t api_request;
    uint32_t filter_type;
} list_endpoints_req_t;

typedef struct {
    amm_header_t header;
    uint32_t api_response;
    uint32_t confirmation;
    uint32_t num_endpoints;
    endpoint_id_t endpoints[MAX_ENDPOINTS];
} list_endpoints_resp_t;
#pragma pack(pop)

int amm_list_endpoints(int sock, endpoint_id_t* endpoints, uint32_t* count) {
    list_endpoints_req_t req = {0};
    init_header(&req.header, sizeof(req) - sizeof(amm_header_t));
    req.api_request = LIST_ENDPOINTS_REQUEST;
    req.filter_type = 0;

    if (send(sock, &req, sizeof(req), 0) != sizeof(req)) {
        return -1;
    }

    list_endpoints_resp_t resp;
    if (recv_exact(sock, &resp, sizeof(resp)) < 0) {
        return -1;
    }

    if (resp.header.som != AMM_HMI_SOM) return -1;
    if (resp.api_response != ENDPOINT_LIST_RESPONSE) return -1;

    *count = resp.num_endpoints;
    if (*count > MAX_ENDPOINTS) *count = MAX_ENDPOINTS;
    memcpy(endpoints, resp.endpoints, *count * sizeof(endpoint_id_t));

    return 0;
}

// Usage
endpoint_id_t endpoints[MAX_ENDPOINTS];
uint32_t count = 0;
if (amm_list_endpoints(sock, endpoints, &count) == 0) {
    printf("Found %u endpoints:\n", count);
    for (uint32_t i = 0; i < count; i++) {
        printf("  [%u] 0x%016llX\n", i, endpoints[i].lower64);
    }
}

enum class RequestType : uint32_t {
    ListEndpoints = 0x01,
    GetEndpointDetails = 0x02,
    ProvisionEndpoint = 0x03,
    CreateOperationalATR = 0x04,
    ListATRs = 0x05,
    DeleteEndpoint = 0x06,
    DeleteATR = 0x07
};

struct EndpointId {
    uint64_t lower64;
    uint64_t upper64;
};

std::vector<EndpointId> listEndpoints(uint32_t filter = 0) {
    #pragma pack(push, 1)
    struct Request {
        MsgHeader header;
        uint32_t api_request;
        uint32_t filter_type;
    };

    struct Response {
        MsgHeader header;
        uint32_t api_response;
        uint32_t confirmation;
        uint32_t num_endpoints;
        EndpointId endpoints[MAX_ENDPOINTS];
    };
    #pragma pack(pop)

    Request req{};
    req.header.init(sizeof(Request) - sizeof(MsgHeader));
    req.api_request = static_cast<uint32_t>(RequestType::ListEndpoints);
    req.filter_type = filter;

    sendAll(&req, sizeof(req));

    Response resp{};
    recvAll(&resp, sizeof(resp));

    if (resp.header.som != AMM_HMI_SOM) {
        throw std::runtime_error("Invalid SOM");
    }

    std::vector<EndpointId> result;
    for (uint32_t i = 0; i < resp.num_endpoints && i < MAX_ENDPOINTS; i++) {
        result.push_back(resp.endpoints[i]);
    }
    return result;
}

// Usage
auto endpoints = client.listEndpoints();
std::cout << "Found " << endpoints.size() << " endpoints:" << std::endl;
for (size_t i = 0; i < endpoints.size(); i++) {
    std::cout << "  [" << i << "] 0x" << std::hex
              << endpoints[i].lower64 << std::dec << std::endl;
}

const LIST_ENDPOINTS_REQUEST: u32 = 0x01;
const ENDPOINT_LIST_RESPONSE: u32 = 0x41;

#[derive(Debug, Clone, Copy)]
pub struct EndpointId {
    pub lower64: u64,
    pub upper64: u64,
}

impl AMMClient {
    pub fn list_endpoints(&mut self, filter: u32) -> Result<Vec<EndpointId>> {
        // Build request
        let payload_len: u16 = 8; // api_request(4) + filter(4)
        let header = self.build_header(payload_len);

        let mut request = Vec::with_capacity(12 + 8);
        request.extend_from_slice(&header);
        request.extend_from_slice(&LIST_ENDPOINTS_REQUEST.to_le_bytes());
        request.extend_from_slice(&filter.to_le_bytes());

        self.stream.write_all(&request)?;

        // Read response
        let resp_size = 12 + 4 + 4 + 4 + (MAX_ENDPOINTS * 16);
        let mut response = vec![0u8; resp_size];
        self.recv_exact(&mut response)?;

        // Validate SOM
        let som = u32::from_le_bytes(response[0..4].try_into().unwrap());
        if som != AMM_HMI_SOM {
            return Err(std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                "Invalid SOM"
            ));
        }

        let num_endpoints = u32::from_le_bytes(
            response[20..24].try_into().unwrap()
        ) as usize;

        let mut endpoints = Vec::with_capacity(num_endpoints.min(MAX_ENDPOINTS));
        let mut offset = 24;
        for _ in 0..num_endpoints.min(MAX_ENDPOINTS) {
            let lower64 = u64::from_le_bytes(response[offset..offset+8].try_into().unwrap());
            let upper64 = u64::from_le_bytes(response[offset+8..offset+16].try_into().unwrap());
            endpoints.push(EndpointId { lower64, upper64 });
            offset += 16;
        }

        Ok(endpoints)
    }
}

// Usage
let endpoints = client.list_endpoints(0)?;
println!("Found {} endpoints:", endpoints.len());
for (i, ep) in endpoints.iter().enumerate() {
    println!("  [{}] 0x{:016X}", i, ep.lower64);
}

List ATRs

Query AMM for all trust relationships:

List ATRs

LIST_ATRS_REQUEST = 0x05
ATR_LIST_RESPONSE = 0x45

ATR_CATEGORIES = {
    0: "Illegal",
    1: "Bootstrap",
    2: "Provisional",
    3: "Operational"
}

def list_atrs(self, filter_type: int = 0) -> list:
    """List all ATRs from AMM."""
    payload = struct.pack("<II", LIST_ATRS_REQUEST, filter_type)
    request = self._build_header(len(payload)) + payload

    self.sock.sendall(request)

    # Response: header(12) + api_response(4) + confirmation(4) + num(4) + atrs(64*20)
    # Each ATR: category(4) + lower64(8) + upper64(8) = 20 bytes
    response = self._recv_exact(12 + 4 + 4 + 4 + MAX_ATRS * 20)

    som, = struct.unpack("<I", response[0:4])
    if som != AMM_HMI_SOM:
        raise ValueError(f"Invalid SOM: 0x{som:08X}")

    api_response, confirmation, num_atrs = struct.unpack("<III", response[12:24])

    atrs = []
    offset = 24
    for i in range(min(num_atrs, MAX_ATRS)):
        category, lower64, upper64 = struct.unpack("<IQQ", response[offset:offset+20])
        atrs.append({
            "category": category,
            "category_name": ATR_CATEGORIES.get(category, "Unknown"),
            "lower64": lower64,
            "upper64": upper64
        })
        offset += 20

    return atrs

# Usage
atrs = client.list_atrs()
print(f"Found {len(atrs)} ATRs:")
for i, atr in enumerate(atrs):
    print(f"  [{i}] {atr['category_name']} - 0x{atr['lower64']:016X}")

#define LIST_ATRS_REQUEST 0x05
#define ATR_LIST_RESPONSE 0x45

#pragma pack(push, 1)
typedef struct {
    uint32_t category;
    uint64_t lower64;
    uint64_t upper64;
} atr_entry_t;

typedef struct {
    amm_header_t header;
    uint32_t api_request;
    uint32_t filter_type;
} list_atrs_req_t;

typedef struct {
    amm_header_t header;
    uint32_t api_response;
    uint32_t confirmation;
    uint32_t num_atrs;
    atr_entry_t atrs[MAX_ATRS];
} list_atrs_resp_t;
#pragma pack(pop)

const char* atr_category_name(uint32_t category) {
    switch (category) {
        case 0: return "Illegal";
        case 1: return "Bootstrap";
        case 2: return "Provisional";
        case 3: return "Operational";
        default: return "Unknown";
    }
}

int amm_list_atrs(int sock, atr_entry_t* atrs, uint32_t* count) {
    list_atrs_req_t req = {0};
    init_header(&req.header, sizeof(req) - sizeof(amm_header_t));
    req.api_request = LIST_ATRS_REQUEST;
    req.filter_type = 0;

    if (send(sock, &req, sizeof(req), 0) != sizeof(req)) return -1;

    list_atrs_resp_t resp;
    if (recv_exact(sock, &resp, sizeof(resp)) < 0) return -1;

    if (resp.header.som != AMM_HMI_SOM) return -1;

    *count = resp.num_atrs;
    if (*count > MAX_ATRS) *count = MAX_ATRS;
    memcpy(atrs, resp.atrs, *count * sizeof(atr_entry_t));

    return 0;
}

// Usage
atr_entry_t atrs[MAX_ATRS];
uint32_t count = 0;
if (amm_list_atrs(sock, atrs, &count) == 0) {
    printf("Found %u ATRs:\n", count);
    for (uint32_t i = 0; i < count; i++) {
        printf("  [%u] %s - 0x%016llX\n",
               i, atr_category_name(atrs[i].category), atrs[i].lower64);
    }
}

struct ATREntry {
    uint32_t category;
    uint64_t lower64;
    uint64_t upper64;

    std::string categoryName() const {
        switch (category) {
            case 0: return "Illegal";
            case 1: return "Bootstrap";
            case 2: return "Provisional";
            case 3: return "Operational";
            default: return "Unknown";
        }
    }
};

std::vector<ATREntry> listATRs(uint32_t filter = 0) {
    #pragma pack(push, 1)
    struct Request {
        MsgHeader header;
        uint32_t api_request;
        uint32_t filter_type;
    };

    struct Response {
        MsgHeader header;
        uint32_t api_response;
        uint32_t confirmation;
        uint32_t num_atrs;
        ATREntry atrs[MAX_ATRS];
    };
    #pragma pack(pop)

    Request req{};
    req.header.init(sizeof(Request) - sizeof(MsgHeader));
    req.api_request = static_cast<uint32_t>(RequestType::ListATRs);
    req.filter_type = filter;

    sendAll(&req, sizeof(req));

    Response resp{};
    recvAll(&resp, sizeof(resp));

    std::vector<ATREntry> result;
    for (uint32_t i = 0; i < resp.num_atrs && i < MAX_ATRS; i++) {
        result.push_back(resp.atrs[i]);
    }
    return result;
}

// Usage
auto atrs = client.listATRs();
std::cout << "Found " << atrs.size() << " ATRs:" << std::endl;
for (size_t i = 0; i < atrs.size(); i++) {
    std::cout << "  [" << i << "] " << atrs[i].categoryName()
              << " - 0x" << std::hex << atrs[i].lower64 << std::dec << std::endl;
}

const LIST_ATRS_REQUEST: u32 = 0x05;
const ATR_LIST_RESPONSE: u32 = 0x45;

#[derive(Debug, Clone, Copy)]
pub struct AtrEntry {
    pub category: u32,
    pub lower64: u64,
    pub upper64: u64,
}

impl AtrEntry {
    pub fn category_name(&self) -> &'static str {
        match self.category {
            0 => "Illegal",
            1 => "Bootstrap",
            2 => "Provisional",
            3 => "Operational",
            _ => "Unknown",
        }
    }
}

impl AMMClient {
    pub fn list_atrs(&mut self, filter: u32) -> Result<Vec<AtrEntry>> {
        let payload_len: u16 = 8;
        let header = self.build_header(payload_len);

        let mut request = Vec::with_capacity(12 + 8);
        request.extend_from_slice(&header);
        request.extend_from_slice(&LIST_ATRS_REQUEST.to_le_bytes());
        request.extend_from_slice(&filter.to_le_bytes());

        self.stream.write_all(&request)?;

        // Each ATR: category(4) + lower64(8) + upper64(8) = 20 bytes
        let resp_size = 12 + 4 + 4 + 4 + (MAX_ATRS * 20);
        let mut response = vec![0u8; resp_size];
        self.recv_exact(&mut response)?;

        let num_atrs = u32::from_le_bytes(
            response[20..24].try_into().unwrap()
        ) as usize;

        let mut atrs = Vec::with_capacity(num_atrs.min(MAX_ATRS));
        let mut offset = 24;
        for _ in 0..num_atrs.min(MAX_ATRS) {
            let category = u32::from_le_bytes(response[offset..offset+4].try_into().unwrap());
            let lower64 = u64::from_le_bytes(response[offset+4..offset+12].try_into().unwrap());
            let upper64 = u64::from_le_bytes(response[offset+12..offset+20].try_into().unwrap());
            atrs.push(AtrEntry { category, lower64, upper64 });
            offset += 20;
        }

        Ok(atrs)
    }
}

// Usage
let atrs = client.list_atrs(0)?;
println!("Found {} ATRs:", atrs.len());
for (i, atr) in atrs.iter().enumerate() {
    println!("  [{}] {} - 0x{:016X}", i, atr.category_name(), atr.lower64);
}

Key Data Structures

Endpoint Identifier (16 bytes)

0-7	lower64 (U64)
8-15	upper64 (U64)

ATR Categories

`0`	Illegal Value
`1`	Bootstrap Provisional
`2`	Provisional
`3`	Operational

AMM Integration

AMM HMI API Integration

Protocol Overview

Message Header (12 bytes)

Request Types

Connection Setup

List Endpoints

List ATRs

Key Data Structures

Endpoint Identifier (16 bytes)

ATR Categories

Next Steps

API Reference

AppEndpoint Integration