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
maxusagecountsignatures per key - within the operation's
validmswindow
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
validmsas short as the pipeline needs, so an approval cannot be banked and spent later. - Set
maxusagecountto the number of signatures the run produces, usually1. - 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
orderentry 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-devcannot 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 / cancelledDiagram: 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) andapiname=canceloperation
Filter the audit log by operationid to see all events for one operation. See Monitor and Filter the Audit Log.