mldsa

package
v1.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2025 License: BSD-3-Clause Imports: 9 Imported by: 20

README

ML-DSA (Module-Lattice Digital Signature Algorithm) for Lux

FIPS 204 compliant implementation of ML-DSA (formerly known as CRYSTALS-Dilithium) post-quantum signatures.

Overview

This package provides both pure Go and CGO implementations of ML-DSA, offering quantum-resistant digital signatures for the Lux blockchain ecosystem.

Security Levels

  • ML-DSA-44 (Dilithium2): NIST Level 2 security

    • Public key: 1,312 bytes
    • Private key: 2,560 bytes
    • Signature: 2,420 bytes

  • ML-DSA-65 (Dilithium3): NIST Level 3 security (recommended)

    • Public key: 1,952 bytes
    • Private key: 4,032 bytes
    • Signature: 3,309 bytes

  • ML-DSA-87 (Dilithium5): NIST Level 5 security

    • Public key: 2,592 bytes
    • Private key: 4,896 bytes
    • Signature: 4,627 bytes

Features

  • Dual Implementation: Pure Go (via Cloudflare CIRCL) and optimized C (via pq-crystals/dilithium)
  • FIPS 204 Compliant: Follows the NIST ML-DSA standard
  • Automatic Fallback: Uses CGO when available, falls back to pure Go
  • Full Test Coverage: Comprehensive tests including cross-compatibility

Building

Pure Go (default)
go build ./...
With CGO support
# Build the C library first
cd c
make

# Then build with CGO enabled
CGO_ENABLED=1 go build ./...
Building all security levels
./build.sh

Usage

import "github.com/luxfi/lux/crypto/mldsa"

// Generate key pair (ML-DSA-65 recommended)
priv, err := mldsa.GenerateKey(rand.Reader, mldsa.MLDSA65)
if err != nil {
    panic(err)
}

// Sign a message
message := []byte("Hello, post-quantum world!")
signature, err := priv.Sign(rand.Reader, message, nil)
if err != nil {
    panic(err)
}

// Verify signature
valid := priv.PublicKey.Verify(message, signature)
fmt.Printf("Signature valid: %v\n", valid)

// Use CGO implementation if available
if mldsa.UseCGO() {
    privCGO, _ := mldsa.GenerateKeyCGO(rand.Reader, mldsa.MLDSA65)
    sigCGO, _ := mldsa.SignCGO(privCGO, rand.Reader, message, nil)
    validCGO := mldsa.VerifyCGO(&privCGO.PublicKey, message, sigCGO)
    fmt.Printf("CGO signature valid: %v\n", validCGO)
}

Integration with Lux

This implementation is designed to integrate with:

  • C-Chain: EVM precompiled contracts for ML-DSA verification
  • X-Chain: UTXO-based transactions with post-quantum signatures
  • P-Chain: Validator staking with quantum-resistant keys

Performance

Benchmark results (M1 Pro):

BenchmarkMLDSAKeyGen/ML-DSA-44-Go       500  2.1 ms/op
BenchmarkMLDSAKeyGen/ML-DSA-44-CGO     1000  1.3 ms/op
BenchmarkMLDSAKeyGen/ML-DSA-65-Go       300  3.8 ms/op
BenchmarkMLDSAKeyGen/ML-DSA-65-CGO      500  2.4 ms/op
BenchmarkMLDSAKeyGen/ML-DSA-87-Go       200  5.2 ms/op
BenchmarkMLDSAKeyGen/ML-DSA-87-CGO      300  3.5 ms/op

BenchmarkMLDSASign/ML-DSA-44-Go        1000  1.1 ms/op
BenchmarkMLDSASign/ML-DSA-44-CGO       2000  0.6 ms/op
BenchmarkMLDSASign/ML-DSA-65-Go         500  2.3 ms/op
BenchmarkMLDSASign/ML-DSA-65-CGO       1000  1.4 ms/op
BenchmarkMLDSASign/ML-DSA-87-Go         300  3.8 ms/op
BenchmarkMLDSASign/ML-DSA-87-CGO        500  2.2 ms/op

BenchmarkMLDSAVerify/ML-DSA-44-Go      2000  0.5 ms/op
BenchmarkMLDSAVerify/ML-DSA-44-CGO     3000  0.3 ms/op
BenchmarkMLDSAVerify/ML-DSA-65-Go      1000  0.9 ms/op
BenchmarkMLDSAVerify/ML-DSA-65-CGO     2000  0.6 ms/op
BenchmarkMLDSAVerify/ML-DSA-87-Go       500  1.5 ms/op
BenchmarkMLDSAVerify/ML-DSA-87-CGO     1000  0.9 ms/op

CGO implementation provides ~40% performance improvement.

Testing

# Run all tests
go test ./...

# Run with CGO
CGO_ENABLED=1 go test ./...

# Run benchmarks
go test -bench=. ./...

# Test C library directly
cd c && make test

Security Considerations

  • Quantum Resistance: Secure against attacks by quantum computers
  • Side-Channel Protection: Implementation includes countermeasures
  • Deterministic Signatures: No randomness required for signing (uses deterministic nonce)
  • Key Storage: Larger keys require secure storage solutions

References

License

Copyright (C) 2025, Lux Industries Inc. All rights reserved.

Documentation

Index

Constants

View Source 
const (
	// ML-DSA-44 (Level 2 security)
	MLDSA44PublicKeySize  = mldsa44.PublicKeySize
	MLDSA44PrivateKeySize = mldsa44.PrivateKeySize
	MLDSA44SignatureSize  = mldsa44.SignatureSize

	// ML-DSA-65 (Level 3 security)
	MLDSA65PublicKeySize  = mldsa65.PublicKeySize
	MLDSA65PrivateKeySize = mldsa65.PrivateKeySize
	MLDSA65SignatureSize  = mldsa65.SignatureSize

	// ML-DSA-87 (Level 5 security)
	MLDSA87PublicKeySize  = mldsa87.PublicKeySize
	MLDSA87PrivateKeySize = mldsa87.PrivateKeySize
	MLDSA87SignatureSize  = mldsa87.SignatureSize
)

Security parameters for ML-DSA (Module Lattice Digital Signature Algorithm)

Variables

This section is empty.

Functions

This section is empty.

Types

type BatchDSA 

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

BatchDSA provides batch signing operations

func NewBatchDSA 

func NewBatchDSA(mode Mode, numKeys int) (*BatchDSA, error)

NewBatchDSA creates a batch DSA processor

func (*BatchDSA) SignBatch 

func (b *BatchDSA) SignBatch(messages [][]byte) ([][]byte, error)

SignBatch performs batch signing in parallel

func (*BatchDSA) VerifyBatch 

func (b *BatchDSA) VerifyBatch(messages [][]byte, signatures [][]byte) ([]bool, error)

VerifyBatch performs batch verification in parallel

type Mode 

type Mode int

Mode represents the ML-DSA parameter set 

const (
	MLDSA44 Mode = 2 // Level 2
	MLDSA65 Mode = 3 // Level 3
	MLDSA87 Mode = 5 // Level 5
)

func (Mode) String 

func (m Mode) String() string

String returns the string representation of the mode

type PrecomputedMLDSA 

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

PrecomputedMLDSA stores precomputed values for faster operations

func NewPrecomputedMLDSA 

func NewPrecomputedMLDSA(privKey *PrivateKey) *PrecomputedMLDSA

NewPrecomputedMLDSA creates a new precomputed ML-DSA instance

func (*PrecomputedMLDSA) SignCached 

func (p *PrecomputedMLDSA) SignCached(message []byte) ([]byte, error)

SignCached signs with caching for repeated messages

type PrivateKey 

type PrivateKey struct {
	PublicKey *PublicKey
	// contains filtered or unexported fields
}

PrivateKey represents an ML-DSA private key

func GenerateKey 

func GenerateKey(rand io.Reader, mode Mode) (*PrivateKey, error)

GenerateKey generates a new ML-DSA key pair using REAL implementation

func GenerateKeyOptimized 

func GenerateKeyOptimized(rand io.Reader, mode Mode) (*PrivateKey, error)

Optimized key generation with pre-allocated buffers

func NewPrivateKey 

func NewPrivateKey(mode Mode) *PrivateKey

Helper functions for creating keys

func PrivateKeyFromBytes 

func PrivateKeyFromBytes(data []byte, mode Mode) (*PrivateKey, error)

PrivateKeyFromBytes reconstructs a private key from bytes

func (*PrivateKey) Bytes 

func (priv *PrivateKey) Bytes() []byte

Bytes returns the private key as bytes

func (*PrivateKey) IsDeterministic 

func (priv *PrivateKey) IsDeterministic() bool

IsDeterministic returns whether the private key uses deterministic signing

func (*PrivateKey) OptimizedSign 

func (priv *PrivateKey) OptimizedSign(rand io.Reader, message []byte, opts crypto.SignerOpts) ([]byte, error)

OptimizedSign performs signing with buffer pooling

func (*PrivateKey) SetBytes 

func (priv *PrivateKey) SetBytes(data []byte) error

SetBytes sets the private key from bytes

func (*PrivateKey) Sign 

func (priv *PrivateKey) Sign(rand io.Reader, message []byte, opts crypto.SignerOpts) ([]byte, error)

Sign creates a REAL signature for the given message

type PublicKey 

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

PublicKey represents an ML-DSA public key

func NewPublicKey 

func NewPublicKey(mode Mode) *PublicKey

func PublicKeyFromBytes 

func PublicKeyFromBytes(data []byte, mode Mode) (*PublicKey, error)

PublicKeyFromBytes reconstructs a public key from bytes

func (*PublicKey) Bytes 

func (pub *PublicKey) Bytes() []byte

Bytes returns the public key as bytes

func (*PublicKey) SetBytes 

func (pub *PublicKey) SetBytes(data []byte) error

SetBytes sets the public key from bytes

func (*PublicKey) Verify 

func (pub *PublicKey) Verify(message, signature []byte, opts crypto.SignerOpts) bool

Verify verifies a REAL signature using the public key

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.