Tutorial: Issue a Device Certificate Using the Trial Environment¶
This is Part 3 of the tutorial series. It runs on its own; Part 1 is recommended, not required. Part 1: Admin Configuration · Part 2: Sign Code Using the Trial Environment New to the trial? Trial Environment covers the three hostnames, the seeded identities and keys, and how to switch identity in the browser.
In this tutorial you issue a device certificate with the Cryptera Keyserver, the workflow a provisioning station or manufacturing line uses to give each IoT device its identity certificate. You:
- set up a certificate authority for device identities: a device ROOT key and a CA key beneath it
- grant a provisioning client permission to issue from the CA key
- generate a device key pair and a Certificate Signing Request (CSR) locally
- authenticate as the provisioning client, submit the CSR, and receive a signed certificate chain
The device's private key never leaves your machine.
Uses Internal Authserver
This tutorial uses the Keyserver's internal Authserver for demonstration purposes. Do not use the internal Authserver in production. Production provisioning workflows must authenticate through an external identity provider such as Azure Entra ID or GitLab OIDC. For provisioning stations that cannot hold a client secret, use the PKCE flow. See PKCE Client Integration Guide (Provisioning Tools).
If device-root, device-ca, or HSM Key IDs 0102/0103 already exist on this trial, pick new values and use them wherever the steps name these keys. The 409 message names the field; see Cleanup and re-runs for how names are reused. Step 7 to Step 11 can be repeated freely against an existing CA.
Prerequisites¶
- Linux or macOS terminal running bash or zsh. The
diff <(…)check in Step 11 uses process substitution, whichsh/dashdo not support. -
Tools installed.
awk,grepanddiffare preinstalled; install the rest:Ubuntu 24.04:
macOS with Homebrew:
-
Access to a Cryptera trial system
- Administrative access to the Keyserver UI (
adminuser, or another administrator). The certificate-authority setup needs an active administrative session. If you have not created one before, see Step 1: Log in and start an administrative session of the Admin Configuration tutorial.
Trial credentials
On a standard trial, adminuser and the seeded client devicecert-client authenticate with the password password; your getting-started email says if yours differs. In production the client authenticates with credentials issued by your identity provider.
Set the base URLs:
export KEYSERVER="https://keyserver.<UNIQUE-ID>.cryptera-security.io"
export AUTHSERVER="https://authserver.<UNIQUE-ID>.cryptera-security.io/oauth2/token"
If a step produces an empty value
A failed request can leave a variable empty and only break a step or two later. To see the error, re-run the command with --fail-with-body added to curl and -e added to jq:
curl then prints the server's error body and exits non-zero, and jq -e exits non-zero on a null result, so the failure surfaces at the step that caused it. A missing role permission shows up here as a 403 on the operation call.
Set Up Your Device Certificate Authority¶
You create a device ROOT key and a CA key beneath it, giving a three-certificate chain: device certificate → CA → device root. Keeping device identities on a separate hierarchy from firmware signing means a compromise of one does not affect the other. If you completed Admin Configuration, this is the same administrative workflow.
Step 1: Start an Administrative Session¶
Key creation requires an administrative session, as in Step 1: Log in and start an administrative session of the Admin Configuration tutorial.
- Log in to
https://keyclient.<UNIQUE-ID>.cryptera-security.ioasadminuser. - Click Admin, enter a description (for example
Setting up device certificate hierarchy), and click Create. - Wait for the yellow Authorizers badge. On a trial with one administrator,
adminuserself-authorizes immediately.
Step 2: Create the Device Root Key¶
- Click Keys in the navigation bar, then Create.
-
Fill in:
Field Value Notes Key ID device-rootHSM Key ID 0102Unused 4-digit hex, 0100–FFFE, no0xprefixKey Type ROOTKey Location HSMAlways select HSM ( KEYSTOREis only for keys that must be exportable).Description Device identity rootGenerator Algorithm ECParameter secp256r1Hash Algorithm SHA256Required Approvers 0Certificate Validity 3650Leave the Distinguished Name fields at their defaults. Field-by-field guidance is in Part 1: Create a ROOT key and Manage Keys.
-
Click Save. The panel switches to Edit Signingkey: the fields become read-only except Description and Required Approvers. Reload the page and wait for
device-rootto showINITIALIZEDbefore continuing.
Step 3: Create the Device CA Key¶
The CA key issues device certificates directly from CSRs; device-root signs its own certificate.
- Click Create from the Keys list again.
-
Fill in:
Field Value Notes Key ID device-caHSM Key ID 0103Different 4-digit hex value from device-rootKey Type CAKey Location HSMSame location as device-rootRoot Key device-rootSelecting it locks Generator Algorithm to device-root's and resets Parameter to its default; confirm Parameter issecp256r1and set Hash Algorithm toSHA256Description Device provisioning CARequired Approvers 0Immediate issuance, for this tutorial Certificate Validity 1825The CA key's own certificate Issued Device Certificate Validity 730How long certificates issued from CSRs stay valid, independent of the field above -
Click Save. The panel switches to Edit Signingkey: the fields become read-only except Description, Required Approvers and the Issued Device Certificate Validity (days). Reload the page and wait for
device-cato showINITIALIZEDbefore continuing.
This tutorial uses 0 approvers on device-ca so issuance completes immediately. Production CA keys typically require one or more human approvers, using the same mechanism as firmware keys. See Now Protect the Key in the code signing tutorial.
Step 4: Create a Role for Certificate Issuance¶
- Click Roles in the navigation bar, then Create.
-
Fill in the header fields:
Field Value Name devicecert-issuerDescription Provisioning clients — issues device certificates from device-ca -
Expand Signing Key Permissions ..., then click Add natures to role ...
- In the Nature dropdown, select devcertsigner, the Nature for provisioning clients that issue device certificates from CSRs.
- A list of key checkboxes appears. Tick
device-ca. - Click Add, the button to the right of the Nature dropdown, then Save.
We recommend using Natures rather than adding individual permissions manually. devcertsigner grants createoperation, createcertificate, getoperation, canceloperation, getallkeys, getkeys, getdata, and getprivkeys, scoped to device-ca. On an HSM key such as device-ca, getprivkeys has no effect. See the Nature reference.
Step 5: Attach the Role to devicecert-client¶
- Click Subjects in the navigation bar.
- Click the edit (pencil) icon in the
devicecert-clientrow. The subject already exists on your trial, with no roles. Do not create a new subject. Step 5: Authorize the seeded CI/CD client of the Admin Configuration tutorial explains why. - In the Associated Roles section, check the box next to
devicecert-issuer. Leave any roles that are already ticked as they are. - Click Save.
Step 6: Close the Administrative Session¶
- Click Admin in the navigation bar.
- Click Revoke.
The yellow badge disappears from the navigation bar. Administrative changes are no longer possible until a new session is created.
Step 7: Generate a Device Key Pair and CSR¶
The device's private key is generated locally. It must not be created on or transmitted to the Keyserver. Only the CSR (which contains the public key and identity) is sent.
Generate an EC key pair:
Create a CSR carrying the device identity (typically the serial number as CN):
device.csr now contains the CSR in PEM format.
Step 8: Authenticate as the Provisioning Client¶
devicecert-client now carries the devicecert-issuer role you attached in Step 5, scoped to device-ca.
export CLIENT_ID=devicecert-client
export CLIENT_SECRET=password
export AUTH_CREDS=$(printf '%s' "$CLIENT_ID:$CLIENT_SECRET" | base64 | tr -d '\n')
export TOKEN=$(
curl -sS --tlsv1.3 \
-X POST \
-H "Authorization: Basic $AUTH_CREDS" \
-d "grant_type=client_credentials" \
"$AUTHSERVER" | jq -r .access_token
)
[ -n "$TOKEN" ] && [ "$TOKEN" != null ] && echo "Token received"
Expected output:
If nothing is printed, the credentials were rejected. Check the client name, password, and AUTHSERVER URL.
Step 9: Create an Operation for the CA Key¶
Certificate issuance is gated by an operation, as firmware signing is. The operation names the CA key and how many certificates may be issued.
export CAKEY="device-ca"
export OPERATION_ID=$(
curl -sS --tlsv1.3 \
-X POST "$KEYSERVER/api/operations" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"validms": 600000,
"description": "Issuing device certificate for Device12345",
"new-keyusagerestrictions": [
{ "keyid": "'"$CAKEY"'", "maxusagecount": 1 }
]
}' | jq -r .id
)
echo "$OPERATION_ID"
device-ca requires 0 approvers, so the operation is approved immediately. In a real provisioning line, maxusagecount is typically set to the batch size, so a single approved operation covers one production run.
Step 10: Submit the CSR¶
Certificate issuance uses the dedicated endpoint POST /api/certificates. The CSR is sent as PEM in the csrpem field. Building the request body with jq escapes the newlines in the PEM:
export CERT_RESPONSE=$(
jq -n --arg op "$OPERATION_ID" --arg csr "$(cat device.csr)" \
'{
operationid: $op,
keyid: "'"$CAKEY"'",
fullchain: true,
csrpem: $csr
}' | \
curl -sS --tlsv1.3 \
-X POST "$KEYSERVER/api/certificates" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @-
)
With fullchain: true, the response contains the entire chain in the order device certificate, intermediate (CA), root:
Confirm you received the full chain (device certificate, CA, and device root):
Expected output:
Operation expired?
If the response is a 410 error stating "Operation has expired", more than validms milliseconds passed between Step 9 and this step. Create a new operation and retry. Expired operations cannot be reused. In production, use the shortest validms the line needs.
Step 11: Inspect and Verify the Certificate¶
Split the chain into its three certificates: device, intermediate (the CA key), and root:
awk '/BEGIN CERT/{n++} n==1' device-chain.pem > device.crt
awk '/BEGIN CERT/{n++} n==2' device-chain.pem > intermediate.crt
awk '/BEGIN CERT/{n++} n==3' device-chain.pem > root.crt
Inspect the issued certificate:
Expected output:
OpenSSL 3.2 and newer omit the spaces around =.
Verify the chain up to the root:
Expected:
Only root.crt is the trust anchor, which mirrors a device that trusts only a burned-in root.
This proves chain integrity, not provenance
root.crt came from the same response as device.crt, so this proves only that the chain is internally consistent. In production, fetch the root once over an authenticated channel, store it with your provisioning tooling, and verify every issued certificate against that stored copy.
Finally, confirm the issued certificate contains the public key of your locally generated device key:
diff <(openssl x509 -in device.crt -pubkey -noout) \
<(openssl pkey -in device.key -pubout) \
&& echo "Certificate matches device key"
Expected output:
Completion¶
You have issued a device certificate from your own device CA and verified the three-certificate chain (device → CA → device root). In a production line, Step 7 to Step 11 run once per device, with the operation from Step 9 shared across a batch (maxusagecount = batch size), as described in Integrate Provisioning Tools. Every issued certificate is recorded in the audit log with the operation ID, giving a complete record of which certificates were issued under which approval.
Related:
- Key Types and Storage: CA keys and the certificate hierarchy
- Audit Coverage Reference: what certificate issuance records in the audit log
Production setup recommendations
The API calls are identical in production; authentication, device key generation, batch operations and approval policy change. See Issue Device Certificates from CI/CD and Provisioning Pipelines. To connect a provisioning station that issues one certificate per device, see Integrate Provisioning Tools.