Skip to main content

Private Key Policy

This page explains how certificate private keys are protected and how that impacts exports and device retrieval.

Policies​

  • HYBRID: The private key is wrapped for device retrieval, with a master-key fallback also available. Suitable for most scenarios.
  • MASTER_ONLY: Only the master key protects the data key; device-based wrap is not required. Device retrieval may return plaintext if explicitly allowed.
  • DEVICE_REQUIRED: Device wrap is required; server-side plaintext export is forbidden.

Server-side plaintext export​

The server may return a plaintext private key over TLS for specific flows when:

  • The policy allows it (MASTER_ONLY or HYBRID with explicit flag), and
  • The certificate owner has enabled the export flag at creation time or later.

If disallowed by policy or flags, the endpoint returns an error:

  • 403 CERTS::EXPORT_FORBIDDEN

Device-self retrieval behavior​

Device agents using JWT can request the key bundle:

  • HYBRID / DEVICE_REQUIRED: Expect an AEAD-encrypted bundle. If wrapping hasn't occurred yet, you receive 409 DEVICES::WRAP_PENDING.
  • MASTER_ONLY with export enabled: The server may return plaintext material directly. If the certificate hasn’t been issued yet, expect 409 CERTS::NOT_ISSUED.

Error semantics​

  • 403 CERTS::EXPORT_FORBIDDEN — Policy/flag denies server-side plaintext export.
  • 409 CERTS::NOT_ISSUED — Export requested before issuance (no private key material yet).
  • 409 DEVICES::WRAP_PENDING — Device-wrapped bundle not ready; retry with backoff.

Security notes​

  • Plaintext export is always over TLS and controlled via explicit flags.
  • Private keys are never stored in plaintext; they are decrypted only for export when policy allows.
  • Device-bound wraps use X25519-based envelope encryption.