doc: clarify --use-system-ca support status

joyeecheung · aduh95 · commit ca395407856a · 2025-11-05T23:05:50.000+01:00
Node.js only checks trust settings of additional certificates from the system store. It does not, however, support revocation/distrust of existing certificates. PR-URL: #60340 Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -3142,21 +3142,18 @@ On platforms other than Windows and macOS, this loads certificates from the dire
 and file trusted by OpenSSL, similar to `--use-openssl-ca`, with the difference being
 that it caches the certificates after first load.
 
-On Windows and macOS, the certificate trust policy is planned to follow
-[Chromium's policy for locally trusted certificates][]:
+On Windows and macOS, the certificate trust policy is similar to
+[Chromium's policy for locally trusted certificates][], but with some differences:
 
 On macOS, the following settings are respected:
 
 * Default and System Keychains
   * Trust:
     * Any certificate where the &ldquo;When using this certificate&rdquo; flag is set to &ldquo;Always Trust&rdquo; or
-    * Any certificate where the &ldquo;Secure Sockets Layer (SSL)&rdquo; flag is set to &ldquo;Always Trust.&rdquo;
-  * Distrust:
-    * Any certificate where the &ldquo;When using this certificate&rdquo; flag is set to &ldquo;Never Trust&rdquo; or
-    * Any certificate where the &ldquo;Secure Sockets Layer (SSL)&rdquo; flag is set to &ldquo;Never Trust.&rdquo;
+    * Any certificate where the &ldquo;Secure Sockets Layer (SSL)&rdquo; flag is set to &ldquo;Always Trust&rdquo;.
+  * The certificate must also be valid, with "X.509 Basic Policy" set to  &ldquo;Always Trust&rdquo;.
 
-On Windows, the following settings are respected (unlike Chromium's policy, distrust
-and intermediate CA are not currently supported):
+On Windows, the following settings are respected:
 
 * Local Machine (accessed via `certlm.msc`)
   * Trust:
@@ -3171,8 +3168,11 @@ and intermediate CA are not currently supported):
     * Trusted Root Certification Authorities
     * Enterprise Trust -> Group Policy -> Trusted Root Certification Authorities
 
-On Windows and macOS, Node.js would check that the user settings for the certificates
-do not forbid them for TLS server authentication before using them.
+On Windows and macOS, Node.js would check that the user settings for the trusted
+certificates do not forbid them for TLS server authentication before using them.
+
+Node.js currently does not support distrust/revocation of certificates
+from another source based on system settings.
 
 On other systems, Node.js loads certificates from the default certificate file
 (typically `/etc/ssl/cert.pem`) and default certificate directory (typically
