Skip to main content
Version: v1.1

Provisioning Workflow

Introduction​

This page documents the complete provisioning workflow from a security perspective — the sequence of operations that establishes a Node's cryptographic identity and transitions it from an untrusted, unprovisioned state to a fully authenticated participant in the AosEdge system.

Provisioning is the foundational security operation. Until a Node completes this workflow, it cannot establish mutual TLS connections, authenticate to the cloud, or host services. The workflow involves coordination between an external provisioning tool, the IAM Provision Manager, the PKCS#11 hardware security module, and an external Certificate Authority (CA).

Provisioning Sequence Diagram​

The following diagram shows the complete provisioning flow across all participants:

loading...

Participants​

The provisioning workflow involves four participants:

ParticipantRole
Provisioning ToolExternal client (manufacturing tool or cloud orchestrator) that drives the provisioning sequence by calling IAM's protected gRPC API
IAM (Provision Manager)Orchestrates the provisioning logic — manages certificate modules, delegates key operations to the HSM, and tracks provisioning state
PKCS#11 (HSM)Hardware security module that generates and stores cryptographic keys, creates CSRs, and holds signed certificates
Certificate Authority (CA)External trust anchor that signs CSRs and issues X.509 certificates — typically the cloud CA accessed through the provisioning tool

Workflow Phases​

The provisioning workflow proceeds in three distinct phases: initialization, certificate enrollment, and finalization.

Phase 1: Initialization​

The initialization phase prepares the Node's secure storage for new credentials.

Trigger: The provisioning tool calls StartProvisioning(nodeId, password) on IAM's protected gRPC server.

Sequence:

  1. Callback notification — IAM invokes the OnStartProvisioning callback, allowing platform-specific initialization
  2. Clear existing storage — for each registered certificate type, IAM calls Clear() on the PKCS#11 module to remove any existing keys and certificates from the HSM token
  3. Set token ownership — for each certificate type, IAM calls SetOwner(certType, password) to establish ownership of the PKCS#11 token using the provisioning password
  4. Generate self-signed certificates — for certificate types configured with mIsSelfSigned = true (typically internal inter-component certificates), IAM generates a self-signed certificate immediately via CreateSelfSignedCert()
  5. Disk encryption — IAM invokes the OnEncryptDisk(password) callback, allowing the platform to encrypt the Node's persistent storage

Security properties established:

  • HSM token is owned by the provisioning password — only authorized callers can perform subsequent key operations
  • Previous credentials are irrevocably destroyed — no residual keys from prior provisioning remain
  • Self-signed certificates for internal communication are immediately available

Phase 2: Certificate Enrollment​

The enrollment phase generates key pairs and obtains CA-signed certificates for each certificate type that requires external signing.

Discovery: The provisioning tool calls GetCertTypes(nodeId) to learn which certificate types need enrollment. The Provision Manager returns only non-self-signed types — those already handled during initialization are filtered out.

Per-certificate-type loop:

For each certificate type returned by GetCertTypes, the provisioning tool executes:

Step A: Key Generation and CSR Creation​

The provisioning tool calls CreateKey(nodeId, certType, subject, password).

IAM delegates to the Certificate Handler, which:

  1. Invokes the PKCS#11 module to generate a key pair (RSA 2048-bit or ECDSA P-384, depending on module configuration)
  2. Constructs a Certificate Signing Request (CSR) containing:
    • The public key from the generated pair
    • The subject common name provided by the caller
    • Extended key usage attributes from the module configuration (client auth, server auth, or both)
    • Subject Alternative Names (SANs) if configured
  3. Returns the CSR in PEM format to the provisioning tool

The private key never leaves the HSM — only the CSR (containing the public key) is returned.

Step B: CA Signing (External)​

The provisioning tool submits the CSR to the Certificate Authority for signing. This step occurs outside IAM's control — the provisioning tool handles the CA interaction (typically via a cloud API or direct CA enrollment protocol).

