ضبط(5ssl)

الاسم
config - ملفات ضبط مكتبة OpenSSL CONF

الوصف
توثق هذه الصفحة صيغة ملفات ضبط OpenSSL، كما تُحلل عبر NCONF_load(3) والدوال ذات الصلة. تُستخدم هذه الصيغة من العديد من أوامر OpenSSL، ولتهيئة المكتبات عند استخدامها من أي تطبيق.

يصف الجزء الأول الصيغة العامة لملفات الضبط، وتصف الأقسام اللاحقة دلالات الوحدات الفردية. توصف الوحدات الأخرى في fips_config(5) و x509v3_config(5). توصف صيغة تعريف قيم ASN.1 في ASN1_generate_nconf(3).

الصياغة
ملف الضبط هو سلسلة من السطور. السطور الفارغة، والمسافات البيضاء بين عناصر السطر، ليس لها أي أهمية. يبدأ التعليق بمحرف #؛ ويُتجاهل بقية السطر. إذا كان محرف # هو أول محرف غير مسافة في السطر، فيُتجاهل السطر بأكمله.

  Directives
يمكن استخدام توجيهين للتحكم في تحليل ملفات الضبط: .include و .pragma.

للتوافق مع الإصدارات الأقدم من OpenSSL، تُتجاهل علامة التساوي بعد التوجيه. ستتعامل معها الإصدارات الأقدم كعملية تعيين، لذا يجب توخي الحذر إذا كان الاختلاف في الدلالات مهمًا.

يمكن لملف أن يضمّن ملفات أخرى باستخدام صيغة التضمين:

  .include [=] pathname

إذا كان pathname اسم ملف بسيط، فيُضمّن هذا الملف مباشرة عند تلك النقطة. يمكن أن تحتوي الملفات المُضمّنة على عبارات .include تحدد ملفات أخرى. إذا كان pathname دليلًا، فستُضمّن جميع الملفات الموجودة داخل هذا الدليل والتي تحمل الامتداد ".cnf" أو ".conf". (يتوفر هذا فقط على الأنظمة التي تدعم إدخال/إخراج POSIX.) تُتجاهل أي أدلة فرعية تُوجَد داخل pathname. وبالمثل، إذا فُتح ملف أثناء فحص دليل، وكان ذلك الملف يحتوي على توجيه .include يحدد دليلًا، فيُتجاهل ذلك أيضًا.

كقاعدة عامة، ينبغي أن يكون pathname مسارًا مطلقًا؛ يمكن فرض ذلك باستخدام توجيهات المترجم abspath و includedir الموصوفة أدناه. يُسبق متغير البيئة OPENSSL_CONF_INCLUDE، إن وُجد، لجميع المسارات النسبية. إذا ظل المسار نسبيًا، فيُفسر بناءً على دليل العمل الحالي.

لإلزام جميع تضمينات الملفات بتسمية مسارات مطلقة، استخدم التوجيه التالي:

 .pragma [=] abspath:value

السلوك المبدئي، حيث تكون value هي false أو off، هو السماح بالمسارات النسبية. لإلزام جميع مسارات .include بأن تكون مسارات مطلقة، استخدم قيمة value كـ true أو on.

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

 .pragma [=] dollarid:value

السلوك المبدئي، حيث تكون value هي false أو off، هو التعامل مع علامة الدولار كدلالة على اسم متغير؛ حيث يُفسر "foo$bar" على أنه "foo" متبوعًا بتوسيع المتغير "bar". إذا كانت value هي true أو on، فإن "foo$bar" يكون اسمًا واحدًا من سبعة محارف ويجب تحديد توسيعات المتغيرات باستخدام أقواس معقوفة أو هلالية.

 .pragma [=] includedir:value

إذا حُدد مسار نسبي في توجيه .include، ولم يكن متغير البيئة OPENSSL_CONF_INCLUDE موجودًا، فتُسبق قيمة توجيه المترجم includedir، إن وُجدت، للمسار.

  الإعدادات
