Skip to main content
Version: v1.1

Provisioning and Enrollment

Introduction​

Provisioning is the process that establishes a Node's cryptographic identity within an AosEdge Unit. Before a Node can participate in secure communication — with the cloud, with other Nodes, or with local services — it must be provisioned with valid certificates stored in its hardware security module (HSM).

This page documents the provisioning workflow managed by the Provision Manager subcomponent of IAM, including the step-by-step enrollment sequence, the gRPC API operations involved, and the deprovisioning process.

Provisioning Overview​

A newly manufactured or reset Node starts in an unprovisioned state. In this state, the Node cannot establish TLS connections or authenticate itself. The provisioning workflow transitions the Node to a provisioned state by:

  1. Preparing the secure storage (clearing old keys, setting ownership)
  2. Generating cryptographic key pairs for each required certificate type
  3. Enrolling certificates signed by the appropriate Certificate Authority (CA)
  4. Optionally encrypting the Node's disk storage
  5. Finalizing the provisioning state

Provisioning is a protected operation — it requires IAM to be started in provisioning mode (via the --provisioning or -p command-line flag) and is authenticated by a password provided with each request.

Provisioning Mode​

IAM supports two operational modes that affect which operations are available:

ModeActivationProvisioning OperationsNormal Operations
Normal modeDefault (no flag)RestrictedFull
Provisioning mode--provisioning flagFullFull

In provisioning mode, the protected gRPC server accepts StartProvisioning, FinishProvisioning, and Deprovision requests. In normal mode, these operations may be restricted depending on the Node's current provisioning state.

The provisioning mode flag is passed through the application startup and propagated to both the IAM server and the IAM client (on Secondary Nodes).

Provisioning Workflow​

The complete provisioning sequence involves multiple gRPC calls between the provisioning client (typically a manufacturing tool or cloud orchestrator) and the IAM protected server.

Step 1: Start Provisioning​

The provisioning client calls StartProvisioning with the target Node ID and a password. This triggers the following internal sequence:

  1. Callback notification — IAM server receives the OnStartProvisioning callback
  2. Clear certificate storage — for each registered certificate type, the existing keys and certificates are removed from the HSM
  3. Set ownership — for each certificate type, the HSM token ownership is established using the provided password
  4. Create self-signed certificates — for certificate types configured as self-signed (e.g., internal communication certificates), a self-signed certificate is generated immediately
  5. Disk encryption — the OnEncryptDisk callback is invoked, allowing the platform to encrypt the Node's storage using the provisioning password

After StartProvisioning completes successfully, the Node is ready for certificate enrollment.

Step 2: Get Certificate Types​

The provisioning client calls GetCertTypes to discover which certificate types require external enrollment. The Provision Manager returns only non-self-signed certificate types — those that need a CSR signed by an external CA.

Self-signed certificate types (already handled during StartProvisioning) are filtered out of this response.

Step 3: Create Key (for each certificate type)​

For each certificate type returned by GetCertTypes, the provisioning client calls CreateKey with:

  • Node ID — target Node
  • Certificate type — which certificate module to use
  • Subject — the subject common name for the certificate
  • Password — the ownership password

The Provision Manager delegates to the Certificate Handler, which:

  1. Generates a new key pair in the HSM via PKCS#11
  2. Creates a Certificate Signing Request (CSR) containing the public key and subject information
  3. Returns the CSR in PEM format

The provisioning client then submits this CSR to the appropriate CA for signing.

Step 4: Apply Certificate (for each certificate type)​

Once the CA returns a signed certificate, the provisioning client calls ApplyCert with:

  • Node ID — target Node
  • Certificate type — which certificate module to use
  • Certificate — the signed certificate in PEM format

The Provision Manager delegates to the Certificate Handler, which:

  1. Validates the certificate against the corresponding private key in the HSM
  2. Stores the certificate in the HSM alongside its private key
  3. Records certificate metadata (type, issuer, serial, URLs) in the IAM database
  4. Returns the certificate information (URL, serial number)

