gitprov

type Identity ¶

type Identity struct {
	Issuer       string // exact OIDC issuer   (xor the other Issuer kinds)
	IssuerRegex  string // OIDC issuer regex   (xor)
	IssuerGlob   string // OIDC issuer glob    (xor)
	Subject      string // exact cert SAN      (xor the other Subject kinds)
	SubjectRegex string // cert SAN regex      (xor)
	SubjectGlob  string // cert SAN glob       (xor)
}

Identity is the caller's statement of who may sign (REQ-verify-identity-match): each axis carries exactly one pattern kind — an exact string, a full-match regular expression, or a full-input glob (`/`-separated component semantics; the greatliontech/glob pattern language).

func (id Identity) Validate() error

type ImageCarrier ¶

type ImageCarrier interface {
	// contains filtered or unexported methods
}

ImageCarrier is one of the two carriers cosign produces for a signature over an OCI manifest or index digest (verification.md, Image signatures): a SigstoreBundle or a SimpleSigningEnvelope, as bytes the caller fetched. Where a carrier is found for a digest and how many are judged is the caller's; each VerifyImage call verifies one.

type Object ¶

type Object struct {
	Kind   ObjectKind
	Format ObjectFormat
	Raw    []byte
}

Object is a git object presented for verification: its kind, the object format its raw bytes are in, and the raw object bytes — the git-core content after the "<type> <len>\0" header, exactly as git hashes it. Any re-encode through an object parser is not raw and would verify bytes the origin never signed (REQ-verify-raw-bytes).

type ObjectFormat ¶

type ObjectFormat string

ObjectFormat names a git object format — the hash algorithm whose form the raw bytes are in. It is caller-stated, never inferred from the bytes (REQ-verify-object-formats).

const (
	SHA1   ObjectFormat = "sha1"
	SHA256 ObjectFormat = "sha256"
)

type ObjectKind ¶

type ObjectKind string

ObjectKind names the two signable git object kinds.

const (
	Commit ObjectKind = "commit"
	Tag    ObjectKind = "tag"
)

type PinnedKey ¶

type PinnedKey struct {
	// contains filtered or unexported fields
}

PinnedKey is a public key the caller hands in for a verification — an OpenPGP public key, or an SSH one — verified against directly, never looked up (REQ-verify-pinned-key). It is made by ParsePinnedKey alone: its fingerprint is derived from the parsed key there, so a key and a fingerprint that disagree cannot be built.

func ParsePinnedKey(kind SignatureKind, key string) (PinnedKey, error)

func (k PinnedKey) Fingerprint() string

func (k PinnedKey) Kind() SignatureKind

type SignatureKind ¶

type SignatureKind string

SignatureKind is what signed a git object, selected by the label of the signature's armor header line (REQ-verify-signature-kind): gitsign's CMS under SIGNED MESSAGE, an OpenPGP signature under PGP SIGNATURE, an SSH signature under SSH SIGNATURE. The kind selects the verifier and nothing else does: a verification of one kind handed a signature of another fails with ErrSignatureKind rather than reading the bytes as its own.

const (
	// Sigstore is gitsign's CMS signature, verified by Verify against a
	// trusted root.
	Sigstore SignatureKind = "sigstore"
	// OpenPGP is an OpenPGP signature, verified against pinned keys.
	OpenPGP SignatureKind = "openpgp"
	// SSH is an SSH signature, verified against pinned keys.
	SSH SignatureKind = "ssh"
)

func SignatureKindOf(obj Object) (SignatureKind, error)

type SigstoreBundle ¶

type SigstoreBundle struct {
	JSON []byte // the bundle as serialized
}

SigstoreBundle is the carrier cosign's default sign writes: a sigstore bundle of version 0.3 — a DSSE envelope with one signature over an in-toto v1 statement naming the digest as a subject under the cosign sign predicate type, with the leaf certificate, a transparency-log entry and any RFC 3161 timestamps as verification material — attached to the manifest as an OCI referrer whose artifact type is the bundle's media type.

