signing

README

signing

gitlab.com/phpboyscout/signing — OpenPGP/WKD release signing & verification as a light, dependency-inverted Go library.

It is the org's canonical signing/verification model (the same one behind gtb update), extracted so projects can verify signed releases or sign their own without pulling in the go-tool-base framework.

Design

• Light core. Depends only on ProtonMail/go-crypto and cockroachdb/errors. No cloud SDK, no web framework, no go-tool-base.
• Dependency-inverted backends. The library defines a crypto.Signer-producing Backend interface; heavy/remote backends (AWS KMS, GCP, Azure, HSM, …) are implemented by the consumer and injected. A light local (PEM) backend ships as a default and reference.
• Stdlib seams. crypto.Signer (keys), *slog.Logger (logging), *http.Client (WKD) — inject your own; everything has a sane default.
• Verification. Composite embedded-keys + WKD fingerprint cross-check + detached OpenPGP signature over a checksums manifest.

Packages

Package	Purpose
gitlab.com/phpboyscout/signing	The Backend contract + registry
gitlab.com/phpboyscout/signing/local	Light PEM-on-disk RSA backend (default/reference)
gitlab.com/phpboyscout/signing/openpgpkey	OpenPGP sign/verify + WKD primitives
gitlab.com/phpboyscout/signing/verify	Trust model: resolvers, trust set, signature verification

Quick start (verify a signed release)

trust, err := verify.LoadTrustSet(publisherArmoredPubKey)
if err != nil {
    return err
}
if err := trust.VerifyManifestSignature(manifest, signature); err != nil {
    return err // tampered or untrusted — reject
}
// verified

See the runnable Example tests on pkg.go.dev for the full sign→verify round-trip and the local backend.

Documentation

• Guides & explanation: the documentation site (tutorial, how-to, trust model, threat model) — sources under docs/.
• API reference: pkg.go.dev/gitlab.com/phpboyscout/signing.
• Design: the spec in gitlab.com/phpboyscout/go-tool-base (docs/development/specs/2026-06-30-release-signature-verification-module.md), tracked by work item #1.

Licence

MIT — see LICENSE.

Documentation

Overview

Package signing exposes a registry of signing-key backends. Each backend knows how to talk to a specific HSM/KMS/keyring and produce a crypto.Signer that callers (typically pkg/openpgpkey) use to mint an OpenPGP-armored public key.

Backends register themselves at process start via init() calling Register. Downstream binaries opt into a backend by blank-importing its package — this is the same activate-by-side-effect pattern used in net/http/pprof, image/* decoders, and the framework's own pkg/credentials/keychain. The signing-key minter (gtb keys mint) reads the registered names via Names() and dispatches based on the --backend flag the user passes.

Built-in backends shipping with the standard `gtb` binary:

• "aws-kms" (pkg/signing/kms): RSA-4096 keys held in AWS KMS.
• "local" (pkg/signing/local): RSA keys loaded from an unencrypted PKCS#1 or PKCS#8 PEM file on disk. Use for the onboarding tutorial / local signing flows; never in CI.

Third parties add backends by implementing Backend and calling Register from their package's init(). No upstream change is needed. See docs/how-to/add-signing-backend.md for the contract details.

API stability: Beta. The interface is small and stable; the only known evolution path is additive (e.g. ECDSA support, capability- discovery methods).

Index

• Variables
• func Names() []string
• func Register(b Backend)
• func ResetForTesting()
• type Backend
  • func Get(name string) (Backend, error)

Variables

var ErrUnknownBackend = errors.New("unknown signing backend")

ErrUnknownBackend is returned by Get when the named backend is not registered. The error message lists the available backends so users can see what their binary actually ships with.

Functions

func Names

func Names() []string

Names returns the names of all registered backends, sorted alphabetically. Used by `gtb keys mint --help` to enumerate the accepted --backend values for the current binary.

func Register

func Register(b Backend)

Register adds b to the global backend registry. Called from each backend package's init() so that blank-importing the package activates the backend.

Panics on a duplicate name — duplicates indicate a programming error at process init (two backend packages claiming the same identifier) and failing fast is preferable to silent override.

Panics on a nil Backend or one whose Name() is empty. Both are programmer errors that should never reach a deployed binary.

func ResetForTesting

func ResetForTesting()

ResetForTesting clears the registry. The "ForTesting" suffix is the Go-standard signal that this is a test helper — production code must not call it. Exported (rather than hidden behind a _test.go-only build) so that tests in other packages (notably `internal/cmd/keys`) can drive registry-mutating scenarios against fake backends.

Types

type Backend

type Backend interface {
	Name() string
	NewSigner(ctx context.Context, keyID string) (crypto.Signer, error)
}

Backend constructs a crypto.Signer for an HSM/KMS-held signing key. Implementations are registered globally via Register and selected at runtime by Name (matching, e.g., a CLI front-end's --backend flag).

The contract is deliberately minimal and CLI-agnostic so a backend is trivial to implement and the module stays dependency-light (no flag library in the core):

• Name returns a stable identifier (lowercase, kebab-case, unique across the process — duplicate Register calls panic).
• NewSigner returns a crypto.Signer wrapping the remote key. The backend interprets keyID's format — AWS uses ARNs/aliases, a PEM backend uses a file path, GCP uses resource names, etc. The signer's Public() must return a type the caller can consume; openpgpkey currently requires *rsa.PublicKey.

Backends do not own credential resolution; callers configure the SDK / agent / environment before invoking the signer.

A backend that needs to declare its own CLI flags can implement an optional flag-registration interface defined by the CLI front-end (e.g. gtb), which type-asserts for it. The core intentionally does not define or depend on such an interface, keeping any flag library out of this module.

func Get

func Get(name string) (Backend, error)

Get returns the registered backend with the given name. If no such backend is registered, returns ErrUnknownBackend wrapped with a listing of the available names so the user can immediately see what their binary actually supports.