Skip to content

How-To: Export a KEYSTORE Private Key

Retrieve a signing key's private key when you must sign offline, for example in an air-gapped build step or a one-time migration that needs the raw key outside the Keyserver.

Exporting a key defeats central key custody

Exporting a signing key makes its private key available for use outside the Keyserver, such as for offline signing, air-gapped build steps, migrations, or other workflows that require direct access to the key.

Once a private key is exported, the Keyserver cannot enforce approvals, usage counts, or auditing on anything signed with that copy. Those controls apply only to signing performed through the Keyserver. Prefer signing through the REST API whenever the key does not need to leave the Keyserver. An exported copy cannot be revoked or recalled, so treat it as a permanent liability.

Prerequisites

  • A signing key with Key Location KEYSTORE. Key Location is fixed at creation; it can be edited only on a REJECTED key. An HSM-backed key always returns 409 on this endpoint, because its private key never leaves the HSM in plaintext. See Key Storage. To export a key, create it with Key Location KEYSTORE. See Key Location.
  • A bearer token (client-credentials or authorization-code grant) with read scope
  • A role granting getprivkeys for this specific key. The fwsigner and devcertsigner Natures include it for each ticked key, or you can grant it as an individual permission. See Manage Roles in the Keyserver.

Step 1: Fetch the private key

This response contains the private key

Never print it to a terminal or CI log. Step 2 writes it straight into a protected file.

GET /api/keys/priv/{keyid}
Authorization: Bearer <ACCESS_TOKEN>

Response (abbreviated):

{
  "keyid": "fw-migration",
  "keyinfo": "...",
  "required-approvers": 1,
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "privatekey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "description": "..."
}

This is the same key-info object returned by GET /api/keys/{keyid}, with one addition: the privatekey field, PEM-encoded.

Step 2: Extract and protect the key material

Secure deletion is not guaranteed

shred overwrites the blocks a file currently occupies. It cannot reach copies left by SSD wear levelling, copy-on-write or journaling filesystems, snapshots, container image layers, swap, or cloud block-storage replication. On any of those, assume a recoverable copy may remain.

Export onto ephemeral storage instead, such as a tmpfs mount or a short-lived encrypted volume destroyed afterwards. Plan the key's rotation and revocation when you export it.

Write the key straight to a file only you can read:

( umask 077
  curl -sS --fail-with-body --tlsv1.3 \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    https://keyserver.<UNIQUE-ID>.cryptera-security.io/api/keys/priv/fw-migration \
    | jq -er .privatekey > fw-migration.key \
    || { rm -f fw-migration.key; echo "Export failed (see curl's status line above)" >&2; exit 1; } )
  • umask 077 before the redirect. The shell creates the file the moment the pipeline starts, using the caller's umask, so a later chmod 600 leaves a window in which the key is group- or world-readable.
  • umask 077 runs inside a subshell, so it applies to this file without changing your shell.
  • --fail-with-body makes curl exit non-zero on an HTTP error and print its status line (curl: (22) ... error: 403) to stderr.
  • jq -e exits non-zero when privatekey is missing or null.
  • On any failure the partial file is removed, so no plausible-looking key file is left behind.

Use the key for the offline step that required it, then remove it:

shred -u fw-migration.key

Audit trail

Every successful call is recorded as a getprivkeys audit entry (event REST) containing the keyid. The data field is always empty, so key material never reaches the audit log. See Monitor and Filter the Audit Log to confirm an export happened and who performed it.

If something fails

Symptom Cause and fix
409 "Private key cannot be retrieved for HSM based keys" The key is HSM-backed and cannot be exported (see Prerequisites)
403 The calling subject's roles lack getprivkeys for this specific key. The permission is key-scoped, not global (see Manage Roles)
404 "Signing key is not found" Wrong keyid
409 "Signing key is not initialized!" The key hasn't reached INITIALIZED yet. Wait for key creation to finish, or check the key's status in the admin UI
410 "Signing key has been revoked" The key has been revoked and can no longer be used
401 Missing or expired bearer token

Full status-code reference: Error Codes.