1.0 Introduction

Since version 3.6, {{glossary.Fortanix-Data-Security-Manager}} ({{glossary.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 {{glossary.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 resemble the "Key Operations" that can be allocated to security objects. 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
Encapsulate
Decapsulate
AgreeKey
Export

The operations that an App is allowed to perform include the "Manage" permission operation. When this operation is enabled, it enables the App to carry out the following management tasks:

Create: To allow the App to generate or import a key using /crypto/v1/keys POST/PUT API.
Copy: To allow the App to copy a key from one group to another using /copy API.
Rotate: To allow the App to rotate a key using /rekey API.
Activate: To allow the App to transition key state from preactive to active state using /activate API.
Revoke: To allow the App to deactivate or compromise a key using /revoke API.
Revert: To allow the App to revert a key to its previous state using /revert API.
Move: To allow the App to move a key from one group to another using /crypto/v1/keys PATCH API.
Update Profile: Allows an app to update the security object's name, description, custom metadata, links, and publish public key information.
Update enabled state: Allows an app to enable or disable a security object.
Update policies: Allows an app to update Key Access Junctions (KAJ) and update the security object's size during rekey operations.
Update keyops: Allows an app to update allowed key operations on the security object.
Delete key material: Allows an app to delete the security objects by calling /delete API or through scheduled deletion.
Restore External So: Allows an app to restore key material of an external security object. The external security object should have been created by copying an existing security object.
Calculate Digest: Allows an app to utilize security object to compute the digest of any arbitrary data.
Destroy: To allow the App to destroy the key using /destroy API.
Delete: To allow the App to delete the key using /crypto/v1/keys DELETE API.

2.2 Setting App Permissions

When creating an app, a user has the option to configure permissions for each group to which the app is added.

Select the groups in which you want the app to be included.
After selecting the groups for the app, click on the squares beside the group names. This action will open a new window where you can control and set limitations on the app's permissions within those groups.
NOTE
By default, an app is assigned all possible permissions.

2.3 Example of App Permissions

An app in Group1 is granted permission for encryption but not decryption. Here's the scenario:

Create Key 1 in Group1 with both "Encrypt" and "Decrypt" permissions.
Create App1 in Group1 with only the "Encrypt" permission.
In this configuration, App1 can only carry out encryption operations using Key 1.
Create App2 with "Encrypt" and "Sign" operations.
With this setup, App2 can perform encryption operations using Key1. However, despite App2 having "Sign" permission within Group1, any attempts to perform signing operations using Key 1 will fail. Key 1 has specifically disabled the "Sign" key permission. All operations, except "Encrypt" and "Sign," conducted by App2 within Group1 will be restricted.

3.0 Key Derivation

For an app to execute a "DeriveKey" operation, it must possess the following two permissions:

The "DeriveKey" permission within the group containing the key used for deriving another key.
The "Manage" permission within the group of the newly created key.

For example:

If App1 intends to generate a key using Key A from Group1 and desires the derived key to be part of Group2, then App1 must possess the "DeriveKey" permission within Group1 and the "Manage" permission within Group2.

NOTE
For the mentioned key derivation process, Key A must also be configured with the "DeriveKey" permission to enable App1 to derive keys from it.

4.0 Key Transformation

For an app to carry out a "Transform" operation, it needs to have the "Transform" permission activated at both the group and app levels.

For example:

If App1 intends to modify a key using Key A, which is part of Group1, then App1 must possess the "Transform" permission within Group1.

NOTE
For the mentioned key derivation process, Key A must also be configured with the “DeriveKey” permission to enable App1 to derive keys from it.

5.0 Key Wrapping / Unwrapping

For an app to carry out a "Wrap" operation, an App must possess the following permissions:

“WrapKey” permission within the group containing the wrapping key.
“Export” permission within the group containing the key to be wrapped.

For example:

If App1 aims to wrap Key B in Group2 with Key A in Group1, then App1 should have the "WrapKey" permission in Group1 and the "Export" permission in Group2.

NOTE
For the mentioned wrap process, Key A must be configured with the “WrapKey” permission and Key B should have the “Export” permission for App1 to use it for the wrap operation.

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:

Click the detailed view of a Fortanix DSM SaaS application.
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:

“Pending”: This is the initial state of an approval request. This state indicates that the approval process has not yet matched Quorum Policy requirements.
“Approved”: The approval request met the Quorum Policy requirements and provided the result of the request.
“Denied”: A user of the quorum group has denied the operation. It takes only one user to deny the operation.
“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.

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:

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 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 was created. Refer to the appropriate documents on how to create an security object 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, 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.

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

Can I add a Quorum approval policy for system-level log management changes in Fortanix Data Security Manager?