docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #652 from docker/docs-update 

Include docs about what happens if a client's keys get compromised
This commit is contained in:
Ying Li 2016-04-06 00:23:32 -07:00
parent 6e84b596ca b623214737
commit 819499d6d7
10 changed files with 505 additions and 209 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

207
README.md
View File

@ -2,7 +2,8 @@
[![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) [![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 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 Notary aims to make the internet more secure by making it easy for people to
@ -21,7 +22,7 @@ received content.
## Goals ## 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. * **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. * **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. * **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. * **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 Our last security audit was on July 31, 2015 by NCC ([results](docs/resources/ncc_docker_notary_audit_2015_07_31.pdf)).
Lets try using notary.
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: Prerequisites:
- Requirements from the [Compiling Notary Server](#compiling-notary-server) section (such as go 1.5.1) - Go >= 1.6
- [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
- [godep](https://github.com/tools/godep) installed - [godep](https://github.com/tools/godep) installed
- libtool development headers 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`. Run `make binaries`, which creates the Notary Client CLI binary at `bin/notary`.
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
```

26
docs/advanced_usage.md
View File

@ -102,14 +102,16 @@ The targets key must be locally managed - to rotate the targets key, for instanc
### Use a Yubikey ### Use a Yubikey
Notary can be used with [Yubikey Notary can be used with
4](https://www.yubico.com/products/yubikey-hardware/yubikey4/) keys, via a PKCS11 interface when the Yubikey has CCID mode enabled. <a href="https://www.yubico.com/products/yubikey-hardware/yubikey4/" target="_blank">Yubikey
4</a> 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. 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. >**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 Yubikey support requires
tools)](https://www.yubico.com/support/downloads) to be available in standard <a href="https://www.yubico.com/support/downloads" target="_blank">Yubico PIV libraries
(which are bundled with the PIV tools)</a> to be available in standard
library locations. library locations.
## Work with delegation roles ## 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 For the `targets/releases` delegation role to sign content, the delegation user
must possess the private key corresponding to this public key. This command must possess the private key corresponding to this public key. This command
restricts this delegation to only publish content under pathnames prefixed by 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" 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 `--paths`, or pass the `--all-paths` flag to allow this delegation to publish
content under any pathname. content under any pathname.
@ -172,9 +174,9 @@ $ notary delegation list example.com/collection
targets/releases delegation/path 729c7094a8210fd1e780e7b17b7bb55c9a28a48b871b07f65d97baf93898523a 1 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 $ 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` To add targets to a specified delegation role, we can use the `notary add`
command with the `--roles` flag. 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 <KEY_FILE> --role user` with the private key PEM you can run `notary key import <KEY_FILE> --role user` with the private key PEM
file, or drop the private key PEM in `private/tuf_keys` as `<KEY_ID>.key` with file, or drop the private key PEM in `private/tuf_keys` as `<KEY_ID>.key` with
the `role` PEM header set to `user`. 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 delegation role's valid path.
The `notary list` and `notary remove` commands can also take the `--roles` flag 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. the base `targets` role.
To remove this target from our delegation, use the `notary remove` command with 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, 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, 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 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. 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 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 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, 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 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. (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. If delegation roles exist but the user does not have signing keys, the push will fail.

10
docs/changelog.md
View File

@ -13,16 +13,20 @@ weight=99
## v0.2 ## v0.2
#### 2/24/2016 #### 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
<a href="https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L387" target="_blank">delegation
roles</a> 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. 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. 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. 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:
<a href="https://github.com/docker/notary/releases/tag/v0.2.0" target="_blank">v0.2 release notes</a>.
## v0.1 ## v0.1
#### 11/15/2015 #### 11/15/2015
Initial notary non-alpha release. 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. 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:
<a href="https://github.com/docker/notary/releases/tag/v0.1" target="_blank">v0.1 release notes</a>.

24
docs/getting_started.md
View File

@ -11,16 +11,30 @@ weight=1
# Getting started with Docker Notary # Getting started with Docker Notary
This document describes basic use of Notary as a tool supporting content trust. This document describes basic use of the Notary CLI as a tool supporting Docker
For more advanced use cases, you must [run your own Notary 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 service](running_a_service.md) and should read the [use the Notary client for
advanced users](advanced_usage.md) documentation. 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
<a href="https://www.theupdateframework.com/" target="_blank">The Update Framework (TUF)</a>
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 ## Install Notary
You can download precompiled notary binary for 64 bit Linux or Mac OS X from the You can download precompiled notary binary for 64 bit Linux or Mac OS X from the
Notary repository's [releases page on Notary repository's
GitHub](https://github.com/docker/notary/releases). Windows is not officially <a href="https://github.com/docker/notary/releases" target="_blank">releases page on
GitHub</a>. Windows is not officially
supported, but if you are a developer and Windows user, we would appreciate any supported, but if you are a developer and Windows user, we would appreciate any
insight you can provide regarding issues. 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 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 `--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 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 Engine uses the sha256 checksum as a content address to request and validate the
image manifest from the Docker registry. image manifest from the Docker registry.

173
docs/images/key-hierarchy.svg Normal file
View File

@ -0,0 +1,173 @@
<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="100%" height="100%" viewBox="0 0 460 410" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:1.41421;">
<g transform="matrix(1,0,0,1,-174.938,-212.9)">
<g transform="matrix(1,0,0,1,411.87,472.914)">
<g>
<text x="0px" y="0px" style="font-family:'HelveticaNeue-Medium';font-size:16px;fill:black;">Delegation2</text>
</g>
</g>
<g transform="matrix(1,0,0,1,298.419,472.914)">
<g>
<text x="0px" y="0px" style="font-family:'HelveticaNeue-Medium';font-size:16px;fill:black;">Delegation1</text>
</g>
</g>
<path d="M345.466,282.138L345.466,306.444L234,306.444L234,320.85" style="fill:none;stroke-width:1px;stroke:black;"/>
<path d="M345.466,282.138L345.466,320.85" style="fill:none;stroke-width:1px;stroke:black;"/>
<path d="M345.466,282.138L345.466,306.444L456.931,306.444L456.931,320.85" style="fill:none;stroke-width:1px;stroke:black;"/>
<g transform="matrix(1,0,0,1,324.878,248.776)">
<g>
<text x="0px" y="0px" style="font-family:'HelveticaNeue-Medium';font-size:16px;fill:black;">Root</text>
</g>
</g>
<g transform="matrix(1,0,0,1,194.128,375.664)">
<g>
<text x="0px" y="0px" style="font-family:'HelveticaNeue-Medium';font-size:16px;fill:black;">Timestamp</text>
</g>
</g>
<g transform="matrix(1,0,0,1,311.234,375.664)">
<g>
<text x="0px" y="0px" style="font-family:'HelveticaNeue-Medium';font-size:16px;fill:black;">Snapshot</text>
</g>
</g>
<path d="M453.938,384.888L453.938,408.262L398.262,408.262L341.091,408.262L341.091,421.475" style="fill:none;stroke-width:1px;stroke:black;"/>
<path d="M453.938,384.888L453.938,408.344L567.994,408.344L567.994,421.475" style="fill:none;stroke-width:1px;stroke:black;"/>
<g transform="matrix(1,0,0,1,427.938,360.664)">
<g transform="matrix(1,0,0,1,0.152,15)">
<text x="0px" y="0px" style="font-family:'HelveticaNeue-Medium';font-size:16px;fill:black;">T</text>
</g>
<g transform="matrix(1,0,0,1,7.56,15)">
<text x="0px" y="0px" style="font-family:'HelveticaNeue-Medium';font-size:16px;fill:black;">ar</text>
</g>
<g transform="matrix(1,0,0,1,21.032,15)">
<text x="0px" y="0px" style="font-family:'HelveticaNeue-Medium';font-size:16px;fill:black;">gets</text>
</g>
</g>
<g transform="matrix(1,0,0,1,525.322,472.914)">
<g>
<text x="0px" y="0px" style="font-family:'HelveticaNeue-Medium';font-size:16px;fill:black;">Delegation3</text>
</g>
</g>
<path d="M454.542,482.138L454.542,509.063L512.48,509.063L512.48,523.85" style="fill:none;stroke-width:1px;stroke:black;"/>
<path d="M454.542,482.138L454.542,508.895L424.75,508.895L396.605,508.895L396.605,523.85" style="fill:none;stroke-width:1px;stroke:black;"/>
<g transform="matrix(1,0,0,1,353.933,578.664)">
<g>
<text x="0px" y="0px" style="font-family:'HelveticaNeue-Medium';font-size:16px;fill:black;">Delegation4</text>
</g>
</g>
<g transform="matrix(1,0,0,1,469.808,578.664)">
<g>
<text x="0px" y="0px" style="font-family:'HelveticaNeue-Medium';font-size:16px;fill:black;">Delegation5</text>
</g>
</g>
<path d="M453.938,386.789L453.938,398.689L454.24,421.066L454.245,421.476" style="fill:none;stroke-width:1px;stroke:black;"/>
<path d="M534.008,544.854L534.008,547.467L532.231,550.77L532.231,548.154L534.008,544.854Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M533.008,547.391L532.231,550.77L511.864,551.052L511.445,548.266L533.008,547.391Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M511.861,548.447L511.861,551.06C511.815,551.207 511.231,552.354 510.883,552.984L510.633,549.766C510.981,549.134 511.815,548.593 511.861,548.447Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M511.864,548.438L511.864,551.052L511.861,551.06L511.861,548.447L511.864,548.438Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M511.864,548.438L511.864,551.052C511.82,551.189 511.606,551.685 511.24,552.343L511.24,549.73C511.606,549.07 511.82,548.576 511.864,548.438Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M511.633,548.953L511.289,552.218C511.014,552.718 510.365,553.725 509.977,554.171L510.008,551.453C510.397,551.002 511.42,549.391 511.633,548.953Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M511.445,549.328L511.24,552.343C510.94,552.927 510.504,553.537 510.055,554.046L510.125,551.391C510.574,550.879 511.144,549.908 511.445,549.328Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M510.336,551.031L510.195,553.891C509.787,554.402 509.228,555.013 508.661,555.459L508.133,552.641C508.702,552.199 509.928,551.559 510.336,551.031Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M510.211,551.046L510.125,554.004C509.717,554.516 509.186,555.039 508.618,555.484L508.336,552.843C508.904,552.402 509.803,551.559 510.211,551.046Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M509.133,552.016C507.123,553.65 504.227,555.275 501.811,555.275C499.066,555.275 496.342,554.244 494.268,552.25C493.971,551.971 493.684,551.66 493.412,551.336C491.758,549.328 490.952,546.914 490.952,544.513L490.952,547.127C490.952,549.527 491.758,551.945 493.412,553.949C493.684,554.275 493.971,554.582 494.268,554.865C496.342,556.861 499.066,557.888 501.811,557.888C504.227,557.888 506.651,557.092 508.661,555.459L509.133,552.016Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M490.952,547.127L490.952,544.513C490.952,546.914 491.758,549.328 493.412,551.336C493.684,551.66 493.971,551.971 494.268,552.25C496.342,554.244 499.066,555.275 501.811,555.275C504.227,555.275 506.651,554.476 508.661,552.842L508.661,555.459C506.651,557.092 504.227,557.888 501.811,557.888C499.066,557.888 496.342,556.861 494.268,554.865C493.971,554.582 493.684,554.275 493.412,553.949C491.758,551.945 490.952,549.527 490.952,547.127Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M497.037,547.171C498.614,547.158 499.864,545.863 499.846,544.314C499.82,542.759 498.545,541.521 496.981,541.521C496.973,541.521 496.965,541.521 496.955,541.525C495.397,541.55 494.131,542.83 494.161,544.394C494.172,545.927 495.434,547.171 496.989,547.171C497.004,547.171 497.022,547.171 497.037,547.171M530.082,541.189L534.008,544.854L532.231,548.154L511.864,548.438C511.82,548.576 511.606,549.07 511.24,549.73C510.94,550.31 510.574,550.879 510.125,551.391C509.717,551.902 509.228,552.4 508.661,552.842C506.651,554.476 504.227,555.275 501.811,555.275C499.066,555.275 496.342,554.244 494.268,552.25C493.971,551.971 493.684,551.66 493.412,551.336C489.611,546.726 490.291,539.947 494.934,536.188C496.945,534.546 499.375,533.75 501.793,533.75C504.221,533.75 506.633,534.552 508.594,536.123C510.073,537.211 511.028,538.785 511.077,538.871L512.215,538.924L517.186,538.855L518.936,541.904L523.147,541.509L524.762,543.168L526.24,543.49L530.082,541.189" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M418.133,544.854L418.133,547.467L416.356,550.77L416.356,548.154L418.133,544.854Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M417.133,547.391L416.356,550.77L395.989,551.052L395.57,548.266L417.133,547.391Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M395.986,548.447L395.986,551.06C395.94,551.207 395.356,552.354 395.008,552.984L394.758,549.766C395.106,549.134 395.94,548.593 395.986,548.447Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M395.989,548.438L395.989,551.052L395.986,551.06L395.986,548.447L395.989,548.438Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M395.989,548.438L395.989,551.052C395.945,551.189 395.731,551.685 395.365,552.343L395.365,549.73C395.731,549.07 395.945,548.576 395.989,548.438Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M395.758,548.953L395.414,552.218C395.139,552.718 394.49,553.725 394.102,554.171L394.133,551.453C394.522,551.002 395.545,549.391 395.758,548.953Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M395.57,549.328L395.365,552.343C395.065,552.927 394.629,553.537 394.18,554.046L394.25,551.391C394.699,550.879 395.269,549.908 395.57,549.328Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M394.461,551.031L394.32,553.891C393.912,554.402 393.353,555.013 392.786,555.459L392.258,552.641C392.827,552.199 394.053,551.559 394.461,551.031Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M394.336,551.046L394.25,554.004C393.842,554.516 393.311,555.039 392.743,555.484L392.461,552.843C393.029,552.402 393.928,551.559 394.336,551.046Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M393.258,552.016C391.248,553.65 388.352,555.275 385.936,555.275C383.191,555.275 380.467,554.244 378.393,552.25C378.096,551.971 377.809,551.66 377.537,551.336C375.883,549.328 375.077,546.914 375.077,544.513L375.077,547.127C375.077,549.527 375.883,551.945 377.537,553.949C377.809,554.275 378.096,554.582 378.393,554.865C380.467,556.861 383.191,557.888 385.936,557.888C388.352,557.888 390.776,557.092 392.786,555.459L393.258,552.016Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M375.077,547.127L375.077,544.513C375.077,546.914 375.883,549.328 377.537,551.336C377.809,551.66 378.096,551.971 378.393,552.25C380.467,554.244 383.191,555.275 385.936,555.275C388.352,555.275 390.776,554.476 392.786,552.842L392.786,555.459C390.776,557.092 388.352,557.888 385.936,557.888C383.191,557.888 380.467,556.861 378.393,554.865C378.096,554.582 377.809,554.275 377.537,553.949C375.883,551.945 375.077,549.527 375.077,547.127Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M381.162,547.171C382.739,547.158 383.989,545.863 383.971,544.314C383.945,542.759 382.67,541.521 381.106,541.521C381.098,541.521 381.09,541.521 381.08,541.525C379.522,541.55 378.256,542.83 378.286,544.394C378.297,545.927 379.559,547.171 381.114,547.171C381.129,547.171 381.147,547.171 381.162,547.171M414.207,541.189L418.133,544.854L416.356,548.154L395.989,548.438C395.945,548.576 395.731,549.07 395.365,549.73C395.065,550.31 394.699,550.879 394.25,551.391C393.842,551.902 393.353,552.4 392.786,552.842C390.776,554.476 388.352,555.275 385.936,555.275C383.191,555.275 380.467,554.244 378.393,552.25C378.096,551.971 377.809,551.66 377.537,551.336C373.736,546.726 374.416,539.947 379.059,536.188C381.07,534.546 383.5,533.75 385.918,533.75C388.346,533.75 390.758,534.552 392.719,536.123C394.198,537.211 395.153,538.785 395.202,538.871L396.34,538.924L401.311,538.855L403.061,541.904L407.272,541.509L408.887,543.168L410.365,543.49L414.207,541.189" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M589.522,442.479L589.522,445.092L587.745,448.395L587.745,445.779L589.522,442.479Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M588.522,445.016L587.745,448.395L567.378,448.677L566.959,445.891L588.522,445.016Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M567.375,446.072L567.375,448.685C567.329,448.832 566.745,449.979 566.397,450.609L566.147,447.391C566.495,446.759 567.329,446.218 567.375,446.072Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M567.378,446.063L567.378,448.677L567.375,448.685L567.375,446.072L567.378,446.063Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M567.378,446.063L567.378,448.677C567.334,448.814 567.12,449.31 566.754,449.968L566.754,447.355C567.12,446.695 567.334,446.201 567.378,446.063Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M567.147,446.578L566.804,449.843C566.528,450.343 565.879,451.35 565.491,451.796L565.522,449.078C565.911,448.627 566.934,447.016 567.147,446.578Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M566.959,446.953L566.754,449.968C566.454,450.552 566.018,451.162 565.569,451.671L565.639,449.016C566.088,448.504 566.659,447.533 566.959,446.953Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M565.85,448.656L565.709,451.516C565.301,452.027 564.743,452.638 564.175,453.084L563.647,450.266C564.216,449.824 565.442,449.184 565.85,448.656Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M565.725,448.671L565.639,451.629C565.231,452.141 564.7,452.664 564.132,453.109L563.85,450.468C564.418,450.027 565.317,449.184 565.725,448.671Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M564.647,449.641C562.638,451.275 559.741,452.9 557.325,452.9C554.58,452.9 551.856,451.869 549.782,449.875C549.485,449.596 549.198,449.285 548.926,448.961C547.272,446.953 546.466,444.539 546.466,442.138L546.466,444.752C546.466,447.152 547.272,449.57 548.926,451.574C549.198,451.9 549.485,452.207 549.782,452.49C551.856,454.486 554.58,455.513 557.325,455.513C559.741,455.513 562.165,454.717 564.175,453.084L564.647,449.641Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M546.466,444.752L546.466,442.138C546.466,444.539 547.272,446.953 548.926,448.961C549.198,449.285 549.485,449.596 549.782,449.875C551.856,451.869 554.58,452.9 557.325,452.9C559.741,452.9 562.165,452.101 564.175,450.467L564.175,453.084C562.165,454.717 559.741,455.513 557.325,455.513C554.58,455.513 551.856,454.486 549.782,452.49C549.485,452.207 549.198,451.9 548.926,451.574C547.272,449.57 546.466,447.152 546.466,444.752Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M552.551,444.796C554.128,444.783 555.378,443.488 555.36,441.939C555.334,440.384 554.059,439.146 552.495,439.146C552.487,439.146 552.479,439.146 552.47,439.15C550.911,439.175 549.645,440.455 549.675,442.019C549.686,443.552 550.948,444.796 552.503,444.796C552.518,444.796 552.536,444.796 552.551,444.796M585.596,438.814L589.522,442.479L587.745,445.779L567.378,446.063C567.334,446.201 567.12,446.695 566.754,447.355C566.454,447.935 566.088,448.504 565.639,449.016C565.231,449.527 564.743,450.025 564.175,450.467C562.165,452.101 559.741,452.9 557.325,452.9C554.58,452.9 551.856,451.869 549.782,449.875C549.485,449.596 549.198,449.285 548.926,448.961C545.125,444.351 545.805,437.572 550.448,433.813C552.459,432.171 554.889,431.375 557.307,431.375C559.735,431.375 562.147,432.177 564.108,433.748C565.587,434.836 566.542,436.41 566.591,436.496L567.729,436.549L572.7,436.48L574.45,439.529L578.661,439.134L580.276,440.793L581.754,441.115L585.596,438.814" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M476.07,442.479L476.07,445.092L474.293,448.395L474.293,445.779L476.07,442.479Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M475.07,445.016L474.293,448.395L453.926,448.677L453.508,445.891L475.07,445.016Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M453.924,446.072L453.924,448.685C453.877,448.832 453.293,449.979 452.945,450.609L452.695,447.391C453.043,446.759 453.877,446.218 453.924,446.072Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M453.926,446.063L453.926,448.677L453.924,448.685L453.924,446.072L453.926,446.063Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M453.926,446.063L453.926,448.677C453.883,448.814 453.668,449.31 453.303,449.968L453.303,447.355C453.668,446.695 453.883,446.201 453.926,446.063Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M453.695,446.578L453.352,449.843C453.077,450.343 452.428,451.35 452.039,451.796L452.07,449.078C452.459,448.627 453.482,447.016 453.695,446.578Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M453.508,446.953L453.303,449.968C453.002,450.552 452.566,451.162 452.118,451.671L452.187,449.016C452.637,448.504 453.207,447.533 453.508,446.953Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M452.398,448.656L452.258,451.516C451.85,452.027 451.291,452.638 450.723,453.084L450.195,450.266C450.764,449.824 451.99,449.184 452.398,448.656Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M452.273,448.671L452.187,451.629C451.779,452.141 451.248,452.664 450.68,453.109L450.398,450.468C450.967,450.027 451.865,449.184 452.273,448.671Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M451.195,449.641C449.186,451.275 446.289,452.9 443.873,452.9C441.129,452.9 438.404,451.869 436.33,449.875C436.033,449.596 435.746,449.285 435.475,448.961C433.82,446.953 433.014,444.539 433.014,442.138L433.014,444.752C433.014,447.152 433.82,449.57 435.475,451.574C435.746,451.9 436.033,452.207 436.33,452.49C438.404,454.486 441.129,455.513 443.873,455.513C446.289,455.513 448.713,454.717 450.723,453.084L451.195,449.641Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M433.014,444.752L433.014,442.138C433.014,444.539 433.82,446.953 435.475,448.961C435.746,449.285 436.033,449.596 436.33,449.875C438.404,451.869 441.129,452.9 443.873,452.9C446.289,452.9 448.713,452.101 450.723,450.467L450.723,453.084C448.713,454.717 446.289,455.513 443.873,455.513C441.129,455.513 438.404,454.486 436.33,452.49C436.033,452.207 435.746,451.9 435.475,451.574C433.82,449.57 433.014,447.152 433.014,444.752Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M439.1,444.796C440.676,444.783 441.926,443.488 441.908,441.939C441.883,440.384 440.607,439.146 439.043,439.146C439.036,439.146 439.028,439.146 439.018,439.15C437.459,439.175 436.194,440.455 436.223,442.019C436.235,443.552 437.496,444.796 439.051,444.796C439.066,444.796 439.084,444.796 439.1,444.796M472.144,438.814L476.07,442.479L474.293,445.779L453.926,446.063C453.883,446.201 453.668,446.695 453.303,447.355C453.002,447.935 452.637,448.504 452.187,449.016C451.779,449.527 451.291,450.025 450.723,450.467C448.713,452.101 446.289,452.9 443.873,452.9C441.129,452.9 438.404,451.869 436.33,449.875C436.033,449.596 435.746,449.285 435.475,448.961C431.674,444.351 432.353,437.572 436.996,433.813C439.008,432.171 441.437,431.375 443.856,431.375C446.283,431.375 448.695,432.177 450.657,433.748C452.135,434.836 453.09,436.41 453.139,436.496L454.278,436.549L459.248,436.48L460.998,439.529L465.209,439.134L466.824,440.793L468.303,441.115L472.144,438.814" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M362.619,442.479L362.619,445.092L360.842,448.395L360.842,445.779L362.619,442.479Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M361.619,445.016L360.842,448.395L340.475,448.677L340.056,445.891L361.619,445.016Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M340.472,446.072L340.472,448.685C340.426,448.832 339.842,449.979 339.494,450.609L339.244,447.391C339.592,446.759 340.426,446.218 340.472,446.072Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M340.475,446.063L340.475,448.677L340.472,448.685L340.472,446.072L340.475,446.063Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M340.475,446.063L340.475,448.677C340.431,448.814 340.217,449.31 339.851,449.968L339.851,447.355C340.217,446.695 340.431,446.201 340.475,446.063Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M340.244,446.578L339.9,449.843C339.625,450.343 338.976,451.35 338.588,451.796L338.619,449.078C339.008,448.627 340.031,447.016 340.244,446.578Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M340.056,446.953L339.851,449.968C339.551,450.552 339.115,451.162 338.666,451.671L338.736,449.016C339.185,448.504 339.755,447.533 340.056,446.953Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M338.947,448.656L338.806,451.516C338.398,452.027 337.839,452.638 337.272,453.084L336.744,450.266C337.313,449.824 338.539,449.184 338.947,448.656Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M338.822,448.671L338.736,451.629C338.328,452.141 337.797,452.664 337.229,453.109L336.947,450.468C337.515,450.027 338.414,449.184 338.822,448.671Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M337.744,449.641C335.734,451.275 332.838,452.9 330.422,452.9C327.677,452.9 324.953,451.869 322.879,449.875C322.582,449.596 322.295,449.285 322.023,448.961C320.369,446.953 319.563,444.539 319.563,442.138L319.563,444.752C319.563,447.152 320.369,449.57 322.023,451.574C322.295,451.9 322.582,452.207 322.879,452.49C324.953,454.486 327.677,455.513 330.422,455.513C332.838,455.513 335.262,454.717 337.272,453.084L337.744,449.641Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M319.563,444.752L319.563,442.138C319.563,444.539 320.369,446.953 322.023,448.961C322.295,449.285 322.582,449.596 322.879,449.875C324.953,451.869 327.677,452.9 330.422,452.9C332.838,452.9 335.262,452.101 337.272,450.467L337.272,453.084C335.262,454.717 332.838,455.513 330.422,455.513C327.677,455.513 324.953,454.486 322.879,452.49C322.582,452.207 322.295,451.9 322.023,451.574C320.369,449.57 319.563,447.152 319.563,444.752Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M325.648,444.796C327.225,444.783 328.475,443.488 328.457,441.939C328.431,440.384 327.156,439.146 325.592,439.146C325.584,439.146 325.576,439.146 325.566,439.15C324.008,439.175 322.742,440.455 322.772,442.019C322.783,443.552 324.045,444.796 325.6,444.796C325.615,444.796 325.633,444.796 325.648,444.796M358.693,438.814L362.619,442.479L360.842,445.779L340.475,446.063C340.431,446.201 340.217,446.695 339.851,447.355C339.551,447.935 339.185,448.504 338.736,449.016C338.328,449.527 337.839,450.025 337.272,450.467C335.262,452.101 332.838,452.9 330.422,452.9C327.677,452.9 324.953,451.869 322.879,449.875C322.582,449.596 322.295,449.285 322.023,448.961C318.222,444.351 318.902,437.572 323.545,433.813C325.556,432.171 327.986,431.375 330.404,431.375C332.832,431.375 335.244,432.177 337.205,433.748C338.684,434.836 339.639,436.41 339.688,436.496L340.826,436.549L345.797,436.48L347.547,439.529L351.758,439.134L353.373,440.793L354.851,441.115L358.693,438.814" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M366.994,269.104L366.994,271.717L365.217,275.02L365.217,272.404L366.994,269.104Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M365.994,271.641L365.217,275.02L344.85,275.302L344.431,272.516L365.994,271.641Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M344.847,272.697L344.847,275.31C344.801,275.457 344.217,276.604 343.869,277.234L343.619,274.016C343.967,273.384 344.801,272.843 344.847,272.697Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M344.85,272.688L344.85,275.302L344.847,275.31L344.847,272.697L344.85,272.688Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M344.85,272.688L344.85,275.302C344.806,275.439 344.592,275.935 344.226,276.593L344.226,273.98C344.592,273.32 344.806,272.826 344.85,272.688Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M344.619,273.203L344.275,276.468C344,276.968 343.351,277.975 342.963,278.421L342.994,275.703C343.383,275.252 344.406,273.641 344.619,273.203Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M344.431,273.578L344.226,276.593C343.926,277.177 343.49,277.787 343.041,278.296L343.111,275.641C343.56,275.129 344.13,274.158 344.431,273.578Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M343.322,275.281L343.181,278.141C342.773,278.652 342.214,279.263 341.647,279.709L341.119,276.891C341.688,276.449 342.914,275.809 343.322,275.281Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M343.197,275.296L343.111,278.254C342.703,278.766 342.172,279.289 341.604,279.734L341.322,277.093C341.89,276.652 342.789,275.809 343.197,275.296Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M342.119,276.266C340.109,277.9 337.213,279.525 334.797,279.525C332.052,279.525 329.328,278.494 327.254,276.5C326.957,276.221 326.67,275.91 326.398,275.586C324.744,273.578 323.938,271.164 323.938,268.763L323.938,271.377C323.938,273.777 324.744,276.195 326.398,278.199C326.67,278.525 326.957,278.832 327.254,279.115C329.328,281.111 332.052,282.138 334.797,282.138C337.213,282.138 339.637,281.342 341.647,279.709L342.119,276.266Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M323.938,271.377L323.938,268.763C323.938,271.164 324.744,273.578 326.398,275.586C326.67,275.91 326.957,276.221 327.254,276.5C329.328,278.494 332.052,279.525 334.797,279.525C337.213,279.525 339.637,278.726 341.647,277.092L341.647,279.709C339.637,281.342 337.213,282.138 334.797,282.138C332.052,282.138 329.328,281.111 327.254,279.115C326.957,278.832 326.67,278.525 326.398,278.199C324.744,276.195 323.938,273.777 323.938,271.377Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M330.023,271.421C331.6,271.408 332.85,270.113 332.832,268.564C332.806,267.009 331.531,265.771 329.967,265.771C329.959,265.771 329.951,265.771 329.941,265.775C328.383,265.8 327.117,267.08 327.147,268.644C327.158,270.177 328.42,271.421 329.975,271.421C329.99,271.421 330.008,271.421 330.023,271.421M363.068,265.439L366.994,269.104L365.217,272.404L344.85,272.688C344.806,272.826 344.592,273.32 344.226,273.98C343.926,274.56 343.56,275.129 343.111,275.641C342.703,276.152 342.214,276.65 341.647,277.092C339.637,278.726 337.213,279.525 334.797,279.525C332.052,279.525 329.328,278.494 327.254,276.5C326.957,276.221 326.67,275.91 326.398,275.586C322.597,270.976 323.277,264.197 327.92,260.438C329.931,258.796 332.361,258 334.779,258C337.207,258 339.619,258.802 341.58,260.373C343.059,261.461 344.014,263.035 344.063,263.121L345.201,263.174L350.172,263.105L351.922,266.154L356.133,265.759L357.748,267.418L359.226,267.74L363.068,265.439" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M255.528,341.854L255.528,344.467L253.751,347.77L253.751,345.154L255.528,341.854Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M254.528,344.391L253.751,347.77L233.384,348.052L232.966,345.266L254.528,344.391Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M233.382,345.447L233.382,348.06C233.335,348.207 232.751,349.354 232.403,349.984L232.153,346.766C232.501,346.134 233.335,345.593 233.382,345.447Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M233.384,345.438L233.384,348.052L233.382,348.06L233.382,345.447L233.384,345.438Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M233.384,345.438L233.384,348.052C233.341,348.189 233.126,348.685 232.761,349.343L232.761,346.73C233.126,346.07 233.341,345.576 233.384,345.438Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M233.153,345.953L232.81,349.218C232.534,349.718 231.886,350.725 231.497,351.171L231.528,348.453C231.917,348.002 232.94,346.391 233.153,345.953Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M232.966,346.328L232.761,349.343C232.46,349.927 232.024,350.537 231.575,351.046L231.645,348.391C232.095,347.879 232.665,346.908 232.966,346.328Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M231.856,348.031L231.716,350.891C231.307,351.402 230.749,352.013 230.181,352.459L229.653,349.641C230.222,349.199 231.448,348.559 231.856,348.031Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M231.731,348.046L231.645,351.004C231.237,351.516 230.706,352.039 230.138,352.484L229.856,349.843C230.425,349.402 231.323,348.559 231.731,348.046Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M230.653,349.016C228.644,350.65 225.747,352.275 223.331,352.275C220.587,352.275 217.862,351.244 215.788,349.25C215.491,348.971 215.204,348.66 214.932,348.336C213.278,346.328 212.472,343.914 212.472,341.513L212.472,344.127C212.472,346.527 213.278,348.945 214.932,350.949C215.204,351.275 215.491,351.582 215.788,351.865C217.862,353.861 220.587,354.888 223.331,354.888C225.747,354.888 228.171,354.092 230.181,352.459L230.653,349.016Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M212.472,344.127L212.472,341.513C212.472,343.914 213.278,346.328 214.932,348.336C215.204,348.66 215.491,348.971 215.788,349.25C217.862,351.244 220.587,352.275 223.331,352.275C225.747,352.275 228.171,351.476 230.181,349.842L230.181,352.459C228.171,354.092 225.747,354.888 223.331,354.888C220.587,354.888 217.862,353.861 215.788,351.865C215.491,351.582 215.204,351.275 214.932,350.949C213.278,348.945 212.472,346.527 212.472,344.127Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M218.557,344.171C220.134,344.158 221.384,342.863 221.366,341.314C221.341,339.759 220.065,338.521 218.501,338.521C218.493,338.521 218.486,338.521 218.476,338.525C216.917,338.55 215.652,339.83 215.681,341.394C215.693,342.927 216.954,344.171 218.509,344.171C218.524,344.171 218.542,344.171 218.557,344.171M251.602,338.189L255.528,341.854L253.751,345.154L233.384,345.438C233.341,345.576 233.126,346.07 232.761,346.73C232.46,347.31 232.095,347.879 231.645,348.391C231.237,348.902 230.749,349.4 230.181,349.842C228.171,351.476 225.747,352.275 223.331,352.275C220.587,352.275 217.862,351.244 215.788,349.25C215.491,348.971 215.204,348.66 214.932,348.336C211.132,343.726 211.811,336.947 216.454,333.188C218.466,331.546 220.895,330.75 223.314,330.75C225.741,330.75 228.153,331.552 230.115,333.123C231.593,334.211 232.548,335.785 232.597,335.871L233.736,335.924L238.706,335.855L240.456,338.904L244.667,338.509L246.282,340.168L247.761,340.49L251.602,338.189" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M366.994,341.854L366.994,344.467L365.217,347.77L365.217,345.154L366.994,341.854Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M365.994,344.391L365.217,347.77L344.85,348.052L344.431,345.266L365.994,344.391Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M344.847,345.447L344.847,348.06C344.801,348.207 344.217,349.354 343.869,349.984L343.619,346.766C343.967,346.134 344.801,345.593 344.847,345.447Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M344.85,345.438L344.85,348.052L344.847,348.06L344.847,345.447L344.85,345.438Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M344.85,345.438L344.85,348.052C344.806,348.189 344.592,348.685 344.226,349.343L344.226,346.73C344.592,346.07 344.806,345.576 344.85,345.438Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M344.619,345.953L344.275,349.218C344,349.718 343.351,350.725 342.963,351.171L342.994,348.453C343.383,348.002 344.406,346.391 344.619,345.953Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M344.431,346.328L344.226,349.343C343.926,349.927 343.49,350.537 343.041,351.046L343.111,348.391C343.56,347.879 344.13,346.908 344.431,346.328Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M343.322,348.031L343.181,350.891C342.773,351.402 342.214,352.013 341.647,352.459L341.119,349.641C341.688,349.199 342.914,348.559 343.322,348.031Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M343.197,348.046L343.111,351.004C342.703,351.516 342.172,352.039 341.604,352.484L341.322,349.843C341.89,349.402 342.789,348.559 343.197,348.046Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M342.119,349.016C340.109,350.65 337.213,352.275 334.797,352.275C332.052,352.275 329.328,351.244 327.254,349.25C326.957,348.971 326.67,348.66 326.398,348.336C324.744,346.328 323.938,343.914 323.938,341.513L323.938,344.127C323.938,346.527 324.744,348.945 326.398,350.949C326.67,351.275 326.957,351.582 327.254,351.865C329.328,353.861 332.052,354.888 334.797,354.888C337.213,354.888 339.637,354.092 341.647,352.459L342.119,349.016Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M323.938,344.127L323.938,341.513C323.938,343.914 324.744,346.328 326.398,348.336C326.67,348.66 326.957,348.971 327.254,349.25C329.328,351.244 332.052,352.275 334.797,352.275C337.213,352.275 339.637,351.476 341.647,349.842L341.647,352.459C339.637,354.092 337.213,354.888 334.797,354.888C332.052,354.888 329.328,353.861 327.254,351.865C326.957,351.582 326.67,351.275 326.398,350.949C324.744,348.945 323.938,346.527 323.938,344.127Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M330.023,344.171C331.6,344.158 332.85,342.863 332.832,341.314C332.806,339.759 331.531,338.521 329.967,338.521C329.959,338.521 329.951,338.521 329.941,338.525C328.383,338.55 327.117,339.83 327.147,341.394C327.158,342.927 328.42,344.171 329.975,344.171C329.99,344.171 330.008,344.171 330.023,344.171M363.068,338.189L366.994,341.854L365.217,345.154L344.85,345.438C344.806,345.576 344.592,346.07 344.226,346.73C343.926,347.31 343.56,347.879 343.111,348.391C342.703,348.902 342.214,349.4 341.647,349.842C339.637,351.476 337.213,352.275 334.797,352.275C332.052,352.275 329.328,351.244 327.254,349.25C326.957,348.971 326.67,348.66 326.398,348.336C322.597,343.726 323.277,336.947 327.92,333.188C329.931,331.546 332.361,330.75 334.779,330.75C337.207,330.75 339.619,331.552 341.58,333.123C343.059,334.211 344.014,335.785 344.063,335.871L345.201,335.924L350.172,335.855L351.922,338.904L356.133,338.509L357.748,340.168L359.226,340.49L363.068,338.189" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M478.459,341.854L478.459,344.467L476.682,347.77L476.682,345.154L478.459,341.854Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M477.459,344.391L476.682,347.77L456.315,348.052L455.897,345.266L477.459,344.391Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M456.313,345.447L456.313,348.06C456.266,348.207 455.682,349.354 455.334,349.984L455.084,346.766C455.432,346.134 456.266,345.593 456.313,345.447Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M456.315,345.438L456.315,348.052L456.313,348.06L456.313,345.447L456.315,345.438Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M456.315,345.438L456.315,348.052C456.272,348.189 456.057,348.685 455.692,349.343L455.692,346.73C456.057,346.07 456.272,345.576 456.315,345.438Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M456.084,345.953L455.741,349.218C455.466,349.718 454.817,350.725 454.429,351.171L454.459,348.453C454.848,348.002 455.871,346.391 456.084,345.953Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M455.897,346.328L455.692,349.343C455.391,349.927 454.955,350.537 454.507,351.046L454.577,348.391C455.026,347.879 455.596,346.908 455.897,346.328Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M454.788,348.031L454.647,350.891C454.239,351.402 453.68,352.013 453.112,352.459L452.584,349.641C453.153,349.199 454.379,348.559 454.788,348.031Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M454.663,348.046L454.577,351.004C454.168,351.516 453.638,352.039 453.069,352.484L452.788,349.843C453.356,349.402 454.254,348.559 454.663,348.046Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M453.584,349.016C451.575,350.65 448.679,352.275 446.263,352.275C443.518,352.275 440.793,351.244 438.72,349.25C438.422,348.971 438.135,348.66 437.864,348.336C436.209,346.328 435.403,343.914 435.403,341.513L435.403,344.127C435.403,346.527 436.209,348.945 437.864,350.949C438.135,351.275 438.422,351.582 438.72,351.865C440.793,353.861 443.518,354.888 446.263,354.888C448.679,354.888 451.102,354.092 453.112,352.459L453.584,349.016Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M435.403,344.127L435.403,341.513C435.403,343.914 436.209,346.328 437.864,348.336C438.135,348.66 438.422,348.971 438.72,349.25C440.793,351.244 443.518,352.275 446.263,352.275C448.679,352.275 451.102,351.476 453.112,349.842L453.112,352.459C451.102,354.092 448.679,354.888 446.263,354.888C443.518,354.888 440.793,353.861 438.72,351.865C438.422,351.582 438.135,351.275 437.864,350.949C436.209,348.945 435.403,346.527 435.403,344.127Z" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
<path d="M441.489,344.171C443.065,344.158 444.315,342.863 444.297,341.314C444.272,339.759 442.996,338.521 441.432,338.521C441.425,338.521 441.417,338.521 441.407,338.525C439.848,338.55 438.583,339.83 438.612,341.394C438.624,342.927 439.886,344.171 441.44,344.171C441.455,344.171 441.473,344.171 441.489,344.171M474.534,338.189L478.459,341.854L476.682,345.154L456.315,345.438C456.272,345.576 456.057,346.07 455.692,346.73C455.391,347.31 455.026,347.879 454.577,348.391C454.168,348.902 453.68,349.4 453.112,349.842C451.102,351.476 448.679,352.275 446.263,352.275C443.518,352.275 440.793,351.244 438.72,349.25C438.422,348.971 438.135,348.66 437.864,348.336C434.063,343.726 434.743,336.947 439.386,333.188C441.397,331.546 443.827,330.75 446.245,330.75C448.672,330.75 451.084,331.552 453.046,333.123C454.524,334.211 455.479,335.785 455.528,335.871L456.667,335.924L461.638,335.855L463.388,338.904L467.598,338.509L469.213,340.168L470.692,340.49L474.534,338.189" style="fill:rgb(58,142,237);fill-rule:nonzero;"/>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

4
docs/reference/common-configs.md
View File

@ -54,9 +54,9 @@ below to configure it.
The reporting section contains any configuration for useful for running the The reporting section contains any configuration for useful for running the
service, such as reporting errors. Currently, Notary only supports reporting errors service, such as reporting errors. Currently, Notary only supports reporting errors
to [Bugsnag](https://bugsnag.com). to <a href="https://bugsnag.com" target="_blank">Bugsnag</a>.
See [bugsnag-go](https://github.com/bugsnag/bugsnag-go/) for more information See <a href="https://github.com/bugsnag/bugsnag-go/" target="_blank">bugsnag-go</a> for more information
about these configuration parameters. about these configuration parameters.
```json ```json

2
docs/reference/server-config.md
View File

@ -267,7 +267,7 @@ configure it.
**Token authentication:** **Token authentication:**
This is an implementation of the same authentication used by version 2 of the This is an implementation of the same authentication used by version 2 of the
[Docker registry](https://github.com/docker/distribution). (JWT token-based <a href="https://github.com/docker/distribution" target="_blank">Docker registry</a>. (JWT token-based
authentication post login.) authentication post login.)
<table> <table>

BIN
docs/resources/ncc_docker_notary_audit_2015_07_31.pdf Normal file
View File

Binary file not shown.

8
docs/running_a_service.md
View File

@ -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 The quickest way to spin up a full Notary service for testing and development
purposes is to use the Docker compose file in the purposes is to use the Docker compose file in the
[Notary project](https://github.com/docker/notary). <a href="https://github.com/docker/notary" target="_blank">Notary project</a>.
```plain ```plain
$ git clone https://github.com/docker/notary.git $ git clone https://github.com/docker/notary.git
@ -75,9 +75,9 @@ the following command line arguments:
- `-config=<config file>` - specify the path to the JSON configuration file. - `-config=<config file>` - specify the path to the JSON configuration file.
- `-debug` - Passing this flag enables the debugging server on `localhost:8080`. - `-debug` - Passing this flag enables the debugging server on `localhost:8080`.
The debugging server provides [pprof](https://golang.org/pkg/net/http/pprof/) The debugging server provides <a href="https://golang.org/pkg/net/http/pprof/" target="_blank">pprof</a>
and [expvar](https://golang.org/pkg/expvar/) endpoints. (Remember, this and <a href="https://golang.org/pkg/expvar/" target="_blank">expvar</a> endpoints.
is localhost with respect to the running container - this endpoint is not (Remember, this is localhost with respect to the running container - this endpoint is not
exposed from the container). exposed from the container).
This option can also be set in the configuration file. This option can also be set in the configuration file.

256
docs/service_architecture.md
View File

@ -12,15 +12,67 @@ weight=3
# Understand the Notary service architecture # Understand the Notary service architecture
On this page, you get an overview of the Notary service architecture. This On this page, you get an overview of the Notary service architecture.
document assumes a prior understanding of [The Update
Framework](https://theupdateframework.github.io/). ## Brief overview of TUF keys and roles
This document assumes familiarity with
<a href="https://www.theupdateframework.com/" target="_blank">The Update Framework</a>,
but here is a brief recap of the TUF roles and corresponding key hierarchy:
<center><img src="images/key-hierarchy.svg" alt="TUF Key Hierarchy" width="400px"/></center>
- The root key is the root of all trust. It signs the
<a href="https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L489" target="_blank">root metadata file</a>,
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
<a href="https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L604" target="_blank">snapshot metadata file</a>,
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
<a href="https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L827" target="_blank">timestamp metadata file</a>,
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
<a href="https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L678" target="_blank">targets metadata file</a>,
which lists filenames in the collection, and their sizes and respective
<a href="https://en.wikipedia.org/wiki/Cryptographic_hash_function" target="_blank">hashes</a>.
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
<a href="https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L678" target="_blank">delegation metadata files</a>,
which lists filenames in the collection, and their sizes and respective
<a href="https://en.wikipedia.org/wiki/Cryptographic_hash_function" target="_blank">hashes</a>.
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 ## 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 A Notary service consists of a Notary server, which stores and updates the
signed [TUF metadata files]( signed
https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L348) <a href="https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L348">TUF metadata files</a>
for multiple trusted collections in an associated database, and a Notary signer, which 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 stores private keys for and signs metadata for the Notary server. The following
diagram illustrates this architecture: diagram illustrates this architecture:
@ -38,24 +90,21 @@ responsible for:
The Notary signer is responsible for: The Notary signer is responsible for:
- storing the private signing keys - storing the private signing keys
[wrapped]( <a href="https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31#section-4.4" target="_blank">wrapped</a>
https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31#section-4.4) and <a href="https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31#section-4.8" target="_blank">encrypted</a>
and [encrypted]( using <a href="https://github.com/dvsekhvalnov/jose2go" target="_blank">Javascript Object Signing and Encryption</a> in a database separate from the
https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31#section-4.8) Notary server database
using [Javascript Object Signing and Encryption](
https://github.com/dvsekhvalnov/jose2go) in a database separate from the
Notary server database
- performing signing operations with these keys whenever the Notary server requests - performing signing operations with these keys whenever the Notary server requests
## Example client-server-signer interaction ## Example client-server-signer interaction
The following diagram illustrates the interactions between the Notary client, The following diagram illustrates the interactions between the Notary client,
sever, and signer: server, and signer:
![Notary Service Sequence Diagram](images/metadata-sequence.svg) ![Notary Service Sequence Diagram](images/metadata-sequence.svg)
1. Notary server optionally supports authentication from clients using 1. Notary server optionally supports authentication from clients using
[JWT](http://jwt.io/) tokens. This requires an authorization server that <a href="http://jwt.io/" target="_blank">JWT</a> tokens. This requires an authorization server that
manages access controls, and a cert bundle from this authorization server manages access controls, and a cert bundle from this authorization server
containing the public key it uses to sign tokens. containing the public key it uses to sign tokens.
@ -103,7 +152,9 @@ sever, and signer:
## Threat model ## 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. discusses how our architecture is designed to deal with compromises.
### Notary server compromise ### Notary server compromise
@ -133,7 +184,7 @@ operations with any key the Signer holds.
- **Rollback, Freeze, Mix and Match** - The attacker can request that - **Rollback, Freeze, Mix and Match** - The attacker can request that
the Notary signer sign any arbitrary timestamp (and maybe snapshot) metadata 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 the snapshot key is available, a mix-and-match attack up to the expiration
of the targets file. of the targets file.
@ -143,7 +194,7 @@ operations with any key the Signer holds.
good metadata that any client may have. good metadata that any client may have.
Note that the timestamp and snapshot keys cannot be compromised in a server-only 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 compromise is mitigated, an attacker will not be
able to generate valid timestamp or snapshot metadata and serve them on a able to generate valid timestamp or snapshot metadata and serve them on a
malicious mirror, for example. malicious mirror, for example.
@ -151,9 +202,10 @@ operations with any key the Signer holds.
### Notary signer compromise ### Notary signer compromise
In the event of a Notary signer compromise, an attacker would have access to 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, all the (timestamp and snapshot) private keys stored in a database.
they would have the ability to sign arbitrary content with, and to delete, the If the keys are stored in an HSM, they would have the ability to sign arbitrary
keys in the HSM, but not to exfiltrate the private material. 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 - **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 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. timestamps or snapshots.
- **Key Compromise** - If the Notary signer uses a database as its backend, - **Key Compromise** - If the Notary signer uses a database as its backend,
an attacker can exfiltrate all the private material. Note that the capabilities an attacker can exfiltrate all the (timestamp and snapshot) private material.
of an attacker are the same as of a Notary server compromise in terms of Note that the capabilities of an attacker are the same as of a Notary server
signing arbitrary metadata, with the important detail that in this particular compromise in terms of signing arbitrary metadata, with the important detail
case key rotations will be necessary to recover from the attack. 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 <br/> 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 <br/> 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 <br/> 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 <br/> 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 ## Related information