يُنقسَم ملف الضبط إلى عدد من الأقسام. يبدأ القسم باسم القسم بين قوسين مربعين، وينتهي عند بدء قسم جديد، أو عند نهاية الملف. يمكن أن يتكون اسم القسم من محارف أبجدية رقمية وشرطات سفلية. تُزال المسافات البيضاء بين الاسم والأقواس.

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

تُسقَط البيئة على قسم يسمى ENV.

توجد داخل القسم سلسلة من تعيينات الاسم/القيمة، الموصوفة بمزيد من التفصيل أدناه. للتذكير، الأقواس المربعة الموضحة في هذا المثال مطلوبة وليست اختيارية:

 [ section ]
 name1 = This is value1
 name2 = Another value
 ...
 [ newsection ]
 name1 = New value1
 name3 = Value 3

يمكن أن يحتوي الاسم على أي محارف أبجدية رقمية بالإضافة إلى بضعة رموز ترقيم مثل . و , و ; و _. تُتجاهل المسافات البيضاء بعد الاسم وقبل علامة التساوي.

إذا تكرر اسم في نفس القسم، فتُتجاهل جميع القيم باستثناء القيمة الأخيرة. في ظروف معينة، مثل الأسماء المتميزة للشهادات (DNs)، قد يظهر الحقل نفسه مرات متعددة. ولدعم ذلك، تتجاهل أوامر مثل openssl-req(1) أي نص بادئ مسبوق بنقطة. على سبيل المثال:

 1.OU = First OU
 2.OU = Second OU

تتكون القيمة من السلسلة النصية التي تلي محرف = حتى نهاية السطر مع إزالة أي مسافات بيضاء بادئة أو لاحقة.

تخضع السلسلة النصية للقيمة لتوسيع المتغيرات. يُدرج النص $var أو "${var}" قيمة المتغير المسمى من القسم الحالي. لاستخدام قيمة من قسم آخر، استخدم $section::name أو "${section::name}". وعند استخدام $ENV::name، تُستبدل قيمة متغير البيئة المحدد.

يجب تعريف المتغيرات قبل الإشارة إلى قيمتها، وإلا سيُشار إلى وجود خطأ ولن يُحمّل الملف. يمكن التحايل على ذلك بتحديد قيمة مبدئية في القسم المبدئي قبل استخدام المتغير.

أي إعدادات اسم/قيمة في قسم ENV تكون متاحة لملف الضبط، ولكن لا تُنشر إلى البيئة.

يعد خطأً إذا انتهى الأمر بالقيمة لتكون أطول من 64 كيلوبايت.

يمكن هروب محارف معينة باستخدام علامة اقتباس مفردة ' أو مزدوجة " حول القيمة، أو باستخدام شرطة مائلة عكسية \ قبل المحرف. وجعل المحرف الأخير في السطر \ يسمح بنشر سلسلة القيمة النصية عبر سطور متعددة. بالإضافة إلى ذلك، تُعرف التتابعات \n و \r و \b و \t.

قواعد التوسيع والهروب الموصوفة أعلاه والتي تنطبق على القيمة تنطبق أيضًا على مسار توجيه .include.

ضبط مكتبة OPENSSL
تستخدم الأقسام أدناه المصطلح غير الرسمي الوحدة للإشارة إلى جزء من وظائف OpenSSL. ولا يتطابق هذا مع المصطلح الرسمي وحدة FIPS، على سبيل المثال.

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

يبحث OpenSSL أيضًا عن قيمة config_diagnostics. إذا كانت موجودة ولها قيمة عددية غير صفرية، فستُتجاهل أي أعلام لإخفاء الأخطاء ممررة إلى CONF_modules_load(). يفيد هذا في تشخيص أخطاء الضبط ولكن استخدامه في بيئة الإنتاج يتطلب اعتبارات إضافية. فعند تفعيل هذا الخيار، سيمنع خطأ الضبط الوصول إلى الخدمة تمامًا. وبدون هذا الخيار وفي وجود خطأ ضبط، سيُسمح بالوصول ولكن الضبط المطلوب لن يُستخدم.

 # These must be in the default section
 config_diagnostics = 1
 openssl_conf = openssl_init

 [openssl_init]
 oid_section = oids
 providers = providers
 alg_section = evp_properties
 ssl_conf = ssl_configuration
 engines = engines
 random = random

 [oids]
 ... new oids here ...

 [providers]
 ... provider stuff here ...

 [evp_properties]
 ... EVP properties here ...

 [ssl_configuration]
 ... SSL/TLS configuration properties here ...

 [engines]
 ... engine properties here ...

 [random]
 ... random properties here ...

توصَف دلالات كل وحدة أدناه. تشير عبارة "في قسم التهيئة" إلى القسم المحدد بواسطة openssl_conf أو اسم آخر (مذكور كـ openssl_init في المثال أعلاه). تفترض الأمثلة أدناه استخدام الضبط أعلاه لتحديد الأقسام الفردية.

  ضبط معرف كائن ASN.1
يسمي الاسم oid_section في قسم التهيئة القسم الذي يحتوي على أزواج الاسم/القيمة لمعرفات الكائنات (OIDs). الاسم هو الاسم القصير؛ والقيمة هي اسم طويل اختياري متبوعًا بفاصلة، ثم القيمة الرقمية. وفي حين أن بعض أوامر OpenSSL تملك قسمًا خاصًا بها لتحديد معرفات الكائنات، فإن هذا القسم يجعلها متاحة لجميع الأوامر والتطبيقات.

 [oids]
 shortName = a very long OID name, 1.2.3.4
 newoid1 = 1.2.3.4.1
 some_other_oid = 1.2.3.5

إذا كان هناك ضبط كامل يتضمن الجزء أعلاه في الملف example.cnf، فإن سطر الأوامر التالي:

 OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1

سيخرج:

 0:d=0  hl=2 l=   4 prim: OBJECT            :newoid1

موضحًا أن معرف الكائن "newoid1" أُضيف كـ "1.2.3.4.1".

  ضبط المزود
يسمي الاسم providers في section التهيئة القسم الذي يحتوي على ضبط مزود التعمية. وتسمي تعيينات الاسم/القيمة في هذا القسم مزودًا، وتشير إلى قسم الضبط الخاص بذلك المزود. يُستخدم القسم الخاص بالمزود لتحديد كيفية تحميل الوحدة، وتفعيلها، وتعيين المعاملات الأخرى.

تكون للأسماء التالية دلالة داخل قسم المزود:

identity
    يُستخدم هذا لتحديد اسم بديل، متجاوزًا الاسم المبدئي المحدد في قائمة المزودين. على سبيل المثال:

     [providers]
     foo = foo_provider

     [foo_provider]
     identity = my_fips_module

module
    يحدد مسار الوحدة (عادةً مكتبة مشتركة) المراد تحميلها.

activate
    إذا وُجد وضُبط على إحدى القيم yes أو on أو true أو 1، فسيُفعل المزود المرتبط. وعلى العكس، فإن ضبط هذه القيمة على no أو off أو false أو 0 سيمنع تفعيل المزود. يمكن تقديم الإعدادات بحروف صغيرة أو كبيرة. سيؤدي ضبط activate على أي إعداد آخر، أو إغفال قيمة الإعداد، إلى حدوث خطأ.

    = item soft_load

    إذا فُعّل، فإنه يبلغ المكتبة بمسح كدس الأخطاء عند الفشل في تفعيل المزود المطلوب. تؤدي القيمة 1 أو yes أو true أو on (بحروف صغيرة أو كبيرة) إلى تفعيل هذا الإعداد، في حين أن القيمة 0 أو no أو false أو off (بحروف صغيرة أو كبيرة أيضًا) ستعطله. ستنتج أي قيمة أخرى خطأً. لاحظ أن هذا الإعداد يكون off مبدئيًا إذا لم يُقدّم

تُتاح جميع المعاملات في القسم وكذلك الأقسام الفرعية للمزود.

المزود المبدئي وتفعيله

إذا لم يُفعل أي مزود صراحة، فيُفعل المزود المبدئي ضمنيًا. انظر OSSL_PROVIDER-default(7) لمزيد من التفاصيل.

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

  ضبط EVP
الاسم alg_section في قسم التهيئة يسمي القسم الذي يحتوي على الخصائص الخوارزمية عند استخدام واجهة برمجة تطبيقات EVP.

داخل قسم خصائص الخوارزمية، المعاني التالية تكون للأسماء:

default_properties
    قد تكون القيمة أي شيء مقبول كسلسلة استعلام عن الخصائص لدالة EVP_set_default_properties().

fips_mode (مهجور)
    القيمة هي قيمة منطقية يمكن أن تكون yes أو no. إذا كانت القيمة yes، فهذا يكافئ تمامًا:

     default_properties = fips=yes

    إذا كانت القيمة no، فلن يحدث شيء. استخدام هذا الاسم مهجور، وإذا استُخدم، فيجب أن يكون الاسم الوحيد في القسم.

  ضبط SSL
الاسم ssl_conf في قسم التهيئة يسمي القسم الذي يحتوي على قائمة بضبط SSL/TLS. وكما هو الحال مع المزودين، فإن كل اسم في هذا القسم يحدد قسمًا يحتوي على الضبط الخاص بهذا الاسم. على سبيل المثال:

 [ssl_configuration]
 server = server_tls_config
 client = client_tls_config
 system_default = tls_system_default

 [server_tls_config]
 ... configuration for SSL/TLS servers ...

 [client_tls_config]
 ... configuration for SSL/TLS clients ...

اسم الضبط system_default له معنى خاص. إذا كان موجودًا، فإنه يُطبق كلما أُنشئ كائن SSL_CTX. على سبيل المثال، لفرض حد أدنى من إصدارات بروتوكول TLS و DTLS على مستوى النظام:

 [tls_system_default]
 MinProtocol = TLSv1.2
 MinProtocol = DTLSv1.2

يُطبق الحد الأدنى لبروتوكول TLS على كائنات SSL_CTX القائمة على TLS، والحد الأدنى لبروتوكول DTLS على تلك القائمة على DTLS. ينطبق الأمر نفسه أيضًا على الإصدارات القصوى المحددة باستخدام MaxProtocol.

يتكون كل قسم ضبط من أزواج من الاسم/القيمة التي تُحلل بواسطة SSL_CONF_cmd(3)، والتي ستُستدعى بواسطة SSL_CTX_config() أو SSL_config()، بشكل مناسب. لاحظ أن أي محارف تسبق النقطة المبدئية في قسم الضبط تُتجاهل، بحيث يمكن استخدام الأمر نفسه لمرات متعددة. وربما يكون هذا أكثر فائدة لتحميل أنواع مفاتيح مختلفة، كما هو موضح هنا:

 [server_tls_config]
 RSA.Certificate = server-rsa.pem
 ECDSA.Certificate = server-ecdsa.pem

  ضبط المحرك
الاسم engines في قسم التهيئة يسمي القسم الذي يحتوي على قائمة بضبط ENGINE. وكما هو الحال مع المزودين، فإن كل اسم في هذا القسم يحدد محركًا بالضبط الخاص بذلك المحرك. يُستخدم القسم الخاص بالمحرك لتحديد كيفية تحميل المحرك، وتنشيطه، وضبط المعاملات الأخرى.

داخل قسم المحرك، المعاني التالية تكون للأسماء:

engine_id
    يُستخدم هذا لتحديد اسم بديل، متجاوزًا الاسم المبدئي المحدد في قائمة المحركات. إذا كان موجودًا، فيجب أن يكون أولًا. على سبيل المثال:

     [engines]
     foo = foo_engine

     [foo_engine]
     engine_id = myfoo

