Node.js v21.7.2 ドキュメント

cryptoサポートが利用できないかどうかの判断#

Node.js は、node:crypto モジュールのサポートを含めずにビルドされる可能性があります。 このような場合、https から import しようとしたり、require('node:https') を呼び出そうとすると、エラーがスローされます。

CommonJS を使用する場合、スローされたエラーは try/catch を使用してキャッチできます

let https;
try {
  https = require('node:https');
} catch (err) {
  console.error('https support is disabled!');
} copy

字句 ESM import キーワードを使用する場合、モジュールのロードを試みる前に process.on('uncaughtException') のハンドラーが登録されている場合（たとえば、プリロードモジュールを使用するなど）のみエラーをキャッチできます。

ESM を使用する場合、コードが crypto サポートが有効になっていない Node.js のビルドで実行される可能性がある場合は、字句 import キーワードの代わりに import() 関数を使用することを検討してください。

let https;
try {
  https = await import('node:https');
} catch (err) {
  console.error('https support is disabled!');
} copy

クラス: https.Agent#

http.Agent と同様の HTTPS 用の Agent オブジェクトです。 詳しくは、https.request() を参照してください。

new Agent([options])#

• options <Object> エージェントに設定する構成可能なオプションのセット。http.Agent(options) と同じフィールドを持つことができます。また、

  • maxCachedSessions <number> TLSキャッシュセッションの最大数。TLSセッションキャッシュを無効にするには0を使用します。デフォルト: 100。

  • servername <string> サーバーに送信する Server Name Indication 拡張の値。拡張機能の送信を無効にするには、空の文字列 '' を使用します。デフォルト: ターゲットサーバーがIPアドレスを使用して指定されている場合を除き、ターゲットサーバーのホスト名です。その場合は、デフォルトは ''（拡張機能なし）です。

    TLSセッションの再利用については、セッションの再開 を参照してください。

イベント: 'keylog'#

• line <Buffer> NSS SSLKEYLOGFILE 形式の ASCII テキストの行。
• tlsSocket <tls.TLSSocket> 生成された tls.TLSSocket インスタンス。

keylog イベントは、このエージェントによって管理される接続でキーマテリアルが生成または受信されたときに発行されます（通常はハンドシェイクが完了する前ですが、必ずしもそうではありません）。このキーマテリアルは、キャプチャされたTLSトラフィックを復号化できるため、デバッグ用に保存できます。各ソケットに対して複数回発行される場合があります。

一般的なユースケースは、受信した行を共通のテキストファイルに追加することです。これは、後でトラフィックを復号化するためにソフトウェア（Wiresharkなど）によって使用されます。

// ...
https.globalAgent.on('keylog', (line, tlsSocket) => {
  fs.appendFileSync('/tmp/ssl-keys.log', line, { mode: 0o600 });
}); copy

クラス: https.Server#

• 拡張: <tls.Server>

詳細については、http.Server を参照してください。

server.close([callback])#

• callback <Function>
• 戻り値: <https.Server>

node:http モジュールの server.close() を参照してください。

server[Symbol.asyncDispose]()#

server.close() を呼び出し、サーバーが閉じたときに解決される Promise を返します。

server.closeAllConnections()#

node:http モジュールの server.closeAllConnections() を参照してください。

server.closeIdleConnections()#

node:http モジュールの server.closeIdleConnections() を参照してください。

server.headersTimeout#

• <number> デフォルト: 60000

node:http モジュールの server.headersTimeout を参照してください。

server.listen()#

暗号化された接続をリッスンするHTTPSサーバーを起動します。このメソッドは、net.Server の server.listen() と同じです。

server.maxHeadersCount#

• <number> デフォルト: 2000

node:http モジュールの server.maxHeadersCount を参照してください。

server.requestTimeout#

• <number> デフォルト: 300000

node:http モジュールの server.requestTimeout を参照してください。

server.setTimeout([msecs][, callback])#

• msecs <number> デフォルト: 120000 (2 分)
• callback <Function>
• 戻り値: <https.Server>

node:http モジュールの server.setTimeout() を参照してください。

server.timeout#

• <number> デフォルト: 0 (タイムアウトなし)

node:http モジュールの server.timeout を参照してください。

server.keepAliveTimeout#

• <number> デフォルト: 5000 (5 秒)

node:http モジュールの server.keepAliveTimeout を参照してください。

https.createServer([options][, requestListener])#

• options <オブジェクト> tls.createServer()、tls.createSecureContext()、および http.createServer() からのoptionsを受け入れます。
• requestListener <関数> 'request' イベントに追加されるリスナーです。
• 戻り値: <https.Server>

// curl -k https://127.0.0.1:8000/
const https = require('node:https');
const fs = require('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); copy

または

const https = require('node:https');
const fs = require('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); copy

https.get(options[, callback])#

https.get(url[, options][, callback])#

• url <文字列> | <URL>
• options <オブジェクト> | <文字列> | <URL> https.request() と同じ options を受け入れます。デフォルトではメソッドが GET に設定されています。
• callback <Function>

http.get() と同様ですが、HTTPS 用です。

options は、オブジェクト、文字列、または URL オブジェクトにすることができます。options が文字列の場合、new URL() で自動的に解析されます。もし URL オブジェクトの場合、通常の options オブジェクトに自動的に変換されます。

const https = require('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);
}); copy

https.globalAgent#

すべての HTTPS クライアントリクエストに対する https.Agent のグローバルインスタンス。

https.request(options[, callback])#

https.request(url[, options][, callback])#

• url <文字列> | <URL>
• options <オブジェクト> | <文字列> | <URL> http.request() からのすべての options を受け入れます。デフォルト値にいくつかの違いがあります。
  • protocol デフォルト: 'https:'
  • port デフォルト: 443
  • agent デフォルト: https.globalAgent
• callback <Function>
• 戻り値: <http.ClientRequest>

セキュアな Web サーバーにリクエストを送信します。

次の追加の options が tls.connect() からも受け入れられます。ca、cert、ciphers、clientCertEngine、crl、dhparam、ecdhCurve、honorCipherOrder、key、passphrase、pfx、rejectUnauthorized、secureOptions、secureProtocol、servername、sessionIdContext、highWaterMark。

options は、オブジェクト、文字列、または URL オブジェクトにすることができます。options が文字列の場合、new URL() で自動的に解析されます。もし URL オブジェクトの場合、通常の options オブジェクトに自動的に変換されます。

https.request() は http.ClientRequest クラスのインスタンスを返します。ClientRequest インスタンスは書き込み可能なストリームです。POST リクエストでファイルをアップロードする必要がある場合は、ClientRequest オブジェクトに書き込みます。

const https = require('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(); copy

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) => {
  // ...
}); copy

または、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) => {
  // ...
}); copy

options として URL を使用した例

const options = new URL('https://abc:[email protected]');

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

証明書のフィンガープリントまたは公開鍵（pin-sha256 と同様）でのピン留めの例

const tls = require('node:tls');
const https = require('node:https');
const crypto = require('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(); copy

出力例

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 copy