مرجع إعدادات ⁦TLS⁩

إعدادات ⁦TLS⁩ وإدارة الشهادات لخادم ⁦Elide⁩ لبروتوكول ⁦HTTP⁩.

يوفر ثلاثة أوضاع لتوفير الشهادات:

1. ⁦ACME⁩ تلقائي (⁦auto = true⁩، الافتراضي) — يحصل على الشهادات ويجددها تلقائياً لكل نطاق مُدرج في ⁦ServerBlock.domains⁩، باستخدام ⁦Let's Encrypt⁩ أو جهة مصادقة احتياطية. 2. يدوي (⁦certFile⁩ + ⁦keyFile⁩) — يستخدم ملفات شهادة ومفتاح ⁦PEM⁩ ثابتة توفرها وتُديرها بنفسك. 3. عند الطلب (⁦onDemand⁩) — يُصدر الشهادات في وقت مصافحة ⁦TLS⁩ لأسماء المضيفين غير المعروفة مسبقاً. راجع ⁦OnDemandTls⁩.

يمكن دمج هذه الأوضاع: ⁦auto⁩ يغطي النطاقات المُصرح بها بينما ⁦onDemand⁩ يتعامل مع أسماء المضيفين الديناميكية.

راجع ⁦DnsChallenge⁩ لدعم شهادات أحرف البدل عبر ⁦DNS-01⁩ و⁦ClientAuth⁩ للتحقق المتبادل من عميل ⁦TLS⁩ (⁦mTLS⁩).

> هذه الصفحة مُولَّدة تلقائياً من مخطط ⁦PKL⁩. راجع الدليل لأمثلة الاستخدام.

الأنواع

`TlsVersion`

الحد الأدنى لإصدار بروتوكول ⁦TLS⁩ المقبول من المستمعين.

⁦"1.3"⁩ — ⁦TLS 1.3⁩ فقط. أقوى أمان؛ مُوصى به للخوادم المواجهة للعموم. ⁦"1.2"⁩ — ⁦TLS 1.2⁩ وما فوق. توافق أوسع مع العملاء.

pkl

typealias TlsVersion = "1.2" | "1.3"

`CipherSuitePreset`

مجموعة تشفير ⁦TLS⁩ مُسماة تُطبق أثناء التفاوض.

⁦"default"⁩ — مجموعة ⁦Elide⁩ المُوصى بها من التشفيرات الآمنة والحديثة. ⁦"fips"⁩ — يقتصر على مجموعات ⁦FIPS 140-2⁩ المُعتمدة فقط. ⁦"legacy"⁩ — يضيف مجموعات تشفير أقدم لأقصى توافق مع العملاء. غير مُوصى به للخوادم المواجهة للعموم.

pkl

typealias CipherSuitePreset = "default" | "fips" | "legacy"

---

`OnDemandTls`

⁦TLS⁩ عند الطلب يُصدر شهادة في وقت مصافحة ⁦TLS⁩ لأسماء المضيفين التي لم تُوفر مسبقاً.

هذا يتجنب الحاجة لتعداد جميع النطاقات في الإعدادات مسبقاً، وهو مفيد للمنصات متعددة المستأجرين والإعدادات الشبيهة بأحرف البدل. يُوصى بشدة بنقطة نهاية تفويض (⁦ask⁩) لمنع إساءة الاستخدام من العملاء العشوائيين الذين يُحفزون إصدار الشهادات.

تحديد المعدل عبر ⁦maxPerWindow⁩ و⁦burst⁩ يحمي من هجمات إغراق الشهادات.

الحقل	النوع	الافتراضي	الوصف
`ask`	Uri?	`null`	عنوان ⁦URL⁩ للتفويض يُستعلم قبل إصدار شهادة.
`maxPerWindow`	UInt?	`null`	الحد الأقصى لعدد الشهادات التي يمكن إصدارها لكل ⁦`window`⁩.
`burst`	UInt	`5`	بدل الاندفاع فوق ⁦`maxPerWindow`⁩ أثناء ذروات الحركة القصيرة.
`window`	Duration	`1.h`	مدة النافذة المنزلقة لحد معدل ⁦`maxPerWindow`⁩.

`ask`

عنوان ⁦URL⁩ للتفويض يُستعلم قبل إصدار شهادة.

يُرسل الخادم طلب ⁦GET⁩ بمعامل استعلام ⁦domain⁩ يحتوي على اسم المضيف المطلوب. استجابة ⁦200 OK⁩ تسمح بالإصدار؛ أي كود حالة آخر يرفضه. عند ⁦null⁩، جميع أسماء المضيفين مسموح بها (استخدم بحذر).

`maxPerWindow`

