TLS (SSL)

[مستقر: 2 - مستقر]

مستقر: 2 استقرار: 2 - مستقر

رمز المصدر: lib/tls.js

توفر وحدة node:tls تطبيقًا لبروتوكولات أمان طبقة النقل (TLS) وطبقة المقابس الآمنة (SSL) المُبنية على OpenSSL. يمكن الوصول إلى الوحدة باستخدام:

ESM

import tls from 'node:tls'

CJS

const tls = require('node:tls')

تحديد ما إذا كانت دعم التشفير غير متوفر

من الممكن بناء Node.js بدون تضمين دعم لوحدة node:crypto. في مثل هذه الحالات، سيؤدي محاولة الاستيراد من tls أو استدعاء require('node:tls') إلى إطلاق خطأ.

عند استخدام CommonJS، يمكن التقاط الخطأ المُطلق باستخدام try/catch:

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

عند استخدام الكلمة الأساسية import ESM النحوية، لا يمكن التقاط الخطأ إلا إذا تم تسجيل مُعالِج لـ process.on('uncaughtException') قبل إجراء أي محاولة لتحميل الوحدة (باستخدام، على سبيل المثال، وحدة مُسبقة التحميل).

عند استخدام ESM، إذا كانت هناك فرصة لتنفيذ التعليمات البرمجية على إصدار من Node.js حيث لم يتم تمكين دعم التشفير، فكر في استخدام دالة import() بدلاً من الكلمة الأساسية import النحوية:

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

مفاهيم TLS/SSL

TLS/SSL هي مجموعة من البروتوكولات التي تعتمد على بنية مفتاح عام (PKI) لتمكين الاتصال الآمن بين العميل والخادم. في معظم الحالات الشائعة، يجب أن يكون لكل خادم مفتاح خاص.

يمكن إنشاء المفاتيح الخاصة بطرق متعددة. يوضح المثال أدناه استخدام واجهة سطر أوامر OpenSSL لإنشاء مفتاح خاص RSA بسعة 2048 بت:

openssl genrsa -out ryans-key.pem 2048

مع TLS/SSL، يجب أن يكون لجميع الخوادم (و بعض العملاء) شهادة. الشهادات هي مفاتيح عامة تتوافق مع مفتاح خاص، ويتم توقيعها رقمياً إما بواسطة سلطة إصدار الشهادات أو بواسطة مالك المفتاح الخاص (يُشار إلى هذه الشهادات باسم "ذاتية التوقيع"). الخطوة الأولى للحصول على شهادة هي إنشاء ملف طلب توقيع الشهادة (CSR).

يمكن استخدام واجهة سطر أوامر OpenSSL لإنشاء CSR لمفتاح خاص:

openssl req -new -sha256 -key ryans-key.pem -out ryans-csr.pem

بمجرد إنشاء ملف CSR، يمكن إرساله إلى سلطة إصدار الشهادات للتوقيع أو استخدامه لإنشاء شهادة ذاتية التوقيع.

يُوضح المثال أدناه إنشاء شهادة ذاتية التوقيع باستخدام واجهة سطر أوامر OpenSSL:

openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem

بمجرد إنشاء الشهادة، يمكن استخدامها لإنشاء ملف .pfx أو .p12:

openssl pkcs12 -export -in ryans-cert.pem -inkey ryans-key.pem \
      -certfile ca-cert.pem -out ryans.pfx

حيث:

• in: هي الشهادة الموقعة
• inkey: هو المفتاح الخاص المرتبط
• certfile: هو دمج لجميع شهادات سلطة إصدار الشهادات (CA) في ملف واحد، مثل cat ca1-cert.pem ca2-cert.pem \> ca-cert.pem

سرية التوجّه التامّة

يُشير مصطلح سرية التوجّه التامّة أو سرية التوجّه الأمثل إلى ميزة في طرق اتفاقية المفاتيح (أي، تبادل المفاتيح). أي أن مفاتيح الخادم والعميل تُستخدم للتفاوض على مفاتيح مؤقتة جديدة تُستخدم خصيصاً ولجلسة الاتصال الحالية فقط. عملياً، هذا يعني أنه حتى إذا تم اختراق المفتاح الخاص للخادم، لا يمكن فك تشفير الاتصال إلا من قِبل المتنصّتين إذا تمكّن المهاجم من الحصول على زوج المفاتيح المُولّد خصيصاً للجلسة.

يتم تحقيق سرية التوجّه التامّة من خلال توليد زوج مفاتيح عشوائياً لاتفاقية المفاتيح في كل عملية مصافحة TLS/SSL (على عكس استخدام نفس المفتاح لجميع الجلسات). تُسمّى الطرق التي تُنفّذ هذه التقنية "عابرة".

حالياً، تُستخدم طريقتان بشكل شائع لتحقيق سرية التوجّه التامّة (لاحظ حرف "E" المضاف إلى الاختصارات التقليدية):

• ECDHE: نسخة عابرة من بروتوكول اتفاقية مفاتيح المنحنى الإهليلجي Diffie-Hellman.
• DHE: نسخة عابرة من بروتوكول اتفاقية مفاتيح Diffie-Hellman.

يتم تمكين سرية التوجّه التامّة باستخدام ECDHE بشكل افتراضي. يمكن استخدام خيار ecdhCurve عند إنشاء خادم TLS لتخصيص قائمة منحنيات ECDH المدعومة للاستخدام. راجع tls.createServer() لمزيد من المعلومات.

DHE معطل بشكل افتراضي، لكن يمكن تمكينه إلى جانب ECDHE عن طريق تعيين خيار dhparam إلى 'auto'. كما تُدعم معلمات DHE المخصصة، لكن يُنصح بعدم استخدامها لصالح المعلمات المحددة تلقائياً والمعروفة جيداً.

كانت سرية التوجّه التامّة اختيارية حتى TLSv1.2. اعتباراً من TLSv1.3، يتم دائمًا استخدام (EC)DHE (باستثناء اتصالات PSK فقط).

ALPN و SNI

ALPN (امتداد التفاوض على بروتوكول طبقة التطبيق) و SNI (مؤشر اسم الخادم) هما امتدادات مصافحة TLS:

• ALPN: يسمح باستخدام خادم TLS واحد للعديد من البروتوكولات (HTTP، HTTP/2)
• SNI: يسمح باستخدام خادم TLS واحد للعديد من أسماء المضيفين بشهادات مختلفة.

مفاتيح مُسبقة المشاركة

يُتاح دعم TLS-PSK كبديل لطريقة المصادقة المعتادة القائمة على الشهادات. يستخدم مفتاحًا مُسبق المشاركة بدلاً من الشهادات لمصادقة اتصال TLS، مما يوفر مصادقة متبادلة. لا يستبعد TLS-PSK والبنية التحتية للمفتاح العام بعضهما البعض. يمكن للعملاء والخوادم استيعاب كليهما، واختيار أحدهما أثناء خطوة التفاوض على التشفير العادية.

يُعد TLS-PSK خيارًا جيدًا فقط عندما توجد وسائل لمشاركة مفتاح آمن مع كل جهاز متصل، لذلك لا يحل محل البنية التحتية للمفتاح العام (PKI) لمعظم استخدامات TLS. لقد شهد تنفيذ TLS-PSK في OpenSSL العديد من العيوب الأمنية في السنوات الأخيرة، وذلك غالباً لأنه يُستخدم فقط من قبل أقلية من التطبيقات. يُرجى مراعاة جميع الحلول البديلة قبل التبديل إلى تشفير PSK. عند إنشاء PSK، من الأهمية بمكان استخدام كمية كافية من الإنتروبيا كما هو موضح في RFC 4086. إن اشتقاق سر مُشارك من كلمة مرور أو مصادر أخرى منخفضة الإنتروبيا ليس آمنًا.

يتم تعطيل تشفير PSK افتراضيًا، وبالتالي فإن استخدام TLS-PSK يتطلب تحديد مجموعة تشفير صراحةً باستخدام خيار ciphers. يمكن استرداد قائمة التشفير المتاحة عبر openssl ciphers -v 'PSK'. جميع تشفير TLS 1.3 مؤهلة لـ PSK ويمكن استردادها عبر openssl ciphers -v -s -tls1_3 -psk. على اتصال العميل، يجب تمرير checkServerIdentity مخصص لأن الإعداد الافتراضي سوف يفشل في حالة عدم وجود شهادة.

وفقًا لـ RFC 4279، يجب دعم هويات PSK التي يصل طولها إلى 128 بايت وPSK التي يصل طولها إلى 64 بايت. اعتبارًا من OpenSSL 1.1.0، الحد الأقصى لحجم الهوية هو 128 بايت، والحد الأقصى لطول PSK هو 256 بايت.

لا يدعم التنفيذ الحالي استدعاءات PSK غير المتزامنة نظرًا لقيود واجهة برمجة التطبيقات OpenSSL الأساسية.

لاستخدام TLS-PSK، يجب على العميل والخادم تحديد خيار pskCallback، وهي دالة تُعيد PSK لاستخدامه (والتي يجب أن تكون متوافقة مع خلاصة التشفير المحددة).

سيتم استدعاءه أولاً على العميل:

• تلميح: <string> رسالة اختيارية مُرسلة من الخادم لمساعدة العميل على تحديد هوية لاستخدامها أثناء التفاوض. دائمًا null إذا تم استخدام TLS 1.3.
• المُرتجع: <Object> بالشكل { psk: \<Buffer|TypedArray|DataView\>, identity: \<string\> } أو null.

ثم على الخادم:

• socket: <tls.TLSSocket> مثيل مقبس الخادم، ما يعادل this.
• identity: <string> معلمة الهوية المُرسلة من العميل.
• المُرتجع: <Buffer> | <TypedArray> | <DataView> PSK (أو null).

قيمة مُرتجعة تساوي null تُوقف عملية التفاوض وتُرسل رسالة تنبيه unknown_psk_identity إلى الطرف الآخر. إذا رغب الخادم في إخفاء حقيقة أن هوية PSK لم تكن معروفة، فيجب أن يوفر الاستدعاء بعض البيانات العشوائية كـ psk لجعل الاتصال يفشل مع decrypt_error قبل الانتهاء من التفاوض.

التخفيف من هجوم إعادة التفاوض الذي يبدأه العميل

يسمح بروتوكول TLS للعملاء بإعادة التفاوض على جوانب معينة من جلسة TLS. لسوء الحظ، يتطلب إعادة التفاوض على الجلسة قدرًا غير متناسب من موارد جانب الخادم، مما يجعله ناقلًا محتملاً لهجمات رفض الخدمة.

للتخفيف من هذه المخاطر، يقتصر إعادة التفاوض على ثلاث مرات كل عشر دقائق. يتم إصدار حدث 'error' على مثيل tls.TLSSocket عندما يتم تجاوز هذا الحد. يمكن تكوين الحدود:

• tls.CLIENT_RENEG_LIMIT <number> يحدد عدد طلبات إعادة التفاوض. الافتراضي: 3.
• tls.CLIENT_RENEG_WINDOW <number> يحدد نافذة وقت إعادة التفاوض بالثواني. الافتراضي: 600 (10 دقائق).

لا ينبغي تعديل حدود إعادة التفاوض الافتراضية بدون فهم كامل للتداعيات والمخاطر.

لا يدعم TLSv1.3 إعادة التفاوض.

استئناف الجلسة

إن إنشاء جلسة TLS قد يكون بطيئًا نسبيًا. يمكن تسريع هذه العملية من خلال حفظ حالة الجلسة وإعادة استخدامها لاحقًا. هناك العديد من الآليات للقيام بذلك، والتي سيتم مناقشتها هنا من الأقدم إلى الأحدث (والمفضل).

معرفات الجلسة

يقوم الخادم بإنشاء معرف فريد للاتصالات الجديدة ويرسله إلى العميل. يقوم كل من العميل والخادم بحفظ حالة الجلسة. عند إعادة الاتصال، يرسل العملاء معرف حالة الجلسة المحفوظة الخاصة بهم، وإذا كان الخادم يحتوي أيضًا على الحالة لهذا المعرف، فيمكنه الموافقة على استخدامه. خلاف ذلك، سيقوم الخادم بإنشاء جلسة جديدة. راجع RFC 2246 لمزيد من المعلومات، الصفحة 23 و 30.

يدعم معظم متصفحات الويب استئناف استخدام معرفات الجلسة عند إجراء طلبات HTTPS.

بالنسبة إلى Node.js، ينتظر العملاء حدث 'session' للحصول على بيانات الجلسة، وتوفير البيانات إلى خيار session لـ tls.connect() لاحق لإعادة استخدام الجلسة. يجب على الخوادم تنفيذ معالجات لأحداث 'newSession' و 'resumeSession' لحفظ واستعادة بيانات الجلسة باستخدام معرف الجلسة كمفتاح بحث لإعادة استخدام الجلسات. لإعادة استخدام الجلسات عبر موازنات التحميل أو عمال العناقيد، يجب على الخوادم استخدام ذاكرة تخزين مؤقتة مشتركة للجلسة (مثل Redis) في معالجات الجلسة الخاصة بها.

تذاكر الجلسة

تشفر الخوادم حالة الجلسة بأكملها وترسلها إلى العميل كتذكرة. عند إعادة الاتصال، يتم إرسال الحالة إلى الخادم في الاتصال الأولي. تتجنب هذه الآلية الحاجة إلى ذاكرة تخزين مؤقت للجلسة على جانب الخادم. إذا لم يستخدم الخادم التذكرة، لأي سبب (فشل في فك تشفيرها، أو أنها قديمة جدًا، وما إلى ذلك)، فسيقوم بإنشاء جلسة جديدة وإرسال تذكرة جديدة. راجع RFC 5077 لمزيد من المعلومات.

