Node

https

https

HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a separate module.

Usage in Deno

import * as mod from "node:https";

Classes

Agent

An Agent object for HTTPS similar to http.Agent. See request for more information.

options

Functions

createServer

get

Like http.get() but for HTTPS.

request

Makes a request to a secure web server.

Interfaces

AgentOptions

No documentation available

maxCachedSessions

Server

No documentation available

Type Aliases

RequestOptions

No documentation available

ServerOptions

No documentation available

Variables

globalAgent

No documentation available

class Agent

extends http.Agent

Usage in Deno

import { Agent } from "node:https";

An Agent object for HTTPS similar to http.Agent. See request for more information.

Constructors #

#Agent(options?: AgentOptions)

new

Properties #

#options: AgentOptions

function createServer

Usage in Deno

import { createServer } from "node:https";

Overload 1

#createServer<Request extends http.IncomingMessage = http.IncomingMessage,
Response extends http.ServerResponse = http.ServerResponse,
>(requestListener?: http.RequestListener<Request, Response>): Server<Request, Response>

// curl -k https://localhost:8000/
import https from 'node:https';
import fs from 'node:fs';

const options = {
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);

import https from 'node:https';
import fs from 'node:fs';

const options = {
  pfx: fs.readFileSync('test/fixtures/test_cert.pfx'),
  passphrase: 'sample',
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);

Type Parameters #

#Request extends http.IncomingMessage = http.IncomingMessage

#Response extends http.ServerResponse = http.ServerResponse

Parameters #

#requestListener: http.RequestListener<Request, Response>

optional

A listener to be added to the 'request' event.

Return Type #

Server<Request, Response>

Overload 2

#createServer<Request extends http.IncomingMessage = http.IncomingMessage,
Response extends http.ServerResponse = http.ServerResponse,
>(options: ServerOptions<Request, Response>,
requestListener?: http.RequestListener<Request, Response>,
): Server<Request, Response>

Type Parameters #

#Request extends http.IncomingMessage = http.IncomingMessage

#Response extends http.ServerResponse = http.ServerResponse

Parameters #

#options: ServerOptions<Request, Response>

#requestListener: http.RequestListener<Request, Response>

optional

Return Type #

Server<Request, Response>

function get

Usage in Deno

import { get } from "node:https";

Overload 1

#get(options: RequestOptions
 | string
 | URL,
callback?: (res: http.IncomingMessage) => void,
): http.ClientRequest

Like http.get() but for HTTPS.

options can be an object, a string, or a URL object. If options is a string, it is automatically parsed with new URL(). If it is a URL object, it will be automatically converted to an ordinary options object.

import https from 'node:https';

https.get('https://encrypted.google.com/', (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });

}).on('error', (e) => {
  console.error(e);
});

Parameters #

#options: RequestOptions
 | string
 | URL

Accepts the same options as request, with the method always set to GET.

#callback: (res: http.IncomingMessage) => void

optional

Return Type #

http.ClientRequest

Overload 2

#get(url: string | URL,
options: RequestOptions,
callback?: (res: http.IncomingMessage) => void,
): http.ClientRequest

Parameters #

#url: string | URL

#options: RequestOptions

#callback: (res: http.IncomingMessage) => void

optional

Return Type #

http.ClientRequest

function request

Usage in Deno

import { request } from "node:https";

Overload 1

#request(options: RequestOptions
 | string
 | URL,
callback?: (res: http.IncomingMessage) => void,
): http.ClientRequest

Makes a request to a secure web server.

The following additional options from tls.connect() are also accepted: ca, cert, ciphers, clientCertEngine, crl, dhparam, ecdhCurve, honorCipherOrder, key, passphrase, pfx, rejectUnauthorized, secureOptions, secureProtocol, servername, sessionIdContext, highWaterMark.

https.request() returns an instance of the http.ClientRequest class. The ClientRequest instance is a writable stream. If one needs to upload a file with a POST request, then write to the ClientRequest object.

import https from 'node:https';

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
};

const req = https.request(options, (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

req.on('error', (e) => {
  console.error(e);
});
req.end();

Example using options from tls.connect():

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
};
options.agent = new https.Agent(options);

const req = https.request(options, (res) => {
  // ...
});

Alternatively, opt out of connection pooling by not using an Agent.

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
  agent: false,
};

const req = https.request(options, (res) => {
  // ...
});

Example using a URL as options:

