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 = [email protected]
email = [email protected]

将只识别最后一个值。要指定多个值，请在后面附加一个数字标识符，如这里所示

[extensions]
subjectAltName = @alt_section

[alt_section]
email.1 = [email protected]
email.2 = [email protected]

原始扩展的语法由解析扩展的源代码定义，但应该有文档记录。有关原始扩展的示例，请参阅 "证书策略"。

如果扩展类型不受支持，则必须使用 任意 扩展语法，有关更多详细信息，请参阅 "任意扩展" 部分。

标准扩展

以下部分描述了每个支持扩展的语法。它们没有定义扩展的语义。

基本约束

这是一个多值扩展，它指示证书是否为 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 subjectPublicKey 的值的 160 位 SHA-1 哈希组成（不包括标记、长度和未使用位的数量）。

一个十六进制字符串（可能用 : 分隔字节）

直接输出提供的值。强烈建议不要使用此选项。

默认情况下，x509、req 和 ca 应用程序的行为就像提供了 hash 一样。

示例

subjectKeyIdentifier = hash

颁发者密钥标识符

AKID 扩展规范可以具有值 none，表示不应包含 AKID。否则，它可以具有值 keyid 或 issuer 或两者，用 , 分隔。两者都可以具有选项 always，通过在值和此选项之间放置冒号 : 来指示。对于自签名证书，除非存在 always，否则 AKID 会被抑制。

默认情况下，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（注册 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:[email protected], URI:http://my.example.com/

subjectAltName = IP:192.168.7.1

subjectAltName = IP:13::17

subjectAltName = email:[email protected], 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

颁发者备用名称

此扩展支持主体备用名称的大多数选项；它不支持 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 分发点

这是一个多值扩展，其值可以是使用与主体备用名称相同格式的名称-值对，也可以是单个值，指定包含所有分发点值的节名称。

当使用名称-值对时，将设置一个 DistributionPoint 扩展，其中给定的值作为 fullName 字段作为 distributionPoint 值，而 reasons 和 cRLIssuer 字段将被省略。

当使用单个选项时，该值指定节，该节可以包含以下项目

fullname

分发点的完整名称，与主体备用名称的格式相同。

relativename

该值被视为作为 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

颁发分发点

此扩展应该只出现在 CRL 中。这是一个多值扩展，其语法类似于 CRL 分发点扩展指向的“节”。以下名称具有含义

fullname

分发点的完整名称，与主体备用名称的格式相同。

relativename

该值被视为作为 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 开头，后面跟着一个 ;。名称的其余部分和值遵循主体备用名称的语法，除了不支持 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 OpenSSL 项目作者。保留所有权利。

根据 Apache 许可证 2.0（“许可证”）许可。除非符合许可证，否则您不得使用此文件。您可以在源代码分发中的 LICENSE 文件或 https://www.openssl.org/source/license.html 中获得副本。