User's Guide: Key Components

1.0 Introduction

This article describes the key import and export functionality using the Key Components feature of the Fortanix-Data-Security-Manager (DSM). It also contains the information related to:

• Import key by Clear Components

• Import encrypted key by Components

• Export key Clear Components

• Export encrypted key Components

2.0 Setup Key Custodian Policy

A Key Custodian is a role assigned to Account Members or Account Administrators in Fortanix DSM who can only perform the following activities:

1. Provision clear (unencrypted) components for an import component operation or receive clear components from an export component operation.

2. Provision encrypted components for an import component operation or receive encrypted components from an export component operation.

A Key Custodian has the following restrictions:

1. Should exist on a group level in the Fortanix DSM.

2. Should only be assigned to handle activities related to import/export key on clear components in a particular group.

3. Can only be Account Members or Account Administrators.

2.1 Setup Key Custodian Policy

A Key Custodian policy allows an Account Member or Account Administrator to participate as a Key Custodian for a group. The Key-custodian policy must be set up with at least 2 or 3 custodians (2 is the default). Key Custodians may be account members or administrators and are required for all the key import/export component flow initiated from this group. To set up the policy:

1. Go to the detailed view of a group, and in the INFO tab click the ADD POLICY button for the Key Custodian policy.  

   

2. Next add the participating Key Custodians that are required for the import, export component operation. 

   

   The drop down shows account members, administrators, or a combination of account members and administrators.

   • When you select account members, the list displays users with Account Member roles.

   • When you select administrators, the list displays users with Administrator roles.

   • When you choose account members and administrators , the list displays uses with Account Member and Account Administrator roles.

3. Choose the people who will participate as Key Custodians and then click SAVE POLICY to save the policy.  

   

                                                      

2.2 Edit/Delete Key Custodian Policy

To delete a Key Custodian policy,

1. Go to the detailed view of the group and then in the INFO tab, under the Key Custodian policy section, click the EDIT POLICY button.

   

2. To edit the policy, In the detailed view of the Key Custodian policy make some changes to the policy and click SAVE POLICY button. To delete the policy, click the DELETE POLICY button.

   

3.0 Key Import

3.1 Import Key by Clear Components User Flow

This section describes the “Import Key by Clear Components” feature. The import key by clear component feature is explained using the following example which assumes that:

• A group called “Import Key Component Test Group” exists and has User1, and User2 as group administrators.

• User3 and User4 are group auditors.

In this example:

• User1 creates an “Import Key by Clear Components” request.

• User3 and User4 are the key custodians of a symmetric key and possess clear components.

• The goal is to import the symmetric by clear components into Fortanix DSM.

Steps

1. To add a new Security Object to the Import Key Component Test Group, the User1 clicks the ADD SECURITY OBJECT button in the group detailed view.  

   

2. In the Add New Security Objects form, fill the following details:

   • Security Object (SO) Name: This is the name that the key will have once all components are received by Fortanix DSM (in this example “Key 1”).

   • Select the IMPORT option for the "key create" operation.

   • Select the Import Key from Component check box to start the process for importing key by components.

     WARNING

     The Import Key from Components check box will be disabled if the Key Custodian policy is not set at the group level.

     

   • Key Custodians: In this example, User3, and User4 are being selected as the users that will upload their components to Fortanix DSM. The minimum number of participating Key Custodians is set in the Key Custodian Group policy. For example: When the minimum number of Key Custodians is set as 2 in the group policy, the user must select two users from the list of users at the group policy level to participate in the upload component operation.

   • Choose a type (SO): The type of key that is being imported.

     NOTE

     The allowed key types for importing keys by components are AES, DES3, DES, or HMAC. (in this example: AES).

   • Key size: The size of the key in bits (in this example 256 bits):

     • For AES, the key size can be 128, 192, or 256 bits.

     • For DES3, the key size can be 112 or 168 bits.

     • For DES, the key size can be 56 bits.

     • For HMAC, choose key size from 112 to 8192 bits

   • Key Check Value (KCV): The KCV of the imported key which is optionally added by the admin while creating the import request.

   • Key operations permitted: The operations that the key will be able to execute once it is imported. In this example, the key is given “Encrypt”, “Decrypt” and “Export” key operations.

3. Once all the parameters are selected, the group administrator (User1) clicks the SUBMIT REQUEST FOR COMPONENTS button.  

   

   

   Once the “Import Key by Clear Components” request is submitted, User3 and User4 will be notified that the request has been created and that they can submit their key components.  

