...
▽

Package dilithium

import "github.com/cloudflare/circl/sign/dilithium"
Overview
Index
Examples
Subdirectories

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.

▾ Example

Code:

// Check supported modes
modes := dilithium.ModeNames()
sort.Strings(modes)
fmt.Printf("Supported modes: %v\n", modes)

// Pick Dilithium mode III.
mode := dilithium.ModeByName("Dilithium3")
if mode == nil {
    panic("Mode3 not supported")
}

// Alternatively one could simply write
//
//  mode := dilithium.Mode3

// Generates a keypair.
pk, sk, err := mode.GenerateKey(nil)
if err != nil {
    panic(err)
}
// (Alternatively one can derive a keypair from a seed,
// see mode.NewKeyFromSeed().)

// Packs public and private key
packedSk := sk.Bytes()
packedPk := pk.Bytes()

// Load it again
sk2 := mode.PrivateKeyFromBytes(packedSk)
pk2 := mode.PublicKeyFromBytes(packedPk)

// Creates a signature on our message with the generated private key.
msg := []byte("Some message")
signature := mode.Sign(sk2, msg)

// Checks whether a signature is correct
if !mode.Verify(pk2, msg, signature) {
    panic("incorrect signature")
}

fmt.Printf("O.K.")

Output:

Supported modes: [Dilithium2 Dilithium2-AES Dilithium3 Dilithium3-AES Dilithium5 Dilithium5-AES]
O.K.

func ModeNames 

func ModeNames() []string

ModeNames returns the list of supported modes.

type Mode

Mode is a certain configuration of the Dilithium signature scheme. 

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
}

Mode2 is Dilithium in mode "Dilithium2". 

var Mode2 Mode = &implMode2{}

Mode2AES is Dilithium in mode "Dilithium2-AES". 

var Mode2AES Mode = &implMode2AES{}

Mode3 is Dilithium in mode "Dilithium3". 

var Mode3 Mode = &implMode3{}

Mode3AES is Dilithium in mode "Dilithium3-AES". 

var Mode3AES Mode = &implMode3AES{}

Mode5 is Dilithium in mode "Dilithium5". 

var Mode5 Mode = &implMode5{}

Mode5AES is Dilithium in mode "Dilithium5-AES". 

var Mode5AES Mode = &implMode5AES{}

func ModeByName 

func ModeByName(name string) Mode

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

type PrivateKey

PrivateKey is a Dilithium public key.

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

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

    crypto.Signer
}

type PublicKey

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. 

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

Subdirectories

Name Synopsis
..
mode2 mode2 implements the CRYSTALS-Dilithium signature scheme Dilithium2 as submitted to round3 of the NIST PQC competition and described in
mode2aes mode2aes implements the CRYSTALS-Dilithium signature scheme Dilithium2-AES as submitted to round3 of the NIST PQC competition and described in
mode3 mode3 implements the CRYSTALS-Dilithium signature scheme Dilithium3 as submitted to round3 of the NIST PQC competition and described in
mode3aes mode3aes implements the CRYSTALS-Dilithium signature scheme Dilithium3-AES as submitted to round3 of the NIST PQC competition and described in
mode5 mode5 implements the CRYSTALS-Dilithium signature scheme Dilithium5 as submitted to round3 of the NIST PQC competition and described in
mode5aes mode5aes implements the CRYSTALS-Dilithium signature scheme Dilithium5-AES as submitted to round3 of the NIST PQC competition and described in
templates