34aa149cbc
Repo.RotateBaseKeys() can now be used to replace the root keypair (i.e. primarily the expiring certificate), and Repo.SignRoot will make signatures using the old keypairs if they are available (but not fail if they are not; only the keypairs listed in the role as trusted are mandatory). To do this, we need to keep even the old, possibly currently untrusted, keypairs around (to allow rollover from clients which trust these old keys): The private keys are simply not deleted from the repo's CryptoService; this means no change for the current setup with a long-term private key and periodically expiring certificates, but a true rotation of the private key will eventually require explicit management of the preserved long-term private keys (if we are keeping several of them around, but most are either obsolete and non-preferred or possibly even known to be compromised, we will want to make sure that we always use the new/preferred private key for new certificate generation). The public keys are tricker: 1) We need to keep a list of them; the private keys can be looked up by their IDs, and that allows extracting the public part as well, but we need a list of the key IDs. We can't just keep the key IDs included in the role's list of authorized keys, that would make it impossible to rotate away from a suspect or known compromsied key. 2) With the X.509 certificate “public keys”, key ID is not actually sufficient to retrieve the full public key even if we have access to the private key; we actually need to store the full public key == certificate somewhere. And preferably without having tuf.Repo depend on a certs.Manager, designed to deal with concepts of trust at a higher level than TUF cares about. Actually, to the extent certs.Manager's purpose is to manage and verify trust, storing old, possibly suspect or known compromised certificates would be explicitly contrary to its mission. So, this patch keeps around full copies of the certificates in the root.json “keys” map (not the “roles” map of trusted keys). It means sending to clients a little data which they don't need but it is otherwise harmless; and keeping the certificates within the structured and managed tuf.data.Root format could allow us to build nice UI (e.g. show me all certificates we still carry and keep signing with, let me drop two of them now that our company has changed a name and does not want to advertise the history) if we ever needed to something like this Signed-off-by: Ying Li <ying.li@docker.com> |
||
|---|---|---|
| Godeps | ||
| buildscripts | ||
| certs | ||
| client | ||
| cmd | ||
| cryptoservice | ||
| docs | ||
| fixtures | ||
| migrations | ||
| misc | ||
| notarymysql/docker-entrypoint-initdb.d | ||
| passphrase | ||
| proto | ||
| server | ||
| signer | ||
| trustmanager | ||
| tuf | ||
| utils | ||
| vendor | ||
| version | ||
| .gitignore | ||
| CHANGELOG.md | ||
| CONTRIBUTING.md | ||
| CONTRIBUTORS | ||
| Dockerfile | ||
| LICENSE | ||
| MAINTAINERS | ||
| Makefile | ||
| NOTARY_VERSION | ||
| README.md | ||
| ROADMAP.md | ||
| circle.yml | ||
| const.go | ||
| coverpkg.sh | ||
| development.yml | ||
| docker-compose.yml | ||
| server.Dockerfile | ||
| signer.Dockerfile | ||
README.md
Notary
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.
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:
-
Please ensure that you have docker and docker-compose installed.
-
git clone https://github.com/docker/notary.gitand 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 -
Add
127.0.0.1 notary-serverto 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
Prerequisites:
- Go >= 1.6
- godep installed
- libtool development headers installed
- Ubuntu:
apt-get install libtool-dev - CentOS/RedHat:
yum install libtool-ltdl-devel - Mac OS (Homebrew):
brew install libtool
- Ubuntu:
Run make binaries, which creates the Notary Client CLI binary at bin/notary.