sign

package
v0.0.0-...-fc78dae Latest Latest
Warning

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

 Go to latest Published: Dec 6, 2024 License: MIT Imports: 44 Imported by: 0

Documentation

Overview

Package sign provides an interface abstraction and implementation for creating/verifying signatures of OCI or docker manifest digests.

Index

Constants

View Source 
const (
	AnnotationKeyID     = "keyID"      // AnnotationKeyID is the key identifier. A layer annotation key.
	AnnotationUserID    = "identity"   // AnnotationUserID is the key owner's identity. A layer annotation key.
	AnnotationVerifyAPI = "verify-api" // AnnotationVerifyAPI is the api to use when verifying. A layer annotation key.

)

Keys for OCI layer annotations.

View Source 
const AnnotationX509ChainThumbprint = "io.cncf.notary.x509chain.thumbprint#S256"

AnnotationX509ChainThumbprint stores a certificate chain as a list of thumbprints. A manifest annotation key. Note: Notation keeps this internal at "github.com/notaryproject/notation-go/internal/envelope", which is odd as it's a required property of a notation signature.

View Source 
const (
	SignatureFileExt string = ".sig" // SignatureFileExt is the file extension for a signature manifest.
)
View Source 
const (
	SignatureTagSuffix string = "sig" // SignatureTagSuffix is the suffix for a tag, follows the digest of the signed manifest
)

Variables

View Source 
var ErrNoSignatureAnnotation = errors.New("no signature found in annotations")

ErrNoSignatureAnnotation indicates that a signature was not found in an annotation.

Functions

func FingerprintECDSA 

func FingerprintECDSA(rawKey crypto.PublicKey) (digest.Digest, error)

FingerprintECDSA returns the fingerprint of an ECDSA public key in PEM format. This is a sha256 digest of the data, and can be used to compare keys.

func FingerprintPEM 

func FingerprintPEM(pemBytes []byte) digest.Digest

FingerprintPEM returns a fingerprint of a key in PEM format. Similar to FingerprintECDSA, but does not convert a key to pem format first.

func GetPassFromTerm 

func GetPassFromTerm(confirm bool) ([]byte, error)

GetPassFromTerm prompts the user to provide a password from the terminal.

func IsSigConfig 

func IsSigConfig(mediaType string) bool

IsSigConfig verifies the media type of a notary signature config.

func PrepareSigsGraph 

func PrepareSigsGraph(ctx context.Context, btlPath string, localStore *storage.DataStore, subject ocispec.Descriptor) error

PrepareSigsGraph prepares signatures referring to subject for pushing by adding them to the file-backed oras filestore. Safe to call if no signatures exist. The additional descriptor is for the referrers fallback mechanism, which only supports a single tag. Due to the data-race nature of the fallback mechanism it is likely undesired behavior will occur if more than one fallback manifest is found in the .signature directory.

func Pull 

func Pull(ctx context.Context, btlPath string, source content.ReadOnlyGraphStorage, subject ocispec.Descriptor) error

Pull copies all signatures referring to the subject descriptor from source to btlPath. Safe to call if no signatures exist.

func ResolveSigManifestName 

func ResolveSigManifestName(targetDigest digest.Digest) string

ResolveSigManifestName resolves the filename of a signature manifest. Ex: <algorithm>-<hash_hex>.sig.

func ResolveSigManifestNames 

func ResolveSigManifestNames(localPath string, subjectDigest digest.Digest) ([]string, error)

ResolveSigManifestNames creates and returns a list of filenames of signature manifests containing a subject field that points to the provided subject digest.

func ValidateSigManifest 

func ValidateSigManifest(m ocispec.Manifest) error

ValidateSigManifest validates a signature manifest for correctness.

Types

type EcdsaCertPair 

type EcdsaCertPair struct {
	Cert       *x509.Certificate
	PrivateKey *ecdsa.PrivateKey
}

EcdsaCertPair is an association between a certificate and an ecdsa private key.

func MakeEcdsaCertPair 

func MakeEcdsaCertPair(cn string, privateKey PrivateKeyProvider, issuer *EcdsaCertPair) EcdsaCertPair

MakeEcdsaCertPair creates a new certificate and associates it with a private key. If issuer is not nil, then the provided issuer certificate is a parent certificate, otherwise a root certificate is created.

type KeyRetriever 

type KeyRetriever interface {
	RetrieveVerifier(crypto.Hash) (Verifier, error)
}

KeyRetriever provide a means of fetching public keys from a remote location and defaults to using the attached public key or certificate. WARNING: An attached key / certificate does not automatically link a signer identity with signature, without which a signature does not provide a guarantee of authenticity or security.

func NewCertRetriever 

func NewCertRetriever(mediatype string, payload []byte) (KeyRetriever, error)

NewCertRetriever constructs a certificate based key retriever for a jws or cose envelope.

type NotarySignatures 

type NotarySignatures struct {
	// Subject is the descriptor of the manifest being signed (becomes subject in signature manifest)
	Subject ocispec.Descriptor

	// HashFunc is the hash function used for calculating digests.
	HashFunc crypto.Hash

	// SigManifest is the signature manifest handler.
	SigManifests []SigsManifestHandler

	// Certificate chain for signing
	CertChain []*x509.Certificate

	// LocalPath is the local path to the signature image directory.
	LocalPath string

	// SigVerified is a list of signature layer digests that were successfully verified on the last call to Verify.
	SigVerified []digest.Digest

	// SigFailed is a list of signature layer digests that failed to verify on the last call to Verify.
	SigFailed []digest.Digest
}

NotarySignatures represents a set of notary based manifest signatures, implementing SigsHandler.

func (*NotarySignatures) FailedSignatures 

func (notarySigs *NotarySignatures) FailedSignatures() []digest.Digest

FailedSignatures returns a list of signature fingerprints that failed verification during the last Verify.

func (*NotarySignatures) MakeSignatureManifest 

func (notarySigs *NotarySignatures) MakeSignatureManifest(ctx context.Context,
	signerInfo *signature.SignerInfo,
	mediatype string, envelope []byte,
	unsignedAnnos map[string]string,
) (SigsManifestHandler, error)

MakeSignatureManifest builds a signature manifest adhering to the notary signature spec. See https://github.com/notaryproject/specifications/blob/main/specs/signature-specification.md#oci-signatures.

func (*NotarySignatures) Sign 

func (notarySigs *NotarySignatures) Sign(ctx context.Context, pkProvider PrivateKeyProvider, unsignedAnnos map[string]string, signedAnnos map[string]string) error

Sign signs a manifest digest along with annotations using the private key provided. Sign implements the SigsHandler interface. The LoadLocalSignatures function should be used prior to calling this method.

func (*NotarySignatures) Signatures 

func (notarySigs *NotarySignatures) Signatures() []Signature

Signatures returns a slice of all signature layers.

func (*NotarySignatures) SignedSubject 

func (notarySigs *NotarySignatures) SignedSubject() ocispec.Descriptor

SignedSubject returns the manifest digest to be signed/verified. SignedSubject implements the SigsHandler interface.

func (*NotarySignatures) VerifiedSignatures 

func (notarySigs *NotarySignatures) VerifiedSignatures() []digest.Digest

VerifiedSignatures returns a list of signature fingerprints that passed verification during the last Verify.

func (*NotarySignatures) Verify 

func (notarySigs *NotarySignatures) Verify(ctx context.Context) (bool, error)

Verify verifies all loaded signatures, returning a boolean indicating if all signatures passed verification. More specific information regarding failed and verified signatures can be retrieved with the appropriate methods. TODO: Currently insecure as we verify the certificate chain against its own root certificate. Verify implements the SigsHandler interface. The LoadLocalSignatures function should be used prior to calling this method.

func (*NotarySignatures) WriteDisk 

func (notarySigs *NotarySignatures) WriteDisk(signedDigest digest.Digest) error

WriteDisk writes the config, manifest, and a signature layer to disk. Notary signature manifests are named based on their own digest.

type PrivateKeyProvider 

type PrivateKeyProvider interface {
	// PrivateKey returns a pointer to an ecdsa private key for signing. NOTE: consider opts for future expansion.
	PrivateKey() (crypto.PrivateKey, error)
	// PublicKeyPEM returns a PEM public key based on a private key. This can load the private key if necessary.
	PublicKeyPEM() ([]byte, error)
	// PrivateKeyPEM returns a private key based on a private key. This can load the private key if necessary.
	PrivateKeyPEM() ([]byte, error)
	// Certificate returns a x509 certificate associated with a private key.
	Certificate() (*x509.Certificate, error)
}

PrivateKeyProvider provide methods for accessing a private key and its corresponding public key.