أصبحت استئناف استخدام تذاكر الجلسة مدعومًا بشكل شائع من قبل العديد من متصفحات الويب عند إجراء طلبات HTTPS.

بالنسبة إلى Node.js، يستخدم العملاء نفس واجهات برمجة التطبيقات لاستئناف استخدام معرفات الجلسة كما هو الحال لاستئناف استخدام تذاكر الجلسة. لأغراض التصحيح، إذا قام tls.TLSSocket.getTLSTicket() بإرجاع قيمة، فإن بيانات الجلسة تحتوي على تذكرة، وإلا فإنها تحتوي على حالة جلسة على جانب العميل.

مع TLSv1.3، انتبه إلى أنه قد يتم إرسال تذاكر متعددة من قبل الخادم، مما يؤدي إلى أحداث 'session' متعددة، راجع 'session' لمزيد من المعلومات.

لا تحتاج خوادم المعالجة الفردية إلى تنفيذ محدد لاستخدام تذاكر الجلسة. لاستخدام تذاكر الجلسة عبر إعادة تشغيل الخادم أو موازنات التحميل، يجب أن تحتوي جميع الخوادم على مفاتيح تذاكر متطابقة. يوجد داخليًا ثلاثة مفاتيح بـ 16 بايت، لكن واجهة برمجة تطبيقات tls تعرضها كعازلة واحدة بـ 48 بايت من أجل الراحة.

من الممكن الحصول على مفاتيح التذاكر عن طريق استدعاء server.getTicketKeys() على مثيل خادم واحد ثم توزيعها، ولكن من الأفضل إنشاء 48 بايت من البيانات العشوائية الآمنة بشكل آمن وتعيينها باستخدام خيار ticketKeys من tls.createServer(). يجب إعادة إنشاء المفاتيح بانتظام ويمكن إعادة تعيين مفاتيح الخادم باستخدام server.setTicketKeys().

مفاتيح تذاكر الجلسة هي مفاتيح تشفير، ويجب تخزينها بشكل آمن. مع TLS 1.2 وما دون، إذا تم اختراقها، يمكن فك تشفير جميع الجلسات التي استخدمت تذاكر مشفرة بها. لا يجب تخزينها على القرص، ويجب إعادة إنشائها بانتظام.

إذا أعلن العملاء دعم التذاكر، سيرسلها الخادم. يمكن للخادم تعطيل التذاكر عن طريق توفير require('node:constants').SSL_OP_NO_TICKET في secureOptions.

تنتهي صلاحية كل من معرفات الجلسة وتذاكر الجلسة، مما يتسبب في إنشاء الخادم جلسات جديدة. يمكن تكوين مهلة الانتهاء باستخدام خيار sessionTimeout من tls.createServer().

بالنسبة لجميع الآليات، عند فشل الاستئناف، ستنشئ الخوادم جلسات جديدة. نظرًا لأن فشل استئناف الجلسة لا يتسبب في حدوث أخطاء في اتصال TLS/HTTPS، فمن السهل عدم ملاحظة ضعف أداء TLS بشكل غير ضروري. يمكن استخدام OpenSSL CLI للتحقق من أن الخوادم تستأنف الجلسات. استخدم خيار -reconnect مع openssl s_client، على سبيل المثال:

openssl s_client -connect localhost:443 -reconnect

اقرأ من خلال إخراج التصحيح. يجب أن يقول الاتصال الأول "جديد"، على سبيل المثال:

جديد، TLSv1.2، التشفير هو ECDHE-RSA-AES128-GCM-SHA256

يجب أن يقول الاتصالات اللاحقة "تم إعادة استخدامها"، على سبيل المثال:

تم إعادة استخدامها، TLSv1.2، التشفير هو ECDHE-RSA-AES128-GCM-SHA256

تعديل مجموعة تشفير TLS الافتراضية

تم بناء Node.js مع مجموعة افتراضية من تشفير TLS الممكن تمكينه وتعطيله. يمكن تكوين قائمة التشفير الافتراضية هذه عند بناء Node.js للسماح للتوزيعات بتوفير قائمتها الافتراضية الخاصة.

يمكن استخدام الأمر التالي لعرض مجموعة التشفير الافتراضية:

node -p crypto.constants.defaultCoreCipherList | tr ':' '\n'
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-GCM-SHA384
DHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-SHA256
DHE-RSA-AES128-SHA256
ECDHE-RSA-AES256-SHA384
DHE-RSA-AES256-SHA384
ECDHE-RSA-AES256-SHA256
DHE-RSA-AES256-SHA256
HIGH
!aNULL
!eNULL
!EXPORT
!DES
!RC4
!MD5
!PSK
!SRP
!CAMELLIA

يمكن استبدال هذا الإعداد الافتراضي بالكامل باستخدام مفتاح سطر الأوامر --tls-cipher-list (مباشرة، أو عبر متغير بيئة NODE_OPTIONS). على سبيل المثال، يجعل الأمر التالي ECDHE-RSA-AES128-GCM-SHA256:!RC4 مجموعة تشفير TLS الافتراضية:

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' server.js

export NODE_OPTIONS=--tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4'
node server.js

للتحقق، استخدم الأمر التالي لعرض قائمة التشفير المُحددة، لاحظ الفرق بين defaultCoreCipherList و defaultCipherList:

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' -p crypto.constants.defaultCipherList | tr ':' '\n'
ECDHE-RSA-AES128-GCM-SHA256
!RC4

أي أن قائمة defaultCoreCipherList يتم تعيينها وقت التجميع وقائمة defaultCipherList يتم تعيينها وقت التشغيل.

لتعديل مجموعات التشفير الافتراضية من داخل وقت التشغيل، قم بتعديل متغير tls.DEFAULT_CIPHERS، يجب القيام بذلك قبل الاستماع على أي مقابس، ولن يؤثر ذلك على المقابس المفتوحة بالفعل. على سبيل المثال:

// إزالة تشفير CBC عتيق و تشفير قائم على تبادل مفاتيح RSA لأنها لا توفر سرية للأمام
tls.DEFAULT_CIPHERS +=
  ':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384' +
  ':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384' +
  ':!kRSA'

يمكن أيضًا استبدال الإعداد الافتراضي لكل عميل أو خادم باستخدام خيار ciphers من tls.createSecureContext()، والذي يتوفر أيضًا في tls.createServer()، tls.connect()، وعند إنشاء tls.TLSSocket جديدة.

يمكن أن تحتوي قائمة التشفير على مزيج من أسماء مجموعة تشفير TLSv1.3، تلك التي تبدأ بـ 'TLS_'، ومواصفات لتشفير TLSv1.2 وما دونه. تدعم تشفرات TLSv1.2 تنسيق مواصفات قديم، راجع وثائق تنسيق قائمة تشفير OpenSSL تنسيق قائمة التشفير للحصول على التفاصيل، لكن هذه المواصفات لا تنطبق على تشفرات TLSv1.3. لا يمكن تمكين مجموعات TLSv1.3 إلا عن طريق تضمين اسمها الكامل في قائمة التشفير. لا يمكن، على سبيل المثال، تمكينها أو تعطيلها باستخدام مواصفات TLSv1.2 القديمة 'EECDH' أو '!EECDH'.

على الرغم من الترتيب النسبي لمجموعات تشفير TLSv1.3 و TLSv1.2، فإن بروتوكول TLSv1.3 أكثر أمانًا بكثير من TLSv1.2، وسيتم دائمًا اختياره على TLSv1.2 إذا أشار المصافحة إلى أنه مدعوم، وإذا تم تمكين أي مجموعات تشفير TLSv1.3.

تم اختيار مجموعة التشفير الافتراضية المضمنة في Node.js بعناية لتعكس أفضل ممارسات الأمان الحالية وتخفيف المخاطر. يمكن أن يكون لتغيير مجموعة تشفير TLS الافتراضية تأثير كبير على أمان التطبيق. يجب استخدام مفتاح --tls-cipher-list وخيار ciphers فقط إذا لزم الأمر.

تعطي مجموعة التشفير الافتراضية الأفضلية لتشفير GCM لإعداد تشفير Chrome الحديث كما تعطي الأفضلية لتشفير ECDHE و DHE لسرية للأمام الكاملة، مع توفير بعض التوافق مع الإصدارات القديمة.

لا يمكن للعملاء القدامى الذين يعتمدون على تشفير RC4 أو DES غير الآمن والمنسوخ (مثل Internet Explorer 6) إكمال عملية المصافحة باستخدام التكوين الافتراضي. إذا كان يجب دعم هؤلاء العملاء، فقد توفر توصيات TLS مجموعة تشفير متوافقة. لمزيد من التفاصيل حول التنسيق، راجع وثائق تنسيق قائمة تشفير OpenSSL تنسيق قائمة التشفير.

هناك خمس مجموعات تشفير TLSv1.3 فقط:

• 'TLS_AES_256_GCM_SHA384'
• 'TLS_CHACHA20_POLY1305_SHA256'
• 'TLS_AES_128_GCM_SHA256'
• 'TLS_AES_128_CCM_SHA256'
• 'TLS_AES_128_CCM_8_SHA256'

تم تمكين المجموعات الثلاث الأولى افتراضيًا. يتم دعم مجموعتي CCM بواسطة TLSv1.3 لأنهما قد يكونان أكثر كفاءة على الأنظمة المحدودة، لكنهما غير ممكّنين افتراضيًا لأنهما يوفران أمانًا أقل.

مستوى أمان OpenSSL

تفرض مكتبة OpenSSL مستويات أمان للتحكم في الحد الأدنى المقبول لمستوى الأمان لعمليات التشفير. تتراوح مستويات أمان OpenSSL من 0 إلى 5، حيث يفرض كل مستوى متطلبات أمان أكثر صرامة. مستوى الأمان الافتراضي هو 1، وهو مناسب بشكل عام لمعظم التطبيقات الحديثة. ومع ذلك، تتطلب بعض الميزات والبروتوكولات القديمة، مثل TLSv1، مستوى أمان أقل (SECLEVEL=0) للعمل بشكل صحيح. لمزيد من المعلومات التفصيلية، يرجى الرجوع إلى وثائق OpenSSL حول مستويات الأمان.

ضبط مستويات الأمان

لتعديل مستوى الأمان في تطبيق Node.js الخاص بك، يمكنك تضمين @SECLEVEL=X ضمن سلسلة التشفير، حيث X هو مستوى الأمان المطلوب. على سبيل المثال، لضبط مستوى الأمان على 0 أثناء استخدام قائمة تشفير OpenSSL الافتراضية، يمكنك استخدام:

ESM

