Skip to main content

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.

ImageFloat_Right_Large

Policy​

Each key can have a policy that defines its authorization rules.

info
  • If a policy is left empty (null), the key will not use SKA.
  • Note that keys not configured with SKAs initially (null policy) cannot be modified later to use SKA.
  • If you plan to use SKA Keys later in your project, you can start with an empty policy (always fulfillable) and update it later with 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.

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
Last updated on