dynamic_path
    يحمل هذا ENGINE ويضيفه من المسار المعطى. وهو ما يعادل إرسال عناصر التحكم SO_PATH مع وسيط المسار متبوعًا بـ LIST_ADD بالقيمة 2 و LOAD إلى ENGINE الديناميكي. إذا لم يكن هذا هو السلوك المطلوب، فيمكن إرسال عناصر تحكم بديلة مباشرة إلى ENGINE الديناميكي باستخدام أوامر التحكم.

init
    يحدد هذا ما إذا كان سيتم تهيئة ENGINE. إذا كانت القيمة 0 فلن يُهيأ ENGINE، وإذا كانت القيمة 1 فستُجرى محاولة لتهيئة ENGINE فورًا. إذا لم يكن الأمر init موجودًا، فستُجرى محاولة لتهيئة ENGINE بعد معالجة جميع الأوامر في قسمه.

default_algorithms
    يضبط هذا الخوارزميات المبدئية التي سيوفرها ENGINE باستخدام الدالة ENGINE_set_default_string().

تُعتبر جميع الأسماء الأخرى بمثابة اسم لأمر تحكم يُرسل إلى ENGINE، والقيمة هي الوسيط الممرر مع الأمر. تعني القيمة الخاصة EMPTY أنه لن تُرسل أي قيمة مع الأمر. على سبيل المثال:

 [engines]
 foo = foo_engine

 [foo_engine]
 dynamic_path = /some/path/fooengine.so
 some_ctrl = some_value
 default_algorithms = ALL
 other_ctrl = EMPTY

  ضبط عشوائي
الاسم random في قسم التهيئة يسمي القسم الذي يحتوي على إعدادات مولد الأعداد العشوائية.

داخل القسم العشوائي، المعاني التالية تكون للأسماء:

random
    يُستخدم هذا لتحديد مولد البتات العشوائية. على سبيل المثال:

     [random]
     random = CTR-DRBG

    مولدات البتات العشوائية المتاحة هي:

    CTR-DRBG
    HASH-DRBG
    HMAC-DRBG

cipher
    يحدد هذا شفرة التعمية التي سيستخدمها مولد البتات العشوائية CTR-DRBG. تتجاهل مولدات البتات العشوائية الأخرى هذا الاسم. القيمة المبدئية هي AES-256-CTR.

digest
    يحدد هذا الخلاصة التي ستستخدمها مولدات البتات العشوائية HASH-DRBG أو HMAC-DRBG. تتجاهل مولدات البتات العشوائية الأخرى هذا الاسم.

properties
    يضبط هذا استعلام الخاصية المستخدم عند جلب مولد البتات العشوائية وأي خوارزميات أساسية.

seed
    يضبط هذا مصدر العشوائية الذي ينبغي استخدامه. مبدئيًا سيُستخدم SEED-SRC خارج مزود FIPS. يستخدم مزود FIPS عمليات استدعاء للوصول إلى مصادر العشوائية نفسها من خارج الحدود التي تم التحقق من صحتها.

seed_properties
    يضبط هذا استعلام الخاصية المستخدم عند جلب مصدر العشوائية.

random_provider
    يضبط هذا المزود لاستخدامه في استدعاءات RAND_bytes(3) بدلًا من مصادر الاعتلاج (الإنتروبيا) المدمجة. القيمة المبدئية هي "fips". إذا لم يُحمّل المزود المسمى، فستُستخدم مصادر الاعتلاج المدمجة.

أمثلة
يوضح هذا المثال كيفية استخدام الاقتباس والهروب.

 # This is the default section.
 HOME = /temp
 configdir = $ENV::HOME/config

 [ section_one ]
 # Quotes permit leading and trailing whitespace
 any = " any variable name "
 other = A string that can \
 cover several lines \
 by including \\ characters
 message = Hello World\n

 [ section_two ]
 greeting = $section_one::message

