HSM / Cloud KMS — Per Tenant
What this screen is for
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.
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.
What must exist first
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 platform super administrator holds them; the platform-configuration write neither grants nor is required for any of them.
What the tenant's credential must be granted
The credential of a tenant's own key must be able to read the key's state and its versions, besides wrapping and unwrapping: the key custody check reads them after a restore or an upgrade, so binding the backend and rotating the credential prove them against the declared key. Grant it:
- AWS KMS:
kms:DescribeKey, pluskms:ListKeyRotationsfor a key with imported key material (originEXTERNAL). - Google Cloud KMS:
cloudkms.cryptoKeys.getandcloudkms.cryptoKeyVersions.list. The roleroles/cloudkms.cryptoKeyEncrypterDecrypterincludes neither. - Azure Key Vault and Managed HSM: nothing new; the
getkey permission already required serves it.
The full list of grants, with why each is needed, is in Per-cloud client prerequisites, in the customer documentation.
Decisions you make here
Which backend a tenant may declare
Which of the five a tenant may declare is narrowed by your own allowlist, one of the values on the Configuration tab. 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.
On AWS KMS the key is declared by its key ARN; an alias ARN is refused. A key this deployment created or uses for its own key custody is refused too. A refused credential or key changes nothing:
The credential check, and rotating it
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.
Key custody, and moving it
Below the card, Key custody shows a key custody 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.
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.
Destroying a retired key-encryption key
A retired key-encryption key past its retention, with nothing wrapped under it, offers Destroy…. The platform holds every destruction for the deployment's waiting period (30 days by default) without calling the key's provider or HSM: the list shows Destruction due on with the date the period ends, and until then Cancel destruction… returns the key to retired.
When the period ends the platform checks the key again. If it wraps key material again, shares its key object with a key in use, belongs to a tenant whose custody is moving, or the object under its name is not the recorded one, nothing is destroyed, the key is retired again and a platform alert is raised; destroying it then takes a new request, and after an object that is not the recorded one, only once the token or key service has been investigated.
Otherwise the platform sends the destruction to the key's provider. Until the provider's answer is recorded, the list shows Sent to the provider and Cancel destruction… is disabled. An HSM then destroys the key object: the list shows Destroyed on the HSM, awaiting confirmation, with no cancel.
A Cloud KMS starts its own waiting period, which adds to the platform's: the list shows At its provider with the provider's date, and Cancel destruction… cancels it at the provider until then. 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.
How it relates to other screens
The deployment's own backend, which every tenant without a backend of its own inherits, is set on the Configuration tab:
A tenant's keys are what its backend protects: