OpenSSL

密碼學和 SSL/TLS 工具包

x509v3_config

名稱

x509v3_config - X509 V3 憑證擴充功能組態格式

說明

多個 OpenSSL 指令可以根據組態檔和 CLI 選項（例如 -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 下方的 CA 的最大數量。pathlen 為零表示 CA 無法簽署任何子 CA，只能簽署最終實體憑證。

金鑰使用

金鑰使用是一個多值擴充功能，包含一個允許的金鑰用途名稱清單。已定義的值為：digitalSignature、nonRepudiation、keyEncipherment、dataEncipherment、keyAgreement、keyCertSign、cRLSign、encipherOnly 和 decipherOnly。

範例

keyUsage = digitalSignature, nonRepudiation

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 由 BIT STRING 主體公用金鑰的值的 160 位元 SHA-1 雜湊組成（不包括標籤、長度和未使用的位元數）。

十六進位字串（可能用 : 分隔位元組）

提供的值會直接輸出。強烈建議不要使用此選項。

預設情況下，x509、req 和 ca 應用程式會表現得好像給定 hash 一樣。

範例

subjectKeyIdentifier = hash

授權金鑰識別碼

AKID 擴充功能規格的值可以是 none，表示不會包含 AKID。否則，它的值可以是 keyid 或 issuer，或兩者都有，用 , 分隔。其中任何一個或兩個都可以有 always 選項，表示在值和此選項之間加上一個冒號 :。對於自簽憑證，除非存在 always，否則會取消 AKID。

預設情況下，x509、req 和 ca 應用程式在自簽憑證和 keyid, issuer 中給予 none 時，會像未給予任何值一樣執行。

如果存在 keyid，則會嘗試從發行者憑證複製主體金鑰識別碼 (SKID)，除非發行者憑證與目前的憑證相同，且並非自簽。如果發行者憑證與目前的憑證相同，則會將與簽署金鑰相關的公開金鑰雜湊作為備用。如果存在 always 但無法取得任何值，則會傳回錯誤。

如果存在 issuer，且額外指定了選項 always 或不存在 keyid，則會從發行者憑證複製發行者 DN 和序號。如果失敗，則會傳回錯誤。

範例

authorityKeyIdentifier = keyid, issuer

authorityKeyIdentifier = keyid, issuer:always

主體備用名稱

這是一個多值延伸，支援多種名稱識別碼類型，包括 email (電子郵件地址)、URI (統一資源指標)、DNS (DNS 網域名稱)、RID (已註冊 ID：物件識別碼)、IP (IP 位址)、dirName (識別名稱) 和 otherName。每個語法在以下段落中說明。

email 選項有兩個特殊值。copy 會自動包含憑證主體名稱中包含的任何電子郵件地址在延伸中。move 會自動將憑證主體名稱中的任何電子郵件地址移至延伸。

IP 選項中使用的 IP 位址可以是 IPv4 或 IPv6 格式。

dirName 的值指定包含要使用的識別名稱的組態區段，作為一組名稱值對。多值 AVA 可以透過在名稱前面加上 + 字元來形成。

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

符合 RFC 6531 第 3.3 節中定義語法的非 ASCII 電子郵件地址提供為 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

發行者替代名稱

此擴充功能支援主旨替代名稱的大部分選項；不支援電子郵件：複製。它還新增發行者：複製作為允許的值，如果可能，這會複製發行者憑證中的任何主旨替代名稱。

範例

issuerAltName = issuer:copy

授權資訊存取

此擴充功能提供有關如何擷取 CA 提供的與憑證相關資訊的詳細資料。語法為存取 ID；位置，其中存取 ID是物件識別碼（儘管只有少數值是已知的），而位置具有與主旨替代名稱相同的語法（但電子郵件：複製不受支援）。

存取 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 分配點

這是一個多值擴充功能，其值可以是使用與主旨替代名稱相同格式的名稱值對，或指定包含所有分配點值的區段名稱的單一值。

當使用名稱值對時，將設定 DistributionPoint 擴充功能，並將給定值作為 fullName 欄位作為 distributionPoint 值，且會省略 reasons 和 cRLIssuer 欄位。

當使用單一選項時，值會指定區段，且該區段可以有下列項目

全名

分配點的全名，其格式與主旨替代名稱相同。

相對名稱

此值會視為設定為 nameRelativeToCRLIssuer 欄位值的識別名稱片段。

CRL 發行者

值必須與主旨替代名稱的格式相同。

原因

包含撤銷原因的多值欄位。已識別的值為：keyCompromise、CACompromise、affiliationChanged、superseded、cessationOfOperation、certificateHold、privilegeWithdrawn 和 AACompromise。

只應指定全名或相對名稱其中之一。

簡單範例

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

發行分配點

此擴充功能只應出現在 CRL 中。這是一個多值擴充功能，其語法類似於 CRL 分配點擴充功能所指的「區段」。下列名稱具有意義

全名

分配點的全名，其格式與主旨替代名稱相同。

相對名稱

此值會視為設定為 nameRelativeToCRLIssuer 欄位值的識別名稱片段。

onlysomereasons

包含撤銷原因的多值欄位。已識別的值為：keyCompromise、CACompromise、affiliationChanged、superseded、cessationOfOperation、certificateHold、privilegeWithdrawn 和 AACompromise。

onlyuser、onlyCA、onlyAA、indirectCRL

這些名稱的每個值都是布林值。

範例

[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」語法指向指定所有資訊的區段。

所引用的區段必須包含使用名稱 policyIdentifier 的政策 OID。可以使用語法包含 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 功能（又稱必須釘選）

這是一個多值延伸，包含 TLS 延伸識別碼清單。每個識別碼可以是數字 (0..65535) 或受支援的名稱。當 TLS 客戶端傳送已列出的延伸時，TLS 伺服器預期會在其回覆中包含該延伸。

受支援的名稱有：status_request 和 status_request_v2。

範例

tlsfeature = status_request

已棄用的延伸

下列延伸是非標準的、特定於 Netscape 的，而且在很大程度上已過時。不建議在新的應用程式中使用它們。

Netscape 字串延伸

Netscape 註解 (nsComment) 是包含註解的字串延伸，當在某些瀏覽器中檢視憑證時會顯示該註解。此類型的其他延伸有：nsBaseUrl、nsRevocationUrl、nsCaRevocationUrl、nsRenewalUrl、nsCaPolicyUrl 和 nsSslServerName。

Netscape 憑證類型

這是一個多值延伸，包含要包含的旗標清單。它用於指出憑證可供使用的目的。現在改用 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-2023 The OpenSSL Project Authors。保留所有權利。

根據 Apache 授權條款 2.0（「授權條款」）授權。您只能在遵守授權條款的情況下使用此檔案。您可以在原始程式碼散佈中的 LICENSE 檔案中取得副本，或在 https://www.openssl.org/source/license.html 取得副本。