diff --git a/docs/advanced_usage.md b/docs/advanced_usage.md index 7e91da6897..10a07bbe8e 100644 --- a/docs/advanced_usage.md +++ b/docs/advanced_usage.md @@ -158,9 +158,9 @@ 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`. With the given path of "delegation/path", the `targets/releases` +`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 +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. @@ -174,9 +174,9 @@ $ notary delegation list example.com/collection targets/releases delegation/path 729c7094a8210fd1e780e7b17b7bb55c9a28a48b871b07f65d97baf93898523a 1 ``` -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. +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. 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: +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 @@ -195,7 +195,7 @@ delete the role entirely. To add targets to a specified delegation role, we can use the `notary add` command with the `--roles` flag. -You must have imported an appropriate delegation key for this role. To do so, +You must have imported an appropriate delegation key for this role. To do so, you can run `notary key import --role user` with the private key PEM file, or drop the private key PEM in `private/tuf_keys` as `.key` with the `role` PEM header set to `user`. @@ -211,7 +211,7 @@ role `targets/releases`. This target's path is valid because it is prefixed by the delegation role's valid path. The `notary list` and `notary remove` commands can also take the `--roles` flag -to specify roles to list or remove targets from. By default, this operates over +to specify roles to list or remove targets from. By default, this operates over the base `targets` role. To remove this target from our delegation, use the `notary remove` command with @@ -228,7 +228,7 @@ delegation as the canonical source of a trusted image tag, if it exists. When running `docker pull` with Docker Content Trust on Docker Engine 1.10, Docker will attempt to search the `targets/releases` role for the signed image tag, -and will fall back to the default `targets` role if it does not exist. Please note +and will fall back to the default `targets` role if it does not exist. Please note that when searching the default `targets` role, Docker 1.10 may pick up on other non-`targets/releases` delegation roles' signed images if they exist for this tag. In Docker 1.11, this behavior is changed such that all `docker pull` commands with @@ -237,7 +237,7 @@ or the `targets` base role. When running `docker push` with Docker Content Trust, Docker Engine 1.10 will attempt to sign and push with the `targets/releases` delegation role if it exists, -otherwise falling back to the `targets` role. In Docker 1.11, a `docker push` will +otherwise falling back to the `targets` role. In Docker 1.11, a `docker push` will instead attempt to sign and push with all delegation roles directly under targets (ex: `targets/role` but not `targets/nested/role`) that the user has signing keys for. If delegation roles exist but the user does not have signing keys, the push will fail. diff --git a/docs/getting_started.md b/docs/getting_started.md index 36dcdf379a..b3c434bd79 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -98,7 +98,7 @@ 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 -will then instruct the Engine to do a "pull by digest". During this pull, the +will then instruct the Engine to do a "pull by digest". During this pull, the Engine uses the sha256 checksum as a content address to request and validate the image manifest from the Docker registry. diff --git a/docs/service_architecture.md b/docs/service_architecture.md index dda939b9fa..f5d64c6f70 100644 --- a/docs/service_architecture.md +++ b/docs/service_architecture.md @@ -22,18 +22,18 @@ 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 +- The root key is the root of all trust. It signs the 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 +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, 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 +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 either a collection owner/administrator, or held by the Notary service to facilitate [signing by multiple collaborators via delegation roles](advanced_usage#working-with-delegation-roles). @@ -41,8 +41,8 @@ either a collection owner/administrator, or held by the Notary service to facili 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 -file. The timestamp key is held by the Notary service so the timestamp can be +snapshot for the collection. It is used to verify the integrity of the snapshot +file. The timestamp key is held by the Notary service so the timestamp can be automatically re-generated when it is requested from the server, rather than require that a collection owner come online before each timestamp expiry. @@ -67,7 +67,7 @@ collection collaborators. ## Architecture and components -Notary clients pull metadata from one or more (remote) Notary services. Some +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 @@ -153,7 +153,7 @@ sever, and signer: ## Threat model Both the server and the signer are potential attack vectors against all users -of the Notary service. Client keys are also a potential attack vector, but +of the Notary service. Client keys are also a potential attack vector, but not necessarily against all collections at a time. This section discusses how our architecture is designed to deal with compromises. @@ -194,7 +194,7 @@ operations with any key the Signer holds. good metadata that any client may have. 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, 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. @@ -212,7 +212,7 @@ keys in the HSM, but not to exfiltrate the private material. timestamps or snapshots. - **Key Compromise** - If the Notary signer uses a database as its backend, - an attacker can exfiltrate all the private material. Note that the capabilities + 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. @@ -220,7 +220,7 @@ keys in the HSM, but not to exfiltrate the private material. ### Notary client keys and credentials compromise The security of keys held and administered by users depend measures taken by the -users. If the Notary Client CLI was used to create them, then they are password +users. If the Notary Client CLI was used to create them, then they are password protected and the Notary CLI does not provide options to export them in plaintext. @@ -251,8 +251,8 @@ decrypted key depends on the type and combination of keys that were compromised An attacker can add malicious content, remove legitimate content from a collection, and mix up the targets in a collection, but only within the particular delegation - roles that the key can sign for. Depending on the restrictions on that role, - they may be restricted in what type of content they can modify. They may also + roles that the key can sign for. Depending on the restrictions on that role, + they may be restricted in what type of content they can modify. They may also add or remove the capabilities of other delegation keys below it on the key hierarchy (e.g. if `DelegationKey2` in the above key hierarchy were compromised, it would only be able to modify the capabilities of `DelegationKey4` and `DelegationKey5`). @@ -272,14 +272,14 @@ decrypted key depends on the type and combination of keys that were compromised |------------------|-------------------|---------------------------------|-------------------| | Delegation key
Snapshot key | limited | limited | limited | - The Notary Service always holds the timestamp key. If the attacker has Notary Service + The Notary Service always holds the timestamp key. If the attacker has Notary Service write credentials, then they have effective access to the timestamp key because the server will generate and sign the timestamp for them. An attacker can add malicious content, remove legitimate content from a collection, and mix up the targets in a collection, but only within the particular delegation - roles that the key can sign for. Depending on the restrictions on that role, - they may be restricted in what type of content they can modify. They may also + roles that the key can sign for. Depending on the restrictions on that role, + they may be restricted in what type of content they can modify. They may also add or remove the capabilities of other delegation keys below it on the key hierarchy (e.g. if `DelegationKey2` in the above key hierarchy were compromised, it would only be able to modify the capabilities of `DelegationKey4` and `DelegationKey5`). @@ -301,9 +301,9 @@ decrypted key depends on the type and combination of keys that were compromised keys because the server will generate and sign the snapshot and timestamp for them. An attacker can add any malicious content, remove any legitimate content from a - collection, and mix up the targets in a collection. They may also add or remove + collection, and mix up the targets in a collection. They may also add or remove the capabilities of any top level delegation key or role (e.g. `Delegation1`, - `Delegation2`, and `Delegation3` in the key hierarchy diagram). If they remove + `Delegation2`, and `Delegation3` in the key hierarchy diagram). If they remove the roles entirely, they'd break the trust chain to the lower delegation roles (e.g. `Delegation4`, `Delegation5`). @@ -322,14 +322,14 @@ decrypted key depends on the type and combination of keys that were compromised |------------------|-------------------|---------------------------------|-------------------| | Targets key
Snapshot key | yes | yes | limited | - The Notary Service always holds the timestamp key. If the attacker has Notary Service + The Notary Service always holds the timestamp key. If the attacker has Notary Service write credentials, then they have effective access to the timestamp key because the server will generate and sign the timestamp for them. An attacker can add any malicious content, remove any legitimate content from a - collection, and mix up the targets in a collection. They may also add or remove + collection, and mix up the targets in a collection. They may also add or remove the capabilities of any top level delegation key or role (e.g. `Delegation1`, - `Delegation2`, and `Delegation3` in the key hierarchy diagram). If they remove + `Delegation2`, and `Delegation3` in the key hierarchy diagram). If they remove the roles entirely, they'd break the trust chain to the lower delegation roles (e.g. `Delegation4`, `Delegation5`). @@ -340,7 +340,7 @@ decrypted key depends on the type and combination of keys that were compromised | All keys | yes | yes | yes | No other keys are needed, since the attacker can just any rotate or all of them to ones that they - generate. With these keys, they can set up a mirror to serve malicious data - any malicious data + generate. With these keys, they can set up a mirror to serve malicious data - any malicious data at all, given that they have acess to all the keys. - **Decrypted Root Key + none or any combination of decrypted keys + Notary Service write-capable credentials** @@ -357,7 +357,7 @@ decrypted key depends on the type and combination of keys that were compromised If a root key compromise is detected, the root key holder should contact whomever runs the notary service to manually reverse any malicious changes to -the repository, and immediately rotate the root key. This will create a fork +the repository, and immediately rotate the root key. This will create a fork of the repository history, and thus break existing clients who have downloaded any of the malicious changes.