توضیحات (DESCRIPTION)

از کتابخانه CONF مربوط به OpenSSL می‌توان برای خواندن فایل‌های پیکربندی استفاده کرد؛ ببینید CONF_modules_load_file(3). این کتابخانه برای فایل پیکربندی اصلی OpenSSL در مسیر /etc/ssl/openssl.cnf و در چند جای دیگر مانند فایل‌های افزونه گواهی برای ابزار کاربردی openssl(1) x509 استفاده می‌شود. برنامه‌های کاربردی OpenSSL همچنین می‌توانند از کتابخانه CONF برای مقاصد خاص خود استفاده کنند.

یک فایل پیکربندی به تعدادی بخش تقسیم می‌شود. هر بخش با یک خط [section_name] آغاز می‌شود و هنگامی که بخش جدیدی شروع شود یا به انتهای فایل برسد، پایان می‌یابد. نام بخش می‌تواند شامل نویسه‌های حرفی‌عددی و خط زیر (underscore) باشد.

نخستین بخش یک فایل پیکربندی ویژه است و با عنوان “بخش پیش‌فرض” شناخته می‌شود. این بخش معمولاً بی‌نام است و از ابتدای فایل تا نخستین بخش نام‌دار امتداد می‌یابد. هنگامی که یک نام جستجو می‌شود، ابتدا در یک بخش نام‌دار (در صورت وجود) و سپس در بخش پیش‌فرض جستجو می‌گردد.

محیط به بخشی به نام ENV نگاشت می‌شود.

توضیحات را می‌توان با قرار دادن نویسه ‘#’ در ابتدای آن‌ها درج کرد.

هر بخش در یک فایل پیکربندی از تعدادی جفت نام و مقدار به فرم name=value تشکیل شده است.

رشته name می‌تواند شامل هرگونه نویسه حرفی‌عددی و همچنین چند نماد نشانه‌گذاری مانند ‘.’ ‘,’ ‘;’ و ‘_’ باشد.

رشته value شامل رشته پس از نویسه ‘=’ تا انتهای خط است که فاصله‌های خالی ابتدایی و انتهایی آن حذف شده‌اند.

رشته مقدار دستخوش گسترش متغیرها می‌شود. این کار را می‌توان با گنجاندن زیررشته‌هایی به فرم $name یا ${name}: انجام داد؛ این کار مقدار متغیر نام‌برده را در بخش جاری جایگزین می‌کند. همچنین می‌توان با استفاده از نحو $section::name یا ${section::name} مقداری را از یک بخش دیگر جایگزین کرد. با استفاده از فرم $ENV::name, متغیرهای محیطی را می‌توان جایگزین کرد. همچنین می‌توان با استفاده از نام ENV::name به متغیرهای محیطی مقدار اختصاص داد. این روش در صورتی کار می‌کند که برنامه، متغیرهای محیطی را با استفاده از کتابخانه CONF جستجو کند، به جای اینکه مستقیماً تابع getenv(3) را فراخوانی نماید. طول رشته مقدار پس از گسترش متغیرها نباید از 64k تجاوز کند، در غیر این صورت خطا رخ خواهد داد.

می‌توان برخی نویسه‌ها را با استفاده از هر نوع نقل‌قول یا نویسه ‘\’ اسکیپ کرد. با قرار دادن نویسه ‘\’ به عنوان آخرین نویسه یک خط، یک رشته value می‌تواند در چندین خط گسترش یابد. علاوه بر این، دنباله‌های ‘\n’, ‘\r’, ‘\b’ و ‘\t’ شناخته می‌شوند.

پیکربندی کتابخانه OPENSSL (OPENSSL LIBRARY CONFIGURATION)

برنامه‌های کاربردی می‌توانند جنبه‌های خاصی از OpenSSL را به طور خودکار با استفاده از فایل پیکربندی اصلی OpenSSL، یا در صورت تمایل با یک فایل پیکربندی جایگزین، پیکربندی کنند. ابزار openssl(1) شامل این قابلیت است: هر زیردستور از فایل پیکربندی اصلی OpenSSL استفاده می‌کند، مگر اینکه در زیردستور از گزینه‌ای برای استفاده از یک فایل پیکربندی جایگزین استفاده شده باشد.

برای فعال‌سازی پیکربندی کتابخانه، بخش پیش‌فرض باید شامل یک خط مناسب باشد که به بخش اصلی پیکربندی اشاره کند. نام پیش‌فرض openssl_conf است که توسط ابزار openssl(1) استفاده می‌شود. سایر برنامه‌ها ممکن است از یک نام جایگزین مانند myapplication_conf استفاده کنند. تمام خطوط پیکربندی کتابخانه در بخش پیش‌فرض در ابتدای فایل پیکربندی ظاهر می‌شوند.

بخش پیکربندی باید شامل مجموعه‌ای از جفت‌های نام و مقدار باشد که حاوی اطلاعات پیکربندی ماژول خاص هستند. name نمایانگر نام ماژول پیکربندی است. معنای value به ماژول بستگی دارد: برای نمونه، ممکن است نمایانگر بخش پیکربندی دیگری باشد که حاوی اطلاعات خاص ماژول پیکربندی است. برای نمونه:

# The following line must be in the default section.
openssl_conf = openssl_init

[openssl_init]
oid_section = new_oids

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

ویژگی‌های هر ماژول پیکربندی در زیر شرح داده شده است.

ماژول پیکربندی شیء ASN1 (ASN1 Object Configuration Module)

این ماژول دارای نام oid_section است. مقدار این متغیر به بخشی اشاره می‌کند که شامل جفت‌های نام و مقدار از OIDها است: نامْ همان نام کوتاه و بلند OID است، و مقدارْ شکل عددی OID می‌باشد. اگرچه برخی از زیردستورهای ابزار openssl(1) از قبل قابلیت بخش ASN1 OBJECT مخصوص به خود را دارند، اما همه آن‌ها چنین قابلیتی ندارند. با استفاده از ماژول پیکربندی ASN1 OBJECT، همه زیردستورهای ابزار openssl(1) و همچنین هر برنامه سازگار می‌توانند اشیاء جدید را مشاهده کنند. برای نمونه:

[new_oids]
some_new_oid = 1.2.3.4
some_other_oid = 1.2.3.5

همچنین می‌توان مقدار را روی نام بلند تنظیم کرد که به دنبال آن یک کاما و شکل عددی OID قرار می‌گیرد. برای نمونه:

shortName = some object long name,
  1.2.3.4

فایل‌ها (FILES)

/etc/ssl/openssl.cnf: فایل پیکربندی استاندارد

مثال‌ها (EXAMPLES)

در اینجا یک نمونه فایل پیکربندی با استفاده از برخی ویژگی‌های ذکرشده در بالا آورده شده است:

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

[ section_one ]
# We are now in 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

مثال بعدی نحوه گسترش ایمن متغیرهای محیطی را نشان می‌دهد.

فرض کنید می‌خواهید متغیری به نام tmpfile به یک نام فایل موقت اشاره کند. دایرکتوری که فایل در آن قرار می‌گیرد می‌تواند توسط متغیرهای محیطی TEMP یا TMP تعیین شود، اما ممکن است این متغیرها روی هیچ مقداری تنظیم نشده باشند. اگر صرفاً نام متغیرهای محیطی را درج کنید و آن متغیر وجود نداشته باشد، هنگام تلاش برای بارگذاری فایل پیکربندی خطایی رخ خواهد داد. با استفاده از بخش پیش‌فرض می‌توان هر دو مقدار را جستجو کرد، به گونه‌ای که TEMP دارای اولویت باشد و در صورتی که هیچ‌یک تعریف نشده باشند، از /tmp استفاده شود:

TMP=/tmp
# The above value is used if TMP isn't in the environment
TEMP=$ENV::TMP
# The above value is used if TEMP isn't in the environment
tmpfile=${ENV::TEMP}/tmp.filename

پیکربندی پیچیده‌تر کتابخانه OpenSSL. افزودن OID:

# Default appname: should match "appname" parameter (if any)
# supplied to CONF_modules_load_file et al.
openssl_conf = openssl_conf_section

[openssl_conf_section]
# Configuration module list
oid_section = new_oids

[new_oids]
# New OID, just short name
newoid1 = 1.2.3.4.1
# New OID shortname and long name
newoid2 = New OID 2 long name, 1.2.3.4.2

در صورتی که "openssl_conf" برای مطابقت با "appname" مناسب اصلاح شود، مثال‌های بالا را می‌توان با هر برنامه‌ای که از پیکربندی کتابخانه پشتیبانی می‌کند استفاده کرد.

برای نمونه، اگر فایل نمونه دوم در بالا با نام "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

که نشان می‌دهد OID با عنوان "newoid1" به صورت "1.2.3.4.1" اضافه شده است.

همچنین ببینید (SEE ALSO)

openssl(1), CONF_modules_load_file(3), OPENSSL_config(3), x509v3.cnf(5)

هشدارها (CAVEATS)

اگر یک فایل پیکربندی برای گسترش متغیری که وجود ندارد تلاش کند، خطایی علامت‌گذاری شده و فایل بارگذاری نخواهد شد. این امر همچنین ممکن است هنگام تلاش برای گسترش یک متغیر محیطی که وجود ندارد رخ دهد. برای نمونه، در نسخه‌های پیشین OpenSSL، فایل پیکربندی اصلی و پیش‌فرض OpenSSL از مقدار HOME استفاده می‌کرد که ممکن است در سیستم‌های غیر یونیکس تعریف نشده باشد و موجب بروز خطا می‌شد.

این مشکل را می‌توان با گنجاندن یک بخش پیش‌فرض برای ارائه یک مقدار پیش‌فرض برطرف کرد: در این صورت، اگر جستجوی محیط ناموفق باشد، مقدار پیش‌فرض به جای آن استفاده خواهد شد. برای اینکه این سازوکار به درستی کار کند، مقدار پیش‌فرض باید قبل از گسترش در فایل پیکربندی تعریف شده باشد. برای مشاهده نمونه‌ای از نحوه انجام این کار، به بخش مثال‌ها (EXAMPLES) مراجعه کنید.

اگر یک متغیر بیش از یک بار در همان بخش تعریف شود، تمامی مقادیر به جز آخرین مقدار نادیده گرفته خواهند شد. در شرایط خاص مانند DNها، ممکن است یک فیلد چندین بار تکرار شود. این مسئله معمولاً با نادیده گرفتن نویسه‌های پیش از یک ‘.’ ابتدایی برطرف می‌شود، برای نمونه:

1.OU="My first OU"
2.OU="My Second OU"

اشکالات (BUGS)

در حال حاضر هیچ روشی برای گنجاندن نویسه‌ها با استفاده از قالب هشت‌هشتی \nnn وجود ندارد. تمام رشته‌ها با NUL خاتمه می‌یابند، بنابراین بایت‌های NUL نمی‌توانند بخشی از مقدار را تشکیل دهند.

اسکیپ کردن نویسه‌ها کاملاً بی‌نقص نیست: اگر می‌خواهید از دنباله‌هایی مانند ‘\n’ استفاده کنید، نمی‌توانید از هیچ‌گونه گریزدهی با نقل‌قول در همان خط استفاده نمایید.

فایل‌ها در یک گذر (single pass) بارگذاری می‌شوند. این بدان معناست که گسترش متغیر تنها در صورتی کار خواهد کرد که متغیرهای ارجاع‌شده در نقطه‌ای پیش‌تر در فایل تعریف شده باشند.