User's Guide: Group Quorum Policy

Introduction

A quorum policy is composed of one or more quorum policy rules. A quorum policy rule is composed of:

  • Quorum Group: A set of members in the group that are needed to approve an operation.
  • Administrator: Minimum number of administrators that need to approve the operation.
  • Application: an application that approves a sensitive operation for a specific use case.
  • Using a second-factor security key to approve the request.
  • Password re-entry required to approve the request.

In addition, the quorum policy can establish if “all” or “any” of the quorum policy rules are required to have a quorum and approve the requested operation.

Quorum Policy - Enabling Quorum Approval Policy on Groups

A Group Administrator may enable a quorum approval policy on a group. Doing so mandates that all security-sensitive operations in that group would require approval by a quorum. The list of security-sensitive operations includes:

  • Key deletion
  • Key metadata update
  • key name update
  • Key export (only when the key is marked exportable). This includes:
    • Encrypted Export (Key Wrapping)
    • Export as Components.
  • Encryption and decryption
  • Signature generation
  • Mac generation
  • Wrap key
  • Unwrap key
  • Derive key
  • AgreeKey (ECDH)
  • Plugin create and update
  • Get app credential (API Key/Password)
  • Updating group level metadata
  • Update/Delete Quorum Policy
  • Add/Update/Delete Cryptographic Policy
  • Add/Update Key metadata Policy
  • Key rotation (3.25 release onwards)
  • Group change (update the group for a security object)