The CA validates the CSR and returns a signed X.509 certificate chain in PEM format.

Step C: Certificate Application​

The provisioning tool calls ApplyCert(nodeId, certType, cert) with the signed certificate.

IAM delegates to the Certificate Handler, which:

  1. Validates that the certificate's public key matches the private key stored in the HSM
  2. Stores the signed certificate in the PKCS#11 module alongside its private key
  3. Records certificate metadata (type, issuer, serial number, certificate URL, key URL) in the IAM database
  4. Returns the certificate information to the provisioning tool

After this step, the certificate is available for TLS connections through the configured certificate URL.

Phase 3: Finalization​

Once all certificate types have been enrolled, the provisioning tool calls FinishProvisioning(nodeId, password).

Sequence:

  1. IAM invokes the OnFinishProvisioning callback
  2. The Node's provisioning state is updated from unprovisioned to provisioned
  3. The state is persisted to the provisioning status file on disk

Result: The Node is now fully provisioned — it has valid certificates for all configured types and can establish authenticated mutual TLS connections with other components, other Nodes, and the cloud.

Multi-Node Provisioning​

On multi-Node Units, provisioning can be performed centrally from the Main Node:

Provisioning Tool → Main Node IAM → [RegisterNode stream] → Secondary Node IAM

The Main Node's 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 streaming connection to that Node's IAM client, which processes it locally using its own Provision Manager and PKCS#11 module.

Key differences for multi-Node provisioning:

AspectSingle NodeMulti-Node (forwarded)
Timeout1 minute (default)5 minutes (provisioning timeout)
Key generationLocal HSMRemote Node's HSM
Certificate storageLocal PKCS#11Remote Node's PKCS#11
State persistenceLocal fileRemote Node's file

The extended timeout accounts for network latency and the time required for HSM key generation on the remote Node.

Deprovisioning​

Deprovisioning reverses the provisioning workflow, returning a Node to an unprovisioned state:

  1. The provisioning tool calls Deprovision(nodeId, password)
  2. IAM invokes the OnDeprovision callback
  3. All certificates and keys are cleared from the HSM
  4. The Node's state is updated to unprovisioned

After deprovisioning, the Node cannot establish authenticated connections until it is re-provisioned.

Use cases for deprovisioning:

  • Node decommissioning — removing a Node from service
  • Factory reset — returning a Node to its initial state
  • Credential rotation — deprovisioning followed by re-provisioning with fresh credentials
  • Security incident response — revoking a compromised Node's identity

Security Considerations​

Password Protection​

The provisioning password serves as the authorization gate for all provisioning operations:

  • It authenticates the caller to the PKCS#11 token (via SetOwner)
  • It is required for every provisioning API call (StartProvisioning, FinishProvisioning, Deprovision)
  • It is required for key creation (CreateKey)

The password distribution mechanism (how the provisioning tool obtains the password) is outside IAM's scope and is determined by the OEM's manufacturing or deployment process.

Key Material Isolation​

Private keys are generated inside the HSM and never exported:

  • CreateKey returns only the CSR (public key + metadata) — the private key remains in the PKCS#11 token
  • ApplyCert stores the certificate alongside the existing private key — no key material is transmitted
  • The PKCS#11 interface ensures key operations (signing, decryption) happen within the HSM boundary

Provisioning Mode​

IAM must be started with the --provisioning flag to accept provisioning operations. This prevents accidental or unauthorized provisioning in production:

  • In normal mode, StartProvisioning and Deprovision are restricted
  • Provisioning mode is a startup-time decision — it cannot be toggled at runtime
  • This provides defense-in-depth: even if an attacker obtains the provisioning password, they cannot re-provision a running Node without restarting IAM in provisioning mode

State Persistence​

The provisioning state is persisted to disk, ensuring:

  • A provisioned Node remains provisioned across restarts
  • A power failure during provisioning leaves the Node in a deterministic state
  • The state file can be inspected for diagnostics