Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

使用 TLS Registry 管理安全密钥和证书

Red Hat build of Quarkus 3.15

Red Hat Customer Content Services

摘要

TLS Registry 是一个 Quarkus 扩展，可集中 TLS 配置，从而更轻松地在应用程序间管理和维护安全连接。

向红帽构建的 Quarkus 文档提供反馈
复制链接

要报告错误或改进文档，请登录您的红帽 JIRA 帐户并提交问题。如果您没有红帽 JIRA 帐户，系统会提示您创建一个帐户。

流程

  1. 单击以下链接 来创建 ticket。
  2. 在 Summary 中输入有关此问题的简单描述。
  3. 在描述中提供问题或增强功能的详细描述。请包括有问题的文档 URL。
  4. 点 Submit 创建问题并将其路由到适当的文档团队。

第 1 章 使用 TLS Registry 管理安全密钥和证书
复制链接

TLS Registry 是一个 Quarkus 扩展，可集中 TLS 配置，从而更轻松地在应用程序间管理和维护安全连接。在单一集中位置定义 TLS 配置时，您可以使用 TLS Registry 从应用程序中的多个组件引用这些配置，以确保一致性并减少配置错误的可能性。

TLS Registry 整合设置并支持多个命名配置。因此，您可以为不同的应用程序部分定制 TLS 设置。当不同的组件需要不同的安全配置时，这个灵活性特别有用。

使用兼容扩展时，TLS Registry 扩展会自动包含在项目中，如 Quarkus REST、gRPC。因此，使用 TLS Registry 的应用程序可以准备好处理开箱即用的安全通信。

TLS Registry 还提供与各种密钥存储格式（如 PKCS12、PEM 和 JKS）自动重新载入和兼容性。

1.1. 使用 TLS registry
复制链接

要配置 TLS 连接，包括密钥和信任存储，请使用 quarkus.tlssignal 属性。这些属性是必需的：

  • 设置默认的 TLS 配置，直接在 quarkus.tlsllowedRegistries 下定义
  • 使用 quarkus.tls.<name > …​ 创建单独的、命名的配置。通过指定 quarkus.tls.<name& gt; regarding 属性，您可以调整特定组件的 TLS 设置。

1.1.1. 为 HTTP 服务器配置 HTTPS
复制链接

为确保客户端-服务器通信，通常需要客户端验证服务器的真实性。

  • 服务器必须使用密钥存储，其中包含其证书和私钥
  • 客户端需要配置有信任存储以验证服务器证书

在 TLS 握手期间，服务器提供其证书，然后验证客户端。这可防止中间人攻击和安全数据传输。

以下小节介绍了如何使用 PEM 或 PKCS12 密钥类型设置 HTTPS。另外，它们提供了有关如何使用命名配置一次指定和管理多个 TLS 设置的信息，这样您可以为每个设置定义不同的设置。

根据密钥存储类型使用以下配置示例：

  • 使用 PEM 文件： 

    quarkus.tls.key-store.pem.0.cert=server.crt
quarkus.tls.key-store.pem.0.key=server.key
quarkus.http.insecure-requests=disabled # Reject HTTP requests
    Copy to Clipboard Toggle word wrap

  • 使用 p12 (PKCS12)密钥存储： 

    quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret
quarkus.http.insecure-requests=disabled # Reject HTTP requests
    Copy to Clipboard Toggle word wrap

  • 使用名称区分多个配置： 

    quarkus.tls.https.key-store.p12.path=server-keystore.p12
quarkus.tls.https.key-store.p12.password=secret
quarkus.http.insecure-requests=disabled
quarkus.http.tls-configuration-name=https
    Copy to Clipboard Toggle word wrap

1.1.2. 为客户端配置 HTTPS
复制链接

以下示例将名为 "hello" 的 gRPC 客户端配置为使用带有默认 TLS 配置中的信任存储的 HTTPS： 

quarkus.tls.trust-store.jks.path=grpc-client-truststore.jks
quarkus.tls.trust-store.jks.password=password

quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true
Copy to Clipboard Toggle word wrap

1.1.3. 配置 mTLS
复制链接

要在红帽构建的 Quarkus 应用程序中设置 mutual TLS (mTLS)，请通过创建和管理密钥存储和信任存储来配置服务器和客户端：

  • 服务器密钥存储 ：包含服务器的证书和私钥。
  • Client keystore ：包含客户端的证书和私钥。
  • 服务器 truststore ：存储客户端的证书以验证客户端。

  • 客户端信任存储 ：存储服务器证书以验证服务器。

    指定密钥存储和信任存储的示例配置：

    quarkus.tls.my-server.key-store.p12.path=target/certs/grpc-keystore.p12
quarkus.tls.my-server.key-store.p12.password=password
quarkus.tls.my-server.trust-store.p12.path=target/certs/grpc-server-truststore.p12
quarkus.tls.my-server.trust-store.p12.password=password

quarkus.tls.my-client.trust-store.p12.path=target/certs/grpc-client-truststore.p12
quarkus.tls.my-client.trust-store.p12.password=password
quarkus.tls.my-client.key-store.p12.path=target/certs/grpc-client-keystore.p12
quarkus.tls.my-client.key-store.p12.password=password

quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.tls-configuration-name=my-client
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true

quarkus.http.ssl.client-auth=REQUIRED # Enable mTLS
quarkus.http.insecure-requests=disabled
quarkus.http.tls-configuration-name=my-server
quarkus.grpc.server.use-separate-server=false
quarkus.grpc.server.plain-text=false
    Copy to Clipboard Toggle word wrap

    此配置通过确保服务器和客户端验证彼此的证书启用 mTLS，从而提供额外的安全层。

1.2. 引用 TLS 配置
复制链接

要使用 quarkus.tls.<name> configured 所述引用您创建的 名为 配置示例 ，如 使用 TLS registry 中所述，使用 tls-configuration-name 属性，如下例所示：

核心 HTTP 服务器配置示例：

# Reference the named configuration
quarkus.http.tls-configuration-name=MY_TLS_CONFIGURATION
Copy to Clipboard Toggle word wrap

gRPC 客户端配置示例：

quarkus.grpc.clients.hello.tls-configuration-name=MY_TLS_CONFIGURATION
Copy to Clipboard Toggle word wrap

1.3. 配置 TLS
复制链接

TLS 配置主要涉及管理密钥存储和信任存储。具体设置取决于使用的格式，如 PEM、P12 或 JKS。

以下小节概述了用于配置 TLS 的各种属性。

1.3.1. 密钥存储
复制链接

密钥存储用于存储私钥和证书。它们主要在服务器端使用，但也可以在使用 mTLS 时在客户端上使用。

1.3.1.1. PEM 密钥存储
复制链接

隐私增强邮件(PEM)密钥存储由文件对列表组成：

  • 证书文件 - .crt 或 .pem 文件
  • 私钥文件通常是 .key 文件

配置 PEM 密钥存储： 

quarkus.tls.key-store.pem.a.cert=server.crt
quarkus.tls.key-store.pem.a.key=server.key
quarkus.tls.key-store.pem.b.cert=my-second-cert.crt
quarkus.tls.key-store.pem.b.key=my-second-key.key
Copy to Clipboard Toggle word wrap

在大多数情况下，您只需要一个由证书和私钥组成的对。即使证书是证书链的一部分，它只包含一个与最终用户证书对应的私钥。

当配置了多个对时，选择配置的证书和私钥对基于 Server Name Indication (SNI)。客户端将客户端要连接到的服务器的名称发送到，服务器选择相应的证书和私钥对。要使用这个功能，请确保客户端和服务器上都启用了 SNI。

重要

当配置多个密钥对或证书对时，服务器默认以名称的字典顺序执行配置的对，如在上例中使用 store.pem.a 和 store.pem.b 所示。首先执行具有最低字典顺序的对。要更改它，您可以使用 quarkus.tls.key-store.pem.order 属性定义顺序。例如，quarkus.tls.key-store.pem.order=b,c,a。

