Skip to main content

Notary

The Notary project, initially sponsored by Docker, is designed to provide high levels of trust over digital content using strong cryptographic signatures. In addition to ensuring the provenance of the software, it also provides guarantees that the content is not modified without approval of the author anywhere in the supply chain. This then allows higher level systems like Docker Enterprise Edition (EE) with Docker Content Trust (which uses Notary) to establish clear policy on the usage of content. For instance, a policy can be set that only signed content can be used at runtime and deployed by the orchestrators in the Docker platform. Overall Notary is a core piece of plumbing in Docker’s approach to the secure supply chain whereby security is seamlessly and uniformly embedded into a workflow from development all the way through to operations.

Overview

The Notary project comprises a server and a client for running and interacting with trusted collections.

Notary aims to make the internet more secure by making it easy for people to publish and verify content. We often rely on TLS to secure our communications with a web server, which is inherently flawed, as any compromise of the server enables malicious content to be substituted for the legitimate content.

With Notary, publishers can sign their content offline using keys kept highly secure. Once the publisher is ready to make the content available, they can push their signed trusted collection to a Notary Server.

Consumers, having acquired the publisher's public key through a secure channel, can then communicate with any Notary server or (insecure) mirror, relying only on the publisher's key to determine the validity and integrity of the received content.

Goals

Notary is based on The Update Framework, a secure general design for the problem of software distribution and updates. By using TUF, Notary achieves a number of key advantages:

  • Survivable Key Compromise: Content publishers must manage keys in order to sign their content. Signing keys may be compromised or lost so systems must be designed in order to be flexible and recoverable in the case of key compromise. TUF's notion of key roles is utilized to separate responsibilities across a hierarchy of keys such that loss of any particular key (except the root role) by itself is not fatal to the security of the system.
  • Freshness Guarantees: Replay attacks are a common problem in designing secure systems, where previously valid payloads are replayed to trick another system. The same problem exists in the software update systems, where old signed can be presented as the most recent. Notary makes use of timestamping on publishing so that consumers can know that they are receiving the most up to date content. This is particularly important when dealing with software update where old vulnerable versions could be used to attack users.
  • Configurable Trust Thresholds: Oftentimes there are a large number of publishers that are allowed to publish a particular piece of content. For example, open source projects where there are a number of core maintainers. Trust thresholds can be used so that content consumers require a configurable number of signatures on a piece of content in order to trust it. Using thresholds increases security so that loss of individual signing keys doesn't allow publishing of malicious content.
  • Signing Delegation: To allow for flexible publishing of trusted collections, a content publisher can delegate part of their collection to another signer. This delegation is represented as signed metadata so that a consumer of the content can verify both the content and the delegation.
  • Use of Existing Distribution: Notary's trust guarantees are not tied at all to particular distribution channels from which content is delivered. Therefore, trust can be added to any existing content delivery mechanism.
  • Untrusted Mirrors and Transport: All of the notary metadata can be mirrored and distributed via arbitrary channels.

With technologies such as containerd and Kubernetes already members of CNCF, Notary and TUF are the first security-related projects to be added to the CNFC. This year has seen a significant uptick in data security compromises and we believe the CNCF is positioning itself ahead of the curve by inviting Notary and TUF to join. We hope that more security-focused projects are added to the CNCF over time.

Getting started with the Notary CLI

To use the Notary CLI with Docker hub images, have a look at Notary's getting started docs.

To use the CLI against a local Notary server rather than against Docker Hub:

  1. Ensure that you have docker and docker-compose installed.

  2. git clone https://github.com/theupdateframework/notary.git and from the cloned repository path, start up a local Notary server and signer and copy the config file and testing certs to your local Notary config directory:

    $ docker-compose build
    $ docker-compose up -d
    $ mkdir -p ~/.notary && cp cmd/notary/config.json cmd/notary/root-ca.crt ~/.notary

  3. Add 127.0.0.1 notary-server to your /etc/hosts, or if using docker-machine, add $(docker-machine ip) notary-server).

You can run through the examples in the getting started docs and advanced usage docs, but without the -s (server URL) argument to the notary command since the server URL is specified already in the configuration, file you copied.

You can also leave off the -d ~/.docker/trust argument if you do not care to use notary with Docker images.

References -