import { createServer, connect } from 'node:tls'
const port = 443

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('Client connected with protocol:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})

CJS

const { createServer, connect } = require('node:tls')
const port = 443

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('Client connected with protocol:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})

يضبط هذا النهج مستوى الأمان على 0، مما يسمح باستخدام الميزات القديمة مع الاستمرار في الاستفادة من تشفير OpenSSL الافتراضي.

استخدام

يمكنك أيضًا ضبط مستوى الأمان وتشفير من سطر الأوامر باستخدام --tls-cipher-list=DEFAULT@SECLEVEL=X كما هو موضح في تعديل مجموعة تشفير TLS الافتراضية. ومع ذلك، يُنصح عمومًا بعدم استخدام خيار سطر الأوامر لضبط التشفير، ويفضل تهيئة التشفير للسياقات الفردية ضمن رمز تطبيقك، حيث يوفر هذا النهج تحكمًا أدق ويقلل من خطر خفض مستوى الأمان عالميًا.

رموز أخطاء شهادة X509

قد تفشل العديد من الوظائف بسبب أخطاء الشهادة التي يبلغ عنها OpenSSL. في مثل هذه الحالة، توفر الوظيفة <خطأ> عبر وظيفتها المُستدعاة التي تحتوي على الخاصية code والتي يمكن أن تأخذ إحدى القيم التالية:

• 'UNABLE_TO_GET_ISSUER_CERT': تعذر الحصول على شهادة المُصدر.
• 'UNABLE_TO_GET_CRL': تعذر الحصول على قائمة إلغاء شهادة CRL.
• 'UNABLE_TO_DECRYPT_CERT_SIGNATURE': تعذر فك تشفير توقيع الشهادة.
• 'UNABLE_TO_DECRYPT_CRL_SIGNATURE': تعذر فك تشفير توقيع قائمة إلغاء الشهادة CRL.
• 'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY': تعذر فك تشفير المفتاح العام للمُصدر.
• 'CERT_SIGNATURE_FAILURE': فشل توقيع الشهادة.
• 'CRL_SIGNATURE_FAILURE': فشل توقيع قائمة إلغاء الشهادة CRL.
• 'CERT_NOT_YET_VALID': الشهادة غير صالحة بعد.
• 'CERT_HAS_EXPIRED': انتهت صلاحية الشهادة.
• 'CRL_NOT_YET_VALID': قائمة إلغاء الشهادة CRL غير صالحة بعد.
• 'CRL_HAS_EXPIRED': انتهت صلاحية قائمة إلغاء الشهادة CRL.
• 'ERROR_IN_CERT_NOT_BEFORE_FIELD': خطأ في تنسيق حقل notBefore في الشهادة.
• 'ERROR_IN_CERT_NOT_AFTER_FIELD': خطأ في تنسيق حقل notAfter في الشهادة.
• 'ERROR_IN_CRL_LAST_UPDATE_FIELD': خطأ في تنسيق حقل lastUpdate في قائمة إلغاء الشهادة CRL.
• 'ERROR_IN_CRL_NEXT_UPDATE_FIELD': خطأ في تنسيق حقل nextUpdate في قائمة إلغاء الشهادة CRL.
• 'OUT_OF_MEM': نفاد الذاكرة.
• 'DEPTH_ZERO_SELF_SIGNED_CERT': شهادة ذاتية التوقيع.
• 'SELF_SIGNED_CERT_IN_CHAIN': شهادة ذاتية التوقيع في سلسلة الشهادات.
• 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY': تعذر الحصول على شهادة المُصدر محليًا.
• 'UNABLE_TO_VERIFY_LEAF_SIGNATURE': تعذر التحقق من توقيع الشهادة الأولى.
• 'CERT_CHAIN_TOO_LONG': سلسلة الشهادات طويلة جدًا.
• 'CERT_REVOKED': تم إلغاء الشهادة.
• 'INVALID_CA': شهادة CA غير صالحة.
• 'PATH_LENGTH_EXCEEDED': تجاوز قيد طول المسار.
• 'INVALID_PURPOSE': الغرض من الشهادة غير مدعوم.
• 'CERT_UNTRUSTED': الشهادة غير موثوق بها.
• 'CERT_REJECTED': تم رفض الشهادة.
• 'HOSTNAME_MISMATCH': عدم تطابق اسم المضيف.

الصف: tls.CryptoStream

تم الإضافة في: v0.3.4

تم إهماله منذ: v0.11.3

[مستقر: 0 - مهمل]

مستقر: 0 استقرار: 0 - مهمل: استخدم tls.TLSSocket بدلاً من ذلك.

يمثل الصف tls.CryptoStream تدفقًا من البيانات المشفرة. تم إهمال هذا الصف ولا يجب استخدامه بعد الآن.

cryptoStream.bytesWritten

تم الإضافة في: v0.3.4

تم إهماله منذ: v0.11.3

تعيد الخاصية cryptoStream.bytesWritten العدد الإجمالي للبايتات المكتوبة في المقبس الأساسي بما في ذلك البايتات المطلوبة لتنفيذ بروتوكول TLS.

الصف: tls.SecurePair

تم الإضافة في: v0.3.2

تم إهماله منذ: v0.11.3

[مستقر: 0 - مهمل]

مستقر: 0 استقرار: 0 - مهمل: استخدم tls.TLSSocket بدلاً من ذلك.

تم إرجاعه بواسطة tls.createSecurePair().

الحدث: 'secure'

تم الإضافة في: v0.3.2

تم إهماله منذ: v0.11.3

يتم إصدار حدث 'secure' بواسطة كائن SecurePair بمجرد إنشاء اتصال آمن.

كما هو الحال مع التحقق من حدث الخادم 'secureConnection' ، يجب فحص pair.cleartext.authorized للتأكد من أن الشهادة المستخدمة معتمدة بشكل صحيح.

الصف: tls.Server

تم الإضافة في: v0.3.2

• يمتد: <net.Server>

يقبل الاتصالات المشفرة باستخدام TLS أو SSL.

الحدث: 'connection'

تم الإضافة في: v0.3.2

• socket <stream.Duplex>

يتم إصدار هذا الحدث عند إنشاء تدفق TCP جديد ، قبل بدء مصافحة TLS. يكون socket عادةً كائنًا من نوع net.Socket ولكنه لن يتلقى أحداثًا على عكس المقبس الذي تم إنشاؤه من حدث 'connection' الخاص بـ net.Server. عادةً ما لا يرغب المستخدمون في الوصول إلى هذا الحدث.

يمكن أيضًا إصدار هذا الحدث صراحةً من قبل المستخدمين لإدراج اتصالات في خادم TLS. في هذه الحالة ، يمكن تمرير أي تدفق Duplex.

حدث: 'keylog'

مضاف في: v12.3.0، v10.20.0

• line <Buffer> سطر نص ASCII، بتنسيق NSS SSLKEYLOGFILE.
• tlsSocket <tls.TLSSocket> مثيل tls.TLSSocket الذي تم إنشاؤه عليه.

يتم إصدار حدث keylog عند إنشاء مواد المفاتيح أو استلامها بواسطة اتصال بهذا الخادم (عادةً قبل اكتمال المصافحة، ولكن ليس بالضرورة). يمكن تخزين هذه المواد الرئيسية للتصحيح، حيث إنها تسمح بفك تشفير حركة مرور TLS التي تم التقاطها. قد يتم إصداره عدة مرات لكل مقبس.

مثال نموذجي للاستخدام هو إضافة الأسطر المستلمة إلى ملف نصي مشترك، والذي يستخدمه لاحقًا برنامج (مثل Wireshark) لفك تشفير حركة المرور:

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...') return // تسجيل مفاتيح عنوان IP معين فقط
  logFile.write(line)
})

حدث: 'newSession'

[السجل]

الإصدار	التغييرات
v0.11.12	الآن يتم دعم وسيطة callback.
v0.9.2	مضاف في: v0.9.2

يتم إصدار حدث 'newSession' عند إنشاء جلسة TLS جديدة. يمكن استخدام هذا لتخزين الجلسات في وحدة تخزين خارجية. يجب توفير البيانات إلى وظيفة الاستدعاء 'resumeSession'.

يتم تمرير ثلاث حجج إلى وظيفة الاستدعاء المُستمع عندما يتم استدعاؤها:

• sessionId <Buffer> معرف جلسة TLS
• sessionData <Buffer> بيانات جلسة TLS
• callback <Function> وظيفة استدعاء لا تأخذ أي حجج يجب استدعاؤها من أجل إرسال البيانات أو استلامها عبر الاتصال الآمن.

سيكون للاستماع إلى هذا الحدث تأثير فقط على الاتصالات التي تم إنشاؤها بعد إضافة مُستمع الحدث.

حدث: 'OCSPRequest'

مضاف في: v0.11.13

يتم إصدار حدث 'OCSPRequest' عندما يرسل العميل طلب حالة الشهادة. يتم تمرير ثلاث حجج إلى وظيفة الاستدعاء المُستمع عندما يتم استدعاؤها:

• certificate <Buffer> شهادة الخادم
• issuer <Buffer> شهادة المُصدر
• callback <Function> وظيفة استدعاء يجب استدعاؤها لتوفير نتائج طلب OCSP.

يمكن تحليل شهادة الخادم الحالية للحصول على عنوان URL لـ OCSP ومعرف الشهادة؛ بعد الحصول على استجابة OCSP، يتم استدعاء callback(null, resp)، حيث resp هو مثيل Buffer يحتوي على استجابة OCSP. كلا من certificate و issuer هما تمثيلات DER من Buffer للشهادات الأساسية وشهادات المُصدر. يمكن استخدام هذه للحصول على معرف شهادة OCSP وعنوان URL لنقطة نهاية OCSP.

بدلاً من ذلك، يمكن استدعاء callback(null, null)، مما يشير إلى عدم وجود استجابة OCSP.

سيؤدي استدعاء callback(err) إلى استدعاء socket.destroy(err).

التدفق النموذجي لطلب OCSP هو كما يلي:

يمكن أن يكون issuer فارغًا إذا كانت الشهادة ذاتية التوقيع أو إذا لم يكن المُصدر موجودًا في قائمة شهادات الجذر. (قد يتم توفير مُصدر عبر خيار ca عند إنشاء اتصال TLS.)

سيكون للاستماع إلى هذا الحدث تأثير فقط على الاتصالات التي تم إنشاؤها بعد إضافة مُستمع الحدث.

يمكن استخدام وحدة npm مثل asn1.js لتحليل الشهادات.

حدث: 'resumeSession'

مضاف في: v0.9.2

يُصدر حدث 'resumeSession' عندما يطلب العميل استئناف جلسة TLS سابقة. يتم تمرير استدعاء الوظيفة المُستمعة إلى حججتين عند استدعائها:

• sessionId <Buffer> معرف جلسة TLS
• callback <Function> دالة استدعاء تُستدعى عند استعادة الجلسة السابقة: callback([err[, sessionData]])
  • err <Error>
  • sessionData <Buffer>

يجب أن يقوم مُستمع الحدث بالبحث في التخزين الخارجي عن sessionData الذي تم حفظه بواسطة مُعالِج أحداث 'newSession' باستخدام sessionId المُعطى. إذا تم العثور عليه، فاتصل بـ callback(null, sessionData) لاستئناف الجلسة. إذا لم يتم العثور عليه، فلا يمكن استئناف الجلسة. يجب استدعاء callback() بدون sessionData حتى يمكن متابعة المصافحة وإنشاء جلسة جديدة. من الممكن استدعاء callback(err) لإنهاء الاتصال الوارد وتدمير المقبس.

سيكون للاستماع إلى هذا الحدث تأثير فقط على الاتصالات التي تم إنشاؤها بعد إضافة مُستمع الحدث.

يوضح ما يلي استئناف جلسة TLS:

const tlsSessionStore = {}
server.on('newSession', (id, data, cb) => {
  tlsSessionStore[id.toString('hex')] = data
  cb()
})
server.on('resumeSession', (id, cb) => {
  cb(null, tlsSessionStore[id.toString('hex')] || null)
})

حدث: 'secureConnection'

مضاف في: v0.3.2

يُصدر حدث 'secureConnection' بعد اكتمال عملية المصافحة لاتصال جديد بنجاح. يتم تمرير استدعاء الوظيفة المُستمعة إلى حجة واحدة عند استدعائها:

• tlsSocket <tls.TLSSocket> مقبس TLS المُنشأ.

خاصية tlsSocket.authorized هي قيمة من نوع boolean تشير إلى ما إذا تم التحقق من العميل بواسطة إحدى سلطات إصدار الشهادات المُقدمة للخادم. إذا كانت قيمة tlsSocket.authorized هي false، فسيتم تعيين socket.authorizationError لوصف كيفية فشل المصادقة. بناءً على إعدادات خادم TLS، قد لا تزال الاتصالات غير المصرح بها مُقبولة.

خاصية tlsSocket.alpnProtocol هي سلسلة تحتوي على بروتوكول ALPN المُحدد. عندما لا يكون لدى ALPN بروتوكول مُحدد لأن العميل أو الخادم لم يُرسلا امتداد ALPN، فإن قيمة tlsSocket.alpnProtocol تساوي false.

خاصية tlsSocket.servername هي سلسلة تحتوي على اسم الخادم المُطلوب عبر SNI.

الحدث: 'tlsClientError'

تم الإضافة في: v6.0.0

يُصدر حدث 'tlsClientError' عند حدوث خطأ قبل إنشاء اتصال آمن. يتم تمرير دعوتين للوظيفة المُستمعة عند استدعائها:

• exception <Error> كائن Error يصف الخطأ
• tlsSocket <tls.TLSSocket> مثيل tls.TLSSocket الذي نشأ منه الخطأ.

server.addContext(hostname, context)

تم الإضافة في: v0.5.3

• hostname <string> اسم مضيف SNI أو مُطابقة للأحرف المُبرّعة (مثل '*')
• context <Object> | <tls.SecureContext> كائن يحتوي على أي من الخصائص المُمكنة من وسيطات options في tls.createSecureContext() (مثل key, cert, ca, إلخ)، أو كائن سياق TLS تم إنشاؤه باستخدام tls.createSecureContext() نفسه.

تضيف طريقة server.addContext() سياقًا آمنًا سيتم استخدامه إذا تطابق اسم SNI لطلب العميل مع hostname المُعطى (أو المُطابقة للأحرف المُبرّعة).

عندما يكون هناك سياقات مُطابقة مُتعددة، يتم استخدام آخر واحد تم إضافته.

server.address()

تم الإضافة في: v0.6.0

• الإرجاع: <Object>

يُرجع العنوان المُرتبط، واسم عائلة العنوان، ومنفذ الخادم كما أفاد به نظام التشغيل. راجع net.Server.address() لمزيد من المعلومات.

server.close([callback])

تم الإضافة في: v0.3.2

• callback <Function> وظيفة مُستمعة سيتم تسجيلها للاستماع إلى حدث 'close' لمثيل الخادم.
• الإرجاع: <tls.Server>

توقف طريقة server.close() الخادم عن قبول اتصالات جديدة.

تعمل هذه الوظيفة بشكل غير مُزامن. سيتم إصدار حدث 'close' عندما لا يكون للخادم أي اتصالات مفتوحة أخرى.

server.getTicketKeys()

تم الإضافة في: v3.0.0

• الإرجاع: <Buffer> مُخزن مؤقت (Buffer) بحجم 48 بايت يحتوي على مفاتيح تذاكر الجلسة.

يرجع مفاتيح تذاكر الجلسة.

راجع استئناف الجلسة لمزيد من المعلومات.

server.listen()

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

server.setSecureContext(options)

تم الإضافة في: v11.0.0

• options <Object> كائن يحتوي على أي من الخصائص الممكنة من وسيطات tls.createSecureContext() options (مثل key, cert, ca, إلخ).

تقوم طريقة server.setSecureContext() باستبدال سياق الأمان لخادم موجود. لا تتأثر الاتصالات الحالية بالخادم.

server.setTicketKeys(keys)

تم الإضافة في: v3.0.0

• keys <Buffer> | <TypedArray> | <DataView> مُخزن مؤقت (Buffer) بحجم 48 بايت يحتوي على مفاتيح تذاكر الجلسة.

يحدد مفاتيح تذاكر الجلسة.

تكون التغييرات التي تطرأ على مفاتيح التذاكر فعالة فقط للاتصالات المستقبلية للخادم. ستستخدم الاتصالات الحالية أو المعلقة حاليًا المفاتيح السابقة.

راجع استئناف الجلسة لمزيد من المعلومات.

الصف: tls.TLSSocket

تم الإضافة في: v0.11.4

• يمتد: <net.Socket>

يُجري تشفيرًا شفافًا للبيانات المكتوبة وجميع المفاوضات اللازمة لـ TLS.

تُنفذ مثيلات tls.TLSSocket واجهة Stream ثنائية الاتجاه.

ستُرجع الطرق التي تُرجع بيانات وصفية لاتصال TLS (مثل tls.TLSSocket.getPeerCertificate()) البيانات فقط عندما يكون الاتصال مفتوحًا.

new tls.TLSSocket(socket[, options])

[السجل]

الإصدار	التغييرات
v12.2.0	خيار enableTrace مدعوم الآن.
v5.0.0	خيارات ALPN مدعومة الآن.
v0.11.4	تمت الإضافة في: v0.11.4

• socket <net.Socket> | <stream.Duplex> على جانب الخادم، أي دفق Duplex. على جانب العميل، أي مثيل من net.Socket (لدعم دفق Duplex العام على جانب العميل، يجب استخدام tls.connect()).
• options <Object>
  • enableTrace: انظر tls.createServer()
  • isServer: بروتوكول SSL/TLS غير متماثل، يجب أن تعرف TLSSockets ما إذا كانت ستتصرف كخادم أو عميل. إذا كانت true، فسيتم إنشاء مقبس TLS كخادم. الافتراضي: false.
  • server <net.Server> مثيل من net.Server.
  • requestCert: ما إذا كان يجب التحقق من صحة الند المُستقبِل بطلب شهادة. يطلب العملاء دائمًا شهادة خادم. قد تقوم الخوادم (isServer هي true) بتعيين requestCert على true لطلب شهادة عميل.
  • rejectUnauthorized: انظر tls.createServer()
  • ALPNProtocols: انظر tls.createServer()
  • SNICallback: انظر tls.createServer()
  • session <Buffer> مثيل Buffer يحتوي على جلسة TLS.
  • requestOCSP <boolean> إذا كانت true، فإنها تحدد أنه سيتم إضافة امتداد طلب حالة OCSP إلى طلب العميل وسيتم إصدار حدث 'OCSPResponse' على المقبس قبل إنشاء اتصال آمن.
  • secureContext: كائن سياق TLS تم إنشاؤه باستخدام tls.createSecureContext(). إذا لم يتم توفير secureContext، فسيتم إنشاء واحد عن طريق تمرير كائن options بأكمله إلى tls.createSecureContext().
  • ...: خيارات tls.createSecureContext() التي تُستخدم إذا كان خيار secureContext مفقودًا. خلاف ذلك، يتم تجاهلها.

إنشاء كائن tls.TLSSocket جديد من مقبس TCP موجود.

حدث: 'keylog'

مُضاف في: v12.3.0، v10.20.0

• line <Buffer> سطر من نص ASCII، بتنسيق NSS SSLKEYLOGFILE.

يُصدر حدث keylog على tls.TLSSocket عندما يتم إنشاء أو استقبال مادة مفتاح بواسطة المقبس. يمكن تخزين هذه مادة التشفير للتصحيح، حيث إنها تسمح بفك تشفير حركة مرور TLS المُلتقطة. قد يتم إصداره عدة مرات، قبل أو بعد اكتمال المصافحة.

مثال نموذجي للاستخدام هو إضافة الأسطر المستلمة إلى ملف نصي مشترك، والذي يُستخدم لاحقًا بواسطة برنامج (مثل Wireshark) لفك تشفير حركة المرور:

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
tlsSocket.on('keylog', line => logFile.write(line))

حدث: 'OCSPResponse'

مُضاف في: v0.11.13

يُصدر حدث 'OCSPResponse' إذا تم تعيين خيار requestOCSP عند إنشاء tls.TLSSocket وتم استلام استجابة OCSP. يتم تمرير مُناداة دالة الاستماع وسيطة واحدة عند استدعائها:

• response <Buffer> استجابة OCSP من الخادم

عادةً، تكون response كائنًا موقّعًا رقمياً من CA الخادم يحتوي على معلومات حول حالة إلغاء اعتماد شهادة الخادم.

حدث: 'secureConnect'

مُضاف في: v0.11.4

يُصدر حدث 'secureConnect' بعد اكتمال عملية المصافحة لاتصال جديد بنجاح. سيتم استدعاء مُناداة دالة الاستماع بغض النظر عما إذا كانت شهادة الخادم قد تم اعتمادها أم لا. تقع على عاتق العميل مسؤولية التحقق من خاصية tlsSocket.authorized لتحديد ما إذا كانت شهادة الخادم موقّعة من قبل أحد CAs المحددة. إذا كانت tlsSocket.authorized === false، فيمكن العثور على الخطأ من خلال فحص خاصية tlsSocket.authorizationError. إذا تم استخدام ALPN، فيمكن التحقق من خاصية tlsSocket.alpnProtocol لتحديد البروتوكول المُتفاوض عليه.

لا يتم إصدار حدث 'secureConnect' عند إنشاء <tls.TLSSocket> باستخدام مُنشئ new tls.TLSSocket().

حدث: 'session'

تم الإضافة في: v11.10.0

• session <Buffer>

يتم إصدار حدث 'session' على عميل tls.TLSSocket عندما يتوفر جلسة جديدة أو تذكرة TLS. قد يكون هذا قبل اكتمال المصافحة أو بعدها، اعتمادًا على إصدار بروتوكول TLS الذي تم التفاوض عليه. لا يتم إصدار الحدث على الخادم، أو إذا لم يتم إنشاء جلسة جديدة، على سبيل المثال، عندما تم استئناف الاتصال. بالنسبة لبعض إصدارات بروتوكول TLS، قد يتم إصدار الحدث عدة مرات، وفي هذه الحالة، يمكن استخدام جميع الجلسات للاستئناف.

على العميل، يمكن توفير session إلى خيار session الخاص بـ tls.connect() لاستئناف الاتصال.

راجع استئناف الجلسة لمزيد من المعلومات.

بالنسبة إلى TLSv1.2 وما دون، يمكن استدعاء tls.TLSSocket.getSession() بمجرد اكتمال المصافحة. بالنسبة إلى TLSv1.3، يُسمح فقط باستئناف القائم على التذاكر بواسطة البروتوكول، ويتم إرسال تذاكر متعددة، ولا يتم إرسال التذاكر إلا بعد اكتمال المصافحة. لذلك، من الضروري انتظار حدث 'session' للحصول على جلسة قابلة للاستئناف. يجب على التطبيقات استخدام حدث 'session' بدلاً من getSession() لضمان عملها مع جميع إصدارات TLS. يجب على التطبيقات التي تتوقع الحصول على جلسة واحدة أو استخدامها فقط الاستماع إلى هذا الحدث مرة واحدة فقط:

tlsSocket.once('session', session => {
  // يمكن استخدام الجلسة فورًا أو لاحقًا.
  tls.connect({
    session: session,
    // خيارات الاتصال الأخرى...
  })
})

tlsSocket.address()

[السجل]

الإصدار	التغييرات
v18.4.0	الآن خاصية family تُرجع سلسلة نصية بدلاً من رقم.
v18.0.0	الآن خاصية family تُرجع رقمًا بدلاً من سلسلة نصية.
v0.11.4	تمت الإضافة في: v0.11.4

• الإرجاع: <Object>

يُرجع عنوان address المرتبط، واسم عائلة العنوان family، وport للمقبس الأساسي كما هو مُبلغ عنه بواسطة نظام التشغيل: { port: 12346, family: 'IPv4', address: '127.0.0.1' }.

tlsSocket.authorizationError

مضاف في: v0.11.4

يُرجع سبب عدم التحقق من شهادة النظير. يتم تعيين هذه الخاصية فقط عندما يكون tlsSocket.authorized === false.

tlsSocket.authorized

مضاف في: v0.11.4

• <boolean>

هذه الخاصية تساوي true إذا تم توقيع شهادة النظير بواسطة إحدى سلطات الإصدار المحددة عند إنشاء مثيل tls.TLSSocket، وإلا فهي تساوي false.

tlsSocket.disableRenegotiation()

مضاف في: v8.4.0

يعطل إعادة التفاوض TLS لهذا المثيل TLSSocket. بمجرد استدعائه، ستؤدي محاولات إعادة التفاوض إلى تشغيل حدث 'error' على TLSSocket.

tlsSocket.enableTrace()

مضاف في: v12.2.0

عند تمكينه، يتم كتابة معلومات تتبع حزمة TLS إلى stderr. يمكن استخدام هذا للتحقق من أخطاء اتصال TLS.

يتطابق تنسيق الإخراج مع إخراج openssl s_client -trace أو openssl s_server -trace. بينما يتم إنتاجه بواسطة دالة SSL_trace() الخاصة بـ OpenSSL، إلا أن التنسيق غير موثق، ويمكن أن يتغير دون إشعار، ولا ينبغي الاعتماد عليه.

tlsSocket.encrypted

مضاف في: v0.11.4

يعيد دائمًا true. يمكن استخدام هذا للتمييز بين مقابس TLS ومثيلات net.Socket العادية.

tlsSocket.exportKeyingMaterial(length, label[, context])

مضاف في: v13.10.0، v12.17.0

• length <number> عدد البايتات التي سيتم استرجاعها من مادة التشفير
• label <string> تسمية خاصة بالتطبيق، عادةً ما تكون قيمة من سجل تسميات المُصدر IANA.
• context <Buffer> توفير سياق اختياري.
• يعيد: <Buffer> البايتات المطلوبة من مادة التشفير

تُستخدم مادة التشفير للتحقق من الصحة لمنع أنواع مختلفة من الهجمات في بروتوكولات الشبكة، على سبيل المثال في مواصفات IEEE 802.1X.

مثال

const keyingMaterial = tlsSocket.exportKeyingMaterial(128, 'client finished')

/*
مثال على قيمة keyingMaterial المُعادة:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
*/

راجع وثائق OpenSSL SSL_export_keying_material لمزيد من المعلومات.

tlsSocket.getCertificate()

مضاف في: v11.2.0

• مُخرجات: <Object>

يُعيد كائنًا يمثل الشهادة المحلية. يحتوي الكائن المُرجَع على بعض الخصائص التي تتوافق مع حقول الشهادة.

انظر إلى tls.TLSSocket.getPeerCertificate() للحصول على مثال على بنية الشهادة.

إذا لم تكن هناك شهادة محلية، فسيتم إرجاع كائن فارغ. إذا تم تدمير المقبس، فسيتم إرجاع null.

tlsSocket.getCipher()

[السجل]

الإصدار	التغييرات
v13.4.0, v12.16.0	إرجاع اسم تشفير IETF كـ standardName.
v12.0.0	إرجاع الحد الأدنى لإصدار التشفير، بدلاً من سلسلة ثابتة ('TLSv1/SSLv3').
v0.11.4	مضاف في: v0.11.4

• مُخرجات: <Object>
  • name <string> اسم OpenSSL لمجموعة التشفير.
  • standardName <string> اسم IETF لمجموعة التشفير.
  • version <string> الحد الأدنى لإصدار بروتوكول TLS المدعوم بواسطة مجموعة التشفير هذه. للحصول على بروتوكول التفاوض الفعلي، راجع tls.TLSSocket.getProtocol().

يُعيد كائنًا يحتوي على معلومات حول مجموعة التشفير المُتفاوض عليها.

على سبيل المثال، بروتوكول TLSv1.2 مع تشفير AES256-SHA:

{
  "name": "AES256-SHA",
  "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
  "version": "SSLv3"
}

انظر إلى SSL_CIPHER_get_name لمزيد من المعلومات.

tlsSocket.getEphemeralKeyInfo()

مضاف في: v5.0.0

• مُخرجات: <Object>

يُعيد كائنًا يمثل نوع واسم وحجم معلمة تبادل مفتاح مؤقت في سرية التوجيه الأمامي المثالي على اتصال العميل. يُعيد كائنًا فارغًا عندما لا يكون تبادل المفتاح مؤقتًا. نظرًا لأن هذا مدعوم فقط على مقبس العميل؛ يتم إرجاع null إذا تم استدعاءه على مقبس الخادم. الأنواع المدعومة هي 'DH' و 'ECDH'. تتوفر خاصية name فقط عندما يكون النوع 'ECDH'.

على سبيل المثال: { type: 'ECDH', name: 'prime256v1', size: 256 }.

tlsSocket.getFinished()

مضاف في: v9.9.0

• قيم الإرجاع: <Buffer> | <undefined> أحدث رسالة Finished تم إرسالها إلى المقبس كجزء من عملية مصافحة SSL/TLS، أو undefined إذا لم يتم إرسال أي رسالة Finished حتى الآن.

