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 returns409on this endpoint, because its private key never leaves the HSM in plaintext. See Key Storage. To export a key, create it with Key LocationKEYSTORE. See Key Location. - A bearer token (client-credentials or authorization-code grant) with
readscope - A role granting
getprivkeysfor this specific key. ThefwsigneranddevcertsignerNatures 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.
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 077before the redirect. The shell creates the file the moment the pipeline starts, using the caller's umask, so a laterchmod 600leaves a window in which the key is group- or world-readable.umask 077runs inside a subshell, so it applies to this file without changing your shell.--fail-with-bodymakescurlexit non-zero on an HTTP error and print its status line (curl: (22) ... error: 403) to stderr.jq -eexits non-zero whenprivatekeyis missing ornull.- 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:
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.