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
Import Key by Clear Components User Flow
This section describes the “Import Key by Clear Components” feature of Fortanix Seld-Defendning KMS. This 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 the 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 1: 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.
- Key Custodians: In this example, User3, and User4 are being selected as the users that will upload their components to Fortanix Self-Defending KMS. Any group member can be selected to be a key custodian. Either 2 or 3 users can be selected according to the number of components. You can select a minimum of 2 custodians and a maximum of 3 key custodians.
- Choose a type (SO): The type of key that is being imported.
NOTE: The allowed key types for importing key by components are AES, DES3, or DES. (in this example: AES).
- Key size: The size of the key in bits (in this example 256 bits):
- For AES, key size can be 128, 192, or 256.
- For DES3 key size can be 112 or 168.
- For DES key size can be 56.
- Key Check Value (KCV): The KCV of the imported key.
- 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 2: Add security objectOnce 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 name "Key 1" will appear (Figure 3). User3 has the option of either ADD COMPONENT or CANCEL IMPORT.
Figure 3: Add Key Component requestThe User3 can also add a key component from the Events tab-> TASKS tab -> PENDING tab -> Approval tab in the Fortanix Self-Defending KMS UI.
Figure 4: 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 key.
- The key KCV value.
- The key Clear Component value (Component).
- The Component Key Check Value.
Figure 5: 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, 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. When Fortanix Self-Defending KMS receives the component, the system checks that the Component value and Component KCV match. 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 submit them again.
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 6: Cancel ImportNOTE: Once an “Import Request” is cancelled by any of the key custodians, all other custodians will not be able to enter their key components anymore: the key will not be imported, and all the previously imported components will be destroyed. 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 as shown in section "Import Key by Clear Components User Flow".
- Once User3 has performed Steps 4-6 above to add a key component, the “Import Key by Clear Components” request now moves under the Events tab-> TASKS tab -> APPROVED tab in the Fortanix Self-Defending KMS UI.
Figure 7: 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. The “Import Key by Clear Components” request is now archived and moved under the Events tab-> TASKS tab -> ARCHIVED tab in the Fortanix Self-Defending KMS UI.
Figure 8: Import request archived
- 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, key “Key 1” is displayed in the list of objects.
Figure 9: Key successfully created by componentsThe detailed view of “Key 1" displays the key properties:
Figure 10: "Key 1" detailed view
Key KCV Match
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 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 b using the specified KEK.
- The resulting material from Step c is the final SO that is imported.
NOTE: Recombining Components:
- In case of a key that is not wrapped by a KEK, recombining components results in the original key.
- In case of a key that is wrapped with a KEK, there is the extra step of unwrapping the recombined components to get the original key back.
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.
NOTE: The administrator is given the option to select the KEK.
Figure 11: Request key component with Unwrapping key
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 group 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.
- Group auditors User3 and User 4 are selected to be the key custodians.
- The goal is to export the AES key named “Key 2” 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 2” to be exported and should click EXPORT KEY COMPONENTS. The following figure shows the detailed view of the SO Key 2.
Figure 12: Select Export
- In the “Export as Key Components” form, the administrator (User1) selects the following:
- Key custodians: They need to be members of the group that the key belongs to. The administrator creating the request can assign themselves to be one of the key custodians.
- 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 13: 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 14) that the requester User1 has created an “Export by Components” request of “Key 2”.
NOTE: The members of the quorum policy may or may not overlap with the users that have been selected as key custodians.
- 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 14: Export Request to ApproveThe Approvers can also review the export key request from Events tab-> TASKS tab -> PENDING tab -> Approval tab in the Fortanix Self-Defending KMS UI.
Figure 15: Review Export key task
- Once the quorum is achieved (For example: Approver1 and Approver2 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, one of the key custodians, navigates to his Account page and the notification is displayed.
- The Approver1 can review the export request by clicking the APPROVE button. This step must also be performed by Approver2 or Approver3 so that quorum is achieved. Once the quorum Approvers approve the “Key Export” request, the Exported component will now be available for User3 and User4 under the Events tab-> TASKS tab -> PENDING tab -> Component tab in the Fortanix Self-Defending KMS UI or in the Dashboard view.
Figure 16: View Key ComponentThe component is also visible from the Fortanix Self-Defending KMS Dashboard.
Figure 17: 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 18: Review Export Component Details
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 quorum is reached, Fortanix Self-Defending KMS wraps the key to be exported with the KEK.
- 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 18: Review Export Component Details