User's Guide: Security Controls for Fortanix Self-Defending KMS Applications

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.

1. The following image shows App1 being included in Group1 and Group2.

   
   

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

   
   

    NOTE: By default, an app has all the possible permissions. 

Example of App Permissions

• An App with permission to perform encryption but not decryption in Group1.
  1. Create Key1 in Group1 with “Encrypt” and “Decrypt” permissions.

     
     

  2. Now, create App1 in Group1 with “Encrypt” permission.

     
     

     With this setup, App1 will be able to perform encrypt operations using Key1 but all other types of operations on Group1 will be forbidden.

  3. Create App2 with “Encrypt” and “Sign” operations.

     
     

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

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.

 NOTE: For the above derive operation, Key A should also have the “DeriveKey” permission set so that App1 can derive from it.

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.

 NOTE: For the above wrap operation, Key A should also have the “WrapKey” permission and Key B should have the “Export” permission for App1 to use it for the wrap operation.

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:
  1. 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
  2. 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
• Application detailed view page:
  1. 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
  2. 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

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:

1. “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.
2. “Approved”: The approval request has reached quorum and getting the request will give the result of the request operation.
3. “Denied”: A user of the quorum group has denied the operation.
4. “Failed”: The operation has achieved quorum, but the operation requested fails. For example: the data provided for encryption has an invalid format.

 NOTE: The states “Approved”, “Denied” and “Failed” are final states.

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:
  1. Members: Administrator 1 & Administrator 2
  2. Two administrators must approve
• Rule 2:
  1. Members: Administrator 3 & Administrator 4
  2. 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:

1. Specifying the exact number of quorum groups that are needed to achieve quorum for an operation.
2. 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:

1. Operation: URL path to the operation to be performed/approved.
2. Method: Corresponding HTTP method for the operation to be performed/approved.
3. 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"
  }
}