OpenSSL

openssl-fipsinstall

名称

openssl-fipsinstall - 执行 FIPS 配置安装

概要

openssl fipsinstall [-help] [-in configfilename] [-out configfilename] [-module modulefilename] [-provider_name providername] [-section_name sectionname] [-verify] [-mac_name macname] [-macopt nm:v] [-noout] [-quiet] [-pedantic] [-no_conditional_errors] [-no_security_checks] [-ems_check] [-no_drbg_truncated_digests] [-self_test_onload] [-self_test_oninstall] [-corrupt_desc selftest_description] [-corrupt_type selftest_type] [-config parent_config]

描述

该命令用于生成 FIPS 模块配置文件。每次加载 FIPS 模块时，都可以使用此配置文件将数据传递到 FIPS 模块自测试。FIPS 模块始终验证其 MAC，但可以选择仅在安装时运行一次 KAT。

生成的配置文件包含以下内容：

- FIPS 模块文件的 MAC。

- 测试状态指示器。

这指示已知答案自测试 (KAT) 是否已成功运行。

- 状态指示器的 MAC。

- 用于控制条件自测试错误。

默认情况下，如果连续测试（例如密钥对测试）失败，则 FIPS 模块将进入错误状态，并且此后将无法访问任何服务或加密算法。默认值为 '1' 将导致 fips 模块进入错误状态。如果值为 '0'，则不会进入模块错误状态。无论是否进入错误状态，当前操作（例如密钥生成）都将返回错误。如果未进入模块错误状态，则用户有责任重试操作。

- 用于指示是否执行运行时安全检查的控制。

这指示是否使用与执行密钥最小安全强度和批准的曲线名称等安全参数相关的运行时检查。默认值为 '1' 将执行检查。如果值为 '0'，则不会执行检查，并且必须通过相关安全策略中记录的程序来执行 FIPS 合规性。

此文件在 fips_config(5) 中有描述。

选项

-help

打印使用信息。

-module filename

要对其执行完整性检查的 FIPS 模块的文件名。文件名中提供的路径用于在激活模块时加载模块，这将覆盖环境变量 OPENSSL_MODULES。

-out configfilename

将配置数据输出到的文件名；默认值为标准输出。

-in configfilename

要从中加载配置数据的输入文件名。如果指定了 -verify 选项，则必须使用它。

-verify

验证输入配置文件是否包含正确的信息。

-provider_name providername

配置文件中提供程序的名称。默认值为 fips。

-section_name sectionname

配置文件中节区的名称。默认值为 fips_sect。

-mac_name name

指定将要使用的受支持 MAC 算法的名称。可用的 MAC 机制将取决于构建 OpenSSL 时使用的选项。要查看受支持的 MAC 列表，请使用命令 openssl list -mac-algorithms。默认值为 HMAC。

-macopt nm:v

将选项传递给 MAC 算法。可以在 EVP_MAC 实现文档中找到控制的完整列表。此命令常用的控制字符串是

key:string

将 MAC 密钥指定为字母数字字符串（如果密钥仅包含可打印字符，请使用）。字符串长度必须符合 MAC 算法的任何限制。每个 MAC 算法都必须指定一个密钥。如果未提供密钥，则使用在配置 OpenSSL 时指定的默认密钥。

hexkey:string

以十六进制形式指定 MAC 密钥（每字节两位十六进制数字）。密钥长度必须符合 MAC 算法的任何限制。每个 MAC 算法都必须指定一个密钥。如果未提供密钥，则使用在配置 OpenSSL 时指定的默认密钥。

digest:string

HMAC 使用字母数字字符串（如果密钥仅包含可打印字符，请使用）。字符串长度必须符合 MAC 算法的任何限制。要查看受支持的摘要列表，请使用命令 openssl list -digest-commands。默认摘要为 SHA-256。

-noout

禁用自测试日志记录。

-pedantic

配置模块，使其严格符合 FIPS，而不是向后兼容。这将启用条件错误、安全检查等。请注意，任何先前的配置选项都将被覆盖，任何违反 FIPS 合规性的后续配置选项都将导致错误。

-no_conditional_errors

配置模块，使其在条件自测试失败时（如上所述）不会进入错误状态。

-no_security_checks

配置模块，使其不会执行如上所述的运行时安全检查。

启用配置选项 "no-fips-securitychecks" 提供了另一种在编译时关闭检查的方法。

-ems_check

配置模块，使其在使用 TLS1_PRF KDF 算法时启用运行时扩展主密钥 (EMS) 检查。此检查默认情况下处于禁用状态。有关 EMS 的信息，请参见 RFC 7627。

-no_drbg_truncated_digests

配置模块，使其不允许将截断的摘要与哈希和 HMAC DRBG 结合使用。有关详细信息，请参见 FIPS 140-3 IG D.R。

-self_test_onload

不要将与 "测试状态指示器" 和 "MAC 状态指示器" 相关的两个字段写入输出配置文件。没有这些字段，每次加载模块时都会运行自测试 KAT。此选项可用于交叉编译，因为自测试至少需要在每个目标机器上运行一次。一旦自测试在目标机器上运行，用户可以使用其他机制将这两个字段添加到配置中。

这是默认设置。

-self_test_oninstall

-self_test_oninstall 的反面。与 "测试状态指示器" 和 "MAC 状态指示器" 相关的两个字段将写入输出配置文件。

-quiet

不输出通过/失败消息。表示 -noout。

-corrupt_desc selftest_description, -corrupt_type selftest_type

可以使用 corrupt 选项按名称测试一个或多个自测试的失败。可以使用一个或两个选项来选择要破坏的测试。有关可使用值的参考，请参阅 OSSL_PROVIDER-FIPS(7) 中的 st-desc 和 st-type 条目。

-config parent_config

测试 FIPS 提供程序是否可以从指定的配置文件加载。对该应用程序的先前调用需要生成由基本 parent_config 配置文件包含的额外配置数据。有关如何设置提供程序节区的更多信息，请参见 config(5)。如果使用了 '-config'，则所有其他选项将被忽略。

注意

如果未指定 -quiet 和 -noout 选项，或使用了 -corrupt_desc 或 -corrupt_type 选项，则默认情况下会记录自测试结果。如果基本配置文件设置为自动加载 fips 模块，则在 fipsinstall 应用程序有机会设置自己的自测试回调之前，将加载并自测试 fips 模块。因此，自测试输出和 -corrupt_desc 和 -corrupt_type 选项将被忽略。对于正常使用，基本配置文件在生成 fips 配置文件时应该使用默认提供程序。

-self_test_oninstall 选项已添加，并且 -self_test_onload 选项已在 OpenSSL 3.1 中设置为默认值。

该命令和所有剩余选项已在 OpenSSL 3.0 中添加。

示例

计算 FIPS 模块 fips.so 的 mac，并为该模块运行 FIPS 自测试，并将 fips.cnf 配置文件保存起来

openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips

验证配置文件 fips.cnf 是否包含正确的信息

openssl fipsinstall -module ./fips.so -in fips.cnf  -provider_name fips -verify

破坏任何描述为 SHA1 的自测试

openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips \
        -corrupt_desc 'SHA1'

验证 fips 模块是否可以从基本配置文件加载

export OPENSSL_CONF_INCLUDE=<path of configuration files>
export OPENSSL_MODULES=<provider-path>
openssl fipsinstall -config' 'default.cnf'

另请参见

config(5), fips_config(5), OSSL_PROVIDER-FIPS(7), EVP_MAC(3)

版权

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

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