README

Docs Build Status

DEDIS Advanced Crypto Library for Go

This package provides a toolbox of advanced cryptographic primitives for Go, targeting applications like Cothority that need more than straightforward signing and encryption. Please see the Godoc documentation for this package for details on the library's purpose and API functionality.

This package includes a mix of variable time and constant time implementations. If your application is sensitive to timing-based attacks and you need to constrain Kyber to offering only constant time implementations, you should use the suites.RequireConstantTime() function in the init() function of your main package.

Versioning - Development

We use the following versioning model:

  • crypto.v0 was the first semi-stable version. See migration notes.
  • kyber.v1 never existed, in order to keep kyber, onet and cothorithy versions linked
  • gopkg.in/dedis/kyber.v2 was the last stable version
  • Starting with v3.0.0, kyber is a Go module, and we respect semantic versioning.

So if you depend on the master branch, you can expect breakages from time to time. If you need something that doesn't change in a backward-compatible way you should use have a go.mod file in the directory where your main package is.

Installing

First make sure you have Go version 1.8 or newer installed.

The basic crypto library requires only Go and a few third-party Go-language dependencies that can be installed automatically as follows:

go get go.dedis.ch/kyber

You should then be able to test its basic function as follows:

go test -v

You can recursively test all the packages in the library as follows:

go test -v ./...

A note on deriving shared secrets

Traditionally, ECDH (Elliptic curve Diffie-Hellman) derives the shared secret from the x point only. In this framework, you can either manually retrieve the value or use the MarshalBinary method to take the combined (x, y) value as the shared secret. We recommend the latter process for new softare/protocols using this framework as it is cleaner and generalizes across different types of groups (e.g., both integer and elliptic curves), although it will likely be incompatible with other implementations of ECDH. See the Wikipedia page on ECDH.

Expand ▾ Collapse ▴

Documentation

Overview

Package kyber provides a toolbox of advanced cryptographic primitives, for applications that need more than straightforward signing and encryption. This top level package defines the interfaces to cryptographic primitives designed to be independent of specific cryptographic algorithms, to facilitate upgrading applications to new cryptographic algorithms or switching to alternative algorithms for experimentation purposes.

Abstract Groups

This toolkits public-key crypto API includes a kyber.Group interface supporting a broad class of group-based public-key primitives including DSA-style integer residue groups and elliptic curve groups. Users of this API can write higher-level crypto algorithms such as zero-knowledge proofs without knowing or caring exactly what kind of group, let alone which precise security parameters or elliptic curves, are being used. The kyber.Group interface supports the standard algebraic operations on group elements and scalars that nontrivial public-key algorithms tend to rely on. The interface uses additive group terminology typical for elliptic curves, such that point addition is homomorphically equivalent to adding their (potentially secret) scalar multipliers. But the API and its operations apply equally well to DSA-style integer groups.

As a trivial example, generating a public/private keypair is as simple as:

    suite := suites.MustFind("Ed25519")		// Use the edwards25519-curve
	a := suite.Scalar().Pick(suite.RandomStream()) // Alice's private key
	A := suite.Point().Mul(a, nil)          // Alice's public key

The first statement picks a private key (Scalar) from a the suites's source of cryptographic random or pseudo-random bits, while the second performs elliptic curve scalar multiplication of the curve's standard base point (indicated by the 'nil' argument to Mul) by the scalar private key 'a'. Similarly, computing a Diffie-Hellman shared secret using Alice's private key 'a' and Bob's public key 'B' can be done via:

S := suite.Point().Mul(a, B)		// Shared Diffie-Hellman secret

Note that we use 'Mul' rather than 'Exp' here because the library uses the additive-group terminology common for elliptic curve crypto, rather than the multiplicative-group terminology of traditional integer groups - but the two are semantically equivalent and the interface itself works for both elliptic curve and integer groups.

Higher-level Building Blocks

Various sub-packages provide several specific implementations of these cryptographic interfaces. In particular, the 'group/mod' sub-package provides implementations of modular integer groups underlying conventional DSA-style algorithms. The `group/nist` package provides NIST-standardized elliptic curves built on the Go crypto library. The 'group/edwards25519' sub-package provides the kyber.Group interface using the popular Ed25519 curve.

Other sub-packages build more interesting high-level cryptographic tools atop these primitive interfaces, including:

- share: Polynomial commitment and verifiable Shamir secret splitting for implementing verifiable 't-of-n' threshold cryptographic schemes. This can be used to encrypt a message so that any 2 out of 3 receivers must work together to decrypt it, for example.

