文章目录

  • 译者注
  • 翻译
  • 文档名
  • 描述
  • OPENSSL 库配置
  • ASN1 对象配置模块
  • Engine配置模块
  • EVP配置模块
  • SSL 配置模块
  • 注意
  • 示例
  • 环境
  • OPENSSL_CONF
  • OPENSSL_ENGINES
  • BUGS
  • 也可以看看
  • COPYRIGHT


译者注

本文翻译man config对应的文档。亦可在线查看config - OpenSSL CONF library configuration files

文中的很多内容我知道，所以翻译的很烂。

翻译

文档名

config - OpenSSL CONF 库配置文件。

描述

OpenSSL CONF 库可用于读取配置文件。它用于 OpenSSL 主配置文件 openssl.cnf 以及其他一些地方，例如 SPKAC文件和x509实用程序的证书扩展文件。 OpenSSL 应用程序也可以将 CONF 库用于自己的目的。

配置文件分为多个部分。每个部分都以行**[ section_name ]**开头，并在开始新部分或到达文件末尾时结束。部分名称可以由字母数字字符和下划线组成。

配置文件的第一部分是特殊的，称为默认部分。此部分通常是未命名的，并且从文件的开头跨越到第一个命名的部分。查找名称时，首先在命名部分（如果有）中查找，然后在默认部分中查找。

environment被映射到ENV部分。

注释可以通过在它们前面加上 # 字符来包含。

可以使用 .include 指令后跟路径来包含其他文件。如果路径指向一个目录，则该目录中包含名称以 .cnf 或 .conf 结尾的所有文件。不支持从此类目录中的文件递归包含目录。这意味着包含目录中的文件也可以包含 .include 指令，但仅支持包含常规文件。不支持 POSIX IO 的系统不支持包含目录。

强烈建议使用带有 .include 指令的绝对路径。相对路径是根据应用程序当前工作目录评估的，因此除非包含 .include 指令的配置文件是特定于应用程序的，否则包含将无法按预期工作。

在 .include 指令和路径之间可以有可选的 = 字符和空格字符，这在配置文件需要由不支持 .include 语法的旧 OpenSSL 版本加载的情况下很有用。如果 = 字符不存在，他们会因错误而退出，但他们只是忽略包含。

配置文件中的每个部分都由许多名称和值对组成，形式为 name=value

name字符串可以包含任何字母数字字符以及一些标点符号，例如 . , ;和_。

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

value字符串可以变量扩展。这可以通过包含 $var 或 ${var} 的形式来完成：这将替换当前部分中命名变量的值。也可以使用语法 $section::name 或 ${section::name} 替换另一个节的值。通过使用 $ENV::name形式，可以替换环境变量。也可以使用名称 ENV::name 为环境变量赋值，如果程序使用 CONF 库而不是直接调用 getenv()来查找环境变量，这将起作用。变量扩展后的值字符串长度不得超过 64k。否则会出现错误。

可以使用任何类型的引号或 \ 字符来转义某些字符。通过使一行的最后一个字符为 \，一个值字符串可以分布在多行中。此外，还可以识别序列 \n、\r、\b 和 \t。

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

OPENSSL 库配置

应用程序可以使用主 OpenSSL 配置文件或可选的替代配置文件自动配置 OpenSSL 的某些方面。 openssl 实用程序包括此功能：任何子命令都使用主 OpenSSL 配置文件，除非在子命令中使用选项来使用替代配置文件。

要启用库配置，默认部分需要包含指向主配置部分的适当行。默认名称是 openssl_conf，由 openssl 实用程序使用。其他应用程序可能会使用其他名称，例如 myapplication_conf。所有库配置行都出现在配置文件开头的默认部分中。

配置部分应该由一组包含特定模块配置信息的名称值对组成。 name 代表配置模块的名称。该值的含义是特定于模块的：例如，它可以表示包含配置模块特定信息的进一步配置部分。例如。：

# This must be in the default section
openssl_conf = openssl_init
[openssl_init]
oid_section = new_oids
engines = engine_section
[new_oids]
... new oids here ...
[engine_section]
... engine stuff here ...

每个配置模块的功能如下所述。

ASN1 对象配置模块