const options = new URL('https://abc:xyz@example.com');

const req = https.request(options, (res) => {
  // ...
});

Example pinning on certificate fingerprint, or the public key (similar topin-sha256):

import tls from 'node:tls';
import https from 'node:https';
import crypto from 'node:crypto';

function sha256(s) {
  return crypto.createHash('sha256').update(s).digest('base64');
}
const options = {
  hostname: 'github.com',
  port: 443,
  path: '/',
  method: 'GET',
  checkServerIdentity: function(host, cert) {
    // Make sure the certificate is issued to the host we are connected to
    const err = tls.checkServerIdentity(host, cert);
    if (err) {
      return err;
    }

    // Pin the public key, similar to HPKP pin-sha256 pinning
    const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=';
    if (sha256(cert.pubkey) !== pubkey256) {
      const msg = 'Certificate verification error: ' +
        `The public key of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // Pin the exact certificate, rather than the pub key
    const cert256 = '25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:' +
      'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16';
    if (cert.fingerprint256 !== cert256) {
      const msg = 'Certificate verification error: ' +
        `The certificate of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // This loop is informational only.
    // Print the certificate and public key fingerprints of all certs in the
    // chain. Its common to pin the public key of the issuer on the public
    // internet, while pinning the public key of the service in sensitive
    // environments.
    do {
      console.log('Subject Common Name:', cert.subject.CN);
      console.log('  Certificate SHA256 fingerprint:', cert.fingerprint256);

      hash = crypto.createHash('sha256');
      console.log('  Public key ping-sha256:', sha256(cert.pubkey));

      lastprint256 = cert.fingerprint256;
      cert = cert.issuerCertificate;
    } while (cert.fingerprint256 !== lastprint256);

  },
};

options.agent = new https.Agent(options);
const req = https.request(options, (res) => {
  console.log('All OK. Server matched our pinned cert or public key');
  console.log('statusCode:', res.statusCode);
  // Print the HPKP values
  console.log('headers:', res.headers['public-key-pins']);

  res.on('data', (d) => {});
});

req.on('error', (e) => {
  console.error(e.message);
});
req.end();

Outputs for example:

Subject Common Name: github.com
  Certificate SHA256 fingerprint: 25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16
  Public key ping-sha256: pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=
Subject Common Name: DigiCert SHA2 Extended Validation Server CA
  Certificate SHA256 fingerprint: 40:3E:06:2A:26:53:05:91:13:28:5B:AF:80:A0:D4:AE:42:2C:84:8C:9F:78:FA:D0:1F:C9:4B:C5:B8:7F:EF:1A
  Public key ping-sha256: RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=
Subject Common Name: DigiCert High Assurance EV Root CA
  Certificate SHA256 fingerprint: 74:31:E5:F4:C3:C1:CE:46:90:77:4F:0B:61:E0:54:40:88:3B:A9:A0:1E:D0:0B:A6:AB:D7:80:6E:D3:B1:18:CF
  Public key ping-sha256: WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18=
All OK. Server matched our pinned cert or public key
statusCode: 200
headers: max-age=0; pin-sha256="WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18="; pin-sha256="RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=";
pin-sha256="k2v657xBsOVe1PQRwOsHsw3bsGT2VzIqz5K+59sNQws="; pin-sha256="K87oWBWM9UZfyddvDfoxL+8lpNyoUB2ptGtn0fv6G2Q="; pin-sha256="IQBnNBEiFuhj+8x6X8XLgh01V9Ic5/V3IRQLNFFc7v4=";
pin-sha256="iie1VXtL7HzAMF+/PVPR9xzT80kQxdZeJ+zduCB3uj0="; pin-sha256="LvRiGEjRqfzurezaWuj8Wie2gyHMrW5Q06LspMnox7A="; includeSubDomains

Parameters #

#options: RequestOptions
 | string
 | URL

Accepts all options from request, with some differences in default values:

#callback: (res: http.IncomingMessage) => void

optional

Return Type #

http.ClientRequest

Overload 2

#request(url: string | URL,
options: RequestOptions,
callback?: (res: http.IncomingMessage) => void,
): http.ClientRequest

Parameters #

#url: string | URL

#options: RequestOptions

#callback: (res: http.IncomingMessage) => void

optional

Return Type #

http.ClientRequest

interface AgentOptions

extends [http.AgentOptions][tls.ConnectionOptions]

