diff --git a/_data/toc.yaml b/_data/toc.yaml index dc8270821e..84da755a3b 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1404,28 +1404,6 @@ manuals: title: Release notes - sectiontitle: Open-source projects section: - - sectiontitle: Notary - section: - - path: /notary/getting_started/ - title: Get started with Notary - - path: /notary/advanced_usage/ - title: Use the Notary client - - path: /notary/service_architecture/ - title: Understand the service architecture - - path: /notary/running_a_service/ - title: Run a Notary service - - path: /notary/changelog/ - title: Notary changelog - - sectiontitle: Configuration files - section: - - path: /notary/reference/server-config/ - title: Server configuration - - path: /notary/reference/signer-config/ - title: Signer configuration - - path: /notary/reference/client-config/ - title: Client configuration - - path: /notary/reference/common-configs/ - title: Common Server and signer configurations - sectiontitle: Docker Registry section: - path: /registry/ diff --git a/engine/security/trust/index.md b/engine/security/trust/index.md index 359fe957b8..52096d47a6 100644 --- a/engine/security/trust/index.md +++ b/engine/security/trust/index.md @@ -4,6 +4,15 @@ keywords: content, trust, security, docker, documentation title: Content trust in Docker redirect_from: - /engine/security/trust/content_trust/ +- /notary/getting_started/ +- /notary/advanced_usage/ +- /notary/service_architecture/ +- /notary/running_a_service/ +- /notary/changelog/ +- /notary/reference/server-config/ +- /notary/reference/signer-config/ +- /notary/reference/client-config/ +- /notary/reference/common-configs/ --- When transferring data among networked systems, *trust* is a central concern. In diff --git a/notary/advanced_usage.md b/notary/advanced_usage.md deleted file mode 100644 index 27041dff49..0000000000 --- a/notary/advanced_usage.md +++ /dev/null @@ -1,272 +0,0 @@ ---- -description: Becoming a power user of the notary client. -keywords: docker, notary, notary-client, docker content trust, content trust, power user, advanced -title: Use the Notary client for advanced users ---- - -This page explains advanced uses of Notary client for users who are running -their own Notary service. Make sure you have first read and understood how to -[run your own Notary service](running_a_service.md) before continuing. - -## An important note about the examples - -This document's command examples omit the `-s` and `-d` flags. If you do not -know what these options do, read the [Getting Started](getting_started.md) docs -or run `notary --help` before continuing. Once you understand what these flags do, -you must provide your own values for these options while following this document. -You can also configure these options, see [advanced configuration options](reference/index.md) -for more information. - -## Initialize a Trusted Collection - -Before adding and signing content to a collection, you must first initialize that collection. - -```bash -$ notary init example.com/collection - -No root keys found. Generating a new root key... -You are about to create a new root signing key passphrase. This passphrase -is used to protect the most sensitive key in your signing system. -Choose a long, complex passphrase and be careful to keep the password and the -key file itself secure and backed up. It is highly recommended that you use a -password manager to generate the passphrase and keep it safe. There is no -way to recover this key. You can find the key in your config directory. -Enter passphrase for new root key with ID 1f54328: -Repeat passphrase for new root key with ID 1f54328: -Enter passphrase for new targets key with ID 1df39fc (example.com/collection): -Repeat passphrase for new targets key with ID 1df39fc (example.com/collection): -``` - -Initializing a trusted collection generates the following items; all keys use -asymmetric algorithms, but there is no requirement that they all use the _same_ -algorithm: - -- If no root key is found, an initial `root` key is generated. This key is - used as the default root of trust for all your trusted collections. -- A `targets` key and a `snapshot` key. The same password encrypts both of these - as the security profile of them (when both held by the author of the trusted - collection) is identical. This is why are not prompted for a snapshot key - password. -- A `timestamp` key. This is generated by the server on a request from the - client, returning just the public key. The server holds the private key and - signs timestamps on behalf of the user. -- Stub signed notary metadata. This stages the base version of the trust - metadata for the collection. It is finalized when it is published to the - server. - -## Add and remove Targets - -To add targets to a trusted collection with notary CLI: - -```bash -$ notary add example.com/collection v1 my_file.txt -``` - -This adds the local file `my_file.txt` (which must exist relative to the -current working directory), under the target name `v1`, to the -`example.com/collection` collection we set up. The contents of the local file -are not actually added to the collection - a "target" consists of the file path -and one or more checksums of the contents. - -This is an offline command, and we must run a -`notary publish example.com/collection` for the add to take effect. - -To remove targets, we use the `notary remove` command, specifying the GUN and -target name. - -```bash -$ notary remove example.com/collection v1 -``` - -Removing a target is also an offline command that requires a -`notary publish example.com/collection` to take effect. - -## Manage keys - -By default, the notary client is responsible for managing the private keys for -root, targets, snapshot roles. All of these keys are generated by default when -initializing a new trusted collection. The keys are located in the notary `trust_dir` -directory. In addition, if delegation roles exist, those roles' keys are to also -managed by the notary client. - -The notary server is always responsible for managing the timestamp key. However, -it is possible for the notary server to manage the snapshot key, if the snapshot -key is rotated from the notary client to server, as described in the following -subsection. - -### Rotate keys - -In case of potential compromise, notary provides a CLI command for rotating keys. -You can use the `notary key rotate` command to rotate the targets or snapshot -keys. - -While the snapshot key is managed by the notary client by default, use the `notary key -rotate snapshot -r` command to rotate the snapshot key to the server, such that the -notary server can sign snapshots. This is particularly useful when using -delegations with a trusted collection, so that delegates never need access to the -snapshot key to push their updates to the collection. - -New collections created by a Docker 1.11 Engine client cause the server -manage to the snapshot key by default. To reclaim control of the snapshot key on -the client, use the `notary key rotate` command without the `-r` flag. - -The targets key must be locally managed - to rotate the targets key, for -instance in case of compromise, use the `notary key rotate targets` command -without the `-r` flag. - -### Use a Yubikey - -Notary can be used with -[Yubikey 4](https://www.yubico.com/products/yubikey-hardware/yubikey4/){: target="_blank" rel="noopener" class="_"} -keys, via a PKCS11 interface when the Yubikey has CCID mode enabled. -The Yubikey is prioritized to store root keys, and requires user -touch-input for signing. Yubikey support is included with the Docker Engine 1.11 -client for use with Docker Content Trust. - -Yubikey support requires -[Yubico PIV libraries](https://www.yubico.com/support/knowledge-base/categories/downloads/){: target="_blank" rel="noopener" class="_"} -(bundled with the PIV tools) to be available in standard library locations. - -## Work with delegation roles - -Delegation roles simplify collaborator workflows in notary trusted collections, and -also allow for fine-grained permissions within a collection's contents across -delegations. In essence, delegation roles are restricted versions of the targets -role that are only allowed to sign targets within certain filepaths. - -A delegation role is given its own keys, such that each collaborator can keep -his own private key without the administrator having to share the -targets key or allow a collaborator write access to all targets of the -collection. - -Before adding any delegations, you should rotate the snapshot key to the server. -This is done by default for new collections created with a Docker Engine 1.11 client. -Delegation roles do not require the snapshot key to publish -their own targets to the collection, since the server can publish the valid -snapshot with the delegation targets: - -```bash -$ notary key rotate example.com/collection snapshot -r -``` - -Here, `-r` specifies to rotate the key to the remote server. - -When adding a delegation, your must acquire a x509 certificate with the public -key of the user you wish to delegate to. The user who assumes this -delegation role must hold the private key to sign content with notary. - -Once you've acquired the delegate's x509 certificate, you can add a delegation -for this user: - -```bash -$ notary delegation add example.com/collection targets/releases cert.pem --paths="delegation/path" -``` - -The preceding example illustrates a request to add the delegation -`targets/releases` to the GUN `example.com/collection`. The delegation name must -be prefixed by `targets/` to be valid, since all delegations are restricted -versions of the target role. The command adds the public key contained in the -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` -role could 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 -`--paths`, or pass the `--all-paths` flag to allow this delegation to publish -content under any pathname. - -After publishing, you can view delegations using a list command: - -```bash -$ notary delegation list example.com/collection - - ROLE PATHS KEY IDS THRESHOLD ---------------------------------------------------------------------------------------------------------------- - 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. - -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: - -```bash -$ notary delegation remove example.com/user targets/releases - -Are you sure you want to remove all data for this delegation? (yes/no) -yes - -Forced removal (including all keys and paths) of delegation role targets/releases to repository "example.com/user" staged for next publish. -``` - -You can remove individual keys and/or paths by passing keys as arguments, and/or -paths under the `--paths` flag. Use `--all-paths` to clear all paths for this -role. If you specify all key IDs currently in the delegation role, you -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 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`. - -```bash -$ notary add example/collections delegation/path/target delegation_file.txt --roles=targets/releases -``` - -In the preceding example, you add the target `delegation/path/target` to -collection `example/collections` staged for next publish. The file -`delegation_file.txt` is a target `delegation/path/target` using the delegation -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 -the base `targets` role. - -To remove this target from our delegation, use the `notary remove` command with -the same flag: - -```bash -$ notary remove example/collections delegation/path/target --roles=targets/releases -``` - -## Use delegations with content trust - -Docker Engine 1.10 and above supports the usage of the `targets/releases` -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 attempts to search the `targets/releases` role for the signed image tag, -and falls back to the default `targets` role if it does not exist. 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 -Docker Content Trust must pull tags only signed by the `targets/releases` delegation role -or the `targets` base role. - -When running `docker push` with Docker Content Trust, Docker Engine 1.10 -attempts 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` -attempts 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 fails. -If no delegation roles exist, the push attempts to sign with the base `targets` role. - -To use the `targets/releases` role for pushing and pulling images with content trust, -follow the steps above to add and publish the delegation role with notary. -When adding the delegation, the `--all-paths` flag should be used to allow signing all tags. - -## Files and state on disk - -Notary stores state in its `trust_dir` directory, which is `~/.notary` by -default or usually `~/.docker/trust` when enabling docker content trust. Within this -directory, `trusted_certificates` stores certificates for bootstrapping trust in -a collection, `tuf` stores TUF metadata and changelists to be applied to a GUN, -and `private` stores private keys. - -The `root_keys` subdirectory within `private` stores root private keys, while -`tuf_keys` stores targets, snapshots, and delegations private keys. \ No newline at end of file diff --git a/notary/changelog.md b/notary/changelog.md deleted file mode 100644 index 6b778e0556..0000000000 --- a/notary/changelog.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -description: Notary release changelog -keywords: docker, notary, changelog, notary changelog, notary releases, releases, notary versions, versions -title: Notary Changelog ---- - -## v0.3 - -#### 5/11/2016 -Implements root key and certificate rotation, as well as trust pinning configurations to specify known good key IDs and CAs to replace TOFU. -Additional improvements and fixes to notary internals, and RethinkDB support. - -> Detailed release notes can be found here: -v0.3 release notes. - -## v0.2 - -#### 2/24/2016 - -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. - -## 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. \ No newline at end of file diff --git a/notary/getting_started.md b/notary/getting_started.md deleted file mode 100644 index 5ffddf2f2a..0000000000 --- a/notary/getting_started.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -description: Performing basic operation to use Notary in tandem with Docker Content Trust. -keywords: docker, Notary, notary-client, docker content trust, content trust -title: Get started with 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). 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)](https://www.theupdateframework.com/) -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 macOS from the -Notary repository's -[Releases page on Github](https://github.com/docker/notary/releases). - -## Understand Notary naming - -Notary uses Globally Unique Names (GUNs) to identify trust collections. To -enable Notary to run in a multi-tenant fashion, you must use this format -when interacting with Docker Hub through the Notary client. When specifying -Docker image names for the Notary client, the GUN format is: - -- For official images (identifiable by the "Official Image" moniker), the - image name as displayed on Docker Hub, prefixed with `docker.io/library/`. For - example, if you would normally type `docker pull ubuntu` you must enter `notary - {cmd} docker.io/library/ubuntu`. -- For all other images, the image name as displayed on Docker Hub, prefixed by `docker.io`. - -The Docker Engine client takes care of these name expansions for you so do not -change the names you use with the Engine client or API. This is a requirement -only when interacting with the same Docker Hub repositories through the Notary -client. - -## Inspect a Docker Hub repository - -The most basic operation is listing the available signed tags in a repository. -The Notary client used in isolation does not know where the trust repositories -are located. So, you must provide the `-s` (or long form `--server`) flag to -tell the client which repository server it should communicate with. - -The official Docker Hub Notary servers are located at -`https://notary.docker.io`. If you would like to use your own Notary server, -it is important to use the same or a newer -[Notary version](https://github.com/docker/notary/releases), -as the client for feature compatibility (ex: client version 0.2, server/signer version >= 0.2). -Additionally, Notary stores your own signing keys, -and a cache of previously downloaded trust metadata in a directory, provided -with the `-d` flag. When interacting with Docker Hub repositories, you must -instruct the client to use the associated trust directory, which by default is -found at `.docker/trust` within the calling user's home directory (failing to -use this directory may result in errors when publishing updates to your trust -data): - -```bash -$ notary -s https://notary.docker.io -d ~/.docker/trust list docker.io/library/alpine - NAME DIGEST SIZE (BYTES) ROLE ------------------------------------------------------------------------------------------------------- - 2.6 e9cec9aec697d8b9d450edd32860ecd363f2f3174c8338beb5f809422d182c63 1374 targets - 2.7 9f08005dff552038f0ad2f46b8e65ff3d25641747d3912e3ea8da6785046561a 1374 targets - 3.1 e876b57b2444813cd474523b9c74aacacc238230b288a22bccece9caf2862197 1374 targets - 3.2 4a8c62881c6237b4c1434125661cddf09434d37c6ef26bf26bfaef0b8c5e2f05 1374 targets - 3.3 2d4f890b7eddb390285e3afea9be98a078c2acd2fb311da8c9048e3d1e4864d3 1374 targets - edge 878c1b1d668830f01c2b1622ebf1656e32ce830850775d26a387b2f11f541239 1374 targets - latest 24a36bbc059b1345b7e8be0df20f1b23caa3602e85d42fff7ecd9d0bd255de56 1377 targets -``` - -The output shows us the names of the tags available, the hex encoded sha256 -digest of the image manifest associated with that tag, the size of the manifest, -and the Notary role that signed this tag into the repository. The "targets" role -is the most common role in a simple repository. When a repository has (or -expects) to have collaborators, you may see other "delegated" roles listed as -signers, based on the choice of the administrator as to how they organize their -collaborators. - -When you run a `docker pull` command, Docker Engine is using an integrated -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 uses the list operation to efficiently retrieve all -the mappings). Having validated the signatures on the trust data, the client -instructs 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. - -## Delete a tag - -Notary generates and stores signing keys on the host it's running on. This means -that the Docker Hub cannot delete tags from the trust data, they must be deleted -using the Notary client. You can do this with the `notary remove` command. -Again, you must direct it to speak to the correct Notary server. Neither -you nor the author has permissions to delete tags from the official `alpine` -repository, so the output below is for demonstration only: - -```bash -$ notary -s https://notary.docker.io -d ~/.docker/trust remove docker.io/library/alpine 2.6 -Removal of 2.6 from docker.io/library/alpine staged for next publish. -``` - -In the preceding example, the output message indicates that only the removal was -staged. When performing any write operations they are staged into a change list. -This list is applied to the latest version of the trust repository the next time -a `notary publish` is run for that repository. - -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 silently ignores the flag if provided. -Failing to provide the correct value for the `-d` flag may show the wrong -(probably empty) change list: - -```bash -$ notary -d ~/.docker/trust status docker.io/library/alpine -Unpublished changes for docker.io/library/alpine: - -action scope type path ----------------------------------------------------- -delete targets target 2.6 -$ notary -s https://notary.docker.io publish docker.io/library/alpine -``` - -## Configure the client - -It is verbose and tedious to always provide the `-s` and `-d` flags -manually to most commands. A simple way to create preconfigured versions of the -Notary command is via aliases. Add the following to your `.bashrc` or -equivalent: - -```bash -alias dockernotary="notary -s https://notary.docker.io -d ~/.docker/trust" -``` - -More advanced methods of configuration, and additional options, can be found in -the [configuration doc](reference/index.md) and by running `notary --help`. diff --git a/notary/images/key-hierarchy.svg b/notary/images/key-hierarchy.svg deleted file mode 100644 index efdc9e6575..0000000000 --- a/notary/images/key-hierarchy.svg +++ /dev/null @@ -1,173 +0,0 @@ - - - - - - - Delegation2 - - - - - Delegation1 - - - - - - - - Root - - - - - Timestamp - - - - - Snapshot - - - - - - - T - - - ar - - - gets - - - - - Delegation3 - - - - - - - Delegation4 - - - - - Delegation5 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/notary/images/metadata-sequence.svg b/notary/images/metadata-sequence.svg deleted file mode 100644 index 1ecf148993..0000000000 --- a/notary/images/metadata-sequence.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - Produced by OmniGraffle 6.5.2 2016-04-28 20:11:35 +0000SequenceLayer 1credentialsauthXTUFserver>_Upload new metadata401 - please authbearer tokenverify(metadata)get metadatagenerate( timestamp,snapshot)sign( timestamp, snapshot)private keystimestamp/snapshotsignaturesToken + Upload new metadatatimestamp/snapshotstore metadata200 OKToken + Get new metadataget metadata200 OK + Latest metadata1234567(signer)(server DB)(signer DB)(client) diff --git a/notary/images/service-architecture.svg b/notary/images/service-architecture.svg deleted file mode 100644 index 7117a701fc..0000000000 --- a/notary/images/service-architecture.svg +++ /dev/null @@ -1,92 +0,0 @@ - - - - - - - - server - - - - - - - - - - - >_ - - - - - - - >_ - - - - - - - >_ - - - - - - - - clients - - - - - - - - - - - - - - TUF - - - - - (server DB) - - - - - - - - - - - - - - - (signer DB) - - - - - - - - - - - - - (signer) - - - - diff --git a/notary/images/service-deployment.svg b/notary/images/service-deployment.svg deleted file mode 100644 index e79cf3faf9..0000000000 --- a/notary/images/service-deployment.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - Produced by OmniGraffle 6.5.2 2016-04-08 01:10:50 +0000DeploymentLayer 1Notary ServersserverserverNotary SignersTUF(server DB)(signer DB) diff --git a/notary/images/trust-pinning-flow.png b/notary/images/trust-pinning-flow.png deleted file mode 100644 index bcfa1fb73d..0000000000 Binary files a/notary/images/trust-pinning-flow.png and /dev/null differ diff --git a/notary/index.md b/notary/index.md deleted file mode 100644 index 9222add533..0000000000 --- a/notary/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: List of Notary Documentation -keywords: docker, notary, trust, image, signing, repository, tuf -title: Notary -notoc: true ---- - -* [Getting Started](getting_started.md) -* [Advanced Usage](advanced_usage.md) -* [Service Architecture](service_architecture.md) -* [Running a Service](running_a_service.md) -* [Configuration files](reference/index.md) -* [Changelog](changelog.md) diff --git a/notary/reference/client-config.md b/notary/reference/client-config.md deleted file mode 100644 index 56b825473d..0000000000 --- a/notary/reference/client-config.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -description: Configuring the Notary client, server and signer. -keywords: docker, notary, notary-client, notary-server, notary server, notary-signer, notary signer -title: Notary client configuration file ---- - -This document is for power users of the [Notary client](../advanced_usage.md) -who want to facilitate CLI interaction or specify custom options. - -The configuration file for Notary client normally resides at `~/.notary/config.json`, -but the path to a different configuration file can be specified using the -`-c` or `--configFile` command line flag. - -## Overview of the file - -In addition to the configuration file format, see the optional password -[environment variables](client-config.md#environment-variables-optional) that the Notary client -can take for ease of use. - -Here is a full client configuration file example; click on the top level -JSON keys to learn more about the configuration section corresponding to that key: - - -
{
-  "trust_dir" : "~/.docker/trust",
-  "remote_server": {
-    "url": "https://my-notary-server.my-private-registry.com",
-    "root_ca": "./fixtures/root-ca.crt",
-    "tls_client_cert": "./fixtures/secure.example.com.crt",
-    "tls_client_key": "./fixtures/secure.example.com.crt"
-  },
-  "trust_pinning": {
-    "certs": {
-      "docker.com/notary": ["49cf5c6404a35fa41d5a5aa2ce539dfee0d7a2176d0da488914a38603b1f4292"]
-    }
-  }
-}
-
- -## trust_dir section (optional) - -The `trust_dir` specifies the location (as an absolute path or a path -relative to the directory of the configuration file) where the TUF metadata -and private keys are stored. - -This is normally defaults to `~/.notary`, but specifying `~/.docker/trust` -facilitates interoperability with content trust. - -This option can be overridden with the command line flag `--trustDir`. - -## remote_server section (optional) - -The `remote_server` specifies how to connect to a Notary server to download -metadata updates and publish metadata changes. - -Remote server example: - -```json -"remote_server": { - "url": "https://my-notary-server.my-private-registry.com", - "root_ca": "./fixtures/root-ca.crt", - "tls_client_cert": "./fixtures/secure.example.com.crt", - "tls_client_key": "./fixtures/secure.example.com.crt" -} -``` - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
urlnoURL of the Notary server: defaults to https://notary.docker.io - This configuration option can be overridden with the command line flag - `-s` or `--server`.
root_cano

The path to the file containing the root CA with which to verify - the TLS certificate of the Notary server, for example if it is self-signed. - The path is relative to the directory of the configuration file.

-

This configuration option can overridden with the command line flag - `--tlscacert`, which would specify a path relative to the current working - directory where the Notary client is invoked.

tls_client_certno

The path to the client certificate to use for mutual TLS with - the Notary server. Must be provided along with tls_client_key - or not provided at all. The path is relative to the directory of the - configuration file.

-

This configuration option can overridden with the command line flag - `--tlscert`, which would specify a path relative to the current working - directory where the Notary client is invoked.

tls_client_keyno

The path to the client key to use for mutual TLS with - the Notary server. Must be provided along with tls_client_cert - or not provided at all. The path is relative to the directory of the - configuration file.

-

This configuration option can overridden with the command line flag - `--tlskey`, which would specify a path relative to the current working - directory where the Notary client is invoked.

- -## trust_pinning section (optional) - -The `trust_pinning` specifies how to bootstrap trust for the root of a -Notary client's trusted collection. - -This section is optional, Notary uses TOFU over HTTPS by default and -trust certificates in the downloaded root file. - -In this section, one can provide specific certificates to pin to, or a CA -to pin to as a root of trust for a GUN. Multiple sections can be specified, -but the pinned certificates take highest priority for validation, followed -by the pinned CA, followed by TOFUS (TOFU over HTTPS). The diagram below -describes this validation flow: - -![validation flow](https://cdn.rawgit.com/docker/notary/27469f01fe244bdf70f34219616657b336724bc3/docs/images/trust-pinning-flow.png) - -Only one trust pinning option is used to validate a GUN even if multiple -sections are specified, and any validation failure results in a failed -bootstrapping of the repo. - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
certsno

