certusone
/
dc4bc
mirror of https://github.com/certusone/dc4bc.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'fix/readme-typos' into chore/2-dkg-test 

# Conflicts:
#	README.md
This commit is contained in:
Andrej Zavgorodnij 2020-10-16 13:33:53 +03:00
parent c1068f1532 294044fde4
commit 01b989e183
1 changed files with 22 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
README.md
View File

@ -1,10 +1,10 @@
# dc4bc: distributed custody for the beacon chain
The goal of ths project is to make a simple, secure framework to generate and use threshold signatures for infrequent financial transactions over Ethereum 2.0 Beacon Chain (BLS on BLS12-381 curve). dc4bc only deals with key generation and the signature process with all the user-side logic offloaded to applications using dc4bc as a service or an API.
The goal of this project is to make a simple, secure framework to generate and use threshold signatures for infrequent financial transactions over Ethereum 2.0 Beacon Chain (BLS on BLS12-381 curve). dc4bc only deals with key generation and the signature process with all the user-side logic offloaded to applications using dc4bc as a service or an API.
For a better key management, we presume that, when used in production, private encryption keys and threshold signature related secrets reside in an airgapped machine or an HSM. For a better auditablity and testability, network protocol logic is implemented as a set of finite state machines that change state deterministically in response to a a stream of outside events.
For a better key management, we presume that, when used in production, private encryption keys and threshold signature related secrets reside in an airgapped machine or an HSM. For a better auditablity and testability, network protocol logic is implemented as a set of finite state machines that change state deterministically in response to a stream of outside events.
The main and, for now, only network communication primitive we use is a shared bulletin board in form of an authenticated append-only log. Different implementations of that log could be a shared file (for local development or testing), a trusted network service (e.g. Amazon S3 bucket), a federated blockchain between protocol participants or a public blockchain.
The main and, for now, only network communication primitive we use is a shared bulletin board in form of an authenticated append-only log. Different implementations of that log could be a shared file (for local development or testing), a trusted network service (e.g. Amazon S3 bucket), a federated blockchain between protocol participants or a public blockchain.
# How to test this code?
@ -25,7 +25,7 @@ Please refer to [this page](HowTo.md) for a complete guide to running the minima
* `./cmd` Command line interfaces for the Airgapped machine and the Client. All entry points to dc4bc apps can be found here;
* `./dkg` This package is more of a library for maintaining all active DKG instances and data;
* `./fsm` The FSM source code. The FSM decides when we are ready to move to the next step during DKG and signing;
* `./qr` A library for handling QR codes that encode pending Operations (which are used for communication between The Client, and the Airgapped machine);
* `./qr` A library for handling QR codes that encode pending Operations (which are used for communication between The Client, and the Airgapped machine);
* `./storage` Two Bulletin Board implementations: File storage for local debugging and Kafka storage for real-world scenarios.
# Related repositories
@ -33,19 +33,19 @@ Please refer to [this page](HowTo.md) for a complete guide to running the minima
## Moving parts
### Participants
N participants, having a hot (connected to the network) node and a cold (airgapped) node. Participants all have two pair of keys for digital signatures: one for hot node and one for airgapped. PubHotKey_i, PrivHotKey_i, PubColdKey_i, PrivColdKey_i respectively for Participant_i. Each participant also have a secret seed used to generate DKG messages: given the same seed and the same inbound DKG messages participant's outbound messages are deterministic.
### Participants
N participants, having a hot (connected to the network) node and a cold (airgapped) node. Participants all have two pair of keys for digital signatures: one for hot node and one for airgapped. PubHotKey_i, PrivHotKey_i, PubColdKey_i, PrivColdKey_i respectively for Participant_i. Each participant also has a secret seed used to generate DKG messages: given the same seed and the same inbound DKG messages participants outbound messages are deterministic.
Hot keys are stored on the network-connected node, cold keys and a seed are stored on an airgapped node.
### Conference call
It's presumed participants can use a separate secure communication channel (let's call it Conference Call) to establish initial parameters: the set of participants, their identities and public authentification keys, the nature and connection parameters of a bulletin board and so on.
It's presumed participants can use a separate secure communication channel (let's call it Conference Call) to establish initial parameters: the set of participants, their identities and public authentication keys, the nature and connection parameters of a bulletin board and so on.
### Bulletin Board
The core communication/storage primitive for dc4bc is a bulletin board - a simple authenticated append-only log that can be accesed by all the participants and allows posting authentificated messages and polling for posted messages. We need BB to have two functions:
The core communication/storage primitive for dc4bc is a bulletin board - a simple authenticated append-only log that can be accessed by all the participants and allows posting authenticated messages and polling for posted messages. We need BB to have two functions:
- post(message, signature)
- getMessages(offset = 0)
- returns a list of all messages posted after the first <offset> one
@ -57,8 +57,8 @@ This allows us to establish communication primitives:
- private_message(message, Participant_j):
encrypted_message = { "to" : Participant_j, "message": encrypt(message, PubColdKey_j)}
broadcast(encrypted_message)
Encryption is done using AES526-GCM + AEAD.
Encryption is done using AES256-GCM + AEAD.
Bulletin board can be constructed using a trusted centralized service a-la kafka queue (implemented), using public blockchain, or using a consensus between participants to establish a private blockchain. Anyway, it should be abstracted away in the client and signer both and easily switchable.
@ -66,15 +66,15 @@ Bulletin board is only available on a hot node.
### Secure Channel
There is a secure comminication channel between a hot node and a cold node between each participant. We expect it to be a QR-code based asynchronous messaging protocol, but it can be something more complicated eventually, e.g. USB connection to the HSM. It's got two primitive functions:
There is a secure communication channel between a hot node and a cold node between each participant. We expect it to be a QR-code based asynchronous messaging protocol, but it can be something more complicated eventually, e.g. USB connection to the HSM. It's got two primitive functions:
- h2c_message(message) - send a message from hot node to cold node, returns message hash
- await_c2h_reply(hash(message)) - wait for reply from cold node
## DKG Process
1. Using a Conference Call, participants establish: the set of participants, public keys for authentfication and encryption, the nature and connection parameters of a bulletin board, step timeouts, threshold number.
2. Any participant broadcasts a DKG Startup Message, that contains the set of participants, and public keys for authentfication and encryption. Hash of that message later is used as a unique id of a DKG (used in messages to differentiate between multiple parallel DKGs if needed).
1. Using a Conference Call, participants establish: the set of participants, public keys for authentication and encryption, the nature and connection parameters of a bulletin board, step timeouts, threshold number.
2. Any participant broadcasts a DKG Startup Message, that contains the set of participants, and public keys for authentication and encryption. Hash of that message later is used as a unique id of a DKG (used in messages to differentiate between multiple parallel DKGs if needed).
3. All participants broadcast their agreement to participate in this particular DKG within the agreed upon step timeout.
4. When all participants agree, every participant asks a cold node to publish a commit:
1. message_hash = h2c_message(<start DKG with DKG_hash xxx, number of participants X, threshold Y>)
@ -84,25 +84,25 @@ There is a secure comminication channel between a hot node and a cold node betwe
2. message_hash = h2c_message(<send deals>)
3. deals = await_c2h_reply(message_hash)
4. for participant in participants:
1. direct_message(participant, deal[participant])
6. When a pariticipant has recieved all the deals:
1. private_message(deal[participant], participant)
6. When a participant has received all the deals:
1. They reconstruct the public key from the deals and broadcast it
7. If everyone broadcasts the same reconstructed public key, DKG completed successfully
If at any point something goes wrong (timeout reached, the deal is invalid, public key is not recinstucted equally, some of participants complain using a Conference Call) the DKG is aborted.
If at any point something goes wrong (timeout reached, the deal is invalid, public key is not reconstructed equally, some of participants complain using a Conference Call) the DKG is aborted.
## Signature process
1. Any paricipant broadcast a message to sign upon.
2. All other participants signal their willingness to sign by broadcasting agreemen to sign that message.
3. When enough (>= threshold) participants broadcasted an agreement, every participant:
1. Any participant broadcast a message to sign upon.
2. All other participants signal their willingness to sign by broadcasting agreement to sign that message.
3. When enough (>= threshold) participants have broadcast an agreement, every participant:
1. message_hash = h2c_message(<send a partial signature for message "message" for threshold public key "key">)
2. broadcast(await_c2h_reply(message_hash))
4. When enough (>= threshold) participants broadcasted a partial signature, threshold signature is reconstructed.
4. When enough (>= threshold) participants have broadcast a partial signature, the threshold signature can be reconstructed.
5. Someone broadcasts a partial signature.
If not enough participants signal their willingness to sign within a timeout or signal their rejection to sign, signature process is aborted.
If not enough participants signal their willingness to sign within a timeout or signal their rejection to sign, the signature process is aborted.
We organize logic in the hot node as a set of simple state machines that change state only by external trigger, such as CLI command, message from cold node, or a new message on Bulletin Board. That way it can be easily tested and audited.
We organize logic in the hot node as a set of simple state machines that change state only by external trigger, such as CLI command, a message from the cold node, or a new message on Bulletin Board. That way it can be easily tested and audited.
# Finite-state machines description