Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

back

CipherTrust Manager Administration

Quorums

search

Please Note:

Quorums

This feature allows an administrator to configure a system (or quorum) that can have multiple approvers for an operation. These approvers approve the operations before they can be successfully executed.

Operations Supported by Quorums

OperationAuthorized Group(s) for Approval
DeletekeyKey Admins
AddUserToGroupUser Admins
DownloadBackupKey [Root Domain Only]Restore Admins and Backup Admins
RestoreBackup [Root Domain Only]Restore Admins
DeleteDomainDomain Admins
ManagePolicyadmin
DownloadBackupKeyDomainDomain Backup Admins and Domain Restore Admins
RestoreBackupDomainDomain Restore Admins
DeleteEKMKey [For Deleting EKM Endpoints]CCKM Admins

The authorized group(s) for quorum approval associated with operations are configurable. To configure, refer to Updating Quorum Profile.

The ManagePolicy gives you a provision to enable a quorum for:

  • Creating policies

  • Deleting policies

These policies can be system policies, user policies, or quorum policies. When you activate/deactivate a quorum, a policy is created/deleted internally. If you want to bring activation/deactivation of a quorum policy under a quorum, activate the quorum on the ManagePolicy action.

Once a quorum is enabled for ManagePolicy, the activation and deactivation of a quorum for any supported operation has to go through the quorum's approval process, similar to any other policy on the CipherTrust Manager. For more details on ManagePolicy, refer to Enabling Quorum on ManagePolicy.

This feature is a technical preview for evaluation in non-production environments. A technical preview introduces new, incomplete functionality for customer feedback as we work on the feature. Details and functionality are subject to change. This includes API endpoints, UI elements, and CLI commands. We cannot guarantee that data created as part of a technical preview will be retained after the feature is finalized.

Quorum Policies

To enable the quorum for any operation, first you need to activate the quorum policy. After the quorum policy is active for an operation, a quorum gets created in a pre-active state on performing the corresponding operation. To activate a quorum policy, refer to Activating the Quorum Policy.
For more details on quorum policies, refer to Managing Quorums Policies using ksctl.

All quorum policies must be disabled before system upgrade and creating a backup. This limitation is valid as long as quorum is a technical preview feature.

Quorum Profile

It's a configuration that defines the expiration time, number of approvals, and the voter groups for a quorum.
For more details on quorum profile, refer to Managing Quorums Profiles using ksctl.

States & Life-cycle of a Quorum Request

If an administrator has configured a quorum for any operation and the user initiates that operation, then that operation is denied and leads to the creation of a quorum request.

The quorum request life-cycle is as follows:

  • The quorum is created in a pre-active state. A quorum or a quorum request can have one of these six states at a time as depicted in the below diagram.

    Quorum States

    The user/requester of this quorum must activate the quorum before any of the approvers can review the quorum request.

  • Once the quorum is in the active state, it is available to the approvers to review it. The user/requester can optionally add a reason for initiating the request while activating it.

  • When the required approvals are granted, the quorum is set to an approved state.

  • A quorum request is set to an executed state if the operation has been completed with an approved quorum.

  • A deny vote forces a quorum to be in a denied state implying that the operation can not be performed and the quorum is terminated.

In case a quorum already exists for the same operation, the status of the existing quorum is used to determine the outcome of the operation. Any approver can vote either to approve or deny a quorum request. A note can be added with the vote for additional information.

A quorum in a pre-active state is prone to an expedited expiry. It expires after 15 minutes of creation, if not activated.

Every quorum expires after seven (7) days of the creation and this leads to the termination of that quorum.

Managing Quorums Policies using ksctl

The following operations can be performed:

  • Activate the quorum policy

  • Get status of the quorum policy

  • Deactivate the quorum policy

Activating the Quorum Policy

To create a policy supporting quorum and activating the policy, run:

Syntax

1
ksctl quorum-policy activate --actions <Actions>

Example Request

1
ksctl quorum-policy activate --actions "DeleteKey"

Example Response


{
        "Policy": {
                "id": "fd6f911b-f280-492c-9eac-aed35590d530",
                "uri": "kylo:kylo:admin:policies:enablequorum-fd6f911b-f280-492c-9eac-aed35590d530",
                "account": "kylo:kylo:admin:accounts:kylo",
                "application": "ncryptify:gemalto:admin:apps:kylo",
                "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
                "createdAt": "2021-06-01T04:45:48.917228Z",
                "name": "EnableQuorum",
                "actions": [
                        "DeleteKey"
                ],
                "resources": null,
                "allow": false,
                "effect": "obligate_on_allow",
                "updatedAt": "2021-06-01T04:45:48.917228Z"
        },
        "required_approvals": 2
}

