Documentation update for issue #67

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.

content/includes/agent/installation/install-agent-api.md

@@ -6,6 +6,14 @@ files:
 
 {{<note>}}Make sure `gpg` is installed on your system before continuing. You can install NGINX Agent using command-line tools like `curl` or `wget`.{{</note>}}
 
+Before installing, you can validate the NGINX Instance Manager endpoint and its revocation status:
+
+```bash
+openssl s_client -connect <NIM_FQDN>:443 -servername <NIM_FQDN> -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:
 
 {{<tabs name="install-agent-api">}}
@@ -24,6 +32,8 @@ If your NGINX Instance Manager host doesn't use valid TLS certificates, you can
   curl --insecure https://<NIM_FQDN>/install/nginx-agent | sudo sh
   ```
 
+{{<note>}}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.{{</note>}}
+
 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://<NIM_FQDN>/install/nginx-agent -O - | sudo sh
   ```
 
+{{<note>}}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.{{</note>}}
+
 To add your instance to a group during installation, use the `--instance-group` (or `-g`) flag:
 
 ```shell

content/includes/licensing-and-reporting/configure-nginx-plus-report-to-nim.md

@@ -14,6 +14,8 @@ docs:
 
     {{<call-out "note" "Extra steps for self-signed certificates">}}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" >}}).{{</call-out>}}
 
+    {{<call-out "note" "Revocation and the usage report connection">}}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.{{</call-out>}}
+
 3. Reload NGINX:
 
     ``` bash