بما أن رسائل Finished عبارة عن ملخصات رسائل لمصافحة كاملة (بمجموع 192 بت لـ TLS 1.0 وأكثر لـ SSL 3.0)، فيمكن استخدامها لإجراءات المصادقة الخارجية عندما لا تكون المصادقة المقدمة بواسطة SSL/TLS مرغوبة أو غير كافية.

يتوافق مع روتين SSL_get_finished في OpenSSL ويمكن استخدامه لتنفيذ ربط قناة tls-unique من RFC 5929.

tlsSocket.getPeerCertificate([detailed])

مضاف في: v0.11.4

• detailed <boolean> تضمين سلسلة الشهادة الكاملة إذا كانت true، وإلا فقم بتضمين شهادة النظير فقط.
• قيم الإرجاع: <Object> كائن شهادة.

يرجع كائنًا يمثل شهادة النظير. إذا لم يقدم النظير شهادة، فسيتم إرجاع كائن فارغ. إذا تم تدمير المقبس، فسيتم إرجاع null.

إذا تم طلب سلسلة الشهادة الكاملة، فستتضمن كل شهادة خاصية issuerCertificate تحتوي على كائن يمثل شهادة المُصدر.

كائن الشهادة

[السجل]

الإصدار	التغييرات
v19.1.0, v18.13.0	إضافة خاصية "ca".
v17.2.0, v16.14.0	إضافة fingerprint512.
v11.4.0	دعم معلومات المفتاح العام للمنحنى الإهليلجي.

يحتوي كائن الشهادة على خصائص تتوافق مع حقول الشهادة.

• ca <boolean> true إذا كانت هيئة إصدار الشهادات (CA)، false خلاف ذلك.
• raw <Buffer> بيانات الشهادة المُشفّرة X.509 المُشفّرة بواسطة DER.
• subject <Object> موضوع الشهادة، موصوف من حيث الدولة (C)، والولاية أو المقاطعة (ST)، والموقع (L)، والمنظمة (O)، ووحدة المنظمة (OU)، والاسم الشائع (CN). عادةً ما يكون الاسم الشائع اسم DNS مع شهادات TLS. مثال: {C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}.
• issuer <Object> مُصدر الشهادة، موصوف بنفس المصطلحات مثل subject.
• valid_from <string> تاريخ ووقت بدء صلاحية الشهادة.
• valid_to <string> تاريخ ووقت انتهاء صلاحية الشهادة.
• serialNumber <string> الرقم التسلسلي للشهادة، كسلسلة سداسية عشرية. مثال: 'B9B0D332A1AA5635'.
• fingerprint <string> ملخص SHA-1 للشهادة المشفرة بواسطة DER. يتم إرجاعه كسلسلة سداسية عشرية مفصولة بـ : . مثال: '2A:7A:C2:DD:...'.
• fingerprint256 <string> ملخص SHA-256 للشهادة المشفرة بواسطة DER. يتم إرجاعه كسلسلة سداسية عشرية مفصولة بـ : . مثال: '2A:7A:C2:DD:...'.
• fingerprint512 <string> ملخص SHA-512 للشهادة المشفرة بواسطة DER. يتم إرجاعه كسلسلة سداسية عشرية مفصولة بـ : . مثال: '2A:7A:C2:DD:...'.
• ext_key_usage <Array> (اختياري) الاستخدام الموسّع للمفتاح، وهو مجموعة من OID.
• subjectaltname <string> (اختياري) سلسلة تحتوي على أسماء مُدمجة للموضوع، بديل لأسماء subject.
• infoAccess <Array> (اختياري) مصفوفة تصف AuthorityInfoAccess، المُستخدمة مع OCSP.
• issuerCertificate <Object> (اختياري) كائن شهادة المُصدر. بالنسبة للشهادات المُوقّعة ذاتيًا، قد يكون هذا مرجعًا دائريًا.

قد تحتوي الشهادة على معلومات حول المفتاح العام، حسب نوع المفتاح.

بالنسبة لمفاتيح RSA، قد يتم تعريف الخصائص التالية:

• bits <number> حجم بت RSA. مثال: 1024.
• exponent <string> مُؤشر RSA، كسلسلة في تدوين رقم سداسي عشري. مثال: '0x010001'.
• modulus <string> معامل RSA، كسلسلة سداسية عشرية. مثال: 'B56CE45CB7...'.
• pubkey <Buffer> المفتاح العام.

بالنسبة لمفاتيح EC، قد يتم تعريف الخصائص التالية:

• pubkey <Buffer> المفتاح العام.
• bits <number> حجم المفتاح بالبت. مثال: 256.
• asn1Curve <string> (اختياري) اسم ASN.1 لـ OID للمنحنى الإهليلجي. يتم تحديد المنحنيات المعروفة بواسطة OID. على الرغم من أنه أمر غير معتاد، إلا أنه من الممكن تحديد المنحنى من خلال خصائصه الرياضية، وفي هذه الحالة لن يكون له OID. مثال: 'prime256v1'.
• nistCurve <string> (اختياري) اسم NIST للمنحنى الإهليلجي، إذا كان لديه واحد (لم يتم تعيين أسماء لجميع المنحنيات المعروفة بواسطة NIST). مثال: 'P-256'.

مثال شهادة:

