Documentation
¶
Overview ¶
Package cosign is the ONLY cosign-aware code in StageFreight signing — the edge renderer that satisfies a sign.SignPlan (a declarative trust contract) against a declared capability Env, emitting a concrete cosign invocation. It imports sign (the pure model); sign never imports it. No interface, no registry: a future native signer is just another renderer of SignPlan, added when it exists. See docs/architecture/signing-trust-model.md (1e).
Index ¶
- func Attest(ctx context.Context, rootDir string, desired map[string]config.ToolConstraint, ...) error
- func Available(rootDir string, desired map[string]config.ToolConstraint) bool
- func Render(p sign.SignPlan, op sign.Op, env Env) (args []string, err error)
- func SignBlob(ctx context.Context, rootDir string, desired map[string]config.ToolConstraint, ...) error
- func SignImage(ctx context.Context, rootDir string, desired map[string]config.ToolConstraint, ...) error
- func SigstoreDomain(plan sign.SignPlan, env Env) string
- type Env
- type FIDO2Device
- type KMSKey
- type KeyFile
- type KeyGen
- type OIDCIdentity
- type PKCS11Slot
- type Principal
- type SigstoreDeployment
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Attest ¶
func Attest(ctx context.Context, rootDir string, desired map[string]config.ToolConstraint, digestRef string, plan sign.SignPlan, env Env, opts sign.SignOptions) error
Attest binds a predicate to an image digest ref per the plan. The predicate path AND type are caller-supplied (opts) — the executor serializes them, it never defaults a predicate semantic of its own.
func Available ¶
func Available(rootDir string, desired map[string]config.ToolConstraint) bool
Available reports whether cosign can be resolved via the toolchain.
func Render ¶
Render turns a trust contract (sign.SignPlan) into a concrete cosign invocation by SATISFYING its requirements against the declared Env. It is a capability- satisfaction emitter, not a mode selector — and genuinely pure given (plan, op, env): a constraint solver over distinct trust PRINCIPALS, then a flag emitter. It reads NO ambient environment — logical refs (key/kms) are resolved into Env witnesses by EnvForPlan beforehand, so the env-read is isolated to that boundary.
The load-bearing rule is the principal count |D| for the plan's class:
|D| == 0 → error (no declared capability satisfies the contract)
|D| == 1 → use it
|D| > 1 → error (a genuine TRUST ambiguity — distinct keys could sign;
never silently pick one)
One principal reachable many ways (the same hardware key via FIDO2 and PKCS#11) is |D| == 1, resolved by a deterministic internal transport preference — that is a transport choice, not a trust choice, so it is decided here, not refused.
Render emits only the trust + policy flags (key/sk, tlog, upload). The op target — image digest, blob path, --predicate — is appended by the executor, which owns the live inputs; keeping it out of Render is what keeps Render pure and testable.
func SignBlob ¶
func SignBlob(ctx context.Context, rootDir string, desired map[string]config.ToolConstraint, blobPath, sigPath string, plan sign.SignPlan, env Env) error
SignBlob signs a detached blob (e.g. SHA256SUMS) per the plan, writing the detached signature to sigPath. The caller chooses sigPath so additive, multi-tier signing can write distinct files (never clobbering a lower-tier sig).
func SignImage ¶
func SignImage(ctx context.Context, rootDir string, desired map[string]config.ToolConstraint, digestRef string, plan sign.SignPlan, env Env, opts sign.SignOptions) error
SignImage signs an image digest ref (repo@sha256:…; tags are never used) per the plan's trust contract. opts.MultiArch adds --recursive (sign the whole index).
func SigstoreDomain ¶
SigstoreDomain returns the trust-domain label to RECORD for an oidc/keyless signature — the named ecosystem that vouched for it. Empty for non-oidc classes (no Sigstore domain). For oidc: the explicit Domain label if set, else the Fulcio host for a declared self-hosted deployment, else "public-sigstore". Mirrors the Render decision so the recorded evidence matches where the signature actually went.
Types ¶
type Env ¶
type Env struct {
Keys []KeyFile
KMS []KMSKey
FIDO2 []FIDO2Device
PKCS11 []PKCS11Slot
OIDC []OIDCIdentity
Sigstore SigstoreDeployment // oidc/keyless trust domain (single deployment, not a principal set)
}
Env is the declared capability graph the deployment exposes to the renderer.
func EnvForPlan ¶
EnvForPlan resolves a plan's logical references against the ambient environment into a declared witness Env — the impure resolution boundary that keeps Render itself pure over (plan, op, env). It resolves what has a REF (key/kms/oidc, and the hardware PKCS#11 transport); ref-less hardware witnesses (a present FIDO2 token) are declared externally by the caller and merged in.
type FIDO2Device ¶
type FIDO2Device struct {
Principal Principal
PhysicalPresence bool // touch required to sign
NonExportable bool // key generated on-device, never extractable
}
FIDO2Device is a `hardware`-class witness signed via cosign --sk.
type KMSKey ¶
type KMSKey struct {
Principal Principal
URI string // resolved KMS URI — opaque to core (provider scheme lives only here)
}
KMSKey is a `kms`-class witness (a managed/remote key, addressed by URI).
type KeyGen ¶
type KeyGen struct {
RootDir string
Desired map[string]config.ToolConstraint
}
KeyGen is a provision.KeyGenerator backed by `cosign generate-key-pair`. The Tier-0 key is generated with an EMPTY password — the signing state dir (an operator-chosen durable volume) is the protection boundary, not a passphrase. Tier-0 optimizes persistence + frictionless adoption, not maximum assurance; harden by climbing the custody ladder (SoftHSM → Vault → hardware).
type OIDCIdentity ¶
OIDCIdentity is an `oidc`-class (keyless) signer claim.
type PKCS11Slot ¶
PKCS11Slot is a `hardware`-class witness signed via cosign --key <pkcs11:...>.
type Principal ¶
type Principal string
Principal is a stable trust-principal identity — the model's single load-bearing assumption, made explicit AS DATA. For cryptographic classes it is the key's public-key fingerprint (derived from key material when the Env is constructed — not a free-text label); for oidc it is the (issuer, subject) claim. Render groups witnesses by Principal, so identity equivalence is represented in data, never inferred from transport/endpoint shape.
type SigstoreDeployment ¶
type SigstoreDeployment struct {
Domain string // human label for the trust domain (e.g. "internal", "prplanit")
FulcioURL string // self-hosted Fulcio (CA) — empty = public
RekorURL string // self-hosted Rekor (transparency log) — empty = public
OIDCIssuer string // the OIDC issuer minting identity tokens (valid for public + self-hosted)
TrustedRoot string // path to the trusted-root bundle anchoring this domain's CA + log keys
IdentityToken string // OIDC token value or path (cosign --identity-token); ambient providers used when empty
}
SigstoreDeployment is the named trust DOMAIN an `oidc` (keyless) signature is produced against — the answer to "which signing-authority ecosystem vouches for this evidence?", not a bag of optional endpoint overrides. A future verification engine reasons over this (public vs internal Sigstore, trust-root migration, multi-domain policy, mirrored Rekor), so it is modeled as a first-class domain even though v1 only carries URLs + a label.
Empty Fulcio/Rekor/TrustedRoot = the public Sigstore default (TUF service discovery). Any of them set = a declared (typically self-hosted) deployment the renderer points cosign at explicitly. Resolved from SF_SIGSTORE_* by EnvForPlan — the renderer reads this witness but never the environment.
func (SigstoreDeployment) Declared ¶
func (d SigstoreDeployment) Declared() bool
Declared reports whether a self-hosted Sigstore deployment is configured — keyed on the presence of a service endpoint or trust anchor (NOT Domain, which is only a disclosure label, nor OIDCIssuer, which a public deployment may also override).
Source Files