{"id":13811481,"url":"https://github.com/unboundsecurity/blockchain-crypto-mpc","last_synced_at":"2025-05-14T19:33:37.101Z","repository":{"id":39373254,"uuid":"154275339","full_name":"unboundsecurity/blockchain-crypto-mpc","owner":"unboundsecurity","description":"Protecting cryptographic signing keys and seed secrets with Multi-Party Computation.","archived":false,"fork":false,"pushed_at":"2022-07-28T07:29:15.000Z","size":3302,"stargazers_count":454,"open_issues_count":2,"forks_count":167,"subscribers_count":36,"default_branch":"master","last_synced_at":"2024-08-14T13:04:36.626Z","etag":null,"topics":["blockchain","cryptography","hardware-security-module","hsm","mpc","multi-signature","multiparty-computation","multisig"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unboundsecurity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-23T06:37:57.000Z","updated_at":"2024-08-07T20:18:03.000Z","dependencies_parsed_at":"2022-07-04T07:22:28.763Z","dependency_job_id":null,"html_url":"https://github.com/unboundsecurity/blockchain-crypto-mpc","commit_stats":null,"previous_names":["unbound-tech/blockchain-crypto-mpc"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unboundsecurity%2Fblockchain-crypto-mpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unboundsecurity%2Fblockchain-crypto-mpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unboundsecurity%2Fblockchain-crypto-mpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unboundsecurity%2Fblockchain-crypto-mpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unboundsecurity","download_url":"https://codeload.github.com/unboundsecurity/blockchain-crypto-mpc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225307786,"owners_count":17453871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","cryptography","hardware-security-module","hsm","mpc","multi-signature","multiparty-computation","multisig"],"created_at":"2024-08-04T04:00:21.939Z","updated_at":"2024-11-19T06:32:30.612Z","avatar_url":"https://github.com/unboundsecurity.png","language":"C","readme":"# IMPORTANT NOTE\n \n**As of September 1, 2021, this repository will be converted to read only and support will end.**\n \nTherefore, starting on September 1, 2021, the following changes will occur:\n1. Unbound will stop maintenance for this repo.\n1. Unbound will not release any future versions of this repo.\n1. Unbound will not provide any security updates or hotfixes (should an issue arise).\n1. Unbound will stop support for this repo.\n \nThis library was originally created to enable users to experiment with MPC functionality using a subset of the functionality provided in Unbound products.\n \nUsers are encouraged to explore the new Unbound CORE offerings found in the [Unbound Security website](https://www.unboundsecurity.com/).\n \n\n# 1. Introduction to *blockchain-crypto-mpc*\n\n**blockchain-crypto-mpc** is an open source library released by [Unbound\nSecurity](https://www.unboundsecurity.com) that provides the\ncryptographic foundation to resolve one of the hardest challenges\nassociated with crypto asset and blockchain applications: **The\nprotection of cryptographic signing keys and seed secrets**.\n\n\n\nUnbound leverages [secure multiparty computation\n(MPC)](https://www.unboundsecurity.com/blog/secure-multiparty-computation-mpc/)\nfor the protection and management of cryptographic keys and secrets, and\nprovides industry-grade MPC-based solutions for key management, key\nprotection and additional applications. The protocols were designed by\n[Prof. Yehuda Lindell](https://en.wikipedia.org/wiki/Yehuda_Lindell) and\nDr. Samuel Ranellucci, who also reviewed and approved the code and the\nimplementation.\n\nSee the [Unbound Cryptocurrency Wallet Library White Paper](./docs/Unbound_Cryptocurrency_Wallet_Library_White_Paper.md) for more detailed information about the protocols.\n\nThis readme includes an overview of this library, why it is important,\nwhat it allows you to achieve, sample use cases, and how to use the\nlibrary (high level description).\n\n\n# 2. Who Should Use it? \n\n**Blockchain Crypto MPC provides 100% of the cryptography needed for\nstrongly securing crypto asset and blockchain wallets -- while being as\nor more secure than dedicated cryptographic hardware -- for free**. If\nyou're developing a wallet or a platform for custody/exchanging of\ncrypto assets -- you're in the right place!\n\nLeveraging MPC for the protection of cryptographic keys and secrets,\n**blockchain-crypto-mpc** provides the security benefits of no single\npoint of compromise and shared responsibility (like Multi-Sig), but with\na single signature and without any dependency on the ledger. More\nspecifically, it provides three critical security properties:\n\n1.  Sensitive keys and secrets are split into two random shares, which\n    are stored on separate, segregated machines ('machine' stands for\n    any computing device). Each of these shares by itself reveals\n    nothing whatsoever about the key material.\n\n2.  All cryptographic operations performed throughout the key lifecycle\n    are performed without ever combining these 2 shares together. This\n    includes signing, derivation and even generation. **Bottom line --\n    there is no complete key material or secret in the memory, ever**.\n    **It is proven mathematically that obtaining the key material\n    requires access to both key shares,** **and therefore requires\n    compromising both machines.** A single machine, even if completely\n    compromised and controlled by an attacker, reveals nothing about the\n    key material -- simply because the key material **never** resides in\n    any single machine.\n\n3.  Key shares refresh: The key shares are continually modified without\n    modifying the key itself. It is computationally efficient and can be\n    performed very frequently -- thus forcing the attacker to compromise\n    both machines at virtually the same time in order to obtain key\n    material.\n\n![Key Shares](docs/images/os-key-shares.png)\n\n**blockchain-crypto-mpc** includes a secure MPC implementation of 100%\nof the functionality required to strongly secure crypto asset and\nblockchain wallets. It's pure software, open-source and free to use.\n\nIt is highly recommended for developers of wallets and blockchain\napplications that deal with key management.\n\n**We are delighted to make this contribution to the open source\ncommunity, with hopes that it will enable secure, convenient, and easy\nto use blockchain applications for all.**\n\n# 3. What's Included?\n\n\n**blockchain-crypto-mpc** includes a secure MPC implementation of the\nfollowing algorithms:\n\n-   2-party ECDSA secp256k1: generation and signing\n-   2-party EdDSA ed25519: generation and signing\n-   2-party BIP32 (based on the [BIP32 specification](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)): generation, hard\n    derivation, and normal derivation\n-   Key share refresh\n-   Zero-knowledge backup\n\nThe source code is written in C++ and the external API in C. Detailed\ndocumentation including a whitepaper and security proofs will be\navailable online soon.\n\nIt can be compiled on virtually any platform. The only dependency is\nOpenSSL, which is available on most platforms. Instructions on how to\nremove this dependency will be included in future documentation.\n\nThe compiled binary is a cryptographic library that has to be deployed\non two or more separate machines to provide strong security.\n\n# 4. What are the Typical Use Cases?\n\n\n**blockchain-crypto-mpc** can be used to provide security in any blockchain\napp. In this section we describe typical use cases that are relevant to\nmany applications.\n\n## 4.1 Endpoint/Server Use Case \n\n\nThis use case is common for wallet service providers. The user has a\nmobile wallet on their endpoint device, typically their mobile phone or\nlaptop. The wallet application communicates with a server application.\n\n### 4.1.1 Suggested setup:\n\nThe BIP32 seed and all signing keys are always split between the end\nuser's device (participant 1) and the service provider (participant 2).\nPerforming any cryptographic operation on the seed or private key\nrequires cooperation of both participants (and communication between\nthem).\n\n![Endpoint/Server Use Case](docs/images/use-case-endpoint-server.png)\n\n### 4.1.2 Use Case Properties\n\n-   Guaranteed non-repudiation; the application server cannot sign any\n    transaction without cooperation from the endpoint device.\n-   No single point of compromise: Compromising the seed or key material\n    requires the attacker to compromise both the server and the endpoint\n    simultaneously.\n-   No key or seed material ever appears in the clear throughout its\n    lifecycle, including while in use and during generation.\n-   Resilient to side-channel attacks.\n-   A model that empowers a crypto service provider to create an\n    excellent user experience by delivering a wallet service while\n    maintaining a very high security level and granting the users full\n    control of their crypto assets.\n\n## 4.2 Mobile/Laptop Use Case\n\n\nThis is a use case involving two end-user devices that typically belong\nto the same user. For example, a mobile phone and a laptop. Each device\nruns an app and both participants collaborate to create a secure\nblockchain wallet and sign transactions.\n\n### 4.2.1 Suggested Setup\n\nThe BIP32 seed and all signing keys are always split between the mobile\ndevice (participant 1) and the laptop (participant 2). Performing any\ncryptographic operation on the seed or private key requires cooperation\nof both participants (and communication between them).\n\n![Mobile/Laptop Use Case](docs/images/use-case-mobile-laptop.png)\n\n### 4.2.2 Use Case Properties\n\n-   Both devices must collaborate and approve any transaction. No single\n    device can approve a transaction.\n-   No single point of compromise: Compromising the seed or key material\n    requires the attacker to compromise both the laptop and the mobile\n    device simultaneously.\n-   No key or seed material ever appears in the clear throughout its\n    lifecycle, including while in use and during generation.\n-   Resilient to side-channel attacks.\n-   A model that empowers a wallet provider to create an excellent\n    user experience while maintaining a very high security level and\n    granting the users full control of their crypto assets.\n\n## 4.3 Backup\n\n\nBackup is one of the most challenging aspects of crypto asset key\nmanagement. This section briefly describes the backup functionality of\n**blockchain-crypto-mpc** and two potential usage scenarios.\n\n**blockchain-crypto-mpc** includes a unique backup mechanism that introduces\nzero-knowledge backup: an encrypted cold backup that allows public\nverifiability. This property is significant, as it allows both\nparticipants to verify the correctness of the backup at any point in\ntime without decrypting it. It therefore makes this verification secure\nand prevents a situation where a wrong backup was generated and stored.\n\n### 4.3.1 Backup Use Case 1: User-Managed\n\nThis is a common form of backup, with the role of backup management\nmostly on the end-user. An encrypted backup of the wallet can be stored\nin multiple locations for redundancy (for example, it can be stored by\nthe service provider as described in the Endpoint/Server use case). The\nprivate key for this backup should be in the user's sole possession,\npreferably in a cold backup. The backup recovery process should be used\nonly for disaster recovery.\n\n### 4.3.2 Backup Use Case 2: Managed Backup\n\nThe following scenario is an expansion of the Endpoint/Server use case\nthat includes a 3rd party trustee service. The trustee service is used\nonly when either the user's device and/or the service provider have lost\ntheir respective key shares.\n\n![Backup Use Case 2: Managed Backup](docs/images/use-case-managed-backup.png)\n\nThis model creates a user-transparent backup, effectively similar to a\n2-of-3 scenario: each quorum containing 2 of the 3 participants noted\nabove would suffice to perform a cryptographic operation. This is\nperformed by creating three different random share pairs upon wallet and\nseed generation. In the diagram, key share A is used by\nthe 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.\nIt's important to highlight that each of these pairs is completely\nindependent, each is effectively a backup of the same seed.\n\n# 5. Benchmarking and Performance\n\nThis repository includes a two different tools for benchmarking the **blockchain-crypto-mpc** library. \n\n1. MPC Crypto Bench - a tool written C++. See [mpc_crypto_bench](https://github.com/unboundsecurity/blockchain-crypto-mpc/blob/master/bench/README.md) in the [bench](./bench) folder for more information.\n2. MPC Crypto Python script. See [mpc_crypto](https://github.com/unboundsecurity/blockchain-crypto-mpc/blob/master/python/README.md) in the [Python](./python) folder for more information.\n\nMPC 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.\n \nUsing the Python script, each command was run for 20 iterations and resulted in the following performance numbers:\n\n| Algorithm | Command  | Time (seconds) |\n|-----------|----------|:--------------:|\n| ECDSA     | Generate | 0.945          |\n| ECDSA     | Sign     | 0.015          |\n| EdDSA     | Generate | 0.003          |\n| EdDSA     | Sign     | 0.003          |\n\nThe tests were run on a server with an Intel Xeon E5-2686 v4 (2.30 GHz) with 32 GB RAM.\n\n\n# 6. Technical Overview and Usage Guidelines\n\n\nUnbound's Blockchain Crypto MPC open source library provides functions\nthat enable you to create, sign, and refresh encryption keys, without\nthe whole key ever existing in any location.\n\nThis library can be used to create system with two peers for the\nmanagement of the keys. Each peer uses the library to create and process\nmessages that are sent between the peers. Note that the actual\ncommunication between peers is not included in this library.\n\n![blockchain-crypto-mpc system](docs/images/os-system.png)\n## 6.1 Definitions\n\n\nBlockchain Crypto MPC utilizes the following three structures:\n\n1.  **Key share** -- Encryption keys never exist as complete keys in any\n    phase of the process or in any location at any time. A key share is\n    a piece of a key, which can be used by Unbound's MPC technology to\n    sign transactions.\n2.  **Message** -- Data that is passed to the other peer. The message\n    contains information about the action in progress.\n3.  **Context** -- Since each action, such as signing with a key,\n    involves multiple messages between the two peers, the status of the\n    action is preserved in a context.\n\nThe **key share**, **message**, and **context** contain varying amounts\nof information depending on the type action, and therefore they are\nstructures.\n\n## 6.2 Actions\n\n\nThe library provides the following actions:\n\n-   2-party ECDSA secp256k1: generation and signing\n-   2-party EdDSA ed25519: generation and signing\n-   2-party BIP32 (based on the [BIP32 specification](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)): generation, hard\n    derivation, and normal derivation\n-   Key share refresh\n-   Zero-knowledge backup\n\nThe library also provides mechanisms to handle serialization,\ndeserialization, and memory management for the key share, message, and\ncontext structures.\n\n## 6.3 System Flow\n\n\nThe system flow is shown in the following figure:\n\n![Flow](docs/images/os-flow.png)\n\nThe first step is initialization. During this step you provide the\nlibrary with all the relevant information required to complete the\ndesired action. This step takes that information and creates a\n**context**. Each peer does its own initialization.\n\nThe context is then passed through a series of steps. Each of these\nsteps takes an **input message**, does some manipulation, and then\ncreates an **output message**. You then transfer this output message to\nthe other peer. The other peer receives the message and associates it\nwith a context. It then knows how to handle the incoming message based\non the context.\n\nWhen the peer is done with the last step it sets a finished flag. The\npeer can then do any necessary cleanup, such as freeing memory, or\ncopying an updated key share to storage.\n\n\n### 6.3.1 Peer Roles\n\nPeer 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.\n\n### 6.3.2 Detailed Flow\n\nA detailed flow is described in the following procedure:\n\n1. Peer A calls the relevant initialization function.\n1. Peer A calls the step function, with a null **input message**, and gets an **output message**.\n1. Peer A sends the **operation details** and its **output message** to peer B.\n    - 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.\n1. Peer B verifies the **operation details** and consents to execute it.\n1. Peer B calls the initialization function.\n1. Peer B calls the **step** function with the message it received from peer A as **input message**.\n1. Peer B sends the **output message** back to peer A.\n1. 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.\n1. This ping-pong process continues until both peers are finished, which is determined by output flags from the **step** function. \n\t- The *mpc_protocol_finished* flag denotes that it was the last step on this peer.\n\t- 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.\n\t- If the output message from the last step is not empty it must be sent to the other peer.\n\t- 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.\n\n\t\nThroughout 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.\n\n\n\n### 6.3.3 Example Action\n\nAn example of an ECDSA signing action is shown in the following figure.\n\n![Flow](docs/images/os-flow-example.png)\n\nEach peer starts by calling the **MPCCrypto_initEcdsaSign()** function \nfor initialization. After initialization, each peer calls the \n**MPCCrypto_step()** function a number of times until the peer is \nfinished with the signing process. The signature, which is the result of \nthe signing process, is received by calling the final function, \n**MPCCrypto_finalEcdsaSign()**, after which the signing process is done.\n","funding_links":[],"categories":["TSS list"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funboundsecurity%2Fblockchain-crypto-mpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funboundsecurity%2Fblockchain-crypto-mpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funboundsecurity%2Fblockchain-crypto-mpc/lists"}