- proof: An implementation of the general Camenisch/Stadler framework for discrete logarithm knowledge proofs. This system supports both interactive and non-interactive proofs of a wide variety of statements such as, "I know the secret x associated with public key X or I know the secret y associated with public key Y", without revealing anything about either secret or even which branch of the "or" clause is true.

- sign: The sign directory contains different signature schemes.

- sign/anon provides anonymous and pseudonymous public-key encryption and signing, where the sender of a signed message or the receiver of an encrypted message is defined as an explicit anonymity set containing several public keys rather than just one. For example, a member of an organization's board of trustees might prove to be a member of the board without revealing which member she is.

- sign/cosi provides collective signature algorithm, where a bunch of signers create a unique, compact and efficiently verifiable signature using the Schnorr signature as a basis.

- sign/eddsa provides a kyber-native implementation of the EdDSA signature scheme.

- sign/schnorr provides a basic vanilla Schnorr signature scheme implementation.

- shuffle: Verifiable cryptographic shuffles of ElGamal ciphertexts, which can be used to implement (for example) voting or auction schemes that keep the sources of individual votes or bids private without anyone having to trust more than one of the shuffler(s) to shuffle votes/bids honestly.

Disclaimer

For now this library should currently be considered experimental: it will definitely be changing in non-backward-compatible ways, and it will need independent security review before it should be considered ready for use in security-critical applications. However, we intend to bring the library closer to stability and real-world usability as quickly as development resources permit, and as interest and application demand dictates.

