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.
Note
Currently, quorums are only supported for DeleteKey operation. The Key Admins is the only group authorized to approve a quorum associated with the DeleteKey operation.
Caution
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.
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-activestate. A quorum or a quorum request can have one of these six states at a time as depicted in the below diagram.
Note
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
activestate, 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
approvedstate.A quorum request is set to an
executedstate if the operation has been completed with an approved quorum.A deny vote forces a quorum to be in a
deniedstate 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.
Note
A quorum in a pre-active state is prone to an expedited expiry. It expires after 15 minutes of creation, if not activated.
Note
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
Update the quorum policy
Get details of the quorum policy
Deactivate the quorum policy
Activating the Quorum Policy
To create a policy supporting quorum and activating the policy, run:
Syntax
ksctl quorum-policy activate --approvals <Number-of-approvals> --actions <Actions>
Example Request
ksctl quorum-policy activate --actions "DeleteKey" --approvals 2
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
ksctl quorum-policy status
Example Request
ksctl quorum-policy status
Example Response
true
Updating Quorum Policy
To update the number of approvers for a policy, run:
Syntax
ksctl quorum-policy update --approvals <Number-of-approvals>
Example Request
ksctl quorum-policy update --approvals 1
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": 1
}
Note
Updating the number of approvers do not impact the already existing quorums. It only impacts the future quorums.
Getting Details of the Quorum Policy
To get the details of active quorum policies, run:
Syntax
ksctl quorum-policy get
Example Request
ksctl quorum-policy get
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": 1
}
Deactivating the Quorum Policy
To deactivate the already active quorum policy, run:
Syntax
ksctl quorum-policy deactivate
Example Request
ksctl quorum-policy deactivate
Example Response
There will be no response if quorum policy is deactivated successfully.
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
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
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": []
}
Note
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
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
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
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
ksctl quorum deny --id 558622f8-bf20-4ded-9f43-e72bfaaf73a5
Example Response
There will be no response if quorum is denied successfully.
Note
Quorum can only be denied if it has not been approved already. The approver must revoke the approval before denying the quorum.
Getting List of Quorums
To get the list of quorums, run:
Syntax
ksctl quorum list
Example Request
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
ksctl quorum get --id <QuorumId>
Example Request
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:
ksctl quorum delete --id <QuorumId>
Example Request
ksctl quorum delete --id 558622f8-bf20-4ded-9f43-e72bfaaf73a5
There will be no response if quorum is deleted successfully.
Note
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:
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
ksctl quorum revoke --id 558622f8-bf20-4ded-9f43-e72bfaaf73a5
Example Response
There will be no response if vote is revoked successfully.
