Notary client configuration file

Estimated reading time: 5 minutes

This document is for power users of the Notary client who want to facilitate CLI interaction or specify custom options.

The configuration file for Notary client normally resides at ~/.notary/config.json, but the path to a different configuration file can be specified using the -c or --configFile command line flag.

Overview of the file

In addition to the configuration file format, see the optional password environment variables that the Notary client can take for ease of use.

Here is a full client configuration file example; click on the top level JSON keys to learn more about the configuration section corresponding to that key:

{
  "trust_dir" : "~/.docker/trust",
  "remote_server": {
    "url": "https://my-notary-server.my-private-registry.com",
    "root_ca": "./fixtures/root-ca.crt",
    "tls_client_cert": "./fixtures/secure.example.com.crt",
    "tls_client_key": "./fixtures/secure.example.com.crt"
  },
  "trust_pinning": {
    "certs": {
      "docker.com/notary": ["49cf5c6404a35fa41d5a5aa2ce539dfee0d7a2176d0da488914a38603b1f4292"]
    }
  }
}

trust_dir section (optional)

The trust_dir specifies the location (as an absolute path or a path relative to the directory of the configuration file) where the TUF metadata and private keys are stored.

This is normally defaults to ~/.notary, but specifying ~/.docker/trust facilitates interoperability with content trust.

This option can be overridden with the command line flag --trustDir.

remote_server section (optional)

The remote_server specifies how to connect to a Notary server to download metadata updates and publish metadata changes.

Remote server example:

"remote_server": {
  "url": "https://my-notary-server.my-private-registry.com",
  "root_ca": "./fixtures/root-ca.crt",
  "tls_client_cert": "./fixtures/secure.example.com.crt",
  "tls_client_key": "./fixtures/secure.example.com.crt"
}

trust_pinning section (optional)

The trust_pinning specifies how to bootstrap trust for the root of a Notary client’s trusted collection.

This section is optional, Notary uses 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. Multiple sections can be specified, but the pinned certificates 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 is used to validate a GUN even if multiple sections are specified, and any validation failure results in a failed bootstrapping of the repo.

Environment variables (optional)

The following environment variables containing signing key passphrases can be used to facilitate Notary client CLI interaction. If provided, these passwords are used initially to sign TUF metadata. If the passphrase is incorrect, you are prompted to enter the correct passphrase.

If provided, the passphrase in NOTARY_DELEGATION_PASSPHRASE is tried for all delegation roles that notary attempts to sign with.