diff --git a/doc/api/tls.md b/doc/api/tls.md index 8da9d66c350030..86644cea76b6a3 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -1985,9 +1985,13 @@ changes: * `allowPartialTrustChain` {boolean} Treat intermediate (non-self-signed) certificates in the trust CA certificate list as trusted. * `ca` {string|string\[]|Buffer|Buffer\[]} Optionally override the trusted CA - certificates. Default is to trust the well-known CAs curated by Mozilla. - Mozilla's CAs are completely replaced when CAs are explicitly specified - using this option. The value can be a string or `Buffer`, or an `Array` of + certificates. If not specified, the CA certificates trusted by default are + the same as the ones returned by [`tls.getCACertificates()`][] using the + `default` type. If specified, the default list would be completely replaced + (instead of being concatenated) by the certificates in the `ca` option. + Users need to concatenate manually if they wish to add additional certificates + instead of completely overriding the default. + The value can be a string or `Buffer`, or an `Array` of strings and/or `Buffer`s. Any string or `Buffer` can contain multiple PEM CAs concatenated together. The peer's certificate must be chainable to a CA trusted by the server for the connection to be authenticated. When using @@ -2001,7 +2005,6 @@ changes: provided. For PEM encoded certificates, supported types are "TRUSTED CERTIFICATE", "X509 CERTIFICATE", and "CERTIFICATE". - See also [`tls.rootCertificates`][]. * `cert` {string|string\[]|Buffer|Buffer\[]} Cert chains in PEM format. One cert chain should be provided per private key. Each cert chain should consist of the PEM formatted certificate for a provided private `key`, @@ -2364,6 +2367,39 @@ openssl pkcs12 -certpbe AES-256-CBC -export -out client-cert.pem \ The server can be tested by connecting to it using the example client from [`tls.connect()`][]. +## `tls.getCACertificates([type])` + + + +* `type` {string|undefined} The type of CA certificates that will be returned. Valid values + are `"default"`, `"system"`, `"bundled"` and `"extra"`. + **Default:** `"default"`. +* Returns: {string\[]} An array of PEM-encoded certificates. The array may contain duplicates + if the same certificate is repeatedly stored in multiple sources. + +Returns an array containing the CA certificates from various sources, depending on `type`: + +* `"default"`: return the CA certificates that will be used by the Node.js TLS clients by default. + * When [`--use-bundled-ca`][] is enabled (default), or [`--use-openssl-ca`][] is not enabled, + this would include CA certificates from the bundled Mozilla CA store. + * When [`--use-system-ca`][] is enabled, this would also include certificates from the system's + trusted store. + * When [`NODE_EXTRA_CA_CERTS`][] is used, this would also include certificates loaded from the specified + file. +* `"system"`: return the CA certificates that are loaded from the system's trusted store, according + to rules set by [`--use-system-ca`][]. This can be used to get the certificates from the system + when [`--use-system-ca`][] is not enabled. +* `"bundled"`: return the CA certificates from the bundled Mozilla CA store. This would be the same + as [`tls.rootCertificates`][]. +* `"extra"`: return the CA certificates loaded from [`NODE_EXTRA_CA_CERTS`][]. It's an empty array if + [`NODE_EXTRA_CA_CERTS`][] is not set. + + + ## `tls.getCiphers()`