Skip to main content

How to Export, Backup, and Recover Keys

There are two broad use cases for controlling one's keys:

  • Full Self-Sovereignty: To take full control of a wallet, users can Export Keys out of a WaaS wallet and into a traditional self-custody wallet (CB Wallet, Metamask, etc.).

  • Add or replace a device: To add or restore an existing wallet on a new device, users can Backup Keys (after creating a wallet), and Recover Keys on a new device when necessary.

Refer to the FAQ

See the FAQ for specific questions about security and access.

Export Keys​

Not MPC-secure

Exporting keys is not an MPC-secure action. When a user exports keys, the key shares are combined, negating the security benefits of MPC. To export safely, Coinbase recommends users do so in airplane mode, disconnected from the internet, to keep private keys offline.

WaaS lets users export their full private keys, as a "device archive", out of a WaaS-controlled wallet without any interaction with Coinbase or any other entity.

After the MPC signing shares are generated, both the user share and the Coinbase share are encrypted (separately) to a series of keys stored in the device’s secure enclave. These keys, referred to as a device archive, are securely stored on the mobile device and protected by biometrics and a unique user-defined passcode set when bootstrapping the device.

To export full private keys, a user submits their biometrics and device passcode, at which point the WaaS SDK decrypts each key share, combines the key shares, and surfaces the private key to the user.

Export Enabled by Default​

The ability to export a backup key is enabled by default for MPC Wallets created using the CreateMPCWallet API.

The encrypted backup (referred to as device archive) is protected by a unique user-defined passcode when bootstrapping the device and the device’s biometric authentication.

Preparing a Device Archive for "Existing" Wallets​

caution

This section only pertains to wallets that were created without CreateMPCWallet -- that is, wallets created during the Public Preview (before the GA release), or wallets restored from older device using AddDevice API.

Unlike new wallets (created after GA), existing wallets need to manually generate the device archive to enable key export. This section explains how to prepare a device archive for existing wallets.

  1. Call PrepareDeviceArchive (API) to create an encrypted cryptographic key in the local storage for a given Device/MPCWallet pair or Device/MPCWallet pair. The archive contains cryptographic materials that can be used later to export the private keys.

  2. Invoke ListMPCOperations from the SDK to poll for the pending PrepareDeviceArchive operation.

  3. Complete the MPC operation with the WaaS SDK API, computePrepareDeviceArchiveMPCOperation.

  4. Retrieve your private keys:

    a. Call GetDeviceGroup to get mpcKeyExportMetadata from the response.

    b. In airplane mode, call the WaaS SDK API, exportPrivateKeys.

    info

    Airplane mode is optional but Coinbase highly recommends user’s make this request offline to protect the confidentiality of the private keys.

    Result: Green Check You can now import your keys into any self-custodial wallet.

Backup Keys​

Backup & Recovery are MPC Safe

Key Backup & Recovery adhere to the WaaS MPC security posture, maintaining the security benefits of MPC.

WaaS lets users:

  • Safely backup their private keys to protect against device theft or loss.
  • Restore their keys on a separate device.

During WaaS key backup, an MPC-based encryption and decryption keypair is generated between the user’s device and Coinbase. Both key shares are encrypted with this new MPC key and the ciphertext is stored on a Coinbase server for resilience.

The decryption share is returned to the user--Coinbase recommends that you store this share in a cloud storage location (iCloud or GDrive) only accessible to the user. The decryption share is just one of three credentials the end user must provide to successfully recover their wallet on a new device (Passcode + Biometrics are the other two).

Creating a Decryption Share​

  1. Call PrepareDeviceBackup to create the secure cryptographic material needed to restore a wallet on a new device.

  2. Invoke ListMPCOperations from the SDK to poll for the pending PrepareDeviceBackup operation.

  3. Call computePrepareDeviceBackupMPCOperation (SDK) to complete the MPC operation.

  4. Call exportDeviceBackup (SDK) to return a decryption share which the customer can determine how to store.

Securely store your decryption share

Coinbase recommends that users securely store the decryption share in a storage provider of their choice (iCloud, Google Drive, etc.).

In case of emergency

If a user’s device is lost or stolen, you can easily invalidate the MPC key shares stored on the end user device by calling the RevokeDevice API.

Recover Keys​

Backup & Recovery are MPC Safe

Key Backup & Recovery adhere to the WaaS MPC security posture, maintaining the security benefits of MPC.

WaaS lets users recover their keys in the event that they no longer have access to their original device where the WaaS wallet was created (whether lost, stolen, or replaced).

Recovery Flow​

When a user gets a new device and wants to restore access to one of their wallets, they must first download the backed up decryption key share to the new device from the cloud.

The user subsequently authenticates themselves to Coinbase using the passcode provisioned during onboarding, at which point a distributed decryption operation takes place between the user’s device and Coinbase. The result is that the user has their signing key share available on the new device, without this key share ever being made available to a Coinbase server.

Backup vs Export

To restore keys on a new device, you must have backed up the decryption key share which unlocks your encrypted key share protected by Coinbase.

Recovering Keys on a New Device​

To recover keys on a new device you must do the following:

  1. Bootstrap the device with bootstrapDevice (SDK). You call this once per device--subsequent calls are ignored. It accepts the passcode used to encrypt key material in the phone’s security module.

  2. Register the device by first calling getRegistrationData (SDK). Use the string returned by getRegistrationData to call RegisterDevice (API), which registers the device with WaaS servers.

    Provide the 6-digit passcode and key share to successfully restore the wallet on the new device.

    info

    Use the original passcode when bootstrapping the new device.

  3. Call AddDevice (API) to add the new device to the existing DeviceGroup.

  4. Invoke ListMPCOperations from the SDK to poll for the pending RegisterDevice operation.

  5. Call computeAddDeviceMPCOperation (SDK) to complete the operation.

    Result: Green Check The new device is added to the DeviceGroup as a new member, and has access to the MPC keys required to process MPC operations for this DeviceGroup. All existing Devices in the DeviceGroup remain functional. To remove the old device from the DeviceGroup, use RevokeDevice.

Was this helpful?