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 كيلوبايت.

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

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

ضبط معرف كائن 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
    

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

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". إذا لم يُحمّل المزود المسمى، فستُستخدم مصادر الاعتلاج المدمجة.