{ subject:
   { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
     CN: '*.nodejs.org' },
  issuer:
   { C: 'GB',
     ST: 'Greater Manchester',
     L: 'Salford',
     O: 'COMODO CA Limited',
     CN: 'COMODO RSA Domain Validation Secure Server CA' },
  subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
  infoAccess:
   { 'CA Issuers - URI':
      [ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
     'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
  modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
  exponent: '0x10001',
  pubkey: <Buffer ... >,
  valid_from: 'Aug 14 00:00:00 2017 GMT',
  valid_to: 'Nov 20 23:59:59 2019 GMT',
  fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
  fingerprint256: '69:AE:1A:6A:D4:3D:C6:C1:1B:EA:C6:23:DE:BA:2A:14:62:62:93:5C:7A:EA:06:41:9B:0B:BC:87:CE:48:4E:02',
  fingerprint512: '19:2B:3E:C3:B3:5B:32:E8:AE:BB:78:97:27:E4:BA:6C:39:C9:92:79:4F:31:46:39:E2:70:E5:5F:89:42:17:C9:E8:64:CA:FF:BB:72:56:73:6E:28:8A:92:7E:A3:2A:15:8B:C2:E0:45:CA:C3:BC:EA:40:52:EC:CA:A2:68:CB:32',
  ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
  serialNumber: '66593D57F20CBC573E433381B5FEC280',
  raw: <Buffer ... > }

tlsSocket.getPeerFinished()

تم الإضافة في: v9.9.0

• القيمة المُرجعة: <Buffer> | <undefined> أحدث رسالة Finished المُتوقعة أو التي تم استلامها بالفعل من المقبس كجزء من عملية مصافحة SSL/TLS، أو undefined إذا لم تكن هناك رسالة Finished حتى الآن.

بما أن رسائل Finished هي تلخيصات رسائل عملية المصافحة الكاملة (بإجمالي 192 بت لـ TLS 1.0 وأكثر لـ SSL 3.0)، فيمكن استخدامها لإجراءات المصادقة الخارجية عندما لا تكون المصادقة المقدمة بواسطة SSL/TLS مرغوبة أو غير كافية.

يتوافق مع روتين SSL_get_peer_finished في OpenSSL ويمكن استخدامه لتنفيذ ربط القناة tls-unique من RFC 5929.

tlsSocket.getPeerX509Certificate()

تم الإضافة في: v15.9.0

• القيمة المُرجعة: <X509Certificate>

يُرجع شهادة النظير ككائن <X509Certificate>.

إذا لم تكن هناك شهادة نظير، أو تم تدمير المقبس، فسيتم إرجاع undefined.

tlsSocket.getProtocol()

تم الإضافة في: v5.7.0

• القيمة المُرجعة: <string> | <null>

يُرجع سلسلة تحتوي على إصدار بروتوكول SSL/TLS المُتفاوض عليه للاتصال الحالي. سيتم إرجاع القيمة 'unknown' للمقابس المُتصلة التي لم تُكمل عملية المصافحة. سيتم إرجاع القيمة null لمقابس الخادم أو مقابس العميل المُقطعة.

إصدارات البروتوكول هي:

• 'SSLv3'
• 'TLSv1'
• 'TLSv1.1'
• 'TLSv1.2'
• 'TLSv1.3'

راجع وثائق OpenSSL SSL_get_version لمزيد من المعلومات.

tlsSocket.getSession()

تم الإضافة في: v0.11.4

• <Buffer>

يُرجع بيانات جلسة TLS أو undefined إذا لم يتم التفاوض على أي جلسة. على العميل، يمكن توفير البيانات إلى خيار session من tls.connect() لاستئناف الاتصال. على الخادم، قد يكون مفيدًا للتصحيح.

راجع استئناف الجلسة لمزيد من المعلومات.

ملاحظة: تعمل getSession() فقط لـ TLSv1.2 وما دون. بالنسبة إلى TLSv1.3، يجب على التطبيقات استخدام حدث 'session' (يعمل أيضًا مع TLSv1.2 وما دون).

tlsSocket.getSharedSigalgs()

مضاف في: v12.11.0

• مُخرجات: <Array> قائمة بخوارزميات التوقيع المشتركة بين الخادم والعميل بترتيب تنازلي حسب الأفضلية.

راجع SSL_get_shared_sigalgs لمزيد من المعلومات.

tlsSocket.getTLSTicket()

مضاف في: v0.11.4

• <Buffer>

بالنسبة للعميل، يُرجع تذكرة جلسة TLS إذا كانت متوفرة، أو undefined. بالنسبة للخادم، يُرجع دائمًا undefined.

قد يكون مفيدًا في تصحيح الأخطاء.

راجع استئناف الجلسة لمزيد من المعلومات.

tlsSocket.getX509Certificate()

مضاف في: v15.9.0

• مُخرجات: <X509Certificate>

يُرجع الشهادة المحلية ككائن <X509Certificate>.

إذا لم تكن هناك شهادة محلية، أو تم تدمير المقبس، فسيتم إرجاع undefined.

tlsSocket.isSessionReused()

مضاف في: v0.5.6

• مُخرجات: <boolean> true إذا تم إعادة استخدام الجلسة، false بخلاف ذلك.

راجع استئناف الجلسة لمزيد من المعلومات.

tlsSocket.localAddress

مضاف في: v0.11.4

• <string>

يُرجع التمثيل النصي لعنوان IP المحلي.

tlsSocket.localPort

مضاف في: v0.11.4

• <integer>

يُرجع التمثيل العددي للمنفذ المحلي.

tlsSocket.remoteAddress

مضاف في: v0.11.4

• <string>

يُرجع التمثيل النصي لعنوان IP البعيد. على سبيل المثال، '74.125.127.100' أو '2001:4860:a005::68'.

tlsSocket.remoteFamily

تم الإضافة في: v0.11.4

• <string>

يُرجِع التمثيل النصي لعائلة عنوان IP البعيد. 'IPv4' أو 'IPv6'.

tlsSocket.remotePort

تم الإضافة في: v0.11.4

• <integer>

يُرجِع التمثيل العددي للمنفذ البعيد. على سبيل المثال، 443.

tlsSocket.renegotiate(options, callback)

[السجل]

الإصدار	التغييرات
v18.0.0	تمرير دالة مُعامل خاطئة إلى وسيطة callback يُثير الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v0.11.8	تم الإضافة في: v0.11.8

• options <Object>

  • rejectUnauthorized <boolean> إذا لم تكن false، فسيتم التحقق من شهادة الخادم مقابل قائمة مُقدّمة من سلطات التصديق. يتم إرسال حدث 'error' إذا فشل التحقق؛ يحتوي err.code على رمز خطأ OpenSSL. الافتراضي: true.
  • requestCert

• callback <Function> إذا أعادت renegotiate() قيمة true، فسيتم إرفاق دالة المُعامل مرة واحدة بحدث 'secure'. إذا أعادت renegotiate() قيمة false، فسيتم استدعاء callback في التكرار التالي بخطأ، ما لم يتم تدمير tlsSocket، وفي هذه الحالة لن يتم استدعاء callback على الإطلاق.

• المُرجَع: <boolean> true إذا تم بدء إعادة التفاوض، false بخلاف ذلك.

تُبدأ طريقة tlsSocket.renegotiate() عملية إعادة تفاوض TLS. عند الإكمال، سيتم تمرير دالة المُعامل وسيطة واحدة إما خطأ (Error) (إذا فشل الطلب) أو null.

يمكن استخدام هذه الطريقة لطلب شهادة النظير بعد إنشاء الاتصال الآمن.

عند التشغيل كخادم، سيتم تدمير المقبس بخطأ بعد انتهاء مهلة handshakeTimeout.

بالنسبة إلى TLSv1.3، لا يمكن بدء إعادة التفاوض، فهي غير مدعومة من قبل البروتوكول.

tlsSocket.setKeyCert(context)

تم الإضافة في: v22.5.0، v20.17.0

• context <Object> | <tls.SecureContext> كائن يحتوي على الأقل على خاصيتي key و cert من خيارات tls.createSecureContext() ، أو كائن سياق TLS تم إنشاؤه باستخدام tls.createSecureContext() نفسه.

تعيّن طريقة tlsSocket.setKeyCert() المفتاح الخاص والشهادة لاستخدامها مع المقبس. هذا مفيد بشكل أساسي إذا كنت ترغب في تحديد شهادة خادم من ALPNCallback لخادم TLS.

tlsSocket.setMaxSendFragment(size)

تم الإضافة في: v0.11.11

• size <number> الحد الأقصى لحجم جزء TLS. القيمة القصوى هي 16384. افتراضيًا: 16384.
• القيمة المُرجعه: <boolean>

تعيّن طريقة tlsSocket.setMaxSendFragment() الحد الأقصى لحجم جزء TLS. تُرجع true إذا نجح تعيين الحد ؛ false بخلاف ذلك.

تُقلل أحجام الأجزاء الأصغر من زمن الوصول المؤجل للتخزين المؤقت على العميل: يتم تخزين الأجزاء الأكبر بواسطة طبقة TLS حتى يتم استلام الجزء بالكامل والتحقق من سلامته ؛ قد تمتد الأجزاء الكبيرة على عدة رحلات ذهابًا وإيابًا وقد يتأخر معالجتها بسبب فقدان الحزم أو إعادة ترتيبها. ومع ذلك ، فإن الأجزاء الأصغر تضيف بايتات إطار TLS إضافية وعلوًا في وحدة المعالجة المركزية ، مما قد يقلل من إجمالي إنتاجية الخادم.

tls.checkServerIdentity(hostname, cert)

[السجل]

الإصدار	التغييرات
v17.3.1، v16.13.2، v14.18.3، v12.22.9	تم تعطيل دعم أسماء البدائل التابعة لـ uniformResourceIdentifier استجابةً لـ CVE-2021-44531.
v0.8.4	تم الإضافة في: v0.8.4

• hostname <string> اسم المضيف أو عنوان IP للتحقق من الشهادة ضده.
• cert <Object> كائن شهادة يمثل شهادة النظير.
• القيمة المُرجعه: <Error> | <undefined>

يتحقق من أن الشهادة cert صادرة لـ hostname.

يُرجع كائن <Error> ، ويملؤه بـ reason و host و cert في حالة الفشل. في حالة النجاح ، يُرجع <undefined>.

تهدف هذه الوظيفة إلى استخدامها مع خيار checkServerIdentity الذي يمكن تمريره إلى tls.connect() وبالتالي تعمل على كائن شهادة. لأغراض أخرى ، ضع في اعتبارك استخدام x509.checkHost() بدلاً من ذلك.

يمكن الكتابة فوق هذه الوظيفة عن طريق توفير وظيفة بديلة كخيار options.checkServerIdentity الذي يتم تمريره إلى tls.connect (). يمكن لوظيفة الكتابة فوق أن تستدعي tls.checkServerIdentity() بالطبع ، لزيادة عمليات التحقق التي تتم مع التحقق الإضافي.

لا يتم استدعاء هذه الوظيفة إلا إذا مرت الشهادة بجميع عمليات التحقق الأخرى ، مثل إصدارها بواسطة CA موثوق (options.ca).

قبلت إصدارات Node.js السابقة بشكل غير صحيح شهادات لاسم مضيف معين إذا كان هناك اسم بديل تابع لـ uniformResourceIdentifier مطابق موجود (انظر CVE-2021-44531). يمكن للتطبيقات التي ترغب في قبول أسماء البدائل التابعة لـ uniformResourceIdentifier استخدام دالة مخصصة options.checkServerIdentity تقوم بتنفيذ السلوك المطلوب.

tls.connect(options[, callback])

[History]

الإصدار	التغييرات
v15.1.0, v14.18.0	تمت إضافة خيار onread.
v14.1.0, v13.14.0	أصبح خيار highWaterMark مقبولًا الآن.
v13.6.0, v12.16.0	أصبح خيار pskCallback مدعومًا الآن.
v12.9.0	دعم خيار allowHalfOpen.
v12.4.0	أصبح خيار hints مدعومًا الآن.
v12.2.0	أصبح خيار enableTrace مدعومًا الآن.
v11.8.0, v10.16.0	أصبح خيار timeout مدعومًا الآن.
v8.0.0	أصبح خيار lookup مدعومًا الآن.
v8.0.0	يمكن أن يكون خيار ALPNProtocols عبارة عن TypedArray أو DataView الآن.
v5.0.0	خيارات ALPN مدعومة الآن.
v5.3.0, v4.7.0	أصبح خيار secureContext مدعومًا الآن.
v0.11.3	تمت الإضافة في: v0.11.3

• options <Object>

  • enableTrace: انظر tls.createServer()
  • host <string> المضيف الذي يجب أن يتصل به العميل. الافتراضي: 'localhost'.
  • port <number> المنفذ الذي يجب أن يتصل به العميل.
  • path <string> إنشاء اتصال بمقبس يونكس إلى المسار. إذا تم تحديد هذا الخيار، فسيتم تجاهل host و port.
  • socket <stream.Duplex> إنشاء اتصال آمن على مقبس معين بدلاً من إنشاء مقبس جديد. عادةً ما يكون هذا مثالًا على net.Socket، ولكن يُسمح بأي دفق Duplex. إذا تم تحديد هذا الخيار، فسيتم تجاهل path و host و port، باستثناء التحقق من صحة الشهادة. عادةً ما يكون المقبس متصلاً بالفعل عند تمريره إلى tls.connect()، لكن يمكن توصيله لاحقًا. مسؤولية المستخدم هي توصيل/فصل/تدمير socket؛ لن يتسبب استدعاء tls.connect() في استدعاء net.connect().
  • allowHalfOpen <boolean> إذا تم تعيينه على false، فسوف ينهي المقبس تلقائيًا الجانب القابل للكتابة عندما ينتهي الجانب القابل للقراءة. إذا تم تعيين خيار socket، فلن يكون لهذا الخيار أي تأثير. راجع خيار allowHalfOpen الخاص بـ net.Socket للحصول على التفاصيل. الافتراضي: false.
  • rejectUnauthorized <boolean> إذا لم يكن false، فسيتم التحقق من شهادة الخادم مقابل قائمة سلطات الإصدار الموثوقة المقدمة. يتم إصدار حدث 'error' إذا فشل التحقق؛ يحتوي err.code على رمز خطأ OpenSSL. الافتراضي: true.
  • pskCallback <Function> للمفاوضة TLS-PSK، راجع مفاتيح مسبقة المشاركة.
  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> مصفوفة من السلاسل، أو Buffers، أو TypedArrays، أو DataViews، أو Buffer واحد، أو TypedArray، أو DataView تحتوي على بروتوكولات ALPN المدعومة. يجب أن يكون لدى Buffers التنسيق [len][name][len][name]... على سبيل المثال '\x08http/1.1\x08http/1.0'، حيث أن بايت len هو طول اسم بروتوكول التالي. عادةً ما يكون تمرير مصفوفة أبسط بكثير، على سبيل المثال ['http/1.1', 'http/1.0']. البروتوكولات في وقت سابق في القائمة لها أولوية أعلى من تلك التي في وقت لاحق.
  • servername: <string> اسم الخادم لامتداد SNI (مؤشر اسم الخادم) TLS. وهو اسم المضيف الذي يتم الاتصال به، ويجب أن يكون اسم مضيف، وليس عنوان IP. يمكن استخدامه بواسطة خادم متعدد المنازل لاختيار الشهادة الصحيحة لتقديمها إلى العميل، راجع خيار SNICallback إلى tls.createServer().
  • checkServerIdentity(servername, cert) <Function> دالة استدعاء قابلة للاستخدام (بدلاً من دالة tls.checkServerIdentity() المضمنة) عند التحقق من اسم مضيف الخادم (أو servername المُعطى عند تعيينه صراحةً) مقابل الشهادة. يجب أن تُرجع <Error> إذا فشل التحقق. يجب أن تُرجع الطريقة undefined إذا تم التحقق من servername و cert.
  • session <Buffer> مثيل Buffer، يحتوي على جلسة TLS.
  • minDHSize <number> الحد الأدنى لحجم معلمة DH بالبتات لقبول اتصال TLS. عندما يقدم الخادم معلمة DH بحجم أقل من minDHSize، يتم تدمير اتصال TLS ويتم طرح خطأ. الافتراضي: 1024.
  • highWaterMark: <number> متسق مع معلمة الدفق القابل للقراءة highWaterMark. الافتراضي: 16 * 1024.
  • secureContext: كائن سياق TLS تم إنشاؤه باستخدام tls.createSecureContext(). إذا لم يتم توفير secureContext، فسيتم إنشاء واحد عن طريق تمرير كائن options بأكمله إلى tls.createSecureContext().
  • onread <Object> إذا كان خيار socket مفقودًا، فسيتم تخزين البيانات الواردة في buffer واحد ومرورها إلى callback المُعطى عند وصول البيانات على المقبس، وإلا سيتم تجاهل الخيار. راجع خيار onread الخاص بـ net.Socket للحصول على التفاصيل.
  • ...: خيارات tls.createSecureContext() التي يتم استخدامها إذا كان خيار secureContext مفقودًا، وإلا سيتم تجاهلها.
  • ...: أي خيار socket.connect() لم يتم إدراجه بالفعل.

• callback <Function>

• الإرجاع: <tls.TLSSocket>

سيتم إضافة دالة callback، إذا تم تحديدها، كمستمع لحدث 'secureConnect'.

tls.connect() تُرجع كائن tls.TLSSocket.

على عكس واجهة برمجة التطبيقات https، لا تُمكن tls.connect() من امتداد SNI (مؤشر اسم الخادم) افتراضيًا، مما قد يتسبب في قيام بعض الخوادم بإرجاع شهادة غير صحيحة أو رفض الاتصال تمامًا. لتمكين SNI، قم بتعيين خيار servername بالإضافة إلى host.

يوضح ما يلي عميلًا لمثال خادم الصدى من tls.createServer():

ESM

// يفترض خادم صدى يستمع على المنفذ 8000.
import { connect } from 'node:tls'
import { readFileSync } from 'node:fs'
import { stdin } from 'node:process'

const options = {
  // ضروري فقط إذا كان الخادم يتطلب مصادقة شهادة العميل.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // ضروري فقط إذا كان الخادم يستخدم شهادة ذاتية التوقيع.
  ca: [readFileSync('server-cert.pem')],

  // ضروري فقط إذا لم تكن شهادة الخادم لـ "localhost".
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('client connected', socket.authorized ? 'authorized' : 'unauthorized')
  stdin.pipe(socket)
  stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('server ends connection')
})

CJS

// يفترض خادم صدى يستمع على المنفذ 8000.
const { connect } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  // ضروري فقط إذا كان الخادم يتطلب مصادقة شهادة العميل.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // ضروري فقط إذا كان الخادم يستخدم شهادة ذاتية التوقيع.
  ca: [readFileSync('server-cert.pem')],

  // ضروري فقط إذا لم تكن شهادة الخادم لـ "localhost".
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('client connected', socket.authorized ? 'authorized' : 'unauthorized')
  process.stdin.pipe(socket)
  process.stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('server ends connection')
})

لتوليد الشهادة والمفتاح لهذا المثال، قم بتشغيل:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout client-key.pem -out client-cert.pem

ثم، لتوليد شهادة server-cert.pem لهذا المثال، قم بتشغيل:

openssl pkcs12 -certpbe AES-256-CBC -export -out server-cert.pem \
  -inkey client-key.pem -in client-cert.pem

tls.connect(path[, options][, callback])

مضاف في: v0.11.3

• path <string> قيمة افتراضية لـ options.path.
• options <Object> انظر tls.connect().
• callback <Function> انظر tls.connect().
• قيمة الإرجاع: <tls.TLSSocket>

مثل tls.connect() إلا أن path يمكن توفيره كوسيطة بدلاً من خيار.

سيُعطى الأولوية لخيار المسار، إذا تم تحديده، على وسيطة المسار.

tls.connect(port[, host][, options][, callback])

مضاف في: v0.11.3

• port <number> قيمة افتراضية لـ options.port.
• host <string> قيمة افتراضية لـ options.host.
• options <Object> انظر tls.connect().
• callback <Function> انظر tls.connect().
• قيمة الإرجاع: <tls.TLSSocket>

مثل tls.connect() إلا أن port و host يمكن توفيرهما كوسيطات بدلاً من الخيارات.

سيُعطى الأولوية لخيار المنفذ أو المضيف، إذا تم تحديده، على أي وسيطة منفذ أو مضيف.

tls.createSecureContext([options])

[السجل]

الإصدار	التغييرات
v22.9.0, v20.18.0	تم إضافة خيار allowPartialTrustChain.
v22.4.0, v20.16.0	تعتمد خيارات clientCertEngine و privateKeyEngine و privateKeyIdentifier على دعم المحرك المخصص في OpenSSL وهو مُهمل في OpenSSL 3.
v19.8.0, v18.16.0	يمكن الآن تعيين خيار dhparam على 'auto' لتمكين DHE باستخدام المعلمات المعروفة المناسبة.
v12.12.0	تم إضافة خيارات privateKeyIdentifier و privateKeyEngine للحصول على المفتاح الخاص من محرك OpenSSL.
v12.11.0	تم إضافة خيار sigalgs لتجاوز خوارزميات التوقيع المدعومة.
v12.0.0	تم إضافة دعم TLSv1.3.
v11.5.0	يدعم خيار ca: الآن BEGIN TRUSTED CERTIFICATE.
v11.4.0, v10.16.0	يمكن استخدام minVersion و maxVersion لتقييد إصدارات بروتوكول TLS المسموح بها.
v10.0.0	لم يعد من الممكن تعيين ecdhCurve على false بسبب تغيير في OpenSSL.
v9.3.0	يمكن أن تتضمن وسيطة options الآن clientCertEngine.
v9.0.0	يمكن أن يكون خيار ecdhCurve الآن أسماء منحنى متعددة مفصولة بـ ':' أو 'auto'.
v7.3.0	إذا كانت وسيطة key عبارة عن مصفوفة، فلن تحتاج الإدخالات الفردية إلى خاصية passphrase بعد الآن. يمكن أن تكون إدخالات Array أيضًا سلاسل نصية أو Buffers الآن.
v5.2.0	يمكن أن يكون خيار ca الآن سلسلة واحدة تحتوي على شهادات CA متعددة.
v0.11.13	مضاف في: v0.11.13