Getting Status of the Quorum Policy

To know whether the quorum policy is in active state or inactive state, run:

Syntax

1
ksctl quorum-policy status

Example Request

1
ksctl quorum-policy status

Example Response


 [
    {
        "operation": [
            "DeleteKey"
        ],
        "active": false,
        "profile": "DeleteKey requires quorum"
    },
    {
        "operation": [
            "DownloadBackupkeyDomain"
        ],
        "active": false,
        "profile": "DownloadBackupkeyDomain requires quorum"
    },
    {
        "operation": [
            "AddUserToGroup"
        ],
        "active": false,
        "profile": "AddUserToGroup requires quorum"
    },
    {
        "operation": [
            "RestoreBackupDomain"
        ],
        "active": false,
        "profile": "RestoreBackupDomain requires quorum"
    },
    {
        "operation": [
            "ManagePolicy"
        ],
        "active": false,
        "profile": "ManagePolicy requires quorum"
    },
    {
        "operation": [
            "DeleteDomain"
        ],
        "active": false,
        "profile": "DeleteDomain requires quorum"
    },
    {
        "operation": [
            "DeleteEKMKey"
        ],
        "active": false,
        "profile": "DeleteEKMKey requires quorum"
    },
    {
        "operation": [
            "RestoreBackup"
        ],
        "active": false,
        "profile": "RestoreBackup requires quorum"
    },
    {
        "operation": [
            "DownloadBackupkey"
        ],
        "active": false,
        "profile": "DownloadBackupkey requires quorum"
    }
]

The 'active' field represents whether policy is active. It returns true if the quorum policy is active and false otherwise.

Deactivating the Quorum Policy

To deactivate the already active quorum policy for any specific operation, run:

Syntax

1
ksctl quorum-policy deactivate --actions <Actions>

Example Request

1
ksctl quorum-policy deactivate

Example Response

There will be no response if quorum policy is deactivated successfully.

Enabling Quorum on ManagePolicy

Enabling a quorum on ManagePolicy brings activation/deactivation of a quorum policy under a quorum. It implies that you won't be able to activate/deactivate any quorum on your own without creating a quorum for that request.

Now, let's assume a scenario, where you want to activate a quorum for the "DeleteKey" operation. To do so, run the following command:

1
ksctl quorum-policy activate --actions "DeleteKey"

Example Response


{
        "Policy": {
                "id": "fd6f911b-f280-492c-9eac-aed35590d530",
                "uri": "kylo:kylo:admin:policies:enablequorum-fd6f911b-f280-492c-9eac-aed35590d530",
                "account": "kylo:kylo:admin:accounts:kylo",
                "application": "ncryptify:gemalto:admin:apps:kylo",
                "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
                "createdAt": "2021-06-01T04:45:48.917228Z",
                "name": "EnableQuorum",
                "actions": [
                        "DeleteKey"
                ],
                "resources": null,
                "allow": false,
                "effect": "obligate_on_allow",
                "updatedAt": "2021-06-01T04:45:48.917228Z"
        },
        "required_approvals": 2
}

If you want to deactivate the above generated quorum, use the following command:

1
ksctl quorum-policy deactivate "DeleteKey"

However, if a quorum is enabled on ManagePolicy, you cannot activate/deactivate any quorum.

Now, let's consider a scenario where you have enabled a quorum on ManagePolicy. To do so, run the following command:

1
ksctl quorum-policy activate --actions ManagePolicy

Example Response


{
    "Policy":{
        "id":"16118020-afdf-486d-b233-991426cb4dfe",
        "uri":"kylo:kylo:admin:policies:managepolicy-requires-quorum-16118020-afdf-486d-b233-991426cb4dfe",
        "account":"kylo:kylo:admin:accounts:kylo",
        "application":"ncryptify:gemalto:admin:apps:kylo",
        "devAccount":"ncryptify:gemalto:admin:accounts:gemalto",
        "createdAt":"2022-06-14T11:12:02.146817Z",
        "name":"ManagePolicy requires quorum",
        "actions":[
            "CreatePolicy",
            "DeletePolicy"
        ],
        "resources":null,
        "allow":false,
        "effect":"obligate_on_allow",
        "updatedAt":"2022-06-14T11:12:02.146817Z"
    },
    "required_approvals":3
}

