mldsa

Documentation

Overview

Package mldsa implements the ML-DSA (FIPS 204) lattice signature at the three standardized parameter sets, pure Go and cgo-free. Transpiled from the FIPS 204 final pseudocode (August 2024); verified byte-exact against the NIST ACVP ML-DSA-{keyGen,sigGen,sigVer}-FIPS204 vector sets vendored in testdata/ (see SOURCES.md).

Example

Example signs and verifies with ML-DSA-44. The seed and rnd are fixed for reproducibility; in production both must be fresh CSPRNG output (all-zero rnd selects the deterministic signing variant).

package main

import (
	"fmt"

	"github.com/maceip/tamayo/mldsa"
)

func main() {
	p := mldsa.MLDSA44

	seed := make([]byte, 32)
	pk, sk, err := p.KeyGen(seed)
	if err != nil {
		panic(err)
	}

	msg := []byte("tamayo")
	rnd := make([]byte, 32)
	sig, err := p.Sign(sk, msg, nil, rnd)
	if err != nil {
		panic(err)
	}

	fmt.Println("verify:", p.Verify(pk, msg, sig, nil))
	fmt.Println("tampered:", p.Verify(pk, []byte("tamayp"), sig, nil))
}

Output:
verify: true
tampered: false

Index

• Variables
• type Params
  • func (p *Params) KeyGen(xi []byte) (pk, sk []byte, err error)
  • func (p *Params) Sign(sk, msg, ctx, rnd []byte) ([]byte, error)
  • func (p *Params) SignInternal(sk, mPrime, rnd []byte) ([]byte, error)
  • func (p *Params) SignMu(sk, mu, rnd []byte) ([]byte, error)
  • func (p *Params) SignPreHash(sk, msg, ctx []byte, ph PreHash, rnd []byte) ([]byte, error)
  • func (p *Params) Verify(pk, msg, sig, ctx []byte) bool
  • func (p *Params) VerifyInternal(pk, mPrime, sig []byte) bool
  • func (p *Params) VerifyMu(pk, mu, sig []byte) bool
  • func (p *Params) VerifyPreHash(pk, msg, sig, ctx []byte, ph PreHash) bool
• type PreHash
  • func (p PreHash) Name() string

Examples

• Package

Variables

var (
	MLDSA44 = newParams("ML-DSA-44", 4, 4, 2, 39, 1<<17, (q-1)/88, 80, 128, 3, 18, 6)
	MLDSA65 = newParams("ML-DSA-65", 6, 5, 4, 49, 1<<19, (q-1)/32, 55, 192, 4, 20, 4)
	MLDSA87 = newParams("ML-DSA-87", 8, 7, 2, 60, 1<<19, (q-1)/32, 75, 256, 3, 20, 4)
)

The three FIPS 204 parameter sets.

var (
	PreHashSHA224     = PreHash{"SHA2-224", oidTail(4), func(m []byte) []byte { s := sha256.Sum224(m); return s[:] }}
	PreHashSHA256     = PreHash{"SHA2-256", oidTail(1), func(m []byte) []byte { s := sha256.Sum256(m); return s[:] }}
	PreHashSHA384     = PreHash{"SHA2-384", oidTail(2), func(m []byte) []byte { s := sha512.Sum384(m); return s[:] }}
	PreHashSHA512     = PreHash{"SHA2-512", oidTail(3), func(m []byte) []byte { s := sha512.Sum512(m); return s[:] }}
	PreHashSHA512_224 = PreHash{"SHA2-512/224", oidTail(5), func(m []byte) []byte { s := sha512.Sum512_224(m); return s[:] }}
	PreHashSHA512_256 = PreHash{"SHA2-512/256", oidTail(6), func(m []byte) []byte { s := sha512.Sum512_256(m); return s[:] }}
	PreHashSHA3_224   = PreHash{"SHA3-224", oidTail(7), func(m []byte) []byte { s := sha3.Sum224(m); return s[:] }}
	PreHashSHA3_256   = PreHash{"SHA3-256", oidTail(8), func(m []byte) []byte { s := sha3.Sum256(m); return s[:] }}
	PreHashSHA3_384   = PreHash{"SHA3-384", oidTail(9), func(m []byte) []byte { s := sha3.Sum384(m); return s[:] }}
	PreHashSHA3_512   = PreHash{"SHA3-512", oidTail(10), func(m []byte) []byte { s := sha3.Sum512(m); return s[:] }}
	PreHashSHAKE128   = PreHash{"SHAKE-128", oidTail(11), shakeSum(256)}
	PreHashSHAKE256   = PreHash{"SHAKE-256", oidTail(12), shakeSum(512)}
)

