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"| SIGDiagram: 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.