يوضح هذا المثال كيفية توسيع متغيرات البيئة بأمان. في هذا المثال، يُقصد بالمتغير tempfile الإشارة إلى ملف مؤقت، ويحدد متغير البيئة TEMP أو TMP، إذا كان موجودًا، الدليل الذي ينبغي وضع الملف فيه. وبما أنه يُفحص القسم المبدئي إذا لم يكن المتغير موجودًا، فإنه يمكن ضبط TMP ليكون مبدئيًا إلى /tmp، وضبط TEMP ليكون مبدئيًا إلى TMP.

 # These two lines must be in the default section.
 TMP = /tmp
 TEMP = $ENV::TMP

 # This can be used anywhere
 tmpfile = ${ENV::TEMP}/tmp.filename

يوضح هذا المثال كيفية فرض وضع FIPS للتطبيق sample.

 sample = fips_config

 [fips_config]
 alg_section = evp_properties

 [evp_properties]
 default_properties = "fips=yes"

البيئة

OPENSSL_CONF
    المسار إلى ملف الضبط، أو سلسلة فارغة للإشارة إلى عدم وجوده. يُتجاهل في برامج set-user-ID و set-group-ID.

OPENSSL_ENGINES
    المسار إلى دليل المحركات. يُتجاهل في برامج set-user-ID و set-group-ID.

OPENSSL_MODULES
    المسار إلى الدليل الذي يحتوي على وحدات OpenSSL، مثل المزودين. يُتجاهل في برامج set-user-ID و set-group-ID.

OPENSSL_CONF_INCLUDE
    المسار الاختياري لإضافته في بداية جميع مسارات .include.

العلل
لا توجد طريقة لتضمين المحارف باستخدام الصيغة الثمانية \nnn. السلاسل كلها تنتهي بمحرف فارغ (null) لذا لا يمكن للمحارف الفارغة أن تشكل جزءًا من القيمة.

الهروب ليس صحيحًا تمامًا: إذا كنت تريد استخدام تسلسلات مثل \n فلا يمكنك استخدام أي هروب بالاقتباس على السطر نفسه.

يمكن اعتبار القيد المتمثل في إمكانية فتح دليل واحد فقط وقراءته في المرة الواحدة بمثابة علة وينبغي إصلاحها.

التاريخ
استخدمت واجهة برمجة تطبيقات غير موثقة، وهي NCONF_WIN32()، مجموعة مختلفة قليلاً من قواعد التحليل التي كان الغرض منها مواءمتها مع منصة مايكروسوفت ويندوز. وتحديدًا، لم يكن محرف الشرطة المائلة العكسية محرف هروب وكان يمكن استخدامه في أسماء المسارات، ولم يُتعرف إلا على محرف علامة الاقتباس المزدوجة، وكانت التعليقات تبدأ بفاصلة منقوطة. هُجرت هذه الدالة في OpenSSL 3.0؛ وسيتعين تعديل التطبيقات التي تستخدم ملفات ضبطها تلك الصيغة.

انظر أيضًا
openssl-x509(1)، و openssl-req(1)، و openssl-ca(1)، و openssl-fipsinstall(1)، و ASN1_generate_nconf(3)، و EVP_set_default_properties(3)، و CONF_modules_load(3)، و CONF_modules_load_file(3)، و RAND_bytes(3)، و fips_config(5)، و x509v3_config(5).

حقوق النسخ
حقوق النشر 2000-2025 لمؤلفي مشروع OpenSSL. جميع الحقوق محفوظة.

مرخص بموجب رخصة Apache 2.0 (المشار إليها فيما يلي بـ ”الرخصة“). لا يجوز لك استخدام هذا الملف إلا وفقًا لشروط الرخصة. يمكنك الحصول على نسخة منها في الملف LICENSE الموجود في حزمة التوزيع المصدرية أو على الرابط <https://www.openssl.org/source/license.html>.

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.