X509V3_CONFIG(5ssl)

الاسم
x509v3_config - تنسيق ضبط امتداد شهادة X509 V3

الوصف
تستطيع عدة أوامر من OpenSSL إضافة امتدادات إلى شهادة أو طلب شهادة بناءً على محتويات ملف ضبط وخيارات سطر الأوامر مثل -addext. تُوصف صيغة ملفات الضبط في config(5). عادةً ما تحتوي الأوامر على خيار لتحديد اسم ملف الضبط، وقسم داخل ذلك الملف؛ انظر توثيق كل أمر للحصول على التفاصيل.

تستخدم هذه الصفحة extensions كاسم للقسم، عند الحاجة لذلك في الأمثلة.

يتخذ كل إدخال في قسم الامتداد الصيغة:

 name = [critical, ]value(s)

إذا وُجد critical، فسيُعلم الامتداد على أنه حرج.

إذا عُولجت إدخالات متعددة لنفس اسم الامتداد، فإن الإدخالات اللاحقة تتجاوز السابقة التي تحمل نفس الاسم.

يعتمد تنسيق values على قيمة name، فالكثير منها يحتوي على زوج من النوع والقيمة حيث يُفصل بين النوع والقيمة بنقطتين رأسيتين. هناك أربعة أنواع رئيسة للامتدادات:

 string
 multi-valued
 raw
 arbitrary

يُوصف كل منها في الفقرات التالية.

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

للامتدادات متعددة القيم شكل قصير وشكل طويل. الشكل القصير هو قائمة مفصولة بفواصل من الأسماء والقيم:

 basicConstraints = critical, CA:true, pathlen:1

يسمح الشكل الطويل بوضع القيم في قسم منفصل:

 [extensions]
 basicConstraints = critical, @basic_constraints

 [basic_constraints]
 CA = true
 pathlen = 1

كلا الشكلين متكافئان.

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

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

سيؤدي إلى خطأ، لكن الشكل المكافئ:

 [extensions]
 subjectAltName = @subject_alt_section

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

صحيح.

لا يدعم OpenSSL التكرارات المتعددة لنفس الحقل داخل القسم. في هذا المثال:

 [extensions]
 subjectAltName = @alt_section

 [alt_section]
 email = steve@example.com
 email = steve@example.org

سيتعرف فقط على القيمة الأخيرة. لتحديد قيم متعددة، ألحق معرفًا رقميًا، كما هو موضح هنا:

 [extensions]
 subjectAltName = @alt_section

 [alt_section]
 email.1 = steve@example.com
 email.2 = steve@example.org

تُحدد صيغة الامتدادات الخام بواسطة الشيفرة المصدرية التي تحلل الامتداد ولكن ينبغي توثيقها. انظر "سياسات الشهادة" للحصول على مثال لامتداد خام.

إذا كان نوع الامتداد غير مدعوم، فيجب استخدام صيغة الامتداد الاعتباطي، انظر قسم "الامتدادات الاعتباطية" لمزيد من التفاصيل.

الامتدادات القياسية
تصف الأقسام التالية صيغة كل امتداد مدعوم. وهي لا تُعرّف دلالات الامتداد.

  القيود الأساسية
هذا امتداد متعدد القيم يشير إلى ما إذا كانت الشهادة شهادة CA. القيمة الأولى هي CA متبوعة بـ TRUE أو FALSE. إذا كانت CA تساوي TRUE، فيمكن تضمين اسم pathlen اختياري متبوعًا بقيمة غير سالبة.

على سبيل المثال:

 basicConstraints = CA:TRUE

 basicConstraints = CA:FALSE

 basicConstraints = critical, CA:TRUE, pathlen:1

