Documentation
¶
Overview ¶
Package signing provides cosign-compatible signing and verification for cargoship packages, against an ordinary cosign keypair.
Originally a fork of zarf's src/pkg/signing, which wrapped cosign's CLI command structs. Those are gone: the command structs carried Fulcio, OIDC, cloud KMS, transparency-log and policy-evaluation machinery that cannot be reached from the air-gapped management node cargoship runs on, and that linked Open Policy Agent, cuelang, go-github and the GitLab client into the binary. Signing and verification now go through sigstore-go in signkey.go and verifykey.go.
A cosign keypair is the only supported signing method. Keyless (Fulcio/OIDC) signing and verification were removed; see docs/agent/choice-signing-fork.md and https://github.com/colonel-byte/cargoship/issues/848.
Index ¶
- Constants
- func CosignSignBlobWithOptions(ctx context.Context, blobPath string, opts SignBlobOptions) ([]byte, error)
- func CosignVerifyBlobWithOptions(ctx context.Context, blobPath string, opts VerifyBlobOptions) error
- func SignBlobWithKey(ctx context.Context, keyPath, password, blobPath, bundlePath string) error
- func VerifyBlobWithKey(publicKeyPath, bundlePath, blobPath string) (err error)
- type BundleInfo
- type SignBlobOptions
- type SigningMethod
- type VerifyBlobOptions
Constants ¶
const CosignDefaultTimeout = 3 * time.Minute
CosignDefaultTimeout is the default timeout for sign and verify operations.
Variables ¶
This section is empty.
Functions ¶
func CosignSignBlobWithOptions ¶
func CosignSignBlobWithOptions(ctx context.Context, blobPath string, opts SignBlobOptions) ([]byte, error)
CosignSignBlobWithOptions signs a blob with a cosign keypair and writes a Sigstore bundle beside it.
func CosignVerifyBlobWithOptions ¶
func CosignVerifyBlobWithOptions(ctx context.Context, blobPath string, opts VerifyBlobOptions) error
CosignVerifyBlobWithOptions verifies a blob against a cosign public key and the Sigstore bundle beside it.
func SignBlobWithKey ¶
SignBlobWithKey signs blobPath with a cosign-format private key and writes a Sigstore bundle to bundlePath, using sigstore-go rather than cosign's CLI.
No transparency log, no timestamp authority and no Fulcio certificate: the bundle carries the public key and the signature, which is all an air-gapped verifier has to work with. Nothing here reaches the network.
func VerifyBlobWithKey ¶
VerifyBlobWithKey verifies a Sigstore bundle over blobPath against a PEM-encoded public key, using sigstore-go rather than cosign's CLI command structs.
This is the air-gapped case and only that case: a key the operator holds, a bundle beside the artifact, no Fulcio certificate, no transparency log lookup and no timestamp authority. Nothing here reaches the network.
It is the only verification path there is. The certificate and keyless paths were removed because each of them has to reach a cloud endpoint, and CosignVerifyBlobWithOptions is now the options-struct wrapper that delegates here rather than an alternative to it. See docs/agent/choice-signing-fork.md, and https://github.com/colonel-byte/cargoship/issues/848 to argue for keyless returning.
Types ¶
type BundleInfo ¶
type BundleInfo struct {
Method SigningMethod
Identity string // cert SAN — empty for key-based signatures
Issuer string // OIDC issuer — empty for key-based signatures
HasTSATimestamps bool // true if the bundle contains signed timestamps
}
BundleInfo contains parsed metadata from a Sigstore bundle file.
func ReadBundleInfo ¶
func ReadBundleInfo(bundlePath string) (BundleInfo, error)
ReadBundleInfo parses a Sigstore bundle file and returns its signing metadata.
type SignBlobOptions ¶
type SignBlobOptions struct {
// Key is the path to a cosign-format private key.
Key string
// BundlePath is where the Sigstore bundle is written.
BundlePath string
// Password decrypts the private key. PassFunc takes precedence, and
// COSIGN_PASSWORD is the fallback when neither is set.
Password string
// PassFunc resolves the private-key password, taking precedence over Password.
PassFunc cosign.PassFunc
// Overwrite allows CheckOverwrite to replace an existing bundle.
Overwrite bool
// Timeout bounds the whole operation.
Timeout time.Duration
// Deprecated: use Key. Removed in a future version.
KeyRef string
}
SignBlobOptions holds the signing configuration for a blob.
func DefaultSignBlobOptions ¶
func DefaultSignBlobOptions() SignBlobOptions
DefaultSignBlobOptions returns the signing defaults.
func (SignBlobOptions) CheckOverwrite ¶
func (opts SignBlobOptions) CheckOverwrite(ctx context.Context) error
CheckOverwrite errors if the bundle already exists and Overwrite is false.
type SigningMethod ¶
type SigningMethod string
SigningMethod identifies how a Sigstore bundle was signed.
const ( // SigningMethodKeyless indicates a Fulcio-issued certificate bundle (OIDC/keyless). SigningMethodKeyless SigningMethod = "keyless" // SigningMethodKey indicates a public-key bundle. SigningMethodKey SigningMethod = "key" )
type VerifyBlobOptions ¶
type VerifyBlobOptions struct {
// Key is the path to a PEM-encoded cosign public key.
Key string
// BundlePath is the Sigstore bundle to verify against.
BundlePath string
// Timeout bounds the whole operation.
Timeout time.Duration
// Deprecated: use Key. Removed in a future version.
KeyRef string
}
VerifyBlobOptions holds the verification configuration for a blob.
func DefaultVerifyBlobOptions ¶
func DefaultVerifyBlobOptions() VerifyBlobOptions
DefaultVerifyBlobOptions returns the verification defaults.