FIPS 模式

🌐 FIPS mode

Node.js 提供了由链接的 OpenSSL 库提供的 FIPS 支持。Node.js 本身并没有经过 FIPS 验证。验证属于特定的 OpenSSL 模块或提供者，并且只有在按照其安全策略部署时才适用。供应商提供的 Node.js 或 OpenSSL 构建可能需要不同的配置；请按照这些构建的供应商文档操作。

🌐 Node.js exposes the FIPS support provided by the linked OpenSSL library. Node.js is not itself FIPS validated. Validation belongs to a specific OpenSSL module or provider and only applies when it is deployed according to its security policy. Vendor-provided Node.js or OpenSSL builds can require a different configuration; follow the vendor's documentation for those builds.

使用 OpenSSL 1.1.1 时，Node.js 必须针对支持 FIPS 的 OpenSSL 库进行构建。

🌐 With OpenSSL 1.1.1, Node.js must be built against a FIPS-capable OpenSSL library.

在 OpenSSL 3 中，FIPS 支持使用 OpenSSL FIPS 模块指南 中描述的提供者模型。使用 FIPS 批准的实现需要：

🌐 With OpenSSL 3, FIPS support uses the provider model described in the OpenSSL FIPS module guide. Using FIPS-approved implementations requires:

  • 正确安装的 OpenSSL 3 FIPS 提供程序。
  • 一个 OpenSSL 3 FIPS 模块配置文件。
  • 要加载到 Node.js 使用的 OpenSSL 库上下文中的 FIPS 提供程序，通常是在 Node.js 启动时通过在 OpenSSL 配置文件中激活它来完成的。
  • 当获取加密实现时，默认的属性查询会包含 fips=yes。可以通过 OpenSSL 配置、--enable-fips 或 --force-fips 在进程启动时设置，或者通过 crypto.setFips(true) 在后续获取中设置。

一个 OpenSSL 3 配置文件的示例看起来是这样的：

🌐 An example OpenSSL 3 configuration file looks like this:

nodejs_conf = nodejs_init
config_diagnostics = 1

.include /<absolute path>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
# The fips section name should match the section name inside the
# included fipsmodule.cnf.
fips = fips_sect
base = base_sect