使用 SNI 时此设置非常重要，因为它使用第一个指定的对作为默认值。

1.3.1.2. PKCS12 密钥存储
复制链接

PKCS12 密钥存储是包含证书和私钥的单个文件。

配置 PKCS12 密钥存储： 

quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret
Copy to Clipboard Toggle word wrap

.p12 文件受密码保护，因此您需要提供密码以打开密钥存储。

这些文件可以包含多个证书和私钥。如果是这种情况，请执行以下操作之一：

  • 提供并配置您要使用的证书和私钥的别名： 

    quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret
quarkus.tls.key-store.p12.alias=my-alias
quarkus.tls.key-store.p12.alias-password=my-alias-password
    Copy to Clipboard Toggle word wrap
  • 或者，使用 SNI 选择适当的证书和私钥。请注意，所有密钥都必须使用相同的密码。
1.3.1.3. JKS 密钥存储
复制链接

JKS 密钥存储是单一文件，其中包含服务器或客户端的证书和私钥，用于在 TLS/SSL 连接中进行身份验证和建立安全通信。

重要

JKS 是旧的，但仍然广泛使用特定于 Java 的格式。但是，要使用这种格式，您必须使用特定格式，并且 nowadays 也已弃用，Java 工具。因此，不建议将其与红帽构建的 Quarkus 应用程序一起使用。

另外，OpenShift cert-manager 或 Let 的 Encrypt 通常不提供 JKS，并且保持 PEM-only。

配置 JKS 密钥存储： 

quarkus.tls.key-store.jks.path=server-keystore.jks
quarkus.tls.key-store.jks.password=secret
Copy to Clipboard Toggle word wrap

.jks 文件受密码保护，因此您需要提供密码以打开密钥存储。另外，它们也可以包含多个证书和私钥。如果是这种情况：

  • 提供并配置您要使用的证书和私钥的别名： 

    quarkus.tls.key-store.jks.path=server-keystore.jks
quarkus.tls.key-store.jks.password=secret
quarkus.tls.key-store.jks.alias=my-alias
quarkus.tls.key-store.jks.alias-password=my-alias-password
    Copy to Clipboard Toggle word wrap
  • 或者，使用 SNI 选择适当的证书和私钥。请注意，所有密钥都必须使用相同的密码。
1.3.1.4. SNI
复制链接

服务器名称 Indication (SNI)是一个 TLS 扩展，使客户端能够指定在 TLS 握手期间尝试连接的主机名。SNI 可让服务器为单个 IP 地址上的多个域提供不同的 TLS 证书，这有助于为虚拟主机场景提供安全通信。

启用 SNI： 

quarkus.tls.key-store.sni=true # Disabled by default
Copy to Clipboard Toggle word wrap

启用 SNI 后，客户端表示 TLS 握手期间的服务器名称，允许服务器选择适当的证书：

  • 使用 PEM 文件配置密钥存储时，必须提供多个证书(CRT)和密钥文件。CRT 是 X.509 证书文件的一个通用文件扩展，通常采用 PEM (Privacy-Enhanced Mail)格式。这些文件包含公共证书。
  • 使用 JKS 或 P12 文件配置密钥存储时，服务器会根据 TLS 握手期间客户端提供的 SNI 主机名选择适当的证书。服务器使用存储在密钥存储中的证书中配置的通用名称(CN)或主题替代名称(SAN)匹配 SNI 主机名。所有密钥存储和别名密码都必须相同。
1.3.1.5. 凭证供应商
复制链接

您可以使用凭据提供程序，而不是在配置中传递密钥存储密码和别名密码。

凭据提供程序提供检索密钥存储和别名密码的方式。请注意，只有在配置中未设置密码或别名密码时，才会使用凭证供应商。

配置凭证供应商： 

# The name of the credential bucket in the credentials provider
quarkus.tls.key-store.credentials-provider.name=my-credentials

# The name of the bean providing the credential provider (optional, using the default credential provider if not set)
quarkus.tls.key-store.credentials-provider.bean-name=my-credentials-provider

# The key used to retrieve the keystore password, `password` by default
quarkus.tls.key-store.credentials-provider.password-key=password

# The key used to retrieve the alias password, `alias-password` by default
quarkus.tls.key-store.credentials-provider.alias-password-key=alias-password
Copy to Clipboard Toggle word wrap
重要

凭证供应商只能与 PKCS12 和 JKS 密钥存储一起使用。

1.3.2. 信任存储
复制链接

信任存储用于存储可信方的证书。在常规 TLS 中，客户端使用信任存储来验证服务器。使用 mutual TLS (mTLS)，服务器和客户端都使用信任存储来相互验证。

1.3.2.1. PEM truststores
复制链接

PEM truststores 由 .crt 或 .pem 文件列表组成。它们各自包含一个证书。

配置 PEM 信任存储： 

quarkus.tls.trust-store.pem.certs=ca.crt,ca2.pem
Copy to Clipboard Toggle word wrap
1.3.2.2. PKCS12 信任存储
复制链接

PKCS12 信任存储是一个包含证书的单个文件。当包含多个证书时，您可以使用别名选择适当的证书。

配置 PKCS12 信任存储： 

quarkus.tls.trust-store.p12.path=client-truststore.p12
quarkus.tls.trust-store.p12.password=password
quarkus.tls.trust-store.p12.alias=my-alias
Copy to Clipboard Toggle word wrap

.p12 文件受密码保护，因此您需要提供密码以打开信任存储。但是，与密钥存储不同，别名不需要密码，因为它包含公共证书，而不是私钥。

1.3.2.3. JKS 信任存储
复制链接

JKS 信任存储是包含多个证书的单个文件。当存在多个证书时，您可以使用别名选择适当的证书。但是，避免使用 JKS 格式，因为它比 PKCS12 的安全性较低。

配置 JKS 信任存储： 

quarkus.tls.trust-store.jks.path=client-truststore.jks
quarkus.tls.trust-store.jks.password=password
quarkus.tls.trust-store.jks.alias=my-alias
Copy to Clipboard Toggle word wrap

.jks 文件受密码保护，因此您需要提供密码以打开信任存储。但是，与密钥存储不同，别名不需要密码，因为它包含公共证书，而不是私钥。

1.3.2.4. 凭证供应商
复制链接

您可以使用凭证供应商，而不是在配置中传递信任存储密码。凭证供应商允许您检索密码和其他凭证。请注意，只有在配置中未设置密码时，才会使用凭证供应商。

配置凭证供应商： 

# The name of the credential bucket in the credentials provider
quarkus.tls.trust-store.credentials-provider.name=my-credentials

# The name of the bean providing the credential provider (optional, using the default credential provider if not set)
quarkus.tls.trust-store.credentials-provider.bean-name=my-credentials-provider

# The key used to retrieve the truststore password, `password` by default
quarkus.tls.trust-store.credentials-provider.password-key=password
Copy to Clipboard Toggle word wrap
重要

凭证供应商只能与 PKCS12 和 JKS 信任存储一起使用。

1.3.3. 其他属性
复制链接

虽然 keystores 和 truststores 是最重要的属性，但还有其他属性可用于配置 TLS。

注意

虽然以下示例 使用默认配置，但您可以通过将属性与配置的名称作为前缀来使用 命名 配置。

1.3.3.1. 密码套件
复制链接

密码套件是您可以在 TLS 握手过程中使用的密码列表。您可以配置启用的密码套件的排序列表。如果没有配置，则会从内置密码中选择合理的默认值。但是，在指定时，您的配置前面的是 SSL 引擎定义的默认套件。

配置密码套件： 

quarkus.tls.cipher-suites=TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384
Copy to Clipboard Toggle word wrap
1.3.3.2. TLS 协议版本
复制链接

