Authorization Policy
When generating a key, a policy can be attached to it. This page describes what this policy is, and how it can be used to authorize key usage.
Attributes specify the type of cryptographic operations that can be done with the key. The policy specifies the authorization (when the key can be used). A policy consists of different rules. A rule consists of tokens. A token specifies the conditions under which key usage is permissible.
Attributes
The following basic attributes can be attached to a key:
- Sign: If true the key can be used to sign.
- Decrypt: If true the key can be used to decrypt data.
- Unwrap: If true the key can be used to unwrap keys.
For all available attributes, see this page.
Policy
Each key can have a policy that defines its authorization rules.
You have to decide during creation whether you want to use SKA with a key:
- If a policy is left set to null during creation, the key will not use SKA.
- Keys not configured with SKA during creation cannot be modified later to use SKA.
- If you plan to use SKA Keys later in your project, start with an empty (but non-null) policy. This policy is always fulfillable. Modify it later to a full SKA policy.
Rules
Rules define the conditions that need to be satisfied for a operation to be executed on the HSM.
Rules are grouped by the type of operation. The following rule types exist:
- Use: To use this key in a (signing, decrypt, unwrap) request.
- Modify: To modify the policy of this key.
- Note: This does not modify the key's attributes — only the SKA policy.
- Block: To block usage of this key.
- Being able to block the key can be useful, for example during a security incident.
- Unblock: To unblock usage of this key.
If a rule is empty, the associated operation can be performed without any conditions needing to be satisfied.
A rule contains multiple tokens. If one token is satisfied, the rule is satisfied and the associated operation is allowed by the HSM. In other words, a rule combines tokens with a logical OR.
Tokens
A token consists of a name, a timelock value, a timeout value, and multiple groups.
The timelock value is the amount of time after which the token becomes active, starting from the creation time of the request. When the timelock is set to 0 the token is immediately active.
The timeout value is the amount of time after which the token is no longer active, starting from the creation time of the request. When the timeout is set to 0 the token is forever active.
For more details on how the timestamps are enforced, see the timestamp page.
If all groups in a token reach their quorum of approvals, the rule is satisfied (assuming the timelock or timeout is also satisfied). In other words, a token combines groups, timelock, and timeout with a logical AND.
Groups
A group consists of a list of approvers and a quorum.
An approver is a public key (explicitly, or via some reference). Approvals need to be signed with the corresponding private key.
A quorum is the minimum number of approvers needed for the group to reach approval. For example, if the quorum is 2, and there are 5 approvers, any two approver signatures make the group reach approval.
Examples
Using tokens, groups, and quorums, you can construct arbitrary authorization policies. For example:
- 2 out of 5 board members OR 4 out of 7 security officers can sign
- 1 out of 7 board member AND 3 out of 6 security officers can decrypt
- 1 fraud detection engine can block the key
- 2 out of 5 fraud analysts can unblock the key