Skip to content

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, which sh/dash do not support.
  • Tools installed. awk, grep and diff are preinstalled; install the rest:

    Ubuntu 24.04:

    sudo apt install curl jq openssl
    

    macOS with Homebrew:

    brew install curl jq openssl
    
  • 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:

TOKEN=$(curl --fail-with-body -sS -X POST ... | jq -er .access_token)

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.

  1. Log in to https://keyclient.<UNIQUE-ID>.cryptera-security.io as adminuser.
  2. Click Admin, enter a description (for example Setting up device certificate hierarchy), and click Create.
  3. Wait for the yellow Authorizers badge. On a trial with one administrator, adminuser self-authorizes immediately.

Step 2: Create the Device Root Key

  1. Click Keys in the navigation bar, then Create.
  2. Fill in:

    Field Value Notes
    Key ID device-root
    HSM Key ID 0102 Unused 4-digit hex, 0100–FFFE, no 0x prefix
    Key Type ROOT
    Key Location HSM Always select HSM (KEYSTORE is only for keys that must be exportable).
    Description Device identity root
    Generator Algorithm EC
    Parameter secp256r1
    Hash Algorithm SHA256
    Required Approvers 0
    Certificate Validity 3650

    Leave the Distinguished Name fields at their defaults. Field-by-field guidance is in Part 1: Create a ROOT key and Manage Keys.

  3. 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-root to show INITIALIZED before continuing.

Step 3: Create the Device CA Key

The CA key issues device certificates directly from CSRs; device-root signs its own certificate.

  1. Click Create from the Keys list again.
  2. Fill in:

    Field Value Notes
    Key ID device-ca
    HSM Key ID 0103 Different 4-digit hex value from device-root
    Key Type CA
    Key Location HSM Same location as device-root
    Root Key device-root Selecting it locks Generator Algorithm to device-root's and resets Parameter to its default; confirm Parameter is secp256r1 and set Hash Algorithm to SHA256
    Description Device provisioning CA
    Required Approvers 0 Immediate issuance, for this tutorial
    Certificate Validity 1825 The CA key's own certificate
    Issued Device Certificate Validity 730 How long certificates issued from CSRs stay valid, independent of the field above
  3. 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-ca to show INITIALIZED before 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

  1. Click Roles in the navigation bar, then Create.
  2. Fill in the header fields:

    Field Value
    Name devicecert-issuer
    Description Provisioning clients — issues device certificates from device-ca
  3. Expand Signing Key Permissions ..., then click Add natures to role ...

  4. In the Nature dropdown, select devcertsigner, the Nature for provisioning clients that issue device certificates from CSRs.
  5. A list of key checkboxes appears. Tick device-ca.
  6. 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

  1. Click Subjects in the navigation bar.
  2. Click the edit (pencil) icon in the devicecert-client row. 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.
  3. In the Associated Roles section, check the box next to devicecert-issuer. Leave any roles that are already ticked as they are.
  4. Click Save.

Step 6: Close the Administrative Session

  1. Click Admin in the navigation bar.
  2. 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:

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:prime256v1 -out device.key

Create a CSR carrying the device identity (typically the serial number as CN):

openssl req -new -key device.key -out device.csr \
  -subj "/CN=Device12345/O=ExampleCorp"

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:

Token received

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:

printf '%s' "$CERT_RESPONSE" | jq -r '.certificates' > device-chain.pem

Confirm you received the full chain (device certificate, CA, and device root):

grep -c "BEGIN CERTIFICATE" device-chain.pem

Expected output:

3

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:

openssl x509 -in device.crt -noout -subject -issuer

Expected output:

subject=CN = Device12345, O = ExampleCorp
issuer=CN = device-ca, OU = , O = , L = , ST = , C =

OpenSSL 3.2 and newer omit the spaces around =.

Verify the chain up to the root:

openssl verify -CAfile root.crt -untrusted intermediate.crt device.crt

Expected:

device.crt: OK

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:

Certificate matches device key

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:

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.