signature

package
v5.32.0 Latest Latest
Warning

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

 Go to latest Published: Jul 25, 2024 License: Apache-2.0 Imports: 34 Imported by: 104

Documentation

Index

Constants

View Source 
const (
	// SBKeyTypeGPGKeys refers to keys contained in a GPG keyring
	SBKeyTypeGPGKeys sbKeyType = "GPGKeys"
	// SBKeyTypeSignedByGPGKeys refers to keys signed by keys in a GPG keyring
	SBKeyTypeSignedByGPGKeys sbKeyType = "signedByGPGKeys"
	// SBKeyTypeX509Certificates refers to keys in a set of X.509 certificates
	// FIXME: PEM, DER?
	SBKeyTypeX509Certificates sbKeyType = "X509Certificates"
	// SBKeyTypeSignedByX509CAs refers to keys signed by one of the X.509 CAs
	// FIXME: PEM, DER?
	SBKeyTypeSignedByX509CAs sbKeyType = "signedByX509CAs"
)

Variables

This section is empty.

Functions

func SignDockerManifest 

func SignDockerManifest(m []byte, dockerReference string, mech SigningMechanism, keyIdentity string) ([]byte, error)

SignDockerManifest returns a signature for manifest as the specified dockerReference, using mech and keyIdentity.

func SignDockerManifestWithOptions added in v5.19.0 

func SignDockerManifestWithOptions(m []byte, dockerReference string, mech SigningMechanism, keyIdentity string, options *SignOptions) ([]byte, error)

SignDockerManifest returns a signature for manifest as the specified dockerReference, using mech and keyIdentity, and the specified options.

Types

type InvalidPolicyFormatError 

type InvalidPolicyFormatError string

InvalidPolicyFormatError is returned when parsing an invalid policy configuration.

func (InvalidPolicyFormatError) Error 

func (err InvalidPolicyFormatError) Error() string

type InvalidSignatureError 

type InvalidSignatureError = internal.InvalidSignatureError

InvalidSignatureError is returned when parsing an invalid signature.

type PRSigstoreSignedFulcio added in v5.24.0 

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

PRSigstoreSignedFulcio contains Fulcio configuration options for a "sigstoreSigned" PolicyRequirement. This is a public type with a single private implementation.

func NewPRSigstoreSignedFulcio added in v5.24.0 

func NewPRSigstoreSignedFulcio(options ...PRSigstoreSignedFulcioOption) (PRSigstoreSignedFulcio, error)

NewPRSigstoreSignedFulcio returns a PRSigstoreSignedFulcio based on options.

type PRSigstoreSignedFulcioOption added in v5.24.0 

type PRSigstoreSignedFulcioOption func(*prSigstoreSignedFulcio) error

PRSigstoreSignedFulcioOption is a way to pass values to NewPRSigstoreSignedFulcio

func PRSigstoreSignedFulcioWithCAData added in v5.24.0 

func PRSigstoreSignedFulcioWithCAData(caData []byte) PRSigstoreSignedFulcioOption

PRSigstoreSignedFulcioWithCAData specifies a value for the "caData" field when calling NewPRSigstoreSignedFulcio

func PRSigstoreSignedFulcioWithCAPath added in v5.24.0 

func PRSigstoreSignedFulcioWithCAPath(caPath string) PRSigstoreSignedFulcioOption

PRSigstoreSignedFulcioWithCAPath specifies a value for the "caPath" field when calling NewPRSigstoreSignedFulcio

func PRSigstoreSignedFulcioWithOIDCIssuer added in v5.24.0 

func PRSigstoreSignedFulcioWithOIDCIssuer(oidcIssuer string) PRSigstoreSignedFulcioOption

PRSigstoreSignedFulcioWithOIDCIssuer specifies a value for the "oidcIssuer" field when calling NewPRSigstoreSignedFulcio

func PRSigstoreSignedFulcioWithSubjectEmail added in v5.24.0 