Step 5: Finish Provisioning​

After all certificate types have been enrolled, the provisioning client calls FinishProvisioning. This:

  1. Invokes the OnFinishProvisioning callback on the IAM server
  2. Updates the Node's state from unprovisioned to provisioned
  3. Persists the provisioning state to disk (via the provisioning status file)

The Node is now fully provisioned and can establish authenticated TLS connections.

Deprovisioning​

Deprovisioning reverses the provisioning process, returning a Node to an unprovisioned state. The provisioning client calls Deprovision with the Node ID and password, which:

  1. Invokes the OnDeprovision callback on the IAM server
  2. Clears all certificate storage and keys from the HSM
  3. Updates the Node's state to unprovisioned

Deprovisioning is used during Node decommissioning, factory reset, or when re-provisioning with new credentials is required.

Multi-Node Provisioning​

In a multi-Node Unit, provisioning operations can be performed remotely from the Main Node:

  • The Main Node IAM receives provisioning requests via its protected gRPC server
  • If the target node_id refers to a Secondary Node, the request is forwarded through the RegisterNode bidirectional stream to that Node's IAM client
  • The Secondary Node IAM client processes the forwarded request locally using its own Provision Manager and Certificate Handler
  • Results are returned back through the stream to the Main Node IAM, which responds to the original caller

This architecture allows centralized provisioning management — a single provisioning tool can provision all Nodes in a Unit by communicating only with the Main Node's IAM.

The Node controller on the Main Node manages these forwarded operations with a provisioning-specific timeout of 5 minutes (compared to the default 1-minute timeout for other operations), accounting for the time required for HSM key generation.

gRPC API Reference​

The provisioning workflow uses two protected gRPC services defined in the iamanager/v5 and iamanager/v6 proto packages:

IAMProvisioningService​

RPCRequestResponseDescription
GetCertTypesGetCertTypesRequestCertTypesReturns certificate types requiring external enrollment
StartProvisioningStartProvisioningRequestStartProvisioningResponseInitiates provisioning — clears storage, sets ownership
FinishProvisioningFinishProvisioningRequestFinishProvisioningResponseCompletes provisioning — updates Node state
DeprovisionDeprovisionRequestDeprovisionResponseRemoves all credentials and resets Node state

IAMCertificateService​

RPCRequestResponseDescription
CreateKeyCreateKeyRequestCreateKeyResponseGenerates key pair, returns CSR
ApplyCertApplyCertRequestApplyCertResponseStores signed certificate in HSM

All provisioning and certificate requests include a node_id field to identify the target Node and a password field for authentication. Error responses use the ErrorInfo message to report failures.

Node Provisioning State​

The current Node handler tracks the provisioning state and exposes it through the Node information:

StateDescription
UnprovisionedNo valid certificates — Node cannot authenticate
ProvisionedValid certificates installed — Node is operational

The provisioning state is persisted to a file on disk (configured via mProvisioningStatusPath), ensuring the state survives Node restarts. When IAM starts, it reads this file to determine the current provisioning state and reports it as part of the Node information to other components and to the Main Node.

Certificate Types and Modules​

During provisioning, the system handles multiple certificate types, each backed by a certificate module (PKCS#11-based). Common certificate types include:

  • Client certificates — used for TLS client authentication when connecting to the cloud or other services
  • Server certificates — used for TLS server authentication on local gRPC endpoints
  • Self-signed certificates — used for internal inter-component communication where external CA signing is not required

Each certificate module is configured with:

  • Key algorithm (ECDSA or RSA)
  • Maximum certificate count
  • Extended key usage (client auth, server auth)
  • Alternative DNS names
  • Whether the certificate is self-signed
  • PKCS#11 library and slot configuration

Self-signed certificate types are automatically provisioned during StartProvisioning and do not require the CreateKey/ApplyCert enrollment cycle.