Skip to content

Approval Workflow

The approval workflow is the human checkpoint between a pipeline requesting use of a signing key and the Keyserver performing the signing. For keys with one or more Required Approvers, an operation becomes approved only after the required number of approvals has been collected for each of its keys. See Required approvers per key. To configure approvals and approve operations, see Set Up and Run Approval Workflows.

Approvals control key usage. Administrative sessions control configuration changes. Both are multi-party authorization, for different scopes.

The Keyserver sends no notification when an operation needs approval. Approvers see pending operations when they open the Approvals page. The Pending approvals count on the Dashboard's Approvals card counts the operations still awaiting approval on keys the viewer can approve. Alert approvers through your own process, for example a chat message from the pipeline carrying the operation ID.


Why approvals exist

Even with the private keys protected, unauthorized signing is still a risk:

  • A compromised CI pipeline could attempt to sign malicious firmware
  • A developer could attempt to sign a build that has not passed the required security review
  • A manufacturing tool could attempt to issue device certificates outside an authorized production run
  • A single insider with access to the signing pipeline could attempt to misuse a production key

Approvals introduce a human gate that separates who requests signing from who authorizes it.

The Keyserver enforces that each approver approves an operation at most once, and that the approver holds approve on at least one key in the operation that still needs approvals (otherwise: "User has nothing in this operation (left) to approve"). Either refusal returns 409. See Error Codes Reference. It does not compare the approver with the operation creator. Separating the operation creator from the approver is a deployment rule you enforce through role design.

Never grant both roles to one subject

A subject holding both a signing Nature (fwsigner, devcertsigner) and approver on the same key can create and approve its own operations. Keep signing roles and approver roles on separate subjects, and review role assignments whenever they change.


What an approver authorizes

Approval happens on the operation, not on a specific artifact. The artifact's hash is not supplied until the pipeline calls POST /api/signorders, after approval.

When an approver clicks Approve, they authorize:

  • use of the keys named in the operation
  • up to maxusagecount signatures per key
  • within the operation's validms window

They are not approving a particular binary, digest, or build artifact. The pipeline that created the operation writes the description, so if that pipeline is compromised, the description is not an independent statement of what will be signed.

For operation-scoped approvals, we recommend the following practices:

  • Keep validms as short as the pipeline needs, so an approval cannot be banked and spent later.
  • Set maxusagecount to the number of signatures the run produces, usually 1.
  • Have approvers verify the operation against the corresponding pipeline run, commit, or tag rather than relying on the description alone.
  • Use the audit log as the record of what was signed under the approval. Each order entry carries the operation ID and the key, so an approval can be reconciled afterwards with the sign orders it permitted.

Required approvers per key

Each signing key has a Required Approvers count (required-approvers in the API), set by an administrator when the key is created or edited.

Required Approvers Approval behavior Typical use
0 No approval required for this key Development and test keys
1 One approver must approve the operation Staging or lower-risk production keys
2+ The configured number of distinct approvers must approve the operation High-value production keys

The operation creator can be one of the approvers if it holds approve on the key; see Why approvals exist.

ROOT keys are not used for signing directly. Their use (signing CA and FW key certificates) is protected by administrative sessions instead.


The approval workflow

sequenceDiagram
    autonumber
    participant P as CI Pipeline
    participant KS as Keyserver
    participant KC as Keyclient (admin UI)
    participant A as Approver

    P->>KS: POST /api/operations<br/>(keyid, maxusagecount,<br/>validms, description)
    KS-->>P: 201 { id: "op_id" }

    Note over P,KS: The create response carries the id only.<br/>Approval state is read with<br/>GET /api/operations/op_id

    Note over KS,A: No notification is sent. The approver<br/>checks the Approvals page or the<br/>Dashboard's pending count
    A->>KC: Opens the Approvals page
    KC->>KS: Fetch operations<br/>awaiting this approver
    KS-->>KC: Pending operations
    A->>KC: Views the operation: creator,<br/>keys, usage counts, description
    A->>KC: Approves the operation
    KC->>KS: Registers the approval
    KS-->>KC: Approved
    KC-->>A: Confirmed in the UI

    loop Poll until approved
        P->>KS: GET /api/operations/op_id
        KS-->>P: { approved: true }
    end

    P->>KS: POST /api/signorders<br/>(op_id, keyid, hash, format)
    KS-->>P: { result: "signature" }