الحد الأقصى لعدد الشهادات التي يمكن إصدارها لكل ⁦window⁩.

عند ⁦null⁩، لا يُطبق حد معدل (غير مُوصى به في الإنتاج).

`burst`

بدل الاندفاع فوق ⁦maxPerWindow⁩ أثناء ذروات الحركة القصيرة.

يصبح الحد الفعلي ⁦maxPerWindow + burst⁩ حتى تلحق النافذة المنزلقة. الافتراضي: ⁦5⁩.

`window`

مدة النافذة المنزلقة لحد معدل ⁦maxPerWindow⁩.

الافتراضي: ساعة واحدة.

---

`DnsChallenge`

إعدادات تحدي ⁦ACME⁩ بأسلوب ⁦DNS-01⁩.

تحديات ⁦DNS-01⁩ تُثبت ملكية النطاق عبر إنشاء سجل ⁦DNS TXT⁩. هذا هو نوع تحدي ⁦ACME⁩ الوحيد الذي يدعم شهادات أحرف البدل (مثل ⁦*.example.com⁩). استخدمه عندما لا تكون تحديات ⁦HTTP-01⁩ ممكنة (مثلاً، الخادم غير متاح للعموم على المنفذ ⁦80⁩).

يتطلب ⁦auto = true⁩ في ⁦TlsConfig⁩.

الحقل	النوع	الافتراضي	الوصف
`provider`	"cloudflare"\	"webhook"	(مطلوب)	مزود تحدي ⁦DNS⁩ الذي ينشئ وينظف سجلات ⁦TXT⁩.
`config`	Mapping	`new Mapping {}`	تجاوزات مفتاح/قيمة خاصة بالمزود.
`propagationTimeout`	Duration	`120.s`	الحد الأقصى لانتظار انتشار سجل ⁦DNS TXT⁩ قبل
`pollInterval`	Duration	`5.s`	تكرار استطلاع مزود ⁦DNS⁩ للتحقق مما إذا كان سجل ⁦TXT⁩

`provider`

مزود تحدي ⁦DNS⁩ الذي ينشئ وينظف سجلات ⁦TXT⁩.

⁦"cloudflare"⁩ — يستخدم واجهة ⁦Cloudflare⁩ البرمجية. يتطلب متغير البيئة ⁦CLOUDFLARE_API_TOKEN⁩. اختيارياً عيّن ⁦CLOUDFLARE_ZONE_ID⁩ لتحديد منطقة معينة.

⁦"webhook"⁩ — يُرسل سجلات التحدي عبر ⁦POST⁩ إلى عنوان ⁦URL⁩ مخصص. يتطلب متغير البيئة ⁦DNS_WEBHOOK_URL⁩ أو ⁦DNS_WEBHOOK_SCRIPT⁩.

`config`

تجاوزات مفتاح/قيمة خاصة بالمزود.

معظم المزودين يقرأون بيانات الاعتماد من متغيرات البيئة، لذا هذا التعيين عادةً فارغ. استخدمه للتجاوزات مثل نقطة نهاية ⁦API⁩ مخصصة أو معرف المنطقة أو سر ⁦webhook⁩.

`propagationTimeout`

الحد الأقصى لانتظار انتشار سجل ⁦DNS TXT⁩ قبل اعتبار التحدي فاشلاً.

الافتراضي: ⁦120⁩ ثانية.

`pollInterval`

تكرار استطلاع مزود ⁦DNS⁩ للتحقق مما إذا كان سجل ⁦TXT⁩ قد انتشر.

الافتراضي: ⁦5⁩ ثوانٍ.

---

`CertStorage`

واجهة تخزين دائمة للشهادات وتدبيسات ⁦OCSP⁩ ومفاتيح حساب ⁦ACME⁩.

تُكتب الشهادات وحالة ⁦ACME⁩ على القرص لتبقى بعد إعادة تشغيل الخادم. تأكد من نسخ المجلد احتياطياً ومن أن أذونات نظام الملفات مناسبة (يحتوي على مفاتيح خاصة).

الحقل	النوع	الافتراضي	الوصف
`path`	String	`"~/.local/share/elide/certs"`	مسار المجلد لتخزين الشهادات المستند إلى الملفات.

`path`

مسار المجلد لتخزين الشهادات المستند إلى الملفات.

يُنشأ المجلد تلقائياً إذا لم يكن موجوداً. الافتراضيات حسب المنصة:

pkl

Linux/macOS: `~/.local/share/elide/certs`
Windows:     `%LOCALAPPDATA%\Elide\certs`

---

`ClientAuth`

إعدادات مصادقة شهادة العميل المتبادلة (⁦mTLS⁩).

