X509 V3 certificate extension configuration format

描述

多个 OpenSSL 命令可以根据配置文件的内容和 CLI 选项（例如 -addext）向证书或证书请求添加扩展。配置文件的语法在 config(5) 中描述。这些命令通常有一个选项来指定配置文件的名称以及该文件中的部分；有关详细信息，请参阅单个命令的文档。

本文档使用extensions作为v3扩展的section name.
在扩展section中每个项目如下所示：

“`openssl cnf
name = [critical, ]value(s)

<pre><code class="line-numbers">如果critical关键词存在则标记为关键扩展

如果为同一扩展名处理多个条目，则后面的条目将覆盖前面的同名条目。

值的格式取决于名称的值，许多值具有type-value对，其中类型和值由冒号分隔。扩展主要有四种类型：string，multi-valued，raw，arbitrary.
以下段落将描述每种类型:

string扩展仅包含一个字符串，其中包含值本身或获取值的方式。

multi-valued扩展具有短格式和长格式。短格式是逗号分隔的名称和值列表：
“`openssl cnf
basicConstraints = critical, CA:true, pathlen:1

长格式允许将值放在单独的section中：

“`openssl cnf
[extensions]
basicConstraints = critical, @basic_constraints

[basic_constraints]
CA = true
pathlen = 1

<pre><code class="line-numbers">两种格式是等效的。

如果扩展是多值的，并且字段值包含逗号，则必须使用长格式，否则逗号将被误解为字段分隔符。例如：
“`openssl cnf
subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
““
这样会产生错误，但与以下格式等效
“`openssl cnf
[extensions]
subjectAltName = @subject_alt_section

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

OpenSSL 不支持在一个section中多次出现同一字段。在此示例中：

“`openssl cnf
[extensions]
subjectAltName = @alt_section

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

只会识别最后一个值。要指定多个值，请附加数字标识符，如下所示：
```opensl cnf
[extensions]
subjectAltName = @alt_section

[alt_section]
email.1 = steve@example.com
email.2 = steve@example.org
</code></pre>

The syntax of raw extensions is defined by the source code that parses the extension but should be documented. See "Certificate Policies" for an example of a raw extension.
raw扩展的语法由解析扩展的源代码定义，但应有文档记录。请参阅"<a class="wp-editor-md-post-content-link" href="https://docs.openssl.org/3.4/man5/x509v3_config/#certificate-policies">Certificate Policies</a>" 了解raw扩展的示例。

如果扩展类型不受支持，则必须使用arbitrary扩展语法，有关更多详细信息，请参阅<a class="wp-editor-md-post-content-link" href="https://docs.openssl.org/3.4/man5/x509v3_config/#arbitrary-extensions">"ARBITRARY EXTENSIONS"</a>部分。

<h2>STANDARD EXTENSIONS</h2>

<ul>
<li>Basic Constraints

这是一个multi-valued扩展，用于指示证书是否为 CA 证书。第一个值是 CA，后跟 TRUE 或 FALSE。如果 CA 为 TRUE，则可以包含可选的路径长度名称，后跟非负值。

```openssl cnf
basicConstraints = CA:TRUE


basicConstraints = CA:FALSE

basicConstraints = critical, CA:TRUE, pathlen:1

```
CA 证书必须包含 basicConstraints ，并将 CA 参数设置为 TRUE。最终用户证书必须具有 CA:FALSE 或完全省略此扩展。pathlen 参数指定链中可在此 CA 下出现的 CA 的最大数量。pathlen 为零表示 CA 不能签署任何子 CA，而只能签署最终实体证书。
</p></li>
<li><p>Key Usage

Key Usage是一个multi-valued扩展，由允许的密钥用法的name列表组成。定义的值有：digitalSignature、nonRepudiation、keyEncipherment、dataEncipherment、keyAgreement、keyCertSign、cRLSign、encipherOnly 和 decipherOnly。
示例：

```openssl cnf
keyUsage = digitalSignature, nonRepudiation


keyUsage = critical, keyCertSign

