diff --git a/docs/notary-server-config.md b/docs/notary-server-config.md index affdeeccef..2fbd7754af 100644 --- a/docs/notary-server-config.md +++ b/docs/notary-server-config.md @@ -87,27 +87,27 @@ Example: tls_key_file no - Specifies 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 will use HTTP instead of HTTPS. - The path is relative to the current working directory where + The 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 will use HTTP + instead of HTTPS. The path is relative to the directory where notary-server is run. tls_cert_file no - Specifies the certificate to use for HTTPS. Must be - provided together with tls_key_file, or not at all. - If neither are provided, the server will use HTTP instead of HTTPS. - The path is relative to the current working directory where - notary-server is run. + The 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 will use HTTP instead + of HTTPS. The path is relative to the directory where notary-server + is run. ### `auth` subsection (optional) This sections specifies the authentication options for the server. -Currently, the only authentication scheme supported is token authentication. +Currently, we only support token authentication. Example: @@ -123,8 +123,9 @@ Example: } ``` -Note that this entire section is optional. However, you would like -authentication, then then the required parameters below are needed configure it. +Note that 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:** @@ -154,11 +155,11 @@ authentication post login.) -## `trust service` section (optional) +## `trust service` section (optional but recommended) -The trust service section must be included in order to specify a remote trust -service. If it is left out, a local in-memory ED25519 trust service will be -used. +This section is required to specify a remote trust service, such as +[Notary Signer](notary-signer.md). If it is left out or invalid, a local +in-memory ED25519 trust service will be used instead. Remote trust service example: @@ -174,9 +175,9 @@ Remote trust service example: } ``` -Note that this entire section is optional. However, you would like to use a -separate trust service (recommended), then then the required parameters below -are needed configure it. +Note that this entire section is optional. However, if you would like to use a +separate trust service (recommended), then you need the required parameters +below to configure it. @@ -187,8 +188,9 @@ are needed configure it. - + @@ -203,42 +205,41 @@ are needed configure it. - + - + - + - - + +
type yesMust be `"remote"`; all other values will result in a - local trust service (and the rest of the parameters will be ignored)Must be "remote"; all other values + will result in a local trust service (and the rest of the + parameters will be ignored)
hostname
key_algorithm yesThe key algorithm/type that will be generated and - stored on the signing service. Valid values are `ecdsa`, `rsa`, - and `ed25519`.Algorithm to use to generate keys stored on the + signing service. Valid values are "ecdsa", + "rsa", and "ed25519".
tls_ca_file noThe root CA or TLS cert of the remote service, if it is - self-signed or otherwise not in the system's default trust roots. - The path is relative to the current working directory where - notary-server is run.The path to the root CA that signed the TLS + certificate of the remote service. This parameter if said root + CA is not in the system's default trust roots. The path is + relative to the directory where notary-server is run.
tls_client_key noThe private key to use for TLS mutual authentication. - Must be provided together with tls_client_cert or not - at all. The path is relative to the current working directory where - notary-server is run.The 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 where notary-server is run.
tls_client_certoptionalThe certificate to use for TLS mutual authentication. - Must be provided together with tls_client_key or not - at all. The path is relative to the current working directory where - notary-server is run.noThe 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 where notary-server is run.
## `logging` section (optional) -The logging section sets the log level of the server. If not provided, or if -any part of this section is invalid, the server defaults to an ERROR logging -level. +The logging section sets the log level of the server. If it is not provided +or invalid, the server defaults to an ERROR logging level. Example: @@ -248,9 +249,9 @@ Example: } ``` -Note that this entire section is optional. However, you would like to -specify a different log level, then then the required parameters below -are needed configure it. +Note that 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. @@ -267,10 +268,11 @@ are needed configure it.
-## `storage` section (optional) +## `storage` section (optional but recommended) -The storage section sets the storage options for the server. If not provided, -an in-memory store will be used. Currently, the only DB supported is MySQL. +The storage section specifies which storage backend the server should use to +store TUF metadata. Currently, we only support MySQL. If this +section is not provided or invalid, an in-memory store will be used instead. DB storage example: @@ -281,9 +283,9 @@ DB storage example: } ``` -Note that this entire section is optional. However, you would like to -use a database backend (recommended), then then the required parameters below -are needed configure it. +Note that this entire section is optional. However, if you would like to +use a database backend (recommended), then you need the required parameters +below to configure it. @@ -302,17 +304,18 @@ are needed configure it. + endpoint the username/credentials
db_url yes The URL used to access the DB, which includes both the - endpoint anusername/credentials
## `reporting` section (optional) -The reporting section contains any configuration for reporting errors, etc. to -services via [logrus hooks](https://github.com/Sirupsen/logrus). Currently the -only supported services is [Bugsnag](https://bugsnag.com). (See -[bugsnag-go](https://github.com/bugsnag/bugsnag-go/) for more information about -configuration. +The reporting section contains any configuration for useful for running the +service, such as reporting errors. Currently, we only support reporting errors +to [Bugsnag](https://bugsnag.com). + +See [bugsnag-go](https://github.com/bugsnag/bugsnag-go/) for more information +about these configuration parameters. ```json "reporting": { @@ -322,8 +325,8 @@ configuration. } ``` -Note that this entire section is optional. However, you would like to -use Bugsnag reporting, then then the required parameters below are needed +Note that this entire section is optional. However, if you would like to +report errors to Bugsnag, then you need the required parameters below to configure it. @@ -341,13 +344,12 @@ configure it. - + - +
bugsnag_api_key yesThe API key to use to report errors - if this value is not set, - no errors will be reported to Bugsnag.The API key to use to report errors.
bugsnag_release_stage yesThe current release stage, such as "production" (which is the - default), used to filter errors in the Bugsnag dashboard.The current release stage, such as "production". You can + use this value to filter errors in the Bugsnag dashboard.
diff --git a/docs/notary-server.md b/docs/notary-server.md index 30626b2269..3a32004199 100644 --- a/docs/notary-server.md +++ b/docs/notary-server.md @@ -10,11 +10,22 @@ parent="mn_notary" # Notary Server -The notary server is a remote store for, and coordinates updates to, the signed -metadata files for a repository (which are created by clients). The server is -also responsible for creating and keeping track of timestamp keys for each repo, -and signing a timestamp file for each repo whenever a client sends updates, -after verifying the root, target, and snapshot signatures on the client update. +The Notary Server stores and updates the signed +[TUF metadata files]( +https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L348) +for a repository. The root, snapshot, and targets metadata files are generated +and signed by clients, and the timestamp metadata file is generated and signed +by the server. + +The server creates and stores timestamp keys for each repository (preferably +using a remote key storage/signing service such as +[Notary Signer](notary-signer.md)). + +When clients upload metadata files, the server checks them for conflicts and +verifies the signatures and key references in the files. If everything +checks out, the server then signs the timestamp metadata file for the +repository, which certifies that the files the client uploaded are the most +recent for that repository. ### Authentication @@ -23,49 +34,54 @@ 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. -The client will log into the server (it gets redirected by Notary Server if -authentication is configured), obtain a token, and present the token to Notary -Server, which should be configured to trust signatures from that authorization +If token authentication is enabled on Notary Server, then any client that +does not have a token will be redirected to the authoriziation server. +The client will log in, obtain a token, and then present the token to +Notary Server on future requests. + +Notary Server should be configured to trust signatures from that authorization server. -See the docs for [Docker Registry v2 authentication]( +Please see the docs for [Docker Registry v2 authentication]( https://github.com/docker/distribution/blob/master/docs/spec/auth/token.md) for more information. ### Server storage -Currently Notary Server uses MySQL as a backend for storing the timestamp -*public* keys and the TUF metadata for each repository. +Notary Server uses MySQL as a backend for storing the timestamp +public keys and the TUF metadata for each repository. It relies on a signing +service to store the private keys. ### Signing service -The recommended usage of the server is with a separate signing service: -[Notary Signer](notary-signer.md). The signing service actually -stores the timestamp *private* keys and performs signing for the server. +We recommend deploying Notary Server with a separate, remote signing +service: [Notary Signer](notary-signer.md). This signing service generates +and stores the timestamp private keys and performs signing for the server. -By using a signing service, the private keys then would never be stored on the -server itself. +By using remote a signing service, the private keys would never need to be +stored on the server itself. Notary Signer supports mutual authentication - when you generate client -certificates for Notary Server to authenticate with Notary Signer, please make -sure that the certificates **are not CAs**. Otherwise any server that is -compromised can sign any number of other client certs. +certificates for your deployment of Notary Server, please make +sure that the certificates **are not CAs**. Otherwise if the server is +compromised, it can sign any number of other client certs. As an example, please see [this script](opensslCertGen.sh) to see how to generate client SSL certs with basic constraints using OpenSSL. -### How to configure and run notary server +### How to configure and run Notary Server A JSON configuration file is used to configure Notary Server. Please see the [Notary Server configuration document](notary-server-config.md) for more details about the format of the configuration file. -The parameters of the configuration file can also be overwritten using -environment variables of the form `NOTARY_SERVER_var`, where `var` is the -full path from the top level of the configuration file to the variable you want -to override, in all caps. A change in level is denoted with a `_`. +You can also override the parameters of the configuration by +setting environment variables of the form `NOTARY_SERVER_var`. +`var` is the ALL-CAPS, `"_"`-delimited path of keys from the top level of the +configuration JSON. -For instance, one part of the configuration file might look like: +For instance, if you wanted to override the storage URL of the Notary Server +configuration: ```json "storage": { @@ -74,19 +90,20 @@ For instance, one part of the configuration file might look like: } ``` -If you would like to specify a different `db_url`, the full path from the top -of the configuration tree is `storage -> db_url`, so the environment variable -to set would be `NOTARY_SERVER_STORAGE_DB_URL`. +the full path of keys is `storage -> db_url`. So the environment variable you'd +need to set would be `NOTARY_SERVER_STORAGE_DB_URL`. -Note that you cannot override an intermediate level name. Setting -`NOTARY_SERVER_STORAGE=""` will not disable the MySQL storage. Each leaf -parameter value must be set indepedently. +Note that you cannot override a key whose value is another map. +For instance, setting `NOTARY_SERVER_STORAGE=""` will not disable the +MySQL storage. You can only override keys whose values are strings or numbers. #### Running a Docker image -Get the official Docker image, which comes with some sane defaults. You can -run it with your own signer service and mysql DB, or in the example below, with -just a local signing service and memory store: +Get the official Docker image, which comes with [some defaults]( +https://github.com/docker/notary/blob/master/cmd/notary-server/config.json). +You can override the default configuration with environment variables. +For example, if you wanted to run it with just a local signing service and +memory store (not recommended for production): ``` $ docker pull docker.io/docker/notary-server @@ -97,9 +114,10 @@ $ docker run -p "4443:4443" \ notary-server ``` -Alternately, you can run with your own configuration file entirely. The -docker image loads the config file from `/opt/notary-server/config.json`, so -you can mount your config file at `/opt/notary-server`: +Alternately, you can run the image with your own configuration file entirely. +The docker image loads the config file from `/opt/notary-server/config.json`, +so you can mount a directory with your config file (named `config.json`) +at `/opt/notary-server`: ``` $ docker run -p "4443:4443" -v /path/to/config/dir:/opt/notary-server notary-server @@ -108,7 +126,7 @@ $ docker run -p "4443:4443" -v /path/to/config/dir:/opt/notary-server notary-ser #### Running the binary A JSON configuration file needs to be passed as a parameter/flag when starting up the Notary Server binary. Environment variables can also be set in addition -to the configuration file, but the configuration file is required. +to the configuration file, but the configuration file is required. For example: ``` $ export NOTARY_SERVER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname @@ -117,35 +135,37 @@ $ NOTARY_SERVER_LOGGING_LEVEL=info notary-server -config /path/to/config.json ### What happens if the server is compromised -The server does not hold any keys for the repository except the timestamp key, -so the attacker cannot modify the root, targets, or snapshots metadata. +The server does not hold any keys for repositories, except the for timestamp +keys if you are using a local signing service, so the attacker cannot modify +the root, targets, or snapshots metadata. -If using a signer service, an attacker cannot get access to the timestamp key. -They can use the server to make calls to the signer service to sign arbitrary -data, such as an empty timestamp, an invalid timestamp, or an old timestamp. +If you are using a signer service, an attacker cannot get access to the +timestamp key either. They can use the server's credentials to get the signer +service to sign arbitrary data, such as an empty timestamp, +an invalid timestamp, or an old timestamp. -TOFU (trust on first use) would prevent the attacker from being able to make -existing clients for existing repositories download arbitrary data. They would -need the original root/target/snapshots keys. The attacker could, by signing -bad timestamps, prevent the user from seeing any updated metadata. +However, TOFU (trust on first use) would prevent the attacker from tricking +existing clients for existing repositories to download arbitrary data. +They would need the original root/target/snapshots keys to do that. The +attacker could only, by signing bad timestamps, prevent the such a user from +seeing any updated metadata. The attacker can also make all new keys, and simply replace the repository metadata with metadata signed with these new keys. New clients who have not -seen this repository before will trust this bad data, but older clients will +seen the repository before will trust this bad data, but older clients will know that something is wrong. ### Ops features -Notary server provides the following endpoints for ops friendliness: +Notary server provides the following endpoints for operational friendliness: 1. A health endpoint at `/_notary_server/health` which returns 200 and a - body of `{}` if the server is healthy, and a 500 with a list of + body of `{}` if the server is healthy, and a 500 with a map of failed services if the server cannot access its storage backend. - If it cannot contact the signing service (in which case service is degraded, - but not down, since the server can still serve metadata, but not accept - updates), an error will be logged, but the service will still be considered - healthy. + If it cannot contact the signing service, an error will be logged but the + service will still be considered healthy, because it can still serve + existing metadata. It cannot accept updates, so the service is degraded. 1. A [Bugsnag](https://bugsnag.com) hook for error logs, if a Bugsnag configuration is provided. diff --git a/docs/notary-signer-config.md b/docs/notary-signer-config.md index d4ff34b853..0cec02fb77 100644 --- a/docs/notary-signer-config.md +++ b/docs/notary-signer-config.md @@ -27,13 +27,6 @@ An example (full) server configuration file. "storage": { "backend": "mysql", "db_url": "dockercondemo:dockercondemo@tcp(notarymysql:3306)/dockercondemo" - }, - "reporting": { - "bugsnag": { - "api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8", - "release_stage": "staging", - "endpoint": "https://bugsnag.internal:49000/" - } } } ``` @@ -77,7 +70,7 @@ Example: grpc_addr yes The TCP address (IP and port) to listen for GRPC - traffic (which Notary Server uses) on. Examples: + traffic. Examples: