Certificate Architecture

Introduction

This page documents the certificate architecture of AosCore — the hierarchical trust model that establishes cryptographic identity for every component in the system. Understanding this architecture is essential for OEMs configuring certificate modules, integrating with enterprise PKI infrastructure, and troubleshooting authentication failures between components.

AosCore uses a certificate-based identity system where the cloud Certificate Authority (CA) serves as the root of trust. Each component (CM, SM, IAM, MP) holds certificates issued through this CA, and all inter-component communication is authenticated via mutual TLS (mTLS). The Identity and Access Manager (IAM) on each Node manages the local certificate lifecycle — generating keys, creating CSRs, applying signed certificates, and notifying components of renewals.

Certificate Hierarchy Diagram

The following diagram shows the certificate hierarchy across a Unit with Main and Secondary Nodes, including the certificate modules managed by each Node's IAM instance:

loading...

Root of Trust: Cloud CA

The cloud Certificate Authority is the ultimate trust anchor for the entire AosEdge system. All component certificates chain back to the cloud CA:

• The CA's root certificate is distributed to each Node during provisioning and stored as the CACert in the component configuration
• Every certificate issued to a component is signed (directly or through an intermediate) by this CA
• Trust chain validation ensures that only certificates traceable to the cloud CA are accepted for mTLS connections

The CA root certificate file path is configured per component (typically /etc/Root_CA.pem or a similar system path). Components load this certificate at startup and use it to verify the identity of peers during TLS handshakes.

Certificate Types

AosCore organizes certificates by type — a string identifier that maps to a specific certificate module configuration. Each type serves a distinct purpose in the system:

Certificate Type	Extended Key Usage	Purpose	Used By
iam	serverAuth + clientAuth	IAM gRPC server identity (public and protected APIs)	IAM
cm	clientAuth	CM client authentication to cloud and SM controller	CM
sm	clientAuth	SM client authentication to CM	SM
online	clientAuth	Cloud communication authentication (TLS client cert)	CM
offline	clientAuth	Offline Unit identity verification	Unit-level identity

IAM Certificate (iam)

The IAM certificate is unique in requiring both serverAuth and clientAuth extended key usage:

• Server auth — IAM exposes gRPC servers (public API on the open port, protected API on the secure port) that other components connect to. The server certificate authenticates IAM's identity to clients.
• Client auth — IAM also acts as a client when connecting to the Main Node's IAM (on Secondary Nodes) or when communicating with the cloud during provisioning.

IAM's certificate is the first to be established during provisioning, as other components depend on IAM's server being authenticated before they can obtain their own certificates.

CM Certificate (cm)

The Communication Manager uses its certificate for client authentication in two contexts:

• Cloud connection — CM authenticates to the cloud backend over TLS when establishing the WebSocket connection for desired state updates and telemetry
• SM controller — CM presents its certificate when connecting to SM's gRPC interface to issue service deployment commands

The cm certificate type uses clientAuth extended key usage only, as CM acts exclusively as a client in its connections.

SM Certificate (sm)

The Service Manager uses its certificate for client authentication when connecting to CM's gRPC server. SM subscribes to CM for service deployment instructions and reports service status back. The sm certificate type uses clientAuth extended key usage.

Online Certificate (online)

The online certificate type provides an additional client authentication credential specifically for cloud communication. This separation from the cm type allows independent renewal cycles and potentially different CA chains for cloud-facing authentication versus internal component communication.

Offline Certificate (offline)

The offline certificate type provides Unit identity verification that does not require cloud connectivity. This enables scenarios where the Unit must prove its identity without an active cloud connection — for example, during local diagnostics or inter-Node trust establishment.

Certificate Modules

Each certificate type is managed by a dedicated certificate module — a configured instance within IAM's CertHandler that defines how keys are generated, where they are stored, and what properties the certificates carry.

Module Configuration

A certificate module is defined by the following parameters:

Parameter	Description	Example
id	Certificate type identifier	"iam", "cm", "sm", "online", "offline"
plugin	Storage backend implementation	"pkcs11module", "tpmmodule", "swmodule"
algorithm	Key generation algorithm	"RSA" (2048-bit) or "ECDSA" (P-384)
maxItems	Maximum certificates to retain	2–5 (minimum 2 for CA-signed, 1 for self-signed)
extendedKeyUsage	Certificate purpose	["clientAuth"], ["serverAuth"], or both
alternativeNames	DNS SANs for server certificates	["iam.local", "localhost"]
skipValidation	Skip startup certificate validation	false (default)
isSelfSigned	Module uses self-signed certificates	false (default)

Module Registration

At startup, IAM registers each configured certificate module with the CertHandler. The CertHandler supports up to 8 modules (configurable via AOS_CONFIG_CERTHANDLER_MODULES_MAX_COUNT). Each module is initialized with:

• A reference to the X.509 provider (for CSR generation and certificate parsing)
• A reference to the HSM backend (PKCS#11, TPM, or software storage)
• A reference to the metadata storage (database for tracking certificate info)

Storage Backends

Certificate modules support three storage backend implementations:

Backend	Key Storage	Certificate Storage	Use Case
PKCS#11 (pkcs11module)	PKCS#11 token (HSM, TEE, SoftHSM)	PKCS#11 token	Production deployments with hardware security
TPM (tpmmodule)	TPM 2.0 persistent handles	Filesystem	Platforms with TPM but no PKCS#11
Software (swmodule)	Filesystem	Filesystem	Development and testing

For production deployments, the PKCS#11 backend is recommended as it provides hardware-backed key protection and supports a wide range of security hardware through a standardized interface.

Trust Chain Validation

When a certificate is applied to a module, CertHandler validates the complete certificate chain:

1. Chain parsing — the PEM-encoded certificate chain is parsed into individual X.509 certificates
2. Issuer matching — each certificate's issuer distinguished name is matched against the subject of the next certificate in the chain
3. Signature verification — each certificate's signature is verified against its issuer's public key
4. Root anchoring — the chain must terminate at the configured CA root certificate

If skipValidation is enabled for a module, chain validation is bypassed. This is used in specific deployment scenarios where the storage backend handles its own validation or where self-signed certificates are used for bootstrap.

Extended Key Usage Validation

During CSR creation, the certificate module adds the configured extended key usage extensions:

OID	Extension	Meaning
1.3.6.1.5.5.7.3.1	id-kp-serverAuth	Certificate can be used for TLS server authentication
1.3.6.1.5.5.7.3.2	id-kp-clientAuth	Certificate can be used for TLS client authentication

The CA enforces these extensions when signing the certificate. During mTLS handshakes, peers verify that the presented certificate has the appropriate extended key usage for its role (server or client).

Multi-Node Certificate Distribution

In a multi-Node Unit, certificate management follows a hierarchical model:

Main Node

The Main Node's IAM is the central certificate authority agent for the Unit:

• Manages all certificate modules for the Main Node's components (CM, SM, IAM)
• Forwards provisioning operations to Secondary Nodes through the Node controller's bidirectional gRPC stream
• Holds the complete set of certificate types (iam, cm, sm, online, offline)

Secondary Nodes

Each Secondary Node runs its own IAM instance that:

• Manages a subset of certificate modules (typically sm, online, offline)
• Receives provisioning commands forwarded from the Main Node's IAM
• Independently manages key generation and certificate storage in its local PKCS#11 token
• Does not run CM (only the Main Node communicates with the cloud)

Provisioning Flow for Multi-Node

When provisioning a Secondary Node:

1. The provisioning client connects to the Main Node's IAM protected API
2. Main IAM identifies the target Node and forwards the provisioning request via the Node controller stream
3. The Secondary Node's IAM generates keys and returns CSRs through the same stream
4. CSRs are submitted to the cloud CA for signing
5. Signed certificates are forwarded back to the Secondary Node's IAM for application

This architecture ensures that the cloud CA never needs direct connectivity to Secondary Nodes — all certificate operations are mediated through the Main Node.

Certificate Renewal

Certificates have a finite validity period and must be renewed before expiration. The renewal process is:

1. The cloud initiates renewal by sending a CreateKey request for the target certificate type and Node
2. IAM generates a new key pair in the PKCS#11 token and returns a CSR
3. The cloud signs the CSR with the CA and sends the certificate via ApplyCert
4. IAM stores the new certificate and notifies subscribed components via the OnCertChanged callback
5. Components (CM, SM) reload their TLS credentials with the new certificate
6. If the module's maxItems limit is exceeded, the oldest certificate (by expiration date) is removed

The maxItems configuration (minimum 2 for CA-signed modules) ensures that a valid certificate always exists during the renewal window — the new certificate is applied before the old one is removed.

Component Certificate Usage

Each component obtains its TLS credentials from IAM at startup and subscribes to certificate change notifications:

Component	Certificate Type	TLS Role	Connection Target
CM	cm / online	Client	Cloud backend (WebSocket), SM (gRPC)
SM	sm	Client	CM (gRPC)
IAM	iam	Server + Client	All components (gRPC server), Main IAM (client on Secondary Nodes)
MP	sm (or configured type)	Client + Server	Inter-Node transport channels

Mutual TLS Configuration

For mTLS connections between components:

• The server presents its certificate (e.g., IAM's iam certificate with serverAuth)
• The client presents its certificate (e.g., SM's sm certificate with clientAuth)
• Both sides verify the peer's certificate chain against the shared CA root certificate
• If either verification fails, the connection is rejected

This ensures that only components with valid, CA-signed certificates can communicate — preventing unauthorized components from joining the system.

Related Pages

• Security Model — overview of the complete security architecture
• Certificate Handler — detailed CertHandler implementation, storage modules, and API
• Provisioning Workflow — step-by-step provisioning sequence that establishes certificates

• Hardware Security (PKCS#11) — PKCS#11 integration, HSM configuration, and TEE support

• Node Identity — per-Node identity management
• Architecture Overview — system-wide component relationships