diff --git a/docs/advanced_usage.md b/docs/advanced_usage.md index ddd790cbd0..8a06f2e6d8 100644 --- a/docs/advanced_usage.md +++ b/docs/advanced_usage.md @@ -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 +## Initialize a Trusted Collection -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 diff --git a/docs/changelog.md b/docs/changelog.md index e5cd8920c1..533480c164 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -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). diff --git a/docs/getting_started.md b/docs/getting_started.md index 5c71d3fe74..15f8c8cf9d 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -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 diff --git a/docs/reference/client-config.md b/docs/reference/client-config.md index d5653affef..500b26e630 100644 --- a/docs/reference/client-config.md +++ b/docs/reference/client-config.md @@ -1,6 +1,6 @@