HSM / Cloud KMS
What this screen is for
This is where your installation's key-protection backend is declared, configured and put into force. That backend holds the key-encryption key under which every tenant's key material is wrapped, so it is the one custody decision the whole platform rests on. It is the largest subsystem in Platform Settings: 86 of the deployment's 316 configuration values belong to it, and behind them sit records of their own — the declaration, its coordinates and each tenant's own backend when it has one.
Nine backends can be declared, in two families. Self-hosted HSM: SoftHSM, nShield and Thales Luna. Cloud, by provider and variant: AWS KMS and AWS CloudHSM, Google Cloud KMS and Google Cloud KMS (HSM), Azure Key Vault and Azure Managed HSM. Exactly one is active per environment; the two families are mutually exclusive. Each carries an evidence badge — Certified, Experimental or Design only — stating how far ANKATech has exercised it, and a mechanism marked Design only cannot be declared at all.
The screen has up to three tabs: Configuration, Per tenant and, for a viewer who may read the audit trail, Activity. The Per tenant tab, where a tenant is given a key-protection backend of its own, has its own help, linked below.
What must exist first
- The permission to read platform configuration, which shows the values, and the permission to read the first-run setup state, which shows where the declaration has got to. The platform super administrator, auditor and viewer roles hold both.
- The permission to perform bootstrap operations, for every step of the ladder below — declare, save coordinates, validate, activate. Only the platform super administrator holds it.
- The permission to write a deployment secret, additionally, to seal a cloud credential or to withdraw a declaration. Withdrawal requires both, because disposing of a sealed credential is a change to it.
- The permission to run the key-backend connection test, which is a separate one: it is a diagnostic, not a provisioning act, so checking whether the backend answers does not require the authority to declare one.
- For a cloud backend, a credential granted the provider permissions below before you seal it.
- For a self-hosted HSM, the host itself prepared first. The screen renders that vendor's checklist and the command to run, because on a customer-operated install you hold that host.
What a cloud credential must be granted
The credential you seal for a cloud backend creates and uses one key per tenant and their automatic rotation. Grant it:
- AWS KMS:
kms:CreateKey(aSYMMETRIC_DEFAULTkey per tenant),kms:CreateAlias,kms:ListAliases,kms:DescribeKey,kms:Encrypt,kms:Decrypt,kms:GetKeyRotationStatusandkms:EnableKeyRotation; alsokms:ListKeyRotationswhen the deployment key holds imported key material (originEXTERNAL), so the key custody check can read its materials. - Google Cloud KMS:
cloudkms.keyRings.create,cloudkms.keyRings.get,cloudkms.cryptoKeys.create,cloudkms.cryptoKeys.get,cloudkms.cryptoKeys.update,cloudkms.cryptoKeyVersions.useToEncrypt,cloudkms.cryptoKeyVersions.useToDecryptandcloudkms.cryptoKeyVersions.list. - Azure Key Vault and Managed HSM: the key permissions
create,get,wrapKey,unwrapKey,getrotationpolicyandsetrotationpolicy.
The key-state seal key needs no permission of its own: the platform generates it and keeps it wrapped by the deployment's key, so it never appears at the provider.
No deletion permission is needed: the platform never destroys a key in the deployment backend's account. Without the rotation permissions every wrap still works and the platform alert kek.rotation.missing stays open. The full list, with why each permission is needed, is in Per-cloud client prerequisites, in the customer documentation.
Decisions you make here
Reading where the deployment stands
One badge states the position, and it is the server's verdict rendered, never composed here: Not configured, Declared, pending activation, Activating, Bound, pending completion, Active, or Bound but unreachable. Read the last one literally — it is painted as a failure rather than as a paler Active, because it is the state that would otherwise be acted on as a false green. Beside it the last self-test verdict reads Not run, Not applicable, Passed or Failed.
A bind takes effect without a restart, whichever route issued it: after init-hsm.sh --activate records it on the host, the badge moves on to Bound, pending completion and Complete setup is offered. Activating means the backend is not yet serving — no provisioning backend is available, or the last self-test did not pass.
While a delivery is owed — only on an appliance's host route, before the second activation — the screen shows the command that delivers the staged configuration and says the platform is waiting for it; run it on the host as the environment's deploy user, not as root. On a hosted install the command is not shown: the screen says a delivery is owed and that the operator of the deployment runs it.
Two further states are neither of those: while the status is still being read, or could not be read, the screen says so and does not render the healthy view. A backend whose status never arrived is not a backend that works.
The ladder, and the one step that reaches the backend
Putting a backend into service runs up to five links in order: the coordinates check, the backend declaration, saving the coordinates, sealing the credential, and the activation. Which links are owed depends on how far the deployment has got and on the family — a self-hosted HSM seals no credential here at all, because its token PIN is held by the host as a deployment secret and never travels through the console.
On an nShield, Luna or AWS CloudHSM appliance the host path takes more than one run: the first activation installs the partition credential and stages the configuration, a delivery hands that configuration to the running services, and a second activation binds.
The screen always shows the command for the step you are on — the first activation with its credential argument until the host reports the credential installed; then the delivery and the bare second activation, until the running services carry the staged configuration; after that, the bare second activation alone. Run the delivery first and the activation only after it: the activation reads the configuration the delivery hands over. It never asks you to install a credential the host has already installed.
Only the activation reaches the backend. Saving coordinates records an address, and sealing a credential stores a credential; the activation is where the platform performs a wrap-and-unwrap round trip and commits to serving what was configured. There is no option to skip that test: it is the only observation of the backend on the whole path.
On a self-hosted HSM the round trip creates one temporary AES-256 key on the declared token, confirms from the object's own attributes that it cannot leave the token, wraps and unwraps under it, and destroys it. The label is random and sits outside the tenant key namespace.
A refusal before the round trip contacts nothing and is safe to retry. A refusal the backend itself produced names its cause from a closed vocabulary and never carries an address, a region, an account identifier or a vendor message. A run that created some tenant keys and then failed is reconciled rather than rolled back: re-run after correcting the cause and the existing keys are adopted without the backend being contacted for them.
A successful activation from this screen also completes first-run provisioning, so nothing is left to press afterwards. A bind issued on the host does not: once the running services carry it, the badge reads Bound, pending completion and Complete setup finishes first-run provisioning.
Withdrawing a declaration, and the window that closes
A declaration can be withdrawn while at least one bootstrap tenant still lacks an active key-encryption key, and is refused once both hold one. Withdrawal clears more than the row it is named after: the declared backend, the saved coordinates, the sealed credential together with any retained previous or stranded candidate, and the bootstrap tenants' active key-encryption key rows. Declaring the same backend again therefore costs a fresh credential — there is no restore point across the change.
After that window closes the declared backend is immutable. Re-pointing it would orphan the key material already wrapped under it, permanently and unrecoverably, so the platform refuses; changing it then means destroying and recreating the environment. Every uncertainty resolves to still-bound: a contradicted claim, an unverifiable one and a failed read are all refused alike.
The values themselves
The active backend's parameters are grouped and shown read-only, and every other backend is a static row naming itself, its evidence and the note that it is not active here — not a control. Secrets are masked by the server before they reach the console and are never echoed back; a credential you set is write-only.
Below them, Tenant key-encryption key rotation sets how often the platform rotates each tenant's key-encryption key on a PKCS#11 backend, online: a whole number of months from 1 to 24, 12 by default, saved with the permission to manage key custody. A cloud backend shows Set by the provider, because its provider rotates that key material itself: each tenant has its own key there, which the platform puts on the provider's automatic rotation when it creates it, every 365 days by default.
Three coordinates can be set here, and all three are classified dangerous: which strategy selects the token (label or serial), the token label, and the token serial. The card offers a control only for the ones the current strategy reads — the strategy itself and the coordinate it names — and keeps the other one named, with the reason it is not read; changing the strategy is what brings it back.
When the strategy has no value the card offers all three. A control reads Set while nothing is stored and Change, beside the stored value, once something is.
On AWS CloudHSM the module reports no token serial, so the platform refuses selection by serial there: the strategy offers only label, the card says why, and a write of serial through the API is refused with nothing changed. Address that token by its label.
Positional selection is not accepted on this deployment, so the slot-index entry is published read-only in effect and must be left empty. No PKCS#11 module path is writable anywhere in the catalogue, and the vendor profile is fixed for the life of the environment.
How it relates to other screens
This screen sits inside the Cryptography & Trust group, beside the timestamping authority and the migration trust rules:
A tenant's keys are what this backend protects, and the integration map draws this surface's status beside every other connection: