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/JI-0/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
|
|
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 |