Key custody

Each organization has at most one active signing key. When one of its runs is sealed, the seal is signed with that key. This page describes where the key is held and how it is protected. The operations on it are on Signing keys.

The key¶

A signing key is an Ed25519 key pair. It is either generated inside Pentr or uploaded by the organization as a PKCS#8 PEM. If an organization has no active key when its first run is sealed, one is generated at that point.

The public half is stored in the clear, and it is what a recipient pins when verifying a locker. The key's key_id is the SHA-256 of the public half.

How the private half is held¶

Pentr holds the private half of every organization's signing key. It is stored wrapped: encrypted with AES-256-GCM under a 32-byte key-encryption key (KEK), with a random 12-byte nonce for each wrap and the key's key_id as associated data. A wrapped key decrypts only against the key_id it was wrapped for.

The KEK comes from the PENTR_KEK environment variable of the services that handle signing keys. It is not stored in the database. If it is unset or malformed, the endpoints that generate or upload a key answer 503, and completed runs are left unsealed.

No endpoint returns the wrapped key or the identifier of the KEK that wrapped it. The key endpoints return the public half and metadata only.

When the key is used¶

The private half is unwrapped in one place: the sealing step at the end of a run, which runs in the scheduler. The unwrapped key is held in that process's memory to sign the seal.

Signing is done in software, inside the Pentr process. No KMS or HSM is used. Pentr is therefore able to sign on an organization's behalf.

Uploaded keys¶

An uploaded key is wrapped and held by Pentr in the same way as a generated one. Uploading lets the organization keep its own copy of the private half. It does not keep the key out of Pentr.

Lifecycle¶

Signing keys have no console screen. They are managed through the UI API, as Signing keys describes. Generating or uploading a key retires the active key and makes the new one active. No endpoint retires a key without activating a replacement, and none deletes a key. A retired key stays stored, so seals it signed remain verifiable.

Verification is independent of Pentr¶

A recipient verifies a locker offline, with pentr-verify and the organization's public key. No Pentr service takes part in the check. pentr-verify is open source (MIT) at github.com/PentrAI/pentr-verify and is not published to a package registry. Verifying a locker covers how to obtain it, how to pin the key, and what a pass establishes.