drand

command module
v0.3.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 16, 2018 License: MIT Imports: 12 Imported by: 0

README

Build Status

Drand - A Distributed Randomness Beacon Daemon

Drand (pronounced "dee-rand") is a distributed randomness beacon daemon written in Golang. Servers running drand can be linked with each other to produce collective, publicly verifiable, unbiasable, unpredictable random values at fixed intervals using pairing-based threshold cryptography. drand nodes can also serve individual requests to produce locally-generated private randomness to a client.

Disclaimer

This software is considered experimental and has NOT received a full audit yet. Therefore, DO NOT USE it in production at this point. You have been warned.

I Want Randomness Now!

Sure thing, here you go:

  1. Make sure that you have a working Docker installation.
  2. Then run:
./run_local.sh

The script spins up six local drand nodes and produces fresh randomness every two seconds. Drand is able to produce two kind of randomness:

  • Drand main's function is to generate verifiable unbiasable randomness that we call Public Randomness. This kind of randomness is useful in many applications such as lottery, or sharding or even parameters generation.
  • Drand can also generate Private Randomness. This randomness has been generated locally by the remote server who sends it back in an encrypted form to the client. This is useful to gather different entropy sources to generate a high entropy randomness source.

Drand in a Nutshell

Public Randomness

A drand distributed randomness beacon involves a set of nodes and has two phases:

  • Setup: Each node first generates a long-term public/private key pair. Afterwards, a group file is created which gathers all the participants' public keys together with some further metadata required to operate the beacon. After the group file has been distributed, all participants run a distributed key generation (DKG) protocol to create the collective public key and one private key share per node. The participants NEVER see/use the actual private key explicitly but instead utilize their respective private key shares for drand's cryptographic operations.

  • Generation: After the setup, the participating nodes switch to the randomness generation mode. Any of the nodes can then function as a leader to initiate a randomness generation round. Therefore, a given leader broadcasts a message (in this case, a timestamp) which is then signed by all participants using a threshold version of the Boneh-Lynn-Shacham (BLS) signature scheme and their respective private key shares. Once any node (or third-party observer) has gathered a threshold of partial signatures, it can reconstruct the full BLS signature (using Lagrange interpolation) which corresponds to the collective random value. This random beacon / full BLS signature can be verified against the distributed public key that was computed with the DKG.

Private Randomness

In this mode, the client generates a private/public key pair and encrypts the public key towards the server's public key using the ECIES encryption scheme. Upon reception of the request, the server produces 32 random bytes locally (using Go's crypto/rand interface), and encrypts back the randomness to the client's public key.

Installation

Drand can be installed via Golang or Docker. By default, drand saves the configuration files such as the long-term key pair, the group file, and the collective public key in $HOME/.drand/.

Via Docker

Make sure that you have a working Docker installation.

Via Golang
  1. Make sure that you have a working Golang installation and that your GOPATH is set.
  2. Install drand via:
go get -u github.com/dedis/drand

Usage

NOTE: If you run drand in Docker, always use the following template

docker run \
    --rm \
    --name drand \
    -p <port>:<port> \
    --volume $HOME/.drand/:/.drand/ \
    dedis/drand <command>

where <port> specifies the port through which your drand daemon is reachable and <command> has to be substituted by one of the respective drand commands below.

Setup

To setup the drand beacon, each participant generates its long-term key pair from which we can then assemble the group configuration file, and finally all participants run the distributed key generation protocol.

Long-Term Key

To generate the long-term key pair drand_id.{secret,public} of the drand daemon, execute

drand keygen <address>

where <address> is the address from which your drand daemon is reachable. It can be a HTTPS like address if you have setup a HTTPS proxy in front. Native TLS support in drand is not yet operational, but since drand uses gRPC, this functionality should be easy to implement.

Group Configuration

To generate the group configuration file drand_group.toml, run

drand group <pk1> <pk2> ... <pkn>

where <pki> is the public key file drand_id.public of the i-th participant. The group file is generated in the current directory under group.toml.

NOTE: This group file MUST be distributed to all participants !

Distributed Key Generation

After receiving the drand_group.toml file, participants can start drand via:

drand run <group_file.toml>

One of the nodes has to function as the leader which finalizes the setup and later also initiates regular randomness generation rounds. To start the drand daemon in leader mode, execute:

drand run --leader <group_file.toml>

Once running, the leader initiates the distributed key generation protocol to compute the distributed public key (dist_key.public) and the private key shares (dist_key.private) together with the participants specified in drand_group.toml.

Once the DKG phase is done, the distributed public key is saved in the local directoryas well as in the configuration folder ($HOME/.drand by default) under the file groups/dist_key.public.

Randomness Generation

The leader initiates a new randomness generation round automatically as per the specified time interval (default interval: 1m). All beacon values are stored using BoltDB, a Go native fast key/value database engine.

To change the duration of the randomness generation interval, e.g., to 30s, start drand via

drand run --leader --period 30s
Randomness Gathering
  • Public Randomness: To get the latest public beacon, run the following:
drand fetch public --distkey dist_key.public <address>

dist_key.public is the distributed key generated once the DKG phase completed, and <address> is the address of one drand node. The output will have the following JSON format:

{
    "round": 2,
    "previous_rand": "jnbvQ3LSxg8kp8qwpPO1u2F4ietJCZmMjJUQ1KDo4u94P57hN1K2mJk7oeiWU2Czb5pNqWy4u6vQH2fkqdoNgA==",
    "randomness": "QqcL2Pncns2pKrSdfJw0RK6YFosLpP/44FUBF6Udf38uz5rHyVsZ8/XgElTdDLCpUDIm/DWIzltIzmqArZTjlQ=="
}

The public random value is the field signature, which is a valid BLS signature. The signature is made over the concatenation of the previous_sig and the timestamp (uint64) field. If the signature is valid, that guarantees a threshold of drand nodes computed this signature without being able to bias the outcome.

  • Private Randomness: To get a private random value, run the following:
drand fetch private <server_identity.toml>
{
    "Randomness": "QvIntnAk9P+B3fVQXm3wahNCusx2fKQs0HMRHI77XRk="
}

<server_identity.toml> is the public identity file of one of the server. It is useful to be able to encrypt both the request and response between the client and the server.

The command outputs a 32-byte base64-encoded random value coming from the local randomness engine of the contacted server. If the encryption is not correct, the command outputs an error instead.

Learn More About The Crypto Magic Behind Drand

Drand relies on the following cryptographic constructions:

What's Next?

Although being already functional, drand is still at an early stage of development, so there's a lot left to be done. Feel free to submit feature or, even better, pull requests. ;)

  • integrate native TLS support, should be fairly easy since drand uses gRPC.
  • versioning mechanism
  • much more unit tests
  • systemd unit file

License

The drand source code is released under MIT license, see the file LICENSE for the full text.

Designers and Contributors

Acknowledgments

Thanks to @herumi for providing support for his optimized pairing-based cryptographic library used in the first version.

Thanks to Apostol Vassilev for its interest in drand and the long emails exchanged over the general drand design.

Thanks to @Bren2010 and @grittygrease for providing the native Golang bn256 implementation and for their help in the design of drand.

Documentation

Overview

drand is a distributed randomness beacon. It provides periodically an unpredictable, bias-resistant, and verifiable random value.

Directories

Path Synopsis
fs holds some utilities for manipulating the file system
fs holds some utilities for manipulating the file system
protobuf
crypto
converter implements some routines to go back and forth from a protobuf point and scalar to a kyber Point and Scalar interface.
converter implements some routines to go back and forth from a protobuf point and scalar to a kyber Point and Scalar interface.
crypto/share
Package share is a generated protocol buffer package.
Package share is a generated protocol buffer package.
crypto/share/vss
Package vss is a generated protocol buffer package.
Package vss is a generated protocol buffer package.
dkg
Package dkg is a generated protocol buffer package.
Package dkg is a generated protocol buffer package.
drand
Package drand is a generated protocol buffer package.
Package drand is a generated protocol buffer package.
test package offers some common functionalities that are used throughout many different tests in drand.
test package offers some common functionalities that are used throughout many different tests in drand.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL