Involved Source Files 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.
[FIPS 204]: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.204.pdf
[FIPS 140-3 Go Cryptographic Module]: https://go.dev/doc/security/fips140mldsa_fips140v1.26.go
Code Examples
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)
}
}
Package-Level Type Names (total 4, all are exported)
/* sort exporteds by: | */
Options contains additional options for signing and verifying ML-DSA signatures. 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. HashFunc returns zero, to implement the [crypto.SignerOpts] interface.
*Options : crypto.SignerOpts
func Verify(pk *PublicKey, message []byte, signature []byte, opts *Options) error
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.kmldsa.PrivateKey Bytes returns the private key seed. 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. Public returns the corresponding [PublicKey] for this private key.
It implements the [crypto.Signer] interface. PublicKey returns the corresponding [PublicKey] for this private key. 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.
[pre-hashed μ message representative]: https://www.rfc-editor.org/rfc/rfc9881.html#externalmu SignDeterministic works like [PrivateKey.Sign], but the signature is
deterministic.
*PrivateKey : crypto.Signer
func GenerateKey(params Parameters) (*PrivateKey, error)
func NewPrivateKey(params Parameters, seed []byte) (*PrivateKey, error)
PublicKey is an ML-DSA public key. It implements the informal extended
[crypto.PublicKey] interface.
A PublicKey is safe for concurrent use.pmldsa.PublicKey Bytes returns the public key encoding. 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. Parameters returns the parameters associated with this public key.
func NewPublicKey(params Parameters, encoding []byte) (*PublicKey, error)
func (*PrivateKey).PublicKey() *PublicKey
func newPublicKey(pub *PublicKey, params Parameters, encoding []byte) (*PublicKey, error)
func Verify(pk *PublicKey, message []byte, signature []byte, opts *Options) error
func newPublicKey(pub *PublicKey, params Parameters, encoding []byte) (*PublicKey, error)
func crypto/x509.signatureMLDSAParametersMismatchError(expectedSigAlgo x509.SignatureAlgorithm, pubKey *PublicKey) error
Package-Level Functions (total 8, in which 7 are exported)
GenerateKey generates a new random ML-DSA private key.
MLDSA44 returns the ML-DSA-44 parameter set defined in FIPS 204.
MLDSA65 returns the ML-DSA-65 parameter set defined in FIPS 204.
MLDSA87 returns the ML-DSA-87 parameter set defined in FIPS 204.
NewPrivateKey decodes an ML-DSA private key from the given seed.
The seed must be exactly [PrivateKeySize] bytes long.
NewPublicKey creates a new ML-DSA public key from the given encoding.
Verify reports whether signature is a valid signature of message by pk.
If opts is nil, it's equivalent to the zero value of Options.