From 02dbedab227d3ef2bf8f8ce95307015192f9cb2b Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Mon, 18 Dec 2023 16:20:21 +0000 Subject: [PATCH] engine-freshness (#18953) * engine-freshness * review edits * review edits * review edits --- content/engine/security/_index.md | 61 +++++++++---------- content/engine/security/apparmor.md | 16 ++--- content/engine/security/certificates.md | 8 ++- content/engine/security/non-events.md | 2 +- content/engine/security/protect-access.md | 31 +++++++--- content/engine/security/rootless.md | 8 ++- content/engine/security/trust/_index.md | 16 ++--- .../engine/security/trust/deploying_notary.md | 12 ++-- .../engine/security/trust/trust_automation.md | 7 +-- .../engine/security/trust/trust_delegation.md | 55 +++++++++-------- .../engine/security/trust/trust_key_mng.md | 16 ++--- .../engine/security/trust/trust_sandbox.md | 8 +-- content/engine/security/userns-remap.md | 16 +++-- 13 files changed, 141 insertions(+), 115 deletions(-) diff --git a/content/engine/security/_index.md b/content/engine/security/_index.md index a74a86b61d..b2127d1da5 100644 --- a/content/engine/security/_index.md +++ b/content/engine/security/_index.md @@ -11,12 +11,12 @@ aliases: There are four major areas to consider when reviewing Docker security: - - the intrinsic security of the kernel and its support for - namespaces and cgroups; - - the attack surface of the Docker daemon itself; - - loopholes in the container configuration profile, either by default, + - The intrinsic security of the kernel and its support for + namespaces and cgroups + - The attack surface of the Docker daemon itself + - Loopholes in the container configuration profile, either by default, or when customized by users. - - the "hardening" security features of the kernel and how they + - The "hardening" security features of the kernel and how they interact with containers. ## Kernel namespaces @@ -26,18 +26,18 @@ similar security features. When you start a container with `docker run`, behind the scenes Docker creates a set of namespaces and control groups for the container. -**Namespaces provide the first and most straightforward form of -isolation**: processes running within a container cannot see, and even +Namespaces provide the first and most straightforward form of +isolation. Processes running within a container cannot see, and even less affect, processes running in another container, or in the host system. -**Each container also gets its own network stack**, meaning that a +Each container also gets its own network stack, meaning that a container doesn't get privileged access to the sockets or interfaces of another container. Of course, if the host system is setup accordingly, containers can interact with each other through their respective network interfaces — just like they can interact with external hosts. When you specify public ports for your containers or use -[*links*](../../network/links.md) +[links](../../network/links.md) then IP traffic is allowed between containers. They can ping each other, send/receive UDP packets, and establish TCP connections, but that can be restricted if necessary. From a network architecture point of view, all @@ -60,7 +60,7 @@ in 2005, so both the design and the implementation are pretty mature. ## Control groups -Control Groups are another key component of Linux Containers. They +Control Groups are another key component of Linux containers. They implement resource accounting and limiting. They provide many useful metrics, but they also help ensure that each container gets its fair share of memory, CPU, disk I/O; and, more importantly, that a @@ -84,8 +84,8 @@ Docker daemon. This daemon requires `root` privileges unless you opt-in to [Rootless mode](rootless.md), and you should therefore be aware of some important details. -First of all, **only trusted users should be allowed to control your -Docker daemon**. This is a direct consequence of some powerful Docker +First of all, only trusted users should be allowed to control your +Docker daemon. This is a direct consequence of some powerful Docker features. Specifically, Docker allows you to share a directory between the Docker host and a guest container; and it allows you to do so without limiting the access rights of the container. This means that you @@ -147,9 +147,7 @@ fine-grained access control system. Processes (like web servers) that just need to bind on a port below 1024 do not need to run as root: they can just be granted the `net_bind_service` capability instead. And there are many other capabilities, for almost all the specific areas where root -privileges are usually needed. - -This means a lot for container security; let's see why! +privileges are usually needed. This means a lot for container security. Typical servers run several processes as `root`, including the SSH daemon, `cron` daemon, logging daemons, kernel modules, network configuration tools, @@ -157,34 +155,33 @@ and more. A container is different, because almost all of those tasks are handled by the infrastructure around the container: - SSH access are typically managed by a single server running on - the Docker host; + the Docker host - `cron`, when necessary, should run as a user process, dedicated and tailored for the app that needs its - scheduling service, rather than as a platform-wide facility; - - log management is also typically handed to Docker, or to - third-party services like Loggly or Splunk; - - hardware management is irrelevant, meaning that you never need to + scheduling service, rather than as a platform-wide facility + - Log management is also typically handed to Docker, or to + third-party services like Loggly or Splunk + - Hardware management is irrelevant, meaning that you never need to run `udevd` or equivalent daemons within - containers; - - network management happens outside of the containers, enforcing + containers + - Network management happens outside of the containers, enforcing separation of concerns as much as possible, meaning that a container should never need to perform `ifconfig`, `route`, or ip commands (except when a container is specifically engineered to behave like a router or firewall, of - course). + course) This means that in most cases, containers do not need "real" root -privileges *at all*. And therefore, containers can run with a reduced +privileges at all* And therefore, containers can run with a reduced capability set; meaning that "root" within a container has much less privileges than the real "root". For instance, it is possible to: - - deny all "mount" operations; - - deny access to raw sockets (to prevent packet spoofing); - - deny access to some filesystem operations, like creating new device + - Deny all "mount" operations + - Deny access to raw sockets (to prevent packet spoofing) + - Deny access to some filesystem operations, like creating new device nodes, changing the owner of files, or altering attributes (including - the immutable flag); - - deny module loading; - - and many others. + the immutable flag) + - Deny module loading This means that even if an intruder manages to escalate to root within a container, it is much harder to do serious damage, or to escalate @@ -209,9 +206,9 @@ capability removal, or less secure through the addition of capabilities. The best practice for users would be to remove all capabilities except those explicitly required for their processes. -## Docker Content Trust Signature Verification +## Docker Content Trust signature verification -The Docker Engine can be configured to only run signed images. The Docker Content +Docker Engine can be configured to only run signed images. The Docker Content Trust signature verification feature is built directly into the `dockerd` binary. This is configured in the Dockerd configuration file. diff --git a/content/engine/security/apparmor.md b/content/engine/security/apparmor.md index 59fe204297..86bd09f90a 100644 --- a/content/engine/security/apparmor.md +++ b/content/engine/security/apparmor.md @@ -13,7 +13,9 @@ Docker automatically generates and loads a default profile for containers named `docker-default`. The Docker binary generates this profile in `tmpfs` and then loads it into the kernel. -> **Note**: This profile is used on containers, _not_ on the Docker Daemon. +> **Note** +> +> This profile is used on containers, not on the Docker daemon. A profile for the Docker Engine daemon exists but it is not currently installed with the `deb` packages. If you are interested in the source for the daemon @@ -44,7 +46,7 @@ To load a new profile into AppArmor for use with containers: $ apparmor_parser -r -W /path/to/your_profile ``` -Then, run the custom profile with `--security-opt` like so: +Then, run the custom profile with `--security-opt`: ```console $ docker run --rm -it --security-opt apparmor=your_profile hello-world @@ -193,7 +195,7 @@ profile docker-nginx flags=(attach_disconnected,mediate_deleted) { ``` -Congrats! You just deployed a container secured with a custom apparmor profile! +You just deployed a container secured with a custom apparmor profile. ## Debug AppArmor @@ -213,7 +215,7 @@ looks like the following: ``` In the above example, you can see `profile=/usr/bin/docker`. This means the -user has the `docker-engine` (Docker Engine Daemon) profile loaded. +user has the `docker-engine` (Docker Engine daemon) profile loaded. Look at another log line: @@ -266,14 +268,14 @@ and auditing in `dmesg` anything outside the bounds of the `docker-default` profile. The output above also shows the `/usr/bin/docker` (Docker Engine daemon) profile -is running in `complain` mode. This means AppArmor _only_ logs to `dmesg` +is running in `complain` mode. This means AppArmor only logs to `dmesg` activity outside the bounds of the profile. (Except in the case of Ubuntu Trusty, where some interesting behaviors are enforced.) -## Contribute Docker's AppArmor code +## Contribute to Docker's AppArmor code Advanced users and package managers can find a profile for `/usr/bin/docker` -(Docker Engine Daemon) underneath +(Docker Engine daemon) underneath [contrib/apparmor](https://github.com/moby/moby/tree/master/contrib/apparmor) in the Docker Engine source repository. diff --git a/content/engine/security/certificates.md b/content/engine/security/certificates.md index 6184efec41..95bf831076 100644 --- a/content/engine/security/certificates.md +++ b/content/engine/security/certificates.md @@ -14,7 +14,7 @@ to have the Docker client and the daemon communicate securely over HTTPS. TLS e This article demonstrates how to ensure the traffic between the Docker registry server and the Docker daemon (a client of the registry server) is encrypted and -properly authenticated using *certificate-based client-server authentication*. +properly authenticated using certificate-based client-server authentication. We show you how to install a Certificate Authority (CA) root certificate for the registry and how to set the client TLS certificate for verification. @@ -36,7 +36,8 @@ The presence of one or more `.key/cert` pairs indicates to Docker that there are custom certificates required for access to the desired repository. -> **Note**: +> **Note** +> > If multiple certificates exist, each is tried in alphabetical > order. If there is a 4xx-level or 5xx-level authentication error, Docker > continues to try with the next certificate. @@ -67,7 +68,8 @@ $ openssl genrsa -out client.key 4096 $ openssl req -new -x509 -text -key client.key -out client.cert ``` -> **Note**: +> **Note** +> > These TLS commands only generate a working set of certificates on Linux. > The version of OpenSSL in macOS is incompatible with the type of > certificate Docker requires. diff --git a/content/engine/security/non-events.md b/content/engine/security/non-events.md index d26aaea3e7..ce0c705ca3 100644 --- a/content/engine/security/non-events.md +++ b/content/engine/security/non-events.md @@ -76,7 +76,7 @@ These arguments are blocked by `CAP_NET_ADMIN`, which Docker does not allow by default. -Bugs *not* mitigated: +Bugs not mitigated: * [CVE-2015-3290](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-3290), [5157](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-5157): Bugs in diff --git a/content/engine/security/protect-access.md b/content/engine/security/protect-access.md index 4a5e17beed..33156e546a 100644 --- a/content/engine/security/protect-access.md +++ b/content/engine/security/protect-access.md @@ -85,18 +85,20 @@ In the daemon mode, it only allows connections from clients authenticated by a certificate signed by that CA. In the client mode, it only connects to servers with a certificate signed by that CA. -> Advanced topic +> **Important** > -> Using TLS and managing a CA is an advanced topic. Please familiarize yourself +> Using TLS and managing a CA is an advanced topic. Familiarize yourself > with OpenSSL, x509, and TLS before using it in production. { .important } ### Create a CA, server and client keys with OpenSSL -> **Note**: Replace all instances of `$HOST` in the following example with the +> **Note** +> +> Replace all instances of `$HOST` in the following example with the > DNS name of your Docker daemon's host. -First, on the **Docker daemon's host machine**, generate CA private and public keys: +First, on the Docker daemon's host machine, generate CA private and public keys: ```console $ openssl genrsa -aes256 -out ca-key.pem 4096 @@ -129,7 +131,9 @@ Now that you have a CA, you can create a server key and certificate signing request (CSR). Make sure that "Common Name" matches the hostname you use to connect to Docker: -> **Note**: Replace all instances of `$HOST` in the following example with the +> **Note** +> +> Replace all instances of `$HOST` in the following example with the > DNS name of your Docker daemon's host. ```console @@ -177,7 +181,9 @@ Docker clients. For client authentication, create a client key and certificate signing request: -> **Note**: For simplicity of the next couple of steps, you may perform this +> **Note** +> +> For simplicity of the next couple of steps, you may perform this > step on the Docker daemon's host machine as well. ```console @@ -245,13 +251,16 @@ $ dockerd \ To connect to Docker and validate its certificate, provide your client keys, certificates and trusted CA: -> Run it on the client machine +> **Tip** > > This step should be run on your Docker client machine. As such, you > need to copy your CA certificate, your server certificate, and your client > certificate to that machine. +{ .tip } -> **Note**: Replace all instances of `$HOST` in the following example with the +> **Note** +> +> Replace all instances of `$HOST` in the following example with the > DNS name of your Docker daemon's host. ```console @@ -262,10 +271,12 @@ $ docker --tlsverify \ -H=$HOST:2376 version ``` -> **Note**: +> **Note** +> > Docker over TLS should run on TCP port 2376. -> **Warning**: +> **Warning** +> > As shown in the example above, you don't need to run the `docker` client > with `sudo` or the `docker` group when you use certificate authentication. > That means anyone with the keys can give any instructions to your Docker diff --git a/content/engine/security/rootless.md b/content/engine/security/rootless.md index cac3da4c9d..cf27755561 100644 --- a/content/engine/security/rootless.md +++ b/content/engine/security/rootless.md @@ -45,7 +45,10 @@ testuser:231072:65536 ### Distribution-specific hint -> Note: We recommend that you use the Ubuntu kernel. +> **Tip** +> +> We recommend that you use the Ubuntu kernel. +{ .tip } {{< tabs >}} {{< tab name="Ubuntu" >}} @@ -431,7 +434,8 @@ $ mkdir -p $XDG_RUNTIME_DIR $ dockerd-rootless.sh ``` -> **Note**: +> **Note** +> > You must remove the directory every time you log out. On a systemd host, log into the host using `pam_systemd` (see below). diff --git a/content/engine/security/trust/_index.md b/content/engine/security/trust/_index.md index 054e9f254e..992790d592 100644 --- a/content/engine/security/trust/_index.md +++ b/content/engine/security/trust/_index.md @@ -15,10 +15,10 @@ aliases: - /notary/reference/common-configs/ --- -When transferring data among networked systems, *trust* is a central concern. In +When transferring data among networked systems, trust is a central concern. In particular, when communicating over an untrusted medium such as the internet, it is critical to ensure the integrity and the publisher of all the data a system -operates on. You use the Docker Engine to push and pull images (data) to a +operates on. You use Docker Engine to push and pull images (data) to a public or private registry. Content trust gives you the ability to verify both the integrity and the publisher of all the data received from a registry over any channel. @@ -86,16 +86,16 @@ Trust for an image tag is managed through the use of signing keys. A key set is created when an operation using DCT is first invoked. A key set consists of the following classes of keys: -- an offline key that is the root of DCT for an image tag -- repository or tagging keys that sign tags -- server-managed keys such as the timestamp key, which provides freshness +- An offline key that is the root of DCT for an image tag +- Repository or tagging keys that sign tags +- Server-managed keys such as the timestamp key, which provides freshness security guarantees for your repository The following image depicts the various signing keys and their relationships: ![Content Trust components](images/trust_components.png) -> **WARNING** +> **Warning** > >The root key once lost is not recoverable. If you lose any other key, send an email to [Docker Hub Support](mailto:hub-support@docker.com). This loss also requires manual intervention from every consumer that used a signed tag from this repository prior to the loss. @@ -106,7 +106,7 @@ to create new repositories, it is a good idea to store it offline in hardware. For details on securing, and backing up your keys, make sure you read how to [manage keys for DCT](trust_key_mng.md). -## Signing Images with Docker Content Trust +## Signing images with Docker Content Trust Within the Docker CLI we can sign and push a container image with the `$ docker trust` command syntax. This is built on top of the Notary feature @@ -218,7 +218,7 @@ Enter passphrase for signer key with ID 8ae710e: Successfully deleted signature for registry.example.com/admin/demo:1 ``` -## Client Enforcement with Docker Content Trust +## Client enforcement with Docker Content Trust Content trust is disabled by default in the Docker Client. To enable it, set the `DOCKER_CONTENT_TRUST` environment variable to `1`. This prevents diff --git a/content/engine/security/trust/deploying_notary.md b/content/engine/security/trust/deploying_notary.md index 0ebae5aebb..535a14fac5 100644 --- a/content/engine/security/trust/deploying_notary.md +++ b/content/engine/security/trust/deploying_notary.md @@ -7,15 +7,19 @@ title: Deploy Notary Server with Compose The easiest way to deploy Notary Server is by using Docker Compose. To follow the procedure on this page, you must have already [installed Docker Compose](../../../compose/install/index.md). 1. Clone the Notary repository. - - git clone https://github.com/theupdateframework/notary.git + + ```consolse + $ git clone https://github.com/theupdateframework/notary.git + ``` 2. Build and start Notary Server with the sample certificates. - docker compose up -d + ```consolse + $ docker compose up -d + ``` + For more detailed documentation about how to deploy Notary Server, see the [instructions to run a Notary service](https://github.com/theupdateframework/notary/blob/master/docs/running_a_service.md) as well as [the Notary repository](https://github.com/theupdateframework/notary) for more information. - For more detailed documentation about how to deploy Notary Server, see the [instructions to run a Notary service](https://github.com/theupdateframework/notary/blob/master/docs/running_a_service.md) as well as [the Notary repository](https://github.com/theupdateframework/notary) for more information. 3. Make sure that your Docker or Notary client trusts Notary Server's certificate before you try to interact with the Notary server. See the instructions for [Docker](../../reference/commandline/cli.md#notary) or diff --git a/content/engine/security/trust/trust_automation.md b/content/engine/security/trust/trust_automation.md index 5e92079436..29d0a75a9c 100644 --- a/content/engine/security/trust/trust_automation.md +++ b/content/engine/security/trust/trust_automation.md @@ -8,9 +8,8 @@ It is very common for Docker Content Trust to be built into existing automation systems. To allow tools to wrap Docker and push trusted content, there are environment variables that can be passed through to the client. -This guide follows the steps as described -[here](index.md#signing-images-with-docker-content-trust) so please read -that and understand its prerequisites. +This guide follows the steps as described in +[Signing images with Docker Content Trust](index.md#signing-images-with-docker-content-trust). Make sure you understand and follow the prerequisites. When working directly with the Notary client, it uses its [own set of environment variables](https://github.com/theupdateframework/notary/blob/master/docs/reference/client-config.md#environment-variables-optional). @@ -30,7 +29,7 @@ Successfully imported key from delegation.key ## Add a delegation public key -If you initialising a repository at the same time as adding a Delegation +If you initialize a repository at the same time as adding a delegation public key, then you will need to use the local Notary Canonical Root Key's passphrase to create the repositories trust data. If the repository has already been initiated then you only need the repositories passphrase. diff --git a/content/engine/security/trust/trust_delegation.md b/content/engine/security/trust/trust_delegation.md index b7642ae920..196ef5db90 100644 --- a/content/engine/security/trust/trust_delegation.md +++ b/content/engine/security/trust/trust_delegation.md @@ -19,7 +19,7 @@ Fortunately when using the `$ docker trust` commands, we will automatically initialize a repository, manage the repository keys, and add a collaborator's key to the `targets/releases` delegation via `docker trust signer add`. -## Configuring the Docker Client +## Configuring the Docker client By default, the `$ docker trust` commands expect the notary server URL to be the same as the registry URL specified in the image tag (following a similar logic to @@ -74,7 +74,7 @@ you are not authorized to perform this operation: server returned 401. Failed to add signer to: registry.example.com/user/repo ``` -## Configuring the Notary Client +## Configuring the Notary client Some of the more advanced features of DCT require the Notary CLI. To install and configure the Notary CLI: @@ -99,13 +99,13 @@ For more detailed information about how to use notary outside of the Docker Content Trust use cases, refer to the Notary CLI documentation [here](https://github.com/theupdateframework/notary/blob/master/docs/command_reference.md) -## Creating Delegation Keys +## Creating delegation keys A prerequisite to adding your first contributor is a pair of delegation keys. These keys can either be generated locally using `$ docker trust`, generated by a certificate authority. -### Using Docker Trust to Generate Keys +### Using Docker Trust to generate keys Docker trust has a built-in generator for a delegation key pair, `$ docker trust generate `. Running this command will automatically load @@ -120,7 +120,7 @@ Repeat passphrase for new jeff key with ID 9deed25: Successfully generated and loaded private key. Corresponding public key available: /home/ubuntu/Documents/mytrustdir/jeff.pub ``` -### Manually Generating Keys +### Manually generating keys If you need to manually generate a private key (either RSA or ECDSA) and a x509 certificate containing the public key, you can use local tools like openssl or @@ -170,7 +170,7 @@ Repeat passphrase for new jeff key with ID 8ae710e: Successfully imported key from delegation.key ``` -### Viewing local Delegation keys +### Viewing local delegation keys To list the keys that have been imported in to the local Docker trust store we can use the Notary CLI. @@ -184,9 +184,9 @@ root f6c6a4b00fefd8751f86194c7d87a3bede444540 jeff 9deed251daa1aa6f9d5f9b752847647cf8d705da0763aa5467650d0987ed5306 /home/ubuntu/.docker/trust/private ``` -## Managing Delegations in a Notary Server +## Managing delegations in a Notary Server -When the first Delegation is added to the Notary Server using `$ docker trust`, +When the first delegation is added to the Notary Server using `$ docker trust`, we automatically initiate trust data for the repository. This includes creating the notary target and snapshots keys, and rotating the snapshot key to be managed by the notary server. More information on these keys can be found @@ -196,9 +196,12 @@ When initiating a repository, you will need the key and the passphrase of a loca Notary Canonical Root Key. If you have not initiated a repository before, and therefore don't have a Notary root key, `$ docker trust` will create one for you. -> Be sure to protect and back up your [Notary Canonical Root Key](trust_key_mng.md) +> **Important** +> +> Be sure to protect and back up your [Notary Canonical Root Key](trust_key_mng.md). +{ .important } -### Initiating the Repository +### Initiating the repository To upload the first key to a delegation, at the same time initiating a repository, you can use the `$ docker trust signer add` command. This will add @@ -254,7 +257,7 @@ targets/jeff "" 1091060d7bfd938dfa5be703fa057974f9322a4fae targets/releases "" 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 1 ``` -### Adding Additional Signers +### Adding additional signers Docker Trust allows you to configure multiple delegations per repository, allowing you to manage the lifecycle of delegations. When adding additional @@ -291,14 +294,16 @@ Administrative keys for registry.example.com/admin/demo Root Key: 64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7 ``` -### Adding Keys to an Existing Delegation +### Adding keys to an existing delegation To support things like key rotation and expiring / retiring keys you can publish multiple contributor keys per delegation. The only prerequisite here is to make sure you use the same the delegation name, in this case `jeff`. Docker trust will automatically handle adding this new key to `targets/releases`. -> Note you will need the passphrase for the repository key; this would have been +> **Note** +> +> You will need the passphrase for the repository key; this would have been > configured when you first initiated the repository. ```console @@ -328,13 +333,15 @@ Administrative keys for registry.example.com/admin/demo Root Key: 64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7 ``` -### Removing a Delegation +### Removing a delegation If you need to remove a delegation, including the contributor keys that are attached to the `targets/releases` role, you can use the `$ docker trust signer remove` command. -> Note tags that were signed by the removed delegation will need to be resigned +> **Note** +> +> Tags that were signed by the removed delegation will need to be resigned > by an active delegation ```console @@ -362,16 +369,16 @@ Successfully removed ben from registry.example.com/admin/demo WARN[0000] Error getting targets/releases: valid signatures did not meet threshold for targets/releases ``` -Resigning the delegation file is done with the `$ notary witness` command + Resigning the delegation file is done with the `$ notary witness` command -```console -$ notary witness registry.example.com/admin/demo targets/releases --publish -``` + ```console + $ notary witness registry.example.com/admin/demo targets/releases --publish + ``` -More information on the `$ notary witness` command can be found -[here](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#recovering-a-delegation) + More information on the `$ notary witness` command can be found + [here](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#recovering-a-delegation) -### Removing a Contributor's Key from a Delegation +### Removing a contributor's key from a delegation As part of rotating keys for a delegation, you may want to remove an individual key but retain the delegation. This can be done with the Notary CLI. @@ -429,7 +436,7 @@ and the role specific to that signer `targets/`. targets/releases "" 8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9 1 ``` -### Removing a local Delegation Private Key +### Removing a local delegation private key As part of rotating delegation keys, you may need to remove a local delegation key from the local Docker trust store. This is done with the Notary CLI, using @@ -458,7 +465,7 @@ the `$ notary key remove` command. Deleted 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 (role jeff) from /home/ubuntu/.docker/trust/private. ``` -## Removing all trust data from a Repository +## Removing all trust data from a repository You can remove all trust data from a repository, including repository, target, snapshot and all delegations keys using the Notary CLI. diff --git a/content/engine/security/trust/trust_key_mng.md b/content/engine/security/trust/trust_key_mng.md index b4d37046f6..5c8af2274c 100644 --- a/content/engine/security/trust/trust_key_mng.md +++ b/content/engine/security/trust/trust_key_mng.md @@ -23,16 +23,12 @@ the image repository: - The timestamp and snapshot keys are safely generated and stored in a signing server that is deployed alongside the Docker registry. These keys are generated in a backend - service that isn't directly exposed to the internet and are encrypted at rest. + service that isn't directly exposed to the internet and are encrypted at rest. Use the Notary CLI to [manage your snapshot key locally](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#rotate-keys). Delegation keys are optional, and not generated as part of the normal `docker` -workflow. They need to be +workflow. They need to be [manually generated and added to the repository](trust_delegation.md#creating-delegation-keys). -**Note**: Prior to Docker Engine 1.11, the snapshot key was also generated and stored -locally client-side. -Use the Notary CLI to [manage your snapshot key locally again](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#rotate-keys) for repositories created with newer versions of Docker. - ## Choose a passphrase The passphrases you chose for both the root key and your repository key should @@ -47,9 +43,9 @@ All the Docker trust keys are stored encrypted using the passphrase you provide on creation. Even so, you should still take care of the location where you back them up. Good practice is to create two encrypted USB keys. -> **WARNING** +> **Warning** > -> It is **very important** that you back up your keys to a safe, secure location. +> It is very important that you back up your keys to a safe, secure location. The loss of the repository key is recoverable, but the loss of the root key is not. { .warning } @@ -73,14 +69,14 @@ Prior to Docker Engine 1.11, this feature was only in the experimental branch. ## Key loss -> **WARNING** +> **Warning** > > If a publisher loses keys it means losing the ability to sign images for the repositories in question. If you lose a key, send an email to [Docker Hub Support](mailto:hub-support@docker.com). As a reminder, the loss of a root key is not recoverable. { .warning } -This loss also requires **manual intervention** from every consumer that used a signed +This loss also requires manual intervention from every consumer that used a signed tag from this repository prior to the loss. Image consumers get the following error for content previously downloaded from the affected repo(s): diff --git a/content/engine/security/trust/trust_sandbox.md b/content/engine/security/trust/trust_sandbox.md index fb4229524e..d6ef54d5f3 100644 --- a/content/engine/security/trust/trust_sandbox.md +++ b/content/engine/security/trust/trust_sandbox.md @@ -13,7 +13,7 @@ impacting your production images. Before working through this sandbox, you should have read through the [trust overview](index.md). -### Prerequisites +## Prerequisites These instructions assume you are running in Linux or macOS. You can run this sandbox on a local machine or on a virtual machine. You need to @@ -67,10 +67,10 @@ the `trustsandbox` container, the Notary server, and the Registry server. $ mkdir trustsandbox $ cd trustsandbox -2. Create a file called `docker-compose.yml` with your favorite editor. For example, using vim: +2. Create a file called `compose.yml` with your favorite editor. For example, using vim: - $ touch docker-compose.yml - $ vim docker-compose.yml + $ touch compose.yml + $ vim compose.yml 3. Add the following to the new file. diff --git a/content/engine/security/userns-remap.md b/content/engine/security/userns-remap.md index 7be9b20738..fa2c80d04c 100644 --- a/content/engine/security/userns-remap.md +++ b/content/engine/security/userns-remap.md @@ -34,7 +34,7 @@ outside of the namespace, the process is running as an unprivileged high-number UID on the host, which does not even map to a real user. This means the process has no privileges on the host system at all. -> Multiple ranges +> **Note** > > It is possible to assign multiple subordinate ranges for a given user or group > by adding multiple non-overlapping mappings for the same user or group in the @@ -47,7 +47,9 @@ specify an existing user and/or group, or you can specify `default`. If you specify `default`, a user and group `dockremap` is created and used for this purpose. -> **Warning**: Some distributions, such as RHEL and CentOS 7.3, do not +> **Warning** +> +> Some distributions, such as RHEL and CentOS 7.3, do not > automatically add the new group to the `/etc/subuid` and `/etc/subgid` files. > You are responsible for editing these files and assigning non-overlapping > ranges, in this case. This step is covered in [Prerequisites](#prerequisites). @@ -107,7 +109,7 @@ avoid these situations. avoid overlap. If you want to use the `dockremap` user automatically created by Docker, - check for the `dockremap` entry in these files **after** + check for the `dockremap` entry in these files after configuring and restarting Docker. 3. If there are any locations on the Docker host where the unprivileged @@ -160,7 +162,9 @@ $ dockerd --userns-remap="testuser:testuser" } ``` - > **Note**: To use the `dockremap` user and have Docker create it for you, + > **Note** + > + > To use the `dockremap` user and have Docker create it for you, > set the value to `default` rather than `testuser`. Save the file and restart Docker. @@ -254,8 +258,8 @@ What this means is that the whole container filesystem will belong to the user s The following standard Docker features are incompatible with running a Docker daemon with user namespaces enabled: -- sharing PID or NET namespaces with the host (`--pid=host` or `--network=host`). -- external (volume or storage) drivers which are unaware or incapable of using +- Sharing PID or NET namespaces with the host (`--pid=host` or `--network=host`). +- External (volume or storage) drivers which are unaware or incapable of using daemon user mappings. - Using the `--privileged` mode flag on `docker run` without also specifying `--userns=host`.