5-https.md

> Back to homepage

Advanced HTTPS API

https

Type: object

This option represents the options used to make HTTPS requests.

alpnProtocols

Type: string[]
Default: ['http/1.1']

Acceptable ALPN protocols.

If the http2 option is true, this defaults to ['h2', 'http/1.1'].

rejectUnauthorized

Type: boolean
Default: true

If true, it will throw on invalid certificates, such as expired or self-signed ones.

checkServerIdentity

Type: (hostname: string, certificate: DetailedPeerCertificate) => Error | undefined
Default: tls.checkServerIdentity

Custom check of the certificate. Useful for pinning certificates.

The function must return undefined if the check succeeded.
If it failed, an Error should be returned.

Note:

• In order to have the function called, the certificate must not be expired, self-signed nor with an untrusted-root.

Check Node.js docs for an example.

serverName

Type: string
Default: undefined

Server name for the Server Name Indication (SNI) TLS extension.

This is useful when requesting to servers that don't have a proper domain name but use a certificate with a known CN/SAN.

import got from 'got';

// Request to IP address with specific servername for TLS
await got('https://192.168.1.100', {
	https: {
		serverName: 'example.com'
	}
});

certificateAuthority

Type: string | Uint8Array | string[] | Uint8Array[]

Note:

• The option has been renamed from the ca TLS option for better readability.

Overrides trusted CA certificates.

Defaults to CAs provided by Mozilla.

import got from 'got';

// Single Certificate Authority
await got('https://example.com', {
	https: {
		certificateAuthority: fs.readFileSync('./my_ca.pem')
	}
});

key

Type: string | Uint8Array | string[] | Uint8Array[] | object[]

Private keys in PEM format.

Multiple keys with different passphrases can be provided as an array of {pem: <string | Uint8Array>, passphrase: <string>}.

Note:

• Encrypted keys will be decrypted with https.passphrase.

passphrase

Type: string

Shared passphrase used for a single private key and/or a PFX.

certificate

Type: string | Uint8Array | string[] | Uint8Array[]

Note:

• The option has been renamed from the cert TLS option for better readability.

Certificate chains in PEM format.

One certificate chain should be provided per private key.

When providing multiple certificate chains, they do not have to be in the same order as their private keys in https.key.

pfx

Type: string | Uint8Array | string[] | Uint8Array[] | object[]

PFX or PKCS12 encoded private key and certificate chain. Using https.pfx is an alternative to providing https.key and https.certificate individually. A PFX is usually encrypted, then https.passphrase will be used to decrypt it.

Multiple PFX can be provided as an array of unencrypted buffers or an array of objects like:

{
	buffer: string | Uint8Array,
	passphrase?: string
}

certificateRevocationLists

Type: string | Uint8Array | string[] | Uint8Array[]

Note:

• The option has been renamed from the crl TLS option for better readability.

secureOptions

Type: number

Optionally affect the OpenSSL protocol behavior, which is not usually necessary. This should be used carefully if at all!

The value is a numeric bitmask of the SSL_OP_* options from OpenSSL.

For example, to allow connections to legacy servers that do not support secure renegotiation, you can use crypto.constants.SSL_OP_LEGACY_SERVER_CONNECT.

import crypto from 'node:crypto';
import got from 'got';

// Allow connections to servers with legacy renegotiation
await got('https://legacy-server.com', {
	https: {
		secureOptions: crypto.constants.SSL_OP_LEGACY_SERVER_CONNECT
	}
});

Other HTTPS options

Documentation for the below options.

• ciphers
• dhparam
• signatureAlgorithms (renamed from sigalgs)
• minVersion
• maxVersion
• honorCipherOrder
• tlsSessionLifetime (renamed from sessionTimeout)
• ecdhCurve

Examples

import got from 'got';

// Single key with certificate
await got('https://example.com', {
	https: {
		key: fs.readFileSync('./client_key.pem'),
		certificate: fs.readFileSync('./client_cert.pem')
	}
});

// Multiple keys with certificates (out of order)
await got('https://example.com', {
	https: {
		key: [
			fs.readFileSync('./client_key1.pem'),
			fs.readFileSync('./client_key2.pem')
		],
		certificate: [
			fs.readFileSync('./client_cert2.pem'),
			fs.readFileSync('./client_cert1.pem')
		]
	}
});

// Single key with passphrase
await got('https://example.com', {
	https: {
		key: fs.readFileSync('./client_key.pem'),
		certificate: fs.readFileSync('./client_cert.pem'),
		passphrase: 'client_key_passphrase'
	}
});

// Multiple keys with different passphrases
await got('https://example.com', {
	https: {
		key: [
			{pem: fs.readFileSync('./client_key1.pem'), passphrase: 'passphrase1'},
			{pem: fs.readFileSync('./client_key2.pem'), passphrase: 'passphrase2'},
		],
		certificate: [
			fs.readFileSync('./client_cert1.pem'),
			fs.readFileSync('./client_cert2.pem')
		]
	}
});

// Single encrypted PFX with passphrase
await got('https://example.com', {
	https: {
		pfx: fs.readFileSync('./fake.pfx'),
		passphrase: 'passphrase'
	}
});

// Multiple encrypted PFX's with different passphrases
await got('https://example.com', {
	https: {
		pfx: [
			{
				buffer: fs.readFileSync('./key1.pfx'),
				passphrase: 'passphrase1'
			},
			{
				buffer: fs.readFileSync('./key2.pfx'),
				passphrase: 'passphrase2'
			}
		]
	}
});

// Multiple encrypted PFX's with single passphrase
await got('https://example.com', {
	https: {
		passphrase: 'passphrase',
		pfx: [
			{
				buffer: fs.readFileSync('./key1.pfx')
			},
			{
				buffer: fs.readFileSync('./key2.pfx')
			}
		]
	}
});