Skip to content

Compatibility policy

The module uses semantic versioning. The public API is every exported identifier of the root package compositemldsa and of compositex509. The interop module and the examples are not part of it.

The draft

Composite ML-DSA is still an Internet-Draft. Each release names the draft version it implements, currently draft-ietf-lamps-pq-composite-sigs-19. It is tested against that draft's published test vectors.

When a later draft or the RFC changes the message representative, an encoding or an OID, signatures made under the old rules stop verifying under the new ones. The library then moves to the new rules in a minor release. The release notes say which keys, certificates and signatures are affected. It does not keep several draft versions side by side.

Keys generated by one release remain loadable by the next unless the key encoding itself changes.

Before v1.0.0

A minor release may change the public API. The release notes name every such change and the reason. Patch releases keep the API.

Rules for every release

  • Algorithms may be added. Algorithms() may return more entries, for example once the standard library gains Brainpool or Ed448. Switch statements over Algorithm need a default case.
  • Algorithm values are not stable identifiers. Store the OID or the name, never the integer value of an Algorithm. AlgorithmFromOID and AlgorithmFromName read them back.
  • Options may gain fields. Construct it with field names.
  • Parsing may become stricter, for example when the draft tightens a rule. The release notes name the change.

Upgrading

  1. Read the release notes section for the new version.
  2. Run go get github.com/misiektoja/go-composite-mldsa@vX.Y.Z and build.
  3. Run your own tests against the implementations you exchange certificates with. Tested implementations names the versions each release was verified with.

Go version

The module declares the minimum Go version in go.mod. Every release is built and tested with exactly that toolchain, so the minimum moves to a newer Go patch release when that release fixes a vulnerability govulncheck finds in the module or its example. Go 1.27.1 is the first version whose crypto/mldsa, crypto/x509 and crypto.MessageSigner support everything the library needs. The minimum is Go 1.27.2, which fixed such a vulnerability in os.