centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-03-31 16:28:59 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #606 from docker/doc-fixes

Browse Source 
Documentation fixes
This commit is contained in:
David Lawrence
2016-03-02 17:10:46 -08:00
parent d7c93d7797 638d2f09c8
commit dfeb51f54f
10 changed files with 134 additions and 223 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/advanced_usage.md
View File

@@ -24,9 +24,9 @@ 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 Repository</a>
## Initialize a Trusted Collection</a>
Before adding and signing content to a repository, you must first initialize that repository.
Before adding and signing content to a collection, you must first initialize that collection.
```
$ notary init example.com/collection
@@ -44,30 +44,30 @@ 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 repository will generate the following items; all keys use
Initializing a trusted collection will generate 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 will be generated. This key will be used as the default root of trust for all your repositories.
- A targets key and a snapshot key. The same password is used to encrypt both of these as the security profile of them (when both held by the author of the repository) is identical. This is why you will not be asked for a snapshot key password.
- If no root key is found, an initial root key will be generated. This key will be used as the default root of trust for all your trusted collections.
- A targets key and a snapshot key. The same password is used to encrypt both of these as the security profile of them (when both held by the author of the trusted collection) is identical. This is why you will not be asked 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 will sign timestamps on behalf of the user.
- Stub signed notary metadata. This stages the base version of the trust metadata for the repository. It will be finalized when it is published to the server.
- Stub signed notary metadata. This stages the base version of the trust metadata for the collection. It will be finalized when it is published to the server.
## Add and remove Targets
It's simple to add targets to a repository with notary CLI:
It's simple to add targets to a trusted collection with notary CLI:
```
$ notary add example.com/collection v1 my_file.txt
```
The above command adds the local file `my_file.txt` (this file must exist relative to the current working directory) under the target name `v1` to the `example.com/collection` repository we set up. The contents of the local file are not actually added to the repository - a "target" consists of the
The above command adds the local file `my_file.txt` (this file 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.
Note that 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.
```
$ notary add example.com/collection v1
$ 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.
@@ -76,7 +76,7 @@ Removing a target is also an offline command that requires a `notary publish exa
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 repository. The keys are located in the notary `trust_dir`
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.
@@ -92,15 +92,14 @@ In case of potential compromise, notary provides a CLI command for rotating keys
While the snapshot key is managed by the notary client by default, use the `notary key
rotate -r` command to rotate the snapshot key to the server, such that the
notary server will then sign snapshots. This is particularly useful when using
delegations with a repository, so that delegates will never need access to the
snapshot key to push their updates to the repository.
delegations with a trusted collection, so that delegates will never need access to the
snapshot key to push their updates to the collection.
### Use a Yubikey
Notary can be used with [Yubikey
4](https://www.yubico.com/products/yubikey-hardware/yubikey4/) keys, via the
PKCS11 interface with CCID-enabled PIV. The Yubikey will be prioritized to store
root keys, and will require user touch-input for signing.
4](https://www.yubico.com/products/yubikey-hardware/yubikey4/) keys, via a PKCS11 interface when the Yubikey has CCID mode enabled.
The Yubikey will be prioritized to store root keys, and will require user touch-input for signing.
>**Note**: Yubikey support for signing docker images is only supported in the experimental branch.
@@ -110,25 +109,28 @@ library locations.
## Work with delegation roles
Delegation roles simplify collaborator workflows in notary repositories, and
also allow for fine-grained permissions within a repository's contents across
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 repository administrator having to share the
his own private key without the administrator having to share the
targets key or allow a collaborator write access to all targets of the
repository.
collection.
Before adding any delegations, you should rotate the snapshot key to the server.
This is such that delegation roles will not require the snapshot key to publish
their own targets to the repository, since the server can publish the valid
their own targets to the collection, since the server can publish the valid
snapshot with the delegation targets:
```
$ notary key rotate example.com/collection -r --key-type=snapshot
```
Here, `-r` specifies to rotate the key to the remote server, and `--key-type` (shorthand `-t`)
specifies the role.
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 will assume this
delegation role must hold the private key to sign content with notary.
@@ -140,16 +142,18 @@ for this user:
$ notary delegation add example.com/collection targets/releases cert.pem --paths="delegation/path"
```
In the preceding example, illustrates a request to add the delegation
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.
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`. You can add more paths in a comma-separated list under
`delegation/path`. With the given path of "delegation/path", the targets/releases
role would be able to sign paths like "delegation/path/content.txt", "delegation/path_file.txt"
and "delegation/path.txt". You can add more paths in a comma-separated list under
`--paths`, or pass the `--all-paths` flag to allow this delegation to publish
content under any pathname.
@@ -165,7 +169,7 @@ $ notary delegation list example.com/collection
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. To remove a delegation role entirely, or just individual keys and/or paths, use the `notary delegation remove` command:
A threshold of `1` indicates that only one of the keys specified in `KEY IDS` is required to publish to this delegation. Thresholds other than 1 are not currently supported. To remove a delegation role entirely, or just individual keys and/or paths, use the `notary delegation remove` command:
```
$ notary delegation remove example.com/user targets/releases
@@ -193,8 +197,8 @@ the `role` PEM header set to `user`.
$ 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
repository "example/collections" staged for next publish. The file
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.
@@ -218,14 +222,14 @@ other delegation roles will be supported in a future release. By default, Engine
`targets/releases` role if it exists; if it does not exist, the Engine will
fall back to retrieving images signed by the default `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 path should be restricted to the image's tag. By default, pushing with Docker Content Trust will attempt to add to the `targets/releases` role and will fallback to `targets` if the delegation does not exist.
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. By default, pushing with Docker Content Trust will attempt to add to the `targets/releases` role and will fallback to `targets` _only_ if the delegation does not exist.
# Files and state on disk
Notary stores state in its `trust_dir` directory, which is `~/.notary` by
default or usually `~/.docker/trust` when enabling content trust. Within this
directory, `trusted_certificates` stores certificates for bootstrapping trust in
a repository, `tuf` stores TUF metadata and changelists to applied for a GUN,
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

6
docs/changelog.md
View File

@@ -14,8 +14,8 @@ weight=99
## v0.2
#### 2/24/2016
Adds support for [delegation roles](https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L387) in TUF.
Delegations allow for easier key management amongst collaborators in a notary repository, 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 repository.
Delegations allow for easier key management amongst collaborators in a notary trusted collection, and fine-grained permissions on what content each delegate is allowed to modify and sign.
This version also supports managing the snapshot key on notary server, which should be used when enabling delegations on a trusted collection.
Moreover, this version also adds more key management functionality to the notary CLI, and changes the docker-compose development configuration to use the official MariaDB image.
> Detailed release notes can be found here: [v0.2 release notes](https://github.com/docker/notary/releases/tag/v0.2.0).
@@ -23,6 +23,6 @@ Moreover, this version also adds more key management functionality to the notary
## 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 repository.
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).

4
docs/getting_started.md
View File

@@ -26,7 +26,7 @@ insight you can provide regarding issues.
## Understand Notary naming
Notary uses Globally Unique Names (GUNs) to identify trust repositories. To
Notary uses Globally Unique Names (GUNs) to identify trust collections. To
enable Notary to run in a multi-tenant fashion, you must use 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:
@@ -80,7 +80,7 @@ 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 the Notary CLI uses. To request the mapping of tag
Notary library (the same one as Notary CLI) to request the mapping of tag
to sha256 digest for the one tag you are interested in (or if you passed the
`--all` flag, the client will use the list operation to efficiently retrieve all
the mappings). Having validated the signatures on the trust data, the client

45
docs/reference/client-config.md
View File

@@ -1,6 +1,6 @@
<!--[metadata]>
+++
title = "Client configuration"
title = "Client Configuration"
description = "Configuring the Notary client, server and signer."
keywords = ["docker, notary, notary-client, notary-server, notary server, notary-signer, notary signer"]
[menu.main]
@@ -11,9 +11,8 @@ weight=4
# Notary client configuration file
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.
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
@@ -21,38 +20,24 @@ but the path to a different configuration file can be specified using the
## Overview of the file
A configuration file consists of the following sections:
In addition to the configuration file format, please see the optional password
[environment variables](#environment-variables-optional) that the Notary client
can take for ease of use.
<table>
<tr>
<td><a href="#trust-dir-section-optional">trust_dir</a></td>
<td>TUF key and metadata directory</td>
<td>(optional)</td>
</tr>
<tr>
<td><a href="#remote-server-section-optional">remote_server</a></td>
<td>remote Notary Server configuration</td>
<td>(optional)</td>
</tr>
</table>
Here is a full client configuration file example; please click on the top level
JSON keys to learn more about the configuration section corresponding to that key:
In addition please see the optional password [environment
variables](#environment-variables-optional) that the Notary client can take for
ease of use.
An example (full) clietn configuration file.
```json
{
"trust_dir" : "~/.docker/trust",
"remote_server": {
<pre><code class="language-json">{
<a href="#trust-dir-section-optional">"trust_dir"</a> : "~/.docker/trust",
<a href="#remote-server-section-optional">"remote_server"</a>: {
"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"
}
}
```
</code></pre>
## trust_dir section (optional)
@@ -142,9 +127,3 @@ passphrase.
|`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 |
## Related information
* [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)

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

@@ -11,10 +11,6 @@ weight=5
# Configure sections common to Notary server and signer
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.
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.
@@ -99,6 +95,5 @@ required parameters below, to configure it.
## Related information
* [Server Configuration File](server-config.md)
* [Notary Client Configuration File](client-config.md)
* [Notary Server Configuration File](server-config.md)
* [Notary Signer Configuration File](signer-config.md)

2
docs/reference/index.md
View File

@@ -18,7 +18,7 @@ want to facilitate CLI interaction or specify custom options.
You can configure the following aspects of Notary:
* [Server Configuration File](server-config.md)
* [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)

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

@@ -10,12 +10,8 @@ parent="mn_notary_config"
# Notary server configuration file
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.
For full specific configuration information, see the [common configuration
file](common-configs.md) for the Notary server and signer.
This document is for those who are [running their own Notary service](../running_a_service.md) who
want to specify custom options.
## Overview
@@ -23,51 +19,16 @@ 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.
The configuration file consists of the following sections:
Here is a full server configuration file example; please click on the top level JSON keys to
learn more about the configuration section corresponding to that key:
<table>
<tr>
<td><a href="#server-section-required">server</a></td>
<td>HTTPS configuration</td>
<td>(required)</td>
</tr>
<tr>
<td><a href="#trust-service-section-required">trust_service</a></td>
<td>signing service configuration</td>
<td>(required)</td>
</tr>
<tr>
<td><a href="#storage-section-required">storage</a></td>
<td>TUF metadata storage configuration</td>
<td>(required)</td>
</tr>
<tr>
<td><a href="#auth-section-optional">auth</a></td>
<td>server authentication configuration</td>
<td>(optional)</td>
</tr>
<tr>
<td><a href="../common-configs/#logging-section-optional">logging</a></td>
<td>logging configuration</td>
<td>(optional)</td>
</tr>
<tr>
<td><a href="../common-configs/#reporting-section-optional">reporting</a></td>
<td>ops/reporting configuration</td>
<td>(optional)</td>
</tr>
</table>
An example (full) server configuration file.
```json
{
"server": {
<pre><code class="language-json">{
<a href="#server-section-required">"server"</a>: {
"http_addr": ":4443",
"tls_key_file": "./fixtures/notary-server.key",
"tls_cert_file": "./fixtures/notary-server.crt"
},
"trust_service": {
<a href="#trust-service-section-required">"trust_service"</a>: {
"type": "remote",
"hostname": "notarysigner",
"port": "7899",
@@ -76,11 +37,11 @@ An example (full) server configuration file.
"tls_client_cert": "./fixtures/notary-server.crt",
"tls_client_key": "./fixtures/notary-server.key"
},
"storage": {
<a href="#storage-section-required">"storage"</a>: {
"backend": "mysql",
"db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true"
},
"auth": {
<a href="#auth-section-optional">"auth"</a>: {
"type": "token",
"options": {
"realm": "https://auth.docker.io/token",
@@ -89,17 +50,17 @@ An example (full) server configuration file.
"rootcertbundle": "/path/to/auth.docker.io/cert"
}
},
"logging": {
<a href="../common-configs/#logging-section-optional">"logging"</a>: {
"level": "debug"
},
"reporting": {
<a href="../common-configs/#reporting-section-optional">"reporting"</a>: {
"bugsnag": {
"api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
"release_stage": "production"
}
}
}
```
</code></pre>
## server section (required)
@@ -158,7 +119,7 @@ Example:
## trust_service section (required)
This section configures either a remote trust service, such as
[Notary signer](#notary-signer-configuration-file) or a local in-memory
[Notary signer](signer-config.md) or a local in-memory
ED25519 trust service.
Remote trust service example:
@@ -299,8 +260,8 @@ configure it.
**Token authentication:**
This is an implementation of the same authentication used by
[docker registry](https://github.com/docker/distribution). (JWT token-based
This is an implementation of the same authentication used by version 2 of the
[Docker registry](https://github.com/docker/distribution). (JWT token-based
authentication post login.)
<table>
@@ -327,6 +288,5 @@ authentication post login.)
## Related information
* [Notary Client Configuration File](client-config.md)
* [Notary Signer Configuration File](signer-config.md)
* [Configuration sections common to the Notary Server and Signer](common-configs.md)

59
docs/reference/signer-config.md
View File

@@ -11,72 +11,42 @@ parent="mn_notary_config"
# Notary signer configuration file
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.
This document is for those who are [running their own Notary service](../running_a_service.md) who
want to specify custom options.
## Overview
Notary signer [requires environment
variables](#environment-variables-required-if-using-mysql) to encrypt private
keys at rest. It also requires a configuration file, the path to which is
Notary signer [requires environment variables](#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.
A Notary signer configuration file consists of the following sections:
Here is a full signer configuration file example; please click on the top level JSON keys to
learn more about the configuration section corresponding to that key:
<table>
<tr>
<td><a href="#server-section-required">server</a></td>
<td>HTTPS and GRPC configuration</td>
<td>(required)</td>
</tr>
<tr>
<td><a href="#storage-section-required">storage</a></td>
<td>TUF metadata storage configuration</td>
<td>(required)</td>
</tr>
<tr>
<td><a href="../common-configs/#logging-section-optional">logging</a></td>
<td>logging configuration</td>
<td>(optional)</td>
</tr>
<tr>
<td><a href="../common-configs/#reporting-section-optional">reporting</a></td>
<td>ops/reporting configuration</td>
<td>(optional)</td>
</tr>
</table>
See the [environment variables](#environment-variables-required-if-using-mysql)
to encrypt private keys at rest.
An example (full) server configuration file.
```json
{
"server": {
<pre><code class="language-json">{
<a href="#server-section-required">"server"</a>: {
"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": {
<a href="../common-configs/#logging-section-optional">"logging"</a>: {
"level": 2
},
"storage": {
<a href="#storage-section-required">"storage"</a>: {
"backend": "mysql",
"db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true",
"default_alias": "passwordalias1"
},
"reporting": {
<a href="../common-configs/#reporting-section-optional">"reporting"</a>: {
"bugsnag": {
"api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
"release_stage": "production"
}
}
}
```
</code></pre>
## server section (required)
@@ -203,7 +173,7 @@ Example:
private keys will be encrypted using this password, which
must also be provided as the environment variable
<code>NOTARY_SIGNER_&lt;DEFAULT_ALIAS_VALUE&gt;</code>.
Please see the <a href="#notary-signer-envvars">environment variable</a>
Please see the <a href="#environment-variables-required-if-using-mysql">environment variable</a>
section for more information.</td>
</tr>
</table>
@@ -261,6 +231,5 @@ attempts to sign data using those keys will fail.
## Related information
* [Server Configuration File](server-config.md)
* [Notary Client Configuration File](client-config.md)
* [Notary Server Configuration File](server-config.md)
* [Configuration sections common to the Notary server and signer](common-configs.md)

16
docs/running_a_service.md
View File

@@ -11,8 +11,8 @@ weight=4
# Run a Notary service
This document is for anyone who wants to [run their own Notary
service](running_a_service.md) (such as those who want to use Notary with a
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](https://docs.docker.com/engine/userguide/)
and [Docker Compose](https://docs.docker.com/compose/overview/).
@@ -30,7 +30,7 @@ $ docker-compose up
```
This will build the development Notary server and Notary signer images, and
start up a containers for the Notary server, Notary signer, and the MySQL
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
@@ -51,7 +51,7 @@ To connect using the Notary Client CLI, please see [Getting Started](getting_sta
documentation.
The self-signed certificate's subject name and subject alternative names are
`notary-server`, `notaryserver`, and `localhost`, so if your Docker host not
`notary-server`, `notaryserver`, and `localhost`, so if your Docker host is not
on localhost (for example if you are using Docker Machine), you'll need to
update your hosts file such that the name `notary-server` is associated with
the IP address of your Docker host.
@@ -60,8 +60,8 @@ the IP address of your Docker host.
Both the Notary server and the Notary signer take
[JSON configuration files](reference/index.md). Pre-built images, such as
the [development images above](#notary-service-temp) provide these configuration
files for you with some sane defaults.
the [development images above](#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.
@@ -199,9 +199,9 @@ 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.
**You must acquire _your_ _own_ _certificates_ to use in a production deployment.**
The private key files in the Notary repository are obviously public knowledge
The sample private key files in the Notary repository are obviously public knowledge
and using them in a production deployment is highly insecure.
### Databases

88
docs/service_architecture.md
View File

@@ -21,7 +21,7 @@ Framework](https://theupdateframework.github.io/).
A Notary service consists of a Notary server, which stores and updates the
signed [TUF metadata files](
https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L348)
for multiple repositories 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
diagram illustrates this architecture:
@@ -33,7 +33,7 @@ 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 repository
- storing and serving to clients the latest valid metadata for any trusted collection
The Notary signer is responsible for:
@@ -79,23 +79,22 @@ sever, and signer:
generates the timestamp (and maybe snapshot) metadata. It sends this
generated metadata to the Notary signer to be signed.
5. Notary signer gets the requisite encrypted private keys from its database if
it has them, decrypts the keys, and uses them to sign the metadata. If
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 stores all the signed metadata, 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 repository.
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 will notify 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 is expired
yet.
obtain the metadata from the database, since none of the metadata has expired.
If the timestamp were expired, for example, Notary server would go through
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
@@ -104,53 +103,57 @@ sever, and signer:
## Threat model
Both the server and the signer are possible attack vectors. This section
discusses how the architecture responds when compromised.
Both the server and the signer are potential attack vectors. This section
discusses how our architecture is designed to deal with compromises.
## Notary server compromise
### Notary server compromise
In the event of a Notary server compromise, an attacker would have access to
the metadata stored in the database as well as access to Notary signer to
sign anything with any key the Signer holds.
In the event of a Notary server compromise, an attacker would have direct access to
the metadata stored in the database as well 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 being
or delete metadata from the database, thus preventing clients from being
able to download or upload metadata.
- **Malicious Content** - An attacker can create, store, and serve arbitrary
metadata content for one or more repositories. However, they do not have
access to the original root, target, or (maybe) snapshots keys for
existing repositories.
metadata content for one or more trusted collections. However, they do not have
access to any client-side keys, such as root, targets, and potentially the
snapshot keys for the existing trusted collections.
Only clients who have never seen, and do not have any form of pinned trust
for, the compromised repositories can be tricked into downloading and
trusting the malicious content for these repositories.
Only clients who have never seen the trusted collections, and who do not have any
form of pinned trust, can be tricked into downloading and
trusting the malicious content for these trusted collections.
Clients who have pinned trust for the compromised repositories, either
due to configuration or due to TOFU (trust on first use), will immediately
Clients that have previously interacted with any trusted collection, or that have
their trust pinned to a specific certificate for the collections will immediately
detect that the content is malicious and would not trust any root, targets,
or (maybe) snapshot metadata for these repositories.
or (maybe) snapshot metadata for these collections.
- **Rollback, Mix and Match** - The attacker can request that
the Notary signer sign whatever timestamp (and maybe snapshot) metadata
they want. They can create valid timestamp and snapshot metadata that
certifies that the latest version of the repository contains
strictly older, or even a mix of older and newer, data.
- **Rollback, Freeze, Mix and Match** - The attacker can request that
the Notary signer sign any arbitrary timestamp (and maybe snapshot) metadata
they want. Attackers can lauch a freeze attack, and, depending on whether
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.
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 that the timestamp and snapshot keys are never compromised; once the
Server compromise is mitigated, an attacker will not be able to generate
valid timestamp or snapshot metadata and serve them on a malicious mirror, for
example.
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 is mitigated, an attacker will not be
able to 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 private keys stored in a database. If the keys are stored in an HSM,
they would have the ability to interfere with the keys in the HSM, but not
to exfiltrate the private keys.
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
@@ -158,9 +161,10 @@ to exfiltrate the private keys.
timestamps or snapshots.
- **Key Compromise** - If the Notary signer uses a database as its backend,
an attacker can exfiltrate all the private keys. This will let them set
up a malicious mirror to perform rollback and mix and match attacks,
for instance.
an attacker can exfiltrate all the private material. Note that the capabilities
of an attacker are the same as of a Notary server compromise in terms of
signing arbitrary metadata, with the important detail that in this particular
case key rotations will be necessary to recover from the attack.
## Related information