Inaccurate https.request options docs
- Version: 7.0.0
- Platform: All
- Subsystem: Docs
I needed to explore specifying the SNI hostname independently of the hostname and the Host
header, but the docs list the servername
among these bullets (my emphasis):
The following options from
tls.connect()
can also be specified. However, aglobalAgent
silently ignores these.
pfx
: Certificate, Private key and CA certificates to use for SSL. Defaultnull
.key
: Private key to use for SSL. Defaultnull
.passphrase
: A string of passphrase for the private key or pfx. Defaultnull
.cert
: Public x509 certificate to use. Defaultnull
.ca
: A string, [Buffer
][] or array of strings or [Buffer
][]s of trusted certificates in PEM format. If this is omitted several well known "root" CAs will be used, like VeriSign. These are used to authorize connections.ciphers
: A string describing the ciphers to use or exclude. Consult https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT for details on the format.rejectUnauthorized
: Iftrue
, the server certificate is verified against the list of supplied CAs. An'error'
event is emitted if verification fails. Verification happens at the connection level, before the HTTP request is sent. Defaulttrue
.secureProtocol
: The SSL method to use, e.g.SSLv3_method
to force SSL version 3. The possible values depend on your installation of OpenSSL and are defined in the constant [SSL_METHODS
][].servername
: Servername for SNI (Server Name Indication) TLS extension.In order to specify these options, use a custom [
Agent
][].
That doesn't seem to be correct, though. If I do an HTTPS request without providing an Agent
instance (thus utilizing the global agent), it does use the servername
as the SNI hostname:
require('https').request({
hostname: 'www.github.com',
servername: 'sniname.com'
}).end();
// Error: Hostname/IP doesn't match certificate's altnames: "Host: sniname.com. is not in the cert's altnames: DNS:github.com, DNS:www.github.com"
The rejectUnauthorized
option also works fine without an agent.
It seems like the docs should be fixed to match reality? I'd whip up a PR, but I'm not sure exactly which of the remaining options also work without an agent, and I'm not familiar enough with TLS etc. to find out.
Looks like the inaccuracy was introduced in 8ba56316, while rejectUnauthorized
was added to the list way back in f8c335d0 (0.6.6).