signature

package
v3.0.2+incompatible Latest Latest
Warning

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

Go to latest
Published: Aug 7, 2019 License: Apache-2.0 Imports: 21 Imported by: 0

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.

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 struct {
	// contains filtered or unexported fields
}

InvalidSignatureError is returned when parsing an invalid signature.

func (InvalidSignatureError) Error

func (err InvalidSignatureError) Error() string

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, image 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 futher 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, image 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.

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

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

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 correponds to "Key ID" for OpenPGP keys)
	// is NOT the same as a "key identity" used in other calls ot 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(). FIXME: Eventually expand on keyIdentity (namespace them between mechanisms to eliminate ambiguities, support CA signatures and perhaps other key properties)

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL