diff --git a/README.md b/README.md index cc2d7c2f2a..975099248c 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ received content. ## Goals -Notary is based on [The Update Framework](http://theupdateframework.com/), a secure general design for the problem of software distribution and updates. By using TUF, notary achieves a number of key advantages: +Notary is based on [The Update Framework](https://www.theupdateframework.com/), a secure general design for the problem of software distribution and updates. By using TUF, notary achieves a number of key advantages: * **Survivable Key Compromise**: Content publishers must manage keys in order to sign their content. Signing keys may be compromised or lost so systems must be designed in order to be flexible and recoverable in the case of key compromise. TUF's notion of key roles is utilized to separate responsibilities across a hierarchy of keys such that loss of any particular key (except the root role) by itself is not fatal to the security of the system. * **Freshness Guarantees**: Replay attacks are a common problem in designing secure systems, where previously valid payloads are replayed to trick another system. The same problem exists in the software update systems, where old signed can be presented as the most recent. notary makes use of timestamping on publishing so that consumers can know that they are receiving the most up to date content. This is particularly important when dealing with software update where old vulnerable versions could be used to attack users. diff --git a/docs/advanced_usage.md b/docs/advanced_usage.md index 48fd5f4b56..7e91da6897 100644 --- a/docs/advanced_usage.md +++ b/docs/advanced_usage.md @@ -102,14 +102,16 @@ The targets key must be locally managed - to rotate the targets key, for instanc ### Use a Yubikey -Notary can be used with [Yubikey -4](https://www.yubico.com/products/yubikey-hardware/yubikey4/) keys, via a PKCS11 interface when the Yubikey has CCID mode enabled. +Notary can be used with +Yubikey +4 keys, via a PKCS11 interface when the Yubikey has CCID mode enabled. The Yubikey will be prioritized to store root keys, and will require user touch-input for signing. >**Note**: Yubikey support for signing docker images is only supported in the experimental branch. -Yubikey support requires [Yubico PIV libraries (which are bundled with the PIV -tools)](https://www.yubico.com/support/downloads) to be available in standard +Yubikey support requires +Yubico PIV libraries +(which are bundled with the PIV tools) to be available in standard library locations. ## Work with delegation roles diff --git a/docs/changelog.md b/docs/changelog.md index 533480c164..cb23bf6d2e 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -13,16 +13,20 @@ weight=99 ## v0.2 #### 2/24/2016 -Adds support for [delegation roles](https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L387) in TUF. +Adds support for +delegation +roles in TUF. Delegations allow for easier key management amongst collaborators in a notary trusted collection, and fine-grained permissions on what content each delegate is allowed to modify and sign. This version also supports managing the snapshot key on notary server, which should be used when enabling delegations on a trusted collection. Moreover, this version also adds more key management functionality to the notary CLI, and changes the docker-compose development configuration to use the official MariaDB image. -> Detailed release notes can be found here: [v0.2 release notes](https://github.com/docker/notary/releases/tag/v0.2.0). +> Detailed release notes can be found here: +v0.2 release notes. ## v0.1 #### 11/15/2015 Initial notary non-alpha release. Implements The Update Framework (TUF) with root, targets, snapshot, and timestamp roles to sign and verify content of a trusted collection. -> Detailed release notes can be found here: [v0.1 release notes](https://github.com/docker/notary/releases/tag/v0.1). +> Detailed release notes can be found here: +v0.1 release notes. diff --git a/docs/getting_started.md b/docs/getting_started.md index 78920d805a..36dcdf379a 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -24,16 +24,17 @@ 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)](http://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. +The Update Framework (TUF) +as the underlying security framework, Notary takes care of the operations necessary +to create, manage and distribute the metadata necessary to ensure the integrity and +freshness of your content. ## Install Notary You can download precompiled notary binary for 64 bit Linux or Mac OS X from the -Notary repository's [releases page on -GitHub](https://github.com/docker/notary/releases). Windows is not officially +Notary repository's +releases page on +GitHub. Windows is not officially supported, but if you are a developer and Windows user, we would appreciate any insight you can provide regarding issues. diff --git a/docs/reference/common-configs.md b/docs/reference/common-configs.md index 04f1d6692a..8acc485d43 100644 --- a/docs/reference/common-configs.md +++ b/docs/reference/common-configs.md @@ -54,9 +54,9 @@ below to configure it. The reporting section contains any configuration for useful for running the service, such as reporting errors. Currently, Notary only supports reporting errors -to [Bugsnag](https://bugsnag.com). +to Bugsnag. -See [bugsnag-go](https://github.com/bugsnag/bugsnag-go/) for more information +See bugsnag-go for more information about these configuration parameters. ```json diff --git a/docs/reference/server-config.md b/docs/reference/server-config.md index 848b472ce1..c527248e24 100644 --- a/docs/reference/server-config.md +++ b/docs/reference/server-config.md @@ -267,7 +267,7 @@ configure it. **Token authentication:** This is an implementation of the same authentication used by version 2 of the -[Docker registry](https://github.com/docker/distribution). (JWT token-based +Docker registry. (JWT token-based authentication post login.) diff --git a/docs/running_a_service.md b/docs/running_a_service.md index e3fa761b7f..f9e0961d50 100644 --- a/docs/running_a_service.md +++ b/docs/running_a_service.md @@ -21,7 +21,7 @@ and [Docker Compose](https://docs.docker.com/compose/overview/). The quickest way to spin up a full Notary service for testing and development purposes is to use the Docker compose file in the -[Notary project](https://github.com/docker/notary). +Notary project. ```plain $ git clone https://github.com/docker/notary.git @@ -75,9 +75,9 @@ the following command line arguments: - `-config=` - specify the path to the JSON configuration file. - `-debug` - Passing this flag enables the debugging server on `localhost:8080`. - The debugging server provides [pprof](https://golang.org/pkg/net/http/pprof/) - and [expvar](https://golang.org/pkg/expvar/) endpoints. (Remember, this - is localhost with respect to the running container - this endpoint is not + The debugging server provides pprof + and expvar endpoints. + (Remember, this is localhost with respect to the running container - this endpoint is not exposed from the container). This option can also be set in the configuration file. diff --git a/docs/service_architecture.md b/docs/service_architecture.md index b45205f477..dda939b9fa 100644 --- a/docs/service_architecture.md +++ b/docs/service_architecture.md @@ -16,20 +16,21 @@ 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://theupdateframework.github.io/), +This document assumes familiarity with +The Update Framework, but here is a brief recap of the TUF roles and corresponding key hierarchy:
TUF Key Hierarchy
- The root key is the root of all trust. It signs the -[root metadata file](https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L489), +root metadata file, which lists the IDs of the root, targets, snapshot, and timestamp public keys. Clients use these public keys to verify the signatures on all the metadata files in the repository. This key is held by a collection owner, and should be kept offline and safe, more so than any other key. - The snapshot key signs the -[snapshot metadata file](https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L604), +snapshot metadata file, which enumerates the filenames, sizes, and hashes of the root, targets, and delegation metadata files for the collection. This file is used to verify the integrity of the other metadata files. The snapshot key is held by @@ -37,7 +38,7 @@ either a collection owner/administrator, or held by the Notary service to facili [signing by multiple collaborators via delegation roles](advanced_usage#working-with-delegation-roles). - The timestamp key signs the -[timestamp metadata file](https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L827), +timestamp metadata file, which provides freshness guarantees for the collection by having the shortest expiry time of any particular piece of metadata and by specifying the filename, size, and hash of the most recent snapshot for the collection. It is used to verify the integrity of the snapshot @@ -46,18 +47,18 @@ 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 metdata file](https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L678), +targets metdata file, which lists filenames in the collection, and their sizes and respective -[hashes](https://en.wikipedia.org/wiki/Cryptographic_hash_function). +hashes. This file is used to verify the integrity of some or all of the actual contents of the repository. It is also used to [delegate trust to other collaborators via delegation roles](advanced_usage#working-with-delegation-roles). The targets key is held by the collection owner or administrator. - Delegation keys sign -[delegation metdata files](https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L678), +delegation metdata files, which lists filenames in the collection, and their sizes and respective -[hashes](https://en.wikipedia.org/wiki/Cryptographic_hash_function). +hashes. These files is used to verify the integrity of some or all of the actual contents of the repository. They are is also used to [delegate trust to other collaborators via lower level delegation roles](advanced_usage#working-with-delegation-roles). @@ -70,8 +71,8 @@ Notary clients pull metadata from one or more (remote) Notary services. Some Notary clients will push metadata to one or more Notary services. A Notary service consists of a Notary server, which stores and updates the -signed [TUF metadata files]( -https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt#L348) +signed +TUF metadata files for multiple trusted collections in an associated database, and a Notary signer, which stores private keys for and signs metadata for the Notary server. The following diagram illustrates this architecture: @@ -89,12 +90,9 @@ responsible for: The Notary signer is responsible for: - storing the private signing keys -[wrapped]( -https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31#section-4.4) -and [encrypted]( -https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-31#section-4.8) -using [Javascript Object Signing and Encryption]( -https://github.com/dvsekhvalnov/jose2go) in a database separate from the +wrapped +and encrypted +using Javascript Object Signing and Encryption in a database separate from the Notary server database - performing signing operations with these keys whenever the Notary server requests @@ -106,7 +104,7 @@ sever, and signer: ![Notary Service Sequence Diagram](images/metadata-sequence.svg) 1. Notary server optionally supports authentication from clients using - [JWT](http://jwt.io/) tokens. This requires an authorization server that + JWT tokens. This requires an authorization server that manages access controls, and a cert bundle from this authorization server containing the public key it uses to sign tokens.