diff --git a/docs/advanced_usage.md b/docs/advanced_usage.md index ddd790cbd0..97bf1c3264 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,18 +44,18 @@ 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. - 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 ``` @@ -67,7 +67,7 @@ Note that this is an offline command, and we must run a `notary publish example. 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. @@ -111,24 +110,27 @@ 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 +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/getting_started.md b/docs/getting_started.md index 5c71d3fe74..79767e27ee 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -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..2b328d46f7 100644 --- a/docs/reference/client-config.md +++ b/docs/reference/client-config.md @@ -40,7 +40,7 @@ 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. +An example (full) client configuration file. ```json { @@ -145,6 +145,6 @@ passphrase. ## Related information -* [Server Configuration File](server-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/docs/reference/common-configs.md b/docs/reference/common-configs.md index 87d19308db..f2d072831a 100644 --- a/docs/reference/common-configs.md +++ b/docs/reference/common-configs.md @@ -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,6 @@ required parameters below, to configure it. ## Related information -* [Server Configuration File](server-config.md) +* [Notary Server Configuration File](server-config.md) * [Notary Client Configuration File](client-config.md) * [Notary Signer Configuration File](signer-config.md) diff --git a/docs/reference/index.md b/docs/reference/index.md index 8c9bb763f9..8d0f653a08 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -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 Server Configuration File](server-config.md) * [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) diff --git a/docs/reference/server-config.md b/docs/reference/server-config.md index 919407d8d4..76ca93199d 100644 --- a/docs/reference/server-config.md +++ b/docs/reference/server-config.md @@ -10,8 +10,7 @@ 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 +This document is 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 diff --git a/docs/reference/signer-config.md b/docs/reference/signer-config.md index 60d169a2df..9b3fddf6d7 100644 --- a/docs/reference/signer-config.md +++ b/docs/reference/signer-config.md @@ -11,8 +11,7 @@ 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 +This document is for those who are [running their own service](../running_a_service.md) who want to facilitate CLI interaction or specify custom options. ## Overview @@ -203,7 +202,7 @@ Example: private keys will be encrypted using this password, which must also be provided as the environment variable NOTARY_SIGNER_<DEFAULT_ALIAS_VALUE>. - Please see the environment variable + Please see the environment variable section for more information. @@ -261,6 +260,6 @@ attempts to sign data using those keys will fail. ## Related information -* [Server Configuration File](server-config.md) +* [Notary Server Configuration File](server-config.md) * [Notary Client Configuration File](client-config.md) * [Configuration sections common to the Notary server and signer](common-configs.md) diff --git a/docs/running_a_service.md b/docs/running_a_service.md index f8dd28f7a4..b2c1c65c52 100644 --- a/docs/running_a_service.md +++ b/docs/running_a_service.md @@ -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/).