See more

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

  • Last updated:
  • access_time Reading time:

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

App Permissions

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
    • MacGenerate
    • MacVerify
    • Manage
    • Sign
    • Verify
    • AgreeKey
    • Export

Setting App Permissions

During App creation, a user may set the permissions on each group that App is added to.

  1. The following image shows App1 being included in Group1 and Group2.
    Audit.png
                                                 Figure 1: Adding App1 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 App's group permissions.
    Audit3.png
                                                 Figure 2: Setting App Permissions
    NOTE
    By default, an App is assigned all 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.
      app3.png
                                                   Figure 3: Setting Key1 Permissions
    2. Now, create App1 in Group1 with “Encrypt” permission.
      Audit4.png
                                                   Figure 4: Setting App1 Permissions

      With this setup, App1 is only able to perform encrypt operations using Key1.

    3. Create App2 with “Encrypt” and “Sign” operations.
      Audit5.png
                                                   Figure 5: Setting App2 Permissions
    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.

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.

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

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 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, select the square icon next to the group name. Audit.png
                                                            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. Audit03.png
                                                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. Audit1.png
                                                            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. Audit2.png
                                                Figure 9: Enable audit log permission for app

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.

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.

Quorum Approval Status

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

app6.png
                                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 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.
NOTE
The states “Approved”, “Denied” and “Failed” are final states.

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.

app7.png
                                             Figure 11: Setting Group Quorum Policy

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:

app8.png
                                             Figure 12: Pending Approval Requests

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

app9.png
                                                         Figure 13: Approval 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.

app10.png
                                                         Figure 14: Approve Pending Requests

 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.

app11.png
                                     Figure 15: 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"
  }
}

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 legacyapps-01.svgthat 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.

WARNING
These new security restrictions will not be enforced on applications that are marked “legacy”.

The following screenshots show a table view of legacy applications. Plugin1.png
                                                                        Figure 16: Legacy Applications