TLS 协议版本是 TLS 握手期间可以使用的协议列表。启用的 TLS 协议版本以用逗号分开的排序列表的形式指定。相关的配置属性是 quarkus.tls.protocols （或 quarkus.tls.<name>.protocols 用于命名 TLS 配置）。如果没有配置，则默认为 TLSv1.3，TLSv1.2。

可用的选项有 TLSv1、TLSv1.1、TLSv1.2 和 TLSv1.3。

例如，仅启用 TLSv1.3 ： 

quarkus.tls.protocols=TLSv1.3
Copy to Clipboard Toggle word wrap
1.3.3.3. 握手超时
复制链接

当建立 TLS 连接时，握手阶段是第一步。在此阶段，客户端和服务器交换信息来建立连接，这通常包括密码套件、TLS 协议版本和验证。

为握手阶段配置超时： 

quarkus.tls.handshake-timeout=10S # Default.
Copy to Clipboard Toggle word wrap
1.3.3.4. ALPN
复制链接

应用程序协议协商(ALPN)是一种 TLS 扩展，它允许客户端和服务器协商它们将在 TLS 握手期间进行通信的协议。ALPN 通过允许客户端在建立 TLS 连接前向服务器指示首选应用程序协议来启用效率更高的通信。

这有助于在 HTTP/2 等情形中使用多个协议，从而加快协议选择。

ALPN 默认启用。

  • 要禁用它： 

    quarkus.tls.alpn=false
    Copy to Clipboard Toggle word wrap
    警告

    不建议在非预期的情况下禁用 ALPN，因为它可能会导致性能下降、协议协商问题和意外行为，特别是 HTTP/2 等协议。但是，在协议协商导致冲突的特定边缘情况下，禁用 ALPN 有助于诊断原生不一致或测试性能。

1.3.3.5. 证书撤销列表(CRL)
复制链接

证书撤销列表(CRL)是发布证书颁发机构(CA)在调度过期日期前撤销的证书列表。当证书被破坏时，不再需要或被视为无效，CA 将其添加到 CRL 中，以告知依赖方不再信任它。

您可以使用 DER 或 PKCS Slack7 (P7B)格式，使用您不再信任的证书文件列表配置 CRL。

  • 对于 DER 格式，传递 DER 编码的 CRL。
  • 对于 PKCS#7 格式，传递 SignedData 对象，其中唯一 significant 字段是 crls。

配置 CRL： 

quarkus.tls.certificate-revocation-list=ca.crl, ca2.crl
Copy to Clipboard Toggle word wrap
1.3.3.6. 信任所有证书和主机名验证
复制链接

您可以将 TLS 连接配置为信任所有证书，并禁用主机名验证。请注意，它们是两个不同的进程：

  • 信任所有证书都忽略证书验证，因此所有证书都是可信的证书。此方法可用于使用自签名证书进行测试，但不应在生产环境中使用。
  • 主机名验证是验证服务器身份的过程。

它对防止中间人攻击很有用，并且通常默认为 HTTPS 或 LDAPS。

重要

不应该在生产环境中使用这两个属性。

信任所有证书： 

quarkus.tls.trust-all=true
Copy to Clipboard Toggle word wrap

禁用主机名验证： 

quarkus.tls.hostname-verification-algorithm=NONE
Copy to Clipboard Toggle word wrap

1.3.4. 配置参考
复制链接

下表列出了支持的属性：

build 时修复的 - 配置属性在构建时修复 - 所有其他配置属性在运行时可覆盖

Expand

配置属性

类型

default

在构建时修复了 quarkus.tls.lets-encrypt.enabled

设置为 true 以启用加密支持。

环境变量： QUARKUS_TLS_LETS_ENCRYPT_ENABLED

布尔值

false

quarkus.tls.key-store.pem.order

密钥/证书文件的顺序，取决于 keyCerts 映射中的名称。

默认情况下，Quarkus 使用字典顺序对键进行排序。此属性允许您指定密钥/证书文件的顺序。

环境变量： QUARKUS_TLS_KEY_STORE_PEM_ORDER

字符串列表

 

quarkus.tls.key-store.p12.path

密钥存储文件的路径(P12 / PFX 格式)。

环境变量： QUARKUS_TLS_KEY_STORE_P12_PATH

path

所需的 HEKETI Required

quarkus.tls.key-store.p12.password

密钥存储的密码。如果没有设置，则必须从凭证提供程序检索密码。

环境变量： QUARKUS_TLS_KEY_STORE_P12_PASSWORD

string

 

quarkus.tls.key-store.p12.alias

密钥存储中私钥和证书的别名。

环境变量： QUARKUS_TLS_KEY_STORE_P12_ALIAS

string

 

quarkus.tls.key-store.p12.alias-password

密钥存储中别名的密码。如果没有设置，则从凭证提供程序检索密码。

环境变量： QUARKUS_TLS_KEY_STORE_P12_ALIAS_PASSWORD

string

 

quarkus.tls.key-store.p12.provider

密钥存储的提供商。

环境变量： QUARKUS_TLS_KEY_STORE_P12_PROVIDER

string

 

quarkus.tls.key-store.jks.path

密钥存储文件的路径(JKS 格式)。

环境变量： QUARKUS_TLS_KEY_STORE_JKS_PATH

path

所需的 HEKETI Required

quarkus.tls.key-store.jks.password

密钥存储的密码。如果没有设置，则必须从凭证提供程序检索密码。

环境变量： QUARKUS_TLS_KEY_STORE_JKS_PASSWORD

string

 

quarkus.tls.key-store.jks.alias

密钥存储中私钥和证书的别名。

环境变量： QUARKUS_TLS_KEY_STORE_JKS_ALIAS

string

 

quarkus.tls.key-store.jks.alias-password

密钥存储中别名的密码。如果没有设置，则可从凭据提供程序检索密码。

环境变量： QUARKUS_TLS_KEY_STORE_JKS_ALIAS_PASSWORD

string

 

quarkus.tls.key-store.jks.provider

密钥存储的提供商。

环境变量： QUARKUS_TLS_KEY_STORE_JKS_PROVIDER

string

 

quarkus.tls.key-store.sni

启用服务器名称调用(SNI)。

服务器名称 Indication (SNI)是一个 TLS 扩展，它允许客户端指定在 TLS 握手期间尝试连接到的主机名。这可让服务器在单个 IP 地址上为多个域提供不同的 SSL 证书，为虚拟主机场景提供安全通信。

启用此设置后，客户端在 TLS 握手期间指示服务器名称，允许服务器选择正确的证书。

使用 PEM 文件配置密钥存储时，必须指定多个 CRT/Key。使用 JKS 或 P12 文件配置密钥存储时，它会根据 SNI 主机名选择一个别名。在这种情况下，所有密钥存储密码和别名密码都必须相同（使用 密码和 alias-password 属性配置）。不要设置 alias 属性。

环境变量： QUARKUS_TLS_KEY_STORE_SNI

布尔值

false

quarkus.tls.key-store.credentials-provider.name

从 io.quarkus.credentials.CredentialsProvider 中检索的 "credential" 存储桶(map key → passwords)的名称。如果没有设置，则不会使用凭证供应商。

凭据提供程序提供了一种方式，可以检索密钥存储密码和别名密码。请注意，只有在配置中未设置密码时，才会使用凭证供应商。

环境变量： QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_NAME

string

 

quarkus.tls.key-store.credentials-provider.bean-name

提供凭据供应商的 bean 的名称。

该名称用于选择要使用的凭据提供程序。凭据提供程序必须公开为 CDI Bean，并且 @Named 注释设置为选定的配置的名称。

如果没有设置，则使用默认凭证供应商。

环境变量： QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

string

 

quarkus.tls.key-store.credentials-provider.password-key

用于检索密钥存储密码的密钥。

如果所选凭证供应商不支持该密钥，则不会检索密码。否则，检索的值用于打开密钥存储。