```
</p></li>
<li><p>Extended Key Usage

This extension consists of a list of values indicating purposes for which the certificate public key can be used. Each value can be either a short text name or an OID. The following text names, and their intended meaning, are known:
此扩展由一系列指示证书公钥的用途的值组成。每个值都可以是短文本名称或 OID。以下是已知的文本名称及其预期含义：

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

虽然 IETF RFC 5280 规定 id-kp-serverAuth 和 id-kp-clientAuth 仅用于 WWW，但实际上它们用于各种 TLS 客户端和服务器，这也是 OpenSSL 所假定的。

Examples:

```openssl cnf
extendedKeyUsage = critical, codeSigning, 1.2.3.4


extendedKeyUsage = serverAuth, clientAuth

```
</p></li>
<li><p>Subject Key Identifier

subject密钥标识符扩展可以指定以下3个值.

<ul>
<li>none

No SKID extension will be included.</p></li>
<li><p>hash

The process specified in RFC 5280 section 4.2.1.2. (1) is followed: The keyIdentifier is composed of the 160-bit SHA-1 hash of the value of the BIT STRING subjectPublicKey (excluding the tag, length, and number of unused bits).</p></li>
<li><p>A hex string (possibly with : separating bytes)

The provided value is output directly. 千万不要这么干.</p></li>
</ul>

<p>By default the x509, req, and ca apps behave as if hash was given.

Example:

```openssl cnf
subjectKeyIdentifier = hash
```
</p></li>
<li><p>Authority Key Identifier

If issuer is present, and in addition it has the option always specified or keyid is not present, then the issuer DN and serial number are copied from the issuer certificate. If this fails, an error is returned.
AKID 扩展规范可能具有值 none，表示不应包含任何 AKID。否则，它可能具有值 keyid 或 issuer 或两者，以 , 分隔。其中一个或两个还可以具有 always参数，通过在值和此选项之间放置冒号 : 来表示。对于自签名证书，除非 always 存在，否则 AKID 将被抑制。

默认情况下，x509、req 和 ca 应用程序的默认值为 none，其它情况为 keyid、issuer。

如果 keyid 存在，则尝试从颁发者证书复制主题密钥标识符 (SKID)，除非颁发者证书与当前证书相同且不是自签名的。如果颁发者证书与当前证书相同，则使用签名密钥相关的公钥的哈希值作为替代值。如果 always 存在但无法获取任何值，则返回错误。

如果issuer name存在，并且它还具有issuer选项或不存在 keyid，则从颁发者证书中复制颁发者 DN 和序列号。如果失败，则返回错误。
Examples:

```openssl cnf
authorityKeyIdentifier = keyid, issuer


authorityKeyIdentifier = keyid, issuer:always

```
</p></li>
<li><p>Subject Alternative Name

这是一个multi-valued扩展，支持多种类型的名称标识符，包括 email（电子邮件地址）、URI（统一资源指示器）、DNS（DNS 域名）、RID（注册 ID：对象标识符）、IP（IP 地址）、dirName（可分辨名称）和 otherName。以下段落描述了每种语法。

<ul>
<li>email 选项有两个特殊值。copy 将自动在扩展中包含证书 subject name 中包含的任何电子邮件地址。move 将自动将任何电子邮件地址从证书主题名称subject name到扩展。</p></li>
<li><p>IP 选项中使用的 IP 地址可以是 IPv4 或 IPv6 格式。</p></li>
<li><p>dirName 的值指定包含要使用的DN，其值为一个section name,具体的DN在section中给出，作为一组name-value对。可以通过在名称前面加上 + 字符来形成多值 AVAs。</p></li>
<li><p>otherName 的值可以包括与 OID 相关联的任意数据；该值应为 OID 后跟分号和使用 ASN1_generate_nconf(3) 中的语法指定的内容。</p></li>
</ul>

<p>Examples:

```openssl cnf
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 电子邮件地址应符合 RFC 6531 第 3.3 节中定义的语法的以 otherName.SmtpUTF8Mailbox 形式提供。根据 RFC 8398，电子邮件地址应以 UTF8String 形式提供。为了强制证书中的有效表示，SmtpUTF8Mailbox应按如下方式提供：

```openssl cnf
subjectAltName=@alts
[alts]
otherName = 1.3.6.1.5.5.7.8.9;FORMAT:UTF8,UTF8String:nonasciiname.example.com
</code></pre></li>
<li>Issuer Alternative Name

此扩展支持大多数Subject Alternative Name选项；不支持 email:copy但添加了 issuer:copy 作为允许值，如果可能，它会从颁发者证书中复制任何subject alternative names。
Example:

```openssl cnf
issuerAltName = issuer:copy
```
</p></li>
<li><p>Authority Info Access

此扩展详细说明了如何检索与 CA 提供的证书相关的信息。语法为 access_id;location，其中 access_id 是对象标识符（尽管只有少数值是众所周知的），location 的语法与主题备用名称相同（但不支持 email:copy）。
允许的值包括 access_id include OCSP (OCSP responder), caIssuers (CA Issuers), ad_timestamping (AD Time Stamping), AD_DVCS (ad dvcs), caRepository (CA Repository).

Examples:

```openssl cnf
authorityInfoAccess = OCSP;URI:http://ocsp.example.com/,caIssuers;URI:http://myca.example.com/ca.cer
authorityInfoAccess = OCSP;URI:http://ocsp.example.com/
```
</p></li>
<li><p>CRL distribution points

这是一个multi-valued扩展，其值可以是使用与subject alternative name相同形式的name-value对，也可以是指定section的name,该section包含所有分发点值。
When a name-value pair is used, a DistributionPoint extension will be set with the given value as the fullName field as the distributionPoint value, and the reasons and cRLIssuer fields will be omitted.
当使用name-value对时，将设置 DistributionPoint 扩展，并使用给定的值作为 fullName 字段作为 distributionPoint 值，并且将省略reasons和 cRLIssuer 字段。
当使用单选项值时, 指定的section中可以包含以下项:

<ul>
<li>fullname

distribution point的全名，格式与subject alternative name相同</p></li>
<li><p>relativename

这是distribution points的RDN，会附加到CRLIssuer的DN中形成分发点的DN，通常不会使用这个项目</p></li>
<li><p>CRLIssuer

格式与subject alternative name相同</p></li>
<li><p>reasons

multi-value 字段，包含吊销原因. 可识别的值包括: keyCompromise, CACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, privilegeWithdrawn, and AACompromise.</p></li>
</ul>

<p>Only one of fullname or relativename should be specified.
fullname 和 relativename 只能指定一个。

Simple examples:


```openssl cnf
crlDistributionPoints = URI:http://example.com/myca.crl


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

Full distribution point example:

[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

```
</p></li>
<li><p>Issuing Distribution Point

这个选项的格式与CRL distribution points是类似的，只不过它指定的是issuer的Distribution Point
This extension should only appear in CRLs. It is a multi-valued extension whose syntax is similar to the "section" pointed to by the CRL distribution points extension. The following names have meaning:

<ul>
<li>fullname

distribution point的全名，格式与subject alternative name相同</p></li>
<li><p>relativename

这是distribution points的RDN，会附加到CRLIssuer的DN中形成分发点的DN，通常不会使用这个项目</p></li>
<li><p>onlysomereasons

multi-value 字段，包含吊销原因. 可识别的值包括: keyCompromise, CACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, privilegeWithdrawn, and AACompromise.</p></li>
<li><p>onlyuser, onlyCA, onlyAA, indirectCRL

The value for each of these names is a boolean.</p></li>
</ul>

<p>Example:

```openssl cnf
[extensions]
issuingDistributionPoint = critical, @idp_section


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

```

Certificate Policies

这是一个raw扩展，可以支持证书定义的所有扩展。
policy qualifiers指策略的内容部分。
不带policy qualifiers的策略可以通过OID指定，多个策略以逗号分隔，例如：

certificatePolicies = 1.2.4.5, 1.1.3.4

要包含policy qualifiers需使用"@section"语法指向一个section,这个section中会指定所有信息，而且引用的section必须包括一个名为policyIdentifier的项指定策略OID。

cPSuri qualifiers 可以用以下语法表示。
CPS.nnn = value

where nnn is a number.
userNotice qualifiers 可以用以下语法表示:
userNotice.nnn = @notice

userNotice qualifier的值需要相关section中指定。此部分可以包含explicitText、organization和noticeNumbers选项。explicitText and organization是文本字符串，noticeNumbers是以逗号分隔的数字列表。organization and noticeNumbers选项（如果包含）必须同时存在。某些软件可能需要 ia5org 选项在最前面；这会将编码从 Displaytext 更改为 IA5String。
Example:
[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, or VISIBLE 后跟一个冒号. 例如:
[notice]
explicitText = "UTF8:Explicit Text Here"


Policy Constraints
这是一个multi-valued扩展，由name requireExplicitPolicy 或 inhibitPolicyMapping 和一个非负整数值组成。必须至少存在一个组件。

Example:
policyConstraints = requireExplicitPolicy:3


Inhibit Any Policy
这是一个string扩展，必须包含一个非负数
Example:
inhibitAnyPolicy = 2


Name Constraints
这是一个multi-valued扩展。名称应以单词“permitted”或“excluded”开头，后跟 ;。名称的其余部分和值遵循 subjectAltName 的语法，但不支持 email:copy，并且 IP 形式应由 IP 地址和子网掩码组成，并用 / 分隔。
Examples:
nameConstraints = permitted;IP:192.168.0.0/255.255.0.0

nameConstraints = permitted;email:.example.com

nameConstraints = excluded;email:.com


OCSP No Check
This is a string extension. It is parsed, but ignored.
Example:
noCheck = ignored


TLS Feature (aka Must Staple)
这是一个multi-valued扩展，由 TLS 扩展标识符列表组成。每个标识符可能是一个数字（0..65535）或受支持的名称。当 TLS 客户端发送列出的扩展时，TLS 服务器应在其回复中包含该扩展。
支持的 names 包括: status_request and status_request_v2.
Example:
tlsfeature = status_request



废弃的扩展
以下扩展是非标准的、特定于 Netscape 的且大部分已过时。不鼓励在新应用程序中使用它们。

Netscape String extensions

Netscape Comment (nsComment) is a string extension containing a comment which will be displayed when the certificate is viewed in some browsers. Other extensions of this type are: nsBaseUrl, nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl and nsSslServerName.
Netscape Certificate Type

This is a multi-valued extensions which consists of a list of flags to be included. It was used to indicate the purposes for which a certificate could be used. The basicConstraints, keyUsage and extended key usage extensions are now used instead.

Acceptable values for nsCertType are: client, server, email, objsign, reserved, sslCA, emailCA, objCA.
ARBITRARY 扩展
如果 OpenSSL 代码不支持某个扩展，则必须使用任意扩展格式对其进行编码。对于受支持的扩展，也可以使用任意格式。应特别小心，确保数据针对给定的扩展类型正确格式化。
There are two ways to encode arbitrary extensions.
The first way is to use the word ASN1 followed by the extension content using the same syntax as ASN1_generate_nconf(3). For example:
[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

It is also possible to use the word DER to include the raw encoded data in any extension.
1.2.3.4 = critical, DER:01:02:03:04
1.2.3.4.1 = DER:01020304

The value following DER is a hex dump of the DER encoding of the extension Any extension can be placed in this form to override the default behaviour. For example:
basicConstraints = critical, DER:00:01:02:03

警告
无法保证特定实现会正确处理给定的扩展。因此，有时可能会将证书用于其扩展所禁止的用途，因为特定应用程序不识别或不遵守相关扩展的值。

应谨慎使用 DER 和 ASN1 选项。如果不谨慎使用，可能会创建无效的扩展。
Views: 1

				 Post Views: 0