يجب أن تتضمن شهادة CA اسم basicConstraints مع ضبط معامل CA على TRUE. يجب أن تحتوي شهادة المستخدم النهائي إما على CA:FALSE أو حذف الامتداد تمامًا. يحدد معامل pathlen الحد الأقصى لعدد شهادات CA التي يمكن أن تظهر أسفل هذه الشهادة في سلسلة. تعني قيمة pathlen الصفرية أن CA لا يمكنه توقيع أي شهادات CA فرعية، ولا يمكنه سوى توقيع شهادات كيانات النهاية.

  استخدام المفتاح
استخدام المفتاح هو امتداد متعدد القيم يتكون من قائمة بأسماء استخدامات المفاتيح المسموح بها. القيم المُعرّفة هي: "digitalSignature"، و "nonRepudiation" (مع اسم بديل هو "contentCommitment")، "keyEncipherment"، و "dataEncipherment"، و "keyAgreement"، و "keyCertSign"، "cRLSign"، و "encipherOnly"، و "decipherOnly".

أمثلة:

 keyUsage = digitalSignature, nonRepudiation

 keyUsage = digitalSignature, contentCommitment

 keyUsage = critical, keyCertSign

  استخدام المفتاح الموسع
يتكون هذا الامتداد من قائمة قيم تشير إلى الأغراض التي يمكن استخدام مفتاح الشهادة العام لأجلها. يمكن أن تكون كل قيمة إما اسمًا نصيًا قصيرًا أو OID. الأسماء النصية التالية، ومعناها المقصود، معروفة:

 Value                  Meaning according to RFC 5280 etc.
 -----                  ----------------------------------
 serverAuth             SSL/TLS WWW Server Authentication
 clientAuth             SSL/TLS WWW Client Authentication
 codeSigning            Code Signing
 emailProtection        E-mail Protection (S/MIME)
 timeStamping           Trusted Timestamping
 OCSPSigning            OCSP Signing
 ipsecIKE               ipsec Internet Key Exchange
 msCodeInd              Microsoft Individual Code Signing (authenticode)
 msCodeCom              Microsoft Commercial Code Signing (authenticode)
 msCTLSign              Microsoft Trust List Signing
 msEFS                  Microsoft Encrypted File System

بينما تقول IETF RFC 5280 أن id-kp-serverAuth و id-kp-clientAuth مخصصان فقط لاستخدام WWW، إلا أنهما في الواقع يُستخدمان لجميع أنواع عملاء وخوادم TLS، وهذا ما يفترضه OpenSSL أيضًا.

أمثلة:

 extendedKeyUsage = critical, codeSigning, 1.2.3.4

 extendedKeyUsage = serverAuth, clientAuth

  معرّف مفتاح الموضوع
مواصفة امتداد SKID لها قيمة ذات ثلاثة خيارات.

none
    لن يُضمن أي امتداد SKID.

hash
    تُتبع العملية المحددة في RFC 5280 القسم 4.2.1.2. (1): يتكون keyIdentifier من تجزئة SHA-1 بطول 160 بت لقيمة BIT STRING subjectPublicKey (باستثناء الوسم، والطول، وعدد البتات غير المستخدمة).

A hex string (possibly with ":" separating bytes)
    تُخرج القيمة المقدمة مباشرة. لا يُنصح بهذا الخيار بشدة.

مبدئيًا، تتصرف تطبيقات x509، و req، و ca كما لو أُعطي hash.

مثال:

 subjectKeyIdentifier = hash

  معرّف مفتاح المرجع
قد تحمل مواصفة امتداد AKID القيمة none مما يشير إلى عدم تضمين AKID. وإلا فقد تحمل القيمة keyid أو issuer أو كليهما، مفصولين بـ ",". يمكن لأي منهما أو كليهما الحصول على خيار always، المشار إليه بوضع نقطتين رأسيتين ":" بين القيمة وهذا الخيار. بالنسبة للشهادات الموقعة ذاتيًا، يُحجب AKID ما لم يكن always موجودًا.

