docker/docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-11-05 00:14:17 +03:00
Code Activity

Single space after a full stop in already-touched files

Browse Source 
Signed-off-by: Ying Li <ying.li@docker.com>
This commit is contained in:
Ying Li
2016-03-31 22:08:44 -07:00
parent 7cbe4da88f
commit 4881afd56c
3 changed files with 32 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/advanced_usage.md
View File

@@ -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 <KEY_FILE> --role user` with the private key PEM
file, or drop the private key PEM in `private/tuf_keys` as `<KEY_ID>.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.

2
docs/getting_started.md
View File

@@ -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.

46
docs/service_architecture.md
View File

@@ -22,18 +22,18 @@ but here is a brief recap of the TUF roles and corresponding key hierarchy:
<center><img src="images/key-hierarchy.svg" alt="TUF Key Hierarchy" width="400px"/></center>
- The root key is the root of all trust. It signs the
- The root key is the root of all trust. It signs the
<a href="https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L489" target="_blank">root metadata file</a>,
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
<a href="https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L604" target="_blank">snapshot metadata file</a>,
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
<a href="https://github.com/theupdateframework/tuf/blob/1bed3e09a478c2c918ffbff10b9118f6e52ee129/docs/tuf-spec.txt#L827" target="_blank">timestamp metadata file</a>,
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 <br/> 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 <br/> 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.