diff --git a/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md b/content/nginxaas/aws/deploy/ssl-tls-certificates/overview.md index f4a752e05..5f895f86f 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) + +{{< call-out class="note" title="ML-DSA key format support" >}} +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 >}} ## 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..938a60713 --- /dev/null +++ b/content/nginxaas/aws/quickstart/pqc.md @@ -0,0 +1,160 @@ +--- +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 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 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. + +## 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 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**. +1. 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; + # ... + } + ``` + +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. +{{< /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. +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 { + listen 443 ssl; + ssl_protocols TLSv1.3; + ssl_certificate /etc/nginx/certs/mldsa.crt; + ssl_certificate_key /etc/nginx/certs/mldsa.key; + # ... + } + ``` + +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" >}}). +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. + +--- + +## 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, 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 + +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 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" >}}). +{{< /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..d70ee6119 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) + +{{< call-out class="note" title="ML-DSA key format support" >}} +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 >}} ## 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..8b8f71e5b --- /dev/null +++ b/content/nginxaas/google/quickstart/pqc.md @@ -0,0 +1,160 @@ +--- +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 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 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. + +## 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 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**. +1. 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; + # ... + } + ``` + +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. +{{< /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. +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 { + listen 443 ssl; + ssl_protocols TLSv1.3; + ssl_certificate /etc/nginx/certs/mldsa.crt; + ssl_certificate_key /etc/nginx/certs/mldsa.key; + # ... + } + ``` + +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" >}}). +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. + +--- + +## 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, 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 + +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 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" >}}). +{{< /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.