مبدئيًا، تتصرف تطبيقات x509، و req، و ca كما لو أُعطي none للشهادات الموقعة ذاتيًا و keyid"," issuer بخلاف ذلك.

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

إذا وُجد issuer، بالإضافة إلى تحديد الخيار always أو عدم وجود keyid، فإن DN المرجع والرقم التسلسلي يُنسخان من شهادة المرجع. إذا فشل ذلك، فإنه يُرجع خطأ.

أمثلة:

 authorityKeyIdentifier = keyid, issuer

 authorityKeyIdentifier = keyid, issuer:always

  اسم الموضوع البديل
هذا امتداد متعدد القيم يدعم عدة أنواع من معرّفات الأسماء، بما في ذلك email (عنوان بريد إلكتروني)، URI (مؤشر مورد موحد)، DNS (اسم نطاق DNS)، RID (معرّف مسجل: OBJECT IDENTIFIER)، IP (عنوان IP)، dirName (اسم مميز)، و otherName. تُوصف صيغة كل منها في الفقرات التالية.

يحتوي خيار email على قيمتين خاصتين. "copy" سيضمن آليًا أي عناوين بريد إلكتروني مضمنة في اسم موضوع الشهادة في الامتداد. "move" سينقل آليًا أي عناوين بريد إلكتروني من اسم موضوع الشهادة إلى الامتداد.

يمكن أن يكون عنوان IP المستخدم في خيار IP بتنسيق IPv4 أو IPv6.

تحدد قيمة dirName قسم الضبط الذي يحتوي على الاسم المميز المُراد استخدامه، كمجموعة من أزواج الاسم والقيمة. يمكن تشكيل AVAs متعددة القيم عن طريق وضع حرف + قبل الاسم.

يمكن أن تتضمن قيمة otherName بيانات اعتباطية مرتبطة بـ OID؛ يجب أن تكون القيمة هي OID متبوعة بفاصلة منقوطة والمحتوى المحدّد باستخدام الصيغة في ASN1_generate_nconf(3).

أمثلة:

 subjectAltName = email:copy, email:my@example.com, URI:http://my.example.com/

 subjectAltName = IP:192.168.7.1

 subjectAltName = IP:13::17

 subjectAltName = email:my@example.com, RID:1.2.3.4

 subjectAltName = otherName:1.2.3.4;UTF8:some other identifier

 [extensions]
 subjectAltName = dirName:dir_sect

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

تُقدّم عناوين البريد الإلكتروني غير ASCII التي تتوافق مع الصيغة المحددة في القسم 3.3 من RFC 6531 كـ otherName.SmtpUTF8Mailbox. وفقًا لـ RFC 8398، ينبغي تقديم عنوان البريد الإلكتروني كـ UTF8String. لفرض التمثيل الصحيح في الشهادة، ينبغي تقديم SmtpUTF8Mailbox كما يلي

 subjectAltName=@alts
 [alts]
 otherName = 1.3.6.1.5.5.7.8.9;FORMAT:UTF8,UTF8String:nonasciiname.example.com

  اسم المرجع البديل
يدعم هذا الامتداد معظم خيارات اسم الموضوع البديل؛ وهو لا يدعم email:copy. كما أنه يضيف issuer:copy كقيمة مسموح بها، والتي تنسخ أي أسماء موضوع بديلة من شهادة المرجع، إن أمكن.

مثال:

 issuerAltName = issuer:copy

  وصول معلومات المرجع
يعطي هذا الامتداد تفاصيل حول كيفية استرجاع المعلومات المتعلقة بالشهادة التي يوفرها CA. الصيغة هي access_id;location، حيث access_id هو معرّف كائن (على الرغم من أن بضع قيم فقط معروفة جيدًا) و location له نفس صيغة اسم الموضوع البديل (باستثناء أن email:copy غير مدعوم).

القيم المحتملة لـ access_id تتضمن OCSP (مستجيب OCSP)، caIssuers (مصدرو CA)، ad_timestamping (طابع زمني AD)، AD_DVCS (ad dvcs)، caRepository (مستودع CA).