Mapping of GUN to certificate IDs to pin to. - Both are strings in the JSON object.

cano

Mapping of GUN prefixes to filepaths containing - the root CA file with which to verify the certificates in the root file. - This file can contain multiple root certificates, bundled in separate - PEM blocks. - The path is relative to the directory of the configuration file.

disable_tofuno

Boolean value determining whether to use trust - on first use when bootstrapping validation on a collection's - root file. This keeps TOFUs on by default.

- -## Environment variables (optional) - -The following environment variables containing signing key passphrases can -be used to facilitate [Notary client CLI interaction](../advanced_usage.md). -If provided, these passwords are used initially to sign TUF metadata. -If the passphrase is incorrect, you are prompted to enter the correct -passphrase. - - -| Environment Variable | Description | -| ----------------------------- | ----------------------------------------- | -|`NOTARY_ROOT_PASSPHRASE` | The root/offline key passphrase | -|`NOTARY_TARGETS_PASSPHRASE` | The targets (an online) key passphrase | -|`NOTARY_SNAPSHOT_PASSPHRASE` | The snapshot (an online) key passphrase | -|`NOTARY_DELEGATION_PASSPHRASE` | The delegation (an online) key passphrase | -|`NOTARY_AUTH` | The notary server credentials: `:` encoded in base64 | - - -If provided, the passphrase in `NOTARY_DELEGATION_PASSPHRASE` -is tried for all delegation roles that notary attempts to sign with. diff --git a/notary/reference/common-configs.md b/notary/reference/common-configs.md deleted file mode 100644 index b00b7364f6..0000000000 --- a/notary/reference/common-configs.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -description: Configuring the notary client, server and signer. -keywords: docker, notary, notary-client, notary-server, notary server, notary-signer, notary signer -title: Configure sections common to Notary server and signer ---- - -The logging and bug reporting configuration options for both Notary server and -Notary signer have the same keys and format. The following sections provide -further detail. - -For full specific configuration information, see the configuration files for the -Notary [server](server-config.md) or [signer](signer-config.md). - -## logging section (optional) - -The logging section sets the log level of the server. If it is not provided, -the signer/server defaults to an ERROR logging level. However if an explicit -value was provided, it must be a valid value. - -Example: - -```json -"logging": { - "level": "debug" -} -``` - -This entire section is optional. However, if you would like to -specify a different log level, then you need the required parameters -below to configure it. - - - - - - - - - - - - -
ParameterRequiredDescription
levelyesOne of "debug", "info", - "warning", "error", "fatal", - or "panic"
- -## reporting section (optional) - -The reporting section contains any configuration for useful for running the -service, such as reporting errors. Currently, Notary only supports reporting errors -to Bugsnag. - -See bugsnag-go for more information -about these configuration parameters. - -```json -"reporting": { - "bugsnag": { - "api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8", - "release_stage": "production" - } -} -``` - -This entire section is optional. If you want to report errors to -Bugsnag, then you need to include a `bugsnag` subsection, along with the -required parameters below, to configure it. - -**Bugsnag reporting:** - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
api_keyyesThe BugSnag API key to use to report errors.
release_stageyesThe current release stage, such as "production". You can - use this value to filter errors in the Bugsnag dashboard.
- -## Related information - -* [Notary Server Configuration File](server-config.md) -* [Notary Signer Configuration File](signer-config.md) diff --git a/notary/reference/index.md b/notary/reference/index.md deleted file mode 100644 index 0241ec5242..0000000000 --- a/notary/reference/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -description: Configuring the notary client, server and signer. -keywords: docker, notary, notary-client, notary-server, notary server, notary-signer, notary signer -title: Notary configuration files ---- - -This document is for power users of the [notary client](../advanced_usage.md), -or for those who are [running their own service](../running_a_service.md) who -want to facilitate CLI interaction or specify custom options. - -You can configure the following aspects of Notary: - -* [Notary Client Configuration File](client-config.md) -* [Notary Server Configuration File](server-config.md) -* [Notary Signer Configuration File](signer-config.md) -* [Configuration sections common to the Notary Server and Signer](common-configs.md) diff --git a/notary/reference/server-config.md b/notary/reference/server-config.md deleted file mode 100644 index ad60f6d123..0000000000 --- a/notary/reference/server-config.md +++ /dev/null @@ -1,410 +0,0 @@ ---- -description: Configuring the notary client, server and signer. -keywords: docker, notary, notary-client, notary-server, notary server, notary-signer, notary signer -title: Notary server configuration file ---- - -This document is for those who are [running their own Notary service](../running_a_service.md) -and want to specify custom options. - -## Overview - -A configuration file is required by Notary server, and the path to the -configuration file must be specified using the `-config` option on the command -line. - -Notary server also allows you to [increase/decrease](server-config.md#hot-logging-level-reload) the logging level without having to restart. - -Here is a full server configuration file example: - -```json -{ - "server": { - "http_addr": ":4443", - "tls_key_file": "./fixtures/notary-server.key", - "tls_cert_file": "./fixtures/notary-server.crt" - }, - "trust-service": { - "type": "remote", - "hostname": "notarysigner", - "port": "7899", - "key_algorithm": "ecdsa", - "tls_ca_file": "./fixtures/root-ca.crt", - "tls_client_cert": "./fixtures/notary-server.crt", - "tls_client_key": "./fixtures/notary-server.key" - }, - "storage": { - "backend": "mysql", - "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true" - }, - "auth": { - "type": "token", - "options": { - "realm": "https://auth.docker.io/token", - "service": "notary-server", - "issuer": "auth.docker.io", - "rootcertbundle": "/path/to/auth.docker.io/cert" - } - }, - "logging": { - "level": "debug" - }, - "reporting": { - "bugsnag": { - "api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8", - "release_stage": "production" - } - }, - "caching": { - "max_age": { - "current_metadata": 300, - "consistent_metadata": 31536000, - } - }, - "repositories": { - "gun_prefixes": ["docker.io/", "my-own-registry.com/"] - } -} -``` - -For details on the `reporting` and `logging` sections, see the documentation on -[common Notary configuration sections](/notary/reference/common-configs/). - -## server section (required) - -Example: - -```json -"server": { - "http_addr": ":4443", - "tls_key_file": "./fixtures/notary-server.key", - "tls_cert_file": "./fixtures/notary-server.crt" -} -``` - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
http_addryesThe TCP address (IP and port) to listen on. Examples: -
    -
  • ":4443" means listen on port 4443 on all IPs (and - hence all interfaces, such as those listed when you run - ifconfig)
    • -
  • "127.0.0.1:4443" means listen on port 4443 on - localhost only. That means that the server is not - accessible except locally (via SSH tunnel, or just on a local - terminal)
    • -
-
tls_key_filenoThe path to the private key to use for - HTTPS. Must be provided together with tls_cert_file, - or not at all. If neither are provided, the server uses HTTP - instead of HTTPS. The path is relative to the directory of the - configuration file.
tls_cert_filenoThe path to the certificate to use for HTTPS. - Must be provided together with tls_key_file, or not - at all. If neither are provided, the server uses HTTP instead - of HTTPS. The path is relative to the directory of the - configuration file.
- - -## trust_service section (required) - -This section configures either a remote trust service, such as -[Notary signer](signer-config.md) or a local in-memory -ED25519 trust service. - -Remote trust service example: - -```json -"trust_service": { - "type": "remote", - "hostname": "notarysigner", - "port": "7899", - "key_algorithm": "ecdsa", - "tls_ca_file": "./fixtures/root-ca.crt", - "tls_client_cert": "./fixtures/notary-server.crt", - "tls_client_key": "./fixtures/notary-server.key" -} -``` - -Local trust service example: - -```json -"trust_service": { - "type": "local" -} -``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
typeyesMust be "remote" or "local"
hostnameyes if remoteThe hostname of the remote trust service
portyes if remoteThe GRPC port of the remote trust service
key_algorithmyes if remoteAlgorithm to use to generate keys stored on the - signing service. Valid values are "ecdsa", - "rsa", and "ed25519".
tls_ca_filenoThe path to the root CA that signed the TLS - certificate of the remote service. This parameter must be - provided if said root CA is not in the system's default trust - roots. The path is relative to the directory of the configuration file.
tls_client_keynoThe path to the private key to use for TLS mutual - authentication. This must be provided together with - tls_client_cert or not at all. The path is relative - to the directory of the configuration file.
tls_client_certnoThe path to the certificate to use for TLS mutual - authentication. This must be provided together with - tls_client_key or not at all. The path is relative - to the directory of the configuration file.
- -## storage section (required) - -The storage section specifies which storage backend the server should use to -store TUF metadata. Only MySQL or an in-memory store is supported. - -DB storage example: - -```json -"storage": { - "backend": "mysql", - "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true" -} -``` - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
backendyesMust be "mysql" or "memory". - If "memory" is selected, the db_url - is ignored.
db_urlyes if not memoryThe - the Data Source Name used to access the DB. - ( include parseTime=true as part of the DSN)
- - -## auth section (optional) - -This sections specifies the authentication options for the server. -Currently, we only support token authentication. - -Example: - -```json -"auth": { - "type": "token", - "options": { - "realm": "https://auth.docker.io", - "service": "notary-server", - "issuer": "auth.docker.io", - "rootcertbundle": "/path/to/auth.docker.io/cert" - } -} -``` - -This entire section is optional. However, if you would like -authentication for your server, then you need the required parameters below to -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). - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
typeyesMust be "token"; all other values result in no - authentication (and the rest of the parameters are ignored)
optionsyesThe options for token auth. See - - the registry token configuration documentation - for the parameter details.
- -## caching section (optional) - -Example: - -```json -"caching": { - "max_age": { - "current_metadata": 300, - "consistent_metadata": 31536000, - } -} -``` - - - - - - - - - - - - -
ParameterRequiredDescription
max_agenoThe max age, in seconds, for caching services to cache - the latest metadata for a role and the metadata by checksum for a - role. This value is set on the cache control headers for - GET-ting metadata. - - `must-revalidate` is also set on the cache control headers - for current metadata, as current metadata may change whenever new - metadata is signed into a repo. - - Consistent metadata should never change, although it may be deleted, - so the max age can be a higher value. -
- -## repositories section (optional) - -Example: - -```json -"repositories": { - "gun_prefixes": ["docker.io/", "my-own-registry.com/"] -} -``` - - - - - - - - - - - - -
ParameterRequiredDescription
gun_prefixesnoA list of GUN prefixes accepted by this - server. POST operations on an image beginning with any other prefix - are rejected with a 400, and GET/DELETE operations are rejected - with a 404. -
- -## Hot logging level reload - -We don't support completely reloading notary configuration files yet at present. What we support for now is: -- increase logging level by signaling `SIGUSR1` -- decrease logging level by signaling `SIGUSR2` - -Example: - -To increase logging level - -```bash -$ kill -s SIGUSR1 PID -``` - -or - -```bash -$ docker container exec -i CONTAINER_ID kill -s SIGUSR1 PID -``` - -To decrease logging level - -```bash -$ kill -s SIGUSR2 PID -``` - -or - -```bash -$ docker container exec -i CONTAINER_ID kill -s SIGUSR2 PID -``` - -PID is the process id of `notary-server` and it may not the PID 1 process if you are running -the container with some kind of wrapper startup script or something. - -You can get the PID of `notary-server` through - -```bash -$ docker container exec CONTAINER_ID ps aux -``` - -or - -```bash -$ ps aux | grep "notary-server -config" | grep -v "grep" -``` - -## Related information - -* [Notary Signer Configuration File](signer-config.md) -* [Configuration sections common to the Notary Server and Signer](common-configs.md) diff --git a/notary/reference/signer-config.md b/notary/reference/signer-config.md deleted file mode 100644 index 8e02abd3c2..0000000000 --- a/notary/reference/signer-config.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -description: Configuring the notary client, server and signer. -keywords: docker, notary, notary-client, notary-server, notary server, notary-signer, notary signer -title: Notary signer configuration file ---- - -This document is for those who are [running their own Notary service](../running_a_service.md) -and want to specify custom options. - -## Overview - -Notary signer [requires environment variables](signer-config.md#environment-variables-required-if-using-mysql) -to encrypt private keys at rest. It also requires a configuration file, the -path to which is specified on the command line using the `-config` flag. - -Here is a full signer configuration file example: - -```json -{ - "server": { - "http_addr": ":4444", - "grpc_addr": ":7899", - "tls_cert_file": "./fixtures/notary-signer.crt", - "tls_key_file": "./fixtures/notary-signer.key", - "client_ca_file": "./fixtures/notary-server.crt" - }, - "logging": { - "level": 2 - }, - "storage": { - "backend": "mysql", - "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true", - "default_alias": "passwordalias1" - }, - "reporting": { - "bugsnag": { - "api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8", - "release_stage": "production" - } - } -} -``` - -For details on the `reporting` and `logging` sections, see the documentation on -[common Notary configuration sections](common-configs.md). - -## server section (required) - -"server" in this case refers to Notary signer's HTTP/GRPC server, not -"Notary server". - -Example: - -```json -{ - "server": { - "http_addr": ":4444", - "grpc_addr": ":7899", - "tls_cert_file": "./fixtures/notary-signer.crt", - "tls_key_file": "./fixtures/notary-signer.key", - "client_ca_file": "./fixtures/notary-server.crt" - } -} -``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
http_addryesThe TCP address (IP and port) to listen for HTTP - traffic on. Examples: -
    -
  • ":4444" means listen on port 4444 on all IPs (and - hence all interfaces, such as those listed when you run - ifconfig)
    • -
  • "127.0.0.1:4444" means listen on port 4444 on - localhost only. That means that the server is not - accessible except locally (via SSH tunnel, or just on a local - terminal)
    • -
-
grpc_addryesThe TCP address (IP and port) to listen for GRPC - traffic. Examples: -
    -
  • ":7899" means listen on port 7899 on all IPs (and - hence all interfaces, such as those listed when you run - ifconfig)
    • -
  • "127.0.0.1:7899" means listen on port 7899 on - localhost only. That means that the server is not - accessible except locally (via SSH tunnel, or just on a local - terminal)
    • -
-
tls_key_fileyesThe path to the private key to use for - HTTPS. The path is relative to the directory of the - configuration file.
tls_cert_fileyesThe path to the certificate to use for - HTTPS. The path is relative to the directory of the - configuration file.
client_ca_filenoThe root certificate to trust for - mutual authentication. If provided, any clients connecting to - Notary signer need a client certificate signed by - this root. If not provided, mutual authentication is not - required. The path is relative to the directory of the - configuration file.
- - -## storage section (required) - -This is used to store encrypted private keys. We only support MySQL or an -in-memory store, currently. - -Example: - -```json -"storage": { - "backend": "mysql", - "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true", - "default_alias": "passwordalias1" -} -``` - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
backendyesMust be "mysql" or "memory". - If "memory" is selected, the db_url - is ignored.
db_urlyes if not memoryThe - the Data Source Name used to access the DB. - (include parseTime=true as part of the DSN)
default_aliasyes if not memoryThis parameter specifies the alias of the current - password used to encrypt the private keys in the DB. All new - private keys are encrypted using this password, which - must also be provided as the environment variable - NOTARY_SIGNER_<DEFAULT_ALIAS_VALUE>. - See the environment variable - section for more information.
- - -## Environment variables (required if using MySQL) - -Notary signer stores the private keys in encrypted form. -The alias of the passphrase used to encrypt the keys is also stored. In order -to encrypt the keys for storage and decrypt the keys for signing, the -passphrase must be passed in as an environment variable. - -For example, the configuration above specifies the default password alias to be -`passwordalias1`. - -If this configuration is used, then you must: - -```bash -export NOTARY_SIGNER_PASSWORDALIAS1=mypassword -``` - -so that that Notary signer knows to encrypt all keys with the passphrase -`mypassword`, and to decrypt any private key stored with password alias -`passwordalias1` with the passphrase `mypassword`. - -Older passwords may also be provided as environment variables. - -Let's say that you wanted to change the password that is used to create new -keys (rotating the passphrase and re-encrypting all the private keys is not -supported yet). - -You could change the config to look like: - -```json -"storage": { - "backend": "mysql", - "db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true", - "default_alias": "passwordalias2" -} -``` - -Then you can set: - -```bash -export NOTARY_SIGNER_PASSWORDALIAS1=mypassword -export NOTARY_SIGNER_PASSWORDALIAS2=mynewfancypassword -``` - -That way, all new keys are encrypted and decrypted using the passphrase -`mynewfancypassword`, but old keys that were encrypted using the passphrase -`mypassword` can still be decrypted. - -The environment variables for the older passwords are optional, but Notary -Signer cannot decrypt older keys if they are not provided, and -attempts to sign data using those keys fail. - - -## Related information - -* [Notary Server Configuration File](server-config.md) -* [Configuration sections common to the Notary server and signer](common-configs.md) diff --git a/notary/resources/ncc_docker_notary_audit_2015_07_31.pdf b/notary/resources/ncc_docker_notary_audit_2015_07_31.pdf deleted file mode 100644 index 725a4a4587..0000000000 Binary files a/notary/resources/ncc_docker_notary_audit_2015_07_31.pdf and /dev/null differ diff --git a/notary/resources/opensslCertGen.sh b/notary/resources/opensslCertGen.sh deleted file mode 100644 index eddbce4ce6..0000000000 --- a/notary/resources/opensslCertGen.sh +++ /dev/null @@ -1,135 +0,0 @@ -#!/usr/bin/env bash - -# Script to be used for generating testing certs only - for a production system, -# a public CA or an internal CA should be used - - -CLIENT_USAGE=$(cat <] - -Example: - ${0} client -o clienttls -EOL -) - -SERVER_USAGE=$(cat < [-o ] - [-r ] - [-a ] [-a ] ... - -Example: - ${0} server -o servertls -n notary-server -a DNS:notaryserver \ - -a DNS:notary_server -a IP:127.0.0.1 -EOL -) - -if [[ -z "${1}" ]]; then - printf "${CLIENT_USAGE}\n\n${SERVER_USAGE}\n\n" - exit 1 -fi - -OPENSSLCNF= -for path in /etc/openssl/openssl.cnf /etc/ssl/openssl.cnf /usr/local/etc/openssl/openssl.cnf; do - if [[ -e ${path} ]]; then - OPENSSLCNF=${path} - fi -done -if [[ -z ${OPENSSLCNF} ]]; then - printf "Could not find openssl.cnf" - exit 1 -fi - -if [[ "${1}" == "client" ]]; then - # Generate client keys - ensure that these keys are NOT CA's, otherwise - # any client that is compromised can sign any number of other client - # certs. - OUT="clienttls" - while getopts "o:" opt "${@:2}"; do - case "${opt}" in - o) - OUT="${OPTARG}" - ;; - *) - printf "${CLIENT_USAGE}" - exit 1 - ;; - esac - done - - openssl genrsa -out "${OUT}.key" 4096 - openssl req -new -key "${OUT}.key" -out "${OUT}.csr" \ - -subj '/C=US/ST=CA/L=San Francisco/O=Docker/CN=Notary Testing Client Auth' - - cat > "${OUT}.cnf" < "${OUT}.cnf" - cat >> "${OUT}.cnf" <> "${OUT}.cnf" - fi - - openssl genrsa -out "${OUT}.key" 4096 - openssl req -new -nodes -key "${OUT}.key" -out "${OUT}.csr" \ - -subj "/C=US/ST=CA/L=San Francisco/O=Docker/CN=${COMMONNAME}" \ - -config "${OUT}.cnf" -extensions "v3_req" - openssl x509 -req -days 3650 -in "${OUT}.csr" -signkey "${OUT}.key" \ - -out "${OUT}.crt" -extensions v3_req -extfile "${OUT}.cnf" -fi diff --git a/notary/resources/tuf_update_flow.jpg b/notary/resources/tuf_update_flow.jpg deleted file mode 100644 index 371088c2b6..0000000000 Binary files a/notary/resources/tuf_update_flow.jpg and /dev/null differ diff --git a/notary/running_a_service.md b/notary/running_a_service.md deleted file mode 100644 index 42c99ad6c9..0000000000 --- a/notary/running_a_service.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -description: Run your own notary service to host arbitrary content signing. -keywords: docker, notary, notary-server, notary server, notary-signer, notary signer -title: Run a Notary service ---- - -This document is for anyone who wants to run their own Notary -service (such as those who want to use Notary with a -private Docker registry). Running a Notary service requires that you are already -familiar with using [Docker Engine](/engine/userguide/) -and [Docker Compose](/compose/). - -## Run a service for testing or 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 -[Notary project](https://github.com/docker/notary). - -```console -$ git clone https://github.com/theupdateframework/notary.git -$ cd notary -$ docker-compose up -``` - -This builds the development Notary server and Notary signer images, and -start up containers for the Notary server, Notary signer, and the MySQL -database that both of them share. The MySQL data is stored in a volume. - -Notary server and Notary signer communicate over mutually authenticated TLS -(using the self-signed testing certs in the repository), and Notary server -listens for HTTPS traffic on port 4443. - -By default, this development Notary server container runs with the testing -self-signed TLS certificates. Before you can successfully connect to -it, you must use the root CA file in `fixtures/root-ca.crt`. - -For example, to connect using OpenSSL: - -```console -$ openssl s_client -connect :4443 -CAfile fixtures/root-ca.crt -no_ssl3 -no_ssl2 -``` - -To connect using the Notary Client CLI, see [Getting Started](getting_started.md). -The version of the Notary server and signer -needs to be greater than or equal to that of the Notary Client CLI to ensure feature compatibility. -For instance, if you use Notary Client CLI 0.2, the server and signer each need -to be at least version 0.2 as well. - -The self-signed certificate's subject name and subject alternative names are -`notary-server`, `notaryserver`, and `localhost`, so if your Docker host is not -on `localhost` (for example if you are using Docker Machine), -update your hosts file such that the name `notary-server` is associated with -the IP address of your Docker host. - -## Advanced configuration options - -Both the Notary server and the Notary signer take -[JSON configuration files](reference/index.md). Pre-built images, such as -the [development images above](running_a_service.md#run-a-service-for-testing-or-development) -provide these configuration files for you with some sane defaults. - -However, for running in production, or if you just want to change those defaults -on your development service, you probably want to change those defaults. - -### Running with different command line arguments - -You can override the `docker run` command for the image if you want to pass -different command line options. Both Notary server and Notary signer take -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](ttps://golang.org/pkg/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. - -- `-logf=` - This flag sets the output format for the logs. Possible - formats are "json" and "logfmt". - - This option cannot be set in the configuration file, since some log - messages are produced on startup before the configuration file has been - read. - -### Specifying your own configuration files - -You can run the images with your own configuration files entirely. -You just need to mount your configuration directory, and then pass the -path to that configuration file as an argument to the `docker run` command. - -### Overriding configuration file parameters using environment variables - -You can also override the parameters of the configuration by -setting environment variables of the form `NOTARY_SERVER_` or -`NOTARY_SIGNER_`. - -`var` is the ALL-CAPS, `"_"`-delimited path of keys from the top level of the -configuration JSON. - -For instance, if you wanted to override the storage URL of the Notary server -configuration: - -```json -{ - "storage": { - "backend": "mysql", - "db_url": "dockercondemo:dockercondemo@tcp(notary-mysql)/dockercondemo" - } -} -``` - -You would need to set the environment variable `NOTARY_SERVER_STORAGE_DB_URL`, -because the `db_url` is in the `storage` section of the Notary server -configuration JSON. - -ou cannot override a key whose value is another map. For instance, setting -`NOTARY_SERVER_STORAGE='{"storage": {"backend": "memory"}}'` does not set -in-memory storage. It just fails to parse. You can only override keys whose -values are strings or numbers. - -For example, let's say that you wanted to run a single Notary server instance: - -- with your own TLS cert and keys -- with a local, in-memory signer service rather than using Notary signer -- using a local, in-memory TUF metadata store rather than using MySQL -- produce JSON-formatted logs - -One way to do this would be: - -1. Generate your own TLS certificate and key as `server.crt` and `server.key`, - and put them in the directory `/tmp/server-configdir`. - -2. Write the following configuration file to `/tmp/server-configdir/config.json`: - -```json -{ - "server": { - "http_addr": ":4443", - "tls_key_file": "./server.key", - "tls_cert_file": "./server.crt" - }, - "trust_service": { - "type": "remote", - "hostname": "notarysigner", - "port": "7899", - "tls_ca_file": "./root-ca.crt", - "key_algorithm": "ecdsa", - "tls_client_cert": "./notary-server.crt", - "tls_client_key": "./notary-server.key" - }, - "storage": { - "backend": "mysql", - "db_url": "server@tcp(mysql:3306)/notaryserver?parseTime=True" - } -} -``` - - NWe include a remote trust service and a database storage - type to demonstrate how environment variables can override - configuration parameters. - -3. Run the following command (assuming you've already built or pulled a Notary server docker image): - -```console -$ docker run \ - -p "4443:4443" \ - -v /tmp/server-configdir:/etc/docker/notary-server/ \ - -e NOTARY_SERVER_TRUST_SERVICE_TYPE=local \ - -e NOTARY_SERVER_STORAGE_BACKEND=memory \ - -e NOTARY_SERVER_LOGGING_LEVEL=debug \ - notary_server \ - -config=/etc/docker/notary-server/config.json \ - -logf=json - -{"level":"info","msg":"Version: 0.2, Git commit: 619f8cf","time":"2016-02-25T00:53:59Z"} -{"level":"info","msg":"Using local signing service, which requires ED25519. Ignoring all other trust_service parameters, including keyAlgorithm","time":"2016-02-25T00:53:59Z"} -{"level":"info","msg":"Using memory backend","time":"2016-02-25T00:53:59Z"} -{"level":"info","msg":"Starting Server","time":"2016-02-25T00:53:59Z"} -{"level":"info","msg":"Enabling TLS","time":"2016-02-25T00:53:59Z"} -{"level":"info","msg":"Starting on :4443","time":"2016-02-25T00:53:59Z"} -``` - -You can do the same using -[Docker Compose](/compose/) by setting volumes, -environment variables, and overriding the default command for the Notary server -containers in the Compose file. - - -## Recommendations for deploying in production - -When moving from development to production there are a number of considerations -that must be made to ensure security and scalability. - -### Certificates - -The Notary repository includes sample certificates in the fixtures directory. -When you initialize a development service using the provided `docker-compose.yml` -file, these sample certificates are used to create a more production like -environment. - -**You must acquire your own certificates to use in a production deployment.** - -The sample private key files in the Notary repository are obviously public knowledge -and using them in a production deployment is highly insecure. - -### Certificate directory - -Notary is a user/client-based system, and it searches for certificates in the -user's home directory, at `~/.docker/trust`. To streamline using Notary from -the command line, create an alias that maps the user's `trust` directory to -the system's `ca-certificates` directory. - -```console -$ alias notary="notary -s https:// -d ~/.docker/trust --tlscacert /usr/local/share/ca-certificates/.crt" -``` - -### Databases - -The server and signer each require a database. These should be separate databases -with different users. The users should be limited in their permissions. We recommend -giving the following MySQL (or equivalent) permissions to the users restricted to -only their own databases: - -- Notary server database user: `SELECT, INSERT, UPDATE, DELETE` -- Notary signer database user: `SELECT, INSERT, DELETE` - -### High Availability - -To increase availability, you can run multiple instances -of both the server and signer applications. These can scale arbitrarily and -independently. The database can also scale independently but this is left as -an exercise for experienced DBAs and Operations teams. A typical deployment -looks like this: - -![Notary server Deployment Diagram](https://cdn.rawgit.com/docker/notary/09f81717080f53276e6881ece57cbbbf91b8e2a7/docs/images/service-deployment.svg) - -In the diagram, a load balancer routes external traffic to a cluster of Notary server -instances. These may make requests to Notary signer instances if either a) signing -is required, or b) key generation is required. The requests from a Notary server -to a Notary signer cluster are router via an internal load balancer. - -Notary can be used with a CDN or other caching system. All GET requests for JSON -files may be cached indefinitely __except__ URLs matching: - -- `*/root.json` -- `*/timestamp.json` - -All other requests for JSON files include sha256 checksums of the file being requested -and are therefore immutable. Requests for JSON files make up the vast majority of -all notary requests. Requests for anything other than a GET of a JSON file should -not be cached. - -## Related information - -* [Notary service architecture](service_architecture.md) -* [Notary configuration files](reference/index.md) diff --git a/notary/service_architecture.md b/notary/service_architecture.md deleted file mode 100644 index b17a2f0d10..0000000000 --- a/notary/service_architecture.md +++ /dev/null @@ -1,373 +0,0 @@ ---- -description: How the three requisite notary components interact -keywords: docker, notary, notary-client, docker content trust, content trust, notary-server, notary server, notary-signer, notary signer, notary architecture -title: Understand the Notary service architecture ---- - -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](https://www.theupdateframework.com/){:target="_blank" rel="noopener" class="_"}, -but here is a brief recap of the TUF roles and corresponding key hierarchy: - -![TUF Key Hierarchy](https://cdn.rawgit.com/docker/notary/09f81717080f53276e6881ece57cbbbf91b8e2a7/docs/images/key-hierarchy.svg){:width="400px"} - -- The root key is the root of all trust. It signs the - [root metadata file](https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L489){:target="_blank" rel="noopener" class="_"}, - 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](https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L604){:target="_blank" rel="noopener" class="_"}, - 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](https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L827){:target="_blank" rel="noopener" class="_"}, - 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](https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L678){:target="_blank" rel="noopener" class="_"}, - which lists filenames in the collection, and their sizes and respective - [hashes](https://en.wikipedia.org/wiki/Cryptographic_hash_function){:target="_blank" rel="noopener" class="_"}. - 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](https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L678){:target="_blank" rel="noopener" class="_"}, - which lists filenames in the collection, and their sizes and respective - [hashes](https://en.wikipedia.org/wiki/Cryptographic_hash_function){:target="_blank" rel="noopener" class="_"}. - These files are used to verify the integrity of some or all of the actual contents of the repository. - They are also used to - delegate trust to other collaborators via lower level [delegation roles](advanced_usage.md#work-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 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/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L348){:target="_blank" rel="noopener" class="_"} -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: - -![Notary Service Architecture Diagram](/notary/images/service-architecture.svg) - -Root, targets, and (sometimes) snapshot metadata are generated and signed by -clients, who upload the metadata to the Notary server. The server is -responsible for: - -- ensuring that any uploaded metadata is valid, signed, and self-consistent -- generating the timestamp (and sometimes snapshot) metadata -- storing and serving to clients the latest valid metadata for any trusted collection - -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){:target="_blank" rel="noopener" class="_"} - and - [encrypted](https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31#section-4.8){:target="_blank" rel="noopener" class="_"} - using [Javascript Object Signing and Encryption](https://github.com/dvsekhvalnov/jose2go){:target="_blank" rel="noopener" class="_"} - 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, -server, and signer: - -![Notary Service Sequence Diagram](https://cdn.rawgit.com/docker/notary/27469f01fe244bdf70f34219616657b336724bc3/docs/images/metadata-sequence.svg) - -1. Notary server optionally supports authentication from clients using - [JWT](https://jwt.io){:target="_blank" rel="noopener" class="_"} 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. - - If token authentication is enabled on Notary server, then any connecting - client that does not have a token is redirected to the authorization - server. - - See the docs for - [Docker Registry v2 authentication]( https://github.com/docker/distribution/blob/master/docs/spec/auth/token.md) - for more information. - -2. The client logs in to the authorization server via basic auth over HTTPS, - obtain a bearer token, and then present the token to Notary server on future - requests. - -3. When clients uploads new metadata files, Notary server checks them against - any previous versions for conflicts, and verifies the signatures, checksums, - and validity of the uploaded metadata. - -4. Once all the uploaded metadata has been validated, Notary server - generates the timestamp (and maybe snapshot) metadata. It sends this - generated metadata to the Notary signer to be signed. - -5. Notary signer retrieves the necessary encrypted private keys from its database - if available, decrypts the keys, and uses them to sign the metadata. If - successful, it sends the signatures back to Notary server. - -6. Notary server is the source of truth for the state of a trusted collection of - data, storing both client-uploaded and server-generated metadata in the TUF - database. The generated timestamp and snapshot metadata certify that the - metadata files the client uploaded are the most recent for that trusted collection. - - Finally, Notary server notifies the client that their upload was successful. - -7. The client can now immediately download the latest metadata from the server, - using the still-valid bearer token to connect. Notary server only needs to - obtain the metadata from the database, since none of the metadata has expired. - - In the case that the timestamp has expired, Notary server would go through - the entire sequence where it generates a new timestamp, request Notary signer - for a signature, stores the newly signed timestamp in the database. It then - sends this new timestamp, along with the rest of the stored metadata, to the - requesting client. - - -## Threat model - -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 - -In the event of a Notary server compromise, an attacker would have direct access to -the metadata stored in the database as well as access to the credentials -used to communicate with Notary signer, and therefore, access to arbitrary signing -operations with any key the Signer holds. - -- **Denial of Service** - An attacker could reject client requests and corrupt - or delete metadata from the database, thus preventing clients from the ability - to download or upload metadata. - -- **Malicious Content** - An attacker can create, store, and serve arbitrary - metadata content for one or more trusted collections. However, the attacker - has no access to any client-side keys, such as root, targets, and potentially - the snapshot keys for the existing trusted collections. - - A client can only be tricked into downloading and trusting the malicious - content for these trusted collections if it has never seen the trusted - collections and does not have any form of pinned trust. - - If a client has previously interacted with any trusted collection or has its - trust pinned to a specific certificate for the collections, the client - immediately detects that the content is malicious and doesn't trust any root, - targets, or (maybe) snapshot metadata for these collections. - -- **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 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. - - Clients both with and without pinned trust would be vulnerable to these - attacks, so long as the attacker ensures that the version number of their - malicious metadata is higher than the version number of the most recent - good metadata that any client may have. - -> **Note**: 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 is mitigated, an attacker cannot generate valid timestamp or -> snapshot metadata and serve them on a malicious mirror, for example. - -### Notary signer compromise - -In the event of a Notary signer compromise, an attacker would have access to -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 - HSM), and thus prevent Notary servers from signing generated - timestamps or snapshots. - -- **Key Compromise** - If the Notary signer uses a database as its backend, - an attacker can exfiltrate all the (timestamp and snapshot) private material. - 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 are 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 compromised. For -example, were the snapshot and targets key both compromised, 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 generates and signs 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 -For example, if `DelegationKey2` in the above key hierarchy is compromised, the -compromised key could -only 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 cannot 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 -generates and signs 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. A key may also -add or remove the capabilities of other delegation keys below it on the key hierarchy -For example, if `DelegationKey2` in the above key hierarchy is compromised, it can -only 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 generates and signs 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, such as `Delegation1`, -`Delegation2`, and `Delegation3` in the key hierarchy diagram. If they remove -the roles entirely, they break the trust chain to the lower delegation roles, -such as `Delegation4` or `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 cannot 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 -generates and signs 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, for example, `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, -such as `Delegation4` or `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 access 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 don't even need to rotate the snapshot and timestamp -keys because the server generates and signs 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 creates 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 -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 - -* [Run a Notary service](running_a_service.md) -* [Notary configuration files](reference/index.md)