Usage in Deno

import { type AgentOptions } from "node:https";

Properties #

#maxCachedSessions: number | undefined

optional

class Server

extends tls.Server

Usage in Deno

import { Server } from "node:https";

Deno compatibility

The cert and key options do not support an array input.

See http.Server for more information.

Constructors #

#Server(requestListener?: http.RequestListener<Request, Response>)

new

#Server(options: ServerOptions<Request, Response>,
requestListener?: http.RequestListener<Request, Response>,
)

new

Type Parameters #

#Request extends http.IncomingMessage = http.IncomingMessage

#Response extends http.ServerResponse = http.ServerResponse

Methods #

#addListener(event: string,
listener: (...args: any[]) => void,
): this

#addListener(event: "keylog",
listener: (line: Buffer,
tlsSocket: tls.TLSSocket,
) => void,
): this

#addListener(event: "newSession",
listener: (sessionId: Buffer,
sessionData: Buffer,
callback: (err: Error,
resp: Buffer,
) => void,
) => void,
): this

#addListener(event: "OCSPRequest",
listener: (certificate: Buffer,
issuer: Buffer,
callback: (err: Error | null,
resp: Buffer,
) => void,
) => void,
): this

#addListener(event: "resumeSession",
listener: (sessionId: Buffer,
callback: (err: Error,
sessionData: Buffer,
) => void,
) => void,
): this

#addListener(event: "secureConnection",
listener: (tlsSocket: tls.TLSSocket) => void,
): this

#addListener(event: "tlsClientError",
listener: (err: Error,
tlsSocket: tls.TLSSocket,
) => void,
): this

#addListener(event: "close",
listener: () => void,
): this

#addListener(event: "connection",
listener: (socket: Duplex) => void,
): this

#addListener(event: "error",
listener: (err: Error) => void,
): this

#addListener(event: "listening",
listener: () => void,
): this

#addListener(event: "checkContinue",
listener: http.RequestListener<Request, Response>,
): this

#addListener(event: "checkExpectation",
listener: http.RequestListener<Request, Response>,
): this

#addListener(event: "clientError",
listener: (err: Error,
socket: Duplex,
) => void,
): this

#addListener(event: "connect",
listener: (req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
) => void,
): this

#addListener(event: "request",
listener: http.RequestListener<Request, Response>,
): this

#addListener(event: "upgrade",
listener: (req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
) => void,
): this

#closeAllConnections(): void

Closes all connections connected to this server.

#closeIdleConnections(): void

Closes all connections connected to this server which are not sending a request or waiting for a response.

#emit(event: string,
...args: any[],
): boolean

#emit(event: "keylog",
line: Buffer,
tlsSocket: tls.TLSSocket,
): boolean

#emit(event: "newSession",
sessionId: Buffer,
sessionData: Buffer,
callback: (err: Error,
resp: Buffer,
) => void,
): boolean

#emit(event: "OCSPRequest",
certificate: Buffer,
issuer: Buffer,
callback: (err: Error | null,
resp: Buffer,
) => void,
): boolean

#emit(event: "resumeSession",
sessionId: Buffer,
callback: (err: Error,
sessionData: Buffer,
) => void,
): boolean

#emit(event: "secureConnection",
tlsSocket: tls.TLSSocket,
): boolean

#emit(event: "tlsClientError",
err: Error,
tlsSocket: tls.TLSSocket,
): boolean

#emit(event: "close"): boolean

#emit(event: "connection",
socket: Duplex,
): boolean

#emit(event: "error",
err: Error,
): boolean

#emit(event: "listening"): boolean

#emit(event: "checkContinue",
req: InstanceType<Request>,
res: InstanceType<Response>,
): boolean

#emit(event: "checkExpectation",
req: InstanceType<Request>,
res: InstanceType<Response>,
): boolean

#emit(event: "clientError",
err: Error,
socket: Duplex,
): boolean

#emit(event: "connect",
req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
): boolean

#emit(event: "request",
req: InstanceType<Request>,
res: InstanceType<Response>,
): boolean

#emit(event: "upgrade",
req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
): boolean

#on(event: string,
listener: (...args: any[]) => void,
): this

#on(event: "keylog",
listener: (line: Buffer,
tlsSocket: tls.TLSSocket,
) => void,
): this

#on(event: "newSession",
listener: (sessionId: Buffer,
sessionData: Buffer,
callback: (err: Error,
resp: Buffer,
) => void,
) => void,
): this

