Skip to content

Latest commit

 

History

82 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

go-composite-mldsa

GitHub Release Go Reference License Tests Coverage Interoperability Supply chain OpenSSF Scorecard

go-composite-mldsa is a Go library for post-quantum composite ML-DSA signatures as specified in draft-ietf-lamps-pq-composite-sigs-19.

A composite key pairs a post-quantum ML-DSA key with a traditional RSA, ECDSA or Ed25519 key. Every signature carries one signature from each and verifies only when both do. A certificate signed this way stays trustworthy as long as either algorithm remains unbroken, which is the point of a migration period where ML-DSA is still new.

The library has two packages and no dependencies outside the Go standard library:

  • compositemldsa generates, encodes, signs and verifies with the 15 composite algorithms the standard library can build
  • compositex509 creates and verifies certificates, certificate requests and revocation lists signed by composite keys or carrying composite subject keys. Every other key type passes through to crypto/x509

Contents

Install

go get github.com/misiektoja/go-composite-mldsa

The module needs Go 1.27.2 or newer.

import (
	compositemldsa "github.com/misiektoja/go-composite-mldsa"
	"github.com/misiektoja/go-composite-mldsa/compositex509"
)

Algorithms

ML-DSA Traditional component
ML-DSA-44 RSA-2048 PSS, RSA-2048 PKCS #1 v1.5, Ed25519, ECDSA P-256
ML-DSA-65 RSA-3072 PSS, RSA-3072 PKCS #1 v1.5, RSA-4096 PSS, RSA-4096 PKCS #1 v1.5, ECDSA P-256, ECDSA P-384, Ed25519
ML-DSA-87 ECDSA P-384, RSA-3072 PSS, RSA-4096 PSS, ECDSA P-521

The Brainpool and Ed448 combinations of the draft are not supported because the Go standard library does not implement those curves. The algorithm reference lists names, OIDs and sizes.

Every supported algorithm passes the draft's published test vectors and exchanges keys, signatures, certificates, requests and revocation lists with Bouncy Castle in both directions.

Getting started

Sign and verify a message:

key, err := compositemldsa.GenerateKey(compositemldsa.MLDSA65ECDSAP256SHA512)
if err != nil {
	log.Fatal(err)
}
signature, err := key.Sign(nil, message, nil)
if err != nil {
	log.Fatal(err)
}
err = compositemldsa.Verify(key.PublicKey(), message, signature, nil)

Issue certificates from a composite CA with the crypto/x509 templates you already use:

der, err := compositex509.CreateCertificate(rand.Reader, template, caCert, subjectPublicKey, caKey)

examples/hierarchy builds a root CA, a device certificate from a certificate request and a revocation list, verifies them and writes PEM files:

go run ./examples/hierarchy out

Getting started walks through the same steps.

Documentation

Full documentation is at misiektoja.github.io/go-composite-mldsa. The package documentation on pkg.go.dev describes every exported identifier.

Limitations

  • The draft is not yet an RFC. The library follows draft-19 exactly and a later draft or the RFC may change the construction.
  • x509.Certificate.Verify cannot build chains through composite certificates. Check each link with compositex509.CheckSignatureFrom.
  • OCSP responses, CMS and TLS are out of scope. The raw signing API covers any structure that signs DER bytes under an algorithm identifier.

Known limitations explains each one.

Support

SUPPORT.md says where to ask questions and report bugs. SECURITY.md describes how to report a vulnerability privately. CONTRIBUTING.md covers the development checks.

License

Apache-2.0, see LICENSE. The draft's test vectors in testdata keep their own Revised BSD License, see testdata/README.md.

Releases

Packages

Used by

Contributors

Languages