func PRSigstoreSignedFulcioWithSubjectEmail(subjectEmail string) PRSigstoreSignedFulcioOption

PRSigstoreSignedFulcioWithSubjectEmail specifies a value for the "subjectEmail" field when calling NewPRSigstoreSignedFulcio

type PRSigstoreSignedOption added in v5.24.0 

type PRSigstoreSignedOption func(*prSigstoreSigned) error

PRSigstoreSignedOption is way to pass values to NewPRSigstoreSigned

func PRSigstoreSignedWithFulcio added in v5.24.0 

func PRSigstoreSignedWithFulcio(fulcio PRSigstoreSignedFulcio) PRSigstoreSignedOption

PRSigstoreSignedWithFulcio specifies a value for the "fulcio" field when calling NewPRSigstoreSigned.

func PRSigstoreSignedWithKeyData added in v5.24.0 

func PRSigstoreSignedWithKeyData(keyData []byte) PRSigstoreSignedOption

PRSigstoreSignedWithKeyData specifies a value for the "keyData" field when calling NewPRSigstoreSigned.

func PRSigstoreSignedWithKeyPath added in v5.24.0 

func PRSigstoreSignedWithKeyPath(keyPath string) PRSigstoreSignedOption

PRSigstoreSignedWithKeyPath specifies a value for the "keyPath" field when calling NewPRSigstoreSigned.

func PRSigstoreSignedWithRekorPublicKeyData added in v5.24.0 

func PRSigstoreSignedWithRekorPublicKeyData(rekorPublicKeyData []byte) PRSigstoreSignedOption

PRSigstoreSignedWithRekorPublicKeyData specifies a value for the "rekorPublicKeyData" field when calling NewPRSigstoreSigned.

func PRSigstoreSignedWithRekorPublicKeyPath added in v5.24.0 

func PRSigstoreSignedWithRekorPublicKeyPath(rekorPublicKeyPath string) PRSigstoreSignedOption

PRSigstoreSignedWithRekorPublicKeyPath specifies a value for the "rekorPublicKeyPath" field when calling NewPRSigstoreSigned.

func PRSigstoreSignedWithSignedIdentity added in v5.24.0 

func PRSigstoreSignedWithSignedIdentity(signedIdentity PolicyReferenceMatch) PRSigstoreSignedOption

PRSigstoreSignedWithSignedIdentity specifies a value for the "signedIdentity" field when calling NewPRSigstoreSigned.

type Policy 

type Policy struct {
	// Default applies to any image which does not have a matching policy in Transports.
	// Note that this can happen even if a matching PolicyTransportScopes exists in Transports
	// if the image matches none of the scopes.
	Default    PolicyRequirements               `json:"default"`
	Transports map[string]PolicyTransportScopes `json:"transports"`
}

Policy defines requirements for considering a signature, or an image, valid.

func DefaultPolicy 

func DefaultPolicy(sys *types.SystemContext) (*Policy, error)

DefaultPolicy returns the default policy of the system. Most applications should be using this method to get the policy configured by the system administrator. sys should usually be nil, can be set to override the default. NOTE: When this function returns an error, report it to the user and abort. DO NOT hard-code fallback policies in your application.

func NewPolicyFromBytes 

func NewPolicyFromBytes(data []byte) (*Policy, error)

NewPolicyFromBytes returns a policy parsed from the specified blob. Use this function instead of calling json.Unmarshal directly.

func NewPolicyFromFile 

func NewPolicyFromFile(fileName string) (*Policy, error)

NewPolicyFromFile returns a policy configured in the specified file.

func (*Policy) UnmarshalJSON 

func (p *Policy) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

type PolicyContext 

type PolicyContext struct {
	Policy *Policy
	// contains filtered or unexported fields
}

PolicyContext encapsulates a policy and possible cached state for speeding up its evaluation.

func NewPolicyContext 

func NewPolicyContext(policy *Policy) (*PolicyContext, error)

NewPolicyContext sets up and initializes a context for the specified policy. The policy must not be modified while the context exists. FIXME: make a deep copy? If this function succeeds, the caller should call PolicyContext.Destroy() when done.

