X509V3.CNF(5) File Formats Manual X509V3.CNF(5)

x509v3.cnf — ساختار پیکربندی افزونه‌های گواهی X.509 نسخه ۳

چندین ابزار کاربردی OpenSSL می‌توانند بر اساس محتویات یک فایل پیکربندی، افزونه‌هایی را به یک گواهی یا درخواست گواهی اضافه کنند. قالب فایل بر اساس قالب openssl.cnf(5) است.

به طور معمول برنامه شامل گزینه‌ای برای اشاره به یک بخش افزونه خواهد بود. هر خط از بخش افزونه به شکل زیر است:

extension_name=[critical,] extension_options

اگر critical وجود داشته باشد، آنگاه افزونه حیاتی (بحرانی) خواهد بود.

قالب extension_options بستگی به مقدار extension_name دارد.

چهار نوع اصلی افزونه وجود دارد: افزونه‌های رشته‌ای، افزونه‌های چندمقداری، افزونه‌های خام، و افزونه‌های اختیاری (دلخواه).

افزونه‌های رشته‌ای صرفاً دارای یک رشته متنی هستند که خود مقدار یا نحوه دستیابی به آن را در بر دارد. برای نمونه:

nsComment="This is a Comment"

افزونه‌های چندمقداری دارای یک فرم کوتاه و یک فرم طولانی هستند. فرم کوتاه فهرستی از نام‌ها و مقادیر است:

basicConstraints=critical,CA:true,pathlen:1

فرم طولانی اجازه می‌دهد مقادیر در یک بخش جداگانه قرار گیرند:

basicConstraints=critical,@bs_section

[bs_section]
CA=true
pathlen=1

هر دو فرم معادل یکدیگر هستند.

ساختار نحو افزونه‌های خام توسط کد افزونه کنترل می‌شود؛ برای نمونه می‌تواند حاوی داده‌هایی در چندین بخش باشد. نحو صحیح مورد استفاده توسط خود کد افزونه تعریف می‌شود؛ برای نمونه افزونه سیاست‌های گواهی را بررسی کنید.

اگر نوع افزونه‌ای پشتیبانی نشود، باید از نحو افزونه اختیاری استفاده شود؛ برای جزئیات بیشتر به بخش افزونه‌های اختیاری و دلخواه (ARBITRARY EXTENSIONS) مراجعه کنید.

بخش‌های زیر هر یک از افزونه‌های پشتیبانی‌شده را با جزئیات شرح می‌دهند.

این یک افزونه چندمقداری است که مشخص می‌کند آیا یک گواهی متعلق به مرجع صدور گواهی (CA) است یا خیر. اولین نام (اجباری) CA است که به دنبال آن TRUE یا FALSE می‌آید. اگر CA برابر با TRUE باشد، یک نام اختیاری pathlen به همراه یک مقدار نامنفی می‌تواند گنجانده شود. برای نمونه:

basicConstraints=CA:TRUE
basicConstraints=CA:FALSE
basicConstraints=critical,CA:TRUE, pathlen:0

یک گواهی CA باید مقدار basicConstraints را با فیلد CA تنظیم‌شده روی TRUE شامل شود. یک گواهی کاربر نهایی باید CA را روی FALSE قرار دهد یا این افزونه را به کلی حذف کند. برخی نرم‌افزارها ممکن است برای گواهی‌های موجودیت نهایی درج basicConstraints با CA تنظیم‌شده روی FALSE را الزامی بدانند.

پارامتر pathlen حداکثر تعداد CAهایی را که می‌توانند در یک زنجیره در سطوح پایین‌تر از این CA قرار گیرند مشخص می‌کند. بنابراین اگر یک CA با pathlen برابر با صفر داشته باشید، این CA تنها برای امضای گواهی‌های کاربران نهایی قابل استفاده است و نه CAهای دیگر.

کاربرد کلید یک افزونه چندمقداری شامل فهرستی از نام‌های کاربردهای مجاز کلید است.

نام‌های پشتیبانی‌شده عبارتند از: digitalSignature ، nonRepudiation ، keyEncipherment ، dataEncipherment ، keyAgreement ، keyCertSign ، cRLSign ، encipherOnly و decipherOnly. نمونه‌ها:

keyUsage=digitalSignature, nonRepudiation
keyUsage=critical, keyCertSign

این افزونه شامل فهرستی از اهدافی است که کلید عمومی گواهی می‌تواند برای آن‌ها استفاده شود.

این موارد می‌توانند نام‌های کوتاه شیء یا فرم عددی نقطه‌دار OIDها باشند. در حالی که هر OIDای می‌تواند استفاده شود، تنها مقادیر خاصی معنا دارند. به‌ویژه مقادیر زیر از PKIX، NS و MS معنادار هستند:

مقدار مفهوم
احراز هویت سرور TLS
احراز هویت کلاینت TLS
امضای کد
محافظت از رایانامه (S/MIME)
برچسب زمانی معتبر
امضای OCSP
تبادل کلید اینترنتی IPsec
امضای کد اختصاصی مایکروسافت (authenticode)
امضای کد تجاری مایکروسافت (authenticode)
امضای فهرست اعتماد مایکروسافت
سیستم‌فایل رمزگذاری‌شده مایکروسافت

نمونه‌ها:

extendedKeyUsage=critical,codeSigning,1.2.3.4
extendedKeyUsage=serverAuth,clientAuth

این در واقع یک افزونه رشته‌ای است و می‌تواند دو مقدار ممکن داشته باشد: یا کلمه hash که به طور خودکار از رهنمودهای RFC 3280 پیروی خواهد کرد، یا یک رشته هگزادسیمال که مقدار افزونه را مشخص می‌کند. استفاده از رشته هگزادسیمال شدیداً نهی می‌شود. نمونه:

subjectKeyIdentifier=hash

افزونه شناسه کلید مرجع صدور دو گزینه را می‌پذیرد: keyid و issuer ؛ هر دو می‌توانند مقدار اختیاری always را دریافت کنند.

اگر گزینه keyid حاضر باشد، تلاشی برای کپی کردن شناسه کلید موضوع از گواهی والد صورت می‌گیرد. اگر مقدار always حاضر باشد، در صورت ناموفق بودن گزینه، خطا بازگردانده می‌شود.

گزینه issuer صادرکننده و شماره سریال را از گواهی صادرکننده کپی می‌کند. این کار تنها زمانی انجام می‌شود که گزینه keyid با شکست مواجه شود یا درج نشده باشد، مگر اینکه پرچم always همواره مقدار را شامل شود. نمونه:

authorityKeyIdentifier=keyid,issuer

افزونه نام جایگزین موضوع امکان درج مقادیر مختلفی را در فایل پیکربندی فراهم می‌کند. این موارد شامل email (آدرس ایمیل)، URI (نشانگر یکنواخت منابع)، DNS (نام دامنه DNS)، RID (یک شناسه ثبت‌شده: OBJECT IDENTIFIER)، IP (آدرس IP)، dirName (نام متمایز یا distinguished name) و otherName هستند.

گزینه email می‌تواند شامل یک مقدار ویژه به نام copy باشد. این کار به طور خودکار هرگونه آدرس ایمیل موجود در نام موضوع گواهی را در افزونه درج می‌کند.

آدرس IP مورد استفاده در گزینه‌های IP می‌تواند در قالب IPv4 یا IPv6 باشد.

مقدار dirName باید به بخشی اشاره کند که حاوی نام متمایز به صورت مجموعه‌ای از جفت‌های نام و مقدار است. AVAs با چندین مقدار را می‌توان با افزودن پیشوند نویسه ‘+’ به ابتدای نام ایجاد کرد.

گزینه otherName می‌تواند داده‌های اختیاری مرتبط با یک OID را شامل شود: مقدار باید OID به همراه یک سمی‌کولن و محتوا در قالب استاندارد ASN1_generate_nconf(3) باشد. نمونه‌ها:

subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here
subjectAltName=IP:192.168.7.1
subjectAltName=IP:13::17
subjectAltName=email:my@other.address,RID:1.2.3.4
subjectAltName=otherName:1.2.3.4;UTF8:some other identifier

subjectAltName=dirName:dir_sect

[dir_sect]
C=UK
O=My Organization
OU=My Unit
CN=My Name

گزینه نام جایگزین صادرکننده از تمامی گزینه‌های لفظی نام جایگزین موضوع پشتیبانی می‌کند. این گزینه از email:copy پشتیبانی نمی‌کند زیرا کاربردی نخواهد داشت. در عوض از یک گزینه اضافی issuer:copy پشتیبانی می‌کند که تمام مقادیر نام جایگزین موضوع را از گواهی صادرکننده (در صورت امکان) کپی خواهد کرد. نمونه:

issuerAltName = issuer:copy

افزونه دسترسی به اطلاعات مرجع صدور، جزئیاتی را درباره نحوه دسترسی به اطلاعات مشخص مربوط به CA ارائه می‌دهد. نحو آن به صورت accessOID; location است که در آن location همان نحو نام جایگزین موضوع را دارد (به جز اینکه email:copy پشتیبانی نمی‌شود). پارامتر accessOID می‌تواند هر OID معتبری باشد اما تنها مقادیر معینی معنادار هستند، برای نمونه OCSP و caIssuers. نمونه:

authorityInfoAccess = OCSP;URI:http://ocsp.my.host
authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html

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

برای یک جفت name:value یک DistributionPoint جدید با فیلد fullName تنظیم‌شده روی مقدار داده‌شده ایجاد می‌شود و هر دو فیلد cRLissuer و reasons در این حالت حذف می‌شوند.

در حالت تک‌گزینه‌ای، بخش مشخص‌شده حاوی مقادیر برای هر فیلد است. در این بخش:

اگر نام fullname باشد، فیلد مقدار باید شامل نام کامل نقطه توزیع در همان قالب نام جایگزین موضوع باشد.

اگر نام relativename باشد، فیلد مقدار باید حاوی نام بخشی باشد که محتویات آن نمایانگر یک قطعه DN برای قرار گرفتن در این فیلد است.

نام CRLIssuer در صورت وجود، باید حاوی مقداری برای این فیلد در قالب نام جایگزین موضوع باشد.

اگر نام reasons باشد، فیلد مقدار باید شامل یک فیلد جداشده با کاما حاوی دلایل باشد. دلایل معتبر عبارتند از: keyCompromise ، CACompromise ، affiliationChanged ، superseded ، cessationOfOperation ، certificateHold ، privilegeWithdrawn و AACompromise.

نمونه‌های ساده:

crlDistributionPoints=URI:http://myhost.com/myca.crl
crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl

نمونه کامل نقطه توزیع:

crlDistributionPoints=crldp1_section

[crldp1_section]
fullname=URI:http://myhost.com/myca.crl
CRLissuer=dirName:issuer_sect
reasons=keyCompromise, CACompromise

[issuer_sect]
C=UK
O=Organisation
CN=Some Name

این افزونه تنها باید در CRLها ظاهر شود. این یک افزونه چندمقداری است که نحو آن با چند تفاوت مشابه "بخش" مورد اشاره در افزونه نقاط توزیع CRL است.

نام‌های reasons و CRLissuer شناخته‌شده نیستند.

نام onlysomereasons پذیرفته می‌شود که این فیلد را تنظیم می‌کند. مقدار در همان قالب فیلد reasons در نقطه توزیع CRL است.

نام‌های onlyuser ، onlyCA ، onlyAA و indirectCRL نیز پذیرفته می‌شوند. مقادیر باید مقادیر بولی (TRUE یا FALSE) باشند تا مقدار فیلد متناظر را نشان دهند. نمونه:

issuingDistributionPoint=critical, @idp_section

[idp_section]
fullname=URI:http://myhost.com/myca.crl
indirectCRL=TRUE
onlysomereasons=keyCompromise, CACompromise

[issuer_sect]
C=UK
O=Organisation
CN=Some Name

این یک افزونه خام است. تمام فیلدهای این افزونه را می‌توان با استفاده از نحو مناسب تنظیم کرد.

اگر از توصیه‌های PKIX پیروی می‌کنید و تنها از یک OID استفاده می‌نمایید، کافی است مقدار آن OID را درج کنید. چندین OID را می‌توان با کاما جدا کرد، برای نمونه:

certificatePolicies= 1.2.4.5, 1.1.3.4

اگر می‌خواهید واجد شرایط‌ها (qualifiers) را بگنجانید، OID سیاست و واجد شرایط‌ها باید در بخشی جداگانه مشخص شوند؛ این کار با استفاده از نحو @section به جای مقدار OID انجام می‌شود.

بخش مورد اشاره باید شامل OID سیاست با استفاده از نام policyIdentifier باشد. واجد شرایط‌های CPSuri را می‌توان با استفاده از نحو زیر گنجاند:

CPS.nnn=value

واجد شرایط‌های userNotice را می‌توان با نحو زیر تنظیم کرد:

userNotice.nnn=@notice

مقدار واجد شرایط userNotice در بخش مربوطه مشخص می‌شود. این بخش می‌تواند گزینه‌های explicitText ، organization و noticeNumbers را شامل شود. گزینه‌های explicitText و organization رشته‌های متنی هستند، و noticeNumbers فهرستی جداشده با کاما از اعداد است. گزینه‌های organization و noticeNumbers (در صورت گنجانده شدن) باید هر دو حاضر باشند. اگر از گزینه userNotice همراه با IE5 استفاده می‌کنید، به گزینه ia5org در بالاترین سطح برای اصلاح کدگذاری نیاز دارید، در غیر این صورت به درستی تفسیر نخواهد شد. نمونه:

certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect

[polsect]
policyIdentifier = 1.3.5.8
CPS.1="http://my.host.name"
CPS.2="http://my.your.name"
userNotice.1=@notice

[notice]
explicitText="Explicit Text Here"
organization="Organisation Name"
noticeNumbers=1,2,3,4

گزینه ia5org نوع فیلد organization را تغییر می‌دهد. در RFC 2459، تنها می‌تواند از نوع DisplayText باشد. در RFC 3280، نوع IA5String نیز مجاز است. برخی نرم‌افزارها (برای نمونه برخی نسخه‌های MSIE) ممکن است به ia5org نیاز داشته باشند.

این یک افزونه چندمقداری شامل نام‌های requireExplicitPolicy یا inhibitPolicyMapping و یک مقدار عدد صحیح نامنفی است. حداقل یک مؤلفه باید حضور داشته باشد. نمونه:

policyConstraints = requireExplicitPolicy:3

این یک افزونه رشته‌ای است که مقدار آن باید یک عدد صحیح نامنفی باشد. نمونه:

inhibitAnyPolicy = 2

افزونه محدودیت‌های نام یک افزونه چندمقداری است. نام باید با کلمه permitted یا excluded شروع شده و پس از آن یک سمی‌کولن بیاید. بقیه نام و مقدار از نحو subjectAltName پیروی می‌کند، به جز اینکه email:copy پشتیبانی نمی‌شود و فرم IP باید شامل آدرس IP و ماسک زیرشبکه جداشده با یک اسلش باشد. نمونه‌ها:

nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
nameConstraints=permitted;email:.somedomain.com
nameConstraints=excluded;email:.com

افزونه عدم بررسی OCSP یک افزونه رشته‌ای است، اما مقدار آن نادیده گرفته می‌شود. نمونه:

noCheck = ignored

این یک افزونه چندمقداری متشکل از فهرستی از شناسه‌های افزونه TLS است. هر شناسه می‌تواند عددی در محدوده ۰ تا ۶۵۵۳۵ یا یک نام پشتیبانی‌شده باشد. هنگامی که یک کلاینت TLS افزونه فهرست‌شده‌ای را ارسال می‌کند، از سرور TLS انتظار می‌رود آن افزونه را در پاسخ خود بگنجاند.

نام‌های پشتیبانی‌شده عبارتند از: status_request و status_request_v2. نمونه:

tlsfeature = status_request

افزونه‌های زیر غیراستاندارد، مختص نت‌اسکیپ و تا حد زیادی منسوخ هستند. استفاده از آن‌ها در برنامه‌های جدید توصیه نمی‌شود.

کامنت نت‌اسکیپ (nsComment) یک افزونه رشته‌ای حاوی توضیحی است که هنگام مشاهده گواهی در برخی مرورگرها نمایش داده می‌شود. نمونه:

nsComment = Some Random Comment

سایر افزونه‌های پشتیبانی‌شده در این دسته عبارتند از: nsBaseUrl ، nsRevocationUrl ، nsCaRevocationUrl ، nsRenewalUrl ، nsCaPolicyUrl و nsSslServerName.

این یک افزونه چندمقداری متشکل از فهرستی از پرچم‌ها برای گنجاندن است. برای تعیین اهدافی که گواهی می‌تواند برای آن‌ها استفاده شود به کار می‌رفت. امروزه به جای آن از افزونه‌های basicConstraints ، keyUsage و کاربرد گسترش‌یافته کلید استفاده می‌شود.

مقادیر قابل قبول برای nsCertType عبارتند از: client ، server ، email ، objsign ، reserved ، sslCA ، emailCA ، objCA.

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

دو روش برای کدگذاری افزونه‌های دلخواه وجود دارد.

روش اول استفاده از کلمه ASN1 و سپس محتوای افزونه با استفاده از همان نحو ASN1_generate_nconf(3) است. برای نمونه:

1.2.3.4=critical,ASN1:UTF8String:Some random data
1.2.3.4=ASN1:SEQUENCE:seq_sect

[seq_sect]
field1 = UTF8:field1
field2 = UTF8:field2

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

1.2.3.4=critical,DER:01:02:03:04
1.2.3.4=DER:01020304

مقدار پس از DER یک دامپ هگزادسیمال از کدگذاری DER افزونه است. هر افزونه‌ای را می‌توان در این فرم قرار داد تا رفتار پیش‌فرض بازنویسی شود. برای نمونه:

basicConstraints=critical,DER:00:01:02:03

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

openssl(1), ASN1_generate_nconf(3), OPENSSL_config(3), openssl.cnf(5)

کد افزونه‌های X509v3 نخستین بار در OpenSSL 0.9.2 اضافه شد.

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

گزینه‌های DER و ASN1 باید با احتیاط استفاده شوند. در صورت عدم دقت، ایجاد افزونه‌های کاملاً نامعتبر بسیار محتمل است.

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

subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar

باعث خطا می‌شود، اما فرم زیر معتبر است:

subjectAltName=@subject_alt_section

[subject_alt_section]
subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar

به دلیل رفتار کتابخانه OpenSSL CONF، همان نام فیلد تنها یک بار می‌تواند در یک بخش تکرار شود. این بدان معناست که:

subjectAltName=@alt_section

[alt_section]
email=steve@here
email=steve@there

تنها آخرین مقدار را استفاده خواهد کرد. برای حل این مشکل می‌توان از فرم زیر استفاده کرد:

[alt_section]
email.1=steve@here
email.2=steve@there
March 31, 2022 Linux 6.12.107+deb13-amd64