打开SSL

config

名称

config - OpenSSL CONF 库配置文件

描述

此页面记录了 OpenSSL 配置文件的语法，由 NCONF_load(3) 及其相关函数解析。此格式由许多 OpenSSL 命令使用，并在任何应用程序使用库时进行初始化。

第一部分描述了配置文件的通用语法，后续部分描述了各个模块的语义。其他模块在 fips_config(5) 和 x509v3_config(5) 中有描述。定义 ASN.1 值的语法在 ASN1_generate_nconf(3) 中描述。

语法

配置文件是一系列行。空行以及一行中元素之间的空格没有意义。注释以字符 # 开头；该行其余部分将被忽略。如果 # 是该行中第一个非空格字符，则整行都会被忽略。

指令

可以使用两个指令来控制配置文件的解析：.include 和 .pragma。

为了与 OpenSSL 的旧版本兼容，指令后的等号将被忽略。旧版本会将其视为赋值，因此如果语义上的差异很重要，则应谨慎操作。

文件可以使用 include 语法包含其他文件

.include [=] pathname

如果 pathname 是一个简单的文件名，则该文件将在该点直接包含。包含的文件可以具有指定其他文件的 .include 语句。如果 pathname 是一个目录，则该目录中所有扩展名为 .cnf 或 .conf 的文件都将被包含。（这仅在具有 POSIX IO 支持的系统上可用。）在 pathname 内部找到的任何子目录都会被 忽略。类似地，如果在扫描目录时打开了一个文件，并且该文件有一个指定目录的 .include 指令，则该指令也会被忽略。

通常，pathname 应该是一个绝对路径；这可以通过下面描述的 abspath 和 includedir pragma 强制执行。如果存在，环境变量 OPENSSL_CONF_INCLUDE 将被预置到所有相对路径名前。如果路径名仍然是相对的，则根据当前工作目录进行解释。

要要求所有文件包含都命名绝对路径，请使用以下指令

.pragma [=] abspath:value

默认行为（其中 value 为 false 或 off）是允许相对路径。要要求所有 .include 路径名都为绝对路径，请使用 value 的 true 或 on 值。

在这些文件中，美元符号 $ 用于引用变量，如下所述。但是，在某些平台上，通常将 $ 视为符号名称中的常规字符。可以通过以下指令来支持此行为

.pragma [=] dollarid:value

默认行为（其中 value 为 false 或 off）是将美元符号视为指示变量名称；foo$bar 被解释为 foo 后跟变量 bar 的扩展。如果 value 为 true 或 on，则 foo$bar 是一个单独的七个字符的名称，并且必须使用大括号或括号来指定变量扩展。

.pragma [=] includedir:value

如果在 .include 指令中指定了相对路径名，并且 OPENSSL_CONF_INCLUDE 环境变量不存在，则如果存在，则将 includedir pragma 的值预置到路径名前。

设置

配置文件被分成多个节。一个节以方括号内的节名开头，并在新节开始或文件结尾处结束。节名可以包含字母数字字符和下划线。名称和括号之间的空格将被删除。

配置文件的第一个节是特殊的，称为 default 节。此节通常没有名称，从文件开头一直延伸到第一个命名节。当查找名称时，首先在当前或命名节中查找，然后在必要时查找默认节。

环境映射到名为 ENV 的节。

一个节内包含一系列名称/值赋值，下面将详细介绍。提醒一下，此示例中显示的方括号是必需的，而不是可选的

[ section ]
name1 = This is value1
name2 = Another value
...
[ newsection ]
name1 = New value1
name3 = Value 3

name 可以包含任何字母数字字符以及一些标点符号，例如 . , ; 和 _。名称之后和等号之前的空格将被忽略。

如果在同一节中重复了名称，则所有值（最后一个值除外）都将被忽略。在某些情况下，例如使用证书 DN 时，同一字段可能会出现多次。为了支持这一点，像 openssl-req(1) 这样的命令会忽略以句点开头的任何前导文本。例如