func (*PolicyContext) Destroy 

func (pc *PolicyContext) Destroy() error

Destroy should be called when the user of the context is done with it.

func (*PolicyContext) GetSignaturesWithAcceptedAuthor 

func (pc *PolicyContext) GetSignaturesWithAcceptedAuthor(ctx context.Context, publicImage types.UnparsedImage) (sigs []*Signature, finalErr error)

GetSignaturesWithAcceptedAuthor returns those signatures from an image for which the policy accepts the author (and which have been successfully verified). NOTE: This may legitimately return an empty list and no error, if the image has no signatures or only invalid signatures. WARNING: This makes the signature contents acceptable for further processing, but it does not necessarily mean that the contents of the signature are consistent with local policy. For example:

  • Do not use a an existence of an accepted signature to determine whether to run a container based on this image; use IsRunningImageAllowed instead.
  • Just because a signature is accepted does not automatically mean the contents of the signature are authorized to run code as root, or to affect system or cluster configuration.

func (*PolicyContext) IsRunningImageAllowed 

func (pc *PolicyContext) IsRunningImageAllowed(ctx context.Context, publicImage types.UnparsedImage) (res bool, finalErr error)

IsRunningImageAllowed returns true iff the policy allows running the image. If it returns false, err must be non-nil, and should be an PolicyRequirementError if evaluation succeeded but the result was rejection. WARNING: This validates signatures and the manifest, but does not download or validate the layers. Users must validate that the layers match their expected digests.

type PolicyReferenceMatch 

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

PolicyReferenceMatch specifies a set of image identities accepted in PolicyRequirement. The type is public, but its implementation is private.

func NewPRMExactReference 

func NewPRMExactReference(dockerReference string) (PolicyReferenceMatch, error)

NewPRMExactReference returns a new "exactReference" PolicyReferenceMatch.

func NewPRMExactRepository 

func NewPRMExactRepository(dockerRepository string) (PolicyReferenceMatch, error)

NewPRMExactRepository returns a new "exactRepository" PolicyRepositoryMatch.

func NewPRMMatchExact 

func NewPRMMatchExact() PolicyReferenceMatch

NewPRMMatchExact returns a new "matchExact" PolicyReferenceMatch.

func NewPRMMatchRepoDigestOrExact 

func NewPRMMatchRepoDigestOrExact() PolicyReferenceMatch

NewPRMMatchRepoDigestOrExact returns a new "matchRepoDigestOrExact" PolicyReferenceMatch.

func NewPRMMatchRepository 

func NewPRMMatchRepository() PolicyReferenceMatch

NewPRMMatchRepository returns a new "matchRepository" PolicyReferenceMatch.

func NewPRMRemapIdentity added in v5.9.0 

func NewPRMRemapIdentity(prefix, signedPrefix string) (PolicyReferenceMatch, error)

NewPRMRemapIdentity returns a new "remapIdentity" PolicyRepositoryMatch.

type PolicyRequirement 

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

PolicyRequirement is a rule which must be satisfied by at least one of the signatures of an image. The type is public, but its definition is private.

func NewPRInsecureAcceptAnything 

func NewPRInsecureAcceptAnything() PolicyRequirement

NewPRInsecureAcceptAnything returns a new "insecureAcceptAnything" PolicyRequirement.

func NewPRReject 

func NewPRReject() PolicyRequirement

NewPRReject returns a new "reject" PolicyRequirement.

func NewPRSignedBaseLayer 

func NewPRSignedBaseLayer(baseLayerIdentity PolicyReferenceMatch) (PolicyRequirement, error)

NewPRSignedBaseLayer returns a new "signedBaseLayer" PolicyRequirement.

func NewPRSignedByKeyData 

func NewPRSignedByKeyData(keyType sbKeyType, keyData []byte, signedIdentity PolicyReferenceMatch) (PolicyRequirement, error)