Now, if you try to deactivate the quorum for "DeleteKey" created above, an error is thrown as shown below and the deactivation of quorum is not allowed.

1
ksctl quorum-policy deactivate --actions "DeleteKey"

Example Response

1
2
3
4
5
{
    "code": 4,
    "codeDesc": "NCERRInsufficientPermissions",
    "message": "A Quorum has been created with ID (fd6f911b-f280-492c-9eac-aed35590d530) in pre-active state. Please activate it."
}

Managing Quorums using ksctl

The following operations can be performed:

  • Activate quorum

  • Approve quorum

  • Deny quorum

  • List/Search quorums

  • Get quorum

  • Delete quorum

  • Revoke vote

Activating Quorums

To activate a quorum, run:

Syntax

1
ksctl quorum activate --id <QuorumId> --quorum-reason <Reason-to-activate>

It changes the state of the quorum from pre-active to active. A quorum can be approved only when it is in the active state.
After quorum is active, it is available for the approval process.

Example Request

1
ksctl quorum activate --id  558622f8-bf20-4ded-9f43-e72bfaaf73a5

Example Response


{
        "id": "558622f8-bf20-4ded-9f43-e72bfaaf73a5",
        "uri": "kylo:kylo:sallyport:quorum:558622f8-bf20-4ded-9f43-e72bfaaf73a5",
        "account": "kylo:kylo:admin:accounts:kylo",
        "createdAt": "2021-05-31T07:47:27.435019Z",
        "updatedAt": "2021-06-01T05:02:49.884088Z",
        "requester_id": "local|f3ef594a-6b8f-4906-87b6-bd415762115d",
        "operation_fingerprint": "c301c3c23252fa3ff3d097e5d00c9000",
        "operation": "DeleteKey",
        "resource_uri": "kylo:kylo:vault:keys:ks-d707f2d9f313415fbc613e4bffb3ebb810f7235350824f2bbaff68668fef6c2e-v0",
        "state": "active",
        "required_approvals": 1,
        "meta": null,
        "votes": []
}

The requester of the operation is also the owner of the associated quorum. Only the requester/owner has permission to activate the associated quorum.

Approving Quorums

To approve a quorum, run:

Syntax

1
ksctl quorum approve --id <QuorumId> --note <Additional-note-for-approval>

When all the required approvals are available, then quorum moves to the approved state and you can re-initiate the associated operation.

Example Request

1
ksctl quorum approve --id  558622f8-bf20-4ded-9f43-e72bfaaf73a5

Example Response

There will be no response if quorum is approved successfully.

Denying Quorums

To deny a approval to a quorum, run:

Syntax

1
ksctl quorum deny --id <QuorumId> --note <Additional-note-for-denial>

This command moves a quorum to the denied state. This is a terminal state and quorum is unusable after deny.

Example Request

1
ksctl quorum deny --id  558622f8-bf20-4ded-9f43-e72bfaaf73a5

Example Response

There will be no response if quorum is denied successfully.

Getting List of Quorums

To get the list of quorums, run:

Syntax

1
ksctl quorum list

Example Request

1
ksctl  quorum list

Example Response


{
        "skip": 0,
        "limit": 10,
        "total": 1,
        "resources": [
                {
                        "id": "558622f8-bf20-4ded-9f43-e72bfaaf73a5",
                        "uri": "kylo:kylo:sallyport:quorum:558622f8-bf20-4ded-9f43-e72bfaaf73a5",
                        "account": "kylo:kylo:admin:accounts:kylo",
                        "createdAt": "2021-05-31T07:47:27.435019Z",
                        "updatedAt": "2021-05-31T07:47:27.431175Z",
                        "requester_id": "local|f3ef594a-6b8f-4906-87b6-bd415762115d",
                        "operation_fingerprint": "c301c3c23252fa3ff3d097e5d00c9000",
                        "operation": "DeleteKey",
                        "resource_uri": "kylo:kylo:vault:keys:ks-d707f2d9f313415fbc613e4bffb3ebb810f7235350824f2bbaff68668fef6c2e-v0",
                        "state": "pre-active",
                        "required_approvals": 1,
                        "meta": null,
                        "votes": []
                }
        ]
}

Getting Details of Quorums

To get details of a quorum, run:

Syntax

1
ksctl quorum get --id <QuorumId>

