diff --git a/certs/certs.go b/certs/certs.go
index 2b46d72b69..2007de3878 100644
--- a/certs/certs.go
+++ b/certs/certs.go
@@ -123,9 +123,7 @@ func ValidateRoot(certStore trustmanager.X509Store, root *data.Signed, gun strin
return &ErrValidationFail{Reason: "failed to validate data with current trusted certificates"}
}
} else {
- logrus.Debugf("found no currently valid root certificates for %s", gun)
- logrus.Debugf("using trust_pinning config to bootstrap trust: %v", trustPinning)
-
+ logrus.Debugf("found no currently valid root certificates for %s, using trust_pinning config to bootstrap trust:", gun, trustPinning)
trustPinChecker, err := NewTrustPinChecker(trustPinning, gun)
if err != nil {
return &ErrValidationFail{Reason: err.Error()}
@@ -146,7 +144,7 @@ func ValidateRoot(certStore trustmanager.X509Store, root *data.Signed, gun strin
if len(validPinnedCerts) == 0 {
return &ErrValidationFail{Reason: "unable to match any certificates to trust_pinning config"}
}
- allValidCerts = validPinnedCerts
+ certsFromRoot = validPinnedCerts
}
// Validate the integrity of the new root (does it have valid signatures)
diff --git a/docs/images/trust-pinning-flow.png b/docs/images/trust-pinning-flow.png
new file mode 100644
index 0000000000..6d88335890
Binary files /dev/null and b/docs/images/trust-pinning-flow.png differ
diff --git a/docs/reference/client-config.md b/docs/reference/client-config.md
index 8d99683ba7..30c3417a0e 100644
--- a/docs/reference/client-config.md
+++ b/docs/reference/client-config.md
@@ -127,10 +127,16 @@ This section is optional, Notary will use TOFU over HTTPS by default and
trust certificates in the downloaded root file.
In this section, one can provide specific certificates to pin to, or a CA
-to pin to as a root of trust for a GUN.
+to pin to as a root of trust for a GUN. Multiple sections can be specified,
+but the pinned certificates will take highest priority for validation, followed
+by the pinned CA, followed by TOFUS (TOFU over HTTPS). The diagram below
+describes this validation flow:
-Only one trust pinning option can be used per GUN, and any validation failure
-will result in a failed bootstrapping of the repo.
+
+
+Only one trust pinning option will be used to validate a GUN even if multiple
+sections are specified, and any validation failure will result in a failed
+bootstrapping of the repo.