diff --git a/content/agent/configuration/encrypt-communication.md b/content/agent/configuration/encrypt-communication.md index a7cf75134..88a511c09 100644 --- a/content/agent/configuration/encrypt-communication.md +++ b/content/agent/configuration/encrypt-communication.md @@ -58,6 +58,96 @@ NGINX_AGENT_TLS_ENABLE=true --- +## Certificate revocation checking (CRL/OCSP) + +### Overview +Certificate revocation ensures that certificates that are compromised, mis-issued, or otherwise invalid are rejected. For NGINX Instance Manager (NIM) and NGINX Agent mTLS, you should: +- Enforce revocation of Agent client certificates on the NIM side using Certificate Revocation Lists (CRLs). +- Enable OCSP stapling on the NIM TLS endpoint so clients receive the server certificate's status with the TLS handshake. + +Current limitations: +- NGINX does not verify client certificates via OCSP. Use CRLs to enforce revocation for client (Agent) certificates. +- NGINX Agent does not perform OCSP/CRL checks of the server certificate. Rely on strict verification (tls.skip_verify: false), CA pinning, short‑lived certificates with automated rotation, and server-side OCSP stapling for better hygiene and monitoring. + +### Prerequisites +- Accurate system time (NTP) on all nodes participating in TLS. +- Access to CRL files from your issuing CA for Agent client certificates. +- If enabling OCSP stapling on the NIM endpoint: allow egress from NIM to CA OCSP responders, have the full certificate chain available, and configure a DNS resolver. +- Avoid skip_verify: true in production; it bypasses chain, name, and revocation checks. + +### NIM validates Agent client certificates (mTLS) using CRLs +Place NIM behind NGINX to terminate TLS and validate Agent client certificates. Configure NGINX to require client certs and enforce revocation via CRLs: + +```nginx +server { + listen 443 ssl; + server_name nim.example.com; + + # Server cert/key for NIM endpoint + ssl_certificate /etc/nginx/nim/server.crt; + ssl_certificate_key /etc/nginx/nim/server.key; + + # Verify Agent (client) certificates + ssl_client_certificate /etc/nginx/nim/ca/agent-issuing-ca.pem; + ssl_verify_client on; # require client certs + ssl_verify_depth 2; + + # Enforce revocation of client certs via CRL + ssl_crl /etc/nginx/nim/ca/agent-issuing-ca.crl.pem; # PEM-encoded CRL + + # Harden server-side presentation to clients (see next section) + ssl_stapling on; + ssl_stapling_verify on; + ssl_trusted_certificate /etc/nginx/nim/ca/fullchain.pem; # for OCSP responder trust + resolver 1.1.1.1 8.8.8.8 valid=300s; + resolver_timeout 5s; + + location / { + proxy_pass http://nim-backend:8035; # adjust to your NIM service + } +} +``` + +Notes: +- Convert DER CRLs to PEM if needed: openssl crl -in ca.crl -inform DER -out ca.crl.pem -outform PEM +- Update CRLs regularly according to your CA's publishing schedule and reload NGINX. Stale CRLs may allow revoked certs. +- Keep CRLs small/manageable by issuing Agent certs from an intermediate CA dedicated to Agents. +- NGINX does not perform OCSP checks for client certificates; use ssl_crl for mTLS client revocation enforcement. Ensure the CRL corresponds to the issuing CA for Agent certificates. + +### Agent validates the NIM server certificate (client-side) +- Keep tls.skip_verify set to false (default) so hostname and chain validation are enforced. +- Pin your issuing CA by setting tls.ca to a minimal bundle that includes only the CA(s) that issue the NIM server certificate. Avoid broad system bundles. +- Prefer short-lived server certificates and automate rotation; promptly revoke compromised certs. +- Enable OCSP stapling on the NIM TLS endpoint (as above). The Agent does not itself validate OCSP/CRL, but stapling improves overall security posture and observability. + +Agent configuration recap: + +```bash +tls: + enable: true + cert: "/path/to/agent-cert.pem" # if mTLS + key: "/path/to/agent-key.pem" # if mTLS + ca: "/etc/pki/org-ca/issuing-ca.pem" # pin your issuing CA + skip_verify: false +``` + +### Cautions +- Setting skip_verify: true disables hostname and chain checks and can lead to trusting revoked/forged server certificates. +- Stale or missing CRLs mean revoked Agent client certificates may still be accepted. Automate CRL refresh and nginx reload. +- Treat OCSP stapling failures as an operational alert; monitor error logs for ocsp errors and investigate promptly. + +### Verification +- Verify OCSP stapling from the NIM endpoint: + openssl s_client -connect nim.example.com:443 -status -servername nim.example.com | grep -A3 "OCSP response" +- Verify a revoked Agent client certificate is rejected (expect TLS handshake failure and a 400/495 status at the edge): attempt client auth with a revoked cert and confirm access is denied. + +See also: +- Enabling mTLS (above) for how to enable TLS/mTLS on the Agent. +- Secure Traffic with Certificates for key/cert generation and configuration guidance: https://docs.nginx.com/nginx-instance-manager/system-configuration/secure-traffic/ +- Insecure Mode (Not Recommended) (below) for the risks of disabling TLS verification. + +--- + ## Enabling Server-Side TLS To enable server-side TLS you must have TLS enabled. See the following examples for how to set these values using a configuration file, CLI flags, or environment variables. diff --git a/content/includes/agent/installation/install-agent-api.md b/content/includes/agent/installation/install-agent-api.md index 15009d21f..f79cd75d9 100644 --- a/content/includes/agent/installation/install-agent-api.md +++ b/content/includes/agent/installation/install-agent-api.md @@ -6,6 +6,14 @@ files: {{}}Make sure `gpg` is installed on your system before continuing. You can install NGINX Agent using command-line tools like `curl` or `wget`.{{}} +Before installing, you can validate the NGINX Instance Manager endpoint and its revocation status: + +```bash +openssl s_client -connect :443 -servername -status | grep -E "Verify return code|OCSP response" +``` + +Note: OCSP status output appears only if the server staples OCSP. Absence of a stapled status is not itself an error, but you should address stapling and revocation checking as described in [Certificate revocation checking (CRL/OCSP)](https://docs.nginx.com/nginx-instance-manager/system-configuration/secure-traffic/#certificate-revocation-checking-crl-ocsp). + If your NGINX Instance Manager host doesn't use valid TLS certificates, you can use the insecure flags to bypass verification. Here are some example commands: {{}} @@ -24,6 +32,8 @@ If your NGINX Instance Manager host doesn't use valid TLS certificates, you can curl --insecure https:///install/nginx-agent | sudo sh ``` +{{}}Caution: The --insecure flag disables certificate validation and certificate revocation checks (CRL/OCSP). Do not use this in production. Instead, use trusted CA bundles and, where possible, pin the issuing CA certificate rather than relying on broad system CA stores.{{}} + To add the instance to a specific instance group during installation, use the `--instance-group` (or `-g`) flag: ```shell @@ -46,6 +56,8 @@ chmod u+x install.sh sudo ./install.sh --skip-verify false ``` +This enforces hostname and full certificate chain validation. For guidance on enforcing certificate revocation checking (CRL/OCSP) to avoid accepting revoked certificates—and on using trusted CA bundles or pinning the issuing CA—see [Certificate revocation checking (CRL/OCSP)](https://docs.nginx.com/nginx-instance-manager/system-configuration/secure-traffic/#certificate-revocation-checking-crl-ocsp). + {{%/tab%}} {{%tab name="wget"%}} @@ -62,6 +74,8 @@ sudo ./install.sh --skip-verify false wget --no-check-certificate https:///install/nginx-agent -O - | sudo sh ``` +{{}}Caution: The --no-check-certificate flag disables certificate validation and certificate revocation checks (CRL/OCSP). Do not use this in production. Instead, use trusted CA bundles and, where possible, pin the issuing CA certificate rather than relying on broad system CA stores.{{}} + To add your instance to a group during installation, use the `--instance-group` (or `-g`) flag: ```shell diff --git a/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md b/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md index 68da7ec26..2fc7b4d85 100644 --- a/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md +++ b/content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md @@ -14,6 +14,8 @@ docs: {{}}If you use self-signed certificates in your NGINX Instance Manager environment, follow the steps in [Configure SSL verification for usage reporting with self-signed certificates]({{< ref "nim/system-configuration/secure-traffic.md#configure-ssl-verify" >}}).{{}} + {{}}The `usage_report` connection is an outbound HTTPS client from NGINX to NGINX Instance Manager. Ensure the NIM endpoint presents a valid, non-revoked server certificate issued by a trusted CA. For production, avoid self-signed certificates; if you must use a private CA or self-signed certificate, import the issuing CA into the NGINX host's trust store and use short-lived server certificates with automated rotation. If your security policy requires active revocation checks, front NGINX Instance Manager with an NGINX server that staples OCSP (`ssl_stapling on;` `ssl_stapling_verify on;`) so monitoring can detect issues quickly. CRL/OCSP configuration for the `usage_report` HTTPS client is not exposed here; see [Certificate revocation checking (CRL/OCSP)]({{< ref "nim/system-configuration/secure-traffic.md#certificate-revocation-checking-crl-ocsp" >}}) for server-side hardening and operational guidance.{{}} + 3. Reload NGINX: ``` bash