trustpinning

Documentation

Index

• func MatchCNToGun(commonName string, gun data.GUN) bool
• func ValidateRoot(prevRoot *data.SignedRoot, root *data.Signed, gun data.GUN, ...) (*data.SignedRoot, error)
• type CertChecker
  • func NewTrustPinChecker(trustPinConfig TrustPinConfig, gun data.GUN, firstBootstrap bool) (CertChecker, error)
• type ErrRootRotationFail
  • func (err ErrRootRotationFail) Error() string
• type ErrValidationFail
  • func (err ErrValidationFail) Error() string
• type TrustPinConfig

Functions

func MatchCNToGun

func MatchCNToGun(commonName string, gun data.GUN) bool

MatchCNToGun checks that the common name in a cert is valid for the given gun. This allows wildcards as suffixes, e.g. `namespace/*`

func ValidateRoot

func ValidateRoot(prevRoot *data.SignedRoot, root *data.Signed, gun data.GUN, trustPinning TrustPinConfig) (*data.SignedRoot, error)

ValidateRoot receives a new root, validates its correctness and attempts to do root key rotation if needed.

First we check if we have any trusted certificates for a particular GUN in a previous root, if we have one. If the previous root is not nil and we find certificates for this GUN, we've already seen this repository before, and have a list of trusted certificates for it. In this case, we use this list of certificates to attempt to validate this root file.

If the previous validation succeeds, we check the integrity of the root by making sure that it is validated by itself. This means that we will attempt to validate the root data with the certificates that are included in the root keys themselves.

However, if we do not have any current trusted certificates for this GUN, we check if there are any pinned certificates specified in the trust_pinning section of the notary client config. If this section specifies a Certs section with this GUN, we attempt to validate that the certificates present in the downloaded root file match the pinned ID.

If the Certs section is empty for this GUN, we check if the trust_pinning section specifies a CA section specified in the config for this GUN. If so, we check that the specified CA is valid and has signed a certificate included in the downloaded root file. The specified CA can be a prefix for this GUN.

If both the Certs and CA configs do not match this GUN, we fall back to the TOFU section in the config: if true, we trust certificates specified in the root for this GUN. If later we see a different certificate for that certificate, we return an ErrValidationFailed error.

Note that since we only allow trust data to be downloaded over an HTTPS channel we are using the current public PKI to validate the first download of the certificate adding an extra layer of security over the normal (SSH style) trust model. We shall call this: TOFUS.

Validation failure at any step will result in an ErrValidationFailed error.

Types

type CertChecker

type CertChecker func(leafCert *x509.Certificate, intCerts []*x509.Certificate) bool

CertChecker is a function type that will be used to check leaf certs against pinned trust

func NewTrustPinChecker

func NewTrustPinChecker(trustPinConfig TrustPinConfig, gun data.GUN, firstBootstrap bool) (CertChecker, error)

NewTrustPinChecker returns a new certChecker function from a TrustPinConfig for a GUN

type ErrRootRotationFail

type ErrRootRotationFail struct {
	Reason string
}

ErrRootRotationFail is returned when we fail to do a full root key rotation by either failing to add the new root certificate, or delete the old ones

func (ErrRootRotationFail) Error

func (err ErrRootRotationFail) Error() string

ErrRootRotationFail is returned when we fail to do a full root key rotation by either failing to add the new root certificate, or delete the old ones

type ErrValidationFail

type ErrValidationFail struct {
	Reason string
}

ErrValidationFail is returned when there is no valid trusted certificates being served inside of the roots.json

func (ErrValidationFail) Error

func (err ErrValidationFail) Error() string

ErrValidationFail is returned when there is no valid trusted certificates being served inside of the roots.json

type TrustPinConfig

type TrustPinConfig struct {
	// CA maps a GUN prefix to file paths containing the root CA.
	// This file can contain multiple root certificates, bundled in separate PEM blocks.
	CA map[string]string
	// Certs maps a GUN to a list of certificate IDs
	Certs map[string][]string
	// DisableTOFU, when true, disables "Trust On First Use" of new key data
	// This is false by default, which means new key data will always be trusted the first time it is seen.
	DisableTOFU bool
}

TrustPinConfig represents the configuration under the trust_pinning section of the config file This struct represents the preferred way to bootstrap trust for this repository This is fully optional. If left at the default, uninitialized value Notary will use TOFU over HTTPS. You can use this to provide certificates or a CA to pin to as a root of trust for a GUN. These are used with the following precedence:

1. Certs 2. CA 3. TOFUS (TOFU over HTTPS)

Only one trust pinning option will be used to validate a particular GUN.