Operations¶
An operation (operation ticket) is a time-limited ticket that authorizes use of one or more signing keys, each a limited number of times. Every sign order (POST /api/signorders) and certificate request (POST /api/certificates) names an operation. The Keyserver refuses the request unless that operation is approved, has not expired or been cancelled, and has uses left for the key. ROOT keys are not used under operations; see ROOT Keys.
Who may create, approve, and use an operation is set by roles. How approvals are collected is described in Approval Workflow.
Operation parameters¶
POST /api/operations takes these fields (full schema in the API Reference):
| Field | Type | Required | Meaning |
|---|---|---|---|
new-keyusagerestrictions | Array of {keyid, maxusagecount}, at least one entry | Yes | Which keys the operation may use, and how many times each (maxusagecount is at least 1). Each key may appear once |
validms | Integer, at least 1 | Yes | Validity window in milliseconds, counted from creation. See Validity window |
description | String, 16 to 4096 characters | Yes | Context shown to approvers |
creatorowns | Boolean, default true | No | Restricts the operation to the subject that created it. See Creator ownership |
{
"new-keyusagerestrictions": [
{ "keyid": "fw-prod", "maxusagecount": 1 }
],
"validms": 600000,
"description": "Controller firmware 2.4.0 release build",
"creatorowns": true
}
The response (201) carries only the operation ID. Read the approval state and usage counts with GET /api/operations/{id}.
Creation is refused when:
- a key does not exist or has been revoked (
404) - a key is not yet
INITIALIZED(409) - the subject lacks
createoperationon one of the keys (403) - a key appears more than once (
409) descriptionis outside 16 to 4096 characters (400)
See Creating an operation (POST /api/operations).
Operation lifecycle¶
stateDiagram-v2
[*] --> Pending : POST /api/operations
Pending --> Approved : required approvers met<br/>(immediate if 0 required)
Pending --> Expired : validms elapsed
Pending --> Cancelled : approver Revoke or<br/>DELETE /api/operations/{id}
Approved --> Expired : validms elapsed
Approved --> Cancelled : DELETE /api/operations/{id}
Expired --> [*]
Cancelled --> [*]Diagram: POST /api/operations; required approvers met (immediate if 0 required); validms elapsed; approver Revoke or DELETE /api/operations/{id}; DELETE /api/operations/{id}
| State | Meaning |
|---|---|
| Pending | Created, and at least one key still needs approvals. GET /api/operations/{id} reports approved: false. No key in the operation can be used |
| Approved | Every key has its required approvals; approved: true. An operation whose keys all have Required Approvers 0 is approved when it is created, so the pipeline can sign immediately |
| Expired | validms has elapsed since creation. Sign orders and certificate requests are refused with 410 |
| Cancelled | Cancelled with DELETE /api/operations/{id}, or by an approver's Revoke. Every request under it, including GET, is refused with 410 ("Operation is cancelled") |
An approved operation stays usable until it expires or is cancelled. A sign order does not end it, and each key keeps its own remaining usage count.
A pipeline polls GET /api/operations/{id} until it reports approved: true, then submits its sign orders; the full sequence is in The approval workflow. GET still returns an expired operation and has no expiry field: the operation expires at createdms + validms.
Approval covers the whole operation¶
An operation is approved only when every key in it has its required approvals. Until then no key in it can be used, including keys that require none. See Approval applies to the whole operation.
Cancelling¶
A subject holding canceloperation on every key in the operation can cancel it at any time with DELETE /api/operations/{id}. When creatorowns is set, only the creator can; see Creator ownership. An approver's Revoke on the Approvals page, which needs revokeapproval on every key, also cancels the whole operation while it is pending; see Revocation. Cancelling stops further signing under the operation. Signatures and certificates already issued cannot be recalled.
Usage count¶
maxusagecount sets the maximum number of uses per key within a single operation. Set it to the number of signings the run needs, usually 1.
Each sign order, or each certificate issued with a CA key, increments that key's usagecount. When it reaches maxusagecount, further requests for that key are refused with 409. See Error Codes Reference.
Usage is tracked per key: one key can be used up while another still has uses left, and the operation is still reported as approved. The API has no operation-level exhausted or remaining-usage field. Read the per-key counts from GET /api/operations/{id} (keyusagerestrictions[].usagecount against maxusagecount).
A per-operation budget, not a rate limit
maxusagecount bounds one operation, not a subject's total signatures: a subject with createoperation can request another operation. Required approvers on the key, prompt role revocation, and identity-provider controls are what limit a compromised pipeline.
Validity window¶
validms sets how long the operation remains valid after creation. A short window limits how long a compromised pipeline could submit sign orders without anyone noticing, and stops an approval from being kept and spent later. After expiry, sign orders and certificate requests under it are refused, and the pipeline must create a new operation.
validms | Window | Fits |
|---|---|---|
300000 | 5 minutes | A tight window for automated pipelines |
600000 | 10 minutes | Allows for approval latency |
3600000 | 1 hour | Manual approval workflows |
Creator ownership¶
creatorowns defaults to true. While it is set, only the subject that created the operation can:
- read it with
GET /api/operations/{id} - submit sign orders under it
- submit certificate requests under it
- cancel it with
DELETE /api/operations/{id}
Any other subject gets 409 ("With creatorowns flag set in operation, only the operation creator can access the operation"), even when its roles allow the action. See Error Codes Reference. Approving and an approver's Revoke are not restricted by creatorowns.
Set creatorowns: false when one subject creates the operation and another uses it, for example a release job that creates the operation and separate build jobs that sign under it.
Using an operation¶
A sign order or certificate request under an operation is refused unless all of these hold:
| Condition | Otherwise |
|---|---|
| The operation exists | 404 |
| The operation is not cancelled or expired, and none of its keys has been revoked | 410 |
creatorowns is not set, or the caller created the operation | 409 |
| The key has the right type: FW for sign orders, CA for certificate requests | 409 |
The caller holds order (sign orders) or createcertificate (certificates) on every key in the operation | 403 |
| The operation is approved | 409 ("Need more approvers") |
| The key is part of the operation | 404 |
The key has uses left (usagecount below maxusagecount) | 409 |
Response bodies and the other causes per request are in Error Codes.