环境变量： QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

string

password

quarkus.tls.key-store.credentials-provider.alias-password-key

用于检索密钥存储别名密码的密钥。

如果所选凭证供应商不包含密钥，则不会检索别名密码。否则，检索的值用于从密钥存储访问别名 私钥。

环境变量： QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_ALIAS_PASSWORD_KEY

string

alias-password

quarkus.tls.trust-store.pem.certs

可信证书路径列表(Pem 格式)。

环境变量： QUARKUS_TLS_TRUST_STORE_PEM_CERTS

路径列表

 

quarkus.tls.trust-store.p12.path

信任存储文件的路径(P12 / PFX 格式)。

环境变量： QUARKUS_TLS_TRUST_STORE_P12_PATH

path

所需的 HEKETI Required

quarkus.tls.trust-store.p12.password

信任存储的密码。如果没有设置，则必须从凭证供应商检索密码。

环境变量： QUARKUS_TLS_TRUST_STORE_P12_PASSWORD

string

 

quarkus.tls.trust-store.p12.alias

信任存储的别名。

环境变量： QUARKUS_TLS_TRUST_STORE_P12_ALIAS

string

 

quarkus.tls.trust-store.p12.provider

信任存储的供应商。

环境变量： QUARKUS_TLS_TRUST_STORE_P12_PROVIDER

string

 

quarkus.tls.trust-store.jks.path

信任存储文件的路径(JKS 格式)。

环境变量： QUARKUS_TLS_TRUST_STORE_JKS_PATH

path

所需的 HEKETI Required

quarkus.tls.trust-store.jks.password

信任存储的密码。如果没有设置，则必须从凭证供应商检索密码。

环境变量： QUARKUS_TLS_TRUST_STORE_JKS_PASSWORD

string

 

quarkus.tls.trust-store.jks.alias

信任存储中密钥的别名。

环境变量： QUARKUS_TLS_TRUST_STORE_JKS_ALIAS

string

 

quarkus.tls.trust-store.jks.provider

信任存储的供应商。

环境变量： QUARKUS_TLS_TRUST_STORE_JKS_PROVIDER

string

 

quarkus.tls.trust-store.credentials-provider.name

从 io.quarkus.credentials.CredentialsProvider 中检索的 "credential" 存储桶(map key → passwords)的名称。如果没有设置，则不会使用凭证供应商。

凭据提供程序提供了一种方式，可以检索密钥存储密码和别名密码。请注意，只有在配置中未设置密码时，才会使用凭证供应商。

环境变量： QUARKUS_TLS_TRUST_STORE_CREDENTIALS_PROVIDER_NAME

string

 

quarkus.tls.trust-store.credentials-provider.bean-name

提供凭据供应商的 bean 的名称。

该名称用于选择要使用的凭据提供程序。凭据提供程序必须公开为 CDI Bean，并且 @Named 注释设置为选定的配置的名称。

如果没有设置，则使用默认凭证供应商。

环境变量： QUARKUS_TLS_TRUST_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

string

 

quarkus.tls.trust-store.credentials-provider.password-key

用于检索信任存储密码的密钥。

如果所选凭证供应商不包含配置的密钥，则不会检索密码。否则，检索的值用于打开信任存储。

环境变量： QUARKUS_TLS_TRUST_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

string

password

quarkus.tls.cipher-suites

设置启用的密码套件的排序列表。如果未指定，则会从内置密码中选择合理的默认值。

当设置了套件时，它优先于正在使用的 SSLEngineOptions 定义的默认套件。

环境变量： QUARKUS_TLS_CIPHER_SUITES

字符串列表

 

quarkus.tls.protocols

设置启用的 TLS 协议的排序列表。

如果没有设置，则默认为 "TLSv1.3, TLSv1.2 "。支持以下协议： TLSv1、TLSv1.1、TLSv1.2、TLSv1.3。要仅启用 TLSv1.3，请将值设为 "TLSv1.3 "。

请注意，设置一个空列表，启用 TLS 无效。您必须至少有一个协议。

另外，此设置会替换默认的协议列表。

环境变量： QUARKUS_TLS_PROTOCOLS

字符串列表

TLSv1.3,TLSv1.2

quarkus.tls.handshake-timeout

TLS 握手阶段的超时时间。

如果没有设置，则默认为 10 秒。

环境变量： QUARKUS_TLS_HANDSHAKE_TIMEOUT

持续时间 5-4 Duration 格式

10S

quarkus.tls.alpn

启用应用程序协议协商(ALPN)。

应用程序-Layer 协议 Negotiation 是一个 TLS 扩展，允许在 TLS 握手期间使用客户端和服务器来协商它们将用于通信的协议。ALPN 通过允许客户端在建立 TLS 连接前向服务器指定首选应用程序协议来启用效率更高的通信。这有助于在 HTTP/2 等情形中使用多个协议，从而加快协议选择。

环境变量： QUARKUS_TLS_ALPN

布尔值

true

quarkus.tls.certificate-revocation-list

设置吊销证书列表（到文件的路径）。

证书撤销列表(CRL)是数字证书列表，已在其调度的过期日期前由发布证书颁发机构(CA)撤销。当证书被入侵时，不再需要或出于某种原因被视为无效，CA 将其添加到 CRL 中，以告知依赖方不再信任该证书。

允许两种格式： DER 和 PKCS#7 （也称为 P7B）。使用 DER 格式时，您必须传递 DER 编码的 CRL。使用 PKCS#7 格式时，您必须传递 PKCS""7 SignedData 对象，且唯一的重要字段是 crls。

环境变量： QUARKUS_TLS_CERTIFICATE_REVOCATION_LIST

路径列表

 

quarkus.tls.trust-all

如果设置为 true，服务器将信任所有证书。

这对于测试非常有用，但不应在生产环境中使用。

环境变量： QUARKUS_TLS_TRUST_ALL

布尔值

false

quarkus.tls.hostname-verification-algorithm

应检查服务器的身份时要使用的主机名验证算法。应该是 HTTPS （默认）、LDAPS 或 NONE。

如果设置为 NONE，则不会验证主机名。

如果没有设置，则配置的扩展决定要使用的默认算法。例如，对于 HTTP，它将是"HTTPS"。对于 TCP，它可以依赖于协议。不过，建议将其设置为"HTTPS"或"LDAPS"。

环境变量： QUARKUS_TLS_HOSTNAME_VERIFICATION_ALGORITHM

string

 

quarkus.tls.reload-period

配置后，服务器将重新加载证书（例如，文件系统）并触发 CertificateUpdatedEvent （如果重新加载成功）

此属性将 period 配置为重新加载证书。未设置 IF，证书不会被自动重新载入。但是，应用程序仍然可以使用 io.quarkus.tls.TlsConfiguration Serialreload （） 方法手动触发重新载入，然后手动触发 CertificateUpdatedEvent。

fired 事件用于通知应用程序证书已更新，从而继续进行证书的实际切换。

环境变量： QUARKUS_TLS_RELOAD_PERIOD

持续时间 5-4 Duration 格式

 

quarkus.tls.key-store.pem."key-certs".key

密钥文件的路径（使用 PEM 格式）。

环境变量： QUARKUS_TLS_KEY_STORE_PEM__KEY_CERTS_KEY

path

所需的 HEKETI Required

quarkus.tls.key-store.pem."key-certs".cert

证书文件的路径（使用 PEM 格式）。

环境变量： QUARKUS_TLS_KEY_STORE_PEM__KEY_CERTS_CERT

path

所需的 HEKETI Required

quarkus.tls."tls-bucket-name".key-store.pem."key-certs".key

密钥文件的路径（使用 PEM 格式）。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_PEM__KEY_CERTS_KEY

path

所需的 HEKETI Required

quarkus.tls."tls-bucket-name".key-store.pem."key-certs".cert

证书文件的路径（使用 PEM 格式）。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_PEM__KEY_CERTS_CERT

