As of September 1, 2021, this repository will be converted to read only and support will end.
Therefore, starting on September 1, 2021, the following changes will occur:
- Unbound will stop maintenance for this repo.
- Unbound will not release any future versions of this repo.
- Unbound will not provide any security updates or hotfixes (should an issue arise).
- Unbound will stop support for this repo.
This library was originally created to enable users to experiment with MPC functionality using a subset of the functionality provided in Unbound products.
Users are encouraged to explore the new Unbound CORE offerings found in the Unbound Security website.
blockchain-crypto-mpc is an open source library released by Unbound Security that provides the cryptographic foundation to resolve one of the hardest challenges associated with crypto asset and blockchain applications: The protection of cryptographic signing keys and seed secrets.
Unbound leverages secure multiparty computation (MPC) for the protection and management of cryptographic keys and secrets, and provides industry-grade MPC-based solutions for key management, key protection and additional applications. The protocols were designed by Prof. Yehuda Lindell and Dr. Samuel Ranellucci, who also reviewed and approved the code and the implementation.
See the Unbound Cryptocurrency Wallet Library White Paper for more detailed information about the protocols.
This readme includes an overview of this library, why it is important, what it allows you to achieve, sample use cases, and how to use the library (high level description).
Blockchain Crypto MPC provides 100% of the cryptography needed for strongly securing crypto asset and blockchain wallets -- while being as or more secure than dedicated cryptographic hardware -- for free. If you're developing a wallet or a platform for custody/exchanging of crypto assets -- you're in the right place!
Leveraging MPC for the protection of cryptographic keys and secrets, blockchain-crypto-mpc provides the security benefits of no single point of compromise and shared responsibility (like Multi-Sig), but with a single signature and without any dependency on the ledger. More specifically, it provides three critical security properties:
-
Sensitive keys and secrets are split into two random shares, which are stored on separate, segregated machines ('machine' stands for any computing device). Each of these shares by itself reveals nothing whatsoever about the key material.
-
All cryptographic operations performed throughout the key lifecycle are performed without ever combining these 2 shares together. This includes signing, derivation and even generation. Bottom line -- there is no complete key material or secret in the memory, ever. It is proven mathematically that obtaining the key material requires access to both key shares, and therefore requires compromising both machines. A single machine, even if completely compromised and controlled by an attacker, reveals nothing about the key material -- simply because the key material never resides in any single machine.
-
Key shares refresh: The key shares are continually modified without modifying the key itself. It is computationally efficient and can be performed very frequently -- thus forcing the attacker to compromise both machines at virtually the same time in order to obtain key material.
blockchain-crypto-mpc includes a secure MPC implementation of 100% of the functionality required to strongly secure crypto asset and blockchain wallets. It's pure software, open-source and free to use.
It is highly recommended for developers of wallets and blockchain applications that deal with key management.
We are delighted to make this contribution to the open source community, with hopes that it will enable secure, convenient, and easy to use blockchain applications for all.
blockchain-crypto-mpc includes a secure MPC implementation of the following algorithms:
- 2-party ECDSA secp256k1: generation and signing
- 2-party EdDSA ed25519: generation and signing
- 2-party BIP32 (based on the BIP32 specification): generation, hard derivation, and normal derivation
- Key share refresh
- Zero-knowledge backup
The source code is written in C++ and the external API in C. Detailed documentation including a whitepaper and security proofs will be available online soon.
It can be compiled on virtually any platform. The only dependency is OpenSSL, which is available on most platforms. Instructions on how to remove this dependency will be included in future documentation.
The compiled binary is a cryptographic library that has to be deployed on two or more separate machines to provide strong security.
blockchain-crypto-mpc can be used to provide security in any blockchain app. In this section we describe typical use cases that are relevant to many applications.
This use case is common for wallet service providers. The user has a mobile wallet on their endpoint device, typically their mobile phone or laptop. The wallet application communicates with a server application.
The BIP32 seed and all signing keys are always split between the end user's device (participant 1) and the service provider (participant 2). Performing any cryptographic operation on the seed or private key requires cooperation of both participants (and communication between them).
- Guaranteed non-repudiation; the application server cannot sign any transaction without cooperation from the endpoint device.
- No single point of compromise: Compromising the seed or key material requires the attacker to compromise both the server and the endpoint simultaneously.
- No key or seed material ever appears in the clear throughout its lifecycle, including while in use and during generation.
- Resilient to side-channel attacks.
- A model that empowers a crypto service provider to create an excellent user experience by delivering a wallet service while maintaining a very high security level and granting the users full control of their crypto assets.
This is a use case involving two end-user devices that typically belong to the same user. For example, a mobile phone and a laptop. Each device runs an app and both participants collaborate to create a secure blockchain wallet and sign transactions.
The BIP32 seed and all signing keys are always split between the mobile device (participant 1) and the laptop (participant 2). Performing any cryptographic operation on the seed or private key requires cooperation of both participants (and communication between them).
- Both devices must collaborate and approve any transaction. No single device can approve a transaction.
- No single point of compromise: Compromising the seed or key material requires the attacker to compromise both the laptop and the mobile device simultaneously.
- No key or seed material ever appears in the clear throughout its lifecycle, including while in use and during generation.
- Resilient to side-channel attacks.
- A model that empowers a wallet provider to create an excellent user experience while maintaining a very high security level and granting the users full control of their crypto assets.
Backup is one of the most challenging aspects of crypto asset key management. This section briefly describes the backup functionality of blockchain-crypto-mpc and two potential usage scenarios.
blockchain-crypto-mpc includes a unique backup mechanism that introduces zero-knowledge backup: an encrypted cold backup that allows public verifiability. This property is significant, as it allows both participants to verify the correctness of the backup at any point in time without decrypting it. It therefore makes this verification secure and prevents a situation where a wrong backup was generated and stored.
This is a common form of backup, with the role of backup management mostly on the end-user. An encrypted backup of the wallet can be stored in multiple locations for redundancy (for example, it can be stored by the service provider as described in the Endpoint/Server use case). The private key for this backup should be in the user's sole possession, preferably in a cold backup. The backup recovery process should be used only for disaster recovery.
The following scenario is an expansion of the Endpoint/Server use case that includes a 3rd party trustee service. The trustee service is used only when either the user's device and/or the service provider have lost their respective key shares.
This model creates a user-transparent backup, effectively similar to a 2-of-3 scenario: each quorum containing 2 of the 3 participants noted above would suffice to perform a cryptographic operation. This is performed by creating three different random share pairs upon wallet and seed generation. In the diagram, key share A is used by the user's device and the Trustee Service, key share B is used by the user's device and the Wallet Service Provider, and key share C is used by the Wallet Service Provider and the Trustee Service. It's important to highlight that each of these pairs is completely independent, each is effectively a backup of the same seed.
This repository includes a two different tools for benchmarking the blockchain-crypto-mpc library.
- MPC Crypto Bench - a tool written C++. See mpc_crypto_bench in the bench folder for more information.
- MPC Crypto Python script. See mpc_crypto in the Python folder for more information.
MPC Crypto Bench tests the raw protocols, with no networking involved, while the MPC Crypto Python script is uses a client and server with actual networking.
Using the Python script, each command was run for 20 iterations and resulted in the following performance numbers:
| Algorithm | Command | Time (seconds) |
|---|---|---|
| ECDSA | Generate | 0.945 |
| ECDSA | Sign | 0.015 |
| EdDSA | Generate | 0.003 |
| EdDSA | Sign | 0.003 |
The tests were run on a server with an Intel Xeon E5-2686 v4 (2.30 GHz) with 32 GB RAM.
Unbound's Blockchain Crypto MPC open source library provides functions that enable you to create, sign, and refresh encryption keys, without the whole key ever existing in any location.
This library can be used to create system with two peers for the management of the keys. Each peer uses the library to create and process messages that are sent between the peers. Note that the actual communication between peers is not included in this library.
Blockchain Crypto MPC utilizes the following three structures:
- Key share -- Encryption keys never exist as complete keys in any phase of the process or in any location at any time. A key share is a piece of a key, which can be used by Unbound's MPC technology to sign transactions.
- Message -- Data that is passed to the other peer. The message contains information about the action in progress.
- Context -- Since each action, such as signing with a key, involves multiple messages between the two peers, the status of the action is preserved in a context.
The key share, message, and context contain varying amounts of information depending on the type action, and therefore they are structures.
The library provides the following actions:
- 2-party ECDSA secp256k1: generation and signing
- 2-party EdDSA ed25519: generation and signing
- 2-party BIP32 (based on the BIP32 specification): generation, hard derivation, and normal derivation
- Key share refresh
- Zero-knowledge backup
The library also provides mechanisms to handle serialization, deserialization, and memory management for the key share, message, and context structures.
The system flow is shown in the following figure:
The first step is initialization. During this step you provide the library with all the relevant information required to complete the desired action. This step takes that information and creates a context. Each peer does its own initialization.
The context is then passed through a series of steps. Each of these steps takes an input message, does some manipulation, and then creates an output message. You then transfer this output message to the other peer. The other peer receives the message and associates it with a context. It then knows how to handle the incoming message based on the context.
When the peer is done with the last step it sets a finished flag. The peer can then do any necessary cleanup, such as freeing memory, or copying an updated key share to storage.
Peer roles are determined by which peer initiates key generation. This peer must be used for any subsequent key operations, such as signing, derivation, and backup. For example, if peer A generates a key and then peer B wants to initiate a signing process, it should make a request to the peer A to start the process. When complete, the peer A can send the result to peer B. Peer B can verify this result with the verify function.
A detailed flow is described in the following procedure:
- Peer A calls the relevant initialization function.
- Peer A calls the step function, with a null input message, and gets an output message.
- Peer A sends the operation details and its output message to peer B.
- Note that the operation details are sent in this step. This information enables peer B to run the initialization function. Alternatively, this information can be sent any time before the next step.
- Peer B verifies the operation details and consents to execute it.
- Peer B calls the initialization function.
- Peer B calls the step function with the message it received from peer A as input message.
- Peer B sends the output message back to peer A.
- Each peer alternates calling the step function with the input message from the other peer and then sending the output message to the other peer.
- This ping-pong process continues until both peers are finished, which is determined by output flags from the step function.
- The mpc_protocol_finished flag denotes that it was the last step on this peer.
- If it also includes the mpc_share_changed flag then the local key share changed, such as with a refresh action. The key share needs to retrieved from the context using the getShare function and stored for future use.
- If the output message from the last step is not empty it must be sent to the other peer.
- One or both peers may need to call the getResult function based on the type of operation. For example, a sign action only has a result for one peer, but a refresh action has a new key share for both peers.
Throughout the entire process the same context should be used. If the context needs to be stored, you can use the serialization function, and then read it back in using the deserialization function.
An example of an ECDSA signing action is shown in the following figure.
Each peer starts by calling the MPCCrypto_initEcdsaSign() function for initialization. After initialization, each peer calls the MPCCrypto_step() function a number of times until the peer is finished with the signing process. The signature, which is the result of the signing process, is received by calling the final function, MPCCrypto_finalEcdsaSign(), after which the signing process is done.