1 //go:generate go run gen.go 2 3 // dilithium implements the CRYSTALS-Dilithium signature schemes 4 // as submitted to round3 of the NIST PQC competition and described in 5 // 6 // https://pq-crystals.org/dilithium/data/dilithium-specification-round3-20210208.pdf 7 // 8 // Each of the eight different modes of Dilithium is implemented by a 9 // subpackage. For instance, Dilithium2 (the recommended mode) 10 // can be found in 11 // 12 // github.com/cloudflare/circl/sign/dilithium/mode2 13 // 14 // If your choice for mode is fixed compile-time, use the subpackages. 15 // This package provides a convenient wrapper around all of the subpackages 16 // so one can be chosen at runtime. 17 // 18 // The authors of Dilithium recommend to combine it with a "pre-quantum" 19 // signature scheme. The packages 20 // 21 // github.com/cloudflare/circl/sign/eddilithium2 22 // github.com/cloudflare/circl/sign/eddilithium3 23 // 24 // implement such hybrids of Dilithium2 with Ed25519 respectively and 25 // Dilithium3 with Ed448. These packages are a drop in replacements for the 26 // mode subpackages of this package. 27 package dilithium 28 29 import ( 30 "crypto" 31 "io" 32 ) 33 34 // PublicKey is a Dilithium public key. 35 // 36 // The structure contains values precomputed during unpacking/key generation 37 // and is therefore significantly larger than a packed public key. 38 type PublicKey interface { 39 // Packs public key 40 Bytes() []byte 41 } 42 43 // PrivateKey is a Dilithium public key. 44 // 45 // The structure contains values precomputed during unpacking/key generation 46 // and is therefore significantly larger than a packed private key. 47 type PrivateKey interface { 48 // Packs private key 49 Bytes() []byte 50 51 crypto.Signer 52 } 53 54 // Mode is a certain configuration of the Dilithium signature scheme. 55 type Mode interface { 56 // GenerateKey generates a public/private key pair using entropy from rand. 57 // If rand is nil, crypto/rand.Reader will be used. 58 GenerateKey(rand io.Reader) (PublicKey, PrivateKey, error) 59 60 // NewKeyFromSeed derives a public/private key pair using the given seed. 61 // Panics if len(seed) != SeedSize() 62 NewKeyFromSeed(seed []byte) (PublicKey, PrivateKey) 63 64 // Sign signs the given message and returns the signature. 65 // It will panic if sk has not been generated for this mode. 66 Sign(sk PrivateKey, msg []byte) []byte 67 68 // Verify checks whether the given signature by pk on msg is valid. 69 // It will panic if pk is of the wrong mode. 70 Verify(pk PublicKey, msg []byte, signature []byte) bool 71 72 // Unpacks a public key. Panics if the buffer is not of PublicKeySize() 73 // length. Precomputes values to speed up subsequent calls to Verify. 74 PublicKeyFromBytes([]byte) PublicKey 75 76 // Unpacks a private key. Panics if the buffer is not 77 // of PrivateKeySize() length. Precomputes values to speed up subsequent 78 // calls to Sign(To). 79 PrivateKeyFromBytes([]byte) PrivateKey 80 81 // SeedSize returns the size of the seed for NewKeyFromSeed 82 SeedSize() int 83 84 // PublicKeySize returns the size of a packed PublicKey 85 PublicKeySize() int 86 87 // PrivateKeySize returns the size of a packed PrivateKey 88 PrivateKeySize() int 89 90 // SignatureSize returns the size of a signature 91 SignatureSize() int 92 93 // Name returns the name of this mode 94 Name() string 95 } 96 97 var modes = make(map[string]Mode) 98 99 // ModeNames returns the list of supported modes. 100 func ModeNames() []string { 101 names := []string{} 102 for name := range modes { 103 names = append(names, name) 104 } 105 return names 106 } 107 108 // ModeByName returns the mode with the given name or nil when not supported. 109 func ModeByName(name string) Mode { 110 return modes[name] 111 } 112