Documentation
¶
Overview ¶
Package mldsa implements the post-quantum ML-DSA signature scheme specified in FIPS 204.
This package is unavailable if using the FIPS 140-3 Go Cryptographic Module v1.0.0, in which case GenerateKey, NewPrivateKey, NewPublicKey, and Verify will return an error. It is available if using v1.26.0 or later.
Example ¶
package main
import (
"crypto/mldsa"
"fmt"
"log"
)
func main() {
// The signer generates a new ML-DSA-44 key pair.
sk, err := mldsa.GenerateKey(mldsa.MLDSA44())
if err != nil {
log.Fatal(err)
}
// The signer publishes the public key encoding.
publicKey := sk.PublicKey().Bytes()
fmt.Printf("public key: %d bytes\n", len(publicKey))
// The signer signs a message and publishes the signature.
msg := []byte("hello, world")
sig, err := sk.Sign(nil, msg, &mldsa.Options{Context: "example"})
if err != nil {
log.Fatal(err)
}
fmt.Printf("signature: %d bytes\n", len(sig))
// The verifier reconstructs the public key and checks the signature.
// The context string must match the one used by the signer.
pk, err := mldsa.NewPublicKey(mldsa.MLDSA44(), publicKey)
if err != nil {
log.Fatal(err)
}
if err := mldsa.Verify(pk, msg, sig, &mldsa.Options{Context: "example"}); err != nil {
log.Fatal("invalid signature: ", err)
}
}
Output: public key: 1312 bytes signature: 2420 bytes
Index ¶
- Constants
- func Verify(pk *PublicKey, message []byte, signature []byte, opts *Options) error
- type Options
- type Parameters
- type PrivateKey
- func (sk *PrivateKey) Bytes() []byte
- func (sk *PrivateKey) Equal(x crypto.PrivateKey) bool
- func (sk *PrivateKey) Public() crypto.PublicKey
- func (sk *PrivateKey) PublicKey() *PublicKey
- func (sk *PrivateKey) Sign(_ io.Reader, message []byte, opts crypto.SignerOpts) (signature []byte, err error)
- func (sk *PrivateKey) SignDeterministic(message []byte, opts crypto.SignerOpts) (signature []byte, err error)
- type PublicKey
Examples ¶
Constants ¶
const ( PrivateKeySize = 32 MLDSA44PublicKeySize = 1312 MLDSA65PublicKeySize = 1952 MLDSA87PublicKeySize = 2592 MLDSA44SignatureSize = 2420 MLDSA65SignatureSize = 3309 MLDSA87SignatureSize = 4627 )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Options ¶
type Options struct {
// Context can be used to distinguish signatures created for different
// purposes. It must be at most 255 bytes long, and it is empty by default.
//
// The same context must be used when signing and verifying a signature.
Context string
}
Options contains additional options for signing and verifying ML-DSA signatures.
type Parameters ¶
type Parameters struct {
// contains filtered or unexported fields
}
Parameters represents one of the fixed parameter sets defined in FIPS 204.
Most applications should use MLDSA44.
Multiple invocations of MLDSA44, MLDSA65, or MLDSA87 will return the same respective value, which can be used for equality checks and switch statements. The returned value is safe for concurrent use.
func MLDSA44 ¶
func MLDSA44() Parameters
MLDSA44 returns the ML-DSA-44 parameter set defined in FIPS 204.
func MLDSA65 ¶
func MLDSA65() Parameters
MLDSA65 returns the ML-DSA-65 parameter set defined in FIPS 204.
func MLDSA87 ¶
func MLDSA87() Parameters
MLDSA87 returns the ML-DSA-87 parameter set defined in FIPS 204.
func (Parameters) PublicKeySize ¶
func (params Parameters) PublicKeySize() int
PublicKeySize returns the size of public keys for this parameter set, in bytes.
func (Parameters) SignatureSize ¶
func (params Parameters) SignatureSize() int
SignatureSize returns the size of signatures for this parameter set, in bytes.
func (Parameters) String ¶
func (params Parameters) String() string
String returns the name of the parameter set, e.g. "ML-DSA-44".
type PrivateKey ¶
type PrivateKey struct {
// contains filtered or unexported fields
}
PrivateKey is an in-memory ML-DSA private key. It implements crypto.Signer and the informal extended crypto.PrivateKey interface.
A PrivateKey is safe for concurrent use.
func GenerateKey ¶
func GenerateKey(params Parameters) (*PrivateKey, error)
GenerateKey generates a new random ML-DSA private key.
func NewPrivateKey ¶
func NewPrivateKey(params Parameters, seed []byte) (*PrivateKey, error)
NewPrivateKey decodes an ML-DSA private key from the given seed.
The seed must be exactly PrivateKeySize bytes long.
func (*PrivateKey) Equal ¶
func (sk *PrivateKey) Equal(x crypto.PrivateKey) bool
Equal reports whether sk and x are the same key (i.e. they are derived from the same seed).
If x is not a *PrivateKey, Equal returns false.
func (*PrivateKey) Public ¶
func (sk *PrivateKey) Public() crypto.PublicKey
Public returns the corresponding PublicKey for this private key.
It implements the crypto.Signer interface.
func (*PrivateKey) PublicKey ¶
func (sk *PrivateKey) PublicKey() *PublicKey
PublicKey returns the corresponding PublicKey for this private key.
func (*PrivateKey) Sign ¶
func (sk *PrivateKey) Sign(_ io.Reader, message []byte, opts crypto.SignerOpts) (signature []byte, err error)
Sign returns a signature of the given message using this private key.
If opts is nil or opts.HashFunc returns zero, the message is signed directly. If opts.HashFunc returns crypto.MLDSAMu, the provided message must be a pre-hashed μ message representative. opts can be of type *Options if a context string is desired along with a directly-signed message. The io.Reader argument is ignored.
func (*PrivateKey) SignDeterministic ¶
func (sk *PrivateKey) SignDeterministic(message []byte, opts crypto.SignerOpts) (signature []byte, err error)
SignDeterministic works like PrivateKey.Sign, but the signature is deterministic.
type PublicKey ¶
type PublicKey struct {
// contains filtered or unexported fields
}
PublicKey is an ML-DSA public key. It implements the informal extended crypto.PublicKey interface.
A PublicKey is safe for concurrent use.
func NewPublicKey ¶
func NewPublicKey(params Parameters, encoding []byte) (*PublicKey, error)
NewPublicKey creates a new ML-DSA public key from the given encoding.
func (*PublicKey) Equal ¶
Equal reports whether pk and x are the same key (i.e. they have the same encoding).
If x is not a *PublicKey, Equal returns false.
func (*PublicKey) Parameters ¶
func (pk *PublicKey) Parameters() Parameters
Parameters returns the parameters associated with this public key.
Source Files