Skip to content

Key Types and Storage

Keys are the core assets of the Keyserver. All signing, certificate issuance, and approval workflows operate on cryptographic key pairs. Each key is stored either in the HSM or in an encrypted KEYSTORE.


Key Storage

Each key's Key Location is chosen when the key is created:

Location Private key Exportable Recommended for
HSM (default) Generated in the Hardware Security Module (HSM); never leaves it in plaintext No; an export request is refused with 409 Production firmware and CA keys
KEYSTORE Held in an encrypted keystore Yes, with GET /api/keys/priv/{keyid} and the getprivkeys permission; every export is audited Designs that need the private key on the device or build host

Use KEYSTORE only when a tool or device must hold the private key itself. It is a per-key, opt-in choice, export requires the getprivkeys permission, and every export is audited. An export request for an HSM key is refused with 409. See Export a KEYSTORE Private Key.


Key Hierarchy

The Keyserver organizes keys into a three-level hierarchy. Each level has a distinct purpose:

flowchart TD
    ROOT["ROOT key<br/>Self-signed certificate<br/>Trust anchor"]
    CA["CA key<br/>Signed by ROOT<br/>Issues device certificates"]
    FW["FW key<br/>Signed by ROOT<br/>Signs firmware and binaries"]
    DEVCERT(["Device Certificate<br/>Issued to IoT device"])
    SIG(["Firmware Signature<br/>Verifiable by relying parties"])

    ROOT -->|"signs certificate of"| CA
    ROOT -->|"signs certificate of"| FW
    CA -->|"issues"| DEVCERT
    FW -->|"produces"| SIG

Diagram: ROOT key Self-signed certificate Trust anchor; CA key Signed by ROOT Issues device certificates; FW key Signed by ROOT Signs firmware and binaries; Device Certificate Issued to IoT device; Firmware Signature Verifiable by relying parties; signs certificate of; issues; produces

A typical deployment has one ROOT key per trust domain: one for firmware signing and another for device identity. One or more CA keys for device provisioning sit under the device-identity root, and one or more FW keys for individual products or product families sit under the firmware-signing root.

Keep firmware signing and device identity in separate hierarchies, each with its own ROOT, so a compromise of one does not affect the other. A single instance therefore usually holds two or more ROOT keys; Issue a Device Certificate Using the Trial Environment (Part 3) builds a device root alongside the firmware root.


Key Types

ROOT Keys

A ROOT key is the trust anchor: its certificate is self-signed, and all other certificates in its hierarchy chain back to it.

ROOT keys:

  • Sign the certificates of CA and FW keys
  • Are long-lived and used infrequently (only when adding new CA or FW keys)
  • Cannot be used for signing firmware or issuing device certificates directly
  • Cannot export CSRs, because they are already trust anchors
  • Are protected by administrative sessions: a ROOT key is used only when an administrator creates a CA or FW key under an active session, so operation approvals do not apply to it

CA Keys (Certificate Authority)

CA keys issue X.509 certificates to IoT devices during manufacturing or provisioning.

A provisioning tool submits a CSR (Certificate Signing Request) generated on the device. The Keyserver signs it with the CA key and returns a certificate that the device stores as its identity credential.

CA keys:

  • Sit below the ROOT key in the certificate chain
  • Sign device CSRs submitted via POST /api/certificates
  • Can be self-signed initially and later submitted to an external CA via "Get CSR"
  • Require approval before use when their Required Approvers count is 1 or more (recommended: at least 1 in production)

FW Keys (Firmware Signing)

FW keys sign firmware images, software binaries, or hashes submitted by CI/CD pipelines.

FW keys:

  • Are used frequently, by every CI build that produces a signed release
  • Are scoped to individual products or product families (one key per product limits the impact of a compromise)
  • Are limited per operation by maxusagecount, as CA keys are, so a single approved operation cannot be spent on more signatures than it was meant for
  • Support zero-approver configuration for development, multi-approver for production

Key Algorithms

A key is generated as EC, which signs with ECDSA, or as RSA. The curve or key size and the hash algorithm are also chosen when the key is created. Curves, key sizes, and which signature formats each algorithm supports are listed in Key Algorithms.

Hash algorithm

Each key has a fixed hash algorithm. The client computes the hash and submits it to the Keyserver, which receives the hash, not the original data. Submit a hash made with the key's hash algorithm. The Keyserver does not check the length: with an RSA key a different hash gives a signature that does not verify, and with an ECDSA key the signature verifies only against the hash algorithm you used.


Operations

A key is used under an operation: a time-limited ticket, approved where the key requires it, that sets how many times each key may be used.