User's Guide: Security Controls for Fortanix Data Security Manager Applications

1.0 Introduction

Since version 3.6, Fortanix Data Security Manager (DSM) provides fine-grained controls that define what operations an Application (App) can perform within each group the App belongs to. In addition to the “Key Operations” that can be given to a security object, users can assign operations to a group that an App can perform.

An App using a security object has the following security controls:

• Quorum control
• App permissions

2.0 App Permissions

2.1 App Permission List

App permissions are similar to the “Key Operations” that can be assigned to Security Objects. Below are the 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 may be added after App creation. The following is a list of possible App permissions:
  • Encrypt
  • Decrypt
  • WrapKey
  • UnwrapKey
  • DeriveKey
  • Transform
  • MacGenerate
  • MacVerify
  • Manage
  • Sign
  • Verify
  • AgreeKey
  • Export

2.2 Setting App Permissions

During the app creation, a user may set the permissions for each group the app is added to.

1. Select the groups in which you want the app to be included.
2. After selecting the groups for the app, click the squares next to the group names. This opens a new window where you can restrict the app’s group permissions. 
   NOTE

   By default, an app is assigned all possible permissions. 

2.3 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 is only able to perform encrypt operations using Key1.

3. Create App2 with “Encrypt” and “Sign” operations. 
4. With this setup, App2 will be able to perform encrypt operations using Key1. Even though App2 has “Sign” permission on Group1, the sign operations using Key1 will fail because Key1 has disabled the “Sign” key permission. All operations other than “Encrypt” and “Sign” performed by App2 on Group1 will be forbidden.

3.0 Key Derivation

An app that performs a “DeriveKey” operation must have the following two permissions:

• “DeriveKey” permission on the group for the key that is used to derive another key.
• “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.

4.0 Key Transformation

An app that performs a “Transform” operation must have the following permission:

• “Transform” permission enabled at the group and app levels.

For example:

App1 wants to transform a key using Key A that belongs to Group1 then, App1 needs to have “Transform” permission in Group1.

5.0 Key Wrapping / Unwrapping

An App that wants to perform a “Wrap” operation must have:

• “WrapKey” permission on the group that has the wrapping key.
• “Export” permission on the group that has the wrapped key.

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.

6.0 Application Usage Reporting in Fortanix DSM SaaS

You can track the usage of a Fortanix DSM SaaS application using the USAGE tab in the detailed view of the application. This tab lists all the crypto operations that the app performed in a particular month along with the date when the operation was performed. To access the USAGE tab:

1. Click the detailed view of a Fortanix DSM SaaS application.
2. Select the USAGE tab. 
   The app can perform the following cryptographic operations:
   
   • Tokenization: Tokenize and detokenize operations, that is, Encrypt or Decrypt in format-preserving encryption (FPE) mode.
   • Secret: Export operation.
   • General: Rest of the operations, that is, Encrypt, Decrypt, WrapKey, UnwrapKey, Sign, Verify, MacGenerate, and others.

7.0 Enabling Audit Log Permission for Applications

You may allow Apps to write to access audit logs by using the configuration in the below UI screens:

• Add application page:
  1. When you create a new application and assign the application to a group, click the squares icon next to the group name.  
  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. 
• 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 icon next to the group name.
  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. 

8.0 Quorum Approval

Quorum Approval is a Fortanix DSM feature that provides an additional 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.

8.1 Quorum Policy

A Quorum Policy is composed of one or more rules. The following are the options for a Quorum Policy rule:

• 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 whether “all” or “any” of the Quorum Policy rules are required to approve the requested operation.

8.2 Quorum Approval Status

The following diagram shows the states of a quorum approval request:

Figure 1: 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 indicates that the approval process has not yet matched Quorum Policy requirements.
2. “Approved”: The approval request met the Quorum Policy requirements and provided the result of the request.
3. “Denied”: A user of the quorum group has denied the operation. It takes only one user to deny the operation.
4. “Failed”: The requested operation 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. Afterwards, a quorum approval for data encryption is requested. When a quorum is achieved, the requester can perform the encryption operation.

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
           }
        }
      ]
    }
  }
}
 

In the JSON object above, a Quorum Policy with multiple rules is mapped to a list of quorum objects. The parameter “n” specifies the number of users needed to obtain a 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 adding Group Administrators to quorum groups. It is recommended that administrators approve sensitive operations.

In the example, assume that an App will create the approval request to encrypt data, and a Security Object (SO) was created. please refer to the appropriate documents on how to create an 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, the below is 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.

Figure 2: Users who Approved Quorum Requests

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"
  }
}
 

8.3 Legacy Applications

Applications that are created before Fortanix DSM 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 DSM version 3.16 and above.