sign

README

Tessera Sign

Signs a Tessera bill of materials with a hybrid post-quantum signature, so a document can be shown to have come from you and to have not changed since.

tessera-sign keygen --out ./keys
tessera-sign sign   --key ./keys/signing.key model.cdx.json
tessera-sign verify --pub ./keys/signing.pub model.cdx.json model.cdx.json.sig

Why this is a separate repository

Tessera itself has zero third-party dependencies, and that is a promise made to every program that embeds it — pinned by a test. Post-quantum signatures need a vetted cryptographic library, and nobody should be hand-rolling one. Keeping the signing in its own module means a service that only wants to read model files never acquires a crypto dependency it did not ask for, and this module can take one without touching that guarantee.

The algorithm choice

Signatures are hybrid: every document is signed twice, independently, and both signatures must verify. If either algorithm is later broken, the other still holds. That is the conservative composition, and it is also the only one that satisfies every major authority at once rather than optimising for one:

Component	Algorithm	Why
Post-quantum	ML-DSA-87 (FIPS 204, Category 5)	NSA CNSA 2.0's designated general-purpose signature, at its highest parameter set
Classical	ECDSA P-384 (FIPS 186-5)	ANSSI requires a classical algorithm alongside any post-quantum one; BSI TR-02102-1 concurs
Digest	SHA-384 (FIPS 180-4)	The weakest digest CNSA 2.0 permits

A pure ML-DSA signature would satisfy the NSA and fail ANSSI's hybrid requirement. A pure ECDSA signature satisfies neither for the long term. Signing twice costs a few kilobytes and removes the argument.

SLH-DSA-SHA2-256s (FIPS 205) is also available with --conservative. It is hash-based, so it rests on strictly weaker assumptions than ML-DSA's lattices, which is why BSI favours it; the signatures are much larger and slower to produce. Use it when the assumption matters more than the size.

What a signature covers

The signature is over the document's bytes. The document contains a SHA-256 and SHA-384 digest of every file the model is made of, so signing it transitively covers the artifact — provided the document is then checked against the artifact, which is what tessera verify does. Signing a document nobody verifies proves only that the document is unaltered, not that it is true.

The intended sequence is therefore:

tessera bom ./model --format cyclonedx > model.cdx.json   # describe
tessera-sign sign --key signing.key model.cdx.json        # attest
tessera-sign verify --pub signing.pub model.cdx.json model.cdx.json.sig
tessera verify model.cdx.json ./model                     # confirm it still holds

Licence

Apache-2.0.

Documentation

Overview

Package sign produces and verifies hybrid post-quantum signatures over the documents Tessera emits.

This is the embedding surface. The implementation stays in internal/ so its shape can change without breaking importers; this file is what has to stay stable, and it is deliberately small.

Every signature is two signatures. A lattice scheme and an elliptic curve sign the same payload independently and both must verify. The reason is that nobody knows which of the two will fail first: ML-DSA rests on assumptions that are a decade old, and ECDSA rests on assumptions a cryptographically relevant quantum computer would end. Requiring both means a break in either family degrades this to the other rather than to nothing.

It lives in a separate module from tessera itself so that the library's zero-dependency guarantee survives. Signing needs a lattice implementation; parsing a model does not, and an embedder who wants only the parser should not inherit one.

Index

• Constants
• func MarshalPrivate(kp *KeyPair) ([]byte, error)
• func MarshalPublic(kp *KeyPair) ([]byte, error)
• func ParsePublic(data []byte) (pq, ec []byte, err error)
• func Verify(b *Bundle, document, expectedPQPub, expectedECPub []byte) error
• type Bundle
  • func Sign(kp *KeyPair, document []byte, at time.Time) (*Bundle, error)
• type KeyPair
  • func Generate(suite Suite) (*KeyPair, error)
  • func ParsePrivate(data []byte) (*KeyPair, error)
• type Suite

Constants

const (
	// SuiteHybridMLDSA87 is the default: ML-DSA-87 (FIPS 204, Category 5) with
	// ECDSA P-384, over SHA-384.
	SuiteHybridMLDSA87 = bundle.SuiteHybridMLDSA87
	// SuiteHybridSLHDSA is the conservative alternative: SLH-DSA-SHA2-256s
	// (FIPS 205) with ECDSA P-384. Hash-based, so it rests on strictly weaker
	// assumptions than a lattice; signatures are an order of magnitude larger.
	SuiteHybridSLHDSA = bundle.SuiteHybridSLHDSA
)

Functions

func MarshalPrivate

func MarshalPrivate(kp *KeyPair) ([]byte, error)

MarshalPrivate encodes a key pair as PEM. The result is secret.

func MarshalPublic

func MarshalPublic(kp *KeyPair) ([]byte, error)

MarshalPublic encodes the public halves as PEM.

func ParsePublic

func ParsePublic(data []byte) (pq, ec []byte, err error)

ParsePublic reads the public halves from PEM.

func Verify

func Verify(b *Bundle, document, expectedPQPub, expectedECPub []byte) error

Verify checks a signature against a document and the public keys the verifier expects.

The expected keys are parameters rather than being read from the bundle. A verifier that trusts the key travelling inside the thing it is verifying is not verifying anything, and that mistake is common enough in this space to be worth designing against rather than documenting around.

Types

type Bundle

type Bundle = bundle.Bundle

Bundle is a detached signature over one document.

func Sign

func Sign(kp *KeyPair, document []byte, at time.Time) (*Bundle, error)

Sign produces a detached signature over document.

type KeyPair

type KeyPair = bundle.KeyPair

KeyPair holds both halves of a hybrid identity.

func Generate

func Generate(suite Suite) (*KeyPair, error)

Generate creates a new hybrid key pair.

func ParsePrivate

func ParsePrivate(data []byte) (*KeyPair, error)

ParsePrivate reads a private key pair from PEM.

type Suite

type Suite = bundle.Suite

Suite names the algorithm set a signature uses.