The twelve approved pre-hash functions (FIPS 204 + NIST CSOR OIDs).

Types

type Params

type Params struct {
	Name   string
	K, L   int   // matrix dimensions
	Eta    int32 // secret key range
	Tau    int   // # of +-1s in the challenge polynomial
	Beta   int32 // Tau * Eta
	Gamma1 int32 // y coefficient range, 2^17 or 2^19
	Gamma2 int32 // low-order rounding range, (q-1)/88 or (q-1)/32
	Omega  int   // max # of hint bits
	Lambda int   // collision strength: c-tilde is Lambda/4 bytes

	PublicKeySize  int
	PrivateKeySize int
	SignatureSize  int
	// contains filtered or unexported fields
}

Params holds one ML-DSA parameter set (FIPS 204 table 1) plus its derived sizes. The three instances below are the only valid values.

func (*Params) KeyGen

func (p *Params) KeyGen(xi []byte) (pk, sk []byte, err error)

KeyGen is ML-DSA.KeyGen_internal (FIPS 204 algorithm 6): expand the 32-byte seed xi into an encoded key pair.

func (*Params) Sign

func (p *Params) Sign(sk, msg, ctx, rnd []byte) ([]byte, error)

Sign is pure ML-DSA.Sign (FIPS 204 algorithm 2) with caller-supplied 32-byte randomness rnd; pass 32 zero bytes for the deterministic variant.

func (*Params) SignInternal

func (p *Params) SignInternal(sk, mPrime, rnd []byte) ([]byte, error)

SignInternal is ML-DSA.Sign_internal (FIPS 204 algorithm 7). mPrime is the formatted message; rnd is the 32-byte signer randomness (all zero for the deterministic variant). The caller-supplied-randomness contract matches the rest of this module: rnd must be fresh CSPRNG output in production.

func (*Params) SignMu

func (p *Params) SignMu(sk, mu, rnd []byte) ([]byte, error)

SignMu is Sign_internal with an externally computed message representative mu = H(tr || M', 64) (the FIPS 204 "external mu" variant).

func (*Params) SignPreHash

func (p *Params) SignPreHash(sk, msg, ctx []byte, ph PreHash, rnd []byte) ([]byte, error)

SignPreHash is HashML-DSA.Sign (FIPS 204 algorithm 4) with caller-supplied 32-byte randomness rnd (pass 32 zero bytes for the deterministic variant).

func (*Params) Verify

func (p *Params) Verify(pk, msg, sig, ctx []byte) bool

Verify is pure ML-DSA.Verify (FIPS 204 algorithm 3).

func (*Params) VerifyInternal

func (p *Params) VerifyInternal(pk, mPrime, sig []byte) bool

VerifyInternal is ML-DSA.Verify_internal (FIPS 204 algorithm 8). Malformed inputs of any length return false rather than panicking.

func (*Params) VerifyMu

func (p *Params) VerifyMu(pk, mu, sig []byte) bool

VerifyMu is Verify_internal with an externally computed mu.

func (*Params) VerifyPreHash

func (p *Params) VerifyPreHash(pk, msg, sig, ctx []byte, ph PreHash) bool

VerifyPreHash is HashML-DSA.Verify (FIPS 204 algorithm 5).

type PreHash

type PreHash struct {
	// contains filtered or unexported fields
}

PreHash identifies an approved pre-hash function: its DER-encoded OID and the digest it produces. The zero value is invalid.

func (PreHash) Name

func (p PreHash) Name() string

Name returns the ACVP/JOSE label (e.g. "SHA2-256").