You can export the key share for a given key from a Builder Vault MPC node using this:

ctx := context.Background()
includePresigs := false
wrappedKeyShare, err := clients.ECDSA().ExportKeyShare(ctx, keyID, includePresigs, wrappingKey)

This returns the key share, along with additional meta data such as the key ID, all wrapped by the provided wrapping key. The wrapping key must be a DER encoded ASN.1 SubjectPublicKeyInfo (see RFC 5280, Section 4.1). You can choose whether or not to include any existing presignature shares for the given key in the exported data. If included, the presignature shares will be deleted from the MPC node.

Similarly to export, you can import a wrapped key share into an MPC node as follows:

restoredKeyID, err := client.ECDSA().ImportKeyShare(ctx, wrappedKeyShare)

When imported, the node will return the key ID of the key. This will be the same key ID as the key had when the key share was exported.

The provided key share must be wrapped using the wrapping key of the MPC node. You can obtain the node's wrapping key by calling:

wrappingKey, err := client.WrappingKey().WrappingKey(context.Background())

📘

Key import/export versus key share import/export

Builder Vault has two kinds of import/export that should not be confused, though they have somewhat overlapping use cases:

(1) Key import/export (described previously). These are MPC operations that require all MPC nodes to interact with each other. The main use case for this is import of an entire key into Builder Vault, out of Builder Vault, or between two Builder Vault instances.

(2) Key share import/export (described here). This is a local operation on a single MPC node, that does not require communication with the other MPC nodes. The main application for this is to generate a backup of the key share held by a single MPC node, e.g. a node running on a mobile device.

Use Cases

Backup

The main use case for import and export of a key share is to create a backup of the key share held by an MPC node, such that the key share can later be restored on the node from the backup. This could for example allow recreating a node on a new mobile device, if the original mobile device was lost.

📘

Correct use of wrapping key for backup

The output of ExportKeyShare is encrypted using the provided wrapping key. If you use the output as a way to back up the key share of a node, it is important that you either:

(1) Make sure that the private wrapping key is available when you want to restore. You can for example keep the private wrapping key in a protected environment such as an HSM. The benefit of this is that the backup is not sensitive and can be stored and replicated anywhere.

(2) Alternatively, you can use a "dummy" wrapping key and unwrap the exported data immediately after you have called ExportKeyShare. This gives you the raw, unencrypted, key share backup. You then need to store this in a secure way. The benefit of this is that you can recover using only the backup.

Note that this is only one of several ways of backing up with Builder Vault, as explained here. But using ExportKeyShare and ImportKeyShare, as explained here, is a simple way to back up an individual share of a key, without the need to run an MPC session involving the other MPC nodes.

The additional metadata stored in the backup increases the size of the backup. There are several ways to handle the backup; a couple of them are:

• Create a QR code containing the backup data to be saved securely outside the phone. Restoring is just a matter of scanning the QR code. This will require access to printers from the phone to get the QR code printed, and the printout should not be left in the printer unattended as it contains the key share.
• Create a symmetric AES key (16-32 bytes) and encrypt the backed-up data. The user can then store or memorize the AES key, e.g., using BIP39, or write down the hex or base64 encoding. The encryption of the backed-up data can then be stored in some central server, as the only one who can decrypt it will be the user who knows the AES key.

These are just a couple of examples of how the backup can be handled safely for inspiration, but many other solutions will solve the problem just as well.

📘

Key Share Backup and Key Resharing

Care must be taken if you use key share backup together with our key resharing feature. If you restore a key share on a single MPC node from an old key share backup that was created in an earlier reshare epoch, this will make the entire key unavailable, since the key shares on the MPC nodes are then no longer related.

The solution is to either avoid using local key share backup with resharing, or to make sure that you take a new share backup after each reshare operation.

From Hot to Cold Keys

Key share export and import can also be used for other use cases. Consider for example a multi-tenant setup with many instances of MPC node 1, each instance running on its own customer mobile devices. There is also a single MPC node 2 running that is always online, running on a server connected to the Internet. Finally, there's another instance of node 2 that is "cold" in the sense that it runs in a protected environment disconnected from the Internet. At any point in time, a customer's mobile device and the online server can run an MPC session to generate a key and some presignatures. At some later point in time, we can now make the key "cold". This can be done by exporting the key share (and corresponding presignature shares) from the online server, importing the share into the cold node, and finally deleting the key share from the online server. Using key share export, this can be done even when the mobile device is not online.

Code Example

A code example showing how to use key share export/import for backing up a key share from one of the MPC nodes is available in our demo repository (Go, Java, node.js).