sign

README

sign

Ed25519 signing for pkgx bottles — interoperable with both minisign and cosign from a single keypair. Pure Go, CGO_ENABLED=0, zero non-crypto dependencies.

A bottle is distributed two ways, so it needs two signature encodings over the same bytes:

• as a tarball over HTTP (dist.pkgx.dev/…/v1.2.3.tar.gz) → a detached minisign .minisig served alongside it;
• as an OCI artifact (ghcr.io/go-pkgx/bottles/…) → a cosign blob signature / image signature.

Both are a plain Ed25519 signature over the bottle bytes, so one keypair and one signature value cover both transports.

Library

kp, _ := sign.Generate()

// minisign — verifies with `minisign -V`
minisig := kp.SignMinisign(tarball, "", "bottle openssl.org 1.1.1w")
_ = sign.VerifyMinisign(tarball, minisig, kp.PublicKeyString())

// cosign — verifies with `cosign verify-blob --key cosign.pub`
pem, _ := kp.PublicKeyPEM()          // cosign public key
b64 := kp.SignBlob(tarball)          // cosign --signature value
pub, _ := sign.ParsePublicKeyPEM(pem)
_ = sign.VerifyBlob(tarball, b64, pub)

Verifying minisign's prehashed (ED, Blake2b-512) form is supported too; the library only emits the legacy (Ed) form so verification needs nothing beyond crypto/ed25519.

CLI

sign keygen --pub k.pub --sec k.key [--comment C]   # writes k.pub, k.pub.pem (cosign), k.key
sign sign   --sec k.key [--comment C] <file>        # writes <file>.minisig and <file>.cosig
sign verify --pub k.pub <file>                       # verifies <file>.minisig

Interoperability

Proven in CI-independent tests against the real minisign and cosign binaries (skipped automatically where those tools are absent):

• our .minisig verifies under minisign -V, and we verify minisign's own output;
• our blob signature verifies under cosign verify-blob --key.

License

BSD-3-Clause © the sign authors.

Documentation

Overview

Package sign signs pkgx bottles with Ed25519, interoperably with both minisign (detached .minisig files, for tarballs served over HTTP from dist.pkgx.dev) and cosign (PEM keys + blob signatures, for bottles published as OCI artifacts on ghcr.io). A single Ed25519 keypair backs both: minisign and cosign each verify a plain Ed25519 signature over the bottle bytes, so one signature value serves both transports.

The package is pure standard library for signing and for verifying legacy ("Ed") signatures; verifying minisign's prehashed ("ED") form additionally pulls in golang.org/x/crypto/blake2b. CGO_ENABLED=0.

Index

• func ParsePublicKeyPEM(p []byte) (ed25519.PublicKey, error)
• func SimpleSigningPayload(dockerRef, manifestDigest string) ([]byte, error)
• func VerifyBlob(data []byte, b64sig string, pub ed25519.PublicKey) error
• func VerifyMinisign(data []byte, minisig, pubkey string) error
• type KeyID
  • func ParsePublicKey(s string) (KeyID, ed25519.PublicKey, error)
• type Keypair
  • func Generate() (*Keypair, error)
  • func LoadSecretKey(s string) (*Keypair, error)
  • func (k *Keypair) PublicKeyFile(comment string) string
  • func (k *Keypair) PublicKeyPEM() ([]byte, error)
  • func (k *Keypair) PublicKeyString() string
  • func (k *Keypair) SecretKeyFile(comment string) string
  • func (k *Keypair) SignBlob(data []byte) string
  • func (k *Keypair) SignMinisign(data []byte, untrusted, trusted string) string
  • func (k *Keypair) SignPayload(payload []byte) string

Functions

func ParsePublicKeyPEM

func ParsePublicKeyPEM(p []byte) (ed25519.PublicKey, error)

ParsePublicKeyPEM decodes a PKIX PEM Ed25519 public key (a cosign.pub).

