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.

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 built-in platform 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 built-in platform 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 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.

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.

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.

Per tenant

The controls of this tab follow three permissions to manage a tenant's own backend from the platform, each for its own controls: declaring — which also covers changing it, rotating its credential, validating it and reverting it — binding it, and running its connection test. A role may hold any one of them without the others. Only the built-in platform administrator holds them; the platform-configuration write neither grants nor is required for any of them.

The Per tenant tab is where a tenant is given a key-protection backend of its own instead of inheriting the deployment's. You choose the target tenant from a selector and never by impersonating it, and the tenant is restated as text beside the surface so a write cannot land on a tenant you did not choose. On a customer-operated install every tenant is entitled to this and no licensed edition is consulted; on a SaaS or dedicated SaaS install only a tenant whose effective edition is Enterprise is.

A tenant's own backend is always a cloud key service: AWS KMS, Google Cloud KMS, Google Cloud KMS (HSM), Azure Key Vault or Azure Managed HSM. An HSM appliance is never offered here. It is linked once, on the Configuration tab, and every tenant that keeps the default inherits it with a key-encryption key of its own. A tenant that must hold its key in an HSM it owns uses AWS KMS with a key in an AWS CloudHSM key store.

Which of the five a tenant may declare is narrowed by your own allowlist, one of the 86 values. An empty allowlist is not "nothing admitted" — it means no restriction has been bound, so all five remain. An allowlist that names only HSM backends, saved before they left this tab, admits none of the five: clear it or name cloud backends.

Declaring a backend does not put it into force. Until the tenant's backend is bound, the tenant cannot create keys: its first key is refused until the bind succeeds, and it does not go on using the backend it had before. Bind before the tenant starts working.

The custody statement on the card names who operates the key service that holds the tenant's key-encryption key: the tenant itself when it brought its own backend; your organisation when this is a customer-operated install; ANKATech on a SaaS or dedicated SaaS install, shared by every tenant on the same tier.

The credential check on the card is a fact the server records, not a guess from the backend's state. It reads Not checked yet while no check is recorded, on an ACTIVE backend too; a connection test or a rotation records one in any state. It reads Proven at with the time after a check passed, and Last check failed at with the time and the reason when a connection test did not pass: refused, unreachable or timed out. Declaring, changing or withdrawing the backend clears it.

Rotating a tenant's access credential never touches key material, and it proves the new credential before replacing the old one. The new credential alone is checked against the declared key: when the tenant already holds non-composite keys that are not public-only imports, the most recent one is unwrapped with it first, and then a throwaway value is wrapped and unwrapped with it. The credential in force is not used, so a rotation works even after the old credential was deactivated at the cloud provider.

A credential that fails the check is refused with its reason and the check that was running, and the credential in force stays as it was. Read the reason first: a credential the key service does not accept at all is reported against the first check, and the fix is the secret itself. A credential that may only decrypt is refused, because new keys must also be wrapped with it. Submitting the same credential again gives the same answer; correct it first. When the key service cannot be reached, the refusal is temporary and a retry shortly is the next step.

After a successful rotation the previous credential can stay in use for a short time (by default up to 60 seconds), so deactivate it at the cloud provider only after that. A rotation over an HSM declaration stored before a tenant's own backend became cloud-only is refused too and changes nothing. Once a tenant holds key material, declaring another backend here is refused, and the refusal says the change is a key custody move.

Below the card, Key custody shows that move: where the tenant's keys are protected, the open move and its progress, the key-encryption key rotation, the retired keys still retained, and the history. When observed, Rotation at the provider reports whether the tenant's own key rotates automatically at its provider; the platform never rotates it.

A retired key-encryption key past its retention, with nothing wrapped under it, offers Destroy…. On a Cloud KMS its provider destroys the key object once its waiting period ends, and until then Cancel destruction… returns it to retired; the list shows the date the provider destroys it. On an HSM the key object is destroyed at once, so it is normally already gone and its cancel is refused; the list shows it destroyed on its HSM, awaiting confirmation. If the HSM gave no answer and the object is still on it, Cancel destruction… returns the key to retired. Either way it reads Destroyed once the provider confirms it. After that nothing still wrapped under the key, including in older backups, can be decrypted. A tenant's own key is never destroyed.

On a customer-operated install you start the move here — to the tenant's own key management service, to another one, or back to the deployment backend, confirmed by typing the tenant's name — and schedule, cancel, abort or roll it back; during its window the tenant is in maintenance. On a SaaS or dedicated SaaS install this tab only reads a tenant's own backend: its tenant administrator manages it, each write here is inert and says why, and the connection test stays available.

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: