Documentation
¶
Overview ¶
Package verification provides the utilities for handling verification related logic like Trust Stores and Trust Policies. Few utilities include loading, parsing, and validating trust policies and trust stores.
Index ¶
- Constants
- Variables
- func IsValidTrustStorePrefix(s string) bool
- func WithPluginConfig(ctx context.Context, config map[string]string) context.Context
- type ErrorNoApplicableTrustPolicy
- type ErrorSignatureRetrievalFailed
- type ErrorVerificationFailed
- type ErrorVerificationInconclusive
- type PolicyDocument
- type SignatureVerification
- type SignatureVerificationOutcome
- type TrustPolicy
- type TrustStorePrefix
- type VerificationAction
- type VerificationLevel
- type VerificationResult
- type VerificationType
- type Verifier
- type X509TrustStore
Constants ¶
const ( Integrity VerificationType = "integrity" Authenticity VerificationType = "authenticity" AuthenticTimestamp VerificationType = "authenticTimestamp" Expiry VerificationType = "expiry" Revocation VerificationType = "revocation" Enforced VerificationAction = "enforce" Logged VerificationAction = "log" Skipped VerificationAction = "skip" TrustStorePrefixCA TrustStorePrefix = "ca" TrustStorePrefixSigningAuthority TrustStorePrefix = "signingAuthority" )
const ( // VerificationPlugin specifies the name of the verification plugin that should be used to verify the signature. VerificationPlugin = "io.cncf.notary.verificationPlugin" // VerificationPluginMinVersion specifies the minimum version of the verification plugin that should be used to verify the signature. VerificationPluginMinVersion = "io.cncf.notary.verificationPluginMinVersion" )
Variables ¶
var ( Strict = &VerificationLevel{ "strict", map[VerificationType]VerificationAction{ Integrity: Enforced, Authenticity: Enforced, AuthenticTimestamp: Enforced, Expiry: Enforced, Revocation: Enforced, }, } Permissive = &VerificationLevel{ "permissive", map[VerificationType]VerificationAction{ Integrity: Enforced, Authenticity: Enforced, AuthenticTimestamp: Logged, Expiry: Logged, Revocation: Logged, }, } Audit = &VerificationLevel{ "audit", map[VerificationType]VerificationAction{ Integrity: Enforced, Authenticity: Logged, AuthenticTimestamp: Logged, Expiry: Logged, Revocation: Logged, }, } Skip = &VerificationLevel{ "skip", map[VerificationType]VerificationAction{ Integrity: Skipped, Authenticity: Skipped, AuthenticTimestamp: Skipped, Expiry: Skipped, Revocation: Skipped, }, } VerificationTypes = []VerificationType{ Integrity, Authenticity, AuthenticTimestamp, Expiry, Revocation, } VerificationActions = []VerificationAction{ Enforced, Logged, Skipped, } VerificationLevels = []*VerificationLevel{ Strict, Permissive, Audit, Skip, } TrustStorePrefixes = []TrustStorePrefix{ TrustStorePrefixCA, TrustStorePrefixSigningAuthority, } )
Functions ¶
func IsValidTrustStorePrefix ¶
IsValidTrustStorePrefix returns true if the given string is a valid TrustStorePrefix, otherwise false.
Types ¶
type ErrorNoApplicableTrustPolicy ¶
type ErrorNoApplicableTrustPolicy struct {
// contains filtered or unexported fields
}
ErrorNoApplicableTrustPolicy is used when there is no trust policy that applies to the given artifact
func (ErrorNoApplicableTrustPolicy) Error ¶
func (e ErrorNoApplicableTrustPolicy) Error() string
type ErrorSignatureRetrievalFailed ¶
type ErrorSignatureRetrievalFailed struct {
// contains filtered or unexported fields
}
ErrorSignatureRetrievalFailed is used when notation is unable to retrieve the digital signature/s for the given artifact
func (ErrorSignatureRetrievalFailed) Error ¶
func (e ErrorSignatureRetrievalFailed) Error() string
type ErrorVerificationFailed ¶
type ErrorVerificationFailed struct {
// contains filtered or unexported fields
}
ErrorVerificationFailed is used when it is determined that the digital signature/s is not valid for the given artifact
func (ErrorVerificationFailed) Error ¶
func (e ErrorVerificationFailed) Error() string
type ErrorVerificationInconclusive ¶
type ErrorVerificationInconclusive struct {
// contains filtered or unexported fields
}
ErrorVerificationInconclusive is used when signature verification fails due to a runtime error (e.g. a network error)
func (ErrorVerificationInconclusive) Error ¶
func (e ErrorVerificationInconclusive) Error() string
type PolicyDocument ¶
type PolicyDocument struct {
// Version of the policy document
Version string `json:"version"`
// TrustPolicies include each policy statement
TrustPolicies []TrustPolicy `json:"trustPolicies"`
}
PolicyDocument represents a trustPolicy.json document
func (*PolicyDocument) ValidatePolicyDocument ¶
func (policyDoc *PolicyDocument) ValidatePolicyDocument() error
ValidatePolicyDocument validates a policy document according to it's version's rule set. if any rule is violated, returns an error
type SignatureVerification ¶
type SignatureVerification struct {
Level string `json:"level"`
Override map[string]string `json:"override,omitempty"`
}
SignatureVerification represents verification configuration in a trust policy
type SignatureVerificationOutcome ¶
type SignatureVerificationOutcome struct {
// EnvelopeContent contains the details of the digital signature and associated metadata
EnvelopeContent *signature.EnvelopeContent
// VerificationLevel describes what verification level was used for performing signature verification
VerificationLevel *VerificationLevel
// VerificationResults contains the verifications performed on the signature and their results
VerificationResults []*VerificationResult
// SignedAnnotations contains arbitrary metadata relating to the target artifact that was signed
SignedAnnotations map[string]string
// Error that caused the verification to fail (if it fails)
Error error
}
SignatureVerificationOutcome encapsulates the SignerInfo (that includes the details of the digital signature) and results for each verification type that was performed
type TrustPolicy ¶
type TrustPolicy struct {
// Name of the policy statement
Name string `json:"name"`
// RegistryScopes that this policy statement affects
RegistryScopes []string `json:"registryScopes"`
// SignatureVerification setting for this policy statement
SignatureVerification SignatureVerification `json:"signatureVerification"`
// TrustStores this policy statement uses
TrustStores []string `json:"trustStores,omitempty"`
// TrustedIdentities this policy statement pins
TrustedIdentities []string `json:"trustedIdentities,omitempty"`
}
TrustPolicy represents a policy statement in the policy document
type TrustStorePrefix ¶
type TrustStorePrefix string
TrustStorePrefix is an enum for trust store prefixes supported such as "ca", "signingAuthority"
type VerificationAction ¶
type VerificationAction string
VerificationAction is an enum for signature verification actions such as Enforced, Logged, Skipped.
type VerificationLevel ¶
type VerificationLevel struct {
Name string
VerificationMap map[VerificationType]VerificationAction
}
VerificationLevel encapsulates the signature verification preset and it's actions for each verification type
func GetVerificationLevel ¶
func GetVerificationLevel(signatureVerification SignatureVerification) (*VerificationLevel, error)
GetVerificationLevel returns VerificationLevel struct for the given SignatureVerification struct throws error if SignatureVerification is invalid
type VerificationResult ¶
type VerificationResult struct {
// Success is set to true if the verification was successful
Success bool
// Type of verification that is performed
Type VerificationType
// Action is the intended action for the given verification type as defined in the trust policy
Action VerificationAction
// Err is set if there are any errors during the verification process
Error error
}
VerificationResult encapsulates the verification result (passed or failed) for a verification type, including the desired verification action as specified in the trust policy
type VerificationType ¶
type VerificationType string
VerificationType is an enum for signature verification types such as Integrity, Authenticity, etc.
type Verifier ¶
type Verifier struct {
PolicyDocument *PolicyDocument
Repository registry.Repository
PathManager *dir.PathManager
PluginManager pluginManager
}
func NewVerifier ¶
func NewVerifier(repository registry.Repository) (*Verifier, error)
func (*Verifier) Verify ¶
func (v *Verifier) Verify(ctx context.Context, artifactUri string) ([]*SignatureVerificationOutcome, error)
Verify performs signature verification on each of the notation supported verification types (like integrity, authenticity, etc.) and return the verification outcomes.
Given an artifact URI, Verify will retrieve all the signatures associated with the URI and perform signature verification. A signature is considered not valid if verification fails due to any one of the following reasons
1. Artifact URI is not associated with a signature i.e. unsigned 2. Registry is unavailable to retrieve the signature 3. Signature does not satisfy the verification rules configured in the trust policy 4. Signature specifies a plugin for extended verification and that throws an error 5. Digest in the signature does not match the digest present in the URI
If each and every signature associated with the URI fail the verification, then Verify will return `ErrorVerificationFailed` error along with an array of `SignatureVerificationOutcome`.
Callers can pass the verification plugin config in context.Context using "verification.WithPluginConfig()"
For more details on signature verification, see https://github.com/notaryproject/notaryproject/blob/main/trust-store-trust-policy-specification.md#signature-verification
type X509TrustStore ¶
type X509TrustStore struct {
Name string
Prefix string
Path string
Certificates []*x509.Certificate
}
X509TrustStore provide the members and behavior for a named trust store
func LoadX509TrustStore ¶
func LoadX509TrustStore(path string) (*X509TrustStore, error)
LoadX509TrustStore loads a named trust store from a certificates directory, throws error if parsing a certificate from a file fails