Documentation
¶
Overview ¶
Package signer signs OCI artifacts with Sigstore, following the cosign key-pair convention: a "simple signing" payload binding the artifact's manifest digest is signed with the user's key, attached to the registry as a cosign signature manifest (the "sha256-<hex>.sig" tag), and returned as a serialized Sigstore bundle for durable storage and offline re-verification.
It is the signing counterpart to github.com/stacklok/toolhive-core/container/verifier: a bundle produced here verifies through that package's [verifier.VerifyBundleWithKey], and the attached manifest is the layout [verifier.RetrieveBundles] reconstructs from.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrKeyRequired = errors.New("signing key required: a cosign private key is needed to sign")
ErrKeyRequired indicates no signing key was provided. Keyless (OIDC) signing is not implemented yet, so a cosign private key is the only supported signing method. Callers exposing a CLI should wrap this with the flag the user is expected to pass.
Functions ¶
func PayloadDigest ¶
PayloadDigest returns the digest of the simple-signing payload that a signature over the artifact at ref pinned to digestStr covers.
Consumers verifying a stored bundle generally hold only the reference and the artifact digest — not the Result from signing — so this is the supported way to recover the value a bundle verifier needs.
func SimpleSigningPayload ¶
SimpleSigningPayload builds the canonical simple-signing payload for the artifact at ref pinned to digestStr. This payload — not the manifest digest — is what gets signed, per the cosign convention: a verifier recovers the payload from the signature manifest's layer, checks the signature over it, and reads the bound manifest digest out of it. Exported because offline re-verification of a stored key-signed bundle must reconstruct exactly these bytes to check the signature's binding.
Types ¶
type Default ¶
type Default struct {
// contains filtered or unexported fields
}
Default implements Signer with file-based cosign keys.
func NewDefault ¶
NewDefault creates a signer using the given registry auth keychain for pushing the signature manifest. A nil keychain falls back to the default keychain.
func (*Default) SignOCI ¶
func (d *Default) SignOCI(ctx context.Context, ref, digestStr string, opts Options) (*Result, error)
SignOCI signs the artifact following the cosign convention: the signature is computed over the simple-signing payload (which embeds the manifest digest, binding the signature to the artifact), the SAME signature is attached to the registry as a cosign signature manifest, and the returned bundle carries it with the payload's digest as the signed message. A verifier reconstructing the bundle from the registry manifest (or re-verifying the stored bundle offline) therefore checks exactly the signature that was attached — one signature, two representations.
type Options ¶
type Options struct {
// Key is the path to a cosign PEM-encoded private key file. An
// encrypted key is decrypted with the COSIGN_PASSWORD environment
// variable, matching the cosign CLI.
Key string
}
Options configures OCI signing.
type Result ¶
type Result struct {
// Bundle is the serialized Sigstore bundle, for durable storage and
// later offline re-verification.
Bundle []byte
// PayloadDigest is the "<algorithm>:<hex>" digest of the simple-signing
// payload the bundle actually signs.
//
// This is deliberately surfaced because it is NOT the artifact digest
// passed to SignOCI. Following the cosign convention, the signature
// covers a payload that *embeds* the artifact digest rather than the
// digest itself, so verifying Bundle offline requires this value —
// passing the artifact digest to a bundle verifier will always fail.
// See [PayloadDigest] to recompute it from a reference and digest alone.
PayloadDigest string
}
Result is the outcome of a signing operation.
type Signer ¶
type Signer interface {
// SignOCI signs the artifact at ref pinned to the given manifest digest
// ("sha256:..."), attaches the signature as a cosign signature manifest
// next to the artifact, and returns the bundle together with the digest
// it signs.
SignOCI(ctx context.Context, ref, digest string, opts Options) (*Result, error)
}
Signer signs OCI artifacts and attaches the signature to the registry.
Source Files