该模块的名称为 oid_section。此变量的值指向包含 OID 名称值对的部分：名称是 OID 短名称和长名称，值是 OID 的数字形式。尽管某些 openssl 实用程序子命令已经具有自己的 ASN1 OBJECT 部分功能，但并非所有功能都具有。通过使用 ASN1 OBJECT 配置模块，所有 openssl 实用程序子命令都可以看到新对象以及任何兼容的应用程序。例如：

[new_oids]
some_new_oid = 1.2.3.4
some_other_oid = 1.2.3.5

也可以将值设置为长名称，后跟逗号和数字 OID 形式。例如：

shortName = some object long name, 1.2.3.4

Engine配置模块

此 ENGINE 配置模块具有名称引擎。此变量的值指向包含更多 ENGINE 配置信息的部分。

engines所指向的部分是一个engines名称表（尽管请参阅下面的 engine_id）以及包含特定于每个 ENGINE 的配置信息的其他部分。

每个 ENGINE 特定部分用于设置默认算法、加载动态、执行初始化和发送 ctrls。实际执行的操作取决于命令名称，即名称值对的名称。下面列出了当前支持的命令。

例如：

[engine_section]
# Configure ENGINE named "foo"
foo = foo_section
# Configure ENGINE named "bar"
bar = bar_section
[foo_section]
... foo ENGINE specific commands ...
[bar_section]
... "bar" ENGINE specific commands ...

命令 engine_id 用于给出 ENGINE 名称。如果使用此命令必须是第一个。例如：

[engine_section]
# This would normally handle an ENGINE named "foo"
foo = foo_section
[foo_section]
# Override default name and use "myfoo" instead.
engine_id = myfoo

命令 dynamic_path 从给定路径加载并添加一个 ENGINE。这等效于将带有路径参数的 ctrls SO_PATH 后跟值为 2 的 LIST_ADD 和 LOAD 发送到动态 ENGINE。如果这不是必需的行为，则可以使用 ctrl 命令将替代 ctrl 直接发送到动态 ENGINE。

命令 init 确定是否初始化 ENGINE。如果值为 0，ENGINE 将不会被初始化，如果为 1 并尝试立即初始化 ENGINE。如果 init 命令不存在，则在其部分中的所有命令都已处理后，将尝试初始化 ENGINE。

命令 default_algorithms 设置 ENGINE 将使用函数 ENGINE_set_default_string() 提供的默认算法。

如果名称与上述命令名称都不匹配，则假定它是发送到 ENGINE 的 ctrl 命令。该命令的值是 ctrl 命令的参数。如果该值为字符串 EMPTY，则不会向该命令发送任何值。

例如：

[engine_section]
# Configure ENGINE named "foo"
foo = foo_section
[foo_section]
# Load engine from DSO
dynamic_path = /some/path/fooengine.so
# A foo specific ctrl.
some_ctrl = some_value
# Another ctrl that doesn't take a value.
other_ctrl = EMPTY
# Supply all default algorithms
default_algorithms = ALL

EVP配置模块

此模块的名称 alg_section 指向包含算法命令的部分。

目前唯一支持的算法命令是 fips_mode，它的值只能是布尔字符串 off。如果 fips_mode 设置为 on，则会发生错误，因为此库版本不支持 FIPS。

SSL 配置模块

该模块的名称为 ssl_conf，它指向包含 SSL 配置的部分。

SSL 配置部分中的每一行都包含配置的名称和包含它的部分。

每个配置部分由 SSL_CONF 的命令值对组成。如果使用适当的配置名称调用 SSL_CTX_config() 或 SSL_config()，则每对将被传递到 SSL_CTX 或 SSL 结构。

注意：配置部分中初始点之前的任何字符都将被忽略，因此可以多次使用相同的命令。

例如：

ssl_conf = ssl_sect
[ssl_sect]
server = server_section
[server_section]
RSA.Certificate = server-rsa.pem
ECDSA.Certificate = server-ecdsa.pem
Ciphers = ALL:!RC4

名称为 system_default 的系统默认配置（如果存在）将在 SSL_CTX 结构的任何创建期间应用。

ssl_conf = ssl_sect
[ssl_sect]
system_default = system_default_sect
[system_default_sect]
MinProtocol = TLSv1.2
MinProtocol = DTLSv1.2

