Skip to content

Reference

Factual descriptions of everything the module exposes: configuration fields and their defaults, every sentinel error, every tunable, the backend registry, and the on-disk formats it reads and writes.

The generated Go API (signatures, doc comments, runnable Example tests) is on pkg.go.dev. These pages cover what a signature alone does not tell you: what a field defaults to, what happens when it is wrong, and which declared symbols this module never acts on.

Which package holds what

The module is gitlab.com/phpboyscout/go/signing. Five importable packages:

Import path What it does Import it when
.../go/signing The Backend contract, the process-global backend registry, and named instances (RegisterFactory, NewInstance) You resolve a signing key by backend name
.../go/signing/verify Trust sets, key resolvers (embedded, WKD, composite), detached-signature verification You consume someone else's signed release
.../go/signing/openpgpkey Mints OpenPGP public keys (RSA only), produces detached signatures, writes a WKD tree You publish OpenPGP-signed manifests
.../go/signing/minisign Produces and verifies prehashed minisign signatures over artefacts (Ed25519 only) Your consumers are Rust tools that do not parse OpenPGP
.../go/signing/local The local backend: an unencrypted PEM key on disk (RSA or Ed25519) You sign without a KMS

A verify-only consumer imports verify alone. That path pulls in ProtonMail/go-crypto and gitlab.com/phpboyscout/go/errors, and with them what go-crypto requires: golang.org/x/crypto and cloudflare/circl for its OpenPGP implementation. go/errors has no dependencies of its own. No cloud SDK, no framework. minisign has the narrower graph of the two: it needs golang.org/x/crypto for BLAKE2b and go/errors, but no OpenPGP stack at all.

Test doubles

Generated testify mocks ship under mocks/, so a downstream test can stand in for a backend or a key resolver without running mockery itself. The generated packages keep their source package's name, so give the import an alias:

Import path Package Mock
.../go/signing/mocks signing MockBackend
.../go/signing/mocks/verify verify MockKeyResolver 
import signingmocks "gitlab.com/phpboyscout/go/signing/mocks"

backend := signingmocks.NewMockBackend(t)
backend.EXPECT().Name().Return("fake")

just mocks regenerates them from .mockery.yml.

Reference pages

  • Configuration fields: every exported config struct, field by field, with defaults and failure modes.
  • Errors: every exported sentinel, what raises it, and what to do.
  • Limits, defaults and tunables: size caps, the key strength floor, comment limits, and which package-level variables this module actually reads.
  • The backend registry: Register, Get, Names, named instances, the panic conditions, and what keyID means per backend.
  • File formats: the minisign signature and public-key files, the WKD directory layout, and the OpenPGP artefacts.

API stability

The module is pre-1.0, so the usual Go pre-1.0 rules apply: a minor-version bump may break the API. The releases page and CHANGELOG.md say what each one changed.

The package documentation marks signing (the Backend contract), openpgpkey.DetachSign and the whole minisign package as Beta. The stated evolution path for Backend is additive only (capability discovery, for instance, or further key algorithms), because a breaking change there would break every out-of-tree backend module at once.

signing.ResetForTesting is exported but is a test helper. It clears the global registry and every registered factory, and production code must not call it.