diff --git a/README.md b/README.md index 96cd5be5c6..61d1a715f1 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ -# Notary +# Notary [![Circle CI](https://circleci.com/gh/docker/notary/tree/master.svg?style=shield)](https://circleci.com/gh/docker/notary/tree/master) [![CodeCov](https://codecov.io/github/docker/notary/coverage.svg?branch=master)](https://codecov.io/github/docker/notary) The Notary project comprises a [server](cmd/notary-server) and a [client](cmd/notary) for running and interacting -with trusted collections. +with trusted collections. Please see the [service architecture](docs/service_architecture.md) documentation +for more information. Notary aims to make the internet more secure by making it easy for people to @@ -21,7 +22,7 @@ received content. ## Goals -Notary is based on [The Update Framework](http://theupdateframework.com/), a secure general design for the problem of software distribution and updates. By using TUF, notary achieves a number of key advantages: +Notary is based on [The Update Framework](https://www.theupdateframework.com/), 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. @@ -30,165 +31,59 @@ Notary is based on [The Update Framework](http://theupdateframework.com/), a sec * **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. -# Notary CLI +## Security -Notary is a tool for publishing and managing trusted collections of content. Publishers can digitally sign collections and consumers can verify integrity and origin of content. This ability is built on a straightforward key management and signing interface to create signed collections and configure trusted publishers. +Please see our [service architecture docs](docs/service_architecture.md#threat-model) for more information about our threat model, which details the varying survivability and severities for key compromise as well as mitigations. -## Using Notary -Lets try using notary. +Our last security audit was on July 31, 2015 by NCC ([results](docs/resources/ncc_docker_notary_audit_2015_07_31.pdf)). + +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](https://github.com/docker/notary/releases) or you can [build one yourself](#building-notary). + +To use the Notary CLI with Docker hub images, please have a look at our +[getting started docs](docs/getting_started.md). + +For more advanced usage, please see the +[advanced usage docs](docs/advanced_usage.md). + +To use the CLI against a local Notary server rather than against Docker Hub: + +1. Please ensure that you have [docker and docker-compose](http://docs.docker.com/compose/install/) installed. +1. `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: + + ```sh + $ docker-compose build + $ docker-compose up -d + $ mkdir -p ~/.notary && cp cmd/notary/config.json cmd/notary/root-ca.crt ~/.notary + ``` + +1. 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](docs/getting_started.md) and +[advanced usage docs](docs/advanced_usage.md), 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: -- Requirements from the [Compiling Notary Server](#compiling-notary-server) section (such as go 1.5.1) -- [docker and docker-compose](http://docs.docker.com/compose/install/) -- [Notary server configuration](#configuring-notary-server) - -As setup, let's build notary and then start up a local notary-server (don't forget to add `127.0.0.1 notary-server` to your `/etc/hosts`, or if using docker-machine, add `$(docker-machine ip) notary-server`). - -```sh -make binaries -docker-compose build -docker-compose up -d -``` - -Note: In order to have notary use the local notary server and development root CA we can load the local development configuration by appending `-c cmd/notary/config.json` to every command. If you would rather not have to use `-c` on every command, copy `cmd/notary/config.json and cmd/notary/root-ca.crt` to `~/.notary`. - - -First, let's initiate a notary collection called `example.com/scripts` - -```sh -notary init example.com/scripts -``` - -Now, look at the keys you created as a result of initialization -```sh -notary key list -``` - -Cool, now add a local file `install.sh` and call it `v1` -```sh -notary add example.com/scripts v1 install.sh -``` - -Wouldn't it be nice if others could know that you've signed this content? Use `publish` to publish your collection to your default notary-server -```sh -notary publish example.com/scripts -``` - -Now, others can pull your trusted collection -```sh -notary list example.com/scripts -``` - -More importantly, they can verify the content of your script by using `notary verify`: -```sh -curl example.com/install.sh | notary verify example.com/scripts v1 | sh -``` - -# Notary Server - -Notary Server manages TUF data over an HTTP API compatible with the -[notary client](cmd/notary). - -It may be configured to use either JWT or HTTP Basic Auth for authentication. -Currently it only supports MySQL for storage of the TUF data, we intend to -expand this to other storage options. - -## Setup for Development - -The notary repository comes with Dockerfiles and a docker-compose file -to facilitate development. Simply run the following commands to start -a notary server with a temporary MySQL database in containers: - -``` -$ docker-compose build -$ docker-compose up -``` - -If you are on Mac OSX with boot2docker or kitematic, you'll need to -update your hosts file such that the name `notary` is associated with -the IP address of your VM (for boot2docker, this can be determined -by running `boot2docker ip`, with kitematic, `echo $DOCKER_HOST` should -show the IP of the VM). If you are using the default Linux setup, -you need to add `127.0.0.1 notary` to your hosts file. - -## Successfully connecting over TLS - -By default notary-server runs with TLS with certificates signed by a local -CA. In order to be able to successfully connect to it using -either `curl` or `openssl`, you will have to use the root CA file in `fixtures/root-ca.crt`. - -OpenSSL example: - -`openssl s_client -connect notary-server:4443 -CAfile fixtures/root-ca.crt` - -## Compiling Notary Server - -Prerequisites: - -- Go = 1.5.1 +- Go >= 1.6 - [godep](https://github.com/tools/godep) installed - libtool development headers installed + - Ubuntu: `apt-get install libtool-dev` + - CentOS/RedHat: `yum install libtool-ltdl-devel` + - Mac OS ([Homebrew](http://brew.sh/)): `brew install libtool` -Install dependencies by running `godep restore`. - -From the root of this git repository, run `make binaries`. This will -compile the `notary`, `notary-server`, and `notary-signer` applications and -place them in a `bin` directory at the root of the git repository (the `bin` -directory is ignored by the .gitignore file). - -`notary-signer` depends upon `pkcs11`, which requires that libtool headers be installed (`libtool-dev` on Ubuntu, `libtool-ltdl-devel` on CentOS/RedHat). If you are using Mac OS, you can `brew install libtool`, and run `make binaries` with the following environment variables (assuming a standard installation of Homebrew): - -```sh -export CPATH=/usr/local/include:${CPATH} -export LIBRARY_PATH=/usr/local/lib:${LIBRARY_PATH} -``` - -## Running Notary Server - -The `notary-server` application has the following usage: - -``` -$ bin/notary-server --help -usage: bin/notary-serve - -config="": Path to configuration file - -debug=false: Enable the debugging server on localhost:8080 -``` - -## Configuring Notary Server - -The configuration file must be a json file with the following format: - -```json -{ - "server": { - "addr": ":4443", - "tls_cert_file": "./fixtures/notary-server.crt", - "tls_key_file": "./fixtures/notary-server.key" - }, - "logging": { - "level": 5 - } -} -``` - -The pem and key provided in fixtures are purely for local development and -testing. For production, you must create your own keypair and certificate, -either via the CA of your choice, or a self signed certificate. - -If using the pem and key provided in fixtures, either: -- Add `fixtures/root-ca.crt` to your trusted root certificates -- Use the default configuration for notary client that loads the CA root for you by using the flag `-c ./cmd/notary/config.json` -- Disable TLS verification by adding the following option notary configuration file in `~/.notary/config.json`: - - "skipTLSVerify": true - -Otherwise, you will see TLS errors or X509 errors upon initializing the -notary collection: - -``` -$ notary list diogomonica.com/openvpn -* fatal: Get https://notary-server:4443/v2/: x509: certificate signed by unknown authority -$ notary list diogomonica.com/openvpn -c cmd/notary/config.json -latest b1df2ad7cbc19f06f08b69b4bcd817649b509f3e5420cdd2245a85144288e26d 4056 -``` +Run `make binaries`, which creates the Notary Client CLI binary at `bin/notary`. diff --git a/docs/advanced_usage.md b/docs/advanced_usage.md index 48fd5f4b56..10a07bbe8e 100644 --- a/docs/advanced_usage.md +++ b/docs/advanced_usage.md @@ -102,14 +102,16 @@ The targets key must be locally managed - to rotate the targets key, for instanc ### Use a Yubikey -Notary can be used with [Yubikey -4](https://www.yubico.com/products/yubikey-hardware/yubikey4/) keys, via a PKCS11 interface when the Yubikey has CCID mode enabled. +Notary can be used with +Yubikey +4 keys, via a PKCS11 interface when the Yubikey has CCID mode enabled. The Yubikey will be prioritized to store root keys, and will require user touch-input for signing. >**Note**: Yubikey support for signing docker images is only supported in the experimental branch. -Yubikey support requires [Yubico PIV libraries (which are bundled with the PIV -tools)](https://www.yubico.com/support/downloads) to be available in standard +Yubikey support requires +Yubico PIV libraries +(which are bundled with the PIV tools) to be available in standard library locations. ## Work with delegation roles @@ -156,9 +158,9 @@ x509 cert `cert.pem` to the `targets/releases` delegation. For the `targets/releases` delegation role to sign content, the delegation user must possess the private key corresponding to this public key. This command restricts this delegation to only publish content under pathnames prefixed by -`delegation/path`. With the given path of "delegation/path", the `targets/releases` +`delegation/path`. With the given path of "delegation/path", the `targets/releases` role would be able to sign paths like "delegation/path/content.txt", "delegation/path_file.txt" -and "delegation/path.txt". You can add more paths in a comma-separated list under +and "delegation/path.txt". You can add more paths in a comma-separated list under `--paths`, or pass the `--all-paths` flag to allow this delegation to publish content under any pathname. @@ -172,9 +174,9 @@ $ notary delegation list example.com/collection targets/releases delegation/path 729c7094a8210fd1e780e7b17b7bb55c9a28a48b871b07f65d97baf93898523a 1 ``` -You can see the `targets/releases` with its paths and key IDs. If you wish to modify these fields, you can do so with additional `notary delegation add` or `notary delegation remove` commands on this role. +You can see the `targets/releases` with its paths and key IDs. If you wish to modify these fields, you can do so with additional `notary delegation add` or `notary delegation remove` commands on this role. -A threshold of `1` indicates that only one of the keys specified in `KEY IDS` is required to publish to this delegation. Thresholds other than 1 are not currently supported. To remove a delegation role entirely, or just individual keys and/or paths, use the `notary delegation remove` command: +A threshold of `1` indicates that only one of the keys specified in `KEY IDS` is required to publish to this delegation. Thresholds other than 1 are not currently supported. To remove a delegation role entirely, or just individual keys and/or paths, use the `notary delegation remove` command: ``` $ notary delegation remove example.com/user targets/releases @@ -193,7 +195,7 @@ delete the role entirely. To add targets to a specified delegation role, we can use the `notary add` command with the `--roles` flag. -You must have imported an appropriate delegation key for this role. To do so, +You must have imported an appropriate delegation key for this role. To do so, you can run `notary key import --role user` with the private key PEM file, or drop the private key PEM in `private/tuf_keys` as `.key` with the `role` PEM header set to `user`. @@ -209,7 +211,7 @@ role `targets/releases`. This target's path is valid because it is prefixed by the delegation role's valid path. The `notary list` and `notary remove` commands can also take the `--roles` flag -to specify roles to list or remove targets from. By default, this operates over +to specify roles to list or remove targets from. By default, this operates over the base `targets` role. To remove this target from our delegation, use the `notary remove` command with @@ -226,7 +228,7 @@ delegation as the canonical source of a trusted image tag, if it exists. When running `docker pull` with Docker Content Trust on Docker Engine 1.10, Docker will attempt to search the `targets/releases` role for the signed image tag, -and will fall back to the default `targets` role if it does not exist. Please note +and will fall back to the default `targets` role if it does not exist. Please note that when searching the default `targets` role, Docker 1.10 may pick up on other non-`targets/releases` delegation roles' signed images if they exist for this tag. In Docker 1.11, this behavior is changed such that all `docker pull` commands with @@ -235,7 +237,7 @@ or the `targets` base role. When running `docker push` with Docker Content Trust, Docker Engine 1.10 will attempt to sign and push with the `targets/releases` delegation role if it exists, -otherwise falling back to the `targets` role. In Docker 1.11, a `docker push` will +otherwise falling back to the `targets` role. In Docker 1.11, a `docker push` will instead attempt to sign and push with all delegation roles directly under targets (ex: `targets/role` but not `targets/nested/role`) that the user has signing keys for. If delegation roles exist but the user does not have signing keys, the push will fail. diff --git a/docs/changelog.md b/docs/changelog.md index 533480c164..cb23bf6d2e 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -13,16 +13,20 @@ weight=99 ## v0.2 #### 2/24/2016 -Adds support for [delegation roles](https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L387) in TUF. +Adds support for +delegation +roles in TUF. Delegations allow for easier key management amongst collaborators in a notary trusted collection, and fine-grained permissions on what content each delegate is allowed to modify and sign. This version also supports managing the snapshot key on notary server, which should be used when enabling delegations on a trusted collection. Moreover, this version also adds more key management functionality to the notary CLI, and changes the docker-compose development configuration to use the official MariaDB image. -> Detailed release notes can be found here: [v0.2 release notes](https://github.com/docker/notary/releases/tag/v0.2.0). +> Detailed release notes can be found here: +v0.2 release notes. ## v0.1 #### 11/15/2015 Initial notary non-alpha release. Implements The Update Framework (TUF) with root, targets, snapshot, and timestamp roles to sign and verify content of a trusted collection. -> Detailed release notes can be found here: [v0.1 release notes](https://github.com/docker/notary/releases/tag/v0.1). +> Detailed release notes can be found here: +v0.1 release notes. diff --git a/docs/getting_started.md b/docs/getting_started.md index 15f8c8cf9d..b3c434bd79 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -11,16 +11,30 @@ weight=1 # Getting started with Docker Notary -This document describes basic use of Notary as a tool supporting content trust. -For more advanced use cases, you must [run your own Notary +This document describes basic use of the Notary CLI as a tool supporting Docker +Content Trust. For more advanced use cases, you must [run your own Notary service](running_a_service.md) and should read the [use the Notary client for advanced users](advanced_usage.md) documentation. +## What is Notary + +Notary is a tool for publishing and managing trusted collections of content. +Publishers can digitally sign collections and consumers can verify integrity +and origin of content. This ability is built on a straightforward key management +and signing interface to create signed collections and configure trusted publishers. + +With Notary anyone can provide trust over arbitrary collections of data. Using +The Update Framework (TUF) +as the underlying security framework, Notary takes care of the operations necessary +to create, manage and distribute the metadata necessary to ensure the integrity and +freshness of your content. + ## Install Notary You can download precompiled notary binary for 64 bit Linux or Mac OS X from the -Notary repository's [releases page on -GitHub](https://github.com/docker/notary/releases). Windows is not officially +Notary repository's +releases page on +GitHub. Windows is not officially supported, but if you are a developer and Windows user, we would appreciate any insight you can provide regarding issues. @@ -84,7 +98,7 @@ Notary library (the same one as Notary CLI) to request the mapping of tag to sha256 digest for the one tag you are interested in (or if you passed the `--all` flag, the client will use the list operation to efficiently retrieve all the mappings). Having validated the signatures on the trust data, the client -will then instruct the Engine to do a "pull by digest". During this pull, the +will then instruct the Engine to do a "pull by digest". During this pull, the Engine uses the sha256 checksum as a content address to request and validate the image manifest from the Docker registry. @@ -111,7 +125,7 @@ You can see a pending change by running `notary status` for the modified repository. The `status` subcommand is an offline operation and as such, does not require the `-s` flag, however it will silently ignore the flag if provided. Failing to provide the correct value for the `-d` flag may show the wrong -(probably empty) change list: +(probably empty) change list: ``` $ notary -d ~/.docker/trust status docker.io/library/alpine diff --git a/docs/images/key-hierarchy.svg b/docs/images/key-hierarchy.svg new file mode 100644 index 0000000000..efdc9e6575 --- /dev/null +++ b/docs/images/key-hierarchy.svg @@ -0,0 +1,173 @@ + + + + + + + Delegation2 + + + + + Delegation1 + + + + + + + + Root + + + + + Timestamp + + + + + Snapshot + + + + + + + T + + + ar + + + gets + + + + + Delegation3 + + + + + + + Delegation4 + + + + + Delegation5 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/reference/common-configs.md b/docs/reference/common-configs.md index 04f1d6692a..8acc485d43 100644 --- a/docs/reference/common-configs.md +++ b/docs/reference/common-configs.md @@ -54,9 +54,9 @@ below to configure it. The reporting section contains any configuration for useful for running the service, such as reporting errors. Currently, Notary only supports reporting errors -to [Bugsnag](https://bugsnag.com). +to Bugsnag. -See [bugsnag-go](https://github.com/bugsnag/bugsnag-go/) for more information +See bugsnag-go for more information about these configuration parameters. ```json diff --git a/docs/reference/server-config.md b/docs/reference/server-config.md index 848b472ce1..c527248e24 100644 --- a/docs/reference/server-config.md +++ b/docs/reference/server-config.md @@ -267,7 +267,7 @@ configure it. **Token authentication:** This is an implementation of the same authentication used by version 2 of the -[Docker registry](https://github.com/docker/distribution). (JWT token-based +Docker registry. (JWT token-based authentication post login.) diff --git a/docs/resources/ncc_docker_notary_audit_2015_07_31.pdf b/docs/resources/ncc_docker_notary_audit_2015_07_31.pdf new file mode 100644 index 0000000000..725a4a4587 Binary files /dev/null and b/docs/resources/ncc_docker_notary_audit_2015_07_31.pdf differ diff --git a/docs/running_a_service.md b/docs/running_a_service.md index e3fa761b7f..f9e0961d50 100644 --- a/docs/running_a_service.md +++ b/docs/running_a_service.md @@ -21,7 +21,7 @@ and [Docker Compose](https://docs.docker.com/compose/overview/). The quickest way to spin up a full Notary service for testing and development purposes is to use the Docker compose file in the -[Notary project](https://github.com/docker/notary). +Notary project. ```plain $ git clone https://github.com/docker/notary.git @@ -75,9 +75,9 @@ the following command line arguments: - `-config=` - specify the path to the JSON configuration file. - `-debug` - Passing this flag enables the debugging server on `localhost:8080`. - The debugging server provides [pprof](https://golang.org/pkg/net/http/pprof/) - and [expvar](https://golang.org/pkg/expvar/) endpoints. (Remember, this - is localhost with respect to the running container - this endpoint is not + The debugging server provides pprof + and expvar endpoints. + (Remember, this is localhost with respect to the running container - this endpoint is not exposed from the container). This option can also be set in the configuration file. diff --git a/docs/service_architecture.md b/docs/service_architecture.md index 40c3ca2a67..3a9edd5dec 100644 --- a/docs/service_architecture.md +++ b/docs/service_architecture.md @@ -12,15 +12,67 @@ weight=3 # Understand the Notary service architecture -On this page, you get an overview of the Notary service architecture. This -document assumes a prior understanding of [The Update -Framework](https://theupdateframework.github.io/). +On this page, you get an overview of the Notary service architecture. + +## Brief overview of TUF keys and roles + +This document assumes familiarity with +The Update Framework, +but here is a brief recap of the TUF roles and corresponding key hierarchy: + +
TUF Key Hierarchy
+ +- The root key is the root of all trust. It signs the + root metadata file, + which lists the IDs of the root, targets, snapshot, and timestamp public keys. + Clients use these public keys to verify the signatures on all the metadata files + in the repository. This key is held by a collection owner, and should be kept offline + and safe, more so than any other key. + +- The snapshot key signs the + snapshot metadata file, + which enumerates the filenames, sizes, and hashes of the root, + targets, and delegation metadata files for the collection. This file is used to + verify the integrity of the other metadata files. The snapshot key is held by + either a collection owner/administrator, or held by the Notary service to facilitate + [signing by multiple collaborators via delegation roles](advanced_usage.md#working-with-delegation-roles). + +- The timestamp key signs the + timestamp metadata file, + which provides freshness guarantees for the collection by having the shortest expiry time of any particular + piece of metadata and by specifying the filename, size, and hash of the most recent + snapshot for the collection. It is used to verify the integrity of the snapshot + file. The timestamp key is held by the Notary service so the timestamp can be + automatically re-generated when it is requested from the server, rather than + require that a collection owner come online before each timestamp expiry. + +- The targets key signs the + targets metadata file, + which lists filenames in the collection, and their sizes and respective + hashes. + This file is used to verify the integrity of some or all of the actual contents of the repository. + It is also used to + [delegate trust to other collaborators via delegation roles](advanced_usage.md#working-with-delegation-roles). + The targets key is held by the collection owner or administrator. + +- Delegation keys sign + delegation metadata files, + which lists filenames in the collection, and their sizes and respective + hashes. + These files is used to verify the integrity of some or all of the actual contents of the repository. + They are is also used to [delegate trust to other collaborators via lower level delegation roles]( + advanced_usage.md#working-with-delegation-roles). + Delegation keys are held by anyone from the collection owner or administrator to + collection collaborators. ## Architecture and components +Notary clients pull metadata from one or more (remote) Notary services. Some +Notary clients will push metadata to one or more Notary services. + A Notary service consists of a Notary server, which stores and updates the -signed [TUF metadata files]( -https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L348) +signed +TUF metadata files for multiple trusted collections in an associated database, and a Notary signer, which stores private keys for and signs metadata for the Notary server. The following diagram illustrates this architecture: @@ -38,24 +90,21 @@ responsible for: The Notary signer is responsible for: - storing the private signing keys -[wrapped]( -https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31#section-4.4) -and [encrypted]( -https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31#section-4.8) -using [Javascript Object Signing and Encryption]( -https://github.com/dvsekhvalnov/jose2go) in a database separate from the -Notary server database + wrapped + and encrypted + using Javascript Object Signing and Encryption in a database separate from the + Notary server database - performing signing operations with these keys whenever the Notary server requests ## Example client-server-signer interaction The following diagram illustrates the interactions between the Notary client, -sever, and signer: +server, and signer: ![Notary Service Sequence Diagram](images/metadata-sequence.svg) 1. Notary server optionally supports authentication from clients using - [JWT](http://jwt.io/) tokens. This requires an authorization server that + JWT tokens. This requires an authorization server that manages access controls, and a cert bundle from this authorization server containing the public key it uses to sign tokens. @@ -103,7 +152,9 @@ sever, and signer: ## Threat model -Both the server and the signer are potential attack vectors. This section +Both the server and the signer are potential attack vectors against all users +of the Notary service. Client keys are also a potential attack vector, but +not necessarily against all collections at a time. This section discusses how our architecture is designed to deal with compromises. ### Notary server compromise @@ -133,7 +184,7 @@ operations with any key the Signer holds. - **Rollback, Freeze, Mix and Match** - The attacker can request that the Notary signer sign any arbitrary timestamp (and maybe snapshot) metadata - they want. Attackers can lauch a freeze attack, and, depending on whether + they want. Attackers can launch a freeze attack, and, depending on whether the snapshot key is available, a mix-and-match attack up to the expiration of the targets file. @@ -143,7 +194,7 @@ operations with any key the Signer holds. good metadata that any client may have. Note that the timestamp and snapshot keys cannot be compromised in a server-only - compromise, so a key rotation would not be necessary. Once the Server + compromise, so a key rotation would not be necessary. Once the Server compromise is mitigated, an attacker will not be able to generate valid timestamp or snapshot metadata and serve them on a malicious mirror, for example. @@ -151,9 +202,10 @@ operations with any key the Signer holds. ### Notary signer compromise In the event of a Notary signer compromise, an attacker would have access to -all the private keys stored in a database. If the keys are stored in an HSM, -they would have the ability to sign arbitrary content with, and to delete, the -keys in the HSM, but not to exfiltrate the private material. +all the (timestamp and snapshot) private keys stored in a database. +If the keys are stored in an HSM, they would have the ability to sign arbitrary +content with, and to delete, the keys in the HSM, but not to exfiltrate the +private material. - **Denial of Service** - An attacker could reject all Notary server requests and corrupt or delete keys from the database (or even delete keys from an @@ -161,10 +213,166 @@ keys in the HSM, but not to exfiltrate the private material. timestamps or snapshots. - **Key Compromise** - If the Notary signer uses a database as its backend, - an attacker can exfiltrate all the private material. Note that the capabilities - of an attacker are the same as of a Notary server compromise in terms of - signing arbitrary metadata, with the important detail that in this particular - case key rotations will be necessary to recover from the attack. + an attacker can exfiltrate all the (timestamp and snapshot) private material. + Note that the capabilities of an attacker are the same as of a Notary server + compromise in terms of signing arbitrary metadata, with the important detail + that in this particular case key rotations will be necessary to recover from + the attack. + +### Notary client keys and credentials compromise + +The security of keys held and administered by users depends on measures taken by +the users. If the Notary Client CLI was used to create them, then they are password +protected and the Notary CLI does not provide options to export them in +plaintext. + +It is up to the user to choose an appropriate password, and to protect their key +from offline brute-force attacks. + +The severity of the compromise of a trust collection owner/administrator's +decrypted key depends on the type and combination of keys that were compromised +(e.g. the snapshot key and targets key, or just the targets key). + +#### Possible attacks given the credentials compromised: + +- **Decrypted Delegation Key, only** + + | Keys compromised | Malicious Content | Rollback, Freeze, Mix and Match | Denial of Service | + |------------------|-------------------|---------------------------------|-------------------| + | Delegation key | no | no | no | + +- **Decrypted Delegation Key + Notary Service write-capable credentials** + + | Keys compromised | Malicious Content | Rollback, Freeze, Mix and Match | Denial of Service | + |------------------|-------------------|---------------------------------|-------------------| + | Delegation key | limited, maybe* | limited, maybe* | limited, maybe* | + + *If the Notary Service holds the snapshot key and the attacker has Notary Service + write credentials, then they have effective access to the snapshot and timestamp + keys because the server will generate and sign the snapshot and timestamp for them. + + An attacker can add malicious content, remove legitimate content from a collection, and + mix up the targets in a collection, but only within the particular delegation + roles that the key can sign for. Depending on the restrictions on that role, + they may be restricted in what type of content they can modify. They may also + add or remove the capabilities of other delegation keys below it on the key hierarchy + (e.g. if `DelegationKey2` in the above key hierarchy were compromised, it would only be + able to modify the capabilities of `DelegationKey4` and `DelegationKey5`). + +- **Decrypted Delegation Key + Decrypted Snapshot Key, only** + + | Keys compromised | Malicious Content | Rollback, Freeze, Mix and Match | Denial of Service | + |------------------|-------------------|---------------------------------|-------------------| + | Delegation key
Snapshot key | no | no | no | + + The attacker does not have access to the timestamp key, which is always held by the Notary + Service, and will be unable to set up a malicious mirror. + +- **Decrypted Delegation Key + Decrypted Snapshot Key + Notary Service write-capable credentials** + + | Keys compromised | Malicious Content | Rollback, Freeze, Mix and Match | Denial of Service | + |------------------|-------------------|---------------------------------|-------------------| + | Delegation key
Snapshot key | limited | limited | limited | + + The Notary Service always holds the timestamp key. If the attacker has Notary Service + write credentials, then they have effective access to the timestamp key because the server + will generate and sign the timestamp for them. + + An attacker can add malicious content, remove legitimate content from a collection, and + mix up the targets in a collection, but only within the particular delegation + roles that the key can sign for. Depending on the restrictions on that role, + they may be restricted in what type of content they can modify. They may also + add or remove the capabilities of other delegation keys below it on the key hierarchy + (e.g. if `DelegationKey2` in the above key hierarchy were compromised, it would only be + able to modify the capabilities of `DelegationKey4` and `DelegationKey5`). + +- **Decrypted Targets Key, only** + + | Keys compromised | Malicious Content | Rollback, Freeze, Mix and Match | Denial of Service | + |------------------|-------------------|---------------------------------|-------------------| + | Targets key | no | no | no | + +- **Decrypted Targets Key + Notary Service write-capable credentials** + + | Keys compromised | Malicious Content | Rollback, Freeze, Mix and Match | Denial of Service | + |------------------|-------------------|---------------------------------|-------------------| + | Targets key | maybe* | maybe* | limited, maybe* | + + *If the Notary Service holds the snapshot key and the attacker has Notary Service + write credentials, then they have effective access to the snapshot and timestamp + keys because the server will generate and sign the snapshot and timestamp for them. + + An attacker can add any malicious content, remove any legitimate content from a + collection, and mix up the targets in a collection. They may also add or remove + the capabilities of any top level delegation key or role (e.g. `Delegation1`, + `Delegation2`, and `Delegation3` in the key hierarchy diagram). If they remove + the roles entirely, they'd break the trust chain to the lower delegation roles + (e.g. `Delegation4`, `Delegation5`). + +- **Decrypted Targets Key + Decrypted Snapshot Key, only** + + | Keys compromised | Malicious Content | Rollback, Freeze, Mix and Match | Denial of Service | + |------------------|-------------------|---------------------------------|-------------------| + | Targets key
Snapshot key | no | no | no | + + The attacker does not have access to the timestamp key, which is always held by the Notary + Service, and will be unable to set up a malicious mirror. + +- **Decrypted Targets Key + Decrypted Snapshot Key + Notary Service write-capable credentials** + + | Keys compromised | Malicious Content | Rollback, Freeze, Mix and Match | Denial of Service | + |------------------|-------------------|---------------------------------|-------------------| + | Targets key
Snapshot key | yes | yes | limited | + + The Notary Service always holds the timestamp key. If the attacker has Notary Service + write credentials, then they have effective access to the timestamp key because the server + will generate and sign the timestamp for them. + + An attacker can add any malicious content, remove any legitimate content from a + collection, and mix up the targets in a collection. They may also add or remove + the capabilities of any top level delegation key or role (e.g. `Delegation1`, + `Delegation2`, and `Delegation3` in the key hierarchy diagram). If they remove + the roles entirely, they'd break the trust chain to the lower delegation roles + (e.g. `Delegation4`, `Delegation5`). + +- **Decrypted Root Key + none or any combination of decrypted keys, only** + + | Keys compromised | Malicious Content | Rollback, Freeze, Mix and Match | Denial of Service | + |------------------|-------------------|---------------------------------|-------------------| + | All keys | yes | yes | yes | + + No other keys are needed, since the attacker can just any rotate or all of them to ones that they + generate. With these keys, they can set up a mirror to serve malicious data - any malicious data + at all, given that they have acess to all the keys. + +- **Decrypted Root Key + none or any combination of decrypted keys + Notary Service write-capable credentials** + + | Keys compromised | Malicious Content | Rollback, Freeze, Mix and Match | Denial of Service | + |------------------|-------------------|---------------------------------|-------------------| + | All keys | yes | yes | yes | + + *If the Notary Service holds the snapshot key and the attacker has Notary Service + write credentials, then they won't even have to rotate the snapshot and timestamp + keys because the server will generate and sign the snapshot and timestamp for them. + +#### Mitigations + +If a root key compromise is detected, the root key holder should contact +whomever runs the notary service to manually reverse any malicious changes to +the repository, and immediately rotate the root key. This will create a fork +of the repository history, and thus break existing clients who have downloaded +any of the malicious changes. + +If a targets key compromise is detected, the root key holder +must rotate the compromised key and push a clean set of targets using the new key. + +If a delegations key compromise is detected, a higher level key (e.g. if +`Delegation4` were compromised, then `Delegation2`; if +`Delegation2` were compromised, then the `Targets` key) +holder must rotate the compromised key, and push a clean set of targets using the new key. + +If a Notary Service credential compromise is detected, the credentials should be +changed immediately. ## Related information