Merge pull request #904 from nginx-proxy/dhparam-rfc7919

Use RFC 7919 DH groups + Remove DH generation

Author: buchdag

README.md

@@ -15,7 +15,7 @@ It handles the automated creation, renewal and use of SSL certificates for proxi
 * Let's Encrypt / ACME domain validation through `http-01` challenge only.
 * Automated update and reload of nginx config on certificate creation/renewal.
 * Support creation of [Multi-Domain (SAN) Certificates](https://github.com/nginx-proxy/acme-companion/blob/main/docs/Let's-Encrypt-and-ACME.md#multi-domains-certificates).
-* Creation of a Strong Diffie-Hellman Group at startup.
+* Creation of a strong [RFC7919 Diffie-Hellman Group](https://datatracker.ietf.org/doc/html/rfc7919#appendix-A) at startup.
 * Work with all versions of docker.
 
 ### Requirements:

app/dhparam/ffdhe2048.pem

@@ -0,0 +1,8 @@
+-----BEGIN DH PARAMETERS-----
+MIIBCAKCAQEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz
++8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a
+87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7
+YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi
+7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD
+ssbzSibBsu/6iGtCOGEoXJf//////////wIBAg==
+-----END DH PARAMETERS-----

app/dhparam/ffdhe3072.pem

@@ -0,0 +1,11 @@
+-----BEGIN DH PARAMETERS-----
+MIIBiAKCAYEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz
++8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a
+87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7
+YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi
+7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD
+ssbzSibBsu/6iGtCOGEfz9zeNVs7ZRkDW7w09N75nAI4YbRvydbmyQd62R0mkff3
+7lmMsPrBhtkcrv4TCYUTknC0EwyTvEN5RPT9RFLi103TZPLiHnH1S/9croKrnJ32
+nuhtK8UiNjoNq8Uhl5sN6todv5pC1cRITgq80Gv6U93vPBsg7j/VnXwl5B0rZsYu
+N///////////AgEC
+-----END DH PARAMETERS-----

test/setup/dhparam.pem renamed to app/dhparam/ffdhe4096.pem

@@ -45,56 +45,63 @@ function check_writable_directory {
 }
 
 function check_dh_group {
-    # Credits to Steve Kamerman for the background Diffie-Hellman creation logic.
-    # https://github.com/nginx-proxy/nginx-proxy/pull/589
-    local DHPARAM_BITS="${DHPARAM_BITS:-2048}"
-    re='^[0-9]*$'
-    if ! [[ "$DHPARAM_BITS" =~ $re ]] ; then
-       echo "Error: invalid Diffie-Hellman size of $DHPARAM_BITS !" >&2
-       exit 1
+	# DH params will be supplied for acme-companion here:
+	local DHPARAM_FILE='/etc/nginx/certs/dhparam.pem'
+
+	# Should be 2048, 3072, or 4096 (default):
+	local DHPARAM_BITS="${DHPARAM_BITS:=4096}"
+
+    # Skip generation if DHPARAM_SKIP is set to true
+    if parse_true "${DHPARAM_SKIP:=false}"; then
+		echo "Info: Skipping Diffie-Hellman group setup."
+		return 0
     fi
 
-    # If a dhparam file is not available, use the pre-generated one and generate a new one in the background.
-    local PREGEN_DHPARAM_FILE="/app/dhparam.pem.default"
-    local DHPARAM_FILE="/etc/nginx/certs/dhparam.pem"
-    local GEN_LOCKFILE="/tmp/le_companion_dhparam_generating.lock"
-
-    # The hash of the pregenerated dhparam file is used to check if the pregen dhparam is already in use
-    local PREGEN_HASH; PREGEN_HASH=$(sha256sum "$PREGEN_DHPARAM_FILE" | cut -d ' ' -f1)
-    if [[ -f "$DHPARAM_FILE" ]]; then
-        local CURRENT_HASH; CURRENT_HASH=$(sha256sum "$DHPARAM_FILE" | cut -d ' ' -f1)
-        if [[ "$PREGEN_HASH" != "$CURRENT_HASH" ]]; then
-            # There is already a dhparam, and it's not the default
-            set_ownership_and_permissions "$DHPARAM_FILE"
-            echo "Info: Custom Diffie-Hellman group found, generation skipped."
-            return 0
-          fi
+    # Let's check DHPARAM_BITS is set to a supported value
+    if [[ ! "$DHPARAM_BITS" =~ ^(2048|3072|4096)$ ]]; then
+        echo "Error: Unsupported DHPARAM_BITS size: ${DHPARAM_BITS}. Supported values are 2048, 3072, or 4096 (default)." >&2
+        exit 1
+    fi
 
-        if [[ -f "$GEN_LOCKFILE" ]]; then
-            # Generation is already in progress
+    # Use an existing pre-generated DH group from RFC7919 (https://datatracker.ietf.org/doc/html/rfc7919#appendix-A):
+    local RFC7919_DHPARAM_FILE="/app/dhparam/ffdhe${DHPARAM_BITS}.pem"
+    local EXPECTED_DHPARAM_HASH; EXPECTED_DHPARAM_HASH=$(sha256sum "$RFC7919_DHPARAM_FILE" | cut -d ' ' -f1)
+
+	# DH params may be provided by the user (rarely necessary)
+	if [[ -f "$DHPARAM_FILE" ]]; then
+        local USER_PROVIDED_DH
+
+        # Check if the DH params file is user provided or comes from acme-companion
+        local DHPARAM_HASH; DHPARAM_HASH=$(sha256sum "$DHPARAM_FILE" | cut -d ' ' -f1)
+        
+        for f in /app/dhparam/ffdhe*.pem; do
+            local FFDHE_HASH; FFDHE_HASH=$(sha256sum "$f" | cut -d ' ' -f1)
+            if [[ "$DHPARAM_HASH" == "$FFDHE_HASH" ]]; then
+                # This is an acme-companion created DH params file
+                USER_PROVIDED_DH='false'
+
+                # Check if /etc/nginx/certs/dhparam.pem matches the expected pre-generated DH group
+                if [[ "$DHPARAM_HASH" == "$EXPECTED_DHPARAM_HASH" ]]; then
+                    set_ownership_and_permissions "$DHPARAM_FILE"
+                    echo "Info: ${DHPARAM_BITS} bits RFC7919 Diffie-Hellman group found, generation skipped."
+                    return 0
+                fi
+            fi
+        done
+
+        if parse_true "${USER_PROVIDED_DH:=true}"; then
+            # This is a user provided DH params file
+            set_ownership_and_permissions "$DHPARAM_FILE"
+            echo "Info: A custom dhparam.pem file was provided. Best practice is to use standardized RFC7919 Diffie-Hellman groups instead."
             return 0
         fi
-    fi
-
-    echo "Info: Creating Diffie-Hellman group in the background."
-    echo "A pre-generated Diffie-Hellman group will be used for now while the new one is being created."
+	fi
 
-    # Put the default dhparam file in place so we can start immediately
-    cp "$PREGEN_DHPARAM_FILE" "$DHPARAM_FILE"
+    # The RFC7919 DH params file either need to be created or replaced
+	echo "Info: Setting up ${DHPARAM_BITS} bits RFC7919 Diffie-Hellman group..."
+	cp "$RFC7919_DHPARAM_FILE" "${DHPARAM_FILE}.tmp"
+    mv "${DHPARAM_FILE}.tmp" "$DHPARAM_FILE"
     set_ownership_and_permissions "$DHPARAM_FILE"
-    touch "$GEN_LOCKFILE"
-
-    # Generate a new dhparam in the background in a low priority and reload nginx when finished (grep removes the progress indicator).
-    (
-        (
-            nice -n +5 openssl dhparam -out "${DHPARAM_FILE}.new" "$DHPARAM_BITS" 2>&1 \
-            && mv "${DHPARAM_FILE}.new" "$DHPARAM_FILE" \
-            && echo "Info: Diffie-Hellman group creation complete, reloading nginx." \
-            && set_ownership_and_permissions "$DHPARAM_FILE" \
-            && reload_nginx
-        ) | grep -vE '^[\.+]+'
-        rm "$GEN_LOCKFILE"
-    ) & disown
 }
 
 function check_default_cert_key {

app/entrypoint.sh

@@ -10,6 +10,20 @@ if [[ "$DEBUG" == true ]]; then
   DEBUG=1 && export DEBUG
 fi
 
+function parse_true() {
+	case "$1" in
+
+		true | True | TRUE | 1)
+		return 0
+		;;
+
+		*)
+		return 1
+		;;
+
+	esac
+}
+
 [[ -z "${VHOST_DIR:-}" ]] && \
  declare -r VHOST_DIR=/etc/nginx/vhost.d
 [[ -z "${START_HEADER:-}" ]] && \

app/functions.sh

@@ -2,8 +2,6 @@
 
 **nginx-proxy** can also be run as two separate containers using the [nginx-proxy/**docker-gen**](https://github.com/nginx-proxy/docker-gen) image and the official [**nginx**](https://hub.docker.com/_/nginx/) image. You may want to do this to prevent having the docker socket bound to a publicly exposed container service (ie avoid mounting the docker socket in the nginx exposed container).
 
-**NOTE**: The first time this container is launched in a three container setup, it will generates a new 2048 bits Diffie-Hellman parameters file. This process can take up to several minutes to complete on lower end hosts, and certificates creation won't start before that (be patient).
-
 Please read and try [basic usage](./Basic-usage.md), and **validate that you have a working two containers setup** before using the three containers setup. In addition to the steps described there, running **nginx-proxy** as two separate containers with **acme-companion** requires the following:
 
 1) Download and mount the template file [nginx.tmpl](https://github.com/nginx-proxy/nginx-proxy/blob/main/nginx.tmpl) into the **docker-gen** container. You can get the nginx.tmpl file with a command like:

docs/Advanced-usage.md

@@ -22,7 +22,9 @@ You can also create test certificates per container (see [Test certificates](./L
 
 * `RENEW_PRIVATE_KEYS` - Set it to `false` to make `acme.sh` reuse previously generated private key for each certificate instead of creating a new one on certificate renewal. Reusing private keys can help if you intend to use [HPKP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Public_Key_Pinning), but please note that HPKP has been deprecated by Google's Chrome and that it is therefore strongly discouraged to use it at all.
 
-* `DHPARAM_BITS` - Change the size of the Diffie-Hellman key generated by the container from the default value of 2048 bits. For example `--env DHPARAM_BITS=1024` to support some older clients like Java 6 and 7.
+* `DHPARAM_BITS` - Change the key size of the RFC7919 Diffie-Hellman group used by the container from the default value of 4096 bits. Supported values are `2048`, `3072` and `4096`. The DH group file will be located in the container at `/etc/nginx/certs/dhparam.pem`. Mounting a different `dhparam.pem` file at that location will override the RFC7919 group creation by the acme-companion container. **COMPATIBILITY WARNING**: some older clients (like Java 6 and 7) do not support DH keys with over 1024 bits. In order to support these clients, you must provide your own `dhparam.pem`.
+
+* `DHPARAM_SKIP` - Set it to `true` to disable the Diffie-Hellman group creation by the container entirely.
 
 * `CA_BUNDLE` - This is a test only variable [for use with Pebble](https://github.com/letsencrypt/pebble#avoiding-client-https-errors). It changes the trusted root CA used by `acme.sh`, from the default Alpine trust store to the CA bundle file located at the provided path (inside the container). Do **not** use it in production unless you are running your own ACME CA.
 

docs/Container-configuration.md

@@ -28,7 +28,6 @@ services:
       - conf:/etc/nginx/conf.d
       - vhost:/etc/nginx/vhost.d
       - html:/usr/share/nginx/html
-      - dhparam:/etc/nginx/dhparam
       - certs:/etc/nginx/certs:ro
       - /var/run/docker.sock:/tmp/docker.sock:ro
     network_mode: bridge
@@ -48,13 +47,10 @@ volumes:
   conf:
   vhost:
   html:
-  dhparam:
   certs:
   acme:
 ```
 
-**Note:** **nginx-proxy** Dockerfile [create a volume for `/etc/nginx/dhparam`](https://github.com/nginx-proxy/nginx-proxy/blob/e80fc0b304bcbcf703d86392394c1a5adb823e3c/Dockerfile#L34), so this compose file include it as a named volume instead of letting it be created anyway as an anonymous volume.
-
 ### Three containers example
 
 ```yaml

docs/Docker-Compose.md

@@ -34,8 +34,6 @@ function run_le_container {
     return 1
   fi
 
-  docker cp "${GITHUB_WORKSPACE}/test/setup/dhparam.pem" "$NGINX_CONTAINER_NAME:/etc/nginx/certs/dhparam.pem"
-
   if docker run -d \
     --name "$name" \
     --volumes-from "$NGINX_CONTAINER_NAME" \