注意

如果配置文件尝试扩展不存在的变量，则会标记错误并且不会加载文件。如果尝试扩展不存在的环境变量，就会发生这种情况。例如，在以前版本的 OpenSSL 中，默认的 OpenSSL 主配置文件使用 HOME 的值，该值可能未在非 Unix 系统上定义，并且会导致错误。

这可以通过包含一个 default部分来提供默认值来解决：如果环境查找失败，则将使用默认值。为了使其正常工作，必须在配置文件中比扩展更早地定义默认值。有关如何执行此操作的示例，请参见示例部分。

如果同一部分中存在相同的变量，则除了最后一个值之外的所有值都将被忽略。在某些情况下，例如使用 DN，同一字段可能会出现多次。例如

1.OU="My first OU"
2.OU="My Second OU"

示例

这是使用上述一些功能的示例配置文件。

# This is the default section.
HOME=/temp
RANDFILE= ${ENV::HOME}/.rnd
configdir=$ENV::HOME/config
[ section_one ]
# We are now in 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

下一个示例展示了如何安全地扩展环境变量。

假设您希望名为 tmpfile 的变量引用临时文件名。它所在的目录可以由 TEMP 或 TMP 环境变量确定，但它们可能根本没有设置为任何值。如果您只包含环境变量名称并且该变量不存在，那么在尝试加载配置文件时这将导致错误。通过使用默认部分，可以使用 TEMP 优先查找两个值，如果两者都没有定义，则使用 /tmp：

TMP=/tmp
# The above value is used if TMP isn't in the environment
TEMP=$ENV::TMP
# The above value is used if TEMP isn't in the environment
tmpfile=${ENV::TEMP}/tmp.filename

进入 FIPS 模式的简单 OpenSSL 库配置示例：

# Default appname: should match "appname" parameter (if any)
# supplied to CONF_modules_load_file et al.
openssl_conf = openssl_conf_section
[openssl_conf_section]
# Configuration module list
alg_section = evp_sect
[evp_sect]
# Set to "yes" to enter FIPS mode if supported
fips_mode = yes

注意：在上面的示例中，您将在不支持 FIPS 的 OpenSSL 版本中遇到错误。

简单的 OpenSSL 库配置，使 TLS 1.2 和 DTLS 1.2 分别成为系统默认的最低 TLS 和 DTLS 版本：

# Toplevel section for openssl (including libssl)
openssl_conf = default_conf_section
[default_conf_section]
# We only specify configuration for the "ssl module"
ssl_conf = ssl_section
[ssl_section]
system_default = system_default_section
[system_default_section]
MinProtocol = TLSv1.2
MinProtocol = DTLSv1.2

最低 TLS 协议适用于基于 TLS 的 SSL_CTX 对象，而最低 DTLS 协议适用于基于 DTLS 的对象。这同样适用于使用 MaxProtocol 设置的最大版本。

更复杂的 OpenSSL 库配置。添加 OID 且不进入 FIPS 模式：

# Default appname: should match "appname" parameter (if any)
# supplied to CONF_modules_load_file et al.
openssl_conf = openssl_conf_section
[openssl_conf_section]
# Configuration module list
alg_section = evp_sect
oid_section = new_oids
[evp_sect]
# This will have no effect as FIPS mode is off by default.
# Set to "yes" to enter FIPS mode, if supported
fips_mode = no
[new_oids]
# New OID, just short name
newoid1 = 1.2.3.4.1
# New OID shortname and long name
newoid2 = New OID 2 long name, 1.2.3.4.2

如果修改“openssl_conf”以匹配适当的“appname”，则上述示例可以与任何支持库配置的应用程序一起使用。

例如，如果上面的第二个示例文件保存到“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

环境

OPENSSL_CONF

配置文件的路径。在 set-user-ID 和 set-group-ID 程序中被忽略。

OPENSSL_ENGINES

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

BUGS

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

转义不太正确：如果你想使用像 \n 这样的序列，你不能在同一行使用任何引号转义。

文件一次加载。这意味着仅当引用的变量在文件中较早定义时，变量扩展才会起作用。

也可以看看

x509(1), req(1), ca(1)

COPYRIGHT

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the “License”). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.