User's Guide: Group Quorum Policy

Prev Next

1.0 Introduction

This article describes the features of the Fortanix-Data-Security-Manager (DSM) Quorum approval policy at group-level.

The Quorum approval policy feature adds an extra layer of control and protection to sensitive operations performed in a Fortanix DSM group. For example, when you apply a Quorum approval policy to a group, operations such as exporting key require approval from a predefined number of quorum approvers before execution.

2.0 Quorum Policy

A quorum policy consists of one or more quorum policy rules. Each rule can include the following components:

  • Quorum Group: Specifies a subset of group members required to approve an operation.

  • Administrator: Specifies the minimum number of administrators who must approve the operation.

  • Application: Identifies an application authorized to approve sensitive operations for specific use cases.

  • Second-Factor Security Key:  Requires the user to authenticate using a second-factor security key to approve the request.

  • Password Re-entry: Requires the user to re-enter their password to approve the request.

The quorum policy can also define the approval condition, whether all rules must be satisfied or if approval from any one rule is sufficient to meet the quorum requirement for the requested operation.

2.1 Enable Quorum Approval Policy on Groups

A group administrator can enable a Quorum approval policy on a group. This enforces that all security-sensitive operations within the group require approval from a defined quorum of approvers.

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)

  • Update group-level metadata

  • Update/Delete Quorum approval 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

By default, plugins do not enforce the quorum policy set on a group. To ensure that a plugin operation follows the quorum approval process, use the require_approval_for function. For more information, refer to Plugins – Lua Programming Reference.

3.0 Group Quorum Approval Policy

3.1 Create a Group Quorum Approval Policy

Perform the following steps to create a group-level Quorum approval policy:

  1. Go to the detailed view of a group and in the INFO tab, locate the Quorum approval policy section and click ADD POLICY.

    Figure 1: Group-level add policy

  2. In the Quorum approval policy form, enter the details of the quorum reviewers or administrative apps required to approve sensitive operations involving security objects 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 ADVANCED to add more combinations for the Quorum approval policy (optional).

    • You can select either AND or OR to define multiple quorum approval rules:

      • AND: All rules must be met for the operation to be approved.

      • OR: Any one of the rules, if met, is sufficient for quorum approval.

  4. There are two optional check boxes:

    • Using a second-factor security key is required to approve requests: This option is auto-enabled if you enabled second-factor authentication at the account level in Settings AUTHENTICATION tab. This option is not editable.

    • Profile password re-entry is required to approve request: Enable this option to enforce password re-entry for approval requests.

  5. In the Operations that require Quorum approval section, configure which group operations should generate the quorum approval request. The group administrators can select from the following:

    • Security Objects

      • Rotate, Delete, Destroy, Revoke, Activate, Revert, Delete Key Material, Move, Update Operations, Update Policies, Update Profiles, Update Enabled State.

        • These operations involve changes to metadata or the state of a security object.

    • Cryptographic

      • Cryptographic Operations

        • Cryptographic operations with security objects in the group.

      Warning

      If you select this option, Fortanix DSM will require quorum approval for all cryptographic operations on keys in this group.

    The following operations always require quorum approval and cannot be modified:

    • Groups

      • Update Group Configuration (Cryptographic, Quorum policy, and Key metadata Policy)

        • Adding or updating the Cryptographic policy for a group.

        • Any changes to the existing Quorum approval policy for a group.

        • Adding or updating the Key metadata policy.

        NOTE

        Adding or updating users and apps to a group is not included.  

    • Plugins

      • Add, Update Plugin

        • Includes any changes to plugin code.

  6. If you have enabled the ADVANCED settings above, select either the any or all option to determine whether all or any of the conditions must be met to achieve quorum.

  7. Click SAVE POLICY at the bottom of the form.

  8. The Quorum policy dialog box displays the quorum policy summary. Review the configuration and click SAVE to apply the policy.

    Figure 2: Choose operations that require approval

3.2 Update Group Quorum Approval Policy

Perform the following steps to update a group-level Quorum approval policy:

  1. Go to the detailed view of a group and in the INFO tab, locate the Quorum approval policy section and click EDIT POLICY.

  2. In the Quorum approval policy form, update the policy as required.

  3. Click SAVE POLICY to apply the changes.

3.3 Delete Group Quorum Approval Policy

Perform the following steps to delete a group-level Quorum approval policy:

  1. Click EDIT POLICY and go to the detailed view of the Quorum approval policy.

  2. Scroll to the end of the Quorum approval policy page, click DELETE POLICY.

  3. On the Delete Policy confirmation dialog box, click DELETE to confirm the action.

    NOTE

    Deleting a Quorum approval policy is a sensitive operation and will automatically generate a quorum approval request.

4.0 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 for 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.

4.1 Workflow for Quorum Approval

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

  • 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.

Figure 3: Approving quorum request

4.2 Quorum Approval Request to Update Group Quorum Policy

Since updating a Quorum approval policy is a sensitive operation, this change in Quorum approval policy should be approved by the reviewers or administrative apps that were part of the policy before the update. So, the original reviewers or administrative apps will receive the following approval request to approve the new policy.

Figure 4: Approving an updated group quorum policy

In the Quorum approval request window, the Existing column displays the existing list of configurations and the New column shows the changes made to the group quorum policy. To proceed with the update, reviewers or administrative apps must click APPROVE. To reject the changes, click DECLINE.

4.3 Quorum Approval Request for Security Object Updates

When a security object is updated, such as changing the security object name, changing the permitted security object permissions, updating the expiry date for the security object, rotating security objects, or deleting or deactivating a security object, such operations will generate a quorum approval request.

Click the Show JSON button to view the approval request body in JSON format.

Figure 5: Show JSON format

Click the toggle for Enable line wrapping to fit the request body within the width of the JSON viewer.

Figure 6: Enable line wrapping toggle

In the Quorum approval request window, the Existing column shows the existing state of the security object, and the New column shows the updates made to the security object. To proceed with the update, reviewers or administrative apps must click APPROVE. To reject the changes, click DECLINE.

4.4 Quorum Approval Request for Cryptographic Policy Updates

When a cryptographic policy is updated, it generates the following quorum approval request:

Figure 7: Approving an updated group cryptographic policy

In the Quorum approval request window, the Existing column shows the existing cryptographic policy settings, and the New column shows the updates made to the cryptographic policy. To proceed with the update, reviewers or administrative apps must click APPROVE. To reject the changes, click DECLINE.

4.5 Quorum Approval Request for Plugin Code Change

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

Figure 8: Approving an updated group cryptographic policy

In the Quorum approval request window, the Existing column shows the existing Plugin code, and the New column shows the updates made to the Plugin code. To proceed with the update, reviewers or administrative apps must click APPROVE. To reject the changes, click DECLINE.

4.6 Error Scenarios

Sometimes, when an approval request fails, such as an 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 9: Import task failed