NewPRSignedByKeyData returns a new "signedBy" PolicyRequirement using a KeyData

func NewPRSignedByKeyPath 

func NewPRSignedByKeyPath(keyType sbKeyType, keyPath string, signedIdentity PolicyReferenceMatch) (PolicyRequirement, error)

NewPRSignedByKeyPath returns a new "signedBy" PolicyRequirement using a KeyPath

func NewPRSignedByKeyPaths added in v5.22.0 

func NewPRSignedByKeyPaths(keyType sbKeyType, keyPaths []string, signedIdentity PolicyReferenceMatch) (PolicyRequirement, error)

NewPRSignedByKeyPaths returns a new "signedBy" PolicyRequirement using KeyPaths

func NewPRSigstoreSigned added in v5.24.0 

func NewPRSigstoreSigned(options ...PRSigstoreSignedOption) (PolicyRequirement, error)

NewPRSigstoreSigned returns a new "sigstoreSigned" PolicyRequirement based on options.

func NewPRSigstoreSignedKeyData added in v5.22.0 

func NewPRSigstoreSignedKeyData(keyData []byte, signedIdentity PolicyReferenceMatch) (PolicyRequirement, error)

NewPRSigstoreSignedKeyData returns a new "sigstoreSigned" PolicyRequirement using a KeyData

func NewPRSigstoreSignedKeyPath added in v5.22.0 

func NewPRSigstoreSignedKeyPath(keyPath string, signedIdentity PolicyReferenceMatch) (PolicyRequirement, error)

NewPRSigstoreSignedKeyPath returns a new "sigstoreSigned" PolicyRequirement using a KeyPath

type PolicyRequirementError 

type PolicyRequirementError string

PolicyRequirementError is an explanatory text for rejecting a signature or an image.

func (PolicyRequirementError) Error 

func (err PolicyRequirementError) Error() string

type PolicyRequirements 

type PolicyRequirements []PolicyRequirement

PolicyRequirements is a set of requirements applying to a set of images; each of them must be satisfied (though perhaps each by a different signature). Must not be empty, frequently will only contain a single element.

func (*PolicyRequirements) UnmarshalJSON 

func (m *PolicyRequirements) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

type PolicyTransportScopes 

type PolicyTransportScopes map[string]PolicyRequirements

PolicyTransportScopes defines policies for images for a specific transport, for various scopes, the map keys. Scopes are defined by the transport (types.ImageReference.PolicyConfigurationIdentity etc.); there is one scope precisely matching to a single image, and namespace scopes as prefixes of the single-image scope. (e.g. hostname[/zero[/or[/more[/namespaces[/individualimage]]]]]) The empty scope, if exists, is considered a parent namespace of all other scopes. Most specific scope wins, duplication is prohibited (hard failure).

func (*PolicyTransportScopes) UnmarshalJSON 

func (m *PolicyTransportScopes) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

type SignOptions added in v5.19.0 

type SignOptions struct {
	// Passphare to use when signing with the key identity.
	Passphrase string
}

SignOptions includes optional parameters for signing container images.

type Signature 

type Signature struct {
	DockerManifestDigest digest.Digest
	DockerReference      string // FIXME: more precise type?
}

Signature is a parsed content of a signature. The only way to get this structure from a blob should be as a return value from a successful call to verifyAndExtractSignature below.

func VerifyDockerManifestSignature 

func VerifyDockerManifestSignature(unverifiedSignature, unverifiedManifest []byte,
	expectedDockerReference string, mech SigningMechanism, expectedKeyIdentity string) (*Signature, error)

VerifyDockerManifestSignature checks that unverifiedSignature uses expectedKeyIdentity to sign unverifiedManifest as expectedDockerReference, using mech.

func VerifyImageManifestSignatureUsingKeyIdentityList added in v5.25.0 

func VerifyImageManifestSignatureUsingKeyIdentityList(unverifiedSignature, unverifiedManifest []byte,
	expectedDockerReference string, mech SigningMechanism, expectedKeyIdentities []string) (*Signature, string, error)

VerifyImageManifestSignatureUsingKeyIdentityList checks that unverifiedSignature uses one of the expectedKeyIdentities to sign unverifiedManifest as expectedDockerReference, using mech. Returns the verified signature and the key identity that was used to verify it.

type SigningMechanism 

type SigningMechanism interface {
	// Close removes resources associated with the mechanism, if any.
	Close() error
	// SupportsSigning returns nil if the mechanism supports signing, or a SigningNotSupportedError.
	SupportsSigning() error
	// Sign creates a (non-detached) signature of input using keyIdentity.
	// Fails with a SigningNotSupportedError if the mechanism does not support signing.
	Sign(input []byte, keyIdentity string) ([]byte, error)
	// Verify parses unverifiedSignature and returns the content and the signer's identity
	Verify(unverifiedSignature []byte) (contents []byte, keyIdentity string, err error)
	// UntrustedSignatureContents returns UNTRUSTED contents of the signature WITHOUT ANY VERIFICATION,
	// along with a short identifier of the key used for signing.
	// WARNING: The short key identifier (which corresponds to "Key ID" for OpenPGP keys)
	// is NOT the same as a "key identity" used in other calls to this interface, and
	// the values may have no recognizable relationship if the public key is not available.
	UntrustedSignatureContents(untrustedSignature []byte) (untrustedContents []byte, shortKeyIdentifier string, err error)
}

SigningMechanism abstracts a way to sign binary blobs and verify their signatures. Each mechanism should eventually be closed by calling Close().

func NewEphemeralGPGSigningMechanism 

func NewEphemeralGPGSigningMechanism(blob []byte) (SigningMechanism, []string, error)

NewEphemeralGPGSigningMechanism returns a new GPG/OpenPGP signing mechanism which recognizes _only_ public keys from the supplied blob, and returns the identities of these keys. The caller must call .Close() on the returned SigningMechanism.

func NewGPGSigningMechanism 

func NewGPGSigningMechanism() (SigningMechanism, error)

NewGPGSigningMechanism returns a new GPG/OpenPGP signing mechanism for the user’s default GPG configuration ($GNUPGHOME / ~/.gnupg) The caller must call .Close() on the returned SigningMechanism.

type SigningNotSupportedError 

type SigningNotSupportedError string

SigningNotSupportedError is returned when trying to sign using a mechanism which does not support that.

func (SigningNotSupportedError) Error 

func (err SigningNotSupportedError) Error() string

type UntrustedSignatureInformation 

type UntrustedSignatureInformation struct {
	UntrustedDockerManifestDigest digest.Digest
	UntrustedDockerReference      string // FIXME: more precise type?
	UntrustedCreatorID            *string
	UntrustedTimestamp            *time.Time
	UntrustedShortKeyIdentifier   string
}

UntrustedSignatureInformation is information available in an untrusted signature. This may be useful when debugging signature verification failures, or when managing a set of signatures on a single image.

WARNING: Do not use the contents of this for ANY security decisions, and be VERY CAREFUL about showing this information to humans in any way which suggest that these values “are probably” reliable. There is NO REASON to expect the values to be correct, or not intentionally misleading (including things like “✅ Verified by $authority”)

func GetUntrustedSignatureInformationWithoutVerifying 

func GetUntrustedSignatureInformationWithoutVerifying(untrustedSignatureBytes []byte) (*UntrustedSignatureInformation, error)

GetUntrustedSignatureInformationWithoutVerifying extracts information available in an untrusted signature, WITHOUT doing any cryptographic verification. This may be useful when debugging signature verification failures, or when managing a set of signatures on a single image.

WARNING: Do not use the contents of this for ANY security decisions, and be VERY CAREFUL about showing this information to humans in any way which suggest that these values “are probably” reliable. There is NO REASON to expect the values to be correct, or not intentionally misleading (including things like “✅ Verified by $authority”)

Source Files

View all Source files

Directories

Path Synopsis
fulcio
internal
rekor

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.