Example Request

1
ksctl quorum get --id 558622f8-bf20-4ded-9f43-e72bfaaf73a5

Example Response


{
        "id": "558622f8-bf20-4ded-9f43-e72bfaaf73a5",
        "uri": "kylo:kylo:sallyport:quorum:558622f8-bf20-4ded-9f43-e72bfaaf73a5",
        "account": "kylo:kylo:admin:accounts:kylo",
        "createdAt": "2021-05-31T07:47:27.435019Z",
        "updatedAt": "2021-05-31T07:47:27.431175Z",
        "requester_id": "local|f3ef594a-6b8f-4906-87b6-bd415762115d",
        "operation_fingerprint": "c301c3c23252fa3ff3d097e5d00c9000",
        "operation": "DeleteKey",
        "resource_uri": "kylo:kylo:vault:keys:ks-d707f2d9f313415fbc613e4bffb3ebb810f7235350824f2bbaff68668fef6c2e-v0",
        "state": "pre-active",
        "required_approvals": 1,
        "meta": null,
        "votes": []
}

Deleting Quorums

To delete a quorum, run:

Syntax

1
ksctl quorum delete --id <QuorumId>

Example Request

1
ksctl quorum delete --id  558622f8-bf20-4ded-9f43-e72bfaaf73a5

There will be no response if quorum is deleted successfully.

The requester of the operation is the owner of the associated quorum. Only the requester/owner has permission to delete the quorum.

Revoking Vote for Quorums

To revoke your vote from an already approved quorum, run:

Syntax

1
ksctl quorum revoke --id <QuorumId>

If the number of approvals falls below the required approvals, the quorum moves back to the active state.

Example Request

1
ksctl quorum revoke  --id 558622f8-bf20-4ded-9f43-e72bfaaf73a5

Example Response

There will be no response if vote is revoked successfully.

Managing Quorum Profiles using ksctl

The following operations can be performed:

  • Get quorum profile

  • List/Search quorum profiles

  • Update quorum profile

Getting Details of the Quorum Profile

To get the details of quorum profile, run:

Syntax

1
ksctl quorum-profiles get --profile-id <ProfileID>

Example Request

1
ksctl quorum-profiles get --profile-id c4a11fc1-d226-4f19-8d03-5911198e89e5

Example Response


ksctl quorum-profiles get --profile-id "61af169c-36b7-42b8-b396-284b92a52613"
{
        "id": "61af169c-36b7-42b8-b396-284b92a52613",
        "uri": "kylo:kylo:sallyport:quorum-profile:deletepolicy-requires-quorum-61af169c-36b7-42b8-b396-284b92a52613",
        "account": "kylo:kylo:admin:accounts:kylo",
        "createdAt": "2021-08-20T05:15:50.329875Z",
        "updatedAt": "2021-08-20T05:17:40.091664Z",
        "name": "DeletePolicy requires quorum",
        "required_approvals": 3,
        "voter_groups": [
                "System Admins"
        ]
}

Getting List of Quorum Profiles

To get the list of all quorum profiles, run:

Syntax

1
ksctl quorum-profiles list

Example Request

1
ksctl quorum-profiles list

Example Response


