verify

package
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 10, 2024 License: Apache-2.0 Imports: 32 Imported by: 10

Documentation

Index

Constants

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

Variables

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

Functions

func VerifyArtifactTransparencyLog 

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

VerifyArtifactTransparencyLog 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.

If online is true, the log entry is verified against the Rekor server.

func VerifyLeafCertificate 

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

func VerifySignature 

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

func VerifySignatureWithArtifact 

func VerifySignatureWithArtifact(sigContent SignatureContent, verificationContent VerificationContent, trustedMaterial root.TrustedMaterial, artifact io.Reader) error

func VerifySignatureWithArtifactDigest 

func VerifySignatureWithArtifactDigest(sigContent SignatureContent, verificationContent VerificationContent, trustedMaterial root.TrustedMaterial, artifactDigest []byte, artifactDigestAlgorithm string) error

func VerifySignedCertificateTimestamp 

func VerifySignedCertificateTimestamp(leafCert *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 VerifyTimestampAuthority 

func VerifyTimestampAuthority(entity SignedEntity, trustedMaterial root.TrustedMaterial) ([]time.Time, error)

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

func VerifyTimestampAuthorityWithThreshold 

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

VerifyTimestampAuthority 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.

Types

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 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) Envelope 

func (b *BaseSignedEntity) Envelope() (*dsse.Envelope, error)

func (*BaseSignedEntity) MessageSignature 

func (b *BaseSignedEntity) MessageSignature() (*protocommon.MessageSignature, error)

func (*BaseSignedEntity) Signature 

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

func (*BaseSignedEntity) Timestamps 

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

func (*BaseSignedEntity) TlogEntries 

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

func (*BaseSignedEntity) VerificationProvider 

func (b *BaseSignedEntity) VerificationProvider() (VerificationContent, 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 added in v0.5.0 

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

func (*ErrNoMatchingCertificateIdentity) Error added in v0.5.0 

func (e *ErrNoMatchingCertificateIdentity) Error() string

func (*ErrNoMatchingCertificateIdentity) Unwrap added in v0.5.0 

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

type ErrValueMismatch added in v0.5.0 

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

func (*ErrValueMismatch) Error added in v0.5.0 

func (e *ErrValueMismatch) Error() string

type ErrValueRegexMismatch added in v0.5.0 

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

func (*ErrValueRegexMismatch) Error added in v0.5.0 

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 added in v0.5.0 

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

func NewIssuerMatcher added in v0.5.1 

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

func (*IssuerMatcher) MarshalJSON added in v0.5.0 

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

func (IssuerMatcher) Verify added in v0.5.0 

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)

func (PolicyBuilder) Options 

func (pc PolicyBuilder) Options() []PolicyOption

type PolicyConfig 

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

func (*PolicyConfig) Validate 

func (p *PolicyConfig) Validate() error

func (*PolicyConfig) WeExpectAnArtifact 

func (p *PolicyConfig) WeExpectAnArtifact() bool

WeExpectAnArtifact 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 weDoNotExpectAnArtifact 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) WeExpectIdentities 

func (p *PolicyConfig) WeExpectIdentities() bool

WeExpectIdentities 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 weDoNotExpectIdentities 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) WeExpectSigningKey added in v0.5.0 

func (p *PolicyConfig) WeExpectSigningKey() bool

WeExpectSigningKey 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 added in v0.5.0 

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
}

type SignedEntityVerifier 

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

func NewSignedEntityVerifier 

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

NewSignedEntityVerifier creates a new SignedEntityVerifier. 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 (*SignedEntityVerifier) Verify 

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

Verify checks the cryptographic integrity of a given SignedEntity according to the options configured in the NewSignedEntityVerifier. 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:

  • (if the signed entity has a certificate) verify that its Subject Alternate Name matches a trusted identity, and that its OID Issuer field matches an expected value
  • (if the signed entity has a dsse envelope) verify that the envelope's statement's subject matches the artifact being verified

func (*SignedEntityVerifier) VerifyObserverTimestamps 

func (v *SignedEntityVerifier) 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 (*SignedEntityVerifier) VerifyTransparencyLogInclusion 

func (v *SignedEntityVerifier) 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 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
	GetCertificate() *x509.Certificate
	HasPublicKey() (PublicKeyProvider, bool)
}

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

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 WithIntegratedTimestamps 

func WithIntegratedTimestamps(threshold int) VerifierOption

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

func WithObserverTimestamps 

func WithObserverTimestamps(threshold int) VerifierOption

WithObserverTimestamps configures the SignedEntityVerifier 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 WithOnlineVerification 

func WithOnlineVerification() VerifierOption

WithOnlineVerification configures the SignedEntityVerifier to perform online verification when verifying Transparency Log entries and Signed Certificate Timestamps.

func WithSignedCertificateTimestamps 

func WithSignedCertificateTimestamps(threshold int) VerifierOption

WithSignedCertificateTimestamps configures the SignedEntityVerifier 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 SignedEntityVerifier 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 SignedEntityVerifier to expect Transparency Log inclusion proofs or SignedEntryTimestamps, verifying them using the TrustedMaterial's RekorLogs().

func WithoutAnyObserverTimestampsUnsafe added in v0.5.0 

func WithoutAnyObserverTimestampsUnsafe() VerifierOption

WithoutAnyObserverTimestampsUnsafe configures the SignedEntityVerifier to not expect any timestamps from either a Timestamp Authority or a Transparency Log.

A SignedEntity without a trusted "observer" timestamp to verify the attached Fulcio certificate can't provide the same kind of integrity guarantee.

Do not enable this if you don't know what you are doing; as the name implies, using it defeats part of the security guarantees offered by Sigstore. This option is only useful for testing.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.