为 Linux 配置 OpenSSL

  • 项目

注意

本文引用了 CentOS，这是一个接近生命周期结束 (EOL) 状态的 Linux 发行版。 请相应地考虑你的使用和规划。 有关详细信息，请参阅 CentOS 生命周期结束指南。

在语音 SDK 中，OpenSSL 动态配置为主机系统版本。

注意

本文仅在语音 SDK 在 Linux 上受支持时适用。

若要确保连接性，请验证是否在系统中安装了 OpenSSL 证书。 运行命令：

openssl version -d

基于 Ubuntu/Debian 的系统上的输出应为：

OPENSSLDIR: "/usr/lib/ssl"

检查 OPENSSLDIR 下是否有 certs 子目录。 在上面的示例中，它会是 /usr/lib/ssl/certs。

  • 如果有 /usr/lib/ssl/certs 并且其中包含多个单独的证书文件（带有 .crt 或 .pem 扩展名），则无需执行进一步的操作。

  • 如果 OPENSSLDIR 是 /usr/lib/ssl 以外的其他内容，或者存在单一的证书捆绑包文件而不是多个单独的文件，则需要设置相应的 SSL 环境变量来指示可以在哪里找到证书。

示例

下面是每个 OpenSSL 目录要配置的一些环境变量示例。

  • OPENSSLDIR 为 /opt/ssl。 存在包含多个 .crt 或 .pem 文件的子目录 certs。 在使用语音 SDK 之前，请将环境变量 SSL_CERT_DIR 设置为指向 /opt/ssl/certs。 例如：
export SSL_CERT_DIR=/opt/ssl/certs
  • OPENSSLDIR 是 /etc/pki/tls（类似于基于 RHEL/CentOS 的系统）。 有一个包含证书捆绑包文件（例如 ca-bundle.crt）的 certs 子目录。 在使用语音 SDK 之前，请将环境变量 SSL_CERT_FILE 设置为指向该文件。 例如：
export SSL_CERT_FILE=/etc/pki/tls/certs/ca-bundle.crt

证书吊销检查

当语音 SDK 连接到语音服务时，它会检查传输层安全性 (TLS/SSL) 证书。 语音 SDK 会验证远程终结点所报告的证书是否可信且是否尚未被吊销。 此验证为防范涉及欺骗和其他相关途径的攻击提供了一层保护。 检查通过 Azure 使用的证书颁发机构 (CA) 检索证书吊销列表 (CRL) 完成。 本文档中列出了已更新的 TLS CRL 的 Azure CA 下载位置。

如果作为语音服务的目标报告了在检索的 CRL 中吊销的证书，SDK 将终止连接，并通过 Canceled 事件报告错误。 如果没有更新的 CRL，无法检查所报告证书的真实性。 因此，语音 SDK 还会将从 Azure CA 位置下载 CRL 失败视为错误。

警告

如果你的解决方案使用代理或防火墙，则应将其配置为允许访问 Azure 使用的所有证书吊销列表 URL。 请注意，其中许多 URL 都在 microsoft.com 域外部，因此，仅允许访问 *.microsoft.com 是不够的。 有关详细信息，请参阅此文档。 在特殊情况下，你可以忽略 CRL 失败（请参阅对应的部分），但强烈建议不要使用此类配置，尤其是对于生产方案。

大型 CRL 文件 (>10 MB)

与 CRL 相关的故障的一个原因是使用大的 CRL 文件。 此类错误通常仅存在于具有扩展 CA 链的特殊环境。 标准公共终结点不应遇到此类问题。

语音 SDK 使用的默认最大 CRL (10 MB) 每个配置对象都可以调整。 此调整的属性键为 CONFIG_MAX_CRL_SIZE_KB，并且指定为字符串的值默认为“10000”(10 MB)。 例如，创建 SpeechRecognizer 对象时（用于管理语音服务连接），可以在其 SpeechConfig 中设置此属性。 在下面的代码片段中，配置已调整为允许 CRL 文件大小最大为 15 MB。

config.SetProperty("CONFIG_MAX_CRL_SIZE_KB"", "15000");

config->SetProperty("CONFIG_MAX_CRL_SIZE_KB"", "15000");

config.setProperty("CONFIG_MAX_CRL_SIZE_KB"", "15000");

speech_config.set_property_by_name("CONFIG_MAX_CRL_SIZE_KB"", "15000")

speechConfig.properties.SetPropertyByString("CONFIG_MAX_CRL_SIZE_KB", "15000")

忽视或忽略 CRL 失败

如果无法将环境配置为访问 Azure CA 位置，则语音 SDK 将无法检索更新的 CRL。 可以将 SDK 配置为继续并记录下载失败，或忽视所有 CRL 检查。

警告

CRL 检查是一种安全措施，忽视检查可提高对攻击的敏感性。 针对 CRL 检查缓解的攻击途径提供保护，如果未全面考虑安全隐患和替代机制，则不应忽视这些检查。

若要在无法检索 CRL 时继续进行连接，请设置属性 "OPENSSL_CONTINUE_ON_CRL_DOWNLOAD_FAILURE" 为 "true"。 仍将尝试检索 CRL，并且仍将在日志中发送失败，但允许连接尝试继续。

config.SetProperty("OPENSSL_CONTINUE_ON_CRL_DOWNLOAD_FAILURE", "true");

config->SetProperty("OPENSSL_CONTINUE_ON_CRL_DOWNLOAD_FAILURE", "true");

config.setProperty("OPENSSL_CONTINUE_ON_CRL_DOWNLOAD_FAILURE", "true");

speech_config.set_property_by_name("OPENSSL_CONTINUE_ON_CRL_DOWNLOAD_FAILURE", "true")


speechConfig.properties.SetPropertyByString("OPENSSL_CONTINUE_ON_CRL_DOWNLOAD_FAILURE", "true")

若要关闭证书吊销检查，请将属性 "OPENSSL_DISABLE_CRL_CHECK" 设置为 "true"。 然后，在连接到语音服务时，不会尝试检查或下载 CRL，并且不会自动验证报告的 TLS/SSL 证书。

config.SetProperty("OPENSSL_DISABLE_CRL_CHECK", "true");

config->SetProperty("OPENSSL_DISABLE_CRL_CHECK", "true");

config.setProperty("OPENSSL_DISABLE_CRL_CHECK", "true");

speech_config.set_property_by_name("OPENSSL_DISABLE_CRL_CHECK", "true")

speechConfig.properties.SetPropertyByString("OPENSSL_DISABLE_CRL_CHECK", "true")

CRL 缓存和性能

默认情况下，语音 SDK 将在磁盘上缓存已成功下载的 CRL，以提高将来连接的初始延迟。 如果不存在缓存的 CRL 或缓存的 CRL 已过期，将下载新列表。

某些 Linux 发行版未定义 TMP 或 TMPDIR 环境变量，因此语音 SDK 无法缓存下载的 CRL。 如果未定义 TMP 或 TMPDIR 环境变量，语音 SDK 将针对每次连接下载新的 CRL。 为了提高初始连接性能，可以创建名为 TMPDIR 的环境变量并将其设置为临时目录的可访问路径。

后续步骤