provenance

Documentation

Overview

Package provenance provides tools for establishing the authenticity of a chart.

In Helm, provenance is established via several factors. The primary factor is the cryptographic signature of a chart. Chart authors may sign charts, which in turn provide the necessary metadata to ensure the integrity of the chart file, the Chart.yaml, and the referenced Docker images.

A provenance file is clear-signed. This provides cryptographic verification that a particular block of information (Chart.yaml, archive file, images) have not been tampered with or altered. To learn more, read the GnuPG documentation on clear signatures: https://www.gnupg.org/gph/en/manual/x135.html

The cryptography used by Helm should be compatible with OpenGPG. For example, you should be able to verify a signature by importing the desired public key and using `gpg --verify`, `keybase pgp verify`, or similar:

$  gpg --verify some.sig
gpg: Signature made Mon Jul 25 17:23:44 2016 MDT using RSA key ID 1FC18762
gpg: Good signature from "Helm Testing (This key should only be used for testing. DO NOT TRUST.) <helm-testing@helm.sh>" [ultimate]

Index

• func Digest(in io.Reader) (string, error)
• func DigestFile(filename string) (string, error)
• type PassphraseFetcher
• type Signatory
  • func NewFromFiles(keyfile, keyringfile string) (*Signatory, error)
  • func NewFromKeyring(keyringfile, id string) (*Signatory, error)
  • func (s *Signatory) ClearSign(chartpath string) (string, error)
  • func (s *Signatory) DecryptKey(fn PassphraseFetcher) error
  • func (s *Signatory) Verify(chartpath, sigpath string) (*Verification, error)
• type SumCollection
• type Verification

Functions

func Digest

func Digest(in io.Reader) (string, error)

Digest hashes a reader and returns a SHA256 digest.

Helm uses SHA256 as its default hash for all non-cryptographic applications.

func DigestFile

func DigestFile(filename string) (string, error)

DigestFile calculates a SHA256 hash (like Docker) for a given file.

It takes the path to the archive file, and returns a string representation of the SHA256 sum.

The intended use of this function is to generate a sum of a chart TGZ file.

Types

type PassphraseFetcher

type PassphraseFetcher func(name string) ([]byte, error)

PassphraseFetcher returns a passphrase for decrypting keys.

This is used as a callback to read a passphrase from some other location. The given name is the Name field on the key, typically of the form:

USER_NAME (COMMENT) <EMAIL>

type Signatory

type Signatory struct {
	// The signatory for this instance of Helm. This is used for signing.
	Entity *openpgp.Entity
	// The keyring for this instance of Helm. This is used for verification.
	KeyRing openpgp.EntityList
}

Signatory signs things.

Signatories can be constructed from a PGP private key file using NewFromFiles or they can be constructed manually by setting the Entity to a valid PGP entity.

The same Signatory can be used to sign or validate multiple charts.

func NewFromFiles

func NewFromFiles(keyfile, keyringfile string) (*Signatory, error)

NewFromFiles constructs a new Signatory from the PGP key in the given filename.

This will emit an error if it cannot find a valid GPG keyfile (entity) at the given location.

Note that the keyfile may have just a public key, just a private key, or both. The Signatory methods may have different requirements of the keys. For example, ClearSign must have a valid `openpgp.Entity.PrivateKey` before it can sign something.

func NewFromKeyring

func NewFromKeyring(keyringfile, id string) (*Signatory, error)

NewFromKeyring reads a keyring file and creates a Signatory.

If id is not the empty string, this will also try to find an Entity in the keyring whose name matches, and set that as the signing entity. It will return an error if the id is not empty and also not found.

func (*Signatory) ClearSign

func (s *Signatory) ClearSign(chartpath string) (string, error)

ClearSign signs a chart with the given key.

This takes the path to a chart archive file and a key, and it returns a clear signature.

The Signatory must have a valid Entity.PrivateKey for this to work. If it does not, an error will be returned.

func (*Signatory) DecryptKey

func (s *Signatory) DecryptKey(fn PassphraseFetcher) error

DecryptKey decrypts a private key in the Signatory.

If the key is not encrypted, this will return without error.

If the key does not exist, this will return an error.

If the key exists, but cannot be unlocked with the passphrase returned by the PassphraseFetcher, this will return an error.

If the key is successfully unlocked, it will return nil.

func (*Signatory) Verify

func (s *Signatory) Verify(chartpath, sigpath string) (*Verification, error)

Verify checks a signature and verifies that it is legit for a chart.

type SumCollection

type SumCollection struct {
	Files  map[string]string `json:"files"`
	Images map[string]string `json:"images,omitempty"`
}

SumCollection represents a collection of file and image checksums.

Files are of the form:

FILENAME: "sha256:SUM"

Images are of the form:

"IMAGE:TAG": "sha256:SUM"

Docker optionally supports sha512, and if this is the case, the hash marker will be 'sha512' instead of 'sha256'.

type Verification

type Verification struct {
	// SignedBy contains the entity that signed a chart.
	SignedBy *openpgp.Entity
	// FileHash is the hash, prepended with the scheme, for the file that was verified.
	FileHash string
	// FileName is the name of the file that FileHash verifies.
	FileName string
}

Verification contains information about a verification operation.