path

所需的 HEKETI Required

quarkus.tls."tls-bucket-name".key-store.pem.order

密钥/证书文件的顺序，取决于 keyCerts 映射中的名称。

默认情况下，Quarkus 使用字典顺序对键进行排序。此属性允许您指定密钥/证书文件的顺序。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_PEM_ORDER

字符串列表

 

quarkus.tls."tls-bucket-name".key-store.p12.path

密钥存储文件的路径(P12 / PFX 格式)。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_PATH

path

所需的 HEKETI Required

quarkus.tls."tls-bucket-name".key-store.p12.password

密钥存储的密码。如果没有设置，则必须从凭证提供程序检索密码。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_PASSWORD

string

 

quarkus.tls."tls-bucket-name".key-store.p12.alias

密钥存储中私钥和证书的别名。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_ALIAS

string

 

quarkus.tls."tls-bucket-name".key-store.p12.alias-password

密钥存储中别名的密码。如果没有设置，则从凭证提供程序检索密码。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_ALIAS_PASSWORD

string

 

quarkus.tls."tls-bucket-name".key-store.p12.provider

密钥存储的提供商。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_PROVIDER

string

 

quarkus.tls."tls-bucket-name".key-store.jks.path

密钥存储文件的路径(JKS 格式)。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_PATH

path

所需的 HEKETI Required

quarkus.tls."tls-bucket-name".key-store.jks.password

密钥存储的密码。如果没有设置，则必须从凭证提供程序检索密码。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_PASSWORD

string

 

quarkus.tls."tls-bucket-name".key-store.jks.alias

密钥存储中私钥和证书的别名。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_ALIAS

string

 

quarkus.tls."tls-bucket-name".key-store.jks.alias-password

密钥存储中别名的密码。如果没有设置，则可从凭据提供程序检索密码。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_ALIAS_PASSWORD

string

 

quarkus.tls."tls-bucket-name".key-store.jks.provider

密钥存储的提供商。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_PROVIDER

string

 

quarkus.tls."tls-bucket-name".key-store.sni

启用服务器名称调用(SNI)。

服务器名称 Indication (SNI)是一个 TLS 扩展，它允许客户端指定在 TLS 握手期间尝试连接到的主机名。这可让服务器在单个 IP 地址上为多个域提供不同的 SSL 证书，为虚拟主机场景提供安全通信。

启用此设置后，客户端在 TLS 握手期间指示服务器名称，允许服务器选择正确的证书。

使用 PEM 文件配置密钥存储时，必须指定多个 CRT/Key。使用 JKS 或 P12 文件配置密钥存储时，它会根据 SNI 主机名选择一个别名。在这种情况下，所有密钥存储密码和别名密码都必须相同（使用 密码和 alias-password 属性配置）。不要设置 alias 属性。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_SNI

布尔值

false

quarkus.tls."tls-bucket-name".key-store.credentials-provider.name

从 io.quarkus.credentials.CredentialsProvider 中检索的 "credential" 存储桶(map key → passwords)的名称。如果没有设置，则不会使用凭证供应商。

凭据提供程序提供了一种方式，可以检索密钥存储密码和别名密码。请注意，只有在配置中未设置密码时，才会使用凭证供应商。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_NAME

string

 

quarkus.tls."tls-bucket-name".key-store.credentials-provider.bean-name

提供凭据供应商的 bean 的名称。

该名称用于选择要使用的凭据提供程序。凭据提供程序必须公开为 CDI Bean，并且 @Named 注释设置为选定的配置的名称。

如果没有设置，则使用默认凭证供应商。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

string

 

quarkus.tls."tls-bucket-name".key-store.credentials-provider.password-key

用于检索密钥存储密码的密钥。

如果所选凭证供应商不支持该密钥，则不会检索密码。否则，检索的值用于打开密钥存储。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

string

password

quarkus.tls."tls-bucket-name".key-store.credentials-provider.alias-password-key

用于检索密钥存储别名密码的密钥。

如果所选凭证供应商不包含密钥，则不会检索别名密码。否则，检索的值用于从密钥存储访问别名 私钥。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_ALIAS_PASSWORD_KEY

string

alias-password

quarkus.tls."tls-bucket-name".trust-store.pem.certs

可信证书路径列表(Pem 格式)。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_PEM_CERTS

路径列表

 

quarkus.tls."tls-bucket-name".trust-store.p12.path

信任存储文件的路径(P12 / PFX 格式)。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_PATH

path

所需的 HEKETI Required

quarkus.tls."tls-bucket-name".trust-store.p12.password

信任存储的密码。如果没有设置，则必须从凭证供应商检索密码。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_PASSWORD

string

 

quarkus.tls."tls-bucket-name".trust-store.p12.alias

信任存储的别名。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_ALIAS

string

 

quarkus.tls."tls-bucket-name".trust-store.p12.provider

信任存储的供应商。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_PROVIDER

string

 

quarkus.tls."tls-bucket-name".trust-store.jks.path

信任存储文件的路径(JKS 格式)。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_PATH

path

所需的 HEKETI Required

quarkus.tls."tls-bucket-name".trust-store.jks.password

信任存储的密码。如果没有设置，则必须从凭证供应商检索密码。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_PASSWORD

string

 

quarkus.tls."tls-bucket-name".trust-store.jks.alias

信任存储中密钥的别名。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_ALIAS

string

 

quarkus.tls."tls-bucket-name".trust-store.jks.provider

信任存储的供应商。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_PROVIDER

string

 

quarkus.tls."tls-bucket-name".trust-store.credentials-provider.name

从 io.quarkus.credentials.CredentialsProvider 中检索的 "credential" 存储桶(map key → passwords)的名称。如果没有设置，则不会使用凭证供应商。

凭据提供程序提供了一种方式，可以检索密钥存储密码和别名密码。请注意，只有在配置中未设置密码时，才会使用凭证供应商。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_CREDENTIALS_PROVIDER_NAME

string

 

quarkus.tls."tls-bucket-name".trust-store.credentials-provider.bean-name

提供凭据供应商的 bean 的名称。

该名称用于选择要使用的凭据提供程序。凭据提供程序必须公开为 CDI Bean，并且 @Named 注释设置为选定的配置的名称。

如果没有设置，则使用默认凭证供应商。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

string

 

quarkus.tls."tls-bucket-name".trust-store.credentials-provider.password-key

用于检索信任存储密码的密钥。

如果所选凭证供应商不包含配置的密钥，则不会检索密码。否则，检索的值用于打开信任存储。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

string

password

quarkus.tls."tls-bucket-name".cipher-suites

设置启用的密码套件的排序列表。如果未指定，则会从内置密码中选择合理的默认值。

当设置了套件时，它优先于正在使用的 SSLEngineOptions 定义的默认套件。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__CIPHER_SUITES

字符串列表

 

quarkus.tls."tls-bucket-name".protocols

设置启用的 TLS 协议的排序列表。

如果没有设置，则默认为 "TLSv1.3, TLSv1.2 "。支持以下协议： TLSv1、TLSv1.1、TLSv1.2、TLSv1.3。要仅启用 TLSv1.3，请将值设为 "TLSv1.3 "。

请注意，设置一个空列表，启用 TLS 无效。您必须至少有一个协议。

另外，此设置会替换默认的协议列表。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME_PROTOCOLS

字符串列表

TLSv1.3,TLSv1.2

quarkus.tls."tls-bucket-name".handshake-timeout

TLS 握手阶段的超时时间。

如果没有设置，则默认为 10 秒。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__HANDSHAKE_TIMEOUT

持续时间 5-4 Duration 格式

10S

quarkus.tls."tls-bucket-name".alpn

启用应用程序协议协商(ALPN)。

应用程序-Layer 协议 Negotiation 是一个 TLS 扩展，允许在 TLS 握手期间使用客户端和服务器来协商它们将用于通信的协议。ALPN 通过允许客户端在建立 TLS 连接前向服务器指定首选应用程序协议来启用效率更高的通信。这有助于在 HTTP/2 等情形中使用多个协议，从而加快协议选择。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME_ALPN

布尔值

true

quarkus.tls."tls-bucket-name".certificate-revocation-list

设置吊销证书列表（到文件的路径）。

证书撤销列表(CRL)是数字证书列表，已在其调度的过期日期前由发布证书颁发机构(CA)撤销。当证书被入侵时，不再需要或出于某种原因被视为无效，CA 将其添加到 CRL 中，以告知依赖方不再信任该证书。

允许两种格式： DER 和 PKCS#7 （也称为 P7B）。使用 DER 格式时，您必须传递 DER 编码的 CRL。使用 PKCS#7 格式时，您必须传递 PKCS""7 SignedData 对象，且唯一的重要字段是 crls。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__CERTIFICATE_REVOCATION_LIST

路径列表

 

quarkus.tls."tls-bucket-name".trust-all

如果设置为 true，服务器将信任所有证书。

这对于测试非常有用，但不应在生产环境中使用。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_ALL

布尔值

false

quarkus.tls."tls-bucket-name".hostname-verification-algorithm

应检查服务器的身份时要使用的主机名验证算法。应该是 HTTPS （默认）、LDAPS 或 NONE。

如果设置为 NONE，则不会验证主机名。

如果没有设置，则配置的扩展决定要使用的默认算法。例如，对于 HTTP，它将是"HTTPS"。对于 TCP，它可以依赖于协议。不过，建议将其设置为"HTTPS"或"LDAPS"。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME__HOSTNAME_VERIFICATION_ALGORITHM

string

 

quarkus.tls."tls-bucket-name".reload-period

配置后，服务器将重新加载证书（例如，文件系统）并触发 CertificateUpdatedEvent （如果重新加载成功）

此属性将 period 配置为重新加载证书。未设置 IF，证书不会被自动重新载入。但是，应用程序仍然可以使用 io.quarkus.tls.TlsConfiguration Serialreload （） 方法手动触发重新载入，然后手动触发 CertificateUpdatedEvent。

fired 事件用于通知应用程序证书已更新，从而继续进行证书的实际切换。

环境变量： QUARKUS_TLS__TLS_BUCKET_NAME_RELOAD_PERIOD

持续时间 5-4 Duration 格式

 
关于 Duration 格式

要写入持续时间值，请使用标准 java.time.Duration 格式。如需更多信息，请参阅 Duration#parse （）Java API 文档。

您还可以使用简化的格式，从数字开始：

  • 如果值只是一个数字，它代表时间（以秒为单位）。
  • 如果值为数字，后跟 ms，代表时间（毫秒）。

在其他情况下，简化的格式被转换为 java.time.Duration 格式以进行解析：

  • 如果该值是一个数字，后跟 h、m 或 s，则前缀为 PT。
  • 如果值为数字，后跟 d，则会以 P 为前缀。

1.4. registry API
复制链接

虽然扩展自动使用 TLS registry，但您也可以通过 registry API 以编程方式访问 TLS 配置。

要访问 TLS 配置，请注入 TlsConfigurationRegistry bean。您可以通过调用 get ("<NAME>")或使用 getDefault （） 来检索命名的 TLS 配置。 

 @Inject
 TlsConfigurationRegistry certificates;
// ...
TlsConfiguration def = certificates.getDefault().orElseThrow();
TlsConfiguration named = certificates.get("name").orElseThrow();
//...
Copy to Clipboard Toggle word wrap

TlsConfiguration 对象包含密钥存储、信任存储、密码套件、协议和其他属性。它还提供了一种从配置创建 SSLContext 的方法。

您还可以使用 TlsConfiguration 对象来配置 Vert.x 客户端或服务器，如 KeyCertOptions、TrustOptions 等。

1.5. 从扩展注册证书
复制链接

本节仅适用于扩展开发人员。扩展可以在 TLS registry 中注册证书。当扩展需要向应用程序提供证书或提供不同的格式时，这非常有用。

要使用扩展在 TLS 注册表中注册证书，处理器 扩展必须生成一个由名称和 CertificateSupplier 组成的 TlsCertificateBuildItem。 

TlsCertificateBuildItem item = new TlsCertificateBuildItem("named",
    new MyCertificateSupplier());
Copy to Clipboard Toggle word wrap

证书供应商是一个通常使用记录器方法检索的运行时对象。

证书供应商示例：

public class MyCertificateSupplier implements Supplier<TlsConfiguration> {

        @Override
        public TlsConfiguration get() {
            try {
                KeyStore ks = KeyStore.getInstance("PKCS12");
                ks.load(getClass().getResourceAsStream("target/certs/test-registration-keystore.p12"),
                        "password".toCharArray());
                KeyStore ts = KeyStore.getInstance("PKCS12");
                ts.load(getClass().getResourceAsStream("target/certs/test-registration-truststore.p12"),
                        "password".toCharArray());
                return new BaseTlsConfiguration() {
                    @Override
                    public KeyStore getKeyStore() {
                        return ks;
                    }

                    @Override
                    public KeyStore getTrustStore() {
                        return ts;
                    }
                };
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        }
    }
Copy to Clipboard Toggle word wrap

1.6. 启动检查
复制链接

当使用 TLS 扩展的应用程序启动时，TLS registry 会执行几个检查来确保配置正确：

  • keystores 和 truststores 可以访问。
  • 别名可用，可在密钥存储和信任存储中访问。
  • 证书有效。
  • 密码套件和协议有效。
  • 证书撤销列表(CRL)有效。

如果这些检查失败，应用程序将不会启动。

1.7. 重新载入证书
复制链接

从 TLSConfigurationRegistry 获取的 TlsConfiguration 包含重新加载证书的机制。reload 方法刷新密钥存储和信任存储，通常通过从文件系统中重新加载它们。

注意

reload 操作不是自动的，必须手动触发。此外，TlsConfiguration 实施必须支持重新加载（这是配置的证书的情况）。

reload 方法返回一个 布尔值，指示重新加载是否成功。值 true 表示 reload 操作成功，而不一定会更新证书。

在重新加载 TlsConfiguration 后，使用此配置的服务器和客户端可能需要执行特定的操作来应用新证书。

通知客户端和服务器有关证书重新加载的建议方法是触发 CDI 事件，类型为 io.quarkus.tls.CertificateUpdatedEvent。为此，请注入此类型的 CDI 事件，并在重新加载发生时触发它。

  1. 手动触发重新载入并触发 CertificateUpdatedEvent ： 
// in the class that performs the reload
@Inject
Event<CertificateUpdatedEvent> event;
@Inject
TlsConfigurationRegistry registry;

public void reload() {
    TlsConfiguration config = registry.get("name").orElseThrow();
    if (config.reload()) {
        event.fire(new CertificateUpdatedEvent("name", config));
    }
}

// In the server or client code
public void onReload(@Observes CertificateUpdatedEvent reload) {
    if ("name".equals(event.getName())) {
        server.updateSSLOptions(reload.tlsConfiguration().getSSLOptions());
        // Or update the SSLContext.
    }

}
Copy to Clipboard Toggle word wrap

1.7.1. 定期重新载入
复制链接

TLS 注册表包含一个内置机制，用于定期检查文件系统的更改和重新加载证书。reload-period 属性指定重新载入证书的时间间隔，并在每次重新载入证书时发出 CertificateUpdatedEvent 的时间间隔。

  1. 配置定期证书重新载入： 

    quarkus.tls.reload-period=1h
quarkus.tls.key-store.pem.0.cert=tls.crt
quarkus.tls.key-store.pem.0.key=tls.key
    Copy to Clipboard Toggle word wrap

  2. 对于每个命名的配置，您可以设置特定的重新加载周期： 