#on(event: "OCSPRequest",
listener: (certificate: Buffer,
issuer: Buffer,
callback: (err: Error | null,
resp: Buffer,
) => void,
) => void,
): this

#on(event: "resumeSession",
listener: (sessionId: Buffer,
callback: (err: Error,
sessionData: Buffer,
) => void,
) => void,
): this

#on(event: "secureConnection",
listener: (tlsSocket: tls.TLSSocket) => void,
): this

#on(event: "tlsClientError",
listener: (err: Error,
tlsSocket: tls.TLSSocket,
) => void,
): this

#on(event: "close",
listener: () => void,
): this

#on(event: "connection",
listener: (socket: Duplex) => void,
): this

#on(event: "error",
listener: (err: Error) => void,
): this

#on(event: "listening",
listener: () => void,
): this

#on(event: "checkContinue",
listener: http.RequestListener<Request, Response>,
): this

#on(event: "checkExpectation",
listener: http.RequestListener<Request, Response>,
): this

#on(event: "clientError",
listener: (err: Error,
socket: Duplex,
) => void,
): this

#on(event: "connect",
listener: (req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
) => void,
): this

#on(event: "request",
listener: http.RequestListener<Request, Response>,
): this

#on(event: "upgrade",
listener: (req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
) => void,
): this

#once(event: string,
listener: (...args: any[]) => void,
): this

#once(event: "keylog",
listener: (line: Buffer,
tlsSocket: tls.TLSSocket,
) => void,
): this

#once(event: "newSession",
listener: (sessionId: Buffer,
sessionData: Buffer,
callback: (err: Error,
resp: Buffer,
) => void,
) => void,
): this

#once(event: "OCSPRequest",
listener: (certificate: Buffer,
issuer: Buffer,
callback: (err: Error | null,
resp: Buffer,
) => void,
) => void,
): this

#once(event: "resumeSession",
listener: (sessionId: Buffer,
callback: (err: Error,
sessionData: Buffer,
) => void,
) => void,
): this

#once(event: "secureConnection",
listener: (tlsSocket: tls.TLSSocket) => void,
): this

#once(event: "tlsClientError",
listener: (err: Error,
tlsSocket: tls.TLSSocket,
) => void,
): this

#once(event: "close",
listener: () => void,
): this

#once(event: "connection",
listener: (socket: Duplex) => void,
): this

#once(event: "error",
listener: (err: Error) => void,
): this

#once(event: "listening",
listener: () => void,
): this

#once(event: "checkContinue",
listener: http.RequestListener<Request, Response>,
): this

#once(event: "checkExpectation",
listener: http.RequestListener<Request, Response>,
): this

#once(event: "clientError",
listener: (err: Error,
socket: Duplex,
) => void,
): this

#once(event: "connect",
listener: (req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
) => void,
): this

#once(event: "request",
listener: http.RequestListener<Request, Response>,
): this

#once(event: "upgrade",
listener: (req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
) => void,
): this

#prependListener(event: string,
listener: (...args: any[]) => void,
): this

#prependListener(event: "keylog",
listener: (line: Buffer,
tlsSocket: tls.TLSSocket,
) => void,
): this

#prependListener(event: "newSession",
listener: (sessionId: Buffer,
sessionData: Buffer,
callback: (err: Error,
resp: Buffer,
) => void,
) => void,
): this

#prependListener(event: "OCSPRequest",
listener: (certificate: Buffer,
issuer: Buffer,
callback: (err: Error | null,
resp: Buffer,
) => void,
) => void,
): this

#prependListener(event: "resumeSession",
listener: (sessionId: Buffer,
callback: (err: Error,
sessionData: Buffer,
) => void,
) => void,
): this

#prependListener(event: "secureConnection",
listener: (tlsSocket: tls.TLSSocket) => void,
): this

#prependListener(event: "tlsClientError",
listener: (err: Error,
tlsSocket: tls.TLSSocket,
) => void,
): this

#prependListener(event: "close",
listener: () => void,
): this

#prependListener(event: "connection",
listener: (socket: Duplex) => void,
): this

#prependListener(event: "error",
listener: (err: Error) => void,
): this

#prependListener(event: "listening",
listener: () => void,
): this

#prependListener(event: "checkContinue",
listener: http.RequestListener<Request, Response>,
): this

#prependListener(event: "checkExpectation",
listener: http.RequestListener<Request, Response>,
): this

#prependListener(event: "clientError",
listener: (err: Error,
socket: Duplex,
) => void,
): this

#prependListener(event: "connect",
listener: (req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
) => void,
): this

#prependListener(event: "request",
listener: http.RequestListener<Request, Response>,
): this

#prependListener(event: "upgrade",
listener: (req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
) => void,
): this

#prependOnceListener(event: string,
listener: (...args: any[]) => void,
): this

#prependOnceListener(event: "keylog",
listener: (line: Buffer,
tlsSocket: tls.TLSSocket,
) => void,
): this

#prependOnceListener(event: "newSession",
listener: (sessionId: Buffer,
sessionData: Buffer,
callback: (err: Error,
resp: Buffer,
) => void,
) => void,
): this

#prependOnceListener(event: "OCSPRequest",
listener: (certificate: Buffer,
issuer: Buffer,
callback: (err: Error | null,
resp: Buffer,
) => void,
) => void,
): this

#prependOnceListener(event: "resumeSession",
listener: (sessionId: Buffer,
callback: (err: Error,
sessionData: Buffer,
) => void,
) => void,
): this

#prependOnceListener(event: "secureConnection",
listener: (tlsSocket: tls.TLSSocket) => void,
): this

#prependOnceListener(event: "tlsClientError",
listener: (err: Error,
tlsSocket: tls.TLSSocket,
) => void,
): this

#prependOnceListener(event: "close",
listener: () => void,
): this

#prependOnceListener(event: "connection",
listener: (socket: Duplex) => void,
): this

#prependOnceListener(event: "error",
listener: (err: Error) => void,
): this

#prependOnceListener(event: "listening",
listener: () => void,
): this

#prependOnceListener(event: "checkContinue",
listener: http.RequestListener<Request, Response>,
): this

#prependOnceListener(event: "checkExpectation",
listener: http.RequestListener<Request, Response>,
): this

#prependOnceListener(event: "clientError",
listener: (err: Error,
socket: Duplex,
) => void,
): this

#prependOnceListener(event: "connect",
listener: (req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
) => void,
): this

#prependOnceListener(event: "request",
listener: http.RequestListener<Request, Response>,
): this

#prependOnceListener(event: "upgrade",
listener: (req: InstanceType<Request>,
socket: Duplex,
head: Buffer,
) => void,
): this

interface Server

extends [http.Server]<Request, Response>

Deno compatibility

The cert and key options do not support an array input.

Type Parameters #

#Request extends http.IncomingMessage = http.IncomingMessage

#Response extends http.ServerResponse = http.ServerResponse

type alias RequestOptions

Usage in Deno

import { type RequestOptions } from "node:https";

Definition #

http.RequestOptions
 & tls.SecureContextOptions
 & { checkServerIdentity?: ((hostname: string,
cert: tls.DetailedPeerCertificate,
) => Error | undefined) | undefined; rejectUnauthorized?: boolean | undefined; servername?: string | undefined;  }

type alias ServerOptions

Usage in Deno

import { type ServerOptions } from "node:https";

Type Parameters #

#Request extends http.IncomingMessage = http.IncomingMessage

#Response extends http.ServerResponse = http.ServerResponse

Definition #

tls.SecureContextOptions
 & tls.TlsOptions
 & http.ServerOptions<Request, Response>

variable globalAgent

Usage in Deno

import { globalAgent } from "node:https";

Type #

Agent

Classes

Functions

Interfaces

Type Aliases

Variables

class Agent

Usage in Deno

Constructors #

Properties #

function createServer

Usage in Deno

Overload 1

Type Parameters #

Parameters #

Return Type #

Overload 2

Type Parameters #

Parameters #

Return Type #

function get

Usage in Deno

Overload 1

Parameters #

Return Type #

Overload 2

Parameters #

Return Type #

function request

Usage in Deno

Overload 1

Parameters #

Return Type #

Overload 2

Parameters #

Return Type #

interface AgentOptions

Usage in Deno

Properties #

class Server

Usage in Deno

Constructors #

Type Parameters #

Methods #

interface Server

Type Parameters #

type alias RequestOptions

Usage in Deno

Definition #

type alias ServerOptions

Usage in Deno

Type Parameters #

Definition #

variable globalAgent

Usage in Deno

Type #

Did you find what you needed?