1.OU = First OU
2.OU = Second OU

value 由 = 字符之后的字符串组成，直到行尾，并删除任何前导和尾随空格。

值字符串将进行变量扩展。文本 $var 或 ${var} 插入当前节中命名变量的值。要使用另一个节中的值，请使用 $section::name 或 ${section::name}。通过使用 $ENV::name，将替换指定环境变量的值。

必须在引用变量值之前定义变量，否则会标记错误并且文件将无法加载。这可以通过在使用变量之前在 default 节中指定默认值来解决。

ENV 节中的任何名称/值设置都可供配置文件使用，但不会传播到环境中。

如果值最终长度超过 64k，则会出错。

可以通过在值周围使用单个 ' 或双 " 引号，或在字符前使用反斜杠 \ 来转义某些字符。通过使一行的最后一个字符为 \，value 字符串可以跨多行分布。此外，还识别序列 \n、\r、\b 和 \t。

上面描述的适用于 value 的扩展和转义规则也适用于 .include 指令的路径名。

OPENSSL 库配置

下面的部分使用非正式术语 模块 来指代 OpenSSL 功能的一部分。例如，这与正式术语 FIPS 模块 不同。

OpenSSL 在默认节中查找 openssl_conf 的值，并将其作为指定如何配置库中任何模块的节的名称。将任何模块保留在其默认配置中不会出错。例如，应用程序可以通过直接调用 CONF_modules_load_file() 来指定不同的名称。

OpenSSL 还查找 config_diagnostics 的值。如果此值存在且具有非零数值，则传递给 CONF_modules_load() 的任何错误抑制标志都将被忽略。这对于诊断错误配置很有用，但在生产环境中使用需要额外考虑。启用此选项后，配置错误将完全阻止访问服务。在没有此选项且存在配置错误的情况下，将允许访问，但不会使用所需的配置。

# These must be in the default section
config_diagnostics = 1
openssl_conf = openssl_init

[openssl_init]
oid_section = oids
providers = providers
alg_section = evp_properties
ssl_conf = ssl_configuration
engines = engines
random = random

[oids]
... new oids here ...

[providers]
... provider stuff here ...

[evp_properties]
... EVP properties here ...

[ssl_configuration]
... SSL/TLS configuration properties here ...

[engines]
... engine properties here ...

[random]
... random properties here ...

下面描述了每个模块的语义。“在初始化节中”是指由 openssl_conf 或其他名称（如上例中的 openssl_init）标识的节。下面的示例假设使用上述配置来指定各个节。

ASN.1 对象标识符配置

初始化节中的名称 oid_section 指定包含 OID 的名称/值对的节。名称是短名称；值是可选的长名称，后跟逗号和数值。虽然一些 OpenSSL 命令有自己的节来指定 OID，但此节使所有命令和应用程序都可以使用它们。

[oids]
shortName = a very long OID name, 1.2.3.4
newoid1 = 1.2.3.4.1
some_other_oid = 1.2.3.5

如果包含上述片段的完整配置位于文件 example.cnf 中，则以下命令行

OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1

将输出

0:d=0  hl=2 l=   4 prim: OBJECT            :newoid1

表明 OID “newoid1” 已添加为“1.2.3.4.1”。

提供程序配置

初始化节中的名称 providers 指定包含加密提供程序配置的节。此节中的名称/值赋值分别命名一个提供程序，并指向该提供程序的配置节。提供程序特定的节用于指定如何加载模块、激活它以及设置其他参数。

在提供程序节内，以下名称具有意义

identity

这用于指定备用名称，覆盖提供程序列表中指定的默认名称。例如

[providers]
foo = foo_provider

[foo_provider]
identity = my_fips_module

module

指定要加载的模块（通常是共享库）的路径名。

activate

如果存在并设置为 yes、on、true 或 1 之一，则将激活关联的提供程序。相反，将此值设置为 no、off、false 或 0 将阻止提供程序被激活。设置可以使用小写或大写给出。将 activate 设置为任何其他设置或省略设置值将导致错误。

= item soft_load

如果启用，则通知库在未能激活请求的提供程序时清除错误堆栈。值 1、yes、true 或 on（小写或大写）将激活此设置，而值 0、no、false 或 off（同样小写或大写）将禁用此设置。任何其他值都会产生错误。请注意，如果未提供此设置，则默认为关闭

节以及子节中的所有参数都可供提供程序使用。

默认提供程序及其激活

如果没有显式激活任何提供程序，则隐式激活默认提供程序。有关更多详细信息，请参阅 OSSL_PROVIDER-default(7)。

如果您显式添加了一个激活任何其他提供程序的节，则很可能需要显式激活默认提供程序，否则它将在 openssl 中不可用。这可能会使系统远程不可用。

EVP 配置

初始化节中的名称 alg_section 指定在使用 EVP API 时包含算法属性的节。

在算法属性节内，以下名称具有意义

default_properties

该值可以是 EVP_set_default_properties() 作为属性查询字符串可接受的任何内容。

fips_mode（已弃用）

该值是一个布尔值，可以是 yes 或 no。如果该值为 yes，则这与

default_properties = fips=yes

完全等效。如果该值为 no，则不会发生任何事情。使用此名称已弃用，如果使用，则它必须是该节中唯一的名称。

SSL 配置

初始化节中的名称 ssl_conf 指定包含 SSL/TLS 配置列表的节。与提供程序一样，此节中的每个名称都标识一个包含该名称配置的节。例如

[ssl_configuration]
server = server_tls_config
client = client_tls_config
system_default = tls_system_default

[server_tls_config]
... configuration for SSL/TLS servers ...

[client_tls_config]
... configuration for SSL/TLS clients ...

配置名称 system_default 具有特殊含义。如果存在，则在创建 SSL_CTX 对象时应用它。例如，要强加系统范围内的最低 TLS 和 DTLS 协议版本

[tls_system_default]
MinProtocol = TLSv1.2
MinProtocol = DTLSv1.2

最低 TLS 协议应用于基于 TLS 的 SSL_CTX 对象，而最低 DTLS 协议应用于基于 DTLS 的对象。使用 MaxProtocol 设置的最大版本也适用相同规则。

每个配置节都由名称/值对组成，这些对由SSL_CONF_cmd(3)解析，SSL_CTX_config()或SSL_config()将根据需要调用它。请注意，配置节中初始点之前的任何字符都会被忽略，以便可以多次使用相同的命令。这可能最适用于加载不同的密钥类型，如下所示

[server_tls_config]
RSA.Certificate = server-rsa.pem
ECDSA.Certificate = server-ecdsa.pem

引擎配置

初始化节中的名称engines指定包含引擎配置列表的节。与提供程序一样，此节中的每个名称都标识一个引擎及其配置。引擎特定的节用于指定如何加载引擎、激活它以及设置其他参数。

在引擎节中，以下名称具有含义

engine_id

这用于指定备用名称，覆盖引擎列表中指定的默认名称。如果存在，它必须位于首位。例如

[engines]
foo = foo_engine

[foo_engine]
engine_id = myfoo

dynamic_path

这将从给定路径加载并添加一个引擎。它等效于发送带有路径参数的SO_PATH控制以及值为2和LOAD的LIST_ADD控制到动态引擎。如果这不是所需的行为，则可以使用ctrl命令将备用ctrl直接发送到动态引擎。

init

这指定是否初始化引擎。如果值为0，则不会初始化引擎，如果值为1，则会尝试立即初始化引擎。如果不存在init命令，则将在处理其节中的所有命令后尝试初始化引擎。

default_algorithms

这使用函数ENGINE_set_default_string()设置引擎将提供的默认算法。

