README
¶
filippo.io/mldsa
This package implements the crypto/mldsa proposed API.
Its API may change, and eventually this package will become a wrapper around the final API in the standard library.
The actual implementation is merged from the internal upstream package crypto/internal/fips140/mldsa, with very few changes (visible in the merge commits in the git history).
Documentation
¶
Overview ¶
Package mldsa implements the post-quantum ML-DSA signature scheme specified in FIPS 204.
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.
func MLDSA44 ¶
func MLDSA44() *Parameters
MLDSA44 returns the ML-DSA-44 parameter set defined in FIPS 204.
Multiple invocations of this function will return the same value, which can be used for equality checks and switch statements. The returned value is safe for concurrent use.
func MLDSA65 ¶
func MLDSA65() *Parameters
MLDSA65 returns the ML-DSA-65 parameter set defined in FIPS 204.
Multiple invocations of this function will return the same value, which can be used for equality checks and switch statements. The returned value is safe for concurrent use.
func MLDSA87 ¶
func MLDSA87() *Parameters
MLDSA87 returns the ML-DSA-87 parameter set defined in FIPS 204.
Multiple invocations of this function will return the same value, which can be used for equality checks and switch statements. The returned value is safe for concurrent use.
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 creates a new 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. The io.Reader argument is ignored.
Example (ExternalMu) ¶
package main
import (
"crypto/sha3"
"fmt"
"log"
"filippo.io/mldsa"
"filippo.io/mldsa/mldsacrypto"
)
func main() {
sk, err := mldsa.GenerateKey(mldsa.MLDSA44())
if err != nil {
log.Fatal(err)
}
pk := sk.PublicKey()
// Compute μ externally, as specified in FIPS 204.
//
// This is useful when the message is large, because μ can be computed
// incrementally by the caller without buffering the full message.
//
// First, compute tr = SHAKE256(publicKey).
H := sha3.NewSHAKE256()
H.Write(pk.Bytes())
var tr [64]byte
H.Read(tr[:])
// Then, compute μ = SHAKE256(tr || 0x00 || len(ctx) || ctx || msg).
// The second byte is 0x00 for ML-DSA (as opposed to HashML-DSA) and ctx
// is the context string, empty by default.
message := []byte("hello, world")
H.Reset()
H.Write(tr[:])
H.Write([]byte{0x00}) // ML-DSA domain separator
H.Write([]byte{0x00}) // context length (0 for empty context)
H.Write(message)
mu := make([]byte, 64)
H.Read(mu)
// Sign the pre-computed μ by passing MLDSAMu as the hash function.
sig, err := sk.Sign(nil, mu, mldsacrypto.MLDSAMu)
if err != nil {
log.Fatal(err)
}
// Verify against the original message using the standard Verify function.
if err := mldsa.Verify(pk, message, sig, nil); err != nil {
log.Fatal(err)
}
fmt.Println("signature verified")
}
Output: signature verified
Example (WithContext) ¶
package main
import (
"fmt"
"log"
"filippo.io/mldsa"
)
func main() {
sk, err := mldsa.GenerateKey(mldsa.MLDSA44())
if err != nil {
log.Fatal(err)
}
message := []byte("hello, world")
sig, err := sk.Sign(nil, message, &mldsa.Options{Context: "example"})
if err != nil {
log.Fatal(err)
}
if err := mldsa.Verify(sk.PublicKey(), message, sig, &mldsa.Options{Context: "example"}); err != nil {
log.Fatal(err)
}
fmt.Println("signature verified")
}
Output: signature verified
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.
Example ¶
package main
import (
"fmt"
"log"
"filippo.io/mldsa"
)
func main() {
sk, err := mldsa.GenerateKey(mldsa.MLDSA44())
if err != nil {
log.Fatal(err)
}
message := []byte("hello, world")
sig, err := sk.SignDeterministic(message, nil)
if err != nil {
log.Fatal(err)
}
if err := mldsa.Verify(sk.PublicKey(), message, sig, nil); err != nil {
log.Fatal(err)
}
fmt.Println("signature verified")
}
Output: signature verified
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, seed []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
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
Package mldsacrypto is a stand-in for the standard library's crypto package, until MLDSAMu is added there, at which point this package will become a wrapper.
|
Package mldsacrypto is a stand-in for the standard library's crypto package, until MLDSAMu is added there, at which point this package will become a wrapper. |