func SimpleSigningPayload

func SimpleSigningPayload(dockerRef, manifestDigest string) ([]byte, error)

SimpleSigningPayload builds cosign's "simple signing" JSON payload binding a signature to an OCI image by its manifest digest (e.g. "sha256:abc…") and reference. This payload — not the raw bytes — is what a cosign image signature covers; bottle stores it as the signature artifact's layer and SignPayload's output in the cosign signature annotation.

func VerifyBlob

func VerifyBlob(data []byte, b64sig string, pub ed25519.PublicKey) error

VerifyBlob checks a base64 Ed25519 blob signature (cosign form) over data.

func VerifyMinisign

func VerifyMinisign(data []byte, minisig, pubkey string) error

VerifyMinisign checks a detached minisign signature over data against a minisign public key. Both legacy ("Ed") and prehashed ("ED", Blake2b-512) algorithms are accepted, so signatures made by the minisign CLI verify too.

Types

type KeyID

type KeyID [8]byte

KeyID is minisign's 8-byte key identifier, echoed in every signature so a verifier can tell which key a signature claims to originate from.

func ParsePublicKey

func ParsePublicKey(s string) (KeyID, ed25519.PublicKey, error)

ParsePublicKey decodes a minisign public key from either a one-line key string or a full .pub file (whose last non-empty line is the key).

type Keypair

type Keypair struct {
	ID      KeyID
	Public  ed25519.PublicKey
	Private ed25519.PrivateKey
}

Keypair is an Ed25519 signing keypair plus its minisign-style KeyID.

func Generate

func Generate() (*Keypair, error)

Generate creates a fresh Ed25519 keypair with a random KeyID.

func LoadSecretKey

func LoadSecretKey(s string) (*Keypair, error)

LoadSecretKey parses a SecretKeyFile back into a Keypair.

func (*Keypair) PublicKeyFile

func (k *Keypair) PublicKeyFile(comment string) string

PublicKeyFile returns the two-line minisign public-key file (comment + key).

func (*Keypair) PublicKeyPEM

func (k *Keypair) PublicKeyPEM() ([]byte, error)

PublicKeyPEM encodes the Ed25519 public key as a PKIX PEM block — the form `cosign verify-blob --key <file>` and `cosign verify --key <file>` expect.

func (*Keypair) PublicKeyString

func (k *Keypair) PublicKeyString() string

PublicKeyString encodes the public key as minisign's one-line base64 form, base64("Ed" || keyID || pubkey) — the "RW…"-prefixed string a verifier stores as the second line of a .pub file.

func (*Keypair) SecretKeyFile

func (k *Keypair) SecretKeyFile(comment string) string

SecretKeyFile encodes the keypair's private key for storage by go-pkgx tools: a comment line plus base64(keyID || Ed25519 private key). This is not minisign's scrypt-encrypted format — it is meant for CI signing keys held in a secret store, so protection is the store's job, not a passphrase.

func (*Keypair) SignBlob

func (k *Keypair) SignBlob(data []byte) string

SignBlob returns the base64 Ed25519 signature over data, matching what `cosign sign-blob --key … <file>` emits and what `cosign verify-blob --signature …` checks. It is the same signature value SignMinisign embeds, in cosign's encoding.

func (*Keypair) SignMinisign

func (k *Keypair) SignMinisign(data []byte, untrusted, trusted string) string

SignMinisign returns a detached minisign signature file (the content of a .minisig) over data. It uses legacy Ed25519 (algorithm "Ed", signature over the raw message) so `minisign -V` and crypto/ed25519 both verify it without Blake2b. The trusted comment is authenticated by the trailing global signature; untrusted defaults if empty.

func (*Keypair) SignPayload

func (k *Keypair) SignPayload(payload []byte) string

SignPayload signs an arbitrary payload (e.g. a SimpleSigningPayload) and returns the base64 signature to store in cosign's `dev.cosignproject.cosign/signature` annotation.