From 5cfc9c85ee41e5a837d1bdfa75c787ba9a135ff5 Mon Sep 17 00:00:00 2001 From: Andrei Belov Date: Mon, 21 Sep 2026 13:01:19 -0600 Subject: [PATCH 1/9] docs(NGINXaaS): add post-quantum quick-start for AWS and GCP --- .../deploy/ssl-tls-certificates/overview.md | 11 +- content/nginxaas/aws/quickstart/_index.md | 5 + content/nginxaas/aws/quickstart/pqc.md | 162 ++++++++++++++++++ .../deploy/ssl-tls-certificates/overview.md | 14 ++ content/nginxaas/google/quickstart/_index.md | 5 + content/nginxaas/google/quickstart/pqc.md | 162 ++++++++++++++++++ 6 files changed, 357 insertions(+), 2 deletions(-) create mode 100644 content/nginxaas/aws/quickstart/_index.md create mode 100644 content/nginxaas/aws/quickstart/pqc.md create mode 100644 content/nginxaas/google/quickstart/_index.md create mode 100644 content/nginxaas/google/quickstart/pqc.md diff --git a/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md b/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md index f4a752e05..5ff8ad076 100644 --- a/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md +++ b/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md @@ -6,9 +6,9 @@ toc: true url: /nginxaas/aws/deploy/ssl-tls-certificates/overview/ f5-content-type: reference f5-product: NGINXaaS for AWS -f5-keywords: "NGINXaaS for AWS, SSL, TLS, certificates, AWS Secrets Manager, certificate rotation, PEM" +f5-keywords: "NGINXaaS for AWS, SSL, TLS, certificates, AWS Secrets Manager, certificate rotation, PEM, ML-DSA, post-quantum, PQC" f5-summary: > - This reference covers the SSL/TLS certificate types and formats F5 NGINXaaS for AWS supports, and the two ways to manage them: the NGINXaaS Console and AWS Secrets Manager. + This reference covers the SSL/TLS certificate types and formats F5 NGINXaaS for AWS supports, including post-quantum ML-DSA certificates, and the two ways to manage them: the NGINXaaS Console and AWS Secrets Manager. Use it to choose a certificate management approach and understand automatic and manual rotation options. f5-audience: operator --- @@ -27,6 +27,13 @@ Encrypt your certificates, keys, and PEM files using one of these algorithms: - RSA - ECC/ECDSA +- ML-DSA (post-quantum KEX) + +{{< call-out class="note" title="ML-DSA key format support" >}} +When you upload an ML-DSA private key using the NGINXaaS Console, only the seed-only key format is supported. +If you store your ML-DSA key in AWS Secrets Manager, both seed-only and seed-priv formats are supported. +See [Enable post-quantum cryptography]({{< ref "/nginxaas/aws/quickstart/pqc.md" >}}) for configuration guidance. +{{< /call-out >}} ## Add SSL/TLS certificates diff --git a/content/nginxaas/aws/quickstart/_index.md b/content/nginxaas/aws/quickstart/_index.md new file mode 100644 index 000000000..9a8193877 --- /dev/null +++ b/content/nginxaas/aws/quickstart/_index.md @@ -0,0 +1,5 @@ +--- +title: Quickstart guides +weight: 500 +url: /nginxaas/aws/quickstart/ +--- diff --git a/content/nginxaas/aws/quickstart/pqc.md b/content/nginxaas/aws/quickstart/pqc.md new file mode 100644 index 000000000..d3cce58bd --- /dev/null +++ b/content/nginxaas/aws/quickstart/pqc.md @@ -0,0 +1,162 @@ +--- +title: Enable post-quantum cryptography +description: "Configure F5 NGINXaaS for AWS to use hybrid ML-KEM key exchange or ML-DSA certificates for post-quantum TLS protection." +weight: 100 +toc: true +f5-docs: DOCS-000 +url: /nginxaas/aws/quickstart/pqc/ +f5-content-type: how-to +f5-product: NGINXaaS for AWS +f5-keywords: "NGINXaaS for AWS, PQC, post-quantum cryptography, ML-KEM, ML-DSA, TLS 1.3, hybrid mode, quantum-safe" +f5-summary: > + Learn how to enable post-quantum cryptography in F5 NGINXaaS for AWS using hybrid ML-KEM key exchange or ML-DSA certificates. + This guide covers both modes, key format requirements, and optional NGINX configuration for hardening. +f5-audience: operator +--- + +Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today — the "harvest now, decrypt later" threat. NGINXaaS for AWS addresses this with two modes: + +- **Hybrid mode**: Combines classical elliptic-curve key exchange (EC) with ML-KEM for data encryption. This protects against quantum attacks while staying compatible with clients that don't yet support PQC. +- **Full PQC mode**: Uses ML-DSA certificates and keys that you provide. This gives you a fully post-quantum TLS stack when both client and server support it. + +## Before you begin + +Before you begin, ensure you have: + +- **An existing NGINXaaS for AWS deployment**: See [Create a deployment]({{< ref "/nginxaas/aws/deploy/create-deployment/deploy-console.md" >}}) if you need to create one. +- **TLS 1.3 in your NGINX configuration**: NGINX includes TLSv1.3 in its default `ssl_protocols` value alongside TLSv1.2. ML-KEM hybrid key exchange only applies to TLS 1.3 connections. To prevent clients from downgrading to TLS 1.2, restrict `ssl_protocols` to `TLSv1.3` only — this is recommended for maximum security but drops support for older clients. + +--- + +## Enable hybrid mode (ML-KEM key exchange) + +Hybrid mode is active by default. NGINX includes TLSv1.3 in its default `ssl_protocols` value, and ML-KEM hybrid groups are part of the default key exchange group list. No configuration changes are required in the NGINXaaS console for hybrid mode to work. + +Clients that support ML-KEM will negotiate it automatically on TLS 1.3 connections. Clients that don't support ML-KEM fall back to classical key exchange. + +### Recommended: Restrict to TLS 1.3 only + +Because hybrid ML-KEM key exchange applies only to TLS 1.3 connections, allowing TLS 1.2 means some clients can still negotiate a purely classical handshake. To prevent downgrade, restrict `ssl_protocols` to `TLSv1.3` only: + +1. Select **Configurations** in the left menu. +2. Select the ellipsis (three dots) next to your configuration and select **Edit**. +3. Add `ssl_protocols TLSv1.3;` to your `server` block: + + ```nginx + server { + listen 443 ssl; + ssl_protocols TLSv1.3; + ssl_certificate /etc/nginx/certs/server.crt; + ssl_certificate_key /etc/nginx/certs/server.key; + # ... + } + ``` + +4. Select **Next** and then **Save** to apply the change. + +{{< call-out class="note" title="Client compatibility" >}} +Restricting to TLSv1.3 drops support for clients that only support TLS 1.2. If you need to support older clients, keep the default `ssl_protocols` value and accept that those connections won't use ML-KEM. +{{< /call-out >}} + +### Optional: Explicitly configure ML-KEM hybrid groups + +If you want to enforce a specific group order or exclude classical-only groups, set `ssl_ecdh_curve` in your `server` block. The following snippet enables ML-KEM hybrid (`X25519MLKEM768`) first, with `X25519` as a classical fallback: + +```nginx +server { + listen 443 ssl; + ssl_protocols TLSv1.3; + ssl_ecdh_curve X25519MLKEM768:X25519; + ssl_certificate /etc/nginx/certs/server.crt; + ssl_certificate_key /etc/nginx/certs/server.key; + # ... +} +``` + +{{< call-out class="note" title="Fallback behavior" >}} +Including `X25519` after `X25519MLKEM768` lets clients that don't support ML-KEM fall back to classical key exchange. Remove `X25519` only if you want to restrict connections to ML-KEM-capable clients. +{{< /call-out >}} + +--- + +## Enable full PQC mode (ML-DSA certificates) + +Full PQC mode requires you to upload an ML-DSA certificate and private key. NGINXaaS for AWS accepts ML-DSA keys in PEM format with the following constraints: + +- **NGINXaaS Console**: Seed-only key format only. +- **AWS Secrets Manager**: Seed-only and seed-priv formats are both supported. + +Choose the method that matches your key format. + +### Upload an ML-DSA certificate using the Console + +Use this method if your ML-DSA private key is in seed-only format. + +1. Follow the steps in [Add certificates using the Console]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}) to upload your ML-DSA certificate and key. +2. In your NGINX configuration, reference the certificate and key with `ssl_certificate` and `ssl_certificate_key`, and set `ssl_protocols TLSv1.3;`: + + ```nginx + server { + listen 443 ssl; + ssl_protocols TLSv1.3; + ssl_certificate /etc/nginx/certs/mldsa.crt; + ssl_certificate_key /etc/nginx/certs/mldsa.key; + # ... + } + ``` + +3. Select **Next** and then **Save** to apply the configuration. + +### Store an ML-DSA certificate in AWS Secrets Manager + +Use this method if your ML-DSA private key is in seed-priv format, or if you want to keep your keys within AWS. + +1. Add your ML-DSA certificate and key to AWS Secrets Manager. Follow the steps in [Add an SSL/TLS certificate to AWS Secrets Manager]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-secrets-manager.md#add-an-ssltls-certificate-to-aws-secrets-manager" >}}). +2. Reference the secret in your NGINX configuration as described in [Use an AWS Secrets Manager certificate in an NGINX configuration]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-secrets-manager.md#use-an-aws-secrets-manager-certificate-in-an-nginx-configuration" >}}). +3. Add `ssl_protocols TLSv1.3;` to your `server` block. + +--- + +## Verify post-quantum negotiation + +To confirm that a client is negotiating a post-quantum key exchange group with your deployment, inspect the TLS handshake from the client side using OpenSSL: + +```shell +openssl s_client -connect :443 -groups X25519MLKEM768 +``` + +In the output, look for the `Negotiated TLS1.3 group` line. A successful hybrid negotiation shows: + +```text +Negotiated TLS1.3 group: X25519MLKEM768 +``` + +If you see `X25519` or another classical group instead, check that `ssl_protocols TLSv1.3;` is set and that no `ssl_ecdh_curve` directive is overriding the defaults with classical-only groups. + +### Track ML-KEM adoption across real clients + +OpenSSL spot-checks confirm your server is ready, but they don't show which of your actual clients negotiate ML-KEM. Use the [`$ssl_curve`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#var_ssl_curve) NGINX variable to log the key exchange group negotiated for each connection, then analyze the logs to measure adoption over time. + +Add a custom `log_format` and an `access_log` directive to your NGINX configuration: + +```nginx +http { + log_format pqc_tracking '$remote_addr - $ssl_protocol $ssl_curve'; + access_log /var/log/nginx/ssl-details.log pqc_tracking; + # ... +} +``` + +In the logs, connections that negotiated ML-KEM hybrid key exchange appear with `X25519MLKEM768` in the `$ssl_curve` field. Classical TLS 1.3 connections appear with `X25519` or another classical group name, and TLS 1.2 connections return an empty value. + +{{< call-out class="note" title="Log storage" >}} +NGINX writes logs to the filesystem of your deployment. Make sure the log path is within an [allowed directory]({{< ref "/nginxaas/aws/deploy/nginx-configuration/configuration-rules.md#nginx-filesystem-restrictions" >}}) and that you have a plan for collecting or rotating the logs before they fill available space. +{{< /call-out >}} + +--- + +## What's next + +- [SSL/TLS certificate overview]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/overview.md" >}}) — supported certificate types, formats, and rotation options. +- [Add certificates using the Console]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}) — manage certificates alongside your NGINX configuration. +- [Add certificates from AWS Secrets Manager]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-secrets-manager.md" >}}) — fetch secrets directly from AWS Secrets Manager. diff --git a/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md b/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md index 93cbcab02..40f61c37d 100644 --- a/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md +++ b/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md @@ -1,10 +1,17 @@ --- title: Overview +description: "Reference for supported SSL/TLS certificate types and how to add them to an F5 NGINXaaS for Google Cloud deployment." weight: 50 toc: true url: /nginxaas/google/deploy/ssl-tls-certificates/overview/ f5-content-type: reference f5-product: NGINXaaS for Google Cloud +f5-docs: DOCS-000 +f5-keywords: "NGINXaaS for Google Cloud, SSL, TLS, certificates, Google Secret Manager, certificate rotation, PEM, ML-DSA, post-quantum, PQC" +f5-summary: > + This reference covers the SSL/TLS certificate types and formats F5 NGINXaaS for Google Cloud supports, including post-quantum ML-DSA certificates, and the two ways to manage them: the NGINXaaS Console and Google Secret Manager. + Use it to choose a certificate management approach and understand automatic and manual rotation options. +f5-audience: operator --- Use F5 NGINXaaS for Google Cloud (NGINXaaS) to secure traffic by adding SSL/TLS certificates to a deployment. @@ -21,6 +28,13 @@ Encrypt your certificates, keys, and PEM files using one of these standards: - RSA - ECC/ECDSA +- ML-DSA (post-quantum KEX) + +{{< call-out class="note" title="ML-DSA key format support" >}} +When you upload an ML-DSA private key using the NGINXaaS Console, only the seed-only key format is supported. +If you store your ML-DSA key in Google Secret Manager, both seed-only and seed-priv formats are supported. +See [Enable post-quantum cryptography]({{< ref "/nginxaas/google/quickstart/pqc.md" >}}) for configuration guidance. +{{< /call-out >}} ## Add SSL/TLS certificates diff --git a/content/nginxaas/google/quickstart/_index.md b/content/nginxaas/google/quickstart/_index.md new file mode 100644 index 000000000..ddd4927cd --- /dev/null +++ b/content/nginxaas/google/quickstart/_index.md @@ -0,0 +1,5 @@ +--- +title: Quickstart guides +weight: 500 +url: /nginxaas/google/quickstart/ +--- diff --git a/content/nginxaas/google/quickstart/pqc.md b/content/nginxaas/google/quickstart/pqc.md new file mode 100644 index 000000000..68d21767e --- /dev/null +++ b/content/nginxaas/google/quickstart/pqc.md @@ -0,0 +1,162 @@ +--- +title: Enable post-quantum cryptography +description: "Configure F5 NGINXaaS for Google Cloud to use hybrid ML-KEM key exchange or ML-DSA certificates for post-quantum TLS protection." +weight: 100 +toc: true +f5-docs: DOCS-000 +url: /nginxaas/google/quickstart/pqc/ +f5-content-type: how-to +f5-product: NGINXaaS for Google Cloud +f5-keywords: "NGINXaaS for Google Cloud, PQC, post-quantum cryptography, ML-KEM, ML-DSA, TLS 1.3, hybrid mode, quantum-safe" +f5-summary: > + Learn how to enable post-quantum cryptography in F5 NGINXaaS for Google Cloud using hybrid ML-KEM key exchange or ML-DSA certificates. + This guide covers both modes, key format requirements, and optional NGINX configuration for hardening. +f5-audience: operator +--- + +Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today — the "harvest now, decrypt later" threat. NGINXaaS for Google Cloud addresses this with two modes: + +- **Hybrid mode**: Combines classical elliptic-curve key exchange (EC) with ML-KEM for data encryption. This protects against quantum attacks while staying compatible with clients that don't yet support PQC. +- **Full PQC mode**: Uses ML-DSA certificates and keys that you provide. This gives you a fully post-quantum TLS stack when both client and server support it. + +## Before you begin + +Before you begin, ensure you have: + +- **An existing NGINXaaS for Google Cloud deployment**: See [Create a deployment]({{< ref "/nginxaas/google/deploy/create-deployment/deploy-console.md" >}}) if you need to create one. +- **TLS 1.3 in your NGINX configuration**: NGINX includes TLSv1.3 in its default `ssl_protocols` value alongside TLSv1.2. ML-KEM hybrid key exchange only applies to TLS 1.3 connections. To prevent clients from downgrading to TLS 1.2, restrict `ssl_protocols` to `TLSv1.3` only — this is recommended for maximum security but drops support for older clients. + +--- + +## Enable hybrid mode (ML-KEM key exchange) + +Hybrid mode is active by default. NGINX includes TLSv1.3 in its default `ssl_protocols` value, and ML-KEM hybrid groups are part of the default key exchange group list. No configuration changes are required in the NGINXaaS console for hybrid mode to work. + +Clients that support ML-KEM will negotiate it automatically on TLS 1.3 connections. Clients that don't support ML-KEM fall back to classical key exchange. + +### Recommended: Restrict to TLS 1.3 only + +Because hybrid ML-KEM key exchange applies only to TLS 1.3 connections, allowing TLS 1.2 means some clients can still negotiate a purely classical handshake. To prevent downgrade, restrict `ssl_protocols` to `TLSv1.3` only: + +1. Select **Configurations** in the left menu. +2. Select the ellipsis (three dots) next to your configuration and select **Edit**. +3. Add `ssl_protocols TLSv1.3;` to your `server` block: + + ```nginx + server { + listen 443 ssl; + ssl_protocols TLSv1.3; + ssl_certificate /etc/nginx/certs/server.crt; + ssl_certificate_key /etc/nginx/certs/server.key; + # ... + } + ``` + +4. Select **Next** and then **Save** to apply the change. + +{{< call-out class="note" title="Client compatibility" >}} +Restricting to TLSv1.3 drops support for clients that only support TLS 1.2. If you need to support older clients, keep the default `ssl_protocols` value and accept that those connections won't use ML-KEM. +{{< /call-out >}} + +### Optional: Explicitly configure ML-KEM hybrid groups + +If you want to enforce a specific group order or exclude classical-only groups, set `ssl_ecdh_curve` in your `server` block. The following snippet enables ML-KEM hybrid (`X25519MLKEM768`) first, with `X25519` as a classical fallback: + +```nginx +server { + listen 443 ssl; + ssl_protocols TLSv1.3; + ssl_ecdh_curve X25519MLKEM768:X25519; + ssl_certificate /etc/nginx/certs/server.crt; + ssl_certificate_key /etc/nginx/certs/server.key; + # ... +} +``` + +{{< call-out class="note" title="Fallback behavior" >}} +Including `X25519` after `X25519MLKEM768` lets clients that don't support ML-KEM fall back to classical key exchange. Remove `X25519` only if you want to restrict connections to ML-KEM-capable clients. +{{< /call-out >}} + +--- + +## Enable full PQC mode (ML-DSA certificates) + +Full PQC mode requires you to upload an ML-DSA certificate and private key. NGINXaaS for Google Cloud accepts ML-DSA keys in PEM format with the following constraints: + +- **NGINXaaS Console**: Seed-only key format only. +- **Google Secret Manager**: Seed-only and seed-priv formats are both supported. + +Choose the method that matches your key format. + +### Upload an ML-DSA certificate using the Console + +Use this method if your ML-DSA private key is in seed-only format. + +1. Follow the steps in [Add certificates using the Console]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}) to upload your ML-DSA certificate and key. +2. In your NGINX configuration, reference the certificate and key with `ssl_certificate` and `ssl_certificate_key`, and set `ssl_protocols TLSv1.3;`: + + ```nginx + server { + listen 443 ssl; + ssl_protocols TLSv1.3; + ssl_certificate /etc/nginx/certs/mldsa.crt; + ssl_certificate_key /etc/nginx/certs/mldsa.key; + # ... + } + ``` + +3. Select **Next** and then **Save** to apply the configuration. + +### Store an ML-DSA certificate in Google Secret Manager + +Use this method if your ML-DSA private key is in seed-priv format, or if you want to keep your keys within Google Cloud. + +1. Add your ML-DSA certificate and key to Google Secret Manager. Follow the steps in [Add an SSL/TLS certificate to Secret Manager]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md#add-an-ssltls-certificate-to-secret-manager" >}}). +2. Reference the secret in your NGINX configuration as described in [Use a Secret Manager certificate in an NGINX configuration]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md#use-a-secret-manager-certificate-in-an-nginx-configuration" >}}). +3. Add `ssl_protocols TLSv1.3;` to your `server` block. + +--- + +## Verify post-quantum negotiation + +To confirm that a client is negotiating a post-quantum key exchange group with your deployment, inspect the TLS handshake from the client side using OpenSSL: + +```shell +openssl s_client -connect :443 -groups X25519MLKEM768 +``` + +In the output, look for the `Negotiated TLS1.3 group` line. A successful hybrid negotiation shows: + +```text +Negotiated TLS1.3 group: X25519MLKEM768 +``` + +If you see `X25519` or another classical group instead, check that `ssl_protocols TLSv1.3;` is set and that no `ssl_ecdh_curve` directive is overriding the defaults with classical-only groups. + +### Track ML-KEM adoption across real clients + +OpenSSL spot-checks confirm your server is ready, but they don't show which of your actual clients negotiate ML-KEM. Use the [`$ssl_curve`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#var_ssl_curve) NGINX variable to log the key exchange group negotiated for each connection, then analyze the logs to measure adoption over time. + +Add a custom `log_format` and an `access_log` directive to your NGINX configuration: + +```nginx +http { + log_format pqc_tracking '$remote_addr - $ssl_protocol $ssl_curve'; + access_log /var/log/nginx/ssl-details.log pqc_tracking; + # ... +} +``` + +In the logs, connections that negotiated ML-KEM hybrid key exchange appear with `X25519MLKEM768` in the `$ssl_curve` field. Classical TLS 1.3 connections appear with `X25519` or another classical group name, and TLS 1.2 connections return an empty value. + +{{< call-out class="note" title="Log storage" >}} +NGINX writes logs to the filesystem of your deployment. Make sure the log path is within an [allowed directory]({{< ref "/nginxaas/google/deploy/nginx-configuration/configuration-rules.md#nginx-filesystem-restrictions" >}}) and that you have a plan for collecting or rotating the logs before they fill available space. +{{< /call-out >}} + +--- + +## What's next + +- [SSL/TLS certificate overview]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/overview.md" >}}) — supported certificate types, formats, and rotation options. +- [Add certificates using the Console]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}) — manage certificates alongside your NGINX configuration. +- [Add certificates from Secret Manager]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md" >}}) — fetch secrets directly from Google Secret Manager. From c280a9d4c15e1f25b28403314015361b84f96aa6 Mon Sep 17 00:00:00 2001 From: Andrei Belov Date: Mon, 21 Sep 2026 13:28:33 -0600 Subject: [PATCH 2/9] fix: get rid of em-dashes --- content/nginxaas/aws/quickstart/pqc.md | 10 +++++----- content/nginxaas/google/quickstart/pqc.md | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/content/nginxaas/aws/quickstart/pqc.md b/content/nginxaas/aws/quickstart/pqc.md index d3cce58bd..813f88da9 100644 --- a/content/nginxaas/aws/quickstart/pqc.md +++ b/content/nginxaas/aws/quickstart/pqc.md @@ -14,7 +14,7 @@ f5-summary: > f5-audience: operator --- -Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today — the "harvest now, decrypt later" threat. NGINXaaS for AWS addresses this with two modes: +Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today - the "harvest now, decrypt later" threat. NGINXaaS for AWS addresses this with two modes: - **Hybrid mode**: Combines classical elliptic-curve key exchange (EC) with ML-KEM for data encryption. This protects against quantum attacks while staying compatible with clients that don't yet support PQC. - **Full PQC mode**: Uses ML-DSA certificates and keys that you provide. This gives you a fully post-quantum TLS stack when both client and server support it. @@ -24,7 +24,7 @@ Post-quantum cryptography (PQC) protects TLS connections against future quantum Before you begin, ensure you have: - **An existing NGINXaaS for AWS deployment**: See [Create a deployment]({{< ref "/nginxaas/aws/deploy/create-deployment/deploy-console.md" >}}) if you need to create one. -- **TLS 1.3 in your NGINX configuration**: NGINX includes TLSv1.3 in its default `ssl_protocols` value alongside TLSv1.2. ML-KEM hybrid key exchange only applies to TLS 1.3 connections. To prevent clients from downgrading to TLS 1.2, restrict `ssl_protocols` to `TLSv1.3` only — this is recommended for maximum security but drops support for older clients. +- **TLS 1.3 in your NGINX configuration**: NGINX includes TLSv1.3 in its default `ssl_protocols` value alongside TLSv1.2. ML-KEM hybrid key exchange only applies to TLS 1.3 connections. To prevent clients from downgrading to TLS 1.2, restrict `ssl_protocols` to `TLSv1.3` only - this is recommended for maximum security but drops support for older clients. --- @@ -157,6 +157,6 @@ NGINX writes logs to the filesystem of your deployment. Make sure the log path i ## What's next -- [SSL/TLS certificate overview]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/overview.md" >}}) — supported certificate types, formats, and rotation options. -- [Add certificates using the Console]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}) — manage certificates alongside your NGINX configuration. -- [Add certificates from AWS Secrets Manager]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-secrets-manager.md" >}}) — fetch secrets directly from AWS Secrets Manager. +- [SSL/TLS certificate overview]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/overview.md" >}}) - supported certificate types, formats, and rotation options. +- [Add certificates using the Console]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}) - manage certificates alongside your NGINX configuration. +- [Add certificates from AWS Secrets Manager]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-secrets-manager.md" >}}) - fetch secrets directly from AWS Secrets Manager. diff --git a/content/nginxaas/google/quickstart/pqc.md b/content/nginxaas/google/quickstart/pqc.md index 68d21767e..0371fc705 100644 --- a/content/nginxaas/google/quickstart/pqc.md +++ b/content/nginxaas/google/quickstart/pqc.md @@ -14,7 +14,7 @@ f5-summary: > f5-audience: operator --- -Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today — the "harvest now, decrypt later" threat. NGINXaaS for Google Cloud addresses this with two modes: +Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today - the "harvest now, decrypt later" threat. NGINXaaS for Google Cloud addresses this with two modes: - **Hybrid mode**: Combines classical elliptic-curve key exchange (EC) with ML-KEM for data encryption. This protects against quantum attacks while staying compatible with clients that don't yet support PQC. - **Full PQC mode**: Uses ML-DSA certificates and keys that you provide. This gives you a fully post-quantum TLS stack when both client and server support it. @@ -24,7 +24,7 @@ Post-quantum cryptography (PQC) protects TLS connections against future quantum Before you begin, ensure you have: - **An existing NGINXaaS for Google Cloud deployment**: See [Create a deployment]({{< ref "/nginxaas/google/deploy/create-deployment/deploy-console.md" >}}) if you need to create one. -- **TLS 1.3 in your NGINX configuration**: NGINX includes TLSv1.3 in its default `ssl_protocols` value alongside TLSv1.2. ML-KEM hybrid key exchange only applies to TLS 1.3 connections. To prevent clients from downgrading to TLS 1.2, restrict `ssl_protocols` to `TLSv1.3` only — this is recommended for maximum security but drops support for older clients. +- **TLS 1.3 in your NGINX configuration**: NGINX includes TLSv1.3 in its default `ssl_protocols` value alongside TLSv1.2. ML-KEM hybrid key exchange only applies to TLS 1.3 connections. To prevent clients from downgrading to TLS 1.2, restrict `ssl_protocols` to `TLSv1.3` only - this is recommended for maximum security but drops support for older clients. --- @@ -157,6 +157,6 @@ NGINX writes logs to the filesystem of your deployment. Make sure the log path i ## What's next -- [SSL/TLS certificate overview]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/overview.md" >}}) — supported certificate types, formats, and rotation options. -- [Add certificates using the Console]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}) — manage certificates alongside your NGINX configuration. -- [Add certificates from Secret Manager]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md" >}}) — fetch secrets directly from Google Secret Manager. +- [SSL/TLS certificate overview]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/overview.md" >}}) - supported certificate types, formats, and rotation options. +- [Add certificates using the Console]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}) - manage certificates alongside your NGINX configuration. +- [Add certificates from Secret Manager]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md" >}}) - fetch secrets directly from Google Secret Manager. From 9d7eca8b18fe6f4865fd145efdd44ca090d24c36 Mon Sep 17 00:00:00 2001 From: Andrei Belov Date: Mon, 21 Sep 2026 13:30:19 -0600 Subject: [PATCH 3/9] fix: address style pattern when referencing to F5 products --- content/nginxaas/aws/quickstart/pqc.md | 2 +- content/nginxaas/google/quickstart/pqc.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/nginxaas/aws/quickstart/pqc.md b/content/nginxaas/aws/quickstart/pqc.md index 813f88da9..d36435206 100644 --- a/content/nginxaas/aws/quickstart/pqc.md +++ b/content/nginxaas/aws/quickstart/pqc.md @@ -14,7 +14,7 @@ f5-summary: > f5-audience: operator --- -Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today - the "harvest now, decrypt later" threat. NGINXaaS for AWS addresses this with two modes: +Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today - the "harvest now, decrypt later" threat. F5 NGINXaaS for AWS addresses this with two modes: - **Hybrid mode**: Combines classical elliptic-curve key exchange (EC) with ML-KEM for data encryption. This protects against quantum attacks while staying compatible with clients that don't yet support PQC. - **Full PQC mode**: Uses ML-DSA certificates and keys that you provide. This gives you a fully post-quantum TLS stack when both client and server support it. diff --git a/content/nginxaas/google/quickstart/pqc.md b/content/nginxaas/google/quickstart/pqc.md index 0371fc705..51e9a46c4 100644 --- a/content/nginxaas/google/quickstart/pqc.md +++ b/content/nginxaas/google/quickstart/pqc.md @@ -14,7 +14,7 @@ f5-summary: > f5-audience: operator --- -Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today - the "harvest now, decrypt later" threat. NGINXaaS for Google Cloud addresses this with two modes: +Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today - the "harvest now, decrypt later" threat. F5 NGINXaaS for Google Cloud addresses this with two modes: - **Hybrid mode**: Combines classical elliptic-curve key exchange (EC) with ML-KEM for data encryption. This protects against quantum attacks while staying compatible with clients that don't yet support PQC. - **Full PQC mode**: Uses ML-DSA certificates and keys that you provide. This gives you a fully post-quantum TLS stack when both client and server support it. From 2d74b17b1efd15012f755d6836e98c4975e6de61 Mon Sep 17 00:00:00 2001 From: Andrei Belov Date: Mon, 21 Sep 2026 13:33:52 -0600 Subject: [PATCH 4/9] fix: remove misleading reference to KEX from ML-DSA mentions --- content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md | 2 +- content/nginxaas/google/deploy/ssl-tls-certificates/overview.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md b/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md index 5ff8ad076..bc8b43db5 100644 --- a/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md +++ b/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md @@ -27,7 +27,7 @@ Encrypt your certificates, keys, and PEM files using one of these algorithms: - RSA - ECC/ECDSA -- ML-DSA (post-quantum KEX) +- ML-DSA (post-quantum) {{< call-out class="note" title="ML-DSA key format support" >}} When you upload an ML-DSA private key using the NGINXaaS Console, only the seed-only key format is supported. diff --git a/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md b/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md index 40f61c37d..fb44ab916 100644 --- a/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md +++ b/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md @@ -28,7 +28,7 @@ Encrypt your certificates, keys, and PEM files using one of these standards: - RSA - ECC/ECDSA -- ML-DSA (post-quantum KEX) +- ML-DSA (post-quantum) {{< call-out class="note" title="ML-DSA key format support" >}} When you upload an ML-DSA private key using the NGINXaaS Console, only the seed-only key format is supported. From 1875e7e85b07d526ef914656eda9d19cf45669ab Mon Sep 17 00:00:00 2001 From: Andrei Belov Date: Mon, 21 Sep 2026 14:37:13 -0600 Subject: [PATCH 5/9] fix: address review comments --- content/nginxaas/aws/quickstart/pqc.md | 4 ++-- content/nginxaas/google/quickstart/pqc.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/nginxaas/aws/quickstart/pqc.md b/content/nginxaas/aws/quickstart/pqc.md index d36435206..9ba45b741 100644 --- a/content/nginxaas/aws/quickstart/pqc.md +++ b/content/nginxaas/aws/quickstart/pqc.md @@ -131,7 +131,7 @@ In the output, look for the `Negotiated TLS1.3 group` line. A successful hybrid Negotiated TLS1.3 group: X25519MLKEM768 ``` -If you see `X25519` or another classical group instead, check that `ssl_protocols TLSv1.3;` is set and that no `ssl_ecdh_curve` directive is overriding the defaults with classical-only groups. +If you see `X25519` or another classical group instead, check that `ssl_protocols TLSv1.3;` is set, and that no `ssl_ecdh_curve` directive is overriding the defaults with classical-only groups. ### Track ML-KEM adoption across real clients @@ -150,7 +150,7 @@ http { In the logs, connections that negotiated ML-KEM hybrid key exchange appear with `X25519MLKEM768` in the `$ssl_curve` field. Classical TLS 1.3 connections appear with `X25519` or another classical group name, and TLS 1.2 connections return an empty value. {{< call-out class="note" title="Log storage" >}} -NGINX writes logs to the filesystem of your deployment. Make sure the log path is within an [allowed directory]({{< ref "/nginxaas/aws/deploy/nginx-configuration/configuration-rules.md#nginx-filesystem-restrictions" >}}) and that you have a plan for collecting or rotating the logs before they fill available space. +NGINX writes logs to the filesystem of your deployment. Make sure the log path is within an [allowed directory]({{< ref "/nginxaas/aws/deploy/nginx-configuration/configuration-rules.md#nginx-filesystem-restrictions" >}}), and that you have a plan for collecting or rotating the logs before they fill available space. {{< /call-out >}} --- diff --git a/content/nginxaas/google/quickstart/pqc.md b/content/nginxaas/google/quickstart/pqc.md index 51e9a46c4..31fdc233b 100644 --- a/content/nginxaas/google/quickstart/pqc.md +++ b/content/nginxaas/google/quickstart/pqc.md @@ -131,7 +131,7 @@ In the output, look for the `Negotiated TLS1.3 group` line. A successful hybrid Negotiated TLS1.3 group: X25519MLKEM768 ``` -If you see `X25519` or another classical group instead, check that `ssl_protocols TLSv1.3;` is set and that no `ssl_ecdh_curve` directive is overriding the defaults with classical-only groups. +If you see `X25519` or another classical group instead, check that `ssl_protocols TLSv1.3;` is set, and that no `ssl_ecdh_curve` directive is overriding the defaults with classical-only groups. ### Track ML-KEM adoption across real clients @@ -150,7 +150,7 @@ http { In the logs, connections that negotiated ML-KEM hybrid key exchange appear with `X25519MLKEM768` in the `$ssl_curve` field. Classical TLS 1.3 connections appear with `X25519` or another classical group name, and TLS 1.2 connections return an empty value. {{< call-out class="note" title="Log storage" >}} -NGINX writes logs to the filesystem of your deployment. Make sure the log path is within an [allowed directory]({{< ref "/nginxaas/google/deploy/nginx-configuration/configuration-rules.md#nginx-filesystem-restrictions" >}}) and that you have a plan for collecting or rotating the logs before they fill available space. +NGINX writes logs to the filesystem of your deployment. Make sure the log path is within an [allowed directory]({{< ref "/nginxaas/google/deploy/nginx-configuration/configuration-rules.md#nginx-filesystem-restrictions" >}}), and that you have a plan for collecting or rotating the logs before they fill available space. {{< /call-out >}} --- From 928b7c5898f21fcf40a35c86a4f1f52dc96a7347 Mon Sep 17 00:00:00 2001 From: Andrei Belov Date: Mon, 21 Sep 2026 15:07:12 -0600 Subject: [PATCH 6/9] fix: point to corresponding log collection sections from quick-start --- content/nginxaas/aws/quickstart/pqc.md | 4 ++-- content/nginxaas/google/quickstart/pqc.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/nginxaas/aws/quickstart/pqc.md b/content/nginxaas/aws/quickstart/pqc.md index 9ba45b741..532bcd8c2 100644 --- a/content/nginxaas/aws/quickstart/pqc.md +++ b/content/nginxaas/aws/quickstart/pqc.md @@ -149,8 +149,8 @@ http { In the logs, connections that negotiated ML-KEM hybrid key exchange appear with `X25519MLKEM768` in the `$ssl_curve` field. Classical TLS 1.3 connections appear with `X25519` or another classical group name, and TLS 1.2 connections return an empty value. -{{< call-out class="note" title="Log storage" >}} -NGINX writes logs to the filesystem of your deployment. Make sure the log path is within an [allowed directory]({{< ref "/nginxaas/aws/deploy/nginx-configuration/configuration-rules.md#nginx-filesystem-restrictions" >}}), and that you have a plan for collecting or rotating the logs before they fill available space. +{{< call-out class="note" title="Collecting logs" >}} +To forward logs to AWS CloudWatch, see [Enable NGINX logs]({{< ref "/nginxaas/aws/monitoring/enable-nginx-logs.md" >}}). {{< /call-out >}} --- diff --git a/content/nginxaas/google/quickstart/pqc.md b/content/nginxaas/google/quickstart/pqc.md index 31fdc233b..0863e662e 100644 --- a/content/nginxaas/google/quickstart/pqc.md +++ b/content/nginxaas/google/quickstart/pqc.md @@ -149,8 +149,8 @@ http { In the logs, connections that negotiated ML-KEM hybrid key exchange appear with `X25519MLKEM768` in the `$ssl_curve` field. Classical TLS 1.3 connections appear with `X25519` or another classical group name, and TLS 1.2 connections return an empty value. -{{< call-out class="note" title="Log storage" >}} -NGINX writes logs to the filesystem of your deployment. Make sure the log path is within an [allowed directory]({{< ref "/nginxaas/google/deploy/nginx-configuration/configuration-rules.md#nginx-filesystem-restrictions" >}}), and that you have a plan for collecting or rotating the logs before they fill available space. +{{< call-out class="note" title="Collecting logs" >}} +To forward logs to Cloud Logging, see [Enable NGINX logs]({{< ref "/nginxaas/google/monitoring/enable-nginx-logs.md" >}}). {{< /call-out >}} --- From 77af5c5c16206f428d6630a0fc9fff3b98a783fc Mon Sep 17 00:00:00 2001 From: Andrei Belov Date: Mon, 21 Sep 2026 17:54:12 -0600 Subject: [PATCH 7/9] fix: address review comments --- content/nginxaas/aws/quickstart/pqc.md | 16 +++++++++------- content/nginxaas/google/quickstart/pqc.md | 16 +++++++++------- 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/content/nginxaas/aws/quickstart/pqc.md b/content/nginxaas/aws/quickstart/pqc.md index 532bcd8c2..17eb23145 100644 --- a/content/nginxaas/aws/quickstart/pqc.md +++ b/content/nginxaas/aws/quickstart/pqc.md @@ -39,8 +39,8 @@ Clients that support ML-KEM will negotiate it automatically on TLS 1.3 connectio Because hybrid ML-KEM key exchange applies only to TLS 1.3 connections, allowing TLS 1.2 means some clients can still negotiate a purely classical handshake. To prevent downgrade, restrict `ssl_protocols` to `TLSv1.3` only: 1. Select **Configurations** in the left menu. -2. Select the ellipsis (three dots) next to your configuration and select **Edit**. -3. Add `ssl_protocols TLSv1.3;` to your `server` block: +1. Select the ellipsis (three dots) next to your configuration and select **Edit**. +1. Add `ssl_protocols TLSv1.3;` to your `server` block: ```nginx server { @@ -52,7 +52,8 @@ Because hybrid ML-KEM key exchange applies only to TLS 1.3 connections, allowing } ``` -4. Select **Next** and then **Save** to apply the change. +1. Select **Next** and then **Save** to apply the change. +1. Deploy configuration to relevant deployments. {{< call-out class="note" title="Client compatibility" >}} Restricting to TLSv1.3 drops support for clients that only support TLS 1.2. If you need to support older clients, keep the default `ssl_protocols` value and accept that those connections won't use ML-KEM. @@ -93,7 +94,7 @@ Choose the method that matches your key format. Use this method if your ML-DSA private key is in seed-only format. 1. Follow the steps in [Add certificates using the Console]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}) to upload your ML-DSA certificate and key. -2. In your NGINX configuration, reference the certificate and key with `ssl_certificate` and `ssl_certificate_key`, and set `ssl_protocols TLSv1.3;`: +1. In your NGINX configuration, reference the certificate and key with `ssl_certificate` and `ssl_certificate_key`, and set `ssl_protocols TLSv1.3;`: ```nginx server { @@ -105,15 +106,16 @@ Use this method if your ML-DSA private key is in seed-only format. } ``` -3. Select **Next** and then **Save** to apply the configuration. +1. Select **Next** and then **Save** to apply the change. +1. Deploy configuration to relevant deployments. ### Store an ML-DSA certificate in AWS Secrets Manager Use this method if your ML-DSA private key is in seed-priv format, or if you want to keep your keys within AWS. 1. Add your ML-DSA certificate and key to AWS Secrets Manager. Follow the steps in [Add an SSL/TLS certificate to AWS Secrets Manager]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-secrets-manager.md#add-an-ssltls-certificate-to-aws-secrets-manager" >}}). -2. Reference the secret in your NGINX configuration as described in [Use an AWS Secrets Manager certificate in an NGINX configuration]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-secrets-manager.md#use-an-aws-secrets-manager-certificate-in-an-nginx-configuration" >}}). -3. Add `ssl_protocols TLSv1.3;` to your `server` block. +1. Reference the secret in your NGINX configuration as described in [Use an AWS Secrets Manager certificate in an NGINX configuration]({{< ref "/nginxaas/aws/deploy/ssl-tls-certificates/ssl-tls-certificates-secrets-manager.md#use-an-aws-secrets-manager-certificate-in-an-nginx-configuration" >}}). +1. Add `ssl_protocols TLSv1.3;` to your `server` block. --- diff --git a/content/nginxaas/google/quickstart/pqc.md b/content/nginxaas/google/quickstart/pqc.md index 0863e662e..af0ff49a3 100644 --- a/content/nginxaas/google/quickstart/pqc.md +++ b/content/nginxaas/google/quickstart/pqc.md @@ -39,8 +39,8 @@ Clients that support ML-KEM will negotiate it automatically on TLS 1.3 connectio Because hybrid ML-KEM key exchange applies only to TLS 1.3 connections, allowing TLS 1.2 means some clients can still negotiate a purely classical handshake. To prevent downgrade, restrict `ssl_protocols` to `TLSv1.3` only: 1. Select **Configurations** in the left menu. -2. Select the ellipsis (three dots) next to your configuration and select **Edit**. -3. Add `ssl_protocols TLSv1.3;` to your `server` block: +1. Select the ellipsis (three dots) next to your configuration and select **Edit**. +1. Add `ssl_protocols TLSv1.3;` to your `server` block: ```nginx server { @@ -52,7 +52,8 @@ Because hybrid ML-KEM key exchange applies only to TLS 1.3 connections, allowing } ``` -4. Select **Next** and then **Save** to apply the change. +1. Select **Next** and then **Save** to apply the change. +1. Deploy configuration to relevant deployments. {{< call-out class="note" title="Client compatibility" >}} Restricting to TLSv1.3 drops support for clients that only support TLS 1.2. If you need to support older clients, keep the default `ssl_protocols` value and accept that those connections won't use ML-KEM. @@ -93,7 +94,7 @@ Choose the method that matches your key format. Use this method if your ML-DSA private key is in seed-only format. 1. Follow the steps in [Add certificates using the Console]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-console.md" >}}) to upload your ML-DSA certificate and key. -2. In your NGINX configuration, reference the certificate and key with `ssl_certificate` and `ssl_certificate_key`, and set `ssl_protocols TLSv1.3;`: +1. In your NGINX configuration, reference the certificate and key with `ssl_certificate` and `ssl_certificate_key`, and set `ssl_protocols TLSv1.3;`: ```nginx server { @@ -105,15 +106,16 @@ Use this method if your ML-DSA private key is in seed-only format. } ``` -3. Select **Next** and then **Save** to apply the configuration. +1. Select **Next** and then **Save** to apply the change. +1. Deploy configuration to relevant deployments. ### Store an ML-DSA certificate in Google Secret Manager Use this method if your ML-DSA private key is in seed-priv format, or if you want to keep your keys within Google Cloud. 1. Add your ML-DSA certificate and key to Google Secret Manager. Follow the steps in [Add an SSL/TLS certificate to Secret Manager]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md#add-an-ssltls-certificate-to-secret-manager" >}}). -2. Reference the secret in your NGINX configuration as described in [Use a Secret Manager certificate in an NGINX configuration]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md#use-a-secret-manager-certificate-in-an-nginx-configuration" >}}). -3. Add `ssl_protocols TLSv1.3;` to your `server` block. +1. Reference the secret in your NGINX configuration as described in [Use a Secret Manager certificate in an NGINX configuration]({{< ref "/nginxaas/google/deploy/ssl-tls-certificates/ssl-tls-certificates-secret-manager.md#use-a-secret-manager-certificate-in-an-nginx-configuration" >}}). +1. Add `ssl_protocols TLSv1.3;` to your `server` block. --- From 0eff3b5a42b1392e78122de363219a5ee8e84f90 Mon Sep 17 00:00:00 2001 From: Andrei Belov Date: Tue, 22 Sep 2026 09:36:22 -0600 Subject: [PATCH 8/9] fix: address review comments --- .../deploy/ssl-tls-certificates/overview.md | 4 ++-- content/nginxaas/aws/quickstart/pqc.md | 22 ++++++++----------- .../deploy/ssl-tls-certificates/overview.md | 4 ++-- content/nginxaas/google/quickstart/pqc.md | 22 ++++++++----------- 4 files changed, 22 insertions(+), 30 deletions(-) diff --git a/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md b/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md index bc8b43db5..5f895f86f 100644 --- a/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md +++ b/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md @@ -30,8 +30,8 @@ Encrypt your certificates, keys, and PEM files using one of these algorithms: - ML-DSA (post-quantum) {{< call-out class="note" title="ML-DSA key format support" >}} -When you upload an ML-DSA private key using the NGINXaaS Console, only the seed-only key format is supported. -If you store your ML-DSA key in AWS Secrets Manager, both seed-only and seed-priv formats are supported. +When you upload an ML-DSA private key using the NGINXaaS Console, use the seed-only key format. +If you store your ML-DSA key in AWS Secrets Manager, you can use either the seed-only or seed-priv format. See [Enable post-quantum cryptography]({{< ref "/nginxaas/aws/quickstart/pqc.md" >}}) for configuration guidance. {{< /call-out >}} diff --git a/content/nginxaas/aws/quickstart/pqc.md b/content/nginxaas/aws/quickstart/pqc.md index 17eb23145..4fe8d0c5a 100644 --- a/content/nginxaas/aws/quickstart/pqc.md +++ b/content/nginxaas/aws/quickstart/pqc.md @@ -14,19 +14,17 @@ f5-summary: > f5-audience: operator --- -Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today - the "harvest now, decrypt later" threat. F5 NGINXaaS for AWS addresses this with two modes: +Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms like RSA and Elliptic Curve Cryptography (ECC) could decrypt traffic captured today. Security teams call this threat harvest now, decrypt later. F5 NGINXaaS for AWS addresses this with two modes: -- **Hybrid mode**: Combines classical elliptic-curve key exchange (EC) with ML-KEM for data encryption. This protects against quantum attacks while staying compatible with clients that don't yet support PQC. -- **Full PQC mode**: Uses ML-DSA certificates and keys that you provide. This gives you a fully post-quantum TLS stack when both client and server support it. +- **Hybrid mode**: Combines classical elliptic-curve key exchange with the Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) for data encryption. This protects against quantum attacks while staying compatible with clients that don't yet support PQC. +- **Full PQC mode**: Uses Module-Lattice-Based Digital Signature Algorithm (ML-DSA) certificates and keys that you provide. This gives you a fully post-quantum TLS stack when both client and server support it. ## Before you begin Before you begin, ensure you have: -- **An existing NGINXaaS for AWS deployment**: See [Create a deployment]({{< ref "/nginxaas/aws/deploy/create-deployment/deploy-console.md" >}}) if you need to create one. -- **TLS 1.3 in your NGINX configuration**: NGINX includes TLSv1.3 in its default `ssl_protocols` value alongside TLSv1.2. ML-KEM hybrid key exchange only applies to TLS 1.3 connections. To prevent clients from downgrading to TLS 1.2, restrict `ssl_protocols` to `TLSv1.3` only - this is recommended for maximum security but drops support for older clients. - ---- +- An existing NGINXaaS for AWS deployment: See [Create a deployment]({{< ref "/nginxaas/aws/deploy/create-deployment/deploy-console.md" >}}) if you need to create one. +- TLS 1.3 in your NGINX configuration: NGINX includes TLSv1.3 in its default `ssl_protocols` value alongside TLSv1.2. ML-KEM hybrid key exchange only applies to TLS 1.3 connections. To prevent clients from downgrading to TLS 1.2, restrict `ssl_protocols` to `TLSv1.3` only - this is recommended for maximum security but drops support for older clients. ## Enable hybrid mode (ML-KEM key exchange) @@ -36,7 +34,7 @@ Clients that support ML-KEM will negotiate it automatically on TLS 1.3 connectio ### Recommended: Restrict to TLS 1.3 only -Because hybrid ML-KEM key exchange applies only to TLS 1.3 connections, allowing TLS 1.2 means some clients can still negotiate a purely classical handshake. To prevent downgrade, restrict `ssl_protocols` to `TLSv1.3` only: +Because hybrid ML-KEM key exchange applies only to TLS 1.3 connections, allowing TLS 1.2 means some clients can still negotiate a purely classical handshake. To prevent a downgrade, restrict `ssl_protocols` to `TLSv1.3` only: 1. Select **Configurations** in the left menu. 1. Select the ellipsis (three dots) next to your configuration and select **Edit**. @@ -78,14 +76,12 @@ server { Including `X25519` after `X25519MLKEM768` lets clients that don't support ML-KEM fall back to classical key exchange. Remove `X25519` only if you want to restrict connections to ML-KEM-capable clients. {{< /call-out >}} ---- - ## Enable full PQC mode (ML-DSA certificates) Full PQC mode requires you to upload an ML-DSA certificate and private key. NGINXaaS for AWS accepts ML-DSA keys in PEM format with the following constraints: -- **NGINXaaS Console**: Seed-only key format only. -- **AWS Secrets Manager**: Seed-only and seed-priv formats are both supported. +- NGINXaaS Console: Seed-only key format only. +- AWS Secrets Manager: Seed-only and seed-priv formats are both supported. Choose the method that matches your key format. @@ -133,7 +129,7 @@ In the output, look for the `Negotiated TLS1.3 group` line. A successful hybrid Negotiated TLS1.3 group: X25519MLKEM768 ``` -If you see `X25519` or another classical group instead, check that `ssl_protocols TLSv1.3;` is set, and that no `ssl_ecdh_curve` directive is overriding the defaults with classical-only groups. +If you see `X25519` or another classical group instead, confirm that `ssl_protocols TLSv1.3;` is set, and that no `ssl_ecdh_curve` directive is overriding the defaults with classical-only groups. ### Track ML-KEM adoption across real clients diff --git a/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md b/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md index fb44ab916..d70ee6119 100644 --- a/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md +++ b/content/nginxaas/google/deploy/ssl-tls-certificates/overview.md @@ -31,8 +31,8 @@ Encrypt your certificates, keys, and PEM files using one of these standards: - ML-DSA (post-quantum) {{< call-out class="note" title="ML-DSA key format support" >}} -When you upload an ML-DSA private key using the NGINXaaS Console, only the seed-only key format is supported. -If you store your ML-DSA key in Google Secret Manager, both seed-only and seed-priv formats are supported. +When you upload an ML-DSA private key using the NGINXaaS Console, use the seed-only key format. +If you store your ML-DSA key in Google Secret Manager, you can use either the seed-only or seed-priv format. See [Enable post-quantum cryptography]({{< ref "/nginxaas/google/quickstart/pqc.md" >}}) for configuration guidance. {{< /call-out >}} diff --git a/content/nginxaas/google/quickstart/pqc.md b/content/nginxaas/google/quickstart/pqc.md index af0ff49a3..a44d71e48 100644 --- a/content/nginxaas/google/quickstart/pqc.md +++ b/content/nginxaas/google/quickstart/pqc.md @@ -14,19 +14,17 @@ f5-summary: > f5-audience: operator --- -Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms (RSA, ECC) could decrypt traffic captured today - the "harvest now, decrypt later" threat. F5 NGINXaaS for Google Cloud addresses this with two modes: +Post-quantum cryptography (PQC) protects TLS connections against future quantum computers. A quantum computer powerful enough to break current public-key algorithms like RSA and Elliptic Curve Cryptography (ECC) could decrypt traffic captured today. Security teams call this threat harvest now, decrypt later. F5 NGINXaaS for Google Cloud addresses this with two modes: -- **Hybrid mode**: Combines classical elliptic-curve key exchange (EC) with ML-KEM for data encryption. This protects against quantum attacks while staying compatible with clients that don't yet support PQC. -- **Full PQC mode**: Uses ML-DSA certificates and keys that you provide. This gives you a fully post-quantum TLS stack when both client and server support it. +- **Hybrid mode**: Combines classical elliptic-curve key exchange with the Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) for data encryption. This protects against quantum attacks while staying compatible with clients that don't yet support PQC. +- **Full PQC mode**: Uses Module-Lattice-Based Digital Signature Algorithm (ML-DSA) certificates and keys that you provide. This gives you a fully post-quantum TLS stack when both client and server support it. ## Before you begin Before you begin, ensure you have: -- **An existing NGINXaaS for Google Cloud deployment**: See [Create a deployment]({{< ref "/nginxaas/google/deploy/create-deployment/deploy-console.md" >}}) if you need to create one. -- **TLS 1.3 in your NGINX configuration**: NGINX includes TLSv1.3 in its default `ssl_protocols` value alongside TLSv1.2. ML-KEM hybrid key exchange only applies to TLS 1.3 connections. To prevent clients from downgrading to TLS 1.2, restrict `ssl_protocols` to `TLSv1.3` only - this is recommended for maximum security but drops support for older clients. - ---- +- An existing NGINXaaS for Google Cloud deployment: See [Create a deployment]({{< ref "/nginxaas/google/deploy/create-deployment/deploy-console.md" >}}) if you need to create one. +- TLS 1.3 in your NGINX configuration: NGINX includes TLSv1.3 in its default `ssl_protocols` value alongside TLSv1.2. ML-KEM hybrid key exchange only applies to TLS 1.3 connections. To prevent clients from downgrading to TLS 1.2, restrict `ssl_protocols` to `TLSv1.3` only - this is recommended for maximum security but drops support for older clients. ## Enable hybrid mode (ML-KEM key exchange) @@ -36,7 +34,7 @@ Clients that support ML-KEM will negotiate it automatically on TLS 1.3 connectio ### Recommended: Restrict to TLS 1.3 only -Because hybrid ML-KEM key exchange applies only to TLS 1.3 connections, allowing TLS 1.2 means some clients can still negotiate a purely classical handshake. To prevent downgrade, restrict `ssl_protocols` to `TLSv1.3` only: +Because hybrid ML-KEM key exchange applies only to TLS 1.3 connections, allowing TLS 1.2 means some clients can still negotiate a purely classical handshake. To prevent a downgrade, restrict `ssl_protocols` to `TLSv1.3` only: 1. Select **Configurations** in the left menu. 1. Select the ellipsis (three dots) next to your configuration and select **Edit**. @@ -78,14 +76,12 @@ server { Including `X25519` after `X25519MLKEM768` lets clients that don't support ML-KEM fall back to classical key exchange. Remove `X25519` only if you want to restrict connections to ML-KEM-capable clients. {{< /call-out >}} ---- - ## Enable full PQC mode (ML-DSA certificates) Full PQC mode requires you to upload an ML-DSA certificate and private key. NGINXaaS for Google Cloud accepts ML-DSA keys in PEM format with the following constraints: -- **NGINXaaS Console**: Seed-only key format only. -- **Google Secret Manager**: Seed-only and seed-priv formats are both supported. +- NGINXaaS Console: Seed-only key format only. +- Google Secret Manager: Seed-only and seed-priv formats are both supported. Choose the method that matches your key format. @@ -133,7 +129,7 @@ In the output, look for the `Negotiated TLS1.3 group` line. A successful hybrid Negotiated TLS1.3 group: X25519MLKEM768 ``` -If you see `X25519` or another classical group instead, check that `ssl_protocols TLSv1.3;` is set, and that no `ssl_ecdh_curve` directive is overriding the defaults with classical-only groups. +If you see `X25519` or another classical group instead, confirm that `ssl_protocols TLSv1.3;` is set, and that no `ssl_ecdh_curve` directive is overriding the defaults with classical-only groups. ### Track ML-KEM adoption across real clients From b533a2b04746119828d190b874cecc887bba34c9 Mon Sep 17 00:00:00 2001 From: Andrei Belov Date: Tue, 22 Sep 2026 15:54:19 -0600 Subject: [PATCH 9/9] fix: rephrase to avoid using the word "field" --- content/nginxaas/aws/quickstart/pqc.md | 2 +- content/nginxaas/google/quickstart/pqc.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/nginxaas/aws/quickstart/pqc.md b/content/nginxaas/aws/quickstart/pqc.md index 4fe8d0c5a..938a60713 100644 --- a/content/nginxaas/aws/quickstart/pqc.md +++ b/content/nginxaas/aws/quickstart/pqc.md @@ -145,7 +145,7 @@ http { } ``` -In the logs, connections that negotiated ML-KEM hybrid key exchange appear with `X25519MLKEM768` in the `$ssl_curve` field. Classical TLS 1.3 connections appear with `X25519` or another classical group name, and TLS 1.2 connections return an empty value. +In the logs, connections that negotiated ML-KEM hybrid key exchange appear with `X25519MLKEM768` in a value of the `$ssl_curve` variable. Classical TLS 1.3 connections appear with `X25519` or another classical group name, and TLS 1.2 connections return an empty value. {{< call-out class="note" title="Collecting logs" >}} To forward logs to AWS CloudWatch, see [Enable NGINX logs]({{< ref "/nginxaas/aws/monitoring/enable-nginx-logs.md" >}}). diff --git a/content/nginxaas/google/quickstart/pqc.md b/content/nginxaas/google/quickstart/pqc.md index a44d71e48..8b8f71e5b 100644 --- a/content/nginxaas/google/quickstart/pqc.md +++ b/content/nginxaas/google/quickstart/pqc.md @@ -145,7 +145,7 @@ http { } ``` -In the logs, connections that negotiated ML-KEM hybrid key exchange appear with `X25519MLKEM768` in the `$ssl_curve` field. Classical TLS 1.3 connections appear with `X25519` or another classical group name, and TLS 1.2 connections return an empty value. +In the logs, connections that negotiated ML-KEM hybrid key exchange appear with `X25519MLKEM768` in a value of the `$ssl_curve` variable. Classical TLS 1.3 connections appear with `X25519` or another classical group name, and TLS 1.2 connections return an empty value. {{< call-out class="note" title="Collecting logs" >}} To forward logs to Cloud Logging, see [Enable NGINX logs]({{< ref "/nginxaas/google/monitoring/enable-nginx-logs.md" >}}).