func GenerateKeyPair 

func GenerateKeyPair() (PrivateKeyProvider, error)

GenerateKeyPair generates a public private ECDSA key pair.

func NewFilePrivateKeyProvider 

func NewFilePrivateKeyProvider(keyPath, certPath string) PrivateKeyProvider

NewFilePrivateKeyProvider creates a private key provider with the given path. Key loading is delayed until later optKey allows the private key to be generated elsewhere, in which case the path won't be used.

func NewPrivateKeyProvider 

func NewPrivateKeyProvider(key *ecdsa.PrivateKey) PrivateKeyProvider

NewPrivateKeyProvider creates a simple private key provider with the raw private key.

type PublicKeyOption 

type PublicKeyOption interface {
	RPCOption
}

PublicKeyOption specifies options to be used when obtaining a public key.

type PublicKeyProvider 

type PublicKeyProvider interface {
	GetPublicKey(opts ...PublicKeyOption) (crypto.PublicKey, error)
}

PublicKeyProvider returns a PublicKey associated with a digital signature.

type RPCAuth 

type RPCAuth struct {
	Address string // address is the remote server address, e.g. https://vault:8200
	Path    string // path for the RPC, in vault this is the transit path which default to "transit"
	Token   string // token used for RPC, in vault this is the VAULT_TOKEN value
	OIDC    RPCAuthOIDC
}

RPCAuth provides credentials for RPC calls, empty fields are ignored.

type RPCAuthOIDC 

type RPCAuthOIDC struct {
	Path  string // path defaults to "jwt" for vault
	Role  string // role is required for jwt logins
	Token string // token is a jwt with vault
}

RPCAuthOIDC is used to perform the RPC login using OIDC instead of a fixed token.

type RPCOption 

type RPCOption interface {
	ApplyContext(*context.Context)
	ApplyRemoteVerification(*bool)
	ApplyRPCAuthOpts(opts *RPCAuth) // was options.RPCAuth
	ApplyKeyVersion(keyVersion *string)
}

RPCOption specifies options to be used when performing RPC.

type Signature 

type Signature interface {

	// Annotations returns the annotations associated with this layer.
	Annotations() (map[string]string, error)

	// GetDescriptor returns the signature layer descriptor.
	GetDescriptor() ocispec.Descriptor

	// GetPayload fetches the opaque data that is being signed.
	// This will always return data when there is no error.
	GetPayload() ([]byte, error)

	// GetPayloadBase64 returns the payload, base64 encoded.
	GetPayloadBase64() (string, error)

	// GetKeyRetrieverForPayload returns a key retriever determined
	// by the metadata included in the signed annotations of a signature.
	GetKeyRetrieverForPayload() (KeyRetriever, error)

	// Path returns the local path of the signature.
	Path() string
}

Signature handles a signature layer by providing access to it's data.

func NewNotarySigLayer 

func NewNotarySigLayer(layerDescriptor ocispec.Descriptor, sigsPath string, layerData []byte) Signature

NewNotarySigLayer returns a sig layer used for extracting signature information. layerData can contain the raw signature layer bytes, or nil if GetPayload() is planned to be called later (which will load the data from sigsPath).

type SigsHandler 

type SigsHandler interface {
	// Sign signs a manifest digest. unsignedAnnos allows unsigned annotations to be included with a signature layer
	// (such as userid/verify api), while signedAnnos are additional metadata to be included in the signed payload,
	// such as attestation data.
	Sign(ctx context.Context, pkProvider PrivateKeyProvider, unsignedAnnos, signedAnnos map[string]string) error

	// Verify verifies ALL existing signatures, using optional locally provided keys.  Returns true if all signatures
	// verify or pass integrity (when the only public key is untrusted).  Additional details can be returned via errors
	// or within the interface implementation
	Verify(context.Context) (bool, error)

	// Signatures returns all signature layers.
	Signatures() []Signature

	// VerifiedSignatures returns a list of signature layer digests that passed verification during the last Verify
	VerifiedSignatures() []digest.Digest

	// FailedSignatures returns a list of signature layer digests that failed verification during the last Verify
	FailedSignatures() []digest.Digest

	// SignedSubject returns the manifest digest to be signed/verified.
	SignedSubject() ocispec.Descriptor

	// WriteDisk writes the config, manifest, and a signature layer to disk.
	WriteDisk(digest.Digest) error
}

