package verify

import "github.com/sigstore/sigstore-go/pkg/verify"

Index

Constants 

const (
	VerificationResultMediaType01 = "application/vnd.dev.sigstore.verificationresult+json;version=0.1"
)

Variables 

var ErrDSSEInvalidSignatureCount = errors.New("exactly one signature is required")

Functions

func VerifyArtifactTransparencyLog 

func VerifyArtifactTransparencyLog(entity SignedEntity, trustedMaterial root.TrustedMaterial, logThreshold int, trustIntegratedTime bool) ([]root.Timestamp, error)

Deprecated: use VerifyTlogEntry instead

func VerifyLeafCertificate 

func VerifyLeafCertificate(observerTimestamp time.Time, leafCert *x509.Certificate, trustedMaterial root.TrustedMaterial) ([][]*x509.Certificate, error)

func VerifySignature 

func VerifySignature(sigContent SignatureContent, verificationContent VerificationContent, trustedMaterial root.TrustedMaterial) error

func VerifySignatureWithArtifactDigests 

func VerifySignatureWithArtifactDigests(sigContent SignatureContent, verificationContent VerificationContent, trustedMaterial root.TrustedMaterial, digests []ArtifactDigest) error

func VerifySignatureWithArtifacts 

func VerifySignatureWithArtifacts(sigContent SignatureContent, verificationContent VerificationContent, trustedMaterial root.TrustedMaterial, artifacts []io.Reader) error

func VerifySignedCertificateTimestamp 

func VerifySignedCertificateTimestamp(chains [][]*x509.Certificate, threshold int, trustedMaterial root.TrustedMaterial) error

VerifySignedCertificateTimestamp, given a threshold, TrustedMaterial, and a leaf certificate, will extract SCTs from the leaf certificate and verify the timestamps using the TrustedMaterial's FulcioCertificateAuthorities() and CTLogs()

func VerifySignedTimestamp 

func VerifySignedTimestamp(entity SignedEntity, trustedMaterial root.TrustedMaterial) ([]*root.Timestamp, []error, error)

VerifySignedTimestamp verifies that the given entity has been timestamped by a trusted timestamp authority and that the timestamp is valid.

func VerifySignedTimestampWithThreshold 

func VerifySignedTimestampWithThreshold(entity SignedEntity, trustedMaterial root.TrustedMaterial, threshold int) ([]*root.Timestamp, error)

VerifySignedTimestamp verifies that the given entity has been timestamped by a trusted timestamp authority and that the timestamp is valid.

The threshold parameter is the number of unique timestamps that must be verified.

func VerifyTimestampAuthority 

func VerifyTimestampAuthority(entity SignedEntity, trustedMaterial root.TrustedMaterial) ([]*root.Timestamp, []error, error)

Deprecated: use VerifySignedTimestamp instead.

func VerifyTimestampAuthorityWithThreshold 

func VerifyTimestampAuthorityWithThreshold(entity SignedEntity, trustedMaterial root.TrustedMaterial, threshold int) ([]*root.Timestamp, error)

Deprecated: use VerifySignedTimestampWithThreshold instead.

func VerifyTlogEntry 

func VerifyTlogEntry(entity SignedEntity, trustedMaterial root.TrustedMaterial, logThreshold int, trustIntegratedTime bool) ([]root.Timestamp, error)

VerifyTlogEntry verifies that the given entity has been logged in the transparency log and that the log entry is valid.

The threshold parameter is the number of unique transparency log entries that must be verified.

Types

type ArtifactDigest 

type ArtifactDigest struct {
	Algorithm string
	Digest    []byte
}

type ArtifactPolicyOption 

type ArtifactPolicyOption func(*PolicyConfig) error

func WithArtifact 

func WithArtifact(artifact io.Reader) ArtifactPolicyOption

WithArtifact allows the caller of Verify to enforce that the SignedEntity being verified was created from, or references, a given artifact.

If the SignedEntity contains a DSSE envelope, then the artifact digest is calculated from the given artifact, and compared to the digest in the envelope's statement.

func WithArtifactDigest 

func WithArtifactDigest(algorithm string, artifactDigest []byte) ArtifactPolicyOption

WithArtifactDigest allows the caller of Verify to enforce that the SignedEntity being verified was created for a given artifact digest.

If the SignedEntity contains a MessageSignature that was signed using the ED25519 algorithm, then providing only an artifactDigest will fail; the whole artifact must be provided. Use WithArtifact instead.

If the SignedEntity contains a DSSE envelope, then the artifact digest is compared to the digest in the envelope's statement.

func WithArtifactDigests 

func WithArtifactDigests(digests []ArtifactDigest) ArtifactPolicyOption

WithArtifactDigests allows the caller of Verify to enforce that the SignedEntity being verified was created for a given array of artifact digests.

If the SignedEntity contains a DSSE envelope, then the artifact digests are compared to the digests in the envelope's statement.

If the SignedEntity does not contain a DSSE envelope, verification fails.

func WithArtifacts 

func WithArtifacts(artifacts []io.Reader) ArtifactPolicyOption

WithArtifacts allows the caller of Verify to enforce that the SignedEntity being verified was created from, or references, a slice of artifacts.

If the SignedEntity contains a DSSE envelope, then the artifact digest is calculated from the given artifact, and compared to the digest in the envelope's statement.

func WithoutArtifactUnsafe 

func WithoutArtifactUnsafe() ArtifactPolicyOption

WithoutArtifactUnsafe allows the caller of Verify to skip checking whether the SignedEntity was created from, or references, an artifact.

WithoutArtifactUnsafe can only be used with SignedEntities that contain a DSSE envelope. If the the SignedEntity has a MessageSignature, providing this policy option will cause verification to always fail, since MessageSignatures can only be verified in the presence of an Artifact or artifact digest. See WithArtifact/WithArtifactDigest for more informaiton.

Do not use this function unless you know what you are doing!

As the name implies, using WithoutArtifactUnsafe is not safe: outside of exceptional circumstances, SignedEntities should always be verified with an artifact.

type BaseSignedEntity 

type BaseSignedEntity struct{}

BaseSignedEntity is a helper struct that implements all the interfaces of SignedEntity. It can be embedded in a struct to implement the SignedEntity interface. This may be useful for testing, or for implementing a SignedEntity that only implements a subset of the interfaces.

func (*BaseSignedEntity) HasInclusionPromise 

func (b *BaseSignedEntity) HasInclusionPromise() bool

func (*BaseSignedEntity) HasInclusionProof 

func (b *BaseSignedEntity) HasInclusionProof() bool

func (*BaseSignedEntity) SignatureContent 

func (b *BaseSignedEntity) SignatureContent() (SignatureContent, error)

func (*BaseSignedEntity) Timestamps 

func (b *BaseSignedEntity) Timestamps() ([][]byte, error)

func (*BaseSignedEntity) TlogEntries 

func (b *BaseSignedEntity) TlogEntries() ([]*tlog.Entry, error)

func (*BaseSignedEntity) VerificationContent 

func (b *BaseSignedEntity) VerificationContent() (VerificationContent, error)

func (*BaseSignedEntity) Version 

func (b *BaseSignedEntity) Version() (string, error)

type CertificateIdentities 

type CertificateIdentities []CertificateIdentity

func (CertificateIdentities) Verify 

func (i CertificateIdentities) Verify(cert certificate.Summary) (*CertificateIdentity, error)

Verify verifies the CertificateIdentities, and if ANY of them match the cert, it returns the CertificateIdentity that matched. If none match, it returns an error.

type CertificateIdentity 

type CertificateIdentity struct {
	SubjectAlternativeName SubjectAlternativeNameMatcher `json:"subjectAlternativeName"`
	Issuer                 IssuerMatcher                 `json:"issuer"`
	certificate.Extensions
}

func NewCertificateIdentity 

func NewCertificateIdentity(sanMatcher SubjectAlternativeNameMatcher, issuerMatcher IssuerMatcher, extensions certificate.Extensions) (CertificateIdentity, error)

func NewShortCertificateIdentity 

func NewShortCertificateIdentity(issuer, issuerRegex, sanValue, sanRegex string) (CertificateIdentity, error)

NewShortCertificateIdentity provides a more convenient way of initializing a CertificiateIdentity with a SAN and the Issuer OID extension. If you need to check more OID extensions, use NewCertificateIdentity instead.

func (CertificateIdentity) Verify 

func (c CertificateIdentity) Verify(actualCert certificate.Summary) error

Verify checks if the actualCert matches the CertificateIdentity's SAN and any of the provided OID extension values. Any empty values are ignored.

type EnvelopeContent 

type EnvelopeContent interface {
	RawEnvelope() *dsse.Envelope
	Statement() (*in_toto.Statement, error)
}

type ErrNoMatchingCertificateIdentity 

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

func (*ErrNoMatchingCertificateIdentity) Error 

func (e *ErrNoMatchingCertificateIdentity) Error() string

func (*ErrNoMatchingCertificateIdentity) Unwrap 

func (e *ErrNoMatchingCertificateIdentity) Unwrap() []error

type ErrValueMismatch 

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

func (*ErrValueMismatch) Error 

func (e *ErrValueMismatch) Error() string

type ErrValueRegexMismatch 

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

func (*ErrValueRegexMismatch) Error 

func (e *ErrValueRegexMismatch) Error() string

type ErrVerification 

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

func NewVerificationError 

func NewVerificationError(e error) ErrVerification

func (ErrVerification) Error 

func (e ErrVerification) Error() string

func (ErrVerification) String 

func (e ErrVerification) String() string

func (ErrVerification) Unwrap 

func (e ErrVerification) Unwrap() error

type HasInclusionPromise 

type HasInclusionPromise interface {
	HasInclusionPromise() bool
}

type HasInclusionProof 

type HasInclusionProof interface {
	HasInclusionProof() bool
}

type IssuerMatcher 

type IssuerMatcher struct {
	Issuer string        `json:"issuer"`
	Regexp regexp.Regexp `json:"regexp,omitempty"`
}

func NewIssuerMatcher 

func NewIssuerMatcher(issuerValue, regexpStr string) (IssuerMatcher, error)

func (*IssuerMatcher) MarshalJSON 

func (i *IssuerMatcher) MarshalJSON() ([]byte, error)

func (IssuerMatcher) Verify 

func (i IssuerMatcher) Verify(actualCert certificate.Summary) error

type MessageSignatureContent 

type MessageSignatureContent interface {
	Digest() []byte
	DigestAlgorithm() string
	Signature() []byte
}

type PolicyBuilder 

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

PolicyBuilder is responsible for building & validating a PolicyConfig

func NewPolicy 

func NewPolicy(artifactOpt ArtifactPolicyOption, options ...PolicyOption) PolicyBuilder

func (PolicyBuilder) BuildConfig 

func (pc PolicyBuilder) BuildConfig() (*PolicyConfig, error)

type PolicyConfig 

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

func (*PolicyConfig) RequireArtifact 

func (p *PolicyConfig) RequireArtifact() bool

RequireArtifact returns true if the Verify algorithm should perform signature verification with an an artifact provided by either the WithArtifact or the WithArtifactDigest functions.

By default, unless explicitly turned off, we should always expect to verify a SignedEntity's signature using an artifact. Bools are initialized to false, so this behaviour is therefore controlled by the ignoreArtifact field.

Double negatives are confusing, though. To aid with comprehension of the main Verify loop, this function therefore just wraps the double negative.

func (*PolicyConfig) RequireIdentities 

func (p *PolicyConfig) RequireIdentities() bool

RequireIdentities returns true if the Verify algorithm should check whether the SignedEntity's certificate was created by one of the identities provided by the WithCertificateIdentity function.

By default, unless explicitly turned off, we should always expect to enforce that a SignedEntity's certificate was created by an Identity we trust. Bools are initialized to false, so this behaviour is therefore controlled by the ignoreIdentities field.

Double negatives are confusing, though. To aid with comprehension of the main Verify loop, this function therefore just wraps the double negative.

func (*PolicyConfig) RequireSigningKey 

func (p *PolicyConfig) RequireSigningKey() bool

RequireSigningKey returns true if we expect the SignedEntity to be signed with a key and not a certificate.

type PolicyOption 

type PolicyOption func(*PolicyConfig) error

func WithCertificateIdentity 

func WithCertificateIdentity(identity CertificateIdentity) PolicyOption

WithCertificateIdentity allows the caller of Verify to enforce that the SignedEntity being verified was signed by the given identity, as defined by the Fulcio certificate embedded in the entity. If this policy is enabled, but the SignedEntity does not have a certificate, verification will fail.

Providing this function multiple times will concatenate the provided CertificateIdentity to the list of identities being checked.

If all of the provided CertificateIdentities fail to match the Fulcio certificate, then verification will fail. If *any* CertificateIdentity matches, then verification will succeed. Therefore, each CertificateIdentity provided to this function must define a "sufficient" identity to trust.

The CertificateIdentity struct allows callers to specify: - The exact value, or Regexp, of the SubjectAlternativeName - The exact value of any Fulcio OID X.509 extension, i.e. Issuer

For convenience, consult the NewShortCertificateIdentity function.

func WithKey 

func WithKey() PolicyOption

WithKey allows the caller of Verify to require the SignedEntity being verified was signed with a key and not a certificate.

func WithoutIdentitiesUnsafe 

func WithoutIdentitiesUnsafe() PolicyOption

WithoutIdentitiesUnsafe allows the caller of Verify to skip enforcing any checks on the identity that created the SignedEntity being verified.

Do not use this option unless you know what you are doing!

As the name implies, using WithoutIdentitiesUnsafe is not safe: outside of exceptional circumstances, we should always enforce that the SignedEntity being verified was signed by a trusted CertificateIdentity.

For more information, consult WithCertificateIdentity.

type PublicKeyProvider 

type PublicKeyProvider interface {
	Hint() string
}

type SignatureContent 

type SignatureContent interface {
	Signature() []byte
	EnvelopeContent() EnvelopeContent
	MessageSignatureContent() MessageSignatureContent
}

type SignatureProvider 

type SignatureProvider interface {
	SignatureContent() (SignatureContent, error)
}

type SignatureVerificationResult 

type SignatureVerificationResult struct {
	PublicKeyID *[]byte              `json:"publicKeyId,omitempty"`
	Certificate *certificate.Summary `json:"certificate,omitempty"`
}

type SignedEntity 

type SignedEntity interface {
	HasInclusionPromise
	HasInclusionProof
	SignatureProvider
	SignedTimestampProvider
	TlogEntryProvider
	VerificationProvider
	VersionProvider
}

type SignedEntityVerifier 

type SignedEntityVerifier = Verifier

Deprecated: Use Verifier instead

type SignedTimestampProvider 

type SignedTimestampProvider interface {
	Timestamps() ([][]byte, error)
}

type SubjectAlternativeNameMatcher 

type SubjectAlternativeNameMatcher struct {
	SubjectAlternativeName string        `json:"subjectAlternativeName"`
	Regexp                 regexp.Regexp `json:"regexp,omitempty"`
}

func NewSANMatcher 

func NewSANMatcher(sanValue string, regexpStr string) (SubjectAlternativeNameMatcher, error)

NewSANMatcher provides an easier way to create a SubjectAlternativeNameMatcher. If the regexpStr fails to compile into a Regexp, an error is returned.

func (*SubjectAlternativeNameMatcher) MarshalJSON 

func (s *SubjectAlternativeNameMatcher) MarshalJSON() ([]byte, error)

The default Regexp json marshal is quite ugly, so we override it here.

func (SubjectAlternativeNameMatcher) Verify 

func (s SubjectAlternativeNameMatcher) Verify(actualCert certificate.Summary) error

Verify checks if the actualCert matches the SANMatcher's Value and Regexp – if those values have been provided.

type TimestampVerificationResult 

type TimestampVerificationResult struct {
	Type      string    `json:"type"`
	URI       string    `json:"uri"`
	Timestamp time.Time `json:"timestamp"`
}

type TlogEntryProvider 

type TlogEntryProvider interface {
	TlogEntries() ([]*tlog.Entry, error)
}

type VerificationContent 

type VerificationContent interface {
	CompareKey(any, root.TrustedMaterial) bool
	ValidAtTime(time.Time, root.TrustedMaterial) bool
	Certificate() *x509.Certificate
	PublicKey() PublicKeyProvider
}

type VerificationProvider 

type VerificationProvider interface {
	VerificationContent() (VerificationContent, error)
}

type VerificationResult 

type VerificationResult struct {
	MediaType          string                        `json:"mediaType"`
	Statement          *in_toto.Statement            `json:"statement,omitempty"`
	Signature          *SignatureVerificationResult  `json:"signature,omitempty"`
	VerifiedTimestamps []TimestampVerificationResult `json:"verifiedTimestamps"`
	VerifiedIdentity   *CertificateIdentity          `json:"verifiedIdentity,omitempty"`
}

func NewVerificationResult 

func NewVerificationResult() *VerificationResult

func (*VerificationResult) MarshalJSON 

func (b *VerificationResult) MarshalJSON() ([]byte, error)

MarshalJSON deals with protojson needed for the Statement. Can be removed when https://github.com/in-toto/attestation/pull/403 is merged.

func (*VerificationResult) UnmarshalJSON 

func (b *VerificationResult) UnmarshalJSON(data []byte) error

type Verifier 

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

func NewSignedEntityVerifier 

func NewSignedEntityVerifier(trustedMaterial root.TrustedMaterial, options ...VerifierOption) (*Verifier, error)

Deprecated: Use NewVerifier instead

func NewVerifier 

func NewVerifier(trustedMaterial root.TrustedMaterial, options ...VerifierOption) (*Verifier, error)

NewVerifier creates a new Verifier. It takes a root.TrustedMaterial, which contains a set of trusted public keys and certificates, and a set of VerifierConfigurators, which set the config that determines the behaviour of the Verify function.

VerifierConfig's set of options should match the properties of a given Sigstore deployment, i.e. whether to expect SCTs, Tlog entries, or signed timestamps.

func (*Verifier) Verify 

func (v *Verifier) Verify(entity SignedEntity, pb PolicyBuilder) (*VerificationResult, error)

Verify checks the cryptographic integrity of a given SignedEntity according to the options configured in the NewVerifier. Its purpose is to determine whether the SignedEntity was created by a Sigstore deployment we trust, as defined by keys in our TrustedMaterial.

If the SignedEntity contains a MessageSignature, then the artifact or its digest must be provided to the Verify function, as it is required to verify the signature. See WithArtifact and WithArtifactDigest for more details.

If and only if verification is successful, Verify will return a VerificationResult struct whose contents' integrity have been verified. Verify may then verify the contents of the VerificationResults using supplied PolicyOptions. See WithCertificateIdentity for more details.

Callers of this function SHOULD ALWAYS:

func (*Verifier) VerifyObserverTimestamps 

func (v *Verifier) VerifyObserverTimestamps(entity SignedEntity, logTimestamps []TimestampVerificationResult) ([]TimestampVerificationResult, error)

VerifyObserverTimestamps verifies RFC3161 signed timestamps, and verifies that timestamp thresholds are met with log entry integrated timestamps, signed timestamps, or a combination of both. The returned timestamps can be used to verify short-lived certificates. logTimestamps may be populated with verified log entry integrated timestamps In order to be verifiable, a SignedEntity must have at least one verified "observer timestamp".

func (*Verifier) VerifyTransparencyLogInclusion 

func (v *Verifier) VerifyTransparencyLogInclusion(entity SignedEntity) ([]TimestampVerificationResult, error)

VerifyTransparencyLogInclusion verifies TlogEntries if expected. Optionally returns a list of verified timestamps from the log integrated timestamps when verifying with observer timestamps. TODO: Return a different verification result for logs specifically (also for #48)

type VerifierConfig 

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

func (*VerifierConfig) Validate 

func (c *VerifierConfig) Validate() error

type VerifierOption 

type VerifierOption func(*VerifierConfig) error

func WithCurrentTime 

func WithCurrentTime() VerifierOption

WithCurrentTime configures the Verifier to not expect any timestamps from either a Timestamp Authority or a Transparency Log. This option should not be enabled when verifying short-lived certificates, as an observer timestamp is needed. This option is useful primarily for private deployments with long-lived code signing certificates.

func WithIntegratedTimestamps 

func WithIntegratedTimestamps(threshold int) VerifierOption

WithIntegratedTimestamps configures the Verifier to expect log entry integrated timestamps from either SignedEntryTimestamps or live log lookups.

func WithObserverTimestamps 

func WithObserverTimestamps(threshold int) VerifierOption

WithObserverTimestamps configures the Verifier to expect timestamps from either an RFC3161 timestamp authority or a log's SignedEntryTimestamp. These are verified using the TrustedMaterial's TimestampingAuthorities() or RekorLogs(), and used to verify the Fulcio certificate.

func WithSignedCertificateTimestamps 

func WithSignedCertificateTimestamps(threshold int) VerifierOption

WithSignedCertificateTimestamps configures the Verifier to expect the Fulcio certificate to have a SignedCertificateTimestamp, and verify it using the TrustedMaterial's CTLogAuthorities().

func WithSignedTimestamps 

func WithSignedTimestamps(threshold int) VerifierOption

WithSignedTimestamps configures the Verifier to expect RFC 3161 timestamps from a Timestamp Authority, verify them using the TrustedMaterial's TimestampingAuthorities(), and, if it exists, use the resulting timestamp(s) to verify the Fulcio certificate.

func WithTransparencyLog 

func WithTransparencyLog(threshold int) VerifierOption

WithTransparencyLog configures the Verifier to expect Transparency Log inclusion proofs or SignedEntryTimestamps, verifying them using the TrustedMaterial's RekorLogs().

type VersionProvider 

type VersionProvider interface {
	Version() (string, error)
}

Source Files

certificate.go certificate_identity.go errors.go interface.go sct.go signature.go signed_entity.go tlog.go tsa.go

Version
v1.1.1 (latest)
Published
Aug 5, 2025
Platform
linux/amd64
Imports
34 packages
Last checked
8 months ago –

Tools for package owners.