From 435b80df3d7faa5d86b5abf1159c74a9c2814aea Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 10 Sep 2024 11:52:05 +0200 Subject: [PATCH] engine: add instructions for using ca certs with docker Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/engine/network/ca-certs.md | 187 +++++++++++++++++++++ hugo_stats.json | 2 + 2 files changed, 189 insertions(+) create mode 100644 content/manuals/engine/network/ca-certs.md diff --git a/content/manuals/engine/network/ca-certs.md b/content/manuals/engine/network/ca-certs.md new file mode 100644 index 0000000000..63fefed4af --- /dev/null +++ b/content/manuals/engine/network/ca-certs.md @@ -0,0 +1,187 @@ +--- +title: Use CA certificates with Docker +linkTitle: CA certificates +description: Learn how to install and use CA certificates on the Docker host and in Linux containers +keywords: docker, networking, ca, certs, host, container, proxy +--- + +> [!CAUTION] +> Best practices should be followed when using Man-in-the-Middle (MITM) CA +> certificates in production containers. If compromised, attackers could +> intercept sensitive data, spoof a trusted service, or perform +> man-in-the-middle attacks. Consult your security team before you proceed. + +If your company uses a proxy that inspects HTTPS traffic, you might need to add +the required root certificates to your host machine and your Docker containers +or images. This is because Docker and its containers, when pulling images or +making network requests, need to trust the proxy’s certificates. + +On the host, adding the root certificate ensures that any Docker commands (like +`docker pull`) work without issues. For containers, you'll need to add the root +certificate to the container's trust store either during the build process or +at runtime. This ensures that applications running inside the containers can +communicate through the proxy without encountering security warnings or +connection failures. + +## Add CA certificate to the host + +The following sections describe how to install CA certificates on your macOS or +Windows host. For Linux, refer to the documentation for your distribution. + +### macOS + +1. Download the CA certificate for your MITM proxy software. +2. Open the **Keychain Access** app. +3. In Keychain Access, select **System**, then switch to the **Certificates** tab. +4. Drag-and-drop the downloaded certificate into the list of certificates. Enter your password if prompted. +5. Find the newly added certificate, double-click it, and expand the **Trust** section. +6. Set **Always Trust** for the certificate. Enter your password if prompted. +7. Start Docker Desktop and verify that `docker pull` works, assuming Docker Desktop is configured to use the MITM proxy. + +### Windows + +Choose whether you want to install the certificate using the Microsoft +Management Console (MMC) or your web browser. + +{{< tabs >}} +{{< tab name="MMC" >}} + +1. Download CA certificate for the MITM proxy software. +2. Open the Microsoft Management Console (`mmc.exe`). +3. Add the **Certificates Snap-In** in the MMC. + 1. Select **File** → **Add/Remove Snap-in**, and then select **Certificates** → **Add >**. + 2. Select **Computer Account** and then **Next**. + 3. Select **Local computer** and then select **Finish**. +4. Import the CA certificate: + 1. From the MMC, expand **Certificates (Local Computer)**. + 2. Expand the **Trusted Root Certification Authorities** section. + 3. Right-click **Certificates** and select **All Tasks** and **Import…**. + 4. Follow the prompts to import your CA certificate. +5. Select **Finish** and then **Close**. +6. Start Docker Desktop and verify that `docker pull` succeeds (assuming Docker Desktop is already configured to use the MITM proxy server). + +> [!NOTE] +> Depending on the SDK and/or runtime/framework in use, further steps may be +> required beyond adding the CA certificate to the operating system's trust +> store. + +{{< /tab >}} +{{< tab name="Web browser" >}} + +1. Download the CA certificate for your MITM proxy software. +2. Open your web browser, go to **Settings** and open **Manage certificates** +3. Select the **Trusted Root Certification Authorities** tab. +4. Select **Import**, then browse for the downloaded CA certificate. +5. Select **Open**, then choose **Place all certificates in the following store**. +6. Ensure **Trusted Root Certification Authorities** is selected and select **Next**. +7. Select **Finish** and then **Close**. +8. Start Docker Desktop and verify that `docker pull` succeeds (assuming Docker Desktop is already configured to use the MITM proxy server). + +{{< /tab >}} +{{< /tabs >}} + +## Add CA certificates to Linux images and containers + +If you need to run containerized workloads that rely on internal or custom +certificates, such as in environments with corporate proxies or secure +services, you must ensure that the containers trust these certificates. Without +adding the necessary CA certificates, applications inside your containers may +encounter failed requests or security warnings when attempting to connect to +HTTPS endpoints. + +By [adding CA certificates to images](#add-certificates-to-images) at build +time, you ensure that any containers started from the image will trust the +specified certificates. This is particularly important for applications that +require seamless access to internal APIs, databases, or other services during +production. + +In cases where rebuilding the image isn't feasible, you can instead [add +certificates to containers](#add-certificates-to-containers) directly. However, +certificates added at runtime won’t persist if the container is destroyed or +recreated, so this method is typically used for temporary fixes or testing +scenarios. + +## Add certificates to images + +> [!NOTE] +> The following commands are for an Ubuntu base image. If your build uses a +> different Linux distribution, use equivalent commands for package management +> (`apt-get`, `update-ca-certificates`, and so on). + +To add ca certificate to a container image when you're building it, add the +following instructions to your Dockerfile. + +```dockerfile +# Install the ca-certificate package +RUN apt-get update && apt-get install -y ca-certificates +# Copy the CA certificate from the context to the build container +COPY your_certificate.crt /usr/local/share/ca-certificates/ +# Update the CA certificates in the container +RUN update-ca-certificates +``` + +### Add certificates to containers + +> [!NOTE] +> The following commands are for an Ubuntu-based container. If your container +> uses a different Linux distribution, use equivalent commands for package +> management (`apt-get`, `update-ca-certificates`, and so on). + +To add a CA certificate to a running Linux container: + +1. Download the CA certificate for your MITM proxy software. +2. If the certificate is in a format other than `.crt`, convert it to `.crt` format: + + ```console {title="Example command"} + $ openssl x509 -in cacert.der -inform DER -out myca.crt + ``` + +3. Copy the certificate into the running container: + + ```console + $ docker cp myca.crt :/tmp + ``` + +4. Attach to the container: + + ```console + $ docker exec -it sh + ``` + +5. Ensure the `ca-certificates` package is installed (required for updating certificates): + + ```console + # apt-get update && apt-get install -y ca-certificates + ``` + +6. Copy the certificate to the correct location for CA certificates: + + ```console + # cp /tmp/myca.crt /usr/local/share/ca-certificates/root_cert.crt + ``` + +7. Update the CA certificates: + + ```console + # update-ca-certificates + ``` + + ```plaintext {title="Example output"} + Updating certificates in /etc/ssl/certs... + rehash: warning: skipping ca-certificates.crt, it does not contain exactly one certificate or CRL + 1 added, 0 removed; done. + ``` + +8. Verify that the container can communicate via the MITM proxy: + + ```console + # curl https://example.com + ``` + + ```plaintext {title="Example output"} + + + + Example Domain + ... + ``` diff --git a/hugo_stats.json b/hugo_stats.json index 74d009b00c..c856c098de 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -75,6 +75,7 @@ "Linux", "Local-or-Hub-storage", "MDM", + "MMC", "Mac", "Mac-/-Linux", "Mac-/-Linux-/-Git-Bash", @@ -126,6 +127,7 @@ "Vue", "WSL-2-backend-Arm-Beta", "WSL-2-backend-x86_64", + "Web-browser", "What-administrative-tasks-can-I-perform-in-Docker-Hub", "What-are-the-key-features-of-Docker-Desktop", "What-key-features-are-included-in-Docker-Hub",