{
        "skip": 0,
        "limit": 10,
        "total": 6,
        "resources": [
                {
                        "id": "61af169c-36b7-42b8-b396-284b92a52613",
                        "uri": "kylo:kylo:sallyport:quorum-profile:managepolicy-requires-quorum-61af169c-36b7-42b8-b396-284b92a52613",
                        "account": "kylo:kylo:admin:accounts:kylo",
                        "createdAt": "2021-08-20T05:15:50.329875Z",
                        "updatedAt": "2021-08-20T05:15:50.328328Z",
                        "name": "ManagePolicy requires quorum",
                        "required_approvals": 3,
                        "voter_groups": [
                                "admin"
                        ]
                },
                {
                        "id": "8966e5c1-7f0b-4bad-b950-6f6aa57c4562",
                        "uri": "kylo:kylo:sallyport:quorum-profile:restorebackup-requires-quorum-8966e5c1-7f0b-4bad-b950-6f6aa57c4562",
                        "account": "kylo:kylo:admin:accounts:kylo",
                        "createdAt": "2021-08-20T05:15:50.326206Z",
                        "updatedAt": "2021-08-20T05:15:50.324867Z",
                        "name": "RestoreBackup requires quorum",
                        "required_approvals": 3,
                        "voter_groups": [
                                "Backup Admins",
                                "Restore Admins"
                        ]
                },
                {
                        "id": "04c9a485-dad8-4c76-8779-62a912f179f4",
                        "uri": "kylo:kylo:sallyport:quorum-profile:addusertogroup-requires-quorum-04c9a485-dad8-4c76-8779-62a912f179f4",
                        "account": "kylo:kylo:admin:accounts:kylo",
                        "createdAt": "2021-08-20T05:15:50.322876Z",
                        "updatedAt": "2021-08-20T05:15:50.321965Z",
                        "name": "AddUserToGroup requires quorum",
                        "required_approvals": 3,
                        "voter_groups": [
                                "User Admins"
                        ]
                },
                {
                        "id": "3f7d5445-c11c-4e18-8415-842a595b2cc9",
                        "uri": "kylo:kylo:sallyport:quorum-profile:downloadbackupkey-requires-quorum-3f7d5445-c11c-4e18-8415-842a595b2cc9",
                        "account": "kylo:kylo:admin:accounts:kylo",
                        "createdAt": "2021-08-20T05:15:50.319131Z",
                        "updatedAt": "2021-08-20T05:15:50.317472Z",
                        "name": "DownloadBackupkey requires quorum",
                        "required_approvals": 3,
                        "voter_groups": [
                                "Backup Admins",
                                "Restore Admins"
                        ]
                },
                {
                        "id": "3fa83307-8dc5-4d9f-be94-b25a54ffdc09",
                        "uri": "kylo:kylo:sallyport:quorum-profile:deletekey-requires-quorum-3fa83307-8dc5-4d9f-be94-b25a54ffdc09",
                        "account": "kylo:kylo:admin:accounts:kylo",
                        "createdAt": "2021-08-20T05:15:50.31489Z",
                        "updatedAt": "2021-08-20T05:15:50.313633Z",
                        "name": "DeleteKey requires quorum",
                        "required_approvals": 3,
                        "voter_groups": [
                                "Key Admins"
                        ]
                },
                {
                        "id": "95506ebb-2fde-48cd-b107-541dc599331e",
                        "uri": "kylo:kylo:sallyport:quorum-profile:deletedomain-requires-quorum-95506ebb-2fde-48cd-b107-541dc599331e",
                        "account": "kylo:kylo:admin:accounts:kylo",
                        "createdAt": "2021-08-20T05:15:50.310317Z",
                        "updatedAt": "2021-08-20T05:15:50.307507Z",
                        "name": "DeleteDomain requires quorum",
                        "required_approvals": 3,
                        "voter_groups": [
                                "Domain Admins"
                        ]
                }
        ]
}

Updating Quorum Profile

To update the quorum profile, run:

Syntax

1
ksctl quorum-profiles update --profile-id <ProfileID> --approvals <NumberOfApprovals> --voter-groups <VoterGroups>

Example Request 1

1
ksctl quorum-profiles update --profile-id 61af169c-36b7-42b8-b396-284b92a52613 --approvals 2

Example Response 1


{
        "id": "61af169c-36b7-42b8-b396-284b92a52613",
        "uri": "kylo:kylo:sallyport:quorum-profile:managepolicy-requires-quorum-61af169c-36b7-42b8-b396-284b92a52613",
        "account": "kylo:kylo:admin:accounts:kylo",
        "createdAt": "2021-08-20T05:15:50.329875Z",
        "updatedAt": "2021-08-20T05:19:32.613434Z",
        "name": "ManagePolicy requires quorum",
        "required_approvals": 2,
        "voter_groups": [
                "admin"
        ]
}

Example Request 2

1
ksctl quorum-profiles update --profile-id 61af169c-36b7-42b8-b396-284b92a52613 --approvals 2 --voter-groups 'Domain Admins,Key Admins'

Example Response 2


{
        "id": "61af169c-36b7-42b8-b396-284b92a52613",
        "uri": "kylo:kylo:sallyport:quorum-profile:managepolicy-requires-quorum-61af169c-36b7-42b8-b396-284b92a52613",
        "account": "kylo:kylo:admin:accounts:kylo",
        "createdAt": "2021-08-20T05:15:50.329875Z",
        "updatedAt": "2021-08-20T05:19:32.613434Z",
        "name": "ManagePolicy requires quorum",
        "required_approvals": 2,
        "voter_groups": [
                "Domain Admins"
                "Key Admins"
        ]
}