يُعد الخادم لطلب (واختيارياً إلزام) شهادة عميل أثناء مصافحة ⁦TLS⁩. تُتحقق الشهادة مقابل سلسلة جهات المصادقة الموثوقة المحددة في ⁦trustedCAs⁩.

الحقل	النوع	الافتراضي	الوصف
`trustedCAs`	Listing(!isEmpty)	(مطلوب)	مسارات ملفات شهادات جهات المصادقة بترميز ⁦PEM⁩ الموثوقة للتحقق من
`required`	Boolean	`true`	ما إذا كانت شهادة العميل الصالحة إلزامية.

`trustedCAs`

مسارات ملفات شهادات جهات المصادقة بترميز ⁦PEM⁩ الموثوقة للتحقق من شهادات العملاء.

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

`required`

ما إذا كانت شهادة العميل الصالحة إلزامية.

عند ⁦true⁩ (الافتراضي)، تُرفض الاتصالات بدون شهادة عميل صالحة على مستوى ⁦TLS⁩. عند ⁦false⁩، تُطلب الشهادة لكن الاتصال يستمر حتى لو لم تُقدم (مفيد لتعريف العميل الاختياري).

---

`TlsConfig`

إعدادات ⁦TLS⁩ الرئيسية لخادم ⁦Elide⁩ لبروتوكول ⁦HTTP⁩.

يتحكم في توفير الشهادات وإصدارات البروتوكول ومجموعات التشفير وتدبيس ⁦OCSP⁩ و⁦TLS⁩ المتبادل. يُطبق على مستوى الخادم بالكامل ما لم يُتجاوز على مستوى كتلة الخادم عبر ⁦TlsBlockOverride⁩.

مثال (⁦ACME⁩ تلقائي)

pkl

new TlsConfig {
  auto = true
  acmeEmail = "ops@example.com"
}

مثال (شهادة يدوية)

pkl

new TlsConfig {
  auto = false
  certFile = "/etc/ssl/example.com.pem"
  keyFile  = "/etc/ssl/example.com-key.pem"
}

الحقل	النوع	الافتراضي	الوصف
`auto`	Boolean	`true`	تفعيل ⁦HTTPS⁩ التلقائي عبر بروتوكول ⁦ACME⁩.
`acmeCA`	Uri	`"https://acme-v02.api.letsencrypt.org/directory"`	عنوان ⁦URL⁩ لدليل جهة مصادقة ⁦ACME⁩ الأساسية.
`acmeCAFallback`	Uri	`"https://acme.zerossl.com/v2/DV90"`	جهة مصادقة ⁦ACME⁩ احتياطية تُستخدم عند عدم الوصول إلى ⁦`acmeCA`⁩ أو
`acmeEmail`	String?	`null`	عنوان البريد الإلكتروني المُسجل لدى جهة مصادقة ⁦ACME⁩.
`onDemand`	OnDemandTls?	`null`	إعدادات ⁦TLS⁩ عند الطلب.
`tailscale`	Boolean	`false`	استخدام جهة مصادقة ⁦Tailscale⁩ بدلاً من جهة ⁦ACME⁩ عامة.
`certFile`	String?	`null`	مسار ملف شهادة بترميز ⁦PEM⁩ لتوفير ⁦TLS⁩ اليدوي.
`keyFile`	String?	`null`	مسار ملف المفتاح الخاص بترميز ⁦PEM⁩ المقابل لـ⁦`certFile`⁩.
`minVersion`	TlsVersion	`"1.2"`	الحد الأدنى لإصدار بروتوكول ⁦TLS⁩ المقبول من المستمعين.
`cipherSuites`	CipherSuitePreset	`"default"`	مجموعة التشفير المُسماة المُطبقة أثناء تفاوض ⁦TLS⁩.
`ocspStapling`	Boolean	`true`	تفعيل تدبيس ⁦OCSP⁩.
`storage`	CertStorage	(فارغ)	واجهة تخزين دائمة للشهادات وحالة ⁦ACME⁩.
`dnsChallenge`	DnsChallenge?	`null`	إعدادات تحدي ⁦ACME⁩ بأسلوب ⁦DNS-01⁩.
`clientAuth`	ClientAuth?	`null`	مصادقة شهادة العميل المتبادلة (⁦mTLS⁩).

`auto`

تفعيل ⁦HTTPS⁩ التلقائي عبر بروتوكول ⁦ACME⁩.

عند ⁦true⁩ (الافتراضي)، يحصل ⁦Elide⁩ على الشهادات ويجددها تلقائياً لجميع أسماء النطاقات المُدرجة في ⁦ServerBlock.domains⁩. يجب أن يكون الخادم متاحاً على المنفذ ⁦80⁩ (لتحديات ⁦HTTP-01⁩) ما لم يُعدّ ⁦dnsChallenge⁩ لتحديات ⁦DNS-01⁩.

