Giter VIP home page Giter VIP logo

zkdocs's Introduction

ZKDocs

ZKDocs provides comprehensive, detailed, and interactive documentation on zero-knowledge proof systems and related primitives.

At Trail of Bits, we audit many implementations of non-standardized cryptographic protocols and often find the same issues. As we discovered more instances of these bugs, we wanted to find a way to prevent them in the future. Unfortunately, for these protocols, the burden is on the developers to figure out all of the low-level implementation details and security pitfalls.

We hope that ZKDocs can fill in this gap and benefit the larger cryptography community.

Comprehensive

We aim to be both self-contained and comprehensive in the topics related to zero-knowledge proof systems, from descriptions of simple systems like Schnorr’s identification protocol, to complex proof systems like Paillier-Blum modulus. We also cover cryptographic primitives such as: random sampling, Fiat-Shamir transformation, and Shamir's Secret Sharing.

Detailed

We describe each protocol in great detail, including all necessary setup, sanity-checks, auxiliary algorithms, further references, and potential security pitfalls with their associated severity.

Interactive

The protocol descriptions are interactive, letting you modify variable names. This allows you to match the variable names in ZKdocs' specification to the variable names in your code, making it easier to find bugs and missing assertions.

Basic interactivity usage

Interactivity features:

  • Click on a variable to highlight it across the document.
  • Type or paste with a variable highlighted to edit its name. Press Enter or Escape to stop editing.
  • Press the Reset variables names button to reset the names of all variables on the current page (variable names are independent across different pages)

Roadmap

Zero-knowledge proof systems

  • Schnorr basic identification protocol
  • Schnorr variants
  • Product of primes
  • Square-free zkp
  • Short proofs for factoring
  • Girault's identification
  • Paillier-Blum Modulus ZK
  • Discrete log equality
  • Ring-Pedersen Parameters ZK
  • STARK
  • Paillier range proofs
  • Bulletproofs
  • Sonic
  • Plonk

Primitives

  • Fiat-Shamir transformation
  • Rejection sampling
  • Nothing-up-my-sleeve constructions
  • Shamir secret sharing
  • Feldman's VSS
  • Fujisaki-Okamoto commitments
  • Pedersen commitments
  • HVZK and NIZK

Common attacks and issues

  • Using HVZKP in the wrong context: two attacks when verifiers are not so honest
  • Golden-shoe attack
  • Alpha-rays: attacking others by having short keys
  • Replay attacks on ZKPs

Dependencies

  • hugo - install with

    brew install hugo

Running locally

  • hugo server --minify --theme book

How to contribute

  • The file schnorr.md is an example of a complete protocol.
  • interactive_variables.js has all the variable renaming logic.
  • The Sigma protocols are structured in latex in 3 columns: Alice column, arrow_column, Verifier column. To write the protocols, you can use helpful latex macros:
    • \work{Work for Alice}{Work for Bob} - writes work in both Alice's and Bob's column
    • \alicework{Work for Alice}, \bobwork{Work for Bob} - writes work for either Alice or Bob
    • \alicebob{Alice work}{message description}{Bob work}, \bobalice{Alice work}{message description}{Bob work} - writes an arrow from alice to bob, or from bob to alice
    • In markdown you would write
{{< rawhtml >}}
 $$
 \begin{array}{c}
 \work{\varprover}{\varverifier}
 \alicework{\samplezqs{\varr}}
 \alicework{\varu = \varg^\varr}
 \alicebob{}{\varu}{}
 \bobwork{\sample{\varc}}
 \bobalice{}{\varc}{}
 \alicework{\varz = \varr + \varx\cdot \varc}
 \alicebob{}{\varz}{}
 \bobwork{\varg^{\varz} \equalQ \varu \cdot \varh^\varc }
 \end{array}
 $$
{{< /rawhtml >}}
  • header.html has all latex macros if more need to be added. In particular it includes all interactive variable macros that the javascript handles afterwards. So, if you write $\varz$ it will default to a z but the user can change its name anywhere on the page.

zkdocs's People

Contributors

artemdinaburg avatar cdahlheimer avatar elopez avatar fcasal avatar robinjadoul avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

zkdocs's Issues

"Short factoring proofs" - inconsistent parameters