أمثلة:

 authorityInfoAccess = OCSP;URI:http://ocsp.example.com/,caIssuers;URI:http://myca.example.com/ca.cer

 authorityInfoAccess = OCSP;URI:http://ocsp.example.com/

  نقاط توزيع CRL
هذا امتداد متعدد القيم يمكن أن تكون قيمه إما زوج اسم-قيمة باستخدام نفس صيغة الاسم البديل للموضوع (subject alternative name) أو قيمة واحدة تحدد اسم القسم الذي يحتوي على جميع قيم نقطة التوزيع.

عند استخدام زوج اسم-قيمة، سيُضبط امتداد DistributionPoint بالقيمة المعطاة كحقل fullName كقيمة لـ distributionPoint، وسيُهمل حقلا reasons و cRLIssuer.

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

fullname
    الاسم الكامل لنقطة التوزيع، بنفس صيغة الاسم البديل للموضوع.

relativename
    تُؤخذ القيمة كجزء من الاسم المميز (distinguished name) الذي يُضبط كقيمة لحقل nameRelativeToCRLIssuer.

CRLIssuer
    يجب أن تكون القيمة بنفس صيغة الاسم البديل للموضوع.

reasons
    حقل متعدد القيم يحتوي على أسباب الإبطال. القيم المتعارف عليها هي: "keyCompromise"، "CACompromise"، "affiliationChanged"، "superseded"، "cessationOfOperation"، "certificateHold"، "privilegeWithdrawn"، و "AACompromise".

يجب تحديد أحد fullname أو relativename فقط.

أمثلة بسيطة:

 crlDistributionPoints = URI:http://example.com/myca.crl

 crlDistributionPoints = URI:http://example.com/myca.crl, URI:http://example.org/my.crl

مثال على نقطة توزيع كاملة:

 [extensions]
 crlDistributionPoints = crldp1_section

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

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

  نقطة توزيع الإصدار
يجب ألا يظهر هذا الامتداد إلا في CRLs. وهو امتداد متعدد القيم تماثل صيغته صيغة "القسم" الذي تشير إليه امتداد نقاط توزيع CRL. للأسماء التالية معنى:

fullname
    الاسم الكامل لنقطة التوزيع، بنفس صيغة الاسم البديل للموضوع.

relativename
    تُؤخذ القيمة كجزء من الاسم المميز (distinguished name) الذي يُضبط كقيمة لحقل nameRelativeToCRLIssuer.

onlysomereasons
    حقل متعدد القيم يحتوي على أسباب الإبطال. القيم المتعارف عليها هي: "keyCompromise"، "CACompromise"، "affiliationChanged"، "superseded"، "cessationOfOperation"، "certificateHold"، "privilegeWithdrawn"، و "AACompromise".

onlyuser, onlyCA, onlyAA, indirectCRL
    قيمة كل من هذه الأسماء هي قيمة منطقية (boolean).

مثال:

 [extensions]
 issuingDistributionPoint = critical, @idp_section

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

  سياسات الشهادة
هذا امتداد خام يدعم جميع الحقول المعرفة لامتداد الشهادة.

تُحدد السياسات بدون مؤهلات بإعطاء OID. تُفصل السياسات المتعددة بفواصل. على سبيل المثال:

 certificatePolicies = 1.2.4.5, 1.1.3.4

لتضمين مؤهلات السياسة، استخدم صيغة "@section" للإشارة إلى قسم يحدد جميع المعلومات.

يجب أن يتضمن القسم المشار إليه OID السياسة باستخدام الاسم policyIdentifier. يمكن تضمين مؤهلات cPSuri باستخدام الصيغة:

 CPS.nnn = value

حيث "nnn" هو رقم.

يمكن ضبط مؤهلات userNotice باستخدام الصيغة:

 userNotice.nnn = @notice