• options <Object>
  • allowPartialTrustChain <boolean> تعامل الشهادات الوسيطة (غير الموقعة ذاتيًا) في قائمة شهادات CA الموثوق بها على أنها موثوقة.
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> تجاوز شهادات CA الموثوق بها اختيارياً. القيمة الافتراضية هي الثقة بقوائم CAs المعروفة جيدًا التي قامت بتجميعها Mozilla. يتم استبدال CAs الخاصة بـ Mozilla تمامًا عندما يتم تحديد CAs صراحةً باستخدام هذا الخيار. يمكن أن تكون القيمة سلسلة نصية أو Buffer، أو Array من السلاسل النصية و/أو Buffers. يمكن أن تحتوي أي سلسلة نصية أو Buffer على العديد من CAs بتنسيق PEM متسلسلة معًا. يجب أن تكون شهادة النظير قابلة للتسلسل إلى CA موثوق بها من قبل الخادم ليتم مصادقة الاتصال. عند استخدام شهادات غير قابلة للتسلسل إلى CA معروفة جيدًا، يجب تحديد CA للشهادة صراحةً على أنها موثوق بها أو سيفشل الاتصال في المصادقة. إذا استخدم النظير شهادة لا تتطابق أو تتسلسل مع أحد CAs الافتراضية، فاستخدم خيار ca لتوفير شهادة CA يمكن أن تتطابق شهادة النظير معها أو تتسلسل إليها. بالنسبة لل شهادات الموقعة ذاتيًا، تكون الشهادة هي CA الخاصة بها، ويجب توفيرها. بالنسبة للشهادات المشفرة بتنسيق PEM، الأنواع المدعومة هي "TRUSTED CERTIFICATE" و "X509 CERTIFICATE" و "CERTIFICATE". انظر أيضًا tls.rootCertificates.
  • cert <string> | <string[]> | <Buffer> | <Buffer[]> سلاسل الشهادات بتنسيق PEM. يجب توفير سلسلة شهادة واحدة لكل مفتاح خاص. يجب أن تتكون كل سلسلة شهادة من الشهادة بتنسيق PEM لمفتاح خاص مُقدم، متبوعًا بالشهادات الوسيطة بتنسيق PEM (إن وجدت)، بالترتيب، وعدم تضمين CA الجذر (يجب أن يكون CA الجذر معروفًا مسبقًا للنظير، انظر ca). عند توفير سلاسل شهادات متعددة، لا يجب أن تكون بنفس ترتيب مفاتيحها الخاصة في key. إذا لم يتم توفير الشهادات الوسيطة، فلن يتمكن النظير من التحقق من صحة الشهادة، وسيفشل المصافحة.
  • sigalgs <string> قائمة مفصولة بفاصلة نقطتين من خوارزميات التوقيع المدعومة. يمكن أن تحتوي القائمة على خوارزميات التجزئة (SHA256، MD5 وما إلى ذلك)، وخوارزميات المفتاح العام (RSA-PSS، ECDSA وما إلى ذلك)، أو مزيج من كليهما (مثل 'RSA+SHA384') أو أسماء مخططات TLS v1.3 (مثل rsa_pss_pss_sha512). انظر صفحات دليل OpenSSL لمزيد من المعلومات.
  • ciphers <string> مواصفات مجموعة التشفير، لتحل محل القيمة الافتراضية. لمزيد من المعلومات، انظر تعديل مجموعة تشفير TLS الافتراضية. يمكن الحصول على الشفرات المسموح بها عبر tls.getCiphers(). يجب أن تكون أسماء الشفرات بأحرف كبيرة لكي يقبلها OpenSSL.
  • clientCertEngine <string> اسم محرك OpenSSL الذي يمكنه توفير شهادة العميل. مُهمل.
  • crl <string> | <string[]> | <Buffer> | <Buffer[]> قوائم CRL (قوائم إلغاء شهادة) بتنسيق PEM.
  • dhparam <string> | <Buffer> 'auto' أو معلمات Diffie-Hellman مخصصة، مطلوبة لـ سرية التوجيه الأمامية المثالية غير ECDHE. إذا تم حذفها أو كانت غير صالحة، فسيتم تجاهل المعلمات بصمت ولن تتوفر شفرات DHE. ستظل سرية التوجيه الأمامية المثالية القائمة على ECDHE متاحة.
  • ecdhCurve <string> سلسلة تصف منحنى مُسمى أو قائمة مفصولة بفاصلة نقطتين من NIDs أو أسماء المنحنى، على سبيل المثال P-521:P-384:P-256، لاستخدامها في اتفاقية مفتاح ECDH. تم تعيينها على auto لاختيار المنحنى تلقائيًا. استخدم crypto.getCurves() للحصول على قائمة بأسماء المنحنيات المتاحة. في الإصدارات الحديثة، سيعرض openssl ecparam -list_curves أيضًا اسم ووصف كل منحنى بيضاوي متاح. الافتراضي: tls.DEFAULT_ECDH_CURVE.
  • honorCipherOrder <boolean> حاول استخدام تفضيلات مجموعة تشفير الخادم بدلاً من تفضيلات العميل. عندما تكون true، تتسبب في تعيين SSL_OP_CIPHER_SERVER_PREFERENCE في secureOptions، انظر خيارات OpenSSL لمزيد من المعلومات.
  • key <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> مفاتيح خاصة بتنسيق PEM. يسمح PEM بإمكانية تشفير المفاتيح الخاصة. سيتم فك تشفير المفاتيح المشفرة باستخدام options.passphrase. يمكن توفير مفاتيح متعددة باستخدام خوارزميات مختلفة إما كمصفوفة من سلاسل المفاتيح أو مخازن البيانات غير المشفرة، أو مصفوفة من الكائنات بالشكل {pem: \<string|buffer\>[, passphrase: \<string\>]}. يمكن أن يحدث النموذج الكائن فقط في مصفوفة. object.passphrase اختياري. سيتم فك تشفير المفاتيح المشفرة باستخدام object.passphrase إذا تم توفيره، أو options.passphrase إذا لم يكن كذلك.
  • privateKeyEngine <string> اسم محرك OpenSSL للحصول على المفتاح الخاص منه. يجب استخدامه مع privateKeyIdentifier. مُهمل.
  • privateKeyIdentifier <string> معرف مفتاح خاص مُدار بواسطة محرك OpenSSL. يجب استخدامه مع privateKeyEngine. يجب عدم تعيينه مع key، لأن كلا الخيارين يُحددان مفتاحًا خاصًا بطرق مختلفة. مُهمل.
  • maxVersion <string> تعيين الحد الأقصى لإصدار TLS المسموح به اختيارياً. واحد من 'TLSv1.3'، 'TLSv1.2'، 'TLSv1.1'، أو 'TLSv1'. لا يمكن تحديده مع خيار secureProtocol؛ استخدم أحدهما أو الآخر. الافتراضي: tls.DEFAULT_MAX_VERSION.
  • minVersion <string> تعيين الحد الأدنى لإصدار TLS المسموح به اختيارياً. واحد من 'TLSv1.3'، 'TLSv1.2'، 'TLSv1.1'، أو 'TLSv1'. لا يمكن تحديده مع خيار secureProtocol؛ استخدم أحدهما أو الآخر. تجنب التعيين إلى أقل من TLSv1.2، ولكن قد يكون مطلوبًا للتوافق بين التشغيل. قد تتطلب الإصدارات التي تسبق TLSv1.2 تخفيض مستوى أمان OpenSSL. الافتراضي: tls.DEFAULT_MIN_VERSION.
  • passphrase <string> عبارة مرور مشتركة تُستخدم لمفتاح خاص واحد و/أو PFX.
  • pfx <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> مفتاح خاص مشفر بتنسيق PFX أو PKCS12 وسلسلة شهادات. pfx بديل لتوفير key و cert بشكل منفصل. عادةً ما يتم تشفير PFX، وإذا كان كذلك، فسيتم استخدام passphrase لفك تشفيره. يمكن توفير PFX متعددة إما كمصفوفة من مخازن بيانات PFX غير المشفرة، أو مصفوفة من الكائنات بالشكل {buf: \<string|buffer\>[, passphrase: \<string\>]}. يمكن أن يحدث النموذج الكائن فقط في مصفوفة. object.passphrase اختياري. سيتم فك تشفير PFX المشفرة باستخدام object.passphrase إذا تم توفيره، أو options.passphrase إذا لم يكن كذلك.
  • secureOptions <number> التأثير اختيارياً على سلوك بروتوكول OpenSSL، وهو ليس ضروريًا عادةً. يجب استخدام هذا بحذر إن أمكن! القيمة هي قناع بت رقمي لخيارات SSL_OP_* من خيارات OpenSSL.
  • secureProtocol <string> آلية مُوروثة لاختيار إصدار بروتوكول TLS الذي سيتم استخدامه، لا تدعم التحكم المستقل في الحد الأدنى والحد الأقصى للإصدار، ولا تدعم تقييد البروتوكول على TLSv1.3. استخدم minVersion و maxVersion بدلاً من ذلك. يتم سرد القيم الممكنة كـ SSL_METHODS، استخدم أسماء الوظائف كسلاسل نصية. على سبيل المثال، استخدم 'TLSv1_1_method' لإجبار إصدار TLS 1.1، أو 'TLS_method' للسماح بأي إصدار بروتوكول TLS يصل إلى TLSv1.3. لا يُوصى باستخدام إصدارات TLS أقل من 1.2، ولكن قد يكون ذلك مطلوبًا للتوافق بين التشغيل. الافتراضي: لا شيء، انظر minVersion.
  • sessionIdContext <string> معرف غير شفاف يستخدمه الخادم لضمان عدم مشاركة حالة الجلسة بين التطبيقات. غير مستخدم من قبل العملاء.
  • ticketKeys: <Buffer> 48 بايت من البيانات العشوائية شبه عشوائية قوية مشفرة. انظر استئناف الجلسة لمزيد من المعلومات.
  • sessionTimeout <number> عدد الثواني التي ستصبح بعدها جلسة TLS التي أنشأها الخادم غير قابلة للاستئناف. انظر استئناف الجلسة لمزيد من المعلومات. الافتراضي: 300.

tls.createServer() يضع القيمة الافتراضية لخيار honorCipherOrder على true، بينما تترك واجهات برمجة التطبيقات الأخرى التي تُنشئ سياقات آمنة هذا الخيار غير مُعيّن.

tls.createServer() يستخدم قيمة هاش SHA1 مُختصرة 128 بت مُنشأة من process.argv كقيمة افتراضية لخيار sessionIdContext، بينما لا تحتوي واجهات برمجة التطبيقات الأخرى التي تُنشئ سياقات آمنة على قيمة افتراضية.

تُنشئ طريقة tls.createSecureContext() كائن SecureContext. وهو قابل للاستخدام كوسيطة لعدة واجهات برمجة تطبيقات tls، مثل server.addContext()، لكن ليس لديه طرق عامة. لا يدعم مُنشئ tls.Server وطريقة tls.createServer() خيار secureContext.

المفتاح مطلوب للشفرات التي تستخدم الشهادات. يمكن استخدام key أو pfx لتوفيره.

إذا لم يتم إعطاء خيار ca، فسيتم استخدام Node.js افتراضيًا قائمة CAs الموثوقة علنًا من Mozilla.

لا يُشجع استخدام معلمات DHE مخصصة لصالح الخيار الجديد dhparam: 'auto'. عند تعيينه على 'auto'، سيتم اختيار معلمات DHE المعروفة جيدًا ذات القوة الكافية تلقائيًا. خلاف ذلك، إذا لزم الأمر، يمكن استخدام openssl dhparam لإنشاء معلمات مخصصة. يجب أن يكون طول المفتاح أكبر من أو يساوي 1024 بت أو سيتم إلقاء خطأ. على الرغم من أن 1024 بت مسموح به، استخدم 2048 بت أو أكبر لأمان أقوى.

tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])

[السجل]

الإصدار	التغييرات
v5.0.0	خيارات ALPN مدعومة الآن.
v0.11.3	مُحذّر منذ: v0.11.3
v0.3.2	تمت الإضافة في: v0.3.2

[مستقر: 0 - مُحذّر]

مستقر: 0 الثبات: 0 - مُحذّر: استخدم tls.TLSSocket بدلاً منه.

