dilithium

Documentation

Overview

dilithium implements the CRYSTALS-Dilithium signature schemes as submitted to round3 of the NIST PQC competition and described in

https://pq-crystals.org/dilithium/data/dilithium-specification-round3-20210208.pdf

Each of the eight different modes of Dilithium is implemented by a subpackage. For instance, Dilithium2 (the recommended mode) can be found in

github.com/cloudflare/circl/sign/dilithium/mode2

If your choice for mode is fixed compile-time, use the subpackages. This package provides a convenient wrapper around all of the subpackages so one can be chosen at runtime.

The authors of Dilithium recommend to combine it with a "pre-quantum" signature scheme. The packages

github.com/cloudflare/circl/sign/eddilithium2
github.com/cloudflare/circl/sign/eddilithium3

implement such hybrids of Dilithium2 with Ed25519 respectively and Dilithium3 with Ed448. These packages are a drop in replacements for the mode subpackages of this package.

Index

• func ModeNames() []string
• type Mode
  • func ModeByName(name string) Mode
• type PrivateKey
• type PublicKey

Functions

func ModeNames

func ModeNames() []string

ModeNames returns the list of supported modes.

Types

type Mode

type Mode interface {
	// GenerateKey generates a public/private key pair using entropy from rand.
	// If rand is nil, crypto/rand.Reader will be used.
	GenerateKey(rand io.Reader) (PublicKey, PrivateKey, error)

	// NewKeyFromSeed derives a public/private key pair using the given seed.
	// Panics if len(seed) != SeedSize()
	NewKeyFromSeed(seed []byte) (PublicKey, PrivateKey)

	// Sign signs the given message and returns the signature.
	// It will panic if sk has not been generated for this mode.
	Sign(sk PrivateKey, msg []byte) []byte

	// Verify checks whether the given signature by pk on msg is valid.
	// It will panic if pk is of the wrong mode.
	Verify(pk PublicKey, msg []byte, signature []byte) bool

	// Unpacks a public key.  Panics if the buffer is not of PublicKeySize()
	// length.  Precomputes values to speed up subsequent calls to Verify.
	PublicKeyFromBytes([]byte) PublicKey

	// Unpacks a private key.  Panics if the buffer is not
	// of PrivateKeySize() length.  Precomputes values to speed up subsequent
	// calls to Sign(To).
	PrivateKeyFromBytes([]byte) PrivateKey

	// SeedSize returns the size of the seed for NewKeyFromSeed
	SeedSize() int

	// PublicKeySize returns the size of a packed PublicKey
	PublicKeySize() int

	// PrivateKeySize returns the size  of a packed PrivateKey
	PrivateKeySize() int

	// SignatureSize returns the size  of a signature
	SignatureSize() int

	// Name returns the name of this mode
	Name() string
}

Mode is a certain configuration of the Dilithium signature scheme.

var Mode2 Mode = &implMode2{}

Mode2 is Dilithium in mode "Dilithium2".

var Mode2AES Mode = &implMode2AES{}

Mode2AES is Dilithium in mode "Dilithium2-AES".

var Mode3 Mode = &implMode3{}

Mode3 is Dilithium in mode "Dilithium3".

var Mode3AES Mode = &implMode3AES{}

Mode3AES is Dilithium in mode "Dilithium3-AES".

var Mode5 Mode = &implMode5{}

Mode5 is Dilithium in mode "Dilithium5".

var Mode5AES Mode = &implMode5AES{}

Mode5AES is Dilithium in mode "Dilithium5-AES".

func ModeByName

func ModeByName(name string) Mode

ModeByName returns the mode with the given name or nil when not supported.

type PrivateKey

type PrivateKey interface {
	// Packs private key
	Bytes() []byte

	crypto.Signer
}

PrivateKey is a Dilithium private key.

The structure contains values precomputed during unpacking/key generation and is therefore significantly larger than a packed private key.

type PublicKey

type PublicKey interface {
	// Packs public key
	Bytes() []byte
}

PublicKey is a Dilithium public key.

The structure contains values precomputed during unpacking/key generation and is therefore significantly larger than a packed public key.