Key and certificate management

Commands that produce, import, or interact with keys and certificates rather than signing or verifying anything.

cosign generate-key-pair

cosign generate-key-pair [--output-key-prefix prefix]
cosign generate-key-pair --kms <kms-uri>
cosign generate-key-pair k8s://<namespace>/<secret-name>
cosign generate-key-pair gitlab://<owner>/<project>
cosign generate-key-pair github://<owner>/<repo>

Implementation: cmd/cosign/cli/generate_key_pair.go + pkg/cosign/keys.go (GenerateKeyPair).

• Default: writes cosign.key (P-256 ECDSA private key, encrypted with nacl/secretbox keyed by an scrypt-derived password) and cosign.pub (PEM public key).
• --kms produces a key in the specified KMS provider; only the public key is exported locally.
• k8s://... uploads the encrypted private key + public key into a Kubernetes Secret. Implementation: pkg/cosign/kubernetes/.
• gitlab:///github:// upload the public key as a project/repo variable for use by CI verifiers. Implementation: pkg/cosign/git/gitlab/ and pkg/cosign/git/github/.

The encryption scheme is documented in pkg/cosign/keys.go::EncryptKey — a private key is wrapped with a key derived from scrypt(password, salt) and stored as PEM with type ENCRYPTED COSIGN PRIVATE KEY.

cosign import-key-pair

cosign import-key-pair --key existing.pem [--output-key-prefix prefix]

Implementation: cmd/cosign/cli/import_key_pair.go. Reads an existing PEM key (P-256 ECDSA, RSA, or Ed25519), encrypts it with cosign's scheme, and emits import-cosign.key / import-cosign.pub. Useful when migrating an existing release signing key into cosign's expected format.

cosign public-key

cosign public-key --key path|kms-uri [--outfile cosign.pub]
cosign public-key --sk

Implementation: cmd/cosign/cli/public_key.go. Extracts the public half of an encrypted local key, a KMS key, or a PIV smart-card key. Handy for distributing the verifier-side material.

cosign piv-tool

cosign piv-tool generate-key [--slot signature]
cosign piv-tool attestation
cosign piv-tool reset
cosign piv-tool set-management-key
cosign piv-tool set-pin
cosign piv-tool set-puk
cosign piv-tool unblock

Implementation: cmd/cosign/cli/piv_tool.go (active build tag pivkey) and the stub cmd/cosign/cli/piv_tool_disabled.go for builds without it.

The piv-tool family uses go-piv/piv-go to talk to a Yubikey (or any PIV-compatible smart card) — generate a hardware-resident signing key, fetch its attestation, change PINs/PUKs, factory-reset, etc. The signing key generated this way is then used by cosign sign --sk.

Backed by pkg/cosign/pivkey/.

cosign pkcs11-tool

cosign pkcs11-tool list-tokens
cosign pkcs11-tool list-keys-uris

Implementation: cmd/cosign/cli/pkcs11_tool.go (active build tag pkcs11key) and stub cmd/cosign/cli/pkcs11_tool_disabled.go.

Wraps a vendor-provided PKCS#11 module (path via COSIGN_PKCS11_MODULE_PATH, PIN via COSIGN_PKCS11_PIN) and lists tokens and the keys on them, returning RFC 7512 pkcs11: URIs that cosign sign --key pkcs11:... understands.

Backed by pkg/cosign/pkcs11key/.

cosign login

cosign login <registry>

This is crane auth login re-exported — registered at the bottom of cmd/cosign/cli/commands.go as cranecmd.NewCmdAuthLogin("cosign"). It writes credentials to the docker config, after which cosign sign/verify pick them up via the standard go-containerregistry keychain.

Key source files

File	Purpose
cmd/cosign/cli/generate_key_pair.go	generate-key-pair
cmd/cosign/cli/import_key_pair.go	import-key-pair
cmd/cosign/cli/public_key.go	public-key
cmd/cosign/cli/piv_tool.go	PIV smart-card subtree (with pivkey tag)
cmd/cosign/cli/pkcs11_tool.go	PKCS#11 subtree (with pkcs11key tag)
pkg/cosign/keys.go	Encrypted local key format (~330 lines)
pkg/cosign/pivkey/	PIV implementation
pkg/cosign/pkcs11key/	PKCS#11 implementation
pkg/cosign/kubernetes/secret.go	Kubernetes Secret upload/download
pkg/cosign/git/github/	GitHub repo variable storage
pkg/cosign/git/gitlab/	GitLab project variable storage