الوحدة 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);
Or
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 الرسمي.