This article describes the key import and export functionality using the Key Components feature of the Fortanix Self-Defending KMS. 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
Setup Key Custodian Policy
A Key Custodian is a role assigned to Account Members or Account Administrators in Fortanix Self-Defending KMS who can only perform the following activities:
- Provision clear components for an import component operation or receive clear components from an export component operation.
- Provision encrypted components for an import component operation or receive encrypted components from an export component operation.
A Key Custodian has the following restrictions:
- Should exist on a group level in the Fortanix Self-Defending KMS.
- Should only be assigned to handle activities related to import/export key in clear components in a particular group.
- Can only be Account Members or Account Administrators.
Setup Key Custodian Policy
A Key Custodian policy allows an Account Member or Account Administrator to participate as Key Custodian for a group. The Key-custodian policy can be set to at least 2 or 3 custodians (2 being the default) who are account members or administrators and are required for all the key import/export component flow initiated from this group. To set up the policy:
- Go to the detailed view of a group, and in the INFO tab click the ADD POLICY button for the Key Custodian policy.
Figure 1: Add Key Custodian Policy
- Next add the participating Key Custodians that are required for the import, export component operation.
Figure 2: Add key Custodians
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.
- Choose the people who will participate as Key Custodians and then click SAVE POLICY to save the policy.
Figure 3: Save policy
Edit/Delete Key Custodian Policy
To delete a Key Custodian policy,
- 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.
Figure 4: Edit policy
- 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.
Figure 5: Edit or delete a policy
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 Self-Defending KMS.
- 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.
Figure 6: Add security object
- 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 Self-Defending KMS (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.
Figure 7: Import Key from Component checkbox disabled
- Key Custodians: In this example, User3, and User4 are being selected as the users that will upload their components to Fortanix Self-Defending KMS. The minimum number of participating Key Custodians is set at the Key Custodian Group policy. For example: If the minimum number of Key Custodians is set as 2 in the group policy, then the user can select any two users from the list of users who are chosen at the group policy level to participate in the upload component operation.
- Choose a type (SO): The type of key that is being imported.
- 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.
- Once all the parameters are selected, the group administrator (User1) clicks the SUBMIT REQUEST FOR COMPONENTS button.
Figure 8: Create an import key component requestOnce 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.
- Now when User3 opens the Account page in Fortanix Self-Defending KMS, 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.
Figure 9: Add Key Component requestThe User3 can also add a key component from the TASKS tab -> PENDING tab -> Import/Export tab in the Fortanix Self-Defending KMS UI.
Figure 10: Add Key Component request
- 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 key Clear Component value (Component).
- The Component Key Check Value.
Figure 11: Add Key Component valuesSimilarly, User4 should also perform Step 5 to add a key component.
- 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.
Figure 12: Key KCV Mismatch
- 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 Self-Defending KMS.
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:
Figure 13: Cancel Import
- 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 Self-Defending KMS UI.
Figure 14: Import component added by User3
- Once all key custodians have performed Steps 4-6 and added the key components, Fortanix Self-Defending KMS will recombine all the key clear components to produce a key with the parameters provided in Step 2. The components are only stored in Fortanix Self-Defending KMS as long as they are needed to recombine the key and once the key is imported its components are destroyed.
Figure 15: Import component completed by all custodians
- When the users navigate to the 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.
Figure 16: Key successfully created by componentsThe detailed view of “Key 1" displays the key properties:
Figure 17: "Key 1" detailed view
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 Self-Defending KMS 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").
Import Encrypted Key by Components User Flow
Fortanix Self-Defending KMS provides the option to specify a Key-Encryption-Key (KEK) which will unwrap the recombined key components. The Fortanix Self-Defending KMS process for this is:
- Fortanix Self-Defending KMS waits until quorum approval is completed to import and unwrap the encrypted key material with wrapping key.
- Once a quorum is reached, Fortanix Self-Defending KMS allows to unwrap the key to be imported with the KEK selected during the Export key as Components operation.
- Fortanix Self-Defending KMS waits until all custodians provide their components.
- Once all components are provided, Fortanix Self-Defending KMS recombines all components.
- Fortanix Self-Defending KMS unwraps (decrypts) the recombined material from Step d using the specified KEK.
- 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 Self-Defending KMS 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.
Figure 18: Request key component with Unwrapping key
Figure 19: Quorum approval for import and unwrap encrypted key
Sometimes when a request fails, such as import request failure, a wrapping key does not have the “unwrap” permission, failure during the import/export operation these “failed” scenarios are captured in the Failed tab in the Tasks page. A user will also get notified about the failed task through the alerts icon on top.
Figure 20: Import Request failed
Figure 21: Error detailed view
Export Key Clear Components User Flow
This section describes “Export Key by Components” feature of Fortanix Self-Defending KMS. 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 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.
- 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".
Figure 22: Key Custodian policy not set
Figure 23: Select Export
- 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: If the minimum number of Key Custodians is set as 2 in the group policy, then the user can select any two users from the list of users who are chosen at the group policy level to participate 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").
Figure 24: Submit Export Request
- Once the key custodians are selected, the administrator clicks the SUBMIT EXPORT REQUEST to submit the export request.
- 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”.
- 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.
Figure 25: Export Request to ApproveThe Approvers can also review the export key request from TASKS tab -> PENDING tab -> Approval tab in the Fortanix Self-Defending KMS UI.
Figure 26: Review Export key task
- The Approver1 can review the export request by clicking the APPROVE button.
Figure 27: View Key Component
- This step must also be performed by Approver2 or Approver3 so that quorum is achieved.
- Once the quorum is achieved (For example: Approver1 and Approve 2 have approved the export request), the key custodians will receive a notification that a key component has been granted to them. In this example, once the export request is approved, User3, who is one of the key custodians, navigates to their Account page and the notification is displayed.
- 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 Self-Defending KMS UI.
Figure 28: View Key ComponentThe component is also visible from the Fortanix Self-Defending KMS Dashboard.
Figure 29: View Key Component
- 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.
- By clicking the VIEW COMPONENT link, the user will be displayed with the export request details and the key component data they own:
Figure 30: Review Export Component Details
Figure 31: Warning
Export Encrypted Key Component User Flow
Fortanix Self-Defending KMS provides the option to specify a KEK which will wrap the key to be exported and then split it into components. The Fortanix Self-Defending KMS flow for this process is:
- Fortanix Self-Defending KMS waits until quorum approval is reached to export and wrap the key to be exported.
- Once a quorum is reached, Fortanix Self-Defending KMS wraps the key to be exported with the KEK selected during the Export key as Components operation.
- Fortanix Self-Defending KMS splits the wrapped material from Step b into components.
- 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 Self-Defending KMS 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.
Figure 32: Wrap key before export