.\" $OpenBSD: openssl.cnf.5,v 1.11 2024/07/08 15:02:28 jmc Exp $ .\" full merge up to: OpenSSL man5/config b53338cb Feb 28 12:30:28 2017 +0100 .\" selective merge up to: OpenSSL a8c5ed81 Jul 18 13:57:25 2017 -0400 .\" .\" This file was written by Dr. Stephen Henson . .\" Copyright (c) 1999, 2000, 2004, 2013, 2015, 2016, 2017 The OpenSSL Project. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" 3. All advertising materials mentioning features or use of this .\" software must display the following acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" .\" .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to .\" endorse or promote products derived from this software without .\" prior written permission. For written permission, please contact .\" openssl-core@openssl.org. .\" .\" 5. Products derived from this software may not be called "OpenSSL" .\" nor may "OpenSSL" appear in their names without prior written .\" permission of the OpenSSL Project. .\" .\" 6. Redistributions of any form whatsoever must retain the following .\" acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" .\" .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: July 8 2024 $ .Dt OPENSSL.CNF 5 .Os .SH "نام (NAME)" libressl-openssl.cnf \- فایل پیکربندی کتابخانه رمزنگاری LibreSSL .Sh "توضیحات (DESCRIPTION)" از کتابخانه CONF مربوط به OpenSSL می‌توان برای خواندن فایل‌های پیکربندی استفاده کرد؛ ببینید .Xr CONF_modules_load_file 3 . این کتابخانه برای فایل پیکربندی اصلی OpenSSL در مسیر .Pa /etc/ssl/openssl.cnf و در چند جای دیگر مانند فایل‌های افزونه گواهی برای ابزار کاربردی .Xr openssl 1 .Cm x509 استفاده می‌شود. برنامه‌های کاربردی OpenSSL همچنین می‌توانند از کتابخانه CONF برای مقاصد خاص خود استفاده کنند. .Pp یک فایل پیکربندی به تعدادی بخش تقسیم می‌شود. هر بخش با یک خط .Bq Ar section_name آغاز می‌شود و هنگامی که بخش جدیدی شروع شود یا به انتهای فایل برسد، پایان می‌یابد. نام بخش می‌تواند شامل نویسه‌های حرفی‌عددی و خط زیر (underscore) باشد. .Pp نخستین بخش یک فایل پیکربندی ویژه است و با عنوان .Dq بخش پیش‌فرض شناخته می‌شود. این بخش معمولاً بی‌نام است و از ابتدای فایل تا نخستین بخش نام‌دار امتداد می‌یابد. هنگامی که یک نام جستجو می‌شود، ابتدا در یک بخش نام‌دار (در صورت وجود) و سپس در بخش پیش‌فرض جستجو می‌گردد. .Pp محیط به بخشی به نام .Ic ENV نگاشت می‌شود. .Pp توضیحات را می‌توان با قرار دادن نویسه .Ql # در ابتدای آن‌ها درج کرد. .Pp هر بخش در یک فایل پیکربندی از تعدادی جفت نام و مقدار به فرم .Ar name Ns = Ns Ar value تشکیل شده است. .Pp رشته .Ar name می‌تواند شامل هرگونه نویسه حرفی‌عددی و همچنین چند نماد نشانه‌گذاری مانند .Ql \&. .Ql \&, .Ql \&; و .Ql _ باشد. .Pp رشته .Ar value شامل رشته پس از نویسه .Ql = تا انتهای خط است که فاصله‌های خالی ابتدایی و انتهایی آن حذف شده‌اند. .Pp رشته مقدار دستخوش گسترش متغیرها می‌شود. این کار را می‌توان با گنجاندن زیررشته‌هایی به فرم .Pf $ Ar name یا .Pf $ Brq Ar name : انجام داد؛ این کار مقدار متغیر نام‌برده را در بخش جاری جایگزین می‌کند. همچنین می‌توان با استفاده از نحو .Pf $ Ar section Ns :: Ns Ar name یا .Pf $ Brq Ar section Ns :: Ns Ar name مقداری را از یک بخش دیگر جایگزین کرد. با استفاده از فرم .Pf $ Ic ENV Ns :: Ns Ar name , متغیرهای محیطی را می‌توان جایگزین کرد. همچنین می‌توان با استفاده از نام .Ic ENV Ns :: Ns Ar name به متغیرهای محیطی مقدار اختصاص داد. این روش در صورتی کار می‌کند که برنامه، متغیرهای محیطی را با استفاده از کتابخانه CONF جستجو کند، به جای اینکه مستقیماً تابع .Xr getenv 3 را فراخوانی نماید. طول رشته مقدار پس از گسترش متغیرها نباید از 64k تجاوز کند، در غیر این صورت خطا رخ خواهد داد. .Pp می‌توان برخی نویسه‌ها را با استفاده از هر نوع نقل‌قول یا نویسه .Ql \e اسکیپ کرد. با قرار دادن نویسه .Ql \e به عنوان آخرین نویسه یک خط، یک رشته .Ar value می‌تواند در چندین خط گسترش یابد. علاوه بر این، دنباله‌های .Ql \en , .Ql \er , .Ql \eb و .Ql \et شناخته می‌شوند. .Sh "پیکربندی کتابخانه OPENSSL (OPENSSL LIBRARY CONFIGURATION)" برنامه‌های کاربردی می‌توانند جنبه‌های خاصی از OpenSSL را به طور خودکار با استفاده از فایل پیکربندی اصلی OpenSSL، یا در صورت تمایل با یک فایل پیکربندی جایگزین، پیکربندی کنند. ابزار .Xr openssl 1 شامل این قابلیت است: هر زیردستور از فایل پیکربندی اصلی OpenSSL استفاده می‌کند، مگر اینکه در زیردستور از گزینه‌ای برای استفاده از یک فایل پیکربندی جایگزین استفاده شده باشد. .Pp برای فعال‌سازی پیکربندی کتابخانه، بخش پیش‌فرض باید شامل یک خط مناسب باشد که به بخش اصلی پیکربندی اشاره کند. نام پیش‌فرض .Ic openssl_conf است که توسط ابزار .Xr openssl 1 استفاده می‌شود. سایر برنامه‌ها ممکن است از یک نام جایگزین مانند .Sy myapplication_conf استفاده کنند. تمام خطوط پیکربندی کتابخانه در بخش پیش‌فرض در ابتدای فایل پیکربندی ظاهر می‌شوند. .Pp بخش پیکربندی باید شامل مجموعه‌ای از جفت‌های نام و مقدار باشد که حاوی اطلاعات پیکربندی ماژول خاص هستند. .Ar name نمایانگر نام ماژول پیکربندی است. معنای .Ar value به ماژول بستگی دارد: برای نمونه، ممکن است نمایانگر بخش پیکربندی دیگری باشد که حاوی اطلاعات خاص ماژول پیکربندی است. برای نمونه: .Bd -literal -offset indent # The following line must be in the default section. openssl_conf = openssl_init [openssl_init] oid_section = new_oids [new_oids] \&... new oids here ... .Ed .Pp ویژگی‌های هر ماژول پیکربندی در زیر شرح داده شده است. .Ss "ماژول پیکربندی شیء ASN1 (ASN1 Object Configuration Module)" این ماژول دارای نام .Ic oid_section است. مقدار این متغیر به بخشی اشاره می‌کند که شامل جفت‌های نام و مقدار از OIDها است: نامْ همان نام کوتاه و بلند OID است، و مقدارْ شکل عددی OID می‌باشد. اگرچه برخی از زیردستورهای ابزار .Xr openssl 1 از قبل قابلیت بخش ASN1 OBJECT مخصوص به خود را دارند، اما همه آن‌ها چنین قابلیتی ندارند. با استفاده از ماژول پیکربندی ASN1 OBJECT، همه زیردستورهای ابزار .Xr openssl 1 و همچنین هر برنامه سازگار می‌توانند اشیاء جدید را مشاهده کنند. برای نمونه: .Bd -literal -offset indent [new_oids] some_new_oid = 1.2.3.4 some_other_oid = 1.2.3.5 .Ed .Pp همچنین می‌توان مقدار را روی نام بلند تنظیم کرد که به دنبال آن یک کاما و شکل عددی OID قرار می‌گیرد. برای نمونه: .Pp .Dl shortName = some object long name, 1.2.3.4 .Sh "فایل‌ها (FILES)" .Bl -tag -width /etc/ssl/openssl.cnf -compact .It Pa /etc/ssl/openssl.cnf فایل پیکربندی استاندارد .El .Sh "مثال‌ها (EXAMPLES)" در اینجا یک نمونه فایل پیکربندی با استفاده از برخی ویژگی‌های ذکرشده در بالا آورده شده است: .Bd -literal -offset indent # 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 \e cover several lines \e by including \e\e characters message = Hello World\en [ section_two ] greeting = $section_one::message .Ed .Pp مثال بعدی نحوه گسترش ایمن متغیرهای محیطی را نشان می‌دهد. .Pp فرض کنید می‌خواهید متغیری به نام .Sy tmpfile به یک نام فایل موقت اشاره کند. دایرکتوری که فایل در آن قرار می‌گیرد می‌تواند توسط متغیرهای محیطی .Ev TEMP یا .Ev TMP تعیین شود، اما ممکن است این متغیرها روی هیچ مقداری تنظیم نشده باشند. اگر صرفاً نام متغیرهای محیطی را درج کنید و آن متغیر وجود نداشته باشد، هنگام تلاش برای بارگذاری فایل پیکربندی خطایی رخ خواهد داد. با استفاده از بخش پیش‌فرض می‌توان هر دو مقدار را جستجو کرد، به گونه‌ای که .Ev TEMP دارای اولویت باشد و در صورتی که هیچ‌یک تعریف نشده باشند، از .Pa /tmp استفاده شود: .Bd -literal -offset indent 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 .Ed .Pp پیکربندی پیچیده‌تر کتابخانه OpenSSL. افزودن OID: .Bd -literal -offset indent # 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 .Ed .Pp در صورتی که "openssl_conf" برای مطابقت با "appname" مناسب اصلاح شود، مثال‌های بالا را می‌توان با هر برنامه‌ای که از پیکربندی کتابخانه پشتیبانی می‌کند استفاده کرد. .Pp برای نمونه، اگر فایل نمونه دوم در بالا با نام "example.cnf" ذخیره شود، آنگاه خط فرمان: .Pp .Dl OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1 .Pp خروجی زیر را خواهد داد: .Dl 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1 .Pp که نشان می‌دهد OID با عنوان "newoid1" به صورت "1.2.3.4.1" اضافه شده است. .Sh "همچنین ببینید (SEE ALSO)" .Xr openssl 1 , .Xr CONF_modules_load_file 3 , .Xr OPENSSL_config 3 , .Xr x509v3.cnf 5 .Sh "هشدارها (CAVEATS)" اگر یک فایل پیکربندی برای گسترش متغیری که وجود ندارد تلاش کند، خطایی علامت‌گذاری شده و فایل بارگذاری نخواهد شد. این امر همچنین ممکن است هنگام تلاش برای گسترش یک متغیر محیطی که وجود ندارد رخ دهد. برای نمونه، در نسخه‌های پیشین OpenSSL، فایل پیکربندی اصلی و پیش‌فرض OpenSSL از مقدار .Ev HOME استفاده می‌کرد که ممکن است در سیستم‌های غیر یونیکس تعریف نشده باشد و موجب بروز خطا می‌شد. .Pp این مشکل را می‌توان با گنجاندن یک بخش پیش‌فرض برای ارائه یک مقدار پیش‌فرض برطرف کرد: در این صورت، اگر جستجوی محیط ناموفق باشد، مقدار پیش‌فرض به جای آن استفاده خواهد شد. برای اینکه این سازوکار به درستی کار کند، مقدار پیش‌فرض باید قبل از گسترش در فایل پیکربندی تعریف شده باشد. برای مشاهده نمونه‌ای از نحوه انجام این کار، به بخش .Sx "مثال‌ها (EXAMPLES)" مراجعه کنید. .Pp اگر یک متغیر بیش از یک بار در همان بخش تعریف شود، تمامی مقادیر به جز آخرین مقدار نادیده گرفته خواهند شد. در شرایط خاص مانند DNها، ممکن است یک فیلد چندین بار تکرار شود. این مسئله معمولاً با نادیده گرفتن نویسه‌های پیش از یک .Ql \&. ابتدایی برطرف می‌شود، برای نمونه: .Bd -literal -offset indent 1.OU="My first OU" 2.OU="My Second OU" .Ed .Sh "اشکالات (BUGS)" در حال حاضر هیچ روشی برای گنجاندن نویسه‌ها با استفاده از قالب هشت‌هشتی .Pf \e Ar nnn وجود ندارد. تمام رشته‌ها با NUL خاتمه می‌یابند، بنابراین بایت‌های NUL نمی‌توانند بخشی از مقدار را تشکیل دهند. .Pp اسکیپ کردن نویسه‌ها کاملاً بی‌نقص نیست: اگر می‌خواهید از دنباله‌هایی مانند .Ql \en استفاده کنید، نمی‌توانید از هیچ‌گونه گریزدهی با نقل‌قول در همان خط استفاده نمایید. .Pp فایل‌ها در یک گذر (single pass) بارگذاری می‌شوند. این بدان معناست که گسترش متغیر تنها در صورتی کار خواهد کرد که متغیرهای ارجاع‌شده در نقطه‌ای پیش‌تر در فایل تعریف شده باشند.