As should be obvious, this library is intended to be used by developers who are at least moderately knowledgeable about cryptography. If you want a crypto library that makes it easy to implement "basic crypto" functionality correctly - i.e., plain public-key encryption and signing - then [NaCl secretbox](https://godoc.org/golang.org/x/crypto/nacl/secretbox) may be a better choice. This toolkit's purpose is to make it possible - and preferably easy - to do slightly more interesting things that most current crypto libraries don't support effectively. The one existing crypto library that this toolkit is probably most comparable to is the Charm rapid prototyping library for Python (https://charm-crypto.com/category/charm).

This library incorporates and/or builds on existing code from a variety of sources, as documented in the relevant sub-packages.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AllowsVarTime

type AllowsVarTime interface {
	AllowVarTime(bool)
}

    AllowsVarTime allows callers to determine if a given kyber.Scalar or kyber.Point supports opting-in to variable time operations. If an object implements AllowsVarTime, then the caller can use AllowVarTime(true) in order to allow variable time operations on that object until AllowVarTime(false) is called. Variable time operations may be faster, but also risk leaking information via a timing side channel. Thus they are only safe to use on public Scalars and Points, never on secret ones.

    type Encoding

    type Encoding interface {
    	// Encode and write objects to an io.Writer.
    	Write(w io.Writer, objs ...interface{}) error
    
    	// Read and decode objects from an io.Reader.
    	Read(r io.Reader, objs ...interface{}) error
    }

      Encoding represents an abstract interface to an encoding/decoding that can be used to marshal/unmarshal objects to and from streams. Different Encodings will have different constraints, of course. Two implementations are available:

      1. The protobuf encoding using the variable length Google Protobuf encoding
         scheme. The library is available at https://go.dedis.ch/protobuf
      2. The fixbuf encoding, a fixed length binary encoding of arbitrary
         structures. The library is available at https://go.dedis.ch/fixbuf.
      

      type Group

      type Group interface {
      	String() string
      
      	ScalarLen() int // Max length of scalars in bytes
      	Scalar() Scalar // Create new scalar
      
      	PointLen() int // Max length of point in bytes
      	Point() Point  // Create new point
      }

        Group interface represents a mathematical group usable for Diffie-Hellman key exchange, ElGamal encryption, and the related body of public-key cryptographic algorithms and zero-knowledge proof methods. The Group interface is designed in particular to be a generic front-end to both traditional DSA-style modular arithmetic groups and ECDSA-style elliptic curves: the caller of this interface's methods need not know or care which specific mathematical construction underlies the interface.

        The Group interface is essentially just a "constructor" interface enabling the caller to generate the two particular types of objects relevant to DSA-style public-key cryptography; we call these objects Points and Scalars. The caller must explicitly initialize or set a new Point or Scalar object to some value before using it as an input to some other operation involving Point and/or Scalar objects. For example, to compare a point P against the neutral (identity) element, you might use P.Equal(suite.Point().Null()), but not just P.Equal(suite.Point()).

        It is expected that any implementation of this interface should satisfy suitable hardness assumptions for the applicable group: e.g., that it is cryptographically hard for an adversary to take an encrypted Point and the known generator it was based on, and derive the Scalar with which the Point was encrypted. Any implementation is also expected to satisfy the standard homomorphism properties that Diffie-Hellman and the associated body of public-key cryptography are based on.

        type HashFactory

        type HashFactory interface {
        	Hash() hash.Hash
        }

          A HashFactory is an interface that can be mixed in to local suite definitions.

          type Marshaling

          type Marshaling interface {
          	encoding.BinaryMarshaler
          	encoding.BinaryUnmarshaler
          
          	// String returns the human readable string representation of the object.
          	String() string
          
          	// Encoded length of this object in bytes.
          	MarshalSize() int
          
          	// Encode the contents of this object and write it to an io.Writer.
          	MarshalTo(w io.Writer) (int, error)
          
          	// Decode the content of this object by reading from an io.Reader.
          	// If r is an XOF, it uses r to pick a valid object pseudo-randomly,
          	// which may entail reading more than Len bytes due to retries.
          	UnmarshalFrom(r io.Reader) (int, error)
          }

            Marshaling is a basic interface representing fixed-length (or known-length) cryptographic objects or structures having a built-in binary encoding. Implementors must ensure that calls to these methods do not modify the underlying object so that other users of the object can access it concurrently.

            type Point

            type Point interface {
            	Marshaling
            
            	// Equality test for two Points derived from the same Group.
            	Equal(s2 Point) bool
            
            	// Null sets the receiver to the neutral identity element.
            	Null() Point
            
            	// Base sets the receiver to this group's standard base point.
            	Base() Point
            
            	// Pick sets the receiver to a fresh random or pseudo-random Point.
            	Pick(rand cipher.Stream) Point
            
            	// Set sets the receiver equal to another Point p.
            	Set(p Point) Point
            
            	// Clone clones the underlying point.
            	Clone() Point
            
            	// Maximum number of bytes that can be embedded in a single
            	// group element via Pick().
            	EmbedLen() int
            
            	// Embed encodes a limited amount of specified data in the
            	// Point, using r as a source of cryptographically secure
            	// random data.  Implementations only embed the first EmbedLen
            	// bytes of the given data.
            	Embed(data []byte, r cipher.Stream) Point
            
            	// Extract data embedded in a point chosen via Embed().
            	// Returns an error if doesn't represent valid embedded data.
            	Data() ([]byte, error)
            
            	// Add points so that their scalars add homomorphically.
            	Add(a, b Point) Point
            
            	// Subtract points so that their scalars subtract homomorphically.
            	Sub(a, b Point) Point
            
            	// Set to the negation of point a.
            	Neg(a Point) Point
            
            	// Multiply point p by the scalar s.
            	// If p == nil, multiply with the standard base point Base().
            	Mul(s Scalar, p Point) Point
            }

              Point represents an element of a public-key cryptographic Group. For example, this is a number modulo the prime P in a DSA-style Schnorr group, or an (x, y) point on an elliptic curve. A Point can contain a Diffie-Hellman public key, an ElGamal ciphertext, etc.

              type Random

              type Random interface {
              	// RandomStream returns a cipher.Stream that produces a
              	// cryptographically random key stream. The stream must
              	// tolerate being used in multiple goroutines.
              	RandomStream() cipher.Stream
              }

                Random is an interface that can be mixed in to local suite definitions.

                type Scalar

                type Scalar interface {
                	Marshaling
                
                	// Equality test for two Scalars derived from the same Group.
                	Equal(s2 Scalar) bool
                
                	// Set sets the receiver equal to another Scalar a.
                	Set(a Scalar) Scalar
                
                	// Clone creates a new Scalar with the same value.
                	Clone() Scalar
                
                	// SetInt64 sets the receiver to a small integer value.
                	SetInt64(v int64) Scalar
                
                	// Set to the additive identity (0).
                	Zero() Scalar
                
                	// Set to the modular sum of scalars a and b.
                	Add(a, b Scalar) Scalar
                
                	// Set to the modular difference a - b.
                	Sub(a, b Scalar) Scalar
                
                	// Set to the modular negation of scalar a.
                	Neg(a Scalar) Scalar
                
                	// Set to the multiplicative identity (1).
                	One() Scalar
                
                	// Set to the modular product of scalars a and b.
                	Mul(a, b Scalar) Scalar
                
                	// Set to the modular division of scalar a by scalar b.
                	Div(a, b Scalar) Scalar
                
                	// Set to the modular inverse of scalar a.
                	Inv(a Scalar) Scalar
                
                	// Set to a fresh random or pseudo-random scalar.
                	Pick(rand cipher.Stream) Scalar
                
                	// SetBytes sets the scalar from a byte-slice,
                	// reducing if necessary to the appropriate modulus.
                	// The endianess of the byte-slice is determined by the
                	// implementation.
                	SetBytes([]byte) Scalar
                }

                  Scalar represents a scalar value by which a Point (group element) may be encrypted to produce another Point. This is an exponent in DSA-style groups, in which security is based on the Discrete Logarithm assumption, and a scalar multiplier in elliptic curve groups.

                  type XOF

                  type XOF interface {
                  	// Write absorbs more data into the hash's state. It panics if called
                  	// after Read. Use Reseed() to reset the XOF into a state where more data
                  	// can be absorbed via Write.
                  	io.Writer
                  
                  	// Read reads more output from the hash. It returns io.EOF if the
                  	// limit of available data for reading has been reached.
                  	io.Reader
                  
                  	// An XOF implements cipher.Stream, so that callers can use XORKeyStream
                  	// to encrypt/decrypt data. The key stream is read from the XOF using
                  	// the io.Reader interface. If Read returns an error, then XORKeyStream
                  	// will panic.
                  	cipher.Stream
                  
                  	// Reseed makes an XOF writeable again after it has been read from
                  	// by sampling a key from it's output and initializing a fresh XOF implementation
                  	// with that key.
                  	Reseed()
                  
                  	// Clone returns a copy of the XOF in its current state.
                  	Clone() XOF
                  }

                    An XOF is an extendable output function, which is a cryptographic primitive that can take arbitrary input in the same way a hash function does, and then create a stream of output, up to a limit determined by the size of the internal state of the hash function the underlies the XOF.

                    When XORKeyStream is called with zeros for the source, an XOF also acts as a PRNG. If it is seeded with an appropriate amount of keying material, it is a cryptographically secure source of random bits.

                    type XOFFactory

                    type XOFFactory interface {
                    	// XOF creates a new XOF, feeding seed to it via it's Write method. If seed
                    	// is nil or []byte{}, the XOF is left unseeded, it will produce a fixed, predictable
                    	// stream of bits (Caution: this behavior is useful for testing but fatal for
                    	// production use).
                    	XOF(seed []byte) XOF
                    }

                      An XOFFactory is an interface that can be mixed in to local suite definitions.

                      Directories

                      Path Synopsis
                      encrypt
                      ecies
                      Package ecies implements the Elliptic Curve Integrated Encryption Scheme (ECIES).
                      Package ecies implements the Elliptic Curve Integrated Encryption Scheme (ECIES).
                      Package examples provides a suite of tests showing how to use the different abstraction and protocols provided by the kyber library.
                      Package examples provides a suite of tests showing how to use the different abstraction and protocols provided by the kyber library.
                      group
                      curve25519
                      Package curve25519 contains several implementations of Twisted Edwards Curves, from general and unoptimized to highly specialized and optimized.
                      Package curve25519 contains several implementations of Twisted Edwards Curves, from general and unoptimized to highly specialized and optimized.
                      edwards25519
                      Package edwards25519 provides an optimized Go implementation of a Twisted Edwards curve that is isomorphic to Curve25519.
                      Package edwards25519 provides an optimized Go implementation of a Twisted Edwards curve that is isomorphic to Curve25519.
                      mod
                      Package mod contains a generic implementation of finite field arithmetic on integer fields with a constant modulus.
                      Package mod contains a generic implementation of finite field arithmetic on integer fields with a constant modulus.
                      nist
                      Package nist implements cryptographic groups and ciphersuites based on the NIST standards, using Go's built-in crypto library.
                      Package nist implements cryptographic groups and ciphersuites based on the NIST standards, using Go's built-in crypto library.
                      Package proof implements generic support for Sigma-protocols and discrete logarithm proofs in the Camenisch/Stadler framework.
                      Package proof implements generic support for Sigma-protocols and discrete logarithm proofs in the Camenisch/Stadler framework.
                      dleq
                      Package dleq provides functionality to create and verify non-interactive zero-knowledge (NIZK) proofs for the equality (EQ) of discrete logarithms (DL).
                      Package dleq provides functionality to create and verify non-interactive zero-knowledge (NIZK) proofs for the equality (EQ) of discrete logarithms (DL).
                      Package share implements Shamir secret sharing and polynomial commitments.
                      Package share implements Shamir secret sharing and polynomial commitments.
                      dkg/pedersen
                      Package dkg implements a general distributed key generation (DKG) framework.
                      Package dkg implements a general distributed key generation (DKG) framework.
                      dkg/rabin
                      Package dkg implements the protocol described in "Secure Distributed Key Generation for Discrete-Log Based Cryptosystems" by R. Gennaro, S. Jarecki, H. Krawczyk, and T. Rabin.
                      Package dkg implements the protocol described in "Secure Distributed Key Generation for Discrete-Log Based Cryptosystems" by R. Gennaro, S. Jarecki, H. Krawczyk, and T. Rabin.
                      pvss
                      Package pvss implements public verifiable secret sharing as introduced in "A Simple Publicly Verifiable Secret Sharing Scheme and its Application to Electronic Voting" by Berry Schoenmakers.
                      Package pvss implements public verifiable secret sharing as introduced in "A Simple Publicly Verifiable Secret Sharing Scheme and its Application to Electronic Voting" by Berry Schoenmakers.
                      vss/pedersen
                      Package vss implements the verifiable secret sharing scheme from "Non-Interactive and Information-Theoretic Secure Verifiable Secret Sharing" by Torben Pryds Pedersen.
                      Package vss implements the verifiable secret sharing scheme from "Non-Interactive and Information-Theoretic Secure Verifiable Secret Sharing" by Torben Pryds Pedersen.
                      vss/rabin
                      Package vss implements the verifiable secret sharing scheme from the paper "Provably Secure Distributed Schnorr Signatures and a (t, n) Threshold Scheme for Implicit Certificates".
                      Package vss implements the verifiable secret sharing scheme from the paper "Provably Secure Distributed Schnorr Signatures and a (t, n) Threshold Scheme for Implicit Certificates".
                      Package shuffle implements Andrew Neff's verifiable shuffle proof scheme.
                      Package shuffle implements Andrew Neff's verifiable shuffle proof scheme.
                      sign
                      anon
                      Package anon implements cryptographic primitives for anonymous communication.
                      Package anon implements cryptographic primitives for anonymous communication.
                      bls
                      Package bls implements the Boneh-Lynn-Shacham (BLS) signature scheme which was introduced in the paper "Short Signatures from the Weil Pairing".
                      Package bls implements the Boneh-Lynn-Shacham (BLS) signature scheme which was introduced in the paper "Short Signatures from the Weil Pairing".
                      cosi
                      Package cosi implements the collective signing (CoSi) algorithm as presented in the paper "Keeping Authorities 'Honest or Bust' with Decentralized Witness Cosigning" by Ewa Syta et al.
                      Package cosi implements the collective signing (CoSi) algorithm as presented in the paper "Keeping Authorities 'Honest or Bust' with Decentralized Witness Cosigning" by Ewa Syta et al.
                      dss
                      Package dss implements the Distributed Schnorr Signature protocol from the paper "Provably Secure Distributed Schnorr Signatures and a (t, n) Threshold Scheme for Implicit Certificates".
                      Package dss implements the Distributed Schnorr Signature protocol from the paper "Provably Secure Distributed Schnorr Signatures and a (t, n) Threshold Scheme for Implicit Certificates".
                      eddsa
                      Package eddsa implements the EdDSA signature algorithm according to RFC8032.
                      Package eddsa implements the EdDSA signature algorithm according to RFC8032.
                      schnorr
                      Package schnorr implements the vanilla Schnorr signature scheme.
                      Package schnorr implements the vanilla Schnorr signature scheme.
                      tbls
                      Package tbls implements the (t,n)-threshold Boneh-Lynn-Shacham signature scheme.
                      Package tbls implements the (t,n)-threshold Boneh-Lynn-Shacham signature scheme.
                      Package suites allows callers to look up Kyber suites by name.
                      Package suites allows callers to look up Kyber suites by name.
                      util
                      encoding
                      Package encoding package provides helper functions to encode/decode a Point/Scalar in hexadecimal.
                      Package encoding package provides helper functions to encode/decode a Point/Scalar in hexadecimal.
                      key
                      Package key creates asymmetric key pairs.
                      Package key creates asymmetric key pairs.
                      random
                      Package random provides facilities for generating random or pseudorandom cryptographic objects.
                      Package random provides facilities for generating random or pseudorandom cryptographic objects.
                      test
                      Package test contains generic testing and benchmarking infrastructure for cryptographic groups and ciphersuites.
                      Package test contains generic testing and benchmarking infrastructure for cryptographic groups and ciphersuites.
                      xof
                      Package xof holds implementations and testing code for the various extendable output functions.
                      Package xof holds implementations and testing code for the various extendable output functions.
                      blake2xb
                      Package blake2xb provides an implementation of kyber.XOF based on the Blake2xb construction.
                      Package blake2xb provides an implementation of kyber.XOF based on the Blake2xb construction.
                      keccak
                      Package keccak provides an implementation of kyber.XOF based on the Shake256 hash.
                      Package keccak provides an implementation of kyber.XOF based on the Shake256 hash.