[base_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

fipsmodule.cnf 文件是在 FIPS 提供程序安装过程中生成的，包含模块完整性和自检信息。具体的命令和参数取决于安装情况；请参见 OpenSSL FIPS 配置 和 OpenSSL FIPS 模块指南。安装过程中使用了 openssl fipsinstall。

🌐 The fipsmodule.cnf file is generated as part of the FIPS provider installation and contains module integrity and self-test information. The exact command and arguments are installation-specific; see OpenSSL FIPS configuration and the OpenSSL FIPS module guide. The installation uses openssl fipsinstall.

示例在 Node.js 启动时激活提供程序并启用 fips=yes 属性查询。如果想在启动时激活提供程序，但稍后使用 crypto.setFips(true) 启用属性查询，可以省略 alg_section = algorithm_sect 和 [algorithm_sect] 块。提供程序仍然必须被加载；在使用这种启动配置时，保持其激活状态。crypto.setFips(true) 应在应用代码使用其他基于 OpenSSL 的 API 之前调用。它并不等同于在进程启动时启用属性查询，因为 Node.js 在应用代码运行之前会初始化一些 OpenSSL 状态。当属性查询必须从进程启动时就激活时，请按示例原样使用，或使用 --enable-fips，--force-fips。

🌐 The example activates the provider and enables the fips=yes property query when Node.js starts. To activate the provider at startup but enable the property query later with crypto.setFips(true), omit alg_section = algorithm_sect and the [algorithm_sect] block. The provider must still be loaded; when using this startup configuration, keep its activation enabled. crypto.setFips(true) should be called before application code uses other OpenSSL-backed APIs. It is not equivalent to enabling the property query from process startup because Node.js initializes some OpenSSL state before application code runs. Use the example as written, --enable-fips, or --force-fips when the property query must be active from process startup.

config_diagnostics 会导致配置错误，从而阻止启动，而不是被忽略。base 提供非加密支持算法，例如编码器和解码器，这些通常需要与 FIPS 提供者一起使用。default_properties = fips=yes 将 OpenSSL 的默认算法选择限制为与 fips=yes 匹配的实现。

将 OPENSSL_CONF 设置为 OpenSSL 配置文件。对于动态加载的提供者，OPENSSL_MODULES 可以设置包含提供者模块的目录。例如：

🌐 Set OPENSSL_CONF to the OpenSSL configuration file. For a dynamically loaded provider, OPENSSL_MODULES can set the directory containing the provider module. For example:

export OPENSSL_CONF=/<path to configuration file>/nodejs.cnf
export OPENSSL_MODULES=/<path to openssl lib>/ossl-modules

--openssl-config 命令行选项用于选择配置文件，并且优先于 OPENSSL_CONF。如果两者都没有设置，则使用 OpenSSL 的默认配置文件。

🌐 The --openssl-config command-line option selects the configuration file and takes precedence over OPENSSL_CONF. If neither is set, OpenSSL's default configuration file is used.

默认情况下，Node.js 会读取 nodejs_conf 部分，而不是 OpenSSL 通常的 openssl_conf 部分。使用 --openssl-shared-config 来读取 openssl_conf，或者在构建 Node.js 时使用 ./configure --openssl-conf-name=<name> 来更改默认部分名称。

🌐 By default, Node.js reads the nodejs_conf section instead of OpenSSL's usual openssl_conf section. Use --openssl-shared-config to read openssl_conf, or build Node.js with ./configure --openssl-conf-name=<name> to change the default section name.

在 OpenSSL 3 上，上面的配置在启动时启用了 fips=yes 属性查询。以下控制选项也可用：

🌐 On OpenSSL 3, the configuration above enables the fips=yes property query at startup. The following controls are also available:

  • --enable-fips 和 --force-fips 启用了属性查询，并且还要求名为 fips 的配置提供程序初始化并通过自检。如果该检查失败，Node.js 会退出。--force-fips 还防止从脚本代码中禁用 FIPS 模式。启用 --force-fips=strict 后，Node.js 还会拒绝通过 OpenSSL FIPS 指示回调报告的未经批准的操作。
  • crypto.setFips() 会改变 FIPS/属性查询状态。在 OpenSSL 3 中，它不会安装、加载、初始化或验证提供者。在调用之前获取的实现不会被更改。
  • crypto.getFips() 报告 FIPS/属性查询状态。在 OpenSSL 3 上，返回值 1 并不证明 FIPS 提供者已加载或验证。
  • 在 --enable-fips-indicator-events 中，'crypto.fips.indicator' 诊断通道报告了由配置为向后兼容的 OpenSSL 3.4 或更高版本 FIPS 提供程序允许的非批准操作。

在 OpenSSL 1.1.1 中，这些控制使用库的 FIPS 模式支持，并且需要一个支持 FIPS 的 OpenSSL 构建。

🌐 With OpenSSL 1.1.1, these controls use the library's FIPS mode support and require a FIPS-capable OpenSSL build.

只有在当前 FIPS 设置下可用的算法才能使用。在 OpenSSL 3 中，如果没有已加载的提供者提供与 fips=yes 匹配的加密实现，获取它会失败，通常会出现 ERR_OSSL_EVP_UNSUPPORTED。当 FIPS 模式禁用时，Node.js 支持的算法在当前 FIPS 设置下不可用时，也可能出现同样的错误。

🌐 Only algorithms available under the active FIPS settings can be used. With OpenSSL 3, if no loaded provider supplies a requested cryptographic implementation matching fips=yes, fetching it fails, typically with ERR_OSSL_EVP_UNSUPPORTED. The same error can occur for algorithms that Node.js supports when FIPS mode is disabled but that are unavailable under the active FIPS settings.

OpenSSL 文档说明，同一个 FIPS 提供程序不能被同一个进程中的多个 libcrypto 副本使用。这可能会影响加载另一个 libcrypto 副本的本地插件；OpenSSL 文档中提供的解决方法是为每个 libcrypto 实例使用一个单独的提供程序副本。详见 OpenSSL FIPS 提供者的限制。

🌐 OpenSSL documents that the same FIPS provider cannot be used by multiple copies of libcrypto in one process. This can affect native addons that load another copy of libcrypto; OpenSSL's documented workaround is to use a separate copy of the provider for each libcrypto instance. See OpenSSL FIPS provider limitations.