4. Now when User3 opens the Account page in Fortanix DSM, under Key Components section, the request created by User1 to import a key with the name "Key 1" will appear (Figure 9). User3 has the option of either ADD COMPONENT or CANCEL IMPORT.  

   

   The User3 can also add a key component from the TASKS  tab -> PENDING tab -> Import/Export tab in the Fortanix DSM UI.  

   

5. When User3 clicks the ADD COMPONENT button, the following dialog box is displayed with the information below for User3 to review.

   • The user that has created the “Import Key by Clear Components” request.

   • The name of the imported key, that is "Key 1".

   • The type and size of the key.

   • The key KCV value. 

   The User3 should provide the following details:

   • The key Clear Component value (Component).

   • The Component Key Check Value

   

   Similarly, User4 should also perform Step 5 to add a key component.

6. Once the Component and Component Key Check Value have been entered, the user can verify if the Component value and Component KCV match using the Verify KCV link. If they do not match, an error message will be displayed indicating the mismatch. At this point, the key custodian will retype the key clear component and KCV and verify them again.   

   

7. Once the key clear component and KCV matches, User3 and User4 have to click the ADD COMPONENT button, and the component value is sent over TLS and stored securely by Fortanix DSM. 
   The users can also choose to cancel the “Import Request” by clicking the CANCEL IMPORT button. If the user decides to cancel the import operation the following confirmation window is displayed:  

   

   NOTE

   When an “Import Request” is canceled by one key custodian, other custodians will not be able to enter key components: the key will not be imported, and all the previously imported components will be destroyed. If the group administrator wants to import the key by clear components, a new “Import Key by Clear Components” request must be created as shown in section "Import Key by Clear Components User Flow".

8. Once User3 has performed Steps 4-6 above to add a key component, the “Import Key by Clear Components” request now moves under the TASKS  tab -> PENDING -> Import/Export tab in the Fortanix DSM UI.  

   

9. After all key custodians have performed Steps 4-6 and the key components are added, Fortanix DSM will recombine all clear components to produce a key with the parameters provided in Step 2. The components are stored in Fortanix DSM for as long as they are needed to recombine the key. Once the key is imported, its components are destroyed.  

   

10. When a user navigates to the Security Objects (SO) list page, the newly imported key will be shown in the list of SOs. In the following figure, the key “Key 1” is displayed in the list of objects.  

    

    The detailed view of “Key 1" displays the key properties:  

    

3.2 Key KCV Match

If the admin who created the import request optionally added the KCV, then once all the clear components are submitted and the key is recombined, Fortanix DSM checks that the resulting KCV of the recombined key matches the key KCV provided in Step 2 in Section "Import Key by Clear Components User Flow". If these two KCVs do not match, the key will not be imported, and all the submitted components will be destroyed. The result of the “Key Import” request will display an error message. If the group administrator still wants to import the key by clear components, a new “Import Key by Clear Components” request would need to be created (Step 1 in Section "Import Key by Clear Components User Flow").

3.3 Import Encrypted Key by Components User Flow

Fortanix DSM provides the option to specify a Key-Encryption-Key (KEK) which will unwrap (decrypt) the recombined key components. The Fortanix DSM process for this is:

1. Fortanix DSM waits until quorum approval is completed to import and unwrap the encrypted key material with wrapping key.

2. Once a quorum is reached, Fortanix DSM allows to unwrap the key to be imported with the KEK selected during the Export key as Components operation.

3. Fortanix DSM waits until all custodians provide their components.

4. Once all components are provided, Fortanix DSM recombines all components.

5. Fortanix DSM unwraps (decrypts) the recombined material from Step d using the specified KEK.

6. The resulting material from Step e is the final SO that is imported.

The user flow for importing an encrypted key by components is similar to the steps described in section "Import Key by Clear Components User Flow " with the following two differences:

• In Step 3, the administrator needs to select “Unwrap this key before import” check box and select the KEK (unwrapping key).

• The KEK must exist in Fortanix DSM when the “Import Encrypted Key by Components” request is created. The KEK must have “UNWRAPKEY” permissions.

The following figure shows creating an ”Import Key by Components” request with the “Unwrap this key before import” checkbox selected.

4.0 Error Scenarios

When a request fails (import request failure or the wrapping key does not have the “unwrap” permission) during the import/export operation, these “failed” scenarios are captured in the Failed tab on the Tasks page. The user will be notified about the failed task from the alert icon on top of the page.

5.0 Key Export

5.1 Export Key Clear Components User Flow

This section describes “Export Key by Components” feature of Fortanix DSM. The example assumes that:

• A key with “Export” key permissions exists in the group.

• The group has the following quorum policy: the members Approver1, Approver2, and Approver3 form a quorum group, and 2 out of the 3 member’s approvals are required to approve an operation in the group.

In this example:

• A group administrator User1 creates an “Export Key by Components” request.

• Account members/administrators User3 and User 4 are selected to be the key custodians who are assigned as one of the Key Custodians in the Key Custodian policy for the group.

• The goal is to export the AES key named “Key 1” by components so that User3 and User4 each have a component of the key.

1. First, the group administrator User1 creates an “Export Key Components” request by navigating to the detailed view of the key “Key 1” to be exported and should click EXPORT KEY. The following figure shows a detailed view of the SO "Key 1".

   WARNING

   The Export Key button will be disabled if the Key Custodian policy is not set at the group level.

   

   

2. In the “EXPORT KEY” form, the administrator (User1) selects the AS COMPONENT radio button and provides the following details:

   • Key custodians: They need to be members of the Key Custodian group policy set at the group level. The administrator creating the request can assign themselves to be one of the key custodians in the group policy. The minimum number of participating Key Custodians is set at the Key Custodian Group policy. For example: When the minimum number of Key Custodians is set as 2 in the group policy, the user can select any two users from the group policy level to receive the key component. 

   • ADD COMMENT (optional): The administrator can provide a short message describing the context or justification for this request.

   • Wrap key before export: Select if the key should be wrapped before being exported (See Section "Export Encrypted Key Component User Flow"). 

   

3. Once the key custodians are selected, the administrator clicks the SUBMIT EXPORT REQUEST to submit the export request.

4. Once the “Export by Components” request Is created, a quorum approval request will be sent to those group members that form part of the group quorum policy. In this example, Approver1, Approver2, and Approver3 will receive a notification (Figure 24) that the requester User1 has created an “Export by Components” request of “Key 1”.

   NOTE

   The members of the quorum policy may or may not overlap with the users that have been selected as key custodians.

5. The following figure shows Approver1’s account page, where the “Export Key by Components” request is shown. At this point, Approver1 can approve or decline the request.  

   

   The Approvers can also review the export key request from TASKS   tab -> PENDING tab -> Approval tab in the Fortanix DSM UI.  

   

6. The Approver1 can review the export request by clicking the APPROVE button.  

   

7. This step must also be performed by Approver2 or Approver3 so that quorum is achieved.

8. Once the quorum is achieved, the key custodians will receive a notification that a key component was granted to them. In this example, when the export request is approved, and when one of the key custodians (example: User3), navigates to the Account page, a notification is displayed.

9. Once the quorum Approvers approve the “Key Export” request, the Exported component will now be available for User3 and User4 under the TASKS  tab -> PENDING tab -> Import/Export tab in the Fortanix DSM UI.  

   

   The component is also visible from the Fortanix DSM Dashboard.  

   

10. Any Approver can cancel the export operation by clicking the DECLINE button. At this point, the “Export by Components” request is declined, and key custodians will not receive the key components. This state is final; once a request is declined by a reviewer, it cannot be approved even if other approvers approve the request.

11. By clicking the VIEW COMPONENT link, the user will be displayed with the export request details and the key component data they own:  

    

    NOTE

    The key component value is displayed ONLY once when a key is exported as a component. It is recommended that the user note the component value by writing it or printing it.  

    

5.2 Export Encrypted Key Component User Flow

Fortanix DSM provides the option to specify a KEK that wraps the exported key and then split the key into components parts. The process on Fortanix DSM is:

1. Wait until quorum approval is reached.

2. Once a quorum is reached, Fortanix DSM wraps the key to be exported with the KEK selected during the Export key as Components operation. 

3. Fortanix DSM splits the wrapped material from Step b into components.

4. The generated components from Step c are made available to the corresponding custodians.

Exporting Encrypted Key in components user flow is similar to the flow described in the previous section "Export Key Clear Components User Flow", with the following two differences:

• In Step 1 of Section "Export Key Clear Components User Flow", the administrator (User1) needs to select “Wrap key before export” check box and select the KEK.

• The KEK must exist in Fortanix DSM when the “Export Key by Components” request is created. The KEK must belong to the same group as the key that is to be exported and have the “WRAPKEY” permissions.

The following figure shows creating an “Export Key by Components” request with the “Wrap key before export” check box selected. Note that the administrator is given the option to select the KEK.