Notary is a Docker project that allows anyone to have trust over arbitrary collections of data
Go Python Other
Latest commit 905fffb Jan 12, 2017 @ecordell ecordell Add ecordell as a maintainer
Signed-off-by: Evan Cordell <cordell.evan@gmail.com>
Permalink
Failed to load latest commit information.
buildscripts Include CGO disabling and trailing newline Jan 12, 2017
client Additional root rotation tests Jan 9, 2017
cmd Add test case to repro delegation import panic Jan 12, 2017
cryptoservice Do not use trailing punctuation in errors, also no caps where possible Nov 14, 2016
docs Update client-config.md Jan 11, 2017
fixtures fix formatting in fixture config json files Jan 11, 2017
hooks add newlines on build hooks so GH doesn't warn Oct 13, 2016
migrations switch deletion column in changefeed to a category column Nov 14, 2016
notarysql single db for postgres in dev/test mode Sep 22, 2016
passphrase Remove unused functions and aliases Oct 17, 2016
proto Remove unused proto code and cleanup the relative lines Aug 18, 2016
server Additional root rotation tests Jan 9, 2017
signer Additional root rotation tests Jan 9, 2017
storage minor refactoring: root key rotation Jan 9, 2017
trustmanager fixing Sha256 capitalization per Go rules on acronyms Nov 18, 2016
trustpinning fixing formatting in debugf Nov 18, 2016
tuf Additional root rotation tests Jan 9, 2017
utils Use Trim to only shorten the GUN if it contains a leading or trailing… Jan 12, 2017
vendor Vendor gorethink v3 Jan 6, 2017
version Lint fix Oct 19, 2015
.gitignore Speed up coverage calculations? :( Sep 17, 2016
CHANGELOG.md Update changelog with fix, tentative v0.4.3 release date Jan 12, 2017
CONTRIBUTING.md Use vndr instead of Godeps, as it has a cleaner version pinning file … Nov 14, 2016
CONTRIBUTORS updating maintainers and adding top level contributors, removing thos… Oct 28, 2015
Dockerfile Do not build the osx cross packages when running CI tests, since it t… Nov 14, 2016
Jenkinsfile Add docs checking Jenkinsfile Aug 22, 2016
LICENSE Update license to set copyright holder Jul 31, 2015
MAINTAINERS Add ecordell as a maintainer Jan 14, 2017
Makefile Include CGO disabling and trailing newline Jan 12, 2017
NOTARY_VERSION updating changelog for final release Nov 14, 2016
README.md Update changelog with changes for the next release, and update README… Oct 5, 2016
ROADMAP.md Refactored Rufus API Jul 14, 2015
circle.yml Try a simplified CircleCI with just Docker commands. May 25, 2016
codecov.yml Also ignore generated protobuf code for coverage Sep 17, 2016
const.go fixing Sha256 capitalization per Go rules on acronyms Nov 18, 2016
const_nowindows.go Do not support SIGUSR1 and SIGUSR2 syscall handling in windows Sep 22, 2016
const_windows.go Do not support SIGUSR1 and SIGUSR2 syscall handling in windows Sep 22, 2016
cross.Dockerfile Do not build the osx cross packages when running CI tests, since it t… Nov 14, 2016
development.mysql.yml single db for postgres in dev/test mode Sep 22, 2016
development.postgresql.yml single db for postgres in dev/test mode Sep 22, 2016
development.rethink.yml Convert integration test/development compose files to use new testcli… Aug 11, 2016
docker-compose.postgresql.yml single db for postgres in dev/test mode Sep 22, 2016
docker-compose.rethink.yml Bump rethink version due to vulnerabilites (see docker hub vulnerabil… Jun 9, 2016
docker-compose.yml single db for postgres in dev/test mode Sep 22, 2016
notary.go use an iota const for context key values Oct 4, 2016
server.Dockerfile Do not build the osx cross packages when running CI tests, since it t… Nov 14, 2016
server.minimal.Dockerfile custom autobuild script to create minimal build Oct 4, 2016
signer.Dockerfile Do not build the osx cross packages when running CI tests, since it t… Nov 14, 2016
signer.minimal.Dockerfile custom autobuild script to create minimal build Oct 4, 2016
vendor.conf Vendor gorethink v3 Jan 6, 2017

README.md

Notary

Circle CI CodeCov GoReportCard

The Notary project comprises a server and a client for running and interacting with trusted collections. Please see the service architecture documentation for more information.

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.

Security

Please see our service architecture docs for more information about our threat model, which details the varying survivability and severities for key compromise as well as mitigations.

Our last security audit was on July 31, 2015 by NCC (results).

Any security vulnerabilities can be reported to security@docker.com.

Getting started with the Notary CLI

Please get the Notary Client CLI binary from the official releases page or you can build one yourself. The version of Notary server and signer should be greater than or equal to Notary CLI's version to ensure feature compatibility (ex: CLI version 0.2, server/signer version >= 0.2), and all official releases are associated with GitHub tags.

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

For more advanced usage, please see the advanced usage docs.

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

  1. Please ensure that you have docker and docker-compose installed.
  2. git clone https://github.com/docker/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.

Building Notary

Note that our latest stable release is at the head of the releases branch. The master branch is the development branch and contains features for the next release.

Prerequisites:

  • Go >= 1.7.1
  • godep installed
  • libtool development headers installed
    • Ubuntu: apt-get install libltdl-dev
    • CentOS/RedHat: yum install libtool-ltdl-devel
    • Mac OS (Homebrew): brew install libtool

Run make client, which creates the Notary Client CLI binary at bin/notary. Note that make client assumes a standard Go directory structure, in which Notary is checked out to the src directory in your GOPATH. For example:

$GOPATH/
    src/
        github.com/
            docker/
                notary/

To build the server and signer, please run docker-compose build.