Overview

The Workspace Key Backup and Recovery process ensures that the two cloud key shares of your workspace’s full private key are not stored only in Fireblocks’ separate data centers. By not storing those two key shares only on Fireblocks’ servers, you maintain full control of your workspace's full private key if you need to recover your assets from your Fireblocks vault.

Workspace Key Backup and Recovery processes

Workspace Key Backup and Recovery consists of two processes:

1. Setting up and testing in a testnet workspace.
2. Executing your Disaster Recovery (DR) plan in your production workspace.

The next sections show two ways you obtain your Workspace Key Backup package, maintain it, and perform tests in your testnet workspace and then your production workspace.

Workspace Key Recovery in a testnet workspace

How to create your Workspace Key Backup (Python script) Legacy

Step 1: Set up your offline recovery equipment 

Required steps before requesting your Workspace Key Backup package by your organization:

1. Your workspace Owner must have their Fireblocks recovery passphrase readily available. If they do not remember it, they can reset it following these steps before performing the backup.
2. Set up a secure, air-gapped machine for the offline backup. We recommended an Ubuntu 18.04 or newer operating system due to its minimal reliance on third-party libraries and dependencies, making it less susceptible to compromised attempts. However, any other operating system may also be suitable if the computer remains offline and does not go online again. Additionally, consider these security measures for your machine:
   1. Make it accessible only to necessary authorized personnel.
   2. Protect it with a very strong password.
   3. Encrypt all partitions.
   4. Store it in a physical safe when you are not using it.
3. We recommend you purchase additional dedicated hardware (e.g., a USB memory stick) to securely transfer files to and from your offline machine.
4. On your offline machine, go to our Key Backup and Recovery Tool GitHub repo and follow the instructions to install and run the Fireblocks Key Backup and Recovery Tool.
5. We recommend you use a physical safe to store a separate keypair passphrase that you will create during the recovery process and use it when you perform periodic backup verifications or an actual recovery.

The recommendations described above uses up to four offline devices for a basic setup or up to seven offline devices for an advanced setup.

Basic setup

For the basic setup, the following equipment is required:

• An offline machine that you store in a safe, to hold and run three key components:
  
  • Workspace Key Backup package provided to you by Fireblocks Support. It is described in detail in Verifying your Workspace Key Backup package with Python Script.
  • Fireblocks Key Backup and Recovery Tool.
• A second offline machine or secure removable media (e.g., USB memory stick) for storing your recovery keypair, as detailed in step 2 below.
• Another offline machine, secure removable media (e.g., USB), or paper, for storing your recovery passphrase.
• A secure USB for transferring your files to and from your offline machine.

Advanced setup

Use up to three of the same offline machines used in the basic setup, but also copy all files to additional dedicated offline machines for redundancy. You can still use only one secure USB memory stick for file transfers in the advanced setup process.

Step 2: Generate your recovery keypair

The Fireblocks Key Backup and Recovery Tool uses the encryption standard AES-128, although you can use OpenSSL and use AES encryption levels AES-128, AES-196, and AES-256 instead of running it via the tool.

Your recovery keypair allows you to encrypt your two cloud key shares, and then decrypt them in an offline environment. To generate your recovery keypair, complete the steps below on your designated offline machine using command prompts. 

1. Run the Fireblocks Key Backup and Recovery Tool:

./fireblocks_key_backup_and_recovery.py 

2. Select Create a recovery keypair under the “What do you want to do?” prompt that appears, and follow the instructions.
   

By the end of this process, the recovery keypair is saved under the directory from which you are running the tool.

3. Send your recovery Public Key to your Fireblocks Console

Before starting the backup process, review the Security and Maintenance Best Practices article to understand the suggested roles.

Follow the below steps to complete the native In-house key backup process:

1. The Owner extracts the Public Key file to an online machine with access to your Console.
2. In the Fireblocks Console, the Owner goes to Settings > General > In-house key backup, then selects Create backup.

3. Select the public key file generated above > Upload key.

4. Your workspace Owner receives a confirmation email stating that they and the Admin Quorum must now verify and approve the public recovery key on the Fireblocks mobile app.
5. Your Admin Quorum is notified to approve the key using the Fireblocks mobile app. If they do not approve it within 48 hours you must restart this process. 
6. While the request is pending approval, selecting the yellow Awaiting approval badge shows the remaining approval requests and which Admins can still approve them.

7. If you have not run the Fireblocks Key Backup and Recovery Tool yet, do so now by using the below command. Make sure you have completed the prerequisite setup steps before using the tool.
   ./f./fireblocks_key_backup_and_recovery.py
   
   On the screen you see four options under the first prompt: "What do you want to do?"
   

8. Select option 2 - Verify the public backup key (for self-service backups). (The purpose of this step is for the Admin Quorum to verify that the public key generated in the tool is the same as the one the Admin Quorum sees in their mobile app.) 
9. Enter the public key file name created above.
10. Select the verification method: If the Admin Quorum performing the verification is near the offline machine, you can select option (a), otherwise select option (b):
    
    
    1. If Display a scannable public key QR code is selected:
       
       1. A file named pub_key_qr.png is generated and opens automatically.
          
    2. If Obtain a public key short phrase is selected:
       
       
       1. An eight-character short phrase is generated and shown in the tool.
          
11. Or your Admin Quorum collaborates with the workspace Owner to verify and approve the key backup by following the prompts on the Fireblocks mobile app: 
    1. Select View > Get Started > I’m ready to approve.
       
    2. The Admin Quorum selects an approval method (either by scanning a QR code or inputting a short key) and informs the Owner. Since the Owner has access to the offline machine, they can proceed with the QR code option in the Fireblocks Key Backup and Recovery Tool, while the Admins can ask the Owner for a short key.
    3. Scan the QR code or input the short key, according to your suitable method.
    4. Once verification is successful, the Fireblocks mobile app informs you that the key has been verified.
    5. The public key appears in the Fireblocks mobile app.
       
    6. To view the public key on the offline machine, return to your Fireblocks Key Backup and Recovery Tool on the air-gapped machine and select View the public key.

If the public keys match, select Approve on the Fireblocks mobile app. Otherwise, select Deny. This may mean the Owner accidentally modified or uploaded the wrong recovery public key at some point before it was submitted to your Console.

1. 7. The Admin Quorom and Owner enter their Fireblocks mobile app PIN codes and complete biometric authorization to approve the request.
   8. The Admin and Owner enter their Fireblocks app PIN codes and complete biometric authorization to approve the request.

12. In the Fireblocks Console, the backup status updates to Awaiting completion. If any Admin selected Deny, the backup status updates to Denied.

13. After finalizing the approval process on the Fireblocks mobile app, the workspace Owner receives the encrypted kit via email, which they need to download and transfer to the air-gapped machine. 

14. Once the included instructions in the email are carried out, mark the backup as completed in your Console.
    
15. In the Console, the status updates to Completed.
    
16. You have now completed generating your in-house key backup package. Learn about verifying a recovery package here.