Cryptographic Keys

The Keys page (/keys) manages the cryptographic key material your organization uses with the HSM Engine (SHE) and, through it, the HSMaaS/payShield flow. This is the most operationally sensitive page in the dashboard — every action here governs live key material, not a cosmetic setting.

What these keys are

Keys listed here are managed by the Key Management Service (KMS), but the clear (plaintext) key material never lives in KMS itself — except transiently, for the clear-components Import path described below. KMS stores a wrapped value (the key encrypted under SHE’s Local Master Key, or LMK — still key material, just protected, not plaintext) and a Key Check Value (KCV) used to confirm a wrapped value decrypts to the expected key without ever exposing it. Generating, importing, and rotating a key all delegate the actual cryptographic operation to SHE — KMS is the tenant-facing catalog and API in front of it.

The full clear key is never shown or requested by the dashboard, and is never returned by any API. (The one exception is the clear-components Import flow — see Import below — where you do enter individual plaintext key components; those traverse the management plane, but the complete key is never assembled outside SHE.) Every operation that produces new key material returns a wrapped value and KCV exactly once on the dashboard’s own (public-facing) API — there is no dashboard or public endpoint to retrieve them again later. KMS does retain the wrapped value and KCV internally: a separate, internal-only endpoint exists for trusted runtime callers to fetch the active wrapped material without you re-supplying it, for future engine integration. That endpoint is not reachable from the dashboard or the public API surface, and nothing in the platform calls it in production today — see Operational cautions.

These are the same keys your integration uses on the HSMaaS transport: a payShield command you send over that TCP connection carries the wrapped key inline, and SHE unwraps it under the LMK to perform the operation. See that page for the wire-level contract; this page covers managing the keys themselves through the dashboard.

Each key has a type (ZMK, ZPK, or PVK — the payShield key types SHE supports), an algorithm (3DES, AES-128, or AES-256), an optional usage label (a free-text note, e.g. PIN), and a status:

• active — the version KMS currently returns as this key’s active version.
• superseded — a former active version, replaced by a later rotation. KMS no longer returns it as active, but a wrapped value copy already deployed remains cryptographically usable — see Rotate.
• retired — the key can no longer be rotated or looked up as active in KMS, and this cannot be undone. A wrapped value copy already deployed remains cryptographically usable — see Retire.

Generate

Creates brand-new key material from scratch. You choose a type and algorithm (and optionally a usage label); SHE generates the key under the LMK and KMS returns the wrapped value and KCV. Use this when you don’t already have key material to bring in — for example, provisioning a fresh ZPK for a new PIN flow.

Import

Brings in key material you already hold, rather than generating new material. The full clear key is never assembled or seen outside SHE. Two methods are supported:

• Under KEK — you supply a Key Encryption Key (already wrapped under the LMK) and your key encrypted under that KEK; nothing here is plaintext — SHE unwraps and rewraps it under its own LMK.
• Clear components — you supply two or more key components (as used in traditional dual/triple-control key ceremonies) directly into the dialog. Each component is itself sensitive plaintext key material and travels through the dashboard, the BFF, and KMS to SHE in the clear; SHE combines the components inside the HSM boundary, and only the reconstructed complete key is never assembled or visible outside that boundary. Treat this flow with the same care as handling physical key components in a ceremony — ensure it runs over a trusted connection and that no component is logged or captured along the way.

Use Import when you are migrating existing key material from another HSM or provider rather than generating fresh material in Switchbench.

Rotate

Rotating a key creates a new version of it — incrementing the version number — and marks the previous version superseded in KMS’s catalog. You get a new wrapped value and KCV for the new version, which you copy into your configuration.

As with Retire, rotation is a KMS catalog-level change, not a cryptographic invalidation of the old wrapped value: SHE continues to accept any valid LMK-wrapped value carried in a command, including a superseded version, and switching your systems to the new wrapped value does not stop the old one from working. Rotating changes which version KMS marks active and would return from an internal lookup — it does not, by itself, revoke a wrapped value you have already deployed. Coordinate rotation with your own deployment: update every system still holding the old wrapped value in the same maintenance window, since Switchbench does not track which version an in-flight integration is currently configured with, and the old value keeps working until you remove it yourself.

Retire

Retiring a key permanently marks it retired in KMS: it can no longer be looked up as the org’s active key for its type, and it cannot be rotated or un-retired — this action is not reversible.

Retirement is a KMS-side, catalog-level state change, not a cryptographic revocation of the key material itself. SHE is stateless and unwraps whatever LMK-wrapped value it is given in a command without consulting KMS or checking whether that key’s keyRef is still active — so a wrapped value already distributed to your systems remains cryptographically usable after you retire the key in KMS. Retiring stops KMS from handing that key out as the active one for new lookups; it does not revoke or invalidate copies you have already deployed, and neither does rotating (see Rotate) — there is no mechanism today that revokes a deployed wrapped value’s usability. Retire a key only after you have confirmed no active integration still depends on it; to actually stop a deployed wrapped value from working, you must remove or replace it in your own systems yourself.

Operational cautions

• These actions govern live cryptographic material used by real payShield operations, not display-only configuration. There is no draft or preview step — Generate, Rotate, and Import each produce usable key material immediately.
• Wrapped values and KCVs are shown once, at the moment of the operation. If you close the dialog without copying them, you cannot retrieve them again from the dashboard — you would need to rotate (or re-import) to get a new value.
• Retiring is permanent in KMS’s catalog (no un-retire), but — as explained in Retire — it does not revoke wrapped values you have already distributed; SHE will still process them. Plan retirement together with removing the wrapped value from your own systems if immediate revocation is the goal.
• Row-Level Security scopes every key to your organization — you can only see and act on your own org’s keys.
• The dashboard and public API never return the wrapped value/KCV after the moment of creation, but KMS keeps them internally: a separate internal-only endpoint (not reachable from the dashboard or public API) exists for a trusted runtime caller to fetch the active wrapped material without you resupplying it. Nothing in the platform calls it in production today — it is available for future engine integration.

For the wire-level details of how a wrapped key is used inside a payShield command, see HSMaaS (raw payShield) over mTLS TCP.