    quarkus.tls.http.reload-period=30min
quarkus.tls.http.key-store.pem.0.cert=tls.crt
quarkus.tls.http.key-store.pem.0.key=tls.key
    Copy to Clipboard Toggle word wrap
重要

受影响的服务器和客户端可能需要侦听 CertificateUpdatedEvent 以应用新证书。这会自动为 Quarkus HTTP 服务器完成，包括管理界面（如果已启用）。

1.8. 使用 OpenShift serving 证书
复制链接

在 OpenShift 中运行应用时，您可以使用 OpenShift 服务证书 自动生成和更新 TLS 证书。Quarkus TLS registry 可以使用这些证书和证书颁发机构(CA)文件来处理 HTTPS 流量并安全地验证证书。

1.8.1. 获取证书
复制链接

要让 OpenShift 生成服务证书，请注解现有的 Service 对象。生成的证书将存储在 secret 中，然后可以挂载到 pod 中。

以下片段使用带有注解示例 Service 对象来生成 TLS 证书。

  1. 查看 Service 对象的配置： 

    apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/name: ...
    app.kubernetes.io/version: ...
    app.kubernetes.io/managed-by: quarkus
  name: hero-service
spec:
  ports:
    - name: http
      port: 443
      protocol: TCP
      targetPort: 8443
  selector:
    app.kubernetes.io/name: ...
    app.kubernetes.io/version: ...
  type: ClusterIP
    Copy to Clipboard Toggle word wrap

  2. 要生成证书，请在已创建的 OpenShift 服务 中添加其注解： 

    oc annotate service hero-service \
     service.beta.openshift.io/serving-cert-secret-name=my-tls-secret
    Copy to Clipboard Toggle word wrap

    注解 service.beta.openshift.io/serving-cert-secret-name 指示 OpenShift 生成证书并将其存储在名为 my-tls-secret 的 secret 中。

  3. 通过更新部署配置，将 secret 挂载为 pod 中的卷 ： 

    apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/name: ...
    app.kubernetes.io/version: ...
  name: my-service
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: ...
      app.kubernetes.io/version: ...
  template:
    metadata:
      labels:
        app.kubernetes.io/name: ...
        app.kubernetes.io/version: ...
    spec:
      volumes:
        - name: my-tls-secret
    1 
    
          secret:
            secretName: my-tls-secret
      containers:
        - env:
            - name: KUBERNETES_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: QUARKUS_TLS_KEY_STORE_PEM_ACME_CERT
    2 
    
              value: /etc/tls/tls.crt
            - name: QUARKUS_TLS_KEY_STORE_PEM_ACME_KEY
              value: /etc/tls/tls.key
          image: ...
          imagePullPolicy: Always
          name: my-service
          volumeMounts:
    3 
    
            - name: my-tls-secret
              mountPath: /etc/tls
              readOnly: true
          ports:
            - containerPort: 8443
    4 
    
              name: https
              protocol: TCP
    Copy to Clipboard Toggle word wrap
    1
    定义要挂载 secret 的卷。使用与上面声明的 secret 的名称相同。
    2
    使用到证书和私钥的路径设置密钥存储。这可以通过使用环境变量或配置文件来配置。本例使用环境变量。OpenShift serving 证书总是创建 tls.crt 和 tls.key 文件。
    3
    将机密挂载到容器中。确保路径与配置中使用的路径匹配（这里的 /etc/tls）。
    4
    配置端口以提供 HTTPS。
  4. 部署应用以使用 OpenShift 生成的证书。这将通过 HTTPS 提供该服务。
注意

通过设置 quarkus.tls.key-store.pem.acme.cert 和 quarkus.tls.key-store.pem.acme.key 变量或其环境变量变体，TLS registry 将使用 secret 中的证书和私钥。

这会配置 Quarkus HTTP 服务器的默认密钥存储，它允许服务器使用该证书。有关在命名配置中使用此证书的详情，请参考 TLS 配置。

1.8.2. 信任证书颁发机构(CA)
复制链接

先决条件

现在，您的服务使用 OpenShift 发布的证书，请将您的客户端应用程序配置为信任此证书。为此，请创建一个包含 CA 证书的 ConfigMap，然后将 pod 配置为挂载它。以下步骤使用 Quarkus REST 客户端作为示例，但相同的方法适用于任何客户端。

  1. 首先定义一个 空 ConfigMap，它将填充 CA 证书： 

    apiVersion: v1
kind: ConfigMap
metadata:
  name: client-tls-config
  annotations:
    service.beta.openshift.io/inject-cabundle: "true"
    Copy to Clipboard Toggle word wrap

    service.beta.openshift.io/inject-cabundle 注解用于将 CA 证书注入 ConfigMap。请注意，ConfigMap 最初没有数据 - 它为空。在处理过程中，OpenShift 会将 CA 证书注入 service-ca.crt 文件中的 ConfigMap 中。

  2. 通过添加卷并在部署配置中挂载 ConfigMap 来挂载 ConfigMap ： 

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service-client
  labels:
    app.kubernetes.io/name: ...
    app.kubernetes.io/version: ...
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: ...
      app.kubernetes.io/version: ...
  template:
    metadata:
      labels:
        app.kubernetes.io/name: ...
        app.kubernetes.io/version: ...
    spec:
      containers:
        - name: my-service-client
          image: ...
          ports:
            - name: http
              containerPort: 8080
              protocol: TCP
          volumeMounts:
    1 
    
            - name: my-client-volume
              mountPath: /deployments/tls
      volumes:
    2 
    
        - name: my-client-volume
          configMap:
            name: client-tls-config
    Copy to Clipboard Toggle word wrap
    1
    在容器中挂载 ConfigMap。确保路径与配置中使用的路径匹配（在本例中为 /deployments/tls）。
    2
    定义卷挂载 ConfigMap 并引用接收 CA 证书的 ConfigMap。

  3. 配置 REST 客户端以使用此 CA 证书。

    考虑以下 REST 客户端接口： 

    package org.acme;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;

@RegisterRestClient(baseUri = "https://hero-service.cescoffi-dev.svc", configKey = "hero")
    1 
    
public interface HeroClient {

    record Hero (Long id, String name, String otherName, int level, String picture, String powers) {
    }

    @GET
    @Path("/api/heroes/random")
    Hero getRandomHero();

}
    Copy to Clipboard Toggle word wrap
    1
    配置基础 URI 和配置密钥。名称的格式必须是 < service-name>.<namespace>.svc。否则，证书将不被信任。确保也配置了 configKey。

  4. 将 REST 客户端配置为信任 OpenShift 生成的 CA 证书： 

    quarkus.rest-client.hero.tls-configuration-name=my-service-tls
    1 
    
quarkus.tls.my-service-tls.trust-store.pem.certs=/deployments/tls/service-ca.crt
    2
    Copy to Clipboard Toggle word wrap
    1
    使用名为 my-service-tls 的 TLS 配置配置 hero REST 客户端。
    2
    设置 my-service-tls TLS 配置，特别是使用 CA 证书的信任存储。确保路径与 Kubernetes Deployment 配置中使用的路径匹配。该文件始终命名为 service-ca.crt。

1.8.3. 证书续订
复制链接

OpenShift 自动续订它生成的服务证书。当证书被续订时，会使用新证书和私钥来更新 secret。

要确保应用程序使用新证书，您可以使用 Quarkus TLS registry 的定期重新载入功能。

通过设置 reload-period 属性，TLS registry 会定期检查密钥存储和信任存储的更改，并在需要时重新载入它们： 

quarkus.tls.reload-period=24h
Copy to Clipboard Toggle word wrap
  1. （可选）实施自定义机制，以在更新 secret 时重新加载证书。如需更多信息，请参阅 重新加载证书。

1.9. Quarkus CLI 命令和开发证书颁发机构
复制链接

TLS registry 提供 Quarkus CLI 命令来生成开发证书颁发机构(CA)和可信证书。这可避免在本地使用自签名证书。

以下片段显示了 quarkus tls 命令的描述，它包含两个子命令： 

> quarkus tls
Install and Manage TLS development certificates
Usage: tls [COMMAND]
Commands:
  generate-quarkus-ca   Generate Quarkus Dev CA certificate and private key.
1 

