Production Notes: Sign Code Using the REST API¶
The complete signing flow (authenticate, create an operation, obtain approval, submit a sign order, verify the signature) is covered step by step, with expected outputs, in:
→ Tutorial Part 2: Sign Code Using the Trial Environment
The API calls are identical in production. This page covers what changes when you move from the trial environment to a production pipeline.
Production differences from the tutorial¶
Authentication. Replace the internal-Authserver token from the tutorial's Step 1 with your production identity:
- Federation-capable CI platforms, with no stored secrets: GitLab CI (GitLab's own OIDC token) and Azure DevOps (workload identity federation).
- Headless build servers and signing services: an Entra ID service account via Client Credentials. See Integrate a Headless Build Server.
Operation hygiene
Set validms to the shortest window your pipeline needs (a few minutes for a single-signature pipeline), and maxusagecount to the number of signatures the run produces. An approver authorizes the operation, not a specific artifact, so validms limits how long the approval is usable and maxusagecount limits how many signatures can be created under it. For a key that requires approval, a compromised pipeline can then spend at most that one approved budget, visibly and audited. See What an approver authorizes.
Approval polling. For keys with required approvers, poll until the operation is approved before submitting the sign order:
for i in $(seq 1 60); do
APPROVED=$(curl -sS --tlsv1.3 \
-H "Authorization: Bearer $TOKEN" \
"$KEYSERVER/api/operations/$OPERATION_ID" | jq -r .approved)
[ "$APPROVED" = "true" ] && break
sleep 10
done
[ "$APPROVED" = "true" ] || { echo "Approval timeout"; exit 1; }
The Keyserver does not push notifications. Notify your approvers out-of-band (for example, through Slack or email) when the operation is created.
Fail fast and loud. Check every response: a null from jq -r .id or .result means the call failed, and the error body says why. The Error Codes Reference maps each status code (401/403/404/409/410) to its cause. A healthy pipeline mostly sees 409 "Need more approvers" and 410 "Operation has expired".
Signature format. Match the verifying side; the format is set per sign order. See Signature Formats for asn1, p1363 and cms, and which CMS options to use.
Verify in the pipeline. Verify the returned signature against the key's certificate before publishing an artifact, as in Step 7: Verify the Signature of the code signing tutorial. This catches configuration mistakes (wrong key, wrong hash) at build time instead of on devices. Verify a Signature covers p1363 signatures and certificate-chain validation.
Related pages¶
- Tutorial Part 2: Sign Code Using the Trial Environment: the full flow with expected outputs
- Signature Formats: output formats, CMS options and result encoding
- PKCS#11 Library Reference: signing through OpenSSL or JSign instead of raw REST