Supsig Specification

http://git.distrust.co/supsig

About

This document defines the specification for "supsig", a portable software supply chain signing solution for code, code reviews, and reproducible artifact builds.

Status

This is currently a DRAFT

Current draft is in use at multiple organizations, but current reference tooling such as "git-sig" uses version "v0" and may break at any time until we stabilize at "v1".

Contributions at this stage are very welcome.

Please collaborate via Matrix at [https://matrix.to/#/#supsig:matrix.org]

Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119 when, and only when, they appear in all capitals, as shown here.

Goals

• Define a broadly applicable signing format for code, reviews, and artifacts
• Define system for anonymous submission and discovery of signatures

Requirements

• MUST defend against a compromise of any single human or system
  • MUST exclusively rely on FOSS dependencies with signed reproducible builds
• MUST be portable with code archives or any known VCS system
• MUST support signing via the CLI, GUI, or web interfaces
  • Web support implies supporting native signing like Passkeys/Webauthn
• SHOULD support any cryptographic tooling supporting detached signatures
  • We SHOULD NOT attempt to force the FOSS community to migrate off of PGP
  • We SHOULD NOT attempt to force PGP on organizations with other solutions
• MUST support a minimal, yet optional, plaintext review format
• MUST support signatures that only indicate reproducible builds
• MUST allow signing a review from a wide range of alternative review systems
  • MAY be small plain-text snippets, or a hash of an external system
• MUST support all supply chain artifacts including reviews, code, and binaries
• MUST communicate and collaborate on project exclusively with FOSS tools
  • We want to be inclusive to the open source community, not just corporations
  • Examples: Forgejo/gitea issues, e-mail, IRC, matrix, jitsi, etc.
• SHOULD seek compatibility with popular supply chain security tooling
  • Examples: in-toto, witness, OCI container signing

Format

"sig:$version:$vcs_ref:$tree_hash:$review_hash:$sig_type:$signature"

• version: (required) version of the supsig format
• vcs: (optional) vcs system used (ex, git, hg,svn,cvs,perforce,etc )
• tree_hash: (required) sha256 hash of the object or directory being signed
• review_hash: (optional) sha256 hash of a review from any review system
• sig_type: (required) signature type (webauthn, pgp, etc)
• signature: (required) actual ascii armored signature payload

Examples

Signature Generation

Shell: Git and GPG with plaintext review

review="LGTM"
review_hash="$(printf $review | openssl sha256 | awk '{print $2}')"
vcs_ref="$(git rev-parse HEAD)"
tree_hash="$(git rev-parse 'HEAD^{tree}')"
body="sig:v0:$vcs_ref:$tree_hash:$review_hash:pgp"
sig=$(printf "%s" "$body" | gpg --detach-sign  | openssl base64 -A )
printf "%s" "$body:$review:$sig"

Signature Verification

PGP

gpg --verify <(printf "$sig_body") <(printf "$sig")

Review Verification

TODO

Background

TODO

Motivation

TODO

Alternatives

Here we will comment on other popular approaches to supply chain integrity, and our opinion on what they get right, and where they fall short.

No signing

Many software distribution systems are very intentional about not supporting signing at all. Some have expressed fears that some developers are intimidated by the idea of signing code or reviews and would stop contributing entirely such practices were normalized.

Attempts to enforce signing are often rejected as an attempt at gatekeeping, Some distribution system maintainers argue that not signing at all is an appropriate security posture given other mitigations such as the availability of two factor authentication.

Years of supply chain attacks on systems with this posture have seemingly done little to nothing to dissuade these positions.

npm

TODO

pip

TODO

brew

TODO

Centralized signing

• sigstore/fulcio
• nix
• apk
• fulcio
• gitsign

Distributed signing

• bitcoin: https://bitcoinops.org/en/topics/reproducible-builds/
• apt: https://wiki.debian.org/SecureApt
• pacman: https://wiki.archlinux.org/title/Pacman/Package_signing
• crev: ??
• git-wotr
• git-signatures
• sigstore
• cosign
• notary

References

Noteworthy Supply Chain Attacks

Funding

This project is housed under the umbrella of Distrust, and self funded to meet the growing needs of Distrust clients, and by extension the wider open source community whose dependencies they heavily rely on.

Funding for this project and team in the current direction, or partnership with existing projects with compatible goals would be very welcome.