تُحدد قيمة مؤهل userNotice في القسم ذي الصلة. يمكن أن يتضمن هذا القسم خيارات explicitText، و organization، و noticeNumbers. خيارا explicitText و organization هما سلسلتان نصيتان، بينما noticeNumbers هو قائمة أرقام مفصولة بفواصل. يجب أن يكون خيارا organization و noticeNumbers (إذا أُدرجا) موجودين كلاهما. قد تتطلب بعض البرمجيات خيار ia5org في المستوى الأعلى؛ حيث يغير هذا الترميز من Displaytext إلى IA5String.

مثال:

 [extensions]
 certificatePolicies = ia5org, 1.2.3.4, 1.5.6.7.8, @polsect

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

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

يمكن تحديد ترميز محارف explicitText عن طريق إضافة البادئة UTF8، أو BMP، أو VISIBLE متبوعة بنقطتين قبل القيمة. على سبيل المثال:

 [notice]
 explicitText = "UTF8:Explicit Text Here"

  قيود السياسة
هذا امتداد متعدد القيم يتكون من الأسماء 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:.example.com

 nameConstraints = excluded;email:.com

  لا تحقق OCSP
هذا امتداد نصي. يجري تحليله، ولكنه يُهمل.

مثال:

 noCheck = ignored

  ميزة TLS (تُعرف بـ Must Staple)
هذا امتداد متعدد القيم يتكون من قائمة بمعرفات امتدادات TLS. قد يكون كل معرف رقماً (0..65535) أو اسماً مدعوماً. عندما يرسل عميل TLS امتداداً مدرجاً، يُتوقع من خادم TLS تضمين ذلك الامتداد في رده.

الأسماء المدعومة هي: status_request و status_request_v2.

مثال:

 tlsfeature = status_request

امتدادات مهجورة
الامتدادات التالية غير قياسية، وخاصة بـ Netscape، وبالية إلى حد كبير. يُنصح بعدم استخدامها في التطبيقات الجديدة.

  امتدادات نص Netscape
تعليق Netscape (nsComment) هو امتداد نصي يحتوي على تعليق سيُعرض عند عرض الشهادة في بعض المتصفحات. امتدادات أخرى من هذا النوع هي: nsBaseUrl، nsRevocationUrl، nsCaRevocationUrl، nsRenewalUrl، nsCaPolicyUrl و nsSslServerName.

  نوع شهادة Netscape
هذا امتداد متعدد القيم يتكون من قائمة بالأعلام (flags) التي يجب تضمينها. كان يُستخدم للإشارة إلى الأغراض التي يمكن استخدام الشهادة من أجلها. تُستخدم الآن امتدادات basicConstraints، و keyUsage، و extended key usage بدلاً من ذلك.

القيم المقبولة لـ nsCertType هي: client، server، email، objsign، reserved، sslCA، emailCA، objCA.

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

هناك طريقتان لترميز الامتدادات العشوائية.

الطريقة الأولى هي استخدام الكلمة ASN1 متبوعة بمحتوى الامتداد باستخدام نفس صيغة ASN1_generate_nconf(3). على سبيل المثال:

 [extensions]
 1.2.3.4 = critical, ASN1:UTF8String:Some random data
 1.2.3.4.1 = 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.1 = DER:01020304

القيمة التي تتبع DER هي تفريغ ست عشري لترميز DER الخاص بالامتداد. يمكن وضع أي امتداد في هذا الشكل لتجاوز السلوك المبدئي. على سبيل المثال:

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

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

يجب استخدام خياري DER و ASN1 بحذر. من الممكن إنشاء امتدادات غير صالحة إذا لم تُستخدم بعناية.

انظر أيضًا
openssl-req(1), openssl-ca(1), openssl-x509(1), ASN1_generate_nconf(3)

حقوق النسخ
حقوق النشر 2004-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.