  generate-certificate  Generate a TLS certificate with the Quarkus Dev CA if
                        available.
2
Copy to Clipboard Toggle word wrap
1
这对本地开发很有用，因为它允许 Quarkus 作为自己的证书颁发机构（可用于为其他证书签名）。
2
这在为应用和外部服务或客户端在开发过程中安全通信而创建证书时很有用。

在大多数情况下，您要生成 Quarkus Development CA 一次，然后生成由此 CA 签名的证书。Quarkus Development CA 是一个证书颁发机构，可用于在本地签名证书。它仅对开发目的有效，且仅在本地计算机上信任。生成的 CA 位于 $HOME/.quarkus/quarkus-dev-root-ca.pem 中，并安装到系统信任存储中。

1.9.1. 了解自签名与 CA 签名证书
复制链接

使用 TLS 进行开发时，您可以使用两种类型的证书：

  • 自签名证书 ：证书 由使用它的同一实体签名。默认情况下不信任它。当证书颁发机构(CA)不可用或您想要简单的设置时，通常使用此类证书。它不适用于生产环境，应该只用于开发。
  • CA 签名证书 ：证书 由证书 CA （可信实体）签名。此证书默认是可信的，是生产环境的标准选择。

虽然您可以使用自签名证书进行本地开发，但存在限制。浏览器和工具 curl、wget 和 httpie 通常不信任自签名证书，需要在操作系统中手动导入 CA。

要避免这个问题，您可以使用开发 CA 为证书签名并在系统信任存储中安装 CA。这样可确保系统信任 CA 签名的证书。

Quarkus 简化了开发 CA 和此 CA 签名的证书的生成。

1.9.2. 生成开发 CA
复制链接

开发 CA 是一个证书颁发机构，可用于在本地签名证书。请注意，生成的 CA 仅适用于开发目的，只能在本地机器上信任。

生成开发 CA： 

quarkus tls generate-quarkus-ca --install \
1 

     --renew \
2 

     --truststore
3
Copy to Clipboard Toggle word wrap
1
--install 会在系统信任存储中安装 CA。支持 Windows、Mac 和 Linux (Fedora 和 Ubuntu)。但是，根据您的浏览器，您可能需要手动导入生成的 CA。如需更多信息，请参阅浏览器的文档。生成的 CA 位于 $HOME/.quarkus/quarkus-dev-root-ca.pem 中。
2
-- 续订 CA （如果已存在）。使用此选项时，会更改私钥，因此您需要重新生成 CA 签名的证书。如果 CA 过期，它将自动更新，而无需-- renew 选项。
3
--truststore 还会生成包含 CA 证书的 PKCS12 信任存储。
警告

安装证书时，您的系统可能会要求您的密码在系统信任存储中安装证书，或者要求在 Windows 上的对话框中进行确认。

重要

在 Windows 上，以管理员身份从提升的终端运行，以在系统信任存储中安装 CA。

1.9.3. 生成可信（签名）证书
复制链接

先决条件

  • 生成开发 CA

    1. 安装 Quarkus Development CA 后，生成可信证书。此证书由 Quarkus Development CA 签名，并被您的系统信任。 

      quarkus tls generate-certificate --name my-cert
      Copy to Clipboard Toggle word wrap

      此命令生成由 Quarkus Development CA 签名的证书，如果正确安装或导入，您的系统将会信任。

      证书存储在 ./.certs/ 中。生成两个文件：

  • $name-keystore.p12 ：包含私钥和证书。它受密码保护。

  • $NAME-truststore.p12 ：包含 CA 证书，您可以将其用作信任存储，例如用于测试。

    其它选项可用： 

    Usage: tls generate-certificate [-hrV] [-c=<cn>] [-d=<directory>]
       -n=<name> [-p=<password>]
Generate a TLS certificate with the Quarkus Dev CA if available.
  -c, --cn=<cn>       The common name of the certificate. Default is 'localhost'
  -d, --directory=<directory>
                      The directory in which the certificates will be created.
                        Default is `.certs`
  -n, --name=<name>   Name of the certificate. It will be used as file name and
                        alias in the keystore
  -p, --password=<password>
                      The password of the keystore. Default is 'password'
  -r, --renew         Whether existing certificates will need to be replaced
    Copy to Clipboard Toggle word wrap

    生成证书时也会生成 .env 文件，使 Quarkus dev 模式了解这些证书。

    1. 以 dev 模式运行应用程序以使用这些证书： 

      ./mvnw quarkus:dev
...
INFO  [io.quarkus] (Quarkus Main Thread) demo 1.0.0-SNAPSHOT on JVM (powered by Quarkus 999-SNAPSHOT) started in 1.286s. Listening on: http://localhost:8080 and https://localhost:8443
      Copy to Clipboard Toggle word wrap

    2. 使用 HTTPS: https://localhost:8443/q/dev 或发出 curl 请求来打开 Dev UI： 

      curl https://localhost:8443/hello
Hello from Quarkus REST%
      Copy to Clipboard Toggle word wrap
      重要

      如果没有安装 Quarkus Development CA，quarkus 会生成自签名证书。

1.9.4. 生成自签名证书
复制链接

即使安装了 Quarkus Development CA，也可以生成自签名证书： 

quarkus tls generate-certificate --name my-cert --self-signed
Copy to Clipboard Toggle word wrap

这会生成 Quarkus 开发 CA 不签名的自签名证书。

1.9.5. 卸载 Quarkus 开发 CA
复制链接

从您的系统卸载 Quarkus 开发 CA 取决于您的操作系统。

1.9.5.1. 删除 Windows 上的 CA 证书
复制链接

  1. 使用带有管理员权限的 Powershell 终端列出 Windows 上的 CA 证书： 

    # First, we need to identify the serial number of the CA certificate
> certutil -store -user Root
root "Trusted Root Certification Authorities"
================ Certificate 0 ================
Serial Number: 019036d564c8
Issuer: O=Quarkus, CN=quarkus-dev-root-ca # <-That's the CA, copy the Serial Number (the line above)
NotBefore: 6/19/2024 11:07 AM
NotAfter: 6/20/2025 11:07 AM
Subject: C=Cloud, S=world, L=home, OU=Quarkus Dev, O=Quarkus Dev, CN=quarkus-dev-root-ca
Signature matches Public Key
Non-root Certificate uses same Public Key as Issuer
Cert Hash(sha1): 3679bc95b613a2112a3d3256fe8321b6eccce720
No key provider information
Cannot find the certificate and private key for decryption.
CertUtil: -store command completed successfully.
    Copy to Clipboard Toggle word wrap

  2. 删除存储的 CA 证书，并将 $Serial_Number 替换为 CA 证书的序列号： 

    > certutil -delstore -user -v Root $Serial_Number
    Copy to Clipboard Toggle word wrap
1.9.5.2. 删除 Linux 中的 CA 证书
复制链接

  • 对于 Fedora： 

    sudo rm /etc/pki/ca-trust/source/anchors/quarkus-dev-root-ca.pem
sudo update-ca-trust
    Copy to Clipboard Toggle word wrap

  • 在 Ubuntu 中： 

    sudo rm /usr/local/share/ca-certificates/quarkus-dev-root-ca.pem
sudo update-ca-certificates
    Copy to Clipboard Toggle word wrap
1.9.5.3. 删除 Mac 上的 CA 证书
复制链接

  • 在 Mac 上： 

    sudo security -v remove-trusted-cert -d /Users/clement/.quarkus/quarkus-dev-root-ca.pem
    Copy to Clipboard Toggle word wrap

法律通告
复制链接

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat