Since version 3.6, Fortanix Self-Defending Key Management Service (KMS) provides fine-grained controls that define what operations an App can perform in each group the App belongs to. In addition to the “Key Operations” that can be given to a security object, users can define a subset of operations that an App can perform in a certain group.
An application on using a security object has the following security controls:
- Quorum control
- App permissions
App Permissions
App Permission List
App permissions are almost identical to the “Key Operations” that can be assigned to Security Objects. Below are the major differences between both:
- The operations permitted for an app has the “Manage” permission operation which when set, allows an app to perform management operations such as creating, updating, deleting, and rotating a key.
- App permissions can also be added after app creation. The following is the list of possible app permissions:
- Encrypt
- Decrypt
- WrapKey
- UnwrapKey
- DeriveKey
- MacGenerate
- MacVerify
- Manage
- Sign
- Verify
- AgreeKey
- Export
Setting App Permissions
During App creation a user can set the permissions that an App has on each group it is being added to.
- The following image shows App1 being included in Group1 and Group2.
Figure 1: Adding App1 in Group1 and Group2 - After selecting the groups for the app, click the squares next to the group names as shown in Figure 1. This opens a new window as seen in Figure 2 where you can restrict the permissions that the app has in the group.
Figure 2: Setting App Permissions
Example of App Permissions
- An App with permission to perform encryption but not decryption in Group1.
- Create Key1 in Group1 with “Encrypt” and “Decrypt” permissions.
Figure 3: Setting Key1 Permissions - Now, create App1 in Group1 with “Encrypt” permission.
Figure 4: Setting App1 Permissions With this setup, App1 will be able to perform encrypt operations using Key1 but all other types of operations on Group1 will be forbidden.
- Create App2 with “Encrypt” and “Sign” operations.
Figure 5: Setting App2 Permissions - With this setup, App2 will be able to perform encrypt operations using Key1. Note that even though App2 has “Sign” permission on Group1, the sign operations using Key1 would still fail because Key1 has disabled the “Sign” key permission. All operations other than “Encrypt” and “Sign” performed by App2 on Group1 will be forbidden.
- Create Key1 in Group1 with “Encrypt” and “Decrypt” permissions.
Key Derivation
An App that performs a “DeriveKey” operation must have the following two permissions:
- “DeriveKey” permission in the group that the key used to derive another key belongs.
- “Manage” permission in the group of the newly created key.
For example:
App1 wants to derive a key using Key A that belongs to Group1 and wants the derived key to belong to Group2. Then, App1 needs to have “DeriveKey” permission in Group1 and “Manage” permission in Group2.
Key Wrapping / Unwrapping
An App that wants to perform a “Wrap” operation must have:
- “WrapKey” permission in the group that the wrapping key belongs to.
- “Export” permission in the group that the wrapped key belongs to.
For example:
App1 wants to wrap Key B in Group2 with Key A in Group1. Then, App1 must have “WrapKey” permission in Group1 and “Export” permission in Group2.
Enabling Audit Log Permission for Applications
You can allow applications to access audit logs by configuring them in the below UI screens:
- Add application page:
- When you create a new application, and assign the application to a group, select the square icon next to the group name.
Figure 6: Enable audit log permission for app
- In the “Set app permissions for objects in the group” window, select the check box Allow access to audit log to enable audit log access for the application.
Figure 7: Enable audit log permission for app
- When you create a new application, and assign the application to a group, select the square icon next to the group name.
- Application detailed view page:
- To enable an application to access the audit log from the detailed view of an application, go to the application detailed view and click the app permission square next to the group name.
Figure 8: Enable audit log permission for app
- In the “Set app permissions for objects in the group” window, select the check box Allow access to audit log to enable audit log access for the application.
Figure 9: Enable audit log permission for app
- To enable an application to access the audit log from the detailed view of an application, go to the application detailed view and click the app permission square next to the group name.
Quorum Approval
Quorum Approval is a Fortanix Self-Defending KMS feature to add an extra layer of control and protection to the operations performed by or done on Security Objects and Plugins. As an example, by setting a “Quorum Approval” policy on a group, cryptographic operations such as “signing” require the approval of a certain number of members in the group before it can be performed.
“Quorum Approval” policy is set on a group basis and it affects all the SOs that belong to that group.
Quorum Policy
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 Approval Status
The following diagram shows the states of a quorum approval request:
Figure 10: Quorum Approval Request States
Quorum approvals can be in one of the following states:
- “Pending”: This is the initial state of an approval request. This state means that the approval has not reached the necessary quorum (according to quorum group policy) yet.
- “Approved”: The approval request has reached quorum and getting the request will give the result of the request operation.
- “Denied”: A user of the quorum group has denied the operation.
- “Failed”: The operation has achieved quorum, but the operation requested fails. For example: the data provided for encryption has an invalid format.
Usage Example
In the following example, a group with a quorum policy is created. Then, a quorum approval request for encrypting data is created. Once administrators approve the operation and quorum is achieved, the requester can perform the operation and perform the encryption.
In the following example “Quorum Group” is created with two Quorum Policy rules:
- Rule 1:
- Members: Administrator 1 & Administrator 2
- Two administrators must approve
- Rule 2:
- Members: Administrator 3 & Administrator 4
- One member must approve
The quorum policy is that any of the Policy rules is enough for acquiring quorum.

The group can also be created using the following API request:
POST https://{{server}}/sys/v1/groups
Request body:
{
"name": "Quorum Group",
"description": "Group with quorum policy",
"acct_id": "{{acct_id}}",
"approval_policy": {
"quorum": {
"n": 1,
"members": [
{
"quorum": {
"n": 2,
"members": [
{
"user": "{{admin1}}"
},
{
"user": "{{admin2}}"
}
],
"require_2fa": false,
"require_password": false
}
},
{
"quorum": {
"n": 1,
"members": [
{
"user": "{{admin3}}"
},
{
"user": "{{admin4}}"
}
],
"require_2fa": false,
"require_password": false
}
}
]
}
}
}
As it can be seen in the JSON object above, a quorum policy composed of multiple rules maps to a list of quorum objects. The parameter “n” specifies the number of users needed to obtain quorum. Using the API directly provides the following additional operations:
- Specifying the exact number of quorum groups that are needed to achieve quorum for an operation.
- Adding users in quorum groups that are group members. The Web UI only allows to add users to quorum groups that are group administrators since it is recommended that administrators are only able to approve sensitive operations.
In the example we assume that an App will create the approval request to encrypt data and a SO has been created (please refer to the appropriate documents on how to create a SO and an App).
If the App sends a request to the backend to perform a crypto operation it will fail with a HTTP Error 403 – Forbidden and the message “This operation requires approval”. For example:
POST https://{{server}}/crypto/v1/keys/{{symm_key_uuid}}/encrypt
Request body:
{
"alg": "AES",
"mode": "KW",
"plain": "VGhpcyBpcyBteSBzZWNyZXQ="
}
The operations fails with error “403 - Forbidden” and the message “This operation requires approval”.
Approval requests are created by sending a POST request to /svs/v1/approval_requests.
An approval request body contains the following three fields:
- Operation: URL path to the operation to be performed/approved.
- Method: Corresponding HTTP method for the operation to be performed/approved.
- Body: Object with the required parameters to perform the operation. This would be identical to the request body that would be provided to a request to the URL in the “operation” field.
For example, for a quorum approval request to encrypt plain text using an AES with Key Wrap (KW) mode is:
POST https://{{server}}/sys/v1/approval_requests
Request body:
{
"method":"POST",
"operation":"/crypto/v1/keys/{{symm_key_uuid}}/encrypt",
"body":{
"alg": "AES",
"mode": "KW",
"plain": "VGhpcyBpcyBteSBzZWNyZXQ="
}
}
Response:
{
"acct_id": "b280ef77-0ba1-4880-8f34-3196ea12ba5e",
"approvers": [],
"body": {
"alg": "AES",
"mode": "KW",
"plain": "VGhpcyBpcyBteSBzZWNyZXQ="
},
"created_at": "20191205T203648Z",
"expiry": "20200104T203648Z",
"method": "POST",
"operation": "/crypto/v1/keys/d9cbf11b-a154-4aca-8598-d6c569582b20/encrypt",
"request_id": "e7a7cac9-d1d4-4082-b337-49e1483aa528",
"requester": {
"app": "17551f75-86bc-462c-a241-b63dea2449d7"
},
"reviewers": [
{
"user": "a8f31cfa-9b55-46eb-8c05-6961ebd62cc5"
},
{
"user": "379cea5c-6c10-40c3-bc78-7fba347805f3"
},
{
"user": "bb74bb5d-357b-47a8-9ba9-92b8f3e28b8f"
},
{
"user": "dcfbd68b-4255-467d-886f-837c3cf5789d"
}
],
"status": "PENDING",
"subjects": [
{
"sobject": "d9cbf11b-a154-4aca-8598-d6c569582b20"
}
]
}
The response lists the UUIDs of all the users that are part of quorum groups. The status field is "PENDING" since the administrators need to approve the request.
After the approval request is created, users that are part of the quorum groups will be notified that there is a “pending approval”. When the user logs into the account, the homepage of the Web UI will display a banner message like the following:

Users can also click the “Tasks” tab in the “Events” window to review the list of “pending”, “approved” and “archived” requests:

Users can also obtain a list of “approval requests” by sending an API request to the backend:
GET /sys/v1/approval_requests
Response:
[
{
"acct_id": "b280ef77-0ba1-4880-8f34-3196ea12ba5e",
"approvers": [],
"body": {
"alg": "AES",
"mode": "KW",
"plain": "VGhpcyBpcyBteSBzZWNyZXQ="
},
"created_at": "20191205T203648Z",
"expiry": "20200104T203648Z",
"method": "POST",
"operation": "/crypto/v1/keys/d9cbf11b-a154-4aca-8598-d6c569582b20/encrypt",
"request_id": "e7a7cac9-d1d4-4082-b337-49e1483aa528",
"requester": {
"app": "17551f75-86bc-462c-a241-b63dea2449d7"
},
"reviewers": [
{
"user": "379cea5c-6c10-40c3-bc78-7fba347805f3"
},
{
"user": "dcfbd68b-4255-467d-886f-837c3cf5789d"
},
{
"user": "bb74bb5d-357b-47a8-9ba9-92b8f3e28b8f"
},
{
"user": "a8f31cfa-9b55-46eb-8c05-6961ebd62cc5"
}
],
"status": "PENDING",
"subjects": [
{
"sobject": "d9cbf11b-a154-4aca-8598-d6c569582b20"
}
]
}
]
An App can get the result of this request by sending the request:
POST https://{{server}}/sys/v1/approval_requests/{{request_uuid}}/result
If the approval request is in “pending” state, the request will return HTTP error 400 - “Bad Request” and the message “request is pending”.
The administrator can approve the request by clicking the “Approve” button.

Users can also approve or decline quorum requests with the following requests:
POST https://{{server}}/sys/v1/approval_requests/{{request_uuid}}/approve
POST https://{{server}}/sys/v1/approval_requests/{{request_uuid}}/deny
Once (administrator 1 or administrator 2) or (administrator 3 and administrator 4) approve the request, the request will transition to “APPROVED” state in the Web UI and the users that approved the quorum request are displayed.

Following is the request to get the approval request:
GET https://{{server}}/sys/v1/approval_requests
Response:
[
{
"acct_id": "b280ef77-0ba1-4880-8f34-3196ea12ba5e",
"approvers": [
{
"user": "379cea5c-6c10-40c3-bc78-7fba347805f3"
}
],
"body": {
"alg": "AES",
"mode": "KW",
"plain": "k7hjmmsHZGrEnJs0mu1y1f/Y/l93bs6jT1a0kS4SDRs="
},
"created_at": "20191206T025707Z",
"expiry": "20200105T025732Z",
"method": "POST",
"operation": "/crypto/v1/keys/d9cbf11b-a154-4aca-8598-d6c569582b20/encrypt",
"request_id": "595e09a2-5987-4ad6-af92-56cdedba71e9",
"requester": {
"app": "17551f75-86bc-462c-a241-b63dea2449d7"
},
"reviewers": [
{
"user": "379cea5c-6c10-40c3-bc78-7fba347805f3"
},
{
"user": "bb74bb5d-357b-47a8-9ba9-92b8f3e28b8f"
},
{
"user": "dcfbd68b-4255-467d-886f-837c3cf5789d"
},
{
"user": "a8f31cfa-9b55-46eb-8c05-6961ebd62cc5"
}
],
"status": "APPROVED",
"subjects": [
{
"sobject": "d9cbf11b-a154-4aca-8598-d6c569582b20"
}
]
}
]
The status of the approval request is "APPROVED".
To get the result of the operation, the request is:
GET https://{{server}}/sys/v1/approval_requests/{{request_id}}/result
Response:
{
"status": 200,
"body": {
"cipher": "vcybpJfTd/gC094q5WrtfySrqesr7fySJ8TLbVSzUIA2BdVeDYNnQA==",
"kid": "d9cbf11b-a154-4aca-8598-d6c569582b20"
}
}
Legacy Applications
Applications that are created before Fortanix Self-Defending KMS version 3.16 are called Legacy applications. For backward compatibility, these legacy applications will be marked with a special icon that denotes that they are legacy applications.
Fortanix has applied new security restrictions which will be applicable for applications created in Fortanix Self-Defending KMS version 3.16 and above.
The following screenshots show a table view of legacy applications.
Figure 16: Legacy Applications