NOTE
Plugins by default do not honor the quorum policy set on a group. Use function require_approval_for to make plugin execution follow quorum approval flow (see https://support.fortanix.com/hc/en-us/articles/360018084432-Lua-Plugins-Reference#Thefunction'require_approval_for).

Group Quorum Policy

Create a Quorum Policy for a Group

  1. Go to the detailed view of a group, and in the INFO tab, in the Quorum approval policy section click the ADD POLICY button.
  2. In the Quorum approval policy form, fill the details such as the number/name of administrators or applications that need to approve sensitive operations with keys and plugins.
    NOTE
    • Only verified users can be added as approvers in the Quorum approval policy.
    • Users with pending invites will not appear in the drop down for quorum approvers.
  3. Click the Advanced button to add more combinations for the quorum policy.
  4. There are two optional check boxes:
    1. Using a second-factor security key is required to approve requests - This option will be automatically enabled if second-factor authentication is enabled by the user at the account level, from the Authentication tab on the Account Settings page. The user cannot edit this option.
    2. Password re-entry is required to approve request: Enable this option if you want a re-entry of the password to approve a request.
  5. The Operations that require Quorum approval section allows configuring which operations in the group will require quorum approval. The following operations are selected by default and cannot be altered as these operations mandatorily require a quorum approval.
    • Security Objects
      • Rotate, Delete, Destroy, Revoke, Activate, Revert, Delete Key Material, Move, Update Operations, Update Policies, Update ProfilesUpdate Enabled State.
        • Any changes to security object metadata or state.
    • Cryptographic
      • Cryptographic Operations
        • Cryptographic operations with security objects in the group.
        WARNING
        When the Cryptographic Operations option is selected, you cannot perform any cryptographic operation on the keys inside the group without quorum approval.
      The following operations are selected by default and cannot be altered as these operations mandatorily require a quorum approval.
    • Groups
      • Update Group Configuration (Cryptographic, Quorum Policy and Key metadata Policy)
        • Adding/Updating Cryptographic Policy for a group.
        • Any changes to the existing Quorum Policy for a group.
        • Adding/Updating Key Metadata Policy
          NOTE
          Adding/Updating Users and Apps to a group is not included.
    • Plugins
      • Add, Update Plugin
        • Includes any changes to plugin code.
    GroupQuorum0.pngGroupQuorum1.png
    Figure 1: Choose operations that require quorum approval
  6. Click SAVE POLICY at the bottom of the form.
  7. You will now see a summary of the values that were added to the Quorum approval policy. Review the quorum approval details on the modal window and click SAVE to save the policy.

Update Group Quorum Policy

To update a group quorum policy:

  1. Go to the detailed view of a group and in the INFO tab, in the Quorum approval policy section click the EDIT POLICY button. 
  2. In the Quorum approval policy form, make the required changes, and click the SAVE POLICY button. 

Retain and Log Expired Quorum Approval Requests

The Quorum approval requests in the Tasks -> PENDING, COMPLETED, and FAILED tab expire after a default 30-day period. This period can be updated using the Approval requests expiration time field on the Quorum approval policy page.

To retain all the expired Quorum approval requests (pending, completed, and failed) even after their expiration, enable the Retain Expired Requests toggle.

Now go to the Tasks page, select the Show expired tasks check box to see all your expired tasks in the PENDING, COMPLETED, and FAILED tabs.

To retain the audit logs only for the pending approval requests that have expired, enable the toggle for Show audit log for any requests that have expired and have not been acted upon.

Quorum Approval

Modifying the quorum approval policy would also require quorum approval.

  • The quorum approval policy may be defined simply as the minimum number of approvals required among the total number of group administrators or applications for the group.
  • A policy may also include the specific identity of users or applications who form the quorum, and not just the size of the quorum.
  • An advanced policy could be a combination of quorum rules. For example, a quorum could be defined as “one out of users A and B”; “three out of users C, D, E, F, and G”, and "two out of Apps H, I, J, K".
  • A quorum policy may also include optional authentication methods for approval:
    • Two-Factor authentication for approval: This option can be enabled for prompting using additional authentication methods such as Yubikey or other U2F supported services during approval.
    • Password re-entry for approval: This option can be enabled for prompting the user to re-enter the password during quorum approval. 

Workflow for Quorum Approval

Whenever a sensitive operation is performed in a group enabled for quorum approval, a workflow for quorum approval is triggered.

  • This involves sending a notification to all users who can grant approval. This is done by sending an email to each quorum member, as well as generating a task in the approvers’ accounts, which they see on the dashboard as soon as they log in to their Fortanix DSM account.
  • The users can then grant approvals from the UI. The sensitive operation is blocked until the quorum is met.
  • Once the quorum is met, the operation is performed, and the event is logged including the names of users who approved the request.

Quorum10.png Figure 5: Approving quorum request

Quorum Approval Request to Update Group Quorum Policy

Since updating a quorum policy is a sensitive operation, this change in quorum policy should be approved by the administrators/applications who were part of the policy before the update. So, the original approvers/administrators will receive the following approval request to approve the new policy. The window shows what was the old policy in the Existing column and what update was made in the New column.
Click the APPROVE or DECLINE button to approve or decline the policy.

Quorum11.png Figure 6: Quorum approval for Group Policy update - diff view

In the approval window, the Existing column shows the existing state of the security object and the New column shows the updates made to the security object. A user can APPROVE or DECLINE the request.

Quorum Approval Request for Security Object Updates

When a Security Object (SO) is updated such as changing the SO name, changing the permitted SO permissions, updating the expiry date for SO, or deleting/deactivating an SO, such operations will trigger a quorum approval request such as the following:

Show_JSON.png

Figure 7: Show JSON Format

  1. In the approval window, the Existing column shows the existing state of the security object and the New column shows the updates made to the security object.
  2. Click the Show JSON button to view the approval request body in JSON format.
    Click the toggle for Enable line wrapping to fit the request body within the width of the JSON viewer.
    Toggle_Button.png
    Figure 8: Unable the Line Wrapping Toggle Button
  3. A user can APPROVE or DECLINE the request.

Quorum Approval Request for Cryptographic Policy Updates

When a cryptographic policy is updated, it triggers the following Quorum Approval request:

Quorum13.png Figure 9: Quorum approval for Cryptographic Policy update - diff view

In the approval window, the Existing column shows the existing state of the security object and the New column shows the updates made to the security object. A user can APPROVE or DECLINE the request.

Quorum Approval Request for Plugin Code Change

When you update the code for a Fortanix DSM plugin, it triggers the following quorum approval request:

Quorum14.png      Figure 10: Quorum approval for Plugin code change - diff view

In the approval window, the Existing column shows the existing state of the security object and the New column shows the updates made to the security object. A user can APPROVE or DECLINE the request.

Error Scenarios

Sometimes when an approval request fails, such as import request failure, a wrapping key does not have the “unwrap” permission, error during an approval request, or failure during the import/export operation then these “failed” scenarios are captured in the Failed tab in the Tasks page. A user will also get notified about the failed task through the alerts icon on top.

import_task_failed.png
Figure 11: Import Task Failed

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful