Capability Grants
What this screen is for
A capability grant authorizes one cryptographic actor to perform named operations on named keys. It answers four questions in one record: who may act, what they may do, on which keys, and under which conditions. This screen lists the active grants in your tenant and is where you create and revoke them.
Every cryptographic operation an actor requests is checked against its grants when it runs. A role lets the actor request a kind of operation; a grant decides which keys that operation may use. Without a matching grant the operation is refused, even when the actor holds the role, and the refusal is recorded in the audit trail with its reason.
What must exist first
This screen is for tenants that compose authorization by hand. It is not offered to SIMPLE tenants: a SIMPLE tenant uses Internal Use Cases, which create the grants each use case needs.
Before you work here:
- A cryptographic actor to receive the grant. The wizard lists actors, exchange contexts and constraint policies with your permissions to list each of them; a list you cannot read is empty.
- The keys the grant will name. A grant can only name a key that exists in your tenant and has not been deleted.
- The permission to list capability grants, which is what shows this screen. Creating and revoking grants are further permissions, each held separately.
Decisions you make here
Creating a grant
With the permission to create capability grants, New Grant opens a wizard. You choose the actor, the operations, the keys, and optionally an exchange context and a constraint policy, then review everything before Create Grant. The grant takes effect as soon as it is created.
Choosing the operations
Capability offers ENCRYPT, DECRYPT, SIGN, VERIFY, REENCRYPT and RESIGN. A grant authorizes exactly the operations you tick, so tick only what the actor needs.
REENCRYPT and RESIGN work from one key to another. They are operations in their own right: a REENCRYPT grant lets the actor move data from one key to another without letting it decrypt that data on its own. A single grant holds either these key-to-key operations or single-key operations, never both, and a mix is refused when you create it. To authorize both kinds, create two grants.
Choosing the keys
For single-key operations you choose one Asset key. For REENCRYPT or RESIGN you choose a Source key and a Target key. The grant then covers operations between those two keys in either direction, and within either key on its own, so name only a pair the actor may use both ways.
The wizard does not check that a key's purpose fits the operations you ticked. A key made to encrypt and decrypt cannot sign or verify whatever a grant says, and a signing key cannot encrypt, so choose keys whose purpose matches.
Instead of a key, you can tick the wildcard box for single-key operations. The grant then applies to every key in your tenant, including keys created after it. That is the broadest authorization a grant can give: keep it for an actor that genuinely needs every key, and name keys everywhere else.
When you start a grant from a key in the Key Inventory, that key is already chosen and cannot be changed or replaced by the wildcard.
Narrowing to an exchange context
Exchange Context is optional. A grant with an exchange context authorizes its operations only inside that business relationship. A grant without one applies whatever context a request names, or none.
Whichever grant matches, an operation bound to a suspended or closed exchange context is refused. Suspending or closing a context therefore stops every grant that works inside it at once, without revoking any of them.
If an actor holds grants for the same operation and key in more than one exchange context, its requests must name the context they belong to, or they are refused.
Narrowing with a constraint policy
Constraint Policy is optional. A policy adds conditions that every use of the grant must meet: a validity window, a maximum number of uses, a rate per minute, and single use. A grant can reference one policy. Left Unconstrained, the grant is limited only by its actor, operations, keys and exchange context.
A grant takes its limits from the policy when the grant is created. The constraint policies screen explains how each condition behaves and what an edit to a policy does to grants that already reference it.
Revoking a grant
With the permission to revoke capability grants, Revoke withdraws a grant. The actor loses those operations on those keys from its next request; its other grants, and other actors, are unaffected. A revoked grant cannot be restored: create a new one if the authorization is needed again.
Revoking is refused while a cryptographic exchange composes the grant, because the exchange owns the grant's lifecycle. Revoke the exchange instead.
How it relates to other screens
The actor a grant authorizes, and the roles that let it request each kind of operation, are managed on the actors screen. An actor cannot be deleted while grants still reference it:
The two optional narrowings are managed on their own screens:
Grants name keys held in the Key Inventory. Deleting an application revokes the grants of its actors.