• context <Object> كائن سياق آمن كما تم إرجاعه بواسطة tls.createSecureContext()
• isServer <boolean> true لتحديد أن اتصال TLS هذا يجب فتحه كخادم.
• requestCert <boolean> true لتحديد ما إذا كان الخادم يجب أن يطلب شهادة من عميل متصل. ينطبق فقط عندما يكون isServer هو true.
• rejectUnauthorized <boolean> إذا لم يكن false ، سيرفض الخادم تلقائيًا العملاء الذين لديهم شهادات غير صالحة. ينطبق فقط عندما يكون isServer هو true.
• options
  • enableTrace: انظر tls.createServer()
  • secureContext: كائن سياق TLS من tls.createSecureContext()
  • isServer: إذا كان true ، فسيتم إنشاء مقبس TLS في وضع الخادم. الافتراضي: false.
  • server <net.Server> مثيل net.Server
  • requestCert: انظر tls.createServer()
  • rejectUnauthorized: انظر tls.createServer()
  • ALPNProtocols: انظر tls.createServer()
  • SNICallback: انظر tls.createServer()
  • session <Buffer> مثيل Buffer يحتوي على جلسة TLS.
  • requestOCSP <boolean> إذا كان true ، فإنه يحدد أنه سيتم إضافة امتداد طلب حالة OCSP إلى طلب العميل وسيتم إصدار حدث 'OCSPResponse' على المقبس قبل إنشاء اتصال آمن.

يقوم بإنشاء كائن زوج آمن جديد مع تيارين ، أحدهما يقرأ ويكتب البيانات المشفرة والآخر يقرأ ويكتب البيانات العادية. بشكل عام ، يتم توصيل التيار المشفر إلى/من تيار بيانات مشفر وارد ، ويتم استخدام التيار العادي كبديل للتيار المشفر الأولي.

tls.createSecurePair() يُرجع كائن tls.SecurePair مع خصائص تيار cleartext و encrypted.

استخدام cleartext له نفس واجهة برمجة التطبيقات مثل tls.TLSSocket.

أصبحت طريقة tls.createSecurePair() مُحذّرة الآن لصالح tls.TLSSocket(). على سبيل المثال ، الكود:

pair = tls.createSecurePair(/* ... */)
pair.encrypted.pipe(socket)
socket.pipe(pair.encrypted)

يمكن استبداله بـ:

secureSocket = tls.TLSSocket(socket, options)

حيث أن secureSocket له نفس واجهة برمجة التطبيقات مثل pair.cleartext.

tls.createServer([options][, secureConnectionListener])

[السجل]

الإصدار	التغييرات
v22.4.0، v20.16.0	يعتمد خيار clientCertEngine على دعم المحرك المخصص في OpenSSL وهو مُهمل في OpenSSL 3.
v19.0.0	إذا تم تعيين ALPNProtocols، فسيتم إنهاء الاتصالات الواردة التي ترسل امتداد ALPN بدون بروتوكولات مدعومة مع تنبيه no_application_protocol خطير.
v20.4.0، v18.19.0	يمكن أن يتضمن معامل options الآن ALPNCallback.
v12.3.0	يدعم معامل options الآن خيارات net.createServer().
v9.3.0	يمكن أن يتضمن معامل options الآن clientCertEngine.
v8.0.0	يمكن أن يكون خيار ALPNProtocols عبارة عن TypedArray أو DataView الآن.
v5.0.0	يتم دعم خيارات ALPN الآن.
v0.3.2	تمت الإضافة في: v0.3.2

• options <Object>

  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> مصفوفة من السلاسل، أو Buffers، أو TypedArrays، أو DataViews، أو Buffer واحد، أو TypedArray، أو DataView يحتوي على بروتوكولات ALPN المدعومة. يجب أن يكون لدى Buffers التنسيق [len][name][len][name]... على سبيل المثال، 0x05hello0x05world، حيث يكون البايت الأول هو طول اسم البروتوكول التالي. عادةً ما يكون تمرير مصفوفة أبسط بكثير، على سبيل المثال ['hello', 'world']. (يجب ترتيب البروتوكولات حسب أولويتها.)
  • ALPNCallback: <Function> إذا تم تعيينه، فسيتم استدعائه عندما يفتح العميل اتصالاً باستخدام امتداد ALPN. سيتم تمرير وسيطة واحدة إلى وظيفة الاستدعاء: كائن يحتوي على حقلي servername و protocols، اللذان يحتويان على اسم الخادم من امتداد SNI (إن وجد) ومصفوفة من سلاسل أسماء بروتوكول ALPN على التوالي. يجب أن تُعيد وظيفة الاستدعاء إما أحد السلاسل المدرجة في protocols، والتي سيتم إرجاعها إلى العميل كبروتوكول ALPN المحدد، أو undefined، لرفض الاتصال بتنبيه خطير. إذا تم إرجاع سلسلة لا تتطابق مع أحد بروتوكولات ALPN الخاصة بالعميل، فسيتم طرح خطأ. لا يمكن استخدام هذا الخيار مع خيار ALPNProtocols، وسيؤدي تعيين كلا الخيارين إلى طرح خطأ.
  • clientCertEngine <string> اسم محرك OpenSSL الذي يمكنه توفير شهادة العميل. مهمل.
  • enableTrace <boolean> إذا كان true، فسيتم استدعاء tls.TLSSocket.enableTrace() على الاتصالات الجديدة. يمكن تمكين التتبع بعد إنشاء الاتصال الآمن، ولكن يجب استخدام هذا الخيار لتتبع إعداد الاتصال الآمن. الافتراضي: false.
  • handshakeTimeout <number> إلغاء الاتصال إذا لم ينتهِ المصافحة SSL/TLS في عدد الملي ثانية المحدد. يتم إصدار 'tlsClientError' على كائن tls.Server كلما انتهت مهلة المصافحة. الافتراضي: 120000 (120 ثانية).
  • rejectUnauthorized <boolean> إذا لم يكن false، سيرفض الخادم أي اتصال غير مصرح به بقائمة سلطات الإصدار الموثوقة المُقدمة. لا يكون لهذا الخيار أي تأثير إلا إذا كان requestCert هو true. الافتراضي: true.
  • requestCert <boolean> إذا كان true، سيرفض الخادم أي اتصال غير مصرح به بقائمة سلطات الإصدار الموثوقة المُقدمة. الافتراضي: false.
  • sessionTimeout <number> عدد الثواني التي بعدها لن تكون جلسة TLS التي أنشأها الخادم قابلة للاستئناف. انظر استئناف الجلسة لمزيد من المعلومات. الافتراضي: 300.
  • SNICallback(servername, callback) <Function> دالة سيتم استدعاؤها إذا كان العميل يدعم امتداد SNI TLS. سيتم تمرير وسيطتين عند الاستدعاء: servername و callback. callback هي وظيفة استدعاء أولوية الخطأ تأخذ وسيطتين اختياريتين: error و ctx. ctx، إذا تم توفيره، هو مثيل SecureContext. يمكن استخدام tls.createSecureContext() للحصول على SecureContext مناسب. إذا تم استدعاء callback مع وسيطة ctx خاطئة، فسيتم استخدام سياق الأمان الافتراضي للخادم. إذا لم يتم توفير SNICallback، فسيتم استخدام وظيفة الاستدعاء الافتراضية مع واجهة برمجة التطبيقات عالية المستوى (انظر أدناه).
  • ticketKeys: <Buffer> 48 بايت من البيانات العشوائية الزائفة القوية مشفرة. انظر استئناف الجلسة لمزيد من المعلومات.
  • pskCallback <Function> لمفاوضات TLS-PSK، انظر مفاتيح مُشتركة مسبقًا.
  • pskIdentityHint <string> تلميح اختياري لإرساله إلى عميل للمساعدة في اختيار الهوية أثناء مفاوضات TLS-PSK. سيتم تجاهله في TLS 1.3. عند الفشل في تعيين pskIdentityHint سيتم إصدار 'tlsClientError' مع رمز 'ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED'.
  • ...: يمكن توفير أي خيار tls.createSecureContext(). بالنسبة للخوادم، غالبًا ما تكون خيارات الهوية (pfx، key/cert، أو pskCallback) مطلوبة.
  • ...: يمكن توفير أي خيار net.createServer().

• secureConnectionListener <Function>

• الإرجاع: <tls.Server>

ينشئ tls.Server جديدًا. يتم تعيين secureConnectionListener، إذا تم توفيره، تلقائيًا كـمستمع لحدث 'secureConnection'.

يتم مشاركة خيارات ticketKeys تلقائيًا بين عمال وحدة node:cluster.

يوضح ما يلي خادم صدى بسيط:

ESM

import { createServer } from 'node:tls'
import { readFileSync } from 'node:fs'

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),

  // هذا ضروري فقط إذا كنت تستخدم مصادقة شهادة العميل.
  requestCert: true,

  // هذا ضروري فقط إذا كان العميل يستخدم شهادة ذاتية التوقيع.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('server connected', socket.authorized ? 'authorized' : 'unauthorized')
  socket.write('welcome!\n')
  socket.setEncoding('utf8')
  socket.pipe(socket)
})
server.listen(8000, () => {
  console.log('server bound')
})

CJS

const { createServer } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),

  // هذا ضروري فقط إذا كنت تستخدم مصادقة شهادة العميل.
  requestCert: true,

  // هذا ضروري فقط إذا كان العميل يستخدم شهادة ذاتية التوقيع.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('server connected', socket.authorized ? 'authorized' : 'unauthorized')
  socket.write('welcome!\n')
  socket.setEncoding('utf8')
  socket.pipe(socket)
})
server.listen(8000, () => {
  console.log('server bound')
})

لتوليد الشهادة والمفتاح لهذا المثال، قم بتشغيل:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout server-key.pem -out server-cert.pem

ثم، لتوليد شهادة client-cert.pem لهذا المثال، قم بتشغيل:

openssl pkcs12 -certpbe AES-256-CBC -export -out client-cert.pem \
  -inkey server-key.pem -in server-cert.pem

يمكن اختبار الخادم من خلال الاتصال به باستخدام عميل المثال من tls.connect().

tls.getCiphers()

مضاف في: v0.10.2

• مُخرجات: <string[]>

يُرجع مصفوفةً بأسماء تشفير TLS المدعومة. الأسماء صغيرة الحروف لأسباب تاريخية، ولكن يجب تحويلها إلى أحرف كبيرة لاستخدامها في خيار ciphers في tls.createSecureContext().

ليست كل خوارزميات التشفير المدعومة مُفعّلةً افتراضيًا. انظر تعديل مجموعة تشفير TLS الافتراضية.

أسماء خوارزميات التشفير التي تبدأ بـ 'tls_' مخصصة لـ TLSv1.3، وكل الخوارزميات الأخرى مخصصة لـ TLSv1.2 وما دونه.

console.log(tls.getCiphers()) // ['aes128-gcm-sha256', 'aes128-sha', ...]

tls.rootCertificates

مضاف في: v12.3.0

• <string[]>

مصفوفة ثابتة من السلاسل التي تمثل شهادات الجذر (بصيغة PEM) من مخزن شهادات موزيلا المضمّن كما هو مُقدّم من إصدار Node.js الحالي.

مخزن الشهادات المضمّن، كما هو مُقدّم من Node.js، هو لقطة ثابتة من مخزن شهادات موزيلا يتم تثبيته عند وقت الإصدار. وهو متطابق على جميع المنصات المدعومة.

tls.DEFAULT_ECDH_CURVE

[السجل]

الإصدار	التغييرات
v10.0.0	تم تغيير القيمة الافتراضية إلى 'auto'.
v0.11.13	مضاف في: v0.11.13

اسم المنحنى الافتراضي المُستخدم لاتفاقية مفتاح ECDH في خادم tls. القيمة الافتراضية هي 'auto'. انظر tls.createSecureContext() لمزيد من المعلومات.

tls.DEFAULT_MAX_VERSION

مضاف في: v11.4.0

• <string> القيمة الافتراضية لخيار maxVersion من tls.createSecureContext(). يمكن تعيين أي من إصدارات بروتوكول TLS المدعومة، 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', أو 'TLSv1'. الافتراضي: 'TLSv1.3', ما لم يتم تغييره باستخدام خيارات سطر الأوامر. استخدام --tls-max-v1.2 يُعيّن الافتراضي إلى 'TLSv1.2'. استخدام --tls-max-v1.3 يُعيّن الافتراضي إلى 'TLSv1.3'. إذا تم توفير أكثر من خيار، فسيتم استخدام الحد الأقصى الأعلى.

tls.DEFAULT_MIN_VERSION

مضاف في: v11.4.0

• <string> القيمة الافتراضية لخيار minVersion في tls.createSecureContext(). يمكن تعيين أي من إصدارات بروتوكول TLS المدعومة، 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', أو 'TLSv1'. قد تتطلب الإصدارات السابقة لـ TLSv1.2 ترقية مستوى أمان OpenSSL. الافتراضي: 'TLSv1.2', ما لم يتم تغييره باستخدام خيارات سطر الأوامر. يؤدي استخدام --tls-min-v1.0 إلى تعيين الافتراضي إلى 'TLSv1'. يؤدي استخدام --tls-min-v1.1 إلى تعيين الافتراضي إلى 'TLSv1.1'. يؤدي استخدام --tls-min-v1.3 إلى تعيين الافتراضي إلى 'TLSv1.3'. إذا تم توفير أكثر من خيار واحد، فسيتم استخدام الحد الأدنى.

tls.DEFAULT_CIPHERS

مضاف في: v19.8.0, v18.16.0

• <string> القيمة الافتراضية لخيار ciphers في tls.createSecureContext(). يمكن تعيين أي من تشفرات OpenSSL المدعومة. الافتراضي هو محتوى crypto.constants.defaultCoreCipherList, ما لم يتم تغييره باستخدام خيارات سطر الأوامر باستخدام --tls-default-ciphers.