`acmeCA`

عنوان ⁦URL⁩ لدليل جهة مصادقة ⁦ACME⁩ الأساسية.

الافتراضي هو نقطة نهاية إنتاج ⁦Let's Encrypt⁩. انتقل إلى عنوان ⁦URL⁩ التجريبي أثناء الاختبار لتجنب الوصول لحدود معدل الإنتاج:

pkl

`"https://acme-staging-v02.api.letsencrypt.org/directory"`

`acmeCAFallback`

جهة مصادقة ⁦ACME⁩ احتياطية تُستخدم عند عدم الوصول إلى ⁦acmeCA⁩ أو إرجاعها خطأ.

الافتراضي هو ⁦ZeroSSL⁩. عيّنه إلى ⁦null⁩ لتعطيل الاحتياطي.

`acmeEmail`

عنوان البريد الإلكتروني المُسجل لدى جهة مصادقة ⁦ACME⁩.

يُستخدم لتحذيرات انتهاء الشهادات واستعادة الحساب. مطلوب من معظم جهات ⁦ACME⁩ العامة (⁦Let's Encrypt⁩، ⁦ZeroSSL⁩).

`onDemand`

إعدادات ⁦TLS⁩ عند الطلب.

عند تعيينها، تُصدر الشهادات في وقت مصافحة ⁦TLS⁩ لأسماء المضيفين غير المُغطاة بـ⁦ServerBlock.domains⁩. عند ⁦null⁩ (الافتراضي)، يُعطل الإصدار عند الطلب. راجع ⁦OnDemandTls⁩.

`tailscale`

استخدام جهة مصادقة ⁦Tailscale⁩ بدلاً من جهة ⁦ACME⁩ عامة.

يتطلب تشغيل ⁦tailscaled⁩ وتسجيل الجهاز في شبكة ⁦Tailnet⁩. تُصدر الشهادات لاسم ⁦FQDN⁩ الخاص بـ⁦Tailscale⁩ للجهاز.

`certFile`

مسار ملف شهادة بترميز ⁦PEM⁩ لتوفير ⁦TLS⁩ اليدوي.

عند توفيره، تُستخدم هذه الشهادة بدلاً من ⁦ACME⁩ للنطاقات المُقدمة من إعدادات ⁦TLS⁩ الجذرية. يجب إقرانه مع ⁦keyFile⁩.

`keyFile`

مسار ملف المفتاح الخاص بترميز ⁦PEM⁩ المقابل لـ⁦certFile⁩.

مطلوب عند تعيين ⁦certFile⁩؛ يُتجاهل خلاف ذلك.

`minVersion`

الحد الأدنى لإصدار بروتوكول ⁦TLS⁩ المقبول من المستمعين.

⁦"1.3"⁩ مُوصى به بشدة للخوادم المواجهة للعموم. ⁦"1.2"⁩ (الافتراضي) يحتفظ بتوافق أوسع مع العملاء.

`cipherSuites`

مجموعة التشفير المُسماة المُطبقة أثناء تفاوض ⁦TLS⁩.

راجع ⁦CipherSuitePreset⁩ للمجموعات المتاحة.

`ocspStapling`

تفعيل تدبيس ⁦OCSP⁩.

عند ⁦true⁩ (الافتراضي)، يجلب الخادم استجابات ⁦OCSP⁩ ويُضمنها في مصافحة ⁦TLS⁩، مما يُقلل تأخير جانب العميل عبر إلغاء بحث ⁦OCSP⁩ المنفصل.

`storage`

واجهة تخزين دائمة للشهادات وحالة ⁦ACME⁩.

راجع ⁦CertStorage⁩ لإعداد المسار.

`dnsChallenge`

إعدادات تحدي ⁦ACME⁩ بأسلوب ⁦DNS-01⁩.

عند تعيينها (و⁦auto = true⁩)، تُحصل الشهادات عبر سجلات ⁦DNS TXT⁩ بدلاً من تحدي ⁦HTTP-01⁩ الافتراضي. مطلوب لشهادات أحرف البدل. راجع ⁦DnsChallenge⁩.

`clientAuth`

مصادقة شهادة العميل المتبادلة (⁦mTLS⁩).

يُعد التحقق من شهادة العميل على مستوى ⁦TLS⁩ الجذري. يمكن تعيين تجاوزات لكل كتلة خادم عبر ⁦TlsBlockOverride.clientAuth⁩. راجع ⁦ClientAuth⁩.

---