Generate, rotate or revoke a key from an application

Create, rotate or revoke a key of your tenant from code rather than from the console screens.

Who can do it

Not an application's cryptographic actor. The token an application obtains with its actor credential cannot create, rotate or revoke keys:

• The key generation and rotation operations of the cryptographic API are not part of its published contract. The scope key generation needs is never given to an actor, and a rotation is refused with 403 for any token not issued to the administration service, whatever scope it carries.
• Key creation, rotation and revocation are administration operations. A tenant administrator or a tenant key manager runs them, from the console or from code, with the key management CLI, the Admin SDK or the administration API. A platform super administrator can also rotate and revoke a tenant's keys.

An application therefore uses the keys it is granted; the people who manage keys create and change them.

Before you start

• You hold the tenant administrator or tenant key manager role in the tenant.
• The tenant has a key protection backend. Until one is configured, key creation is refused.

Steps

1. Create the key with the administration surfaces, as described in Create a key:
   • Key management CLI: ankasecure-km keys create --kid <id> --algorithm <algorithm> --purpose <purpose>, or --body-file with the full request.
   • Admin SDK: KeyOperations.create(OrchestrationKeyRequest).
   • API: POST /api/v3/admin/tenants/{tenantId}/keys (operation createKey).
2. Rotate the key, which advances it to a new material version under the same key identifier:
   • Key management CLI: ankasecure-km rotation rotate --kid <kid> --body-file <file>.
   • Admin SDK: RotationOperations.rotate(kid, RotationRequest).
   • API: POST /api/v3/admin/tenants/{tenantId}/keys/{kid}/rotations (operation rotateKey).
3. Revoke the key, giving the reason and the lifecycle cause the audit trail records:
   • Key management CLI: ankasecure-km keys revoke --kid <kid> --cause <cause> --reason <reason>.
   • Admin SDK: KeyOperations.revoke(kid, RevokeKeyRequest).
   • API: POST /api/v3/admin/tenants/{tenantId}/keys/{kid}/revoke (operation revokeKey).
4. Grant the application's actor the operations it needs on the key with a Capability Grant. Until it holds one, every cryptographic call on the key is refused with 403.

What you see when it worked

The key appears in the tenant's key inventory under its identifier. After a rotation, the key keeps its identifier and reports its new primary material version; data protected under earlier versions can still be read as the lifecycle policy allows. A revoked key stops protecting new data.

If it fails

Without the console

Related

• Create a key
• Key Inventory
• Capability Grants