In the article "Short factoring proofs" under "Security parameters:" you list among others "$m$, and $K$". However, $K$ is never used in the rest of the article. Instead, $m$ takes the role of $K$ (from the original paper [PS00]), denoting the number of $z_i$'s. I suggest to rename $m$ to $K$, or vice versa, so that there are no more redundant security parameters.
Also, it would be nice to give more details on the choice of $K$/$m$ in the respective section "Choice of security parameters". For example, you write "$B$ and $\ell$ should satisfy $\ell \cdot \log B = \theta(k)$", so you could add something like "$K$/$m$ should be approximately equal to $k$" (or, heuristically, even smaller, cf. [PS00]).

Short factoring proofs: Addition of phi(N)

In the short factoring proof, there is the line $y = r + (N - \varphi(N))e$. In the vanilla protocol, the verifier checks $x \overset{?}{\equiv} z^{y - eN} \mod N$. Because $\varphi(N)$ is the order of the multiplicative group of integers modulo $N$, taking the exponent of a multiple of $\varphi(N)$ gives you the identity 1 for all group elements, so $z^{\varphi(N)e} \equiv 1 \mod N$. This is my understanding how the protocol works.

I was wondering, can we define $y = r + (N + \varphi(N))e$ instead? The minus sign seems redundant to me and the above argument should still work, shouldn't it?

More Detailed Justification for Recommending Large Primes for SSSS

In practice, p should be reasonably large. Breaking S into multiple parts introduces complexity and opportunities for malicious actors. Also, in some verifiable secret sharing schemes, a large p is needed to prevent discrete log attacks.

This advice seems to go against a very common field choice of GF(2^8). As such, I’m personally curious to better understand the argument against (if that is the argument), and generally I think a deeper explanation (or link or reference to one) would be a good idea!

Elligator 2 for indistinguishable from random points

I don't know to which extent you plan to document less well known algorithms, but here is one that is crucial for designing cryptographic formats that do not reveal that they are encrypted text but can still have public key encryption.

While there is some documentation on the Elligator 2 itself, namely a research paper, and while the use of the algorithm is somewhat general knowledge among cryptographic circles, almost no-one knows how to actually implement it securely.

The background is that most formats need to store an ephemeral public key in plain text, and if this is a Curve25519 point, what is stored is a 32-byte value, where the highest bit is always zero, only half of the remaining 255 bit values encode valid points, only 1/8 of those are in the prime group. All these combined, 32 bytes of random data have only 1/32 chance of being a normal public key. An adversary can quickly test for all these things and thus keys can be easily distinguished from random bytes.

Fixing it is a whole lot more complicated than just using Elligator 2 and inserting a few random bits to fill in the blanks. One also has to randomise the subgroups, to avoid only using the prime group, which fortunately stays compatible with standard ECDH (no need to project back to prime group first).

The existing documentation is within Monocypher source code, Covert Encryption source code, and in some Github discussions and old Reddit comments. It would be quite valuable if someone created proper documentation for it, so that not everybody else needs to do the same trial and error that we had to. Let me know if you are interested and I'll collect you the relevant links to get started.

Such documentation could work as a good primer to Ed25519/Curve25519 in general, as all the points can be visualised as a simple rectangle with 8 columns and q rows (~2**252), the low order points on the top row and the prime group on the left column. The neutral element (zero point) is at the top left corner. To hide points, we want to make use of all the columns but still correspond to the standard point on the left column on that same row. It turns out that point add/scalarmult are just adding or multiplying vectors in these rectangle coordinates (columns mod 8, rows mod q), so it can be visualised neatly. The base point is (row 1, column 0) so multiplying it by any number goes to row by that number but stays in the left column.

"Paillier-Blum Modulus" parameter choice reference

On the Paillier-Blum Modulus page (content/docs/zkdocs/zero-knowledge-protocols/product-primes/paillier_blum_modulus.md), it mentions choosing a modulus size of 2048 to get 80 bits of security. By any chance, could someone include a reference for why this modulus size yields this security and ideally which size is needed to target different security levels?

Thanks

as a standalone?

Hey hey,

This project is amazing! Have you thought about releasing this as something that can be used individually by projects to spec their protocols? I would probably use it in a heartbeat :)

HACSpec

Thanks for the nice project! There are some overlaps in goals with the hacspec project.
Cryptographic primitives have been specified there, and some work on ZK proofs is underway.

There may be some opportunities for collaboration in the future, so I wanted to give you a heads-up.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.