type SimpleSigningEnvelope ¶

type SimpleSigningEnvelope struct {
	// Payload is the layer's content, a simple-signing document
	// (application/vnd.dev.cosign.simplesigning.v1+json) naming the
	// digest at critical.image.docker-manifest-digest.
	Payload []byte
	// Signature is the dev.cosignproject.cosign/signature annotation:
	// the signature over the payload bytes, base64.
	Signature string
	// Certificate is the dev.sigstore.cosign/certificate annotation:
	// the Fulcio leaf, PEM.
	Certificate string
	// Chain is the dev.sigstore.cosign/chain annotation, PEM, or empty.
	Chain string
	// RekorBundle is the dev.sigstore.cosign/bundle annotation: the
	// signed entry timestamp with the entry's body, log index, log
	// identifier and integrated time, JSON.
	RekorBundle string
	// RFC3161Timestamp is the dev.sigstore.cosign/rfc3161timestamp
	// annotation, JSON holding the DER timestamp response base64, or
	// empty.
	RFC3161Timestamp string
}

SimpleSigningEnvelope is cosign's legacy carrier, a signature layer under the repository's sha256-<hex>.sig tag or a referrer whose configuration media type is application/vnd.dev.cosign.artifact.sig .v1+json: the layer's payload and its annotations, each as cosign wrote it.

type TrustedRoot ¶

type TrustedRoot struct {
	// contains filtered or unexported fields
}

TrustedRoot is a pinned sigstore TUF trusted root plus the digest of the exact bytes it was loaded from. The digest is computed over the raw bytes before parsing — a parse round-trip is not canonical, so only the raw bytes are a stable identity (REQ-root-pinned-bytes) — and rides into every VerifiedIdentity produced against this root.

The fields are unexported so the parsed root and its digest can never diverge: ParseTrustedRoot/LoadTrustedRoot are the only producers. The zero value is unusable and rejected by Verify.

func LoadTrustedRoot(path string) (*TrustedRoot, error)

func ParseTrustedRoot(raw []byte) (*TrustedRoot, error)

func (t *TrustedRoot) Digest() string

type VerifiedIdentity ¶

type VerifiedIdentity struct {
	Subject             string // the cert SAN that matched policy
	Issuer              string // the cert OIDC issuer
	CertFingerprint     string // "sha256:<hex>" of the leaf cert DER
	RekorLogIndex       int64  // transparency not required ⇒ 0; with it, a genuine entry MAY still be index 0 (Rekor logIndex minimum is 0) — not an unset sentinel
	RekorIntegratedTime int64  // 0 iff transparency was not required (a real entry's integratedTime is wall-clock seconds, never the 1970 epoch — this IS a reliable unset signal); for an image, the signed time the leaf was judged at
	TrustedRootDigest   string // the pinned-root digest verified against (TrustedRoot.Digest)
	Digest              string // for an image, the "<algorithm>:<hex>" digest verified; empty for a git object
}

VerifiedIdentity is the proven outcome of a successful verification — everything a consumer needs to record what was verified and against what.

func Verify(ctx context.Context, obj Object, id Identity, tr *TrustedRoot, requireTransparency bool) (*VerifiedIdentity, error)

func VerifyImage(ctx context.Context, digest string, carrier ImageCarrier, id Identity, tr *TrustedRoot) (*VerifiedIdentity, error)

type VerifiedKey ¶

type VerifiedKey struct {
	Kind        SignatureKind
	Fingerprint string
}

VerifiedKey is the proven outcome of a pinned-key verification: the kind and fingerprint of the pinned key that verified the signature, in place of a Fulcio identity. It carries no signed time, no transparency proof binding one to the signature.

func VerifyPinned(obj Object, keys []PinnedKey) (*VerifiedKey, error)