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.
Example ¶
package main
import (
"fmt"
"sort"
"github.com/cloudflare/circl/sign/dilithium"
)
func main() {
// 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.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 ¶
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.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
common/asm
module
|
|
|
mode2 implements the CRYSTALS-Dilithium signature scheme Dilithium2 as submitted to round3 of the NIST PQC competition and described in
|
mode2 implements the CRYSTALS-Dilithium signature scheme Dilithium2 as submitted to round3 of the NIST PQC competition and described in |
|
mode2aes implements the CRYSTALS-Dilithium signature scheme Dilithium2-AES as submitted to round3 of the NIST PQC competition and described in
|
mode2aes implements the CRYSTALS-Dilithium signature scheme Dilithium2-AES as submitted to round3 of the NIST PQC competition and described in |
|
mode3 implements the CRYSTALS-Dilithium signature scheme Dilithium3 as submitted to round3 of the NIST PQC competition and described in
|
mode3 implements the CRYSTALS-Dilithium signature scheme Dilithium3 as submitted to round3 of the NIST PQC competition and described in |
|
mode3aes implements the CRYSTALS-Dilithium signature scheme Dilithium3-AES as submitted to round3 of the NIST PQC competition and described in
|
mode3aes implements the CRYSTALS-Dilithium signature scheme Dilithium3-AES as submitted to round3 of the NIST PQC competition and described in |
|
mode5 implements the CRYSTALS-Dilithium signature scheme Dilithium5 as submitted to round3 of the NIST PQC competition and described in
|
mode5 implements the CRYSTALS-Dilithium signature scheme Dilithium5 as submitted to round3 of the NIST PQC competition and described in |
|
mode5aes implements the CRYSTALS-Dilithium signature scheme Dilithium5-AES as submitted to round3 of the NIST PQC competition and described in
|
mode5aes implements the CRYSTALS-Dilithium signature scheme Dilithium5-AES as submitted to round3 of the NIST PQC competition and described in |