所有其他名称都被视为发送到引擎的ctrl命令的名称，并且该值是与命令一起传递的参数。特殊值EMPTY表示不使用该命令发送任何值。例如

[engines]
foo = foo_engine

[foo_engine]
dynamic_path = /some/path/fooengine.so
some_ctrl = some_value
default_algorithms = ALL
other_ctrl = EMPTY

随机数配置

初始化节中的名称random指定包含随机数生成器设置的节。

在随机数节中，以下名称具有含义

random

这用于指定随机比特生成器。例如

[random]
random = CTR-DRBG

可用的随机比特生成器为：

CTR-DRBG

HASH-DRBG

HMAC-DRBG

cipher

这指定CTR-DRBG随机比特生成器将使用什么密码。其他随机比特生成器会忽略此名称。默认值为AES-256-CTR。

digest

这指定HASH-DRBG或HMAC-DRBG随机比特生成器将使用什么摘要。其他随机比特生成器会忽略此名称。

properties

这设置在获取随机比特生成器和任何底层算法时使用的属性查询。

seed

这设置应使用的随机性源。默认情况下，在FIPS提供程序之外将使用SEED-SRC。FIPS提供程序使用回调从经过验证的边界之外访问相同的随机性源。

seed_properties

这设置在获取随机性源时使用的属性查询。

示例

此示例演示如何使用引用和转义。

# This is the default section.
HOME = /temp
configdir = $ENV::HOME/config

[ section_one ]
# Quotes permit leading and trailing whitespace
any = " any variable name "
other = A string that can \
cover several lines \
by including \\ characters
message = Hello World\n

[ section_two ]
greeting = $section_one::message

此示例演示如何安全地扩展环境变量。在此示例中，变量tempfile旨在引用一个临时文件，并且如果存在，环境变量TEMP或TMP指定应将文件放置到的目录。由于如果变量不存在则会检查默认节，因此可以将TMP设置为默认为/tmp，并将TEMP设置为默认为TMP。

# These two lines must be in the default section.
TMP = /tmp
TEMP = $ENV::TMP

# This can be used anywhere
tmpfile = ${ENV::TEMP}/tmp.filename

此示例演示如何为应用程序sample强制执行FIPS模式。

sample = fips_config

[fips_config]
alg_section = evp_properties

[evp_properties]
default_properties = "fips=yes"

环境

OPENSSL_CONF

配置文件的路径，或者对于无文件则为空字符串。在set-user-ID和set-group-ID程序中被忽略。

OPENSSL_ENGINES

引擎目录的路径。在set-user-ID和set-group-ID程序中被忽略。

OPENSSL_MODULES

包含OpenSSL模块（例如提供程序）的目录的路径。在set-user-ID和set-group-ID程序中被忽略。

OPENSSL_CONF_INCLUDE

要预先添加到所有.include路径的可选路径。

缺陷

无法使用八进制\nnn形式包含字符。所有字符串都以null结尾，因此null不能构成值的一部分。

转义并不完全正确：如果您想使用\n之类的序列，则不能在同一行上使用任何引用转义。

一次只能打开和读取一个目录的限制可以被认为是一个缺陷，应该修复。

历史

一个未公开的API，NCONF_WIN32()，使用了略微不同的解析规则，这些规则旨在针对Microsoft Windows平台进行定制。具体来说，反斜杠字符不是转义字符，可以在路径名中使用，仅识别双引号字符，并且注释以分号开头。此函数在OpenSSL 3.0中已弃用；使用该语法的配置文件的应用程序将必须进行修改。

参见

openssl-x509(1)，openssl-req(1)，openssl-ca(1)，openssl-fipsinstall(1)，ASN1_generate_nconf(3)，EVP_set_default_properties(3)，CONF_modules_load(3)，CONF_modules_load_file(3)，fips_config(5)，以及x509v3_config(5)。

版权

版权所有 2000-2023 OpenSSL 项目作者。保留所有权利。

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