From d0845acbbae6f6e315ae023ddcbbad29bbb5ccac Mon Sep 17 00:00:00 2001 From: Luke Valenta Date: Thu, 15 Oct 2020 14:18:44 -0500 Subject: [PATCH] RTG-394 update docs owned by Research Team Update distributed-web, randomness-beacon, and time-services developer docs --- .github/CODEOWNERS | 9 + .../src/content/ethereum-gateway/about-eth.md | 20 +-- .../connecting-your-website.md | 9 +- .../ethereum-gateway/getting-started.md | 6 +- .../src/content/ethereum-gateway/index.md | 10 +- .../interacting-with-the-eth-gateway.md | 11 +- .../content/ethereum-gateway/kill-switches.md | 10 +- products/distributed-web/src/content/index.md | 8 +- .../ipfs-gateway/automated-deployment.md | 6 +- .../src/content/ipfs-gateway/browsing-ipfs.md | 8 +- .../ipfs-gateway/connecting-website.md | 6 +- .../src/content/ipfs-gateway/index.md | 6 +- .../ipfs-gateway/setting-up-a-server.md | 6 +- .../content/ipfs-gateway/troubleshooting.md | 6 +- .../content/ipfs-gateway/updating-for-ipfs.md | 6 +- .../src/content/about/Background.md | 10 +- .../src/content/about/Drand.md | 5 +- .../content/about/{future.md => Future.md} | 4 +- .../src/content/about/index.md | 14 +- .../content/cryptographic-background/index.md | 16 +- .../randomness-generation.md | 94 ++++++++++ .../cryptographic-background/setup-phase.md | 160 +++--------------- .../randomness-beacon/src/content/index.md | 8 +- .../src/content/operator-guide/index.md | 6 +- .../src/content/user-guide/index.md | 7 +- products/time-services/src/content/index.md | 8 +- .../time-services/src/content/ntp/index.md | 10 +- .../time-services/src/content/ntp/usage.md | 6 +- .../time-services/src/content/nts/index.md | 9 +- .../time-services/src/content/nts/usage.md | 22 +-- .../src/content/roughtime/about.md | 6 +- .../src/content/roughtime/index.md | 6 +- .../src/content/roughtime/recipes.md | 6 +- .../src/content/roughtime/usage.md | 8 +- 34 files changed, 259 insertions(+), 273 deletions(-) rename products/randomness-beacon/src/content/about/{future.md => Future.md} (92%) create mode 100644 products/randomness-beacon/src/content/cryptographic-background/randomness-generation.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 726dea0b9fff09..7e8ecd87148020 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -21,3 +21,12 @@ products/gateway/ @abracchi-tw # Warp Client products/warpclient/ @abracchi-tw + +# Randomness Beacon +products/randomness-beacon/ @ltv511 @armfazh + +# Distributed Web +products/distributed-web/ @ltv511 @thibmeu @jhoyla @Lekensteyn + +# Time Services +products/time-services/ @ltv511 @wbl @armfazh diff --git a/products/distributed-web/src/content/ethereum-gateway/about-eth.md b/products/distributed-web/src/content/ethereum-gateway/about-eth.md index a901e5d96ca2b1..36b4083216d2c3 100644 --- a/products/distributed-web/src/content/ethereum-gateway/about-eth.md +++ b/products/distributed-web/src/content/ethereum-gateway/about-eth.md @@ -1,9 +1,9 @@ --- -title: About Ethereum -alwaysopen: true -weight: 2 +order: 2 --- +# About Ethereum + The Ethereum network is a distributed consensus platform that allows users to write and compute smart contracts in a distributed manner. Smart contracts are essentially Turing complete programs that are available at a unique address of @@ -11,7 +11,7 @@ the network. When the smart contract is run as part of a transaction, the result and the current state of the contract are stored in a verifiable consensus that is agreed upon by the entire network of nodes. -### Smart contracts +## Smart contracts When a user wants to run a smart contract on some desired inputs, they provide currency known as ETH with their command. This currency is allocated to a @@ -23,7 +23,7 @@ in the network then this is also recorded in the consensus. As such, this consensus represents the current state of the network along with exactly how much Ethereum currency is owned by each individual. -### Addressing +## Addressing All transactions on the network are stored in 'blocks' that make up the entire consensus. In brief, the consensus is a single sequence of blocks with @@ -39,7 +39,7 @@ block, this update is sent around the entire network and anyone can read the nature of the transaction that took place. This makes the entire state of the network accountable. -### Reading & writing content +## Reading & writing content To read content, a user needs to interact with a working Ethereum node. Such nodes can be run locally on a user's machine as daemons (such as: @@ -57,15 +57,15 @@ sent to the wider network and added to the consensus. Reading and writing content to the Ethereum network can be done using Cloudflare's Gateway. To learn more about how to do this see [Interacting with -the Ethereum network](../interacting-with-the-eth-gateway). +the Ethereum network](./interacting-with-the-eth-gateway). -### Connect your website to the gateway +## Connect your website to the gateway If you want to be able to access the Ethereum network accessible from a custom domain name, you can do that using Cloudflare’s Ethereum Gateway. To -learn how, check out [Connecting your Website](../connecting-your-website). +learn how, check out [Connecting your Website](./connecting-your-website). -### Going Further +## Going Further If you’re interested in learning more, you can read the official [RPC documentation](https://github.com/ethereum/wiki/wiki/JSON-RPC), along with the diff --git a/products/distributed-web/src/content/ethereum-gateway/connecting-your-website.md b/products/distributed-web/src/content/ethereum-gateway/connecting-your-website.md index 3acc22cd68409e..9240b1d3d627c6 100644 --- a/products/distributed-web/src/content/ethereum-gateway/connecting-your-website.md +++ b/products/distributed-web/src/content/ethereum-gateway/connecting-your-website.md @@ -1,14 +1,13 @@ --- -title: Connecting your Website -alwaysopen: true -weight: 3 +order: 3 --- +# Connecting your Website You can connect your own domain name to to allow Ethereum network access from your own domain. This means that anyone can send the HTTP (JSON RPC) queries as given in [Interacting with the Ethereum -Gateway](https://developers.cloudflare.com/distributed-web/ethereum-gateway/interacting-with-the-eth-gateway/) +Gateway](./interacting-with-the-eth-gateway/) to your own domain. To do this, you should replace `https://cloudflare-eth.com` with your domain, e.g. `myethereumgateway.xyz`, as the target of the HTTP query. @@ -20,7 +19,7 @@ you need to: 1. Go to your DNS settings for your domain. If your website is on Cloudflare, the DNS settings are accessible from your dashboard. If your website is not on Cloudflare, and you need help finding the DNS records, you can use -[DomaninTools](https://whois.domaintools.com/) to identify your registrar. +[DomainTools](https://whois.domaintools.com/) to identify your registrar. 2. Add a CNAME record from your domain (e.g. www.example.com) to cloudflare-eth.com. Note: if your website is on Cloudflare, the little cloud next to this record will automatically turn grey. Because you’ve CNAME’d to diff --git a/products/distributed-web/src/content/ethereum-gateway/getting-started.md b/products/distributed-web/src/content/ethereum-gateway/getting-started.md index 6b35972f86ba22..23a507756c2b23 100644 --- a/products/distributed-web/src/content/ethereum-gateway/getting-started.md +++ b/products/distributed-web/src/content/ethereum-gateway/getting-started.md @@ -1,9 +1,9 @@ --- -title: Getting started -alwaysopen: true -weight: 1 +order: 1 --- +# Getting started + Cloudflare's Ethereum Gateway is part of the wider Distributed Web Gateway offering, specifically providing access to the Ethereum network. In particular, users can read all information that has been agreed upon by the consensus of diff --git a/products/distributed-web/src/content/ethereum-gateway/index.md b/products/distributed-web/src/content/ethereum-gateway/index.md index 302c5a84af33c5..ed31cc13d1c413 100644 --- a/products/distributed-web/src/content/ethereum-gateway/index.md +++ b/products/distributed-web/src/content/ethereum-gateway/index.md @@ -1,17 +1,15 @@ --- -title: Ethereum Gateway -alwaysopen: true -weight: 3 -hidden: false -showNew: false +order: 3 --- +# Ethereum Gateway + Cloudflare's Ethereum Gateway lets you interact with the Ethereum network without installing any software on your computer. Our gateway makes it possible to add interactive elements to sites powered by Ethereum smart contracts on a decentralized compute platform. Combined with the -[IPFS gateway](/distributed-web/ipfs-gateway/), you have decentralized web and +[IPFS gateway](/ipfs-gateway/), you have decentralized web and resource hosting with the added speed, security, and reliability of the Cloudflare edge network. And you have direct access our Ethereum Gateway at [https://cloudflare-eth.com](https://cloudflare-eth.com). diff --git a/products/distributed-web/src/content/ethereum-gateway/interacting-with-the-eth-gateway.md b/products/distributed-web/src/content/ethereum-gateway/interacting-with-the-eth-gateway.md index 738b913f88373e..4411864323b723 100644 --- a/products/distributed-web/src/content/ethereum-gateway/interacting-with-the-eth-gateway.md +++ b/products/distributed-web/src/content/ethereum-gateway/interacting-with-the-eth-gateway.md @@ -1,14 +1,13 @@ --- -title: Interacting with Ethereum -alwaysopen: true -weight: 4 +order: 4 --- +# Interacting with Ethereum Interacting with the network via the Cloudflare Distributed Web Gateway is as simple as specifying the correct JSON blob for your query! -### Reading from the network +## Reading from the network The Cloudflare Ethereum Gateway allows HTTP requests where the body of the request is set to be the JSON body of the request you would like to make. For @@ -85,7 +84,7 @@ The response in both cases will be a JSON blob of the form: For a full list of possible queries, along with examples see the official [RPC documentation](https://github.com/ethereum/wiki/wiki/JSON-RPC#json-rpc-api-reference). -### Writing to the network +## Writing to the network Currently the Ethereum Gateway allows you to write to the network using the `eth_sendRawTransaction` RPC method. This creates a new message call transaction @@ -132,7 +131,7 @@ await fetch(new Request("https://cloudflare-eth.com", { _(The actual command above will not work, you need to provide your own signed transaction!)_ -### Cloudflare supported API +## Cloudflare supported API The full list of API methods that are supported by the Distributed Web Gateway is given below. The Gateway returns a `403` if a method is specified that is not diff --git a/products/distributed-web/src/content/ethereum-gateway/kill-switches.md b/products/distributed-web/src/content/ethereum-gateway/kill-switches.md index d69344a3210e87..82cd70101ae597 100644 --- a/products/distributed-web/src/content/ethereum-gateway/kill-switches.md +++ b/products/distributed-web/src/content/ethereum-gateway/kill-switches.md @@ -1,10 +1,10 @@ --- -title: Kill Switches -alwaysopen: true -weight: 5 +order: 5 --- -### DAO example: Kill Switches +# Kill Switches + +## DAO example: Kill Switches When writing contracts, be especially careful to write secure code and include a kill switch to ensure that if any bugs do reside in the code, they can be @@ -28,7 +28,7 @@ investors funds. However, not everyone agreed with the chain, with those who disagreed rejecting the irregular block and forming the Ethereum Classic network, each blockchain grew independently. -### Be-all end-all solution? +## Be-all end-all solution? Hardly. Kill switches can cause their own problems. Like if a contract that's a library has its kill switch flipped. All contracts relying on this contract diff --git a/products/distributed-web/src/content/index.md b/products/distributed-web/src/content/index.md index 00d83664d448ac..f65c22965acb97 100644 --- a/products/distributed-web/src/content/index.md +++ b/products/distributed-web/src/content/index.md @@ -1,7 +1,11 @@ --- +title: Welcome order: 0 +type: overview --- -# Welcome +# Simple, secure access to the Distributed Web -TODO... +View files stored on the InterPlanetary File System in your browser. Interact with the Ethereum blockchain. Explore the Distributed Web. + +IPFS Gateway   Ethereum Gateway diff --git a/products/distributed-web/src/content/ipfs-gateway/automated-deployment.md b/products/distributed-web/src/content/ipfs-gateway/automated-deployment.md index c9f428ff1fd29e..0be6a2307f9129 100644 --- a/products/distributed-web/src/content/ipfs-gateway/automated-deployment.md +++ b/products/distributed-web/src/content/ipfs-gateway/automated-deployment.md @@ -1,9 +1,9 @@ --- -title: Automated Deployment -alwaysopen: true -weight: 4 +order: 4 --- +# Automated Deployment + Static sites are pretty easy to deploy automatically. The code of the site is usually kept in a Git repository and deployed by pushing the latest commit to a repository that's connected to a Continuous Integration service like [Travis diff --git a/products/distributed-web/src/content/ipfs-gateway/browsing-ipfs.md b/products/distributed-web/src/content/ipfs-gateway/browsing-ipfs.md index 34ba165d893747..e2be8bb01eadd5 100755 --- a/products/distributed-web/src/content/ipfs-gateway/browsing-ipfs.md +++ b/products/distributed-web/src/content/ipfs-gateway/browsing-ipfs.md @@ -1,14 +1,14 @@ --- -title: Browsing Content on IPFS -alwaysopen: true -weight: 1 +order: 1 --- +# Browsing Content on IPFS + Browsing IPFS using Cloudflare's gateway requires two things: a browser connected to the Internet, and the address of something on IPFS that you want to view. -As mentioned on the [introduction](/distributed-web/ipfs-gateway/) page, every file added to the +As mentioned on the [introduction](/ipfs-gateway/) page, every file added to the IPFS network is given a unique address based on its contents which is called a Content Identifier, or CID. So if you have an image stored on IPFS, its CID would be based on the hash of the bits that compose that image. diff --git a/products/distributed-web/src/content/ipfs-gateway/connecting-website.md b/products/distributed-web/src/content/ipfs-gateway/connecting-website.md index 1153db0cc4de06..6eb93cf12668d0 100755 --- a/products/distributed-web/src/content/ipfs-gateway/connecting-website.md +++ b/products/distributed-web/src/content/ipfs-gateway/connecting-website.md @@ -1,10 +1,10 @@ --- -title: Connecting Your Website -alwaysopen: true -weight: 3 +order: 3 hidden: true --- +# Connecting Your Website + Cloudflare's gateway allows you to host your website on IPFS and still have it accessible from a custom domain name. This allows an end user to access your website without needing to memorize any hash or download any software. Plus, diff --git a/products/distributed-web/src/content/ipfs-gateway/index.md b/products/distributed-web/src/content/ipfs-gateway/index.md index 478c65a27fc2c1..eff942f8e636e5 100755 --- a/products/distributed-web/src/content/ipfs-gateway/index.md +++ b/products/distributed-web/src/content/ipfs-gateway/index.md @@ -1,9 +1,9 @@ --- -title: IPFS Gateway -alwaysopen: true -weight: 2 +order: 2 --- +# IPFS Gateway + Cloudflare's read-only Distributed Web Gateway lets you access content stored on the InterPlanetary File System \(IPFS\) quickly and easily, without downloading any special software or giving up any storage space on your computer. diff --git a/products/distributed-web/src/content/ipfs-gateway/setting-up-a-server.md b/products/distributed-web/src/content/ipfs-gateway/setting-up-a-server.md index 1f75725edcb585..5981c8b18d56d3 100644 --- a/products/distributed-web/src/content/ipfs-gateway/setting-up-a-server.md +++ b/products/distributed-web/src/content/ipfs-gateway/setting-up-a-server.md @@ -1,9 +1,9 @@ --- -title: Setting Up a Server -alwaysopen: true -weight: 2 +order: 2 --- +# Setting Up a Server + While all IPFS nodes are created equal, some are better suited for different purposes depending on their setup. An IPFS node running on your laptop, for instance, isn't very good for hosting a website because your website will go diff --git a/products/distributed-web/src/content/ipfs-gateway/troubleshooting.md b/products/distributed-web/src/content/ipfs-gateway/troubleshooting.md index 1a35b838917b95..10475d8637b7c6 100644 --- a/products/distributed-web/src/content/ipfs-gateway/troubleshooting.md +++ b/products/distributed-web/src/content/ipfs-gateway/troubleshooting.md @@ -1,9 +1,9 @@ --- -title: Troubleshooting -alwaysopen: true -weight: 10 +order: 10 --- +# Troubleshooting + IPFS is still a developing protocol and content is often unavailable or slow to load for reasons outside of Cloudflare's control. Usually, this happens for one of the following reasons: diff --git a/products/distributed-web/src/content/ipfs-gateway/updating-for-ipfs.md b/products/distributed-web/src/content/ipfs-gateway/updating-for-ipfs.md index 8f0f62bd436143..d8cf31f9025a93 100644 --- a/products/distributed-web/src/content/ipfs-gateway/updating-for-ipfs.md +++ b/products/distributed-web/src/content/ipfs-gateway/updating-for-ipfs.md @@ -1,9 +1,9 @@ --- -title: Updating your Website for IPFS -alwaysopen: true -weight: 3 +order: 3 --- +# Updating your Website for IPFS + It's not required, but it is strongly recommended that websites hosted on IPFS use only relative links, unless linking to a different domain. This is because data can be accessed in many different (but ultimately equivalent) ways: diff --git a/products/randomness-beacon/src/content/about/Background.md b/products/randomness-beacon/src/content/about/Background.md index 901ba5ca8e6b35..a5fdb2b649f590 100644 --- a/products/randomness-beacon/src/content/about/Background.md +++ b/products/randomness-beacon/src/content/about/Background.md @@ -1,19 +1,19 @@ --- title: Background -weight: 10 +order: 1 --- -# Where did it all begin? +# Where did it all begin? Over the years, a generation of public randomness (often referred to as _common coins_) has attracted continuous interest from the cryptography research community. Many distributed systems, including various consensus mechanisms, anonymity networks such as Tor, or blockchain systems, assume access to such public randomness. However, it remained a major unsolved issue to generate public randomness in a distributed, scalable, and robust way. Currently, there is no service deployed to produce this type of randomness. The only choice is a centralized, prototype-only randomness beacon run by [NIST](https://www.nist.gov/). Realizing this, [Ewa Syta](http://ewa.syta.us/) started a project on [Scalable Bias-Resistant Distributed Randomness](https://eprint.iacr.org/2016/1067) during her PhD studies under the supervision of [Michael J. Fischer](http://www.cs.yale.edu/homes/fischer/) and [Bryan Ford](https://bford.info/) at Yale University. After Bryan moved to EPFL in 2015, the new members of the DEDIS team at EPFL ([Nicolas Gailly](https://github.com/nikkolasg/), [Linus Gasser](https://people.epfl.ch/linus.gasser), [Philipp Jovanovic](https://jovanovic.io/), [Ismail Khoffi](https://ismailkhoffi.com/), [Eleftherios Kokoris Kogias](https://lefteriskk.github.io/)) joined the project and together published a research paper at the [2017 IEEE Symposium on Security and Privacy](https://ieeexplore.ieee.org/abstract/document/7958592). - -The paper explored the use of key pairings instead of classical elliptic curve cryptography to generate public randomness as a way to simplify the proposed protocol designs and improve performance in terms of randomness generation and verification. -In early 2017, the [DEDIS](https://dedis.epfl.ch/) team at [EPFL](https://www.epfl.ch/en/) started collaborating with [DFINITY](https://dfinity.org/) on various research topics, inlcuding public randomness. The DFINITY architecture is built around a pairing-based randomness beacon sharing similarities to the constructs described in the DEDIS paper. Additionally, DFINITY has already implemented an optimized pairing library in C++. After integrating this implementation into the DEDIS’ crypto library [Kyber](https://github.com/dedis/kyber), all major cryptographic components were ready to implement an efficient, distributed randomness generation protocol using pairings. +The paper explored the use of key pairings instead of classical elliptic curve cryptography to generate public randomness as a way to simplify the proposed protocol designs and improve performance in terms of randomness generation and verification. + +In early 2017, the [DEDIS](https://dedis.epfl.ch/) team at [EPFL](https://www.epfl.ch/en/) started collaborating with [DFINITY](https://dfinity.org/) on various research topics, inlcuding public randomness. The DFINITY architecture is built around a pairing-based randomness beacon sharing similarities to the constructs described in the DEDIS paper. Additionally, DFINITY has already implemented an optimized pairing library in C++. After integrating this implementation into the DEDIS’ crypto library [Kyber](https://github.com/dedis/kyber), all major cryptographic components were ready to implement an efficient, distributed randomness generation protocol using pairings. In September 2017, Nicolas, a PhD student at DEDIS, started coding drand with the help of Philipp to deploy, for the first time, a distributed service providing public randomness in an application-agnostic, secure, and efficient way. A short time later, Cloudflare released an optimized Golang implementation of the BN256 pairing curve, which is now integrated in both Kyber and drand to simplify development and deployment. diff --git a/products/randomness-beacon/src/content/about/Drand.md b/products/randomness-beacon/src/content/about/Drand.md index 5abab1f495d607..1515e4476648a8 100644 --- a/products/randomness-beacon/src/content/about/Drand.md +++ b/products/randomness-beacon/src/content/about/Drand.md @@ -1,10 +1,9 @@ --- title: Drand Project -weight: 10 +order: 0 --- -## What is drand? - +# What is drand? The drand project aims to address the current lack of services providing distributed public randomness. Distributed to increase the reasilience and trustworthiness. drand provides a standalone randomness-as-a-service network that is application agnostic. For example, similar to NTP networks serving timing information accross the globe. drand follows the [KISS principle](https://en.wikipedia.org/wiki/KISS_principle), relying on well-researched cryptographic building blocks and open-source software design principles and libraries, such as protobuf and gRPC, to ensure high performance and interoperability. drand also attempts to use sane security defaults, such as having TLS enabled by default. diff --git a/products/randomness-beacon/src/content/about/future.md b/products/randomness-beacon/src/content/about/Future.md similarity index 92% rename from products/randomness-beacon/src/content/about/future.md rename to products/randomness-beacon/src/content/about/Future.md index 904f39167d9d51..7c62417a324f35 100644 --- a/products/randomness-beacon/src/content/about/future.md +++ b/products/randomness-beacon/src/content/about/Future.md @@ -1,9 +1,9 @@ --- title: Future of Drand -weight: 10 +order: 2 --- -## What do you see as the future of this project? +# What do you see as the future of this project? As of spring 2020, the drand network is production-ready, and we believe that it can now be considered foundational Internet infrastructure, much like DNS or BGP. diff --git a/products/randomness-beacon/src/content/about/index.md b/products/randomness-beacon/src/content/about/index.md index 67c4fd14fc644d..1926df579a9d22 100644 --- a/products/randomness-beacon/src/content/about/index.md +++ b/products/randomness-beacon/src/content/about/index.md @@ -1,9 +1,11 @@ --- -title: About -alwaysopen: true -weight: 10 -hidden: false -showNew: false +order: 1 --- -Learn more about [drand](https://drand.love/): a distributed service providing public randomness in an application-agnostic, secure, and efficient way. \ No newline at end of file +# About Drand + +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, unbiased, unpredictable random values at fixed intervals using bilinear pairings and threshold cryptography. + +Drand is meant to be an Internet infrastructure level service that provides randomness to applications, similar to how NTP provides timing information and Certificate Transparency servers provide certificate revocation information. + +For the most up-to-date documentation on drand, please visit [drand.love](https://drand.love). \ No newline at end of file diff --git a/products/randomness-beacon/src/content/cryptographic-background/index.md b/products/randomness-beacon/src/content/cryptographic-background/index.md index 04a341d223fd64..feee3d4d46c9cc 100644 --- a/products/randomness-beacon/src/content/cryptographic-background/index.md +++ b/products/randomness-beacon/src/content/cryptographic-background/index.md @@ -1,16 +1,16 @@ --- -title: Cryptographic Background -alwaysopen: true -weight: 30 +order: 2 --- -drand is an efficient randomness beacon daemon that utilizes pairing-based cryptography, `𝑡-of-𝑛` distributed key generation, and threshold BLS signatures to generate publicly-verifiable, unbiasable, unpredictable, distributed randomness. +# Cryptographic Background -This is an overview of the cryptographic building blocks drand uses to generate publicly-verifiable, unbiasable, and unpredictable randomness in a distributed manner. +drand is an efficient randomness beacon daemon that utilizes pairing-based cryptography, `𝑡-of-𝑛` distributed key generation, and threshold BLS signatures to generate publicly-verifiable, unbiasable, unpredictable, distributed randomness. -The drand beacon has two phases: a setup phase and a beacon phase. Generally, we assume that there are _n_ participants, out of which at most _f** -Note:** Even though the secret created using Pedersen’s DKG can be biased, it is safe to use for threshold signing as shown by Rabin et al. - - -In this section, we describe how to use this collective key pair to generate publicly-verifiable, unbiasable, and unpredictable randomness in a distributed manner. - -First, we explain pairing-based cryptography (PBC), which has become quite popular, and is used in many modern consensus protocols or zero-knowledge proofs, such as zk-SNARKs. We'll then show how drand uses PBC for the randomness beacon generation phase for threshold Boneh-Lynn-Shacham (BLS) signatures. Finally, we'll discuss how drand links the generated threshold BLS signatures into a randomness chain. - - - -# Pairing-based Cryptography - - -Pairing-based cryptography is based on bilinear groups `(𝔾1,𝔾2,𝔾𝑡)`, where `𝔾1`, `𝔾2`, and `𝔾𝑡` are cyclic groups of prime order `𝑝` with generators `𝑔1`, `𝑔2`, and `𝑔𝑡`, respectively, and a pairing operation `𝑒:𝔾1×𝔾2→𝔾𝑡` with these properties: - -- **Bilinearity:** `∀𝑎,𝑏∈ℤ∗𝑝,∀𝑃∈𝔾1,∀𝑄∈𝔾2,` we have `𝑒(𝑎𝑃,𝑏𝑄)=𝑒(𝑃,𝑄)𝑎𝑏` - -- **Non-degeneracy:** `𝑒≠1` -- **Computability:** There exists an efficient algorithm to compute `𝑒`. - drand currently uses the Barreto-Naehrig curve BN256. - - -# Randomness Generation - - -To generate publicly-verifiable, unbiasable, distributed randomness, drand utilizes threshold Boneh-Lynn-Shacham (BLS) signatures. First we'll describe regular BLS signatures and then the threshold variant. - -## BLS Signature - - - -BLS signatures are short signatures that rely on bilinear pairings and consist only of a single element in `𝔾1`. They are deterministic in the sense they depend only on the message and the signer’s key, unlike other signature schemes, such as ECDSA, that require a fresh random value for each signed message to be secure. Put differently, any two BLS signatures on a given message produced with the same key are identical. In drand, we utilize this property to achieve unbiasability for randomness generation. - -The BLS signature scheme consists of the these sub-procedures. - -**Key Generation** - -To generate a key pair, a signer first chooses a private key, `𝑥∈ℤ∗𝑝`, at random, and then computes the corresponding public key as `𝑋=𝑔𝑥2∈𝔾2`. - - - -**Signature Generation** - -Let `𝐻:{0,1}∗→𝔾1` denote a cryptographic hash function that maps arbitrary bit strings to elements of `𝔾1`. To compute a BLS signature `𝜎` on a message `𝑚`, the signer simply computes `𝜎=𝑥𝐻(𝑚)∈𝔾1`. - - - -**Signature Verification** - -To verify that a BLS signature `𝜎` on a message `𝑚` is valid, the verifier checks if `𝑒(𝐻(𝑚),𝑋)=𝑒(𝜎,𝑔2)` holds using the signer’s public key `𝑋`. - -It's easy to see that this equation holds for valid signatures since `𝑒(𝐻(𝑚),𝑋)=𝑒(𝐻(𝑚),𝑔𝑥2)=𝑒(𝐻(𝑚),𝑔2)𝑥=𝑒(𝑥𝐻(𝑚),𝑔2)=𝑒(𝜎,𝑔2)`. - -### Threshold BLS Signature - -The goal of a threshold signature scheme is to collectively compute a signature by combining individual partial signatures independently generated by the participants. A threshold BLS signature scheme has the following sub-procedures. - - -**Key Generation** - -The `𝑛` participants execute a `𝑡-of-𝑛` DKG to setup a collective public key, `𝑆∈𝔾2`, and private key shares `𝑠𝑖∈ℤ∗𝑝` of the unknown collective private key, `𝑠`, as described above. - - - -**Partial Signature Generation** - -To sign a message, `𝑚`, each `𝑖` uses their private key share, `𝑠𝑖`, to create a partial BLS signature, `𝜎𝑖=𝑠𝑖𝐻(𝑚)`. - - -**Partial Signature Verification** - -To verify the correctness of a partial signature, `𝜎𝑖`, on `𝑚`, a verifier uses the public key share, `𝑆𝑖`, generated during the DKG, and verifies that `𝑒(𝐻(𝑚),𝑆𝑖)=𝑒(𝜎𝑖,𝑔2)` holds. - - - -**Signature Reconstruction** - -To reconstruct the collective BLS signature, `𝜎` on `𝑚`, a verifier first gathers `𝑡` different and valid partial BLS signatures, `𝜎𝑖`, on `𝑚` followed by a Lagrange interpolation. - - - -**Signature Verification** - -To verify a collective BLS signature, `𝜎`, a verifier simply checks that `𝑒(𝐻(𝑚),𝑆)=𝑒(𝜎,𝑔2)` holds, where `𝑆` is the collective public key. - - - -Thanks to the properties of Lagrange interpolation, the value of `𝜎` is independent of the subset of `𝑡` valid partial signatures, `𝜎𝑖`, chosen during signature reconstruction. Additionally, Lagrange interpolation also guarantees that no set of less than `𝑡` signers can predict or bias `𝜎`. - -In summary, a threshold BLS signature, `𝜎`, exhibits all properties required for publicly-verifiable, unbiasable, unpredictable, and distributed randomness. - - - -## Chained Randomness - - -The drand randomness beacon operates in discrete rounds, `𝑟`. In every round, drand producess a new random value using threshold BLS signatures linked together into a chain of randomness. To extend this chain of randomness, each drand participant, `𝑖`, creates in round `𝑟` the partial BLS signature, `𝜎𝑟𝑖` on the message `𝑚=𝐻(𝑟∥𝜎𝑟−1)` where, `𝜎𝑟−1` denotes the (full) BLS threshold signature from round `𝑟−1` and `𝐻`, a cryptographic hash function. - -Once at least `𝑡` participants have broadcasted their partial signatures, `𝜎𝑟𝑖`, on `𝑚`, anyone can recover the full BLS threshold signature, `𝜎𝑟` that corresponds to the random value of round `𝑟`. After this, drand nodes move to round `𝑟+1` and reiterate the process. - -For round `𝑟=0`, drand participants sign a seed fixed during drand setup. This process ensures that every new random value depends on all previously generated signatures. Since the signature is deterministic, there is also no possibility for an adversary forking the chain and presenting two distinct signatures `𝜎𝑟` and `𝜎′𝑟` in a given round `𝑟` to generate inconsistencies in the systems relying on public randomness. \ No newline at end of file +**Note:** Even though the secret created using Pedersen’s DKG can be biased, it is safe to use for threshold signing as shown by Rabin et al. \ No newline at end of file diff --git a/products/randomness-beacon/src/content/index.md b/products/randomness-beacon/src/content/index.md index 00d83664d448ac..73e123514ba1f1 100644 --- a/products/randomness-beacon/src/content/index.md +++ b/products/randomness-beacon/src/content/index.md @@ -1,7 +1,11 @@ --- +title: Welcome order: 0 +type: overview --- -# Welcome +# Decentralized Verifiable Randomness Beacon -TODO... +Explore drand: a distributed service providing public randomness in an application-agnostic, secure, and efficient way + +Get started diff --git a/products/randomness-beacon/src/content/operator-guide/index.md b/products/randomness-beacon/src/content/operator-guide/index.md index a5920cded6dc28..7043c1109a227e 100644 --- a/products/randomness-beacon/src/content/operator-guide/index.md +++ b/products/randomness-beacon/src/content/operator-guide/index.md @@ -1,7 +1,7 @@ --- -title: Operator Guide -alwaysopen: true -weight: 40 +order: 4 --- +# Operator Guide + For the most up-to-date operator documentation, please visit [drand.love/operator](https://drand.love/operator/). \ No newline at end of file diff --git a/products/randomness-beacon/src/content/user-guide/index.md b/products/randomness-beacon/src/content/user-guide/index.md index bfa79b7d533af9..f50511c380980c 100644 --- a/products/randomness-beacon/src/content/user-guide/index.md +++ b/products/randomness-beacon/src/content/user-guide/index.md @@ -1,8 +1,7 @@ --- - -title: User Guide -alwaysopen: true -weight: 40 +order: 3 --- +# User Guide + For the most up-to-date user documentation, please visit [drand.love/developer](https://drand.love/developer/). \ No newline at end of file diff --git a/products/time-services/src/content/index.md b/products/time-services/src/content/index.md index 00d83664d448ac..743669dd2cce49 100644 --- a/products/time-services/src/content/index.md +++ b/products/time-services/src/content/index.md @@ -1,7 +1,11 @@ --- +title: Welcome order: 0 +type: overview --- -# Welcome +# Cloudflare Time Services -TODO... +Learn more about Cloudflare's suite of time services. + +NTP   NTS   Roughtime diff --git a/products/time-services/src/content/ntp/index.md b/products/time-services/src/content/ntp/index.md index ca74994c644455..fe865b4f2882cf 100644 --- a/products/time-services/src/content/ntp/index.md +++ b/products/time-services/src/content/ntp/index.md @@ -1,12 +1,10 @@ --- -title: Network Time Protocol (NTP) -alwaysopen: true -weight: 20 -hidden: false -showNew: false +order: 1 --- -[Network Time Protocol](https://tools.ietf.org/html/rfc1305) (NTP) is an Internet protocol designed to synchronize time between computer systems communicating over unreliable and variable-latency network paths. +# Network Time Protocol + +[Network Time Protocol](https://tools.ietf.org/html/rfc1305) (NTP) is an Internet protocol designed to synchronize time between computer systems communicating over unreliable and variable-latency network paths. NTP works by having a client send a query packet out to an NTP server that then responds with its clock time. The client then computes an estimate of the difference between its clock and the remote clock and attempts to compensate for network delay in this. NTP client queries multiple servers and implements algorithms to select the best estimate, and rejects clearly wrong answers. diff --git a/products/time-services/src/content/ntp/usage.md b/products/time-services/src/content/ntp/usage.md index 66fdb107bf4300..f2553166879a99 100644 --- a/products/time-services/src/content/ntp/usage.md +++ b/products/time-services/src/content/ntp/usage.md @@ -1,8 +1,10 @@ --- -title: Cloudflare's Time Service -weight: 10 +title: User Guide +order: 0 --- +# Using Cloudflare's Time Service + Cloudflare offers a free public time service that allows you to use our anycast network of 180+ locations to synchronize time from our closest server. To use our NTP server, change the time configuration in your device to point to ```time.cloudflare.com```. We do not implement leap smearing: NTP includes a Leap Indicator field [spec](https://tools.ietf.org/html/rfc5905#section-7.3) and the kernel will apply the leap second correction at the appropriate time. This is the behavior servers diff --git a/products/time-services/src/content/nts/index.md b/products/time-services/src/content/nts/index.md index a38e21c7259974..c46ffb654fe119 100644 --- a/products/time-services/src/content/nts/index.md +++ b/products/time-services/src/content/nts/index.md @@ -1,10 +1,9 @@ --- -title: Network Time Security (NTS) -alwaysopen: true -weight: 40 +order: 2 --- -Network Time Security (NTS) provides cryptographic security for the client-server mode of the Network Time Protocol (NTP). This enables users to obtain time in an authenticated manner. +# Network Time Security -The NTS protocol is divided into two-phases. The first phase is the NTS key exchange that establishes the necessary key material between the NTP client and the server. This phase uses the Transport Layer Security (TLS) handshake and relies on the same public key infrastructure as the web. Once the keys are exchanged, the TLS channel is closed and the protocol enters the second phase. In this phase the results of that TLS handshake are used to authenticate NTP time synchronization packets via extension fields. For more information, read the [Internet draft](https://tools.ietf.org/html/draft-ietf-ntp-using-nts-for-ntp-19). +Network Time Security (NTS) provides cryptographic security for the client-server mode of the Network Time Protocol (NTP). This enables users to obtain time in an authenticated manner. +The NTS protocol is divided into two-phases. The first phase is the NTS key exchange that establishes the necessary key material between the NTP client and the server. This phase uses the Transport Layer Security (TLS) handshake and relies on the same public key infrastructure as the web. Once the keys are exchanged, the TLS channel is closed and the protocol enters the second phase. In this phase the results of that TLS handshake are used to authenticate NTP time synchronization packets via extension fields. For more information, read [RFC 8915](https://tools.ietf.org/html/rfc8915). diff --git a/products/time-services/src/content/nts/usage.md b/products/time-services/src/content/nts/usage.md index a9ec44701031e8..cc7da841bde748 100644 --- a/products/time-services/src/content/nts/usage.md +++ b/products/time-services/src/content/nts/usage.md @@ -1,19 +1,15 @@ --- -title: Secure Time Service -weight: 10 +title: User Guide +order: 0 --- -## NTS Client +# Using Cloudflare's Secure Time Service -You can use time.cloudflare.com as the source of time for all your devices today with NTP, while NTS clients are still under development. +[Chrony](https://chrony.tuxfamily.org/doc/devel/chrony.conf.html) and [NTPSec](https://www.ntpsec.org/) have support for NTS. Please read the relevant documentation for guidance on setting them up to point to our time service, `time.cloudflare.com`. -Cloudflare is working on an NTS client. If you would like to get updates about our NTS client development, email us at `time-services@cloudflare.com` to join the mailing list. - -There are currently a few organizations working on NTS Client [implementations](https://tools.ietf.org/html/draft-ietf-ntp-using-nts-for-ntp-19#page-30). [NTPsec](https://www.ntpsec.org/) is one of the organizations that includes experimental support for NTS; go to https://docs.ntpsec.org/latest/NTS-QuickStart.html for more information on NTPsec's implementation of an NTS client. - -## NTS Server - -Cloudflare's time service allows users to connect to our NTP server that supports Network Time Security, enabling users to obtain time in an authenticated manner. Anyone with an NTS supported client can obtain secure time by pointing their client to time.cloudflare.com:1234. Our NTS server supports both NTP and NTS, so while you can use any NTP client to get unauthenticated time, you can also use publicly available NTS clients to get secure time. - -Cloudflare’s time service will allow users to connect to our Network Time Protocol (NTP) server that supports Network Time Security (NTS), enabling users to obtain time in an authenticated manner. Anyone with an NTS supported client can obtain secure time by pointing their client to `time.cloudflare.com:1234`. +## Time Services Mailing List +If you would like to hear about the development of additional clients, +updates on our service, or would like to announce that your client +supports NTS, please email `time-services@cloudflare.com` to be added +to our distribution list. diff --git a/products/time-services/src/content/roughtime/about.md b/products/time-services/src/content/roughtime/about.md index 7a86c3cba7af6a..25021ce98277a4 100644 --- a/products/time-services/src/content/roughtime/about.md +++ b/products/time-services/src/content/roughtime/about.md @@ -1,9 +1,9 @@ --- -title: The protocol -alwaysopen: true -weight: 1 +order: 0 --- +# Roughtime Protocol + Endpoints on the Internet often synchronize their clocks using the Network Time Protocol ([NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)). NTP provides precise synchronization, but is frequently deployed without a means of diff --git a/products/time-services/src/content/roughtime/index.md b/products/time-services/src/content/roughtime/index.md index 8345a28697616e..1823631c2d7a57 100644 --- a/products/time-services/src/content/roughtime/index.md +++ b/products/time-services/src/content/roughtime/index.md @@ -1,9 +1,9 @@ --- -title: Roughtime -alwaysopen: true -weight: 60 +order: 3 --- +# Roughtime + [Roughtime](https://roughtime.googlesource.com/roughtime) is a simple, flexible, and secure authenticated time protocol developed by Google. This page introduces the key concepts of the protocol and demonstrates how to use Cloudflare's diff --git a/products/time-services/src/content/roughtime/recipes.md b/products/time-services/src/content/roughtime/recipes.md index 46d3eeba7cabcc..edc968986f1ba4 100644 --- a/products/time-services/src/content/roughtime/recipes.md +++ b/products/time-services/src/content/roughtime/recipes.md @@ -1,9 +1,9 @@ --- -title: How to use it -alwaysopen: true -weight: 2 +order: 2 --- +# Advanced Usage + This section describes a few ways you can use Roughtime to keep your clock in sync. These recipes will use Cloudflare's Go package, which is available on [GitHub](https://github.com/cloudflare/roughtime). It's based on Google's [Go diff --git a/products/time-services/src/content/roughtime/usage.md b/products/time-services/src/content/roughtime/usage.md index ec7adb183efa31..f7956cd48f2fdd 100644 --- a/products/time-services/src/content/roughtime/usage.md +++ b/products/time-services/src/content/roughtime/usage.md @@ -1,8 +1,10 @@ --- -title: Cloudflare-Roughtime -alwaysopen: true -weight: 10 +title: User Guide +order: 1 --- + +# Using Cloudflare's Roughtime Service + Our service can be reached at `roughtime.cloudflare.com:2002`. The domain resolves to an IP address in our [anycast IP range](https://www.cloudflare.com/learning/cdn/glossary/anycast-network/). You