SigsHandler wraps the act3oci ManifestHandler with additional methods for handling signatures.

func LoadLocalSignatures 

func LoadLocalSignatures(ctx context.Context, targetDescriptor ocispec.Descriptor, localPath string) (SigsHandler, error)

LoadLocalSignatures loads a signature image manifest at a local path, returning a handler for the signature collection.

type SigsManifest 

type SigsManifest struct {
	Descriptor ocispec.Descriptor
	Manifest   ocispec.Manifest
	Config     []byte

	oci.ManifestStatusInfo
	// contains filtered or unexported fields
}

SigsManifest is an alias for ocispec.Manifest which implements the manifest handler interface. It also contains information about the manifest descriptor itself (notably, size, Digest, etc), and a status structure used during transfer. This structure implements the ManifestHandler interface.

Note: This struct is derived from the BottleManifest struct in act3oci.manifesthandler.go, but introduces setters and a config with methods for handling the config. Setters introduced are: SetManifestData, SetManifestRaw, SetConfigData, SetConfigRaw, GetConfigRaw, and AddLayerDescriptor.

func NewEmptySigsManifest 

func NewEmptySigsManifest() *SigsManifest

NewEmptySigsManifest creates an empty sigs manifest for situations when no local sig.

func (*SigsManifest) AddAnnotation 

func (s *SigsManifest) AddAnnotation(key string, value string)

AddAnnotation adds a key value annotation to the manifest. AddAnnotations implements the ManifestHandler interface.

func (*SigsManifest) Copy 

func (s *SigsManifest) Copy() oci.ManifestHandler

Copy creates a fresh manifest handler based on the data contained in the current SigManifest. This allows a duplicate handler to be modified (such as adding annotations) without updating the originating handler.

NOTE: This copy function returns a read-only handler. If there is an error marshaling the manifest a ManifestHandler will have an empty manifest.

func (*SigsManifest) GetAnnotation 

func (s *SigsManifest) GetAnnotation(key string) string

GetAnnotation returns a annotation value based on a given key, or empty if the key is not found GetAnnotation implements the ManifestHandler interface.

func (*SigsManifest) GetAnnotations 

func (s *SigsManifest) GetAnnotations() map[string]string

GetAnnotations retrieves the annotations collection from the manifest.

func (*SigsManifest) GetConfigData 

func (s *SigsManifest) GetConfigData() []byte

GetConfigData returns the full manifest data object. GetConfigData implements the SigsManifestHandler interface.

func (*SigsManifest) GetConfigDescriptor 

func (s *SigsManifest) GetConfigDescriptor() ocispec.Descriptor

GetConfigDescriptor returns the OCI descriptor for the config record within the manifest data. GetConfigDescriptor implements the ManifestHandler interface.

func (*SigsManifest) GetConfigRaw 

func (s *SigsManifest) GetConfigRaw() ([]byte, error)

GetConfigRaw returns the original raw data for the manifest. GetConfigRaw implements the SigsManifestHandler interface.

func (*SigsManifest) GetContentDescriptors 

func (s *SigsManifest) GetContentDescriptors() []ocispec.Descriptor

GetContentDescriptors returns a collection of content descriptors, with the config blob first. GetContentDescriptors implements the ManifestHandler interface.

func (*SigsManifest) GetLayerDescriptors 

func (s *SigsManifest) GetLayerDescriptors() []ocispec.Descriptor

GetLayerDescriptors returns a list of OCI descriptors for each layer specified in a manifest. GetLayerDescriptors implements the ManifestHandler interface.

func (*SigsManifest) GetManifestData 

func (s *SigsManifest) GetManifestData() ocispec.Manifest

GetManifestData returns an OCI manifest structure filled with manifest data. GetManifestData implements the ManifestHandler interface.

func (*SigsManifest) GetManifestDescriptor 

func (s *SigsManifest) GetManifestDescriptor() ocispec.Descriptor

GetManifestDescriptor returns the OCI descriptor for the manifest data. GetManifestDescriptor implements the ManifestHandler interface.

func (*SigsManifest) GetManifestRaw 

func (s *SigsManifest) GetManifestRaw() ([]byte, error)

GetManifestRaw returns a json formatted slice of bytes representing the manifest data. GetManifestRaw implements the ManifestHandler interface.

func (*SigsManifest) GetRawLayers 

func (s *SigsManifest) GetRawLayers() map[digest.Digest][]byte

GetRawLayers returns a map of digests to json formatted slice of bytes of the signature layers. GetRawLayers implements the SigsManifestHandler interface.

func (*SigsManifest) GetStatus 

func (s *SigsManifest) GetStatus() oci.ManifestStatusInfo

GetStatus returns information about the transfer of a manifest, including http and internal error information. GetStatus implements the ManifestHandler interface.

func (*SigsManifest) SetConfigData 

func (s *SigsManifest) SetConfigData(rawData []byte)

SetConfigData sets the config data structure. SetConfigData implements the SigsManifestHandler interface.

func (*SigsManifest) SetLayerDescriptors 

func (s *SigsManifest) SetLayerDescriptors(layers []ocispec.Descriptor) error

SetLayerDescriptors sets layer information in both the manifest and config. SetLayerDescriptors implements the SigsManifestHandler interface.

func (*SigsManifest) SetManifestData 

func (s *SigsManifest) SetManifestData(manifest ocispec.Manifest)

SetManifestData sets the manifest data structure. SetManifestDate implements the SigsManifestHandler interface.

func (*SigsManifest) SetRawLayers 

func (s *SigsManifest) SetRawLayers(layers map[digest.Digest][]byte)

SetRawLayers sets the map of digests to json formatted slice of bytes of the signature layers. SetRawLayers implements the SigsManifestHandler interface.

func (*SigsManifest) UpdateManifestDescriptor 

func (s *SigsManifest) UpdateManifestDescriptor() error

UpdateManifestDescriptor updates the manifest descriptor to reflect the current manifest data. UpdateManifestDescriptor implements the SigsManifestHandler interface.

func (*SigsManifest) WriteDisk 

func (s *SigsManifest) WriteDisk(dir, sigManifestTag, configFileName string) error

WriteDisk writes the entire signature image data to disk. The signature directory is created if it does not already exist. The signature manifest is named locally and remotely by the manifest tag. The signature configuration is named similarly to the manifest with a "-Config.json" suffix rather than ".sig". WriteDisk implements the SigsManifestHandler interface.

type SigsManifestHandler 

type SigsManifestHandler interface {
	oci.ManifestHandler
	// SetManifestData sets the OCI manifest data structure.
	SetManifestData(ocispec.Manifest)
	// UpdateManifestDescriptor updates the manifest descriptor to reflect current manifest data.
	UpdateManifestDescriptor() error
	// GetConfigData gets the OCI config data structure.
	GetConfigData() []byte
	// GetConfigRaw gets the json formatted slice of bytes representing the config data.
	GetConfigRaw() ([]byte, error)
	// SetConfigData sets the OCI config data structure.
	SetConfigData([]byte)
	// SetLayerDescriptors sets the layer descriptors for the manifest and DiffIDs for the config.
	SetLayerDescriptors([]ocispec.Descriptor) error
	// GetAnnotations retrieves the annotations collection from the manifest
	GetAnnotations() map[string]string
	// GetRawLayers returns the raw layers.
	GetRawLayers() map[digest.Digest][]byte
	// SetRawLayers sets the raw layers.
	SetRawLayers(map[digest.Digest][]byte)
	// WriteDisk writes the manifest, config, and layers to disk.
	WriteDisk(string, string, string) error
}

SigsManifestHandler wraps an act3oci.ManifestHandler with additional functions used for creating or updating a signature image manifest.

func SigManifestsFromPath 

func SigManifestsFromPath(localPath string, subjectDigest digest.Digest) ([]SigsManifestHandler, error)

SigManifestsFromPath returns a slice of SigsManifestHandlers for all signature image manifests referring to the subject, discovered by path.

func SigsManifestFromData 

func SigsManifestFromData(contentType string, data []byte) SigsManifestHandler

SigsManifestFromData constructs a SigsManifestHandler from data.

type TrustStoreProvider 

type TrustStoreProvider interface {
	GetX509TrustStore() truststore.X509TrustStore
}

TrustStoreProvider is a notary trust store provider, that can help locate trusted x509 certificates.

type Verifier 

type Verifier interface {
	PublicKeyProvider
	TrustStoreProvider
	VerifySignature(signedSubject ocispec.Descriptor, signature io.Reader) error
}

Verifier verifies the digital signature using a specified public key. VerifyOption (included RPCOpts) was removed from VerifySignature.

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.
JackTT - Gopher 🇻🇳