الوحدة HTTPS في Node.js

مؤشر الاستقرار: 2 - مستقر

HTTPS هو بروتوكول HTTP على TLS/SSL. وهو ينفذ كوحدة منفصلة في Node.js.

الصنف `https.Agent`

أُضيف مع الإصدار: v0.4.5.

كائن وكيل Agent لبروتوكول HTTPS مشابه للوكيل http.Agent. راجع https.request()‎‎ لمزيد من المعلومات.

الصنف `https.Server`

أُضيف مع الإصدار: v0.3.4.

هذا الصنف هو صنف فرعي من tls.Server ويُطلق الأحداث نفسها كخادم http.Server. راجع http.Server لمزيد من المعلومات.

`server.close([callback])‎`

أُضيف مع الإصدار: v0.1.90.

callback من النوع <Function>.

راجع server.close()‎‎ من وحدة HTTP لمزيد من التفاصيل.

`server.listen()‎‎`

يبدأ استماع خادم HTTPS للاتصالات المشفرة. يطابق هذا التابع server.listen()‎‎ من net.Server.

`server.maxHeadersCount`

<number> القيمة الافتراضية: 2000.

راجع http.ServermaxHeadersCount.

`server.setTimeout([msecs][, callback])‎`

أُضيف مع الإصدار: v0.11.2.

msecs من النوع <number> القيمة الافتراضية: 120000 (دقيقتين).
callback من النوع <Function>.

راجع http.ServersetTimeout()‎‎.

`server.timeout`

أُضيف مع الإصدار: v0.11.2.

msecs من النوع <number> القيمة الافتراضية: 120000 (دقيقتين)

راجع http.Servertimeout.

`server.keepAliveTimeout`

أُضيف مع الإصدار: v8.0.0.

<number> القيمة الافتراضية: 5000 (5 ثوان)

راجع http.ServerkeepAliveTimeout.

`https.createServer([options][, requestListener])‎`

أُضيف مع الإصدار: v0.3.4.

options من النوع <Object>: تقبل الخيارات من tls.createServer()‎‎ و tls.createSecureContext()‎ و http.createServer()‎.
requestListener من النوع <Function>: وهو مستمع يُضاف إلى الحدث 'request'.

على سبيل المثال:

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

أو

const https = require('https');
const fs = require('fs');

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

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('مرحبًا أيها العالم\n');
}).listen(8000);

`https.get(options[, callback])‎`

سجل التغييرات

الإصدار	التغييرات
v7.5.0	يمكن أن يكون المعامل `options` كائن WHATWG `URL`.
v0.3.6	أُضيف مع الإصدار: v0.3.6.

options من النوع ‎<Object> | <string> | <URL>‎: ويقبل نفس الخيارات options التي يقبلها https.request()‎، مع ضبط method دائما على GET.
callback من النوع <Function>.

مثل http.get()‎‎ لكن بالنسبة إلى HTTPS.

يمكن أن يكون options كائنًا أو سلسلة نصية أو كائن URL. إذا كان options سلسلة نصية، فإنه يُحلَل تلقائيا بواسطة url.parse()‎‎ إذا كان URL كائن، سيُحول تلقائيًا إلى لكائن options عادي.

على سبيل المثال:

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

`https.globalAgent`

أُضيف مع الإصدار: v0.5.9

مثيل عام من https.Agent لكل طلبات عميل HTTPS.

`https.request(options[, callback])‎`

سجل التغييرات

الإصدار	التغييرات
v9.3.0	يمكن الآن أن يتضمن المعامل `options` على `clientCertEngine`.
v7.5.0	يمكن أن يكون المعامل `options` كائن WHATWG `URL`.
v0.3.6	أُضيف مع الإصدار: v0.3.6.

options من النوع ‎<Object> | <string> | <URL>‎: يقبل جميعَ الخيارات options من http.request()‎‎، مع بعض الاختلافات في القيم الافتراضية:
- protocol القيمة الافتراضية: 'https:'.
- port القيمة الافتراضية: 443.
- الوكيل القيمة الافتراضية: https.globalAgent.
callback من النوع <Function>.

تقديم طلب إلى خادم لتصفح الآمن.

كما تُقبل أيضًا خيارات tls.connect()‎ الإضافية التالية: ca و cert و ciphers و clientCertEngine و crl و dhparam و ecdhCurve و honorCipherOrder و key و passphrase و pfx و rejectUnauthorized و secureOptions و secureProtocol و servername و sessionIdContext.

يمكن أن يكون options كائنًا أو سلسلة نصية أو كائن URL. إذا كان options سلسلة نصية، فإنه يُحلَل تلقائيا بواسطة url.parse()‎‎ إذا كان URL كائن، سيُحول تلقائيًا إلى لكائن options عادي.

على سبيل المثال:

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

مثال على استخدام خيارات من 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) => {
  // ...
});

بدلا من ذلك، الانسحاب من تجمع الاتصالات من خلال عدم استخدام الوكيل 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) => {
  // ...
});

مثال على استخدام URL كخيار options:

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

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

مثال يتعلق ببصمات الشهادة، أو المفتاح العام (على غرار pin-sha256):

const tls = require('tls');
const https = require('https');
const crypto = require('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) {
// التأكد من إصدار الشهادة للمضيف المتصل به
    const err = tls.checkServerIdentity(host, cert);
    if (err) {
      return err;
    }

// تثبيت المفتاح العام، على غرار تثبيت HPKP pin-sha25
    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);
    }

// تثبيت الشهادة الصحيحة، بدلاً من المفتاح العام    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 finge
rprint';
      return new Error(msg);
    }

    // هذه الحلقة بغرض التعليم فقط.
    // طباعة الشهادة وبصمات المفاتيح العامة لكل أنواع الشهادات في السلسلة.
    // من الشائع تثبيت المفتاح العام للمُصدِر على الإنترنت العام،
    // بينما يثبّت المفتاح العام للخدمة في البيئات الحساسة.
    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);
// طباعة قيم HPKP
  console.log('headers:', res.headers['public-key-pins']);

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

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

وتكون مخرجات هذا المثال:

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

مصادر

صفحةHTTPS ‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎ في توثيق Node.js الرسمي.

الصنف https.Agent

الصنف https.Server

server.close([callback])‎

server.listen()‎‎

server.maxHeadersCount

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

server.timeout

server.keepAliveTimeout

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

https.get(options[, callback])‎

https.globalAgent

https.request(options[, callback])‎

مصادر

الصنف `https.Agent`

الصنف `https.Server`

`server.close([callback])‎`

`server.listen()‎‎`

`server.maxHeadersCount`

`server.setTimeout([msecs][, callback])‎`

`server.timeout`

`server.keepAliveTimeout`

`https.createServer([options][, requestListener])‎`

`https.get(options[, callback])‎`

`https.globalAgent`

`https.request(options[, callback])‎`