Diagram: CI Pipeline; Keyserver; Keyclient (admin UI); Approver; POST /api/operations (keyid, maxusagecount, validms, description); 201 { id: "op_id" }; The create response carries the id only. Approval state is read with GET /api/operations/op_id; No notification is sent. The approver checks the Approvals page or the Dashboard's pending count; Opens the Approvals page; Fetch operations awaiting this approver; Pending operations; Views the operation: creator, keys, usage counts, description; Approves the operation; Registers the approval; Approved; Confirmed in the UI; Poll until approved; GET /api/operations/op_id; { approved: true }; POST /api/signorders (op_id, keyid, hash, format); { result: "signature" }

What the approver sees

The Approvals page lists pending operations (not approved, not expired, not cancelled) that still have a key the viewer can approve. View on an operation shows:

  • Who created it (the pipeline's subject) and selected claims from its token
  • Which keys are involved and how many times each may be used
  • The description written by the pipeline when it created the operation
  • When it was created and when it expires
  • Who has already approved

Pipelines should write descriptions that identify the build (product, version, purpose) so approvers can check them against the build system.

Approver actions

  • Approve counts the approver toward every key in the operation on which they hold approve. Signing can proceed once every key has its required approvals.
  • Revoke cancels the whole operation for every approver and key. Signing is blocked, and the pipeline must create a new operation.

Approval applies to the whole operation

Approval is evaluated for the operation as a whole. An operation becomes approved only when every key in it has its required number of approvals. Until then, none of its keys can be used, including keys that require 0 approvers: a sign order or certificate request on any key is refused with 409 ("Need more approvers").

For example, if an operation contains:

{
  "new-keyusagerestrictions": [
    { "keyid": "fw-dev",  "maxusagecount": 1 },
    { "keyid": "fw-prod", "maxusagecount": 1 }
  ]
}

and fw-dev requires 0 approvers while fw-prod requires 2:

  • The operation stays pending until two distinct approvers have approved it for fw-prod.
  • fw-dev cannot be used during that time, even though it requires no approvers.
  • Once both approvals are in, the operation is approved and both keys can be used.

Bundling a loosely controlled key with a strict one therefore cannot bypass the strict key's controls.

stateDiagram-v2
    direction LR
    [*] --> Pending

    state Pending {
        fw_dev : fw-dev approved<br/><b>(0 approvers needed)</b>
        fw_prod : fw-prod waiting<br/><b>(needs 2 approvers)</b>
    }

    Pending --> Approved : two approvers for fw-prod confirm
    Pending --> [*] : expired / cancelled
    Approved --> [*] : expired / cancelled

Diagram: fw-dev approved (0 approvers needed); fw-prod waiting (needs 2 approvers); two approvers for fw-prod confirm; expired / cancelled


Expiration

An expired operation leaves the Approvals page and can no longer be used; see Validity window.


Revocation

Before an operation is approved, an approver holding revokeapproval on all of the operation's keys can click Revoke on it in the Approvals page. See Approver actions.

Cancelling through the API, and what cancellation does to the operation, is described in Cancelling.


Audit trail

Every approval event is recorded in the audit log:

  • Operation creation: apiname=createoperation, with the full request body
  • Each approval: apiname=approve, with the approver's identity and the operation ID
  • Each sign order: apiname=order, with the key used and the operation ID
  • Cancellations: apiname=revokeapproval (an approver's Revoke) and apiname=canceloperation

Filter the audit log by operationid to see all events for one operation. See Monitor and Filter the Audit Log.