TLS registry reference

TLS 注册表是 Quarkus 扩展，负责集中化应用程序的 TLS 配置。它允许在单个位置定义 TLS 配置，并从应用程序中的多个位置引用该配置。

The TLS registry is a Quarkus extension centralizing the TLS configuration for the application. It allows to define the TLS configuration in a single place and to reference it from multiple places in the application.

只要您使用兼容的扩展，TLS 扩展应自动添加到您的项目中。例如，如果您的应用程序使用 Quarkus REST、gRPC 或响应式路由，TLS 注册表会自动添加到您的项目中。

The TLS extension should be automatically added to your project as soon as you use a compatible extension. For example, if your application uses Quarkus REST, gRPC or reactive routes, the TLS registry is automatically added to your project.

Using TLS registry

要配置 TLS 连接，特别是密钥库和信任库，您可以使用 quarkus.tls.* 属性。

To configure a TLS connection, and more specifically the key stores and trust stores, you use the quarkus.tls.* properties.

直接位于 quarkus.tls 下的配置是默认配置，该配置将被应用程序中的所有 TLS 连接使用。但是，您还可以通过使用 quarkus.tls.<name>.* 属性为特定连接设置特定配置。

Configuration directly under quarkus.tls is the default configuration that will be used by all the TLS connections in the application. However, you can also have specific configurations for specific connections by using the quarkus.tls.<name>.* properties.

Configure the HTTP server to use https://

若要配置 HTTP 服务器以使用 HTTPS，可以使用以下配置：

To configure the HTTP server to use HTTPS, you can use the following configuration:

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

因此，你使用 p12（PKCS12）密钥库，请使用以下配置：

So you a p12 (PKCS12) key store, use the following configuration:

quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret
quarkus.http.insecure-requests=disabled # Reject HTTP requests

你可以使用命名配置，而不是默认配置：

Instead of the default configuration, you can use a named configuration:

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

Configure a client to use https://

作为说明客户端配置的示例，我们将使用 gRPC 客户端：

As an example to illustrate client configuration, we will use a gRPC client:

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

Configuring mTLS

要配置 mTLS，您需要同时配置服务器和客户端。两者都将收到密钥库和信任库：

To configure mTLS, you need to configure both the server and the client. Both will receive a key store and a trust store:

  • the server key store contains the server certificate and private key

  • the client key store contains the client certificate and private key

  • the server trust store contains the client certificate (to authenticate the client)

  • the client trust store contains the server certificate (to authenticate the server)

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

Referencing a TLS configuration

使用 quarkus.tls.<name> 配置了 named 配置后，您需要引用它。这是通过使用 tls-configuration-name 属性完成的：

Once you have configured a named configuration using quarkus.tls.<name>, you need to reference it. This is done using the tls-configuration-name property:

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 # Reference the named configuration

Configuring TLS

配置 TLS 主要涉及密钥库和信任库。此配置取决于格式 (pem、p12、jks…​)。还有一些其他重要的属性。本节详细介绍了可用于配置 TLS 的各种属性。

Configuring TLS is mainly about key stores and trust stores. The configuration depends on the format (pem, p12, jks…​). There are other important properties too. This section details the various properties you can use to configure TLS.

Key stores

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

Key stores are used to store the private key and the certificate. They are mainly used on the server-side, but can also be used on the client-side when mTLS is used.

PEM key stores

PEM 密钥库由一对对的两个文件列表组成：证书和私钥。证书文件是 .crt 或 .pem 文件，而私钥文件经常是 .key 文件。

PEM key stores are composed of a list of pair of two files: the certificate and the private key. The certificate file is a .crt or .pem file, and the private key file is often a .key file.

要配置一个 PEM 密钥库，请使用以下属性：

To configure a PEM key store, use the following properties:

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

通常，你只需要一对证书和私钥。该证书可能包含多个证书（一个链），但应该有一个私钥。

In general, you will only need one pair of certificate and private key. The certificate may contain multiple certificates (a chain), but there should be one private key.

当配置多对证书和私钥时，选择是使用 SNI (服务器名称指示) 完成的。客户端会发送其希望连接到的服务器名称，而服务器会选择合适的证书和私钥对。确保在客户端和服务器上均已启用 SNI，以使用此功能。

When multiple pairs are configured, the selection is done using SNI (Server Name Indication). The client will send the server name it wants to connect to, and the server will select the appropriate pair of certificate and private key. Make sure SNI is enabled on both the client and server to use this feature.

在配置多个密钥/证书对时，顺序遵循名称的词典顺序（在先前的代码段中是 a`和 `b）。因此，第一对是词典顺序最低的一对。你可以使用 quarkus.tls.key-store.pem.order`属性定义该顺序，例如： `quarkus.tls.key-store.pem.order=b,c,a。在使用 SNI 时这一点很重要，因为第一对是默认对。

When configuring multiple key/cert pairs, the order is following the lexicographical order of the name (a and b in the previous snippet). So, the first pair is the one with the lowest lexicographical order. You can define the order by using the quarkus.tls.key-store.pem.order property, for example: quarkus.tls.key-store.pem.order=b,c,a. This is important when using SNI, as the first pair is the default one.

PKCS12 key stores

PKCS12 密钥库是一个包含证书和私钥的单个文件。要配置一个 PKCS12 密钥库，请使用以下属性：

PKCS12 key stores are a single file containing the certificate and the private key. To configure a PKCS12 key store, use the following properties:

quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret

`.p12`文件是受密码保护的，因此你需要提供密码以打开该密钥库。此外，该文件可以包含多个证书和私钥。在这种情况下，你可以：

.p12 files are password-protected, so you need to provide the password to open the key store. Also, they can include more than one certificate and private key. In this case, you can:

  • either provide the alias of the certificate and private key you want to use

  • or use SNI to select the appropriate certificate and private key (all keys must use the same password)

要配置该别名，请使用以下属性：

To configure the alias, use the following properties:

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

JKS key stores

JKS 密钥库是一个包含证书和私钥的单个文件。请注意，应该避免使用 JKS 格式，因为它比 PKCS12 的安全性低。要配置一个 JKS 密钥库，请使用以下属性：

JKS key stores are a single file containing the certificate and the private key. Note that the JKS format should be avoided as it is less secure than PKCS12. To configure a JKS key store, use the following properties:

quarkus.tls.key-store.jks.path=server-keystore.jks
quarkus.tls.key-store.jks.password=secret

`.jks`文件是受密码保护的，因此你需要提供密码以打开该密钥库。此外，该文件可以包含多个证书和私钥。在这种情况下，你可以：

.jks files are password-protected, so you need to provide the password to open the key store. Also, they can include more than one certificate and private key. In this case, you can:

  • either provide the alias of the certificate and private key you want to use

  • or use SNI to select the appropriate certificate and private key (all keys must use the same password)

要配置该别名，请使用以下属性：

To configure the alias, use the following properties:

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

SNI

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

Server Name Indication (SNI) is a TLS extension that allows a client to specify the hostname it is attempting to connect to during the TLS handshake. It enables a server to present different TLS certificates for multiple domains on a single IP address, facilitating secure communication for virtual hosting scenarios.

要启用 SNI，请使用以下属性：

To enable SNI, use the following property:

quarkus.tls.key-store.sni=true # Disabled by default

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

With this setting enabled, the client indicate the server name during the TLS handshake, allowing the server to select the right certificate:

  • When configuring the keystore with PEM files, multiple CRT/Key must be given.

  • When configuring the keystore with a JKS or a P12 file, it selects one alias based on the SNI hostname. In this case, all the keystore password and alias password must be the same. Do not set the alias property in this case.

Credential providers

与其在配置中传递密钥库密码和别名密码，你可以使用凭证提供程序。

Instead of passing the key store password and alias password in the configuration, you can use a credential provider.

凭证提供程序提供了一种检索密钥库密码和别名密码的方法。请注意，仅当密码/别名密码未在配置中设置时，才使用凭证提供程序。

A credential provider offers a way to retrieve the key store password and alias password. Note that the credential provider is only used if the password / alias password are not set in the configuration.

要配置凭证提供程序，请使用以下属性：

To configure a credential provider, use the following properties:

# 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 key store 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

凭据提供程序只能与 PKCS12 和 JKS 密钥库一起使用。

The credential provider can only be used with PKCS12 and JKS key stores.

Trust stores

信任库用于存储受信任方证书。它们通常用于客户端，当使用 mTLS 时也在服务器端使用。

Trust stores are used to store the certificates of the trusted parties. They are generally used on the client-side, and on the server-side when mTLS is used.

PEM trust stores

PEM 信任库由 .crt 或 .pem 文件列表组成。每个都包含一个证书。

PEM trust stores are composed of a list of .crt or .pem files. Each of them contains a certificate.

要配置 PEM 信任库，请使用以下属性：

To configure a PEM trust store, use the following properties:

quarkus.tls.trust-store.pem.certs=ca.crt,ca2.pem

PKCS12 trust stores

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

PKCS12 trust stores are a single file containing the certificates. When multiple certificates are included, you can use the alias to select the appropriate certificate.

要配置 PKCS12 信任库，请使用以下属性：

To configure a PKCS12 trust store, use the following properties:

quarkus.tls.trust-store.p12.path=client-truststore.p12
quarkus.tls.trust-store.p12.password=password
quarkus.tls.trust-store.p12.alias=my-alias

.p12 文件受密码保护，因此您需要提供密码才能打开信任库。然而，不同于密钥库，别名不需要密码（因为它不是私钥而是公钥证书）。

.p12 files are password-protected, so you need to provide the password to open the trust store. However, unlike for key stores, the alias does not require a password (because it’s the public certificate and not a private key).

JKS trust stores

JKS 信任库是一个包含证书的单个文件。当包含多个证书时，可以使用别名选择适当的证书。请注意，应避免使用 JKS 格式，因为它不如 PKCS12 安全。

JKS trust stores are a single file containing the certificates. When multiple certificates are included, you can use the alias to select the appropriate certificate. Note that the JKS format should be avoided as it is less secure than PKCS12.

要配置 JKS 信任库，请使用以下属性：

To configure a JKS trust store, use the following properties:

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

.jks 文件受密码保护，因此您需要提供密码才能打开信任库。然而，不同于密钥库，别名不需要密码（因为它不是私钥而是公钥证书）。

.jks files are password-protected, so you need to provide the password to open the trust store. However, unlike for key stores, the alias does not require a password (because it’s the public certificate and not a private key).

Credential providers

您可以使用凭据提供程序，而不必在配置中传递信任库密码。

Instead of passing the trust store password in the configuration, you can use a credential provider.

凭据提供程序提供了一种检索密码和其他凭证的方法。请注意，仅当配置中未设置密码时才使用凭据提供程序。

A credential provider offers a way to retrieve passwords and other credentials. Note that the credential provider is only used if the password is not set in the configuration.

要配置凭证提供程序，请使用以下属性：

To configure a credential provider, use the following properties:

# 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 trust store password, `password` by default
quarkus.tls.trust-store.credentials-provider.password-key=password

凭据提供程序只能与 PKCS12 和 JKS 信任库一起使用。

The credential provider can only be used with PKCS12 and JKS trust stores.

Other properties

虽然密钥库和信任库是最重要的属性，但您还可以使用其他属性来配置 TLS。

While key stores and trust stores are the most important properties, there are other properties you can use to configure TLS.

虽然以下示例使用 default 配置，但您可以通过在属性前加上配置名称来使用 named 配置。

while the following examples use the default configuration, you can use the named configuration by prefixing the properties with the name of the configuration.

Cipher suites

密码套件是 TLS 握手期间可使用密码的列表。您可以配置已启用密码套件的有序列表。如果没有配置，则从内置密码中选择一个合理的默认值。然而，当配置后，它优先于正在使用的 SSL 引擎定义的默认套件。

The cipher suites are the list of ciphers that can be used during the TLS handshake. You can configure the ordered list of enabled cipher suites. If not configured, a reasonable default is selected from the built-in ciphers. However, when configured, it takes precedence over the default suite defined by the SSL engine in use.

要配置密码套件，请使用以下属性：

To configure the cipher suites, use the following property:

quarkus.tls.cipher-suites=TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384

TLS protocol versions

TLS 协议版本是 TLS 握手期间可使用协议的列表。您可以配置已启用 TLS 协议的有序列表。如果没有配置，则默认为 TLSv1.3，TLSv1.2。

The TLS protocol versions are the list of protocols that can be used during the TLS handshake. You can configure the ordered list of enabled TLS protocols. If not configured , it defaults to TLSv1.3, TLSv1.2.

支持：TLSv1，TLSv1.1，TLSv1.2，TLSv1.3。

Are supported: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3.

若要仅启用`TLSv1.3`，请配置以下属性：

To only enable TLSv1.3, configure the following property:

quarkus.tls.protocols=TLSv1.3

Handshake timeout

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

When a TLS connection is established, the handshake phase is the first step. During this phase, the client and server exchange information to establish the connection, typically the cipher suite, the TLS protocol version, the certification validation and so on.

若要配置握手阶段的超时，请使用以下属性：

To configure the timeout for the handshake phase, use the following property:

quarkus.tls.handshake-timeout=10S # Default.

ALPN

应用程序层协议协商 (ALPN) 是 TLS 扩展，允许客户端和服务器在 TLS 握手过程中协商它们将用于通信的协议。ALPN 通过允许客户端在 TLS 连接建立之前向服务器指示其首选应用程序协议，从而实现更有效的通信。

Application-Layer Protocol Negotiation (ALPN) is a TLS extension that allows the client and server during the TLS handshake to negotiate which protocol they will use for communication. ALPN enables more efficient communication by allowing the client to indicate its preferred application protocol to the server before the TLS connection is established.

这有助于在诸如 HTTP/2 之类的场景中，其中可能有多个协议可用，从而实现更快的协议选择。

This helps in scenarios such as HTTP/2 where multiple protocols may be available, allowing for faster protocol selection.

ALPN 默认启用。若要禁用它，请使用以下属性：

ALPN is enabled by default. To disable it, use the following property:

quarkus.tls.alpn=false

Certificate Revocation List (CRL)

证书吊销列表 (CRL) 是一个证书列表，该列表中的证书在其预定的到期日期之前已被颁发证书颁发机构 (CA) 吊销。当证书被破坏、不再需要或由于任何原因被视为无效时，CA 将其添加到 CRL 中以告知依赖方不再信任该证书。

A Certificate Revocation List (CRL) is a list of certificates that have been revoked by the issuing Certificate Authority (CA) before their scheduled expiration date. When a certificate is compromised, no longer needed, or deemed invalid for any reason, the CA adds it to the CRL to inform relying parties not to trust the certificate anymore.

您可以使用不再信任的证书文件列表来配置 CRL。允许使用两种格式：DER 和 PKCS#7（也称为 P7B）。

You can configure the CRL with the list of certificate files you do not trust anymore. Two formats are allowed: DER and PKCS#7 (also known as P7B).

  • When using the DER format, you must pass DER-encoded CRLs.

  • When using the PKCS#7 format, you must pass PKCS#7 SignedData object, with the only significant field being crls.

若要配置 CRL，请使用以下属性：

To configure the CRL, use the following property:

quarkus.tls.certificate-revocation-list=ca.crl, ca2.crl

Trusting all certificates and hostname verification

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

These two properties should not be used in production.

您可以配置您的 TLS 连接以信任所有证书并禁用主机名验证。这两个步骤是不同的：

You can configure your TLS connection to trust all certificates and to disable the hostname verification. These are two different steps:

  • trusting all certificates ignores the certificate validation, so all certificates are trusted. It is useful for testing with self-signed certificates, but should not be used in production.

  • hostname verification is the process of verifying the server’s identity. It is useful to prevent man-in-the-middle attacks. It often defaults to HTTPS or LDAPS.

若要信任所有证书，请使用以下属性：

To trust all certificates, use the following property:

quarkus.tls.trust-all=true

若要禁用主机名验证，请使用以下属性：

To disable the hostname verification, use the following property:

quarkus.tls.hostname-verification-algorithm=NONE

Configuration reference

下表列出了受支持的属性：

The following table lists the supported properties:

Unresolved directive in tls-registry-reference.adoc - include::{generated-dir}/config/quarkus-tls-registry.adoc[]

The registry API

尽管扩展程序会自动使用 TLS 注册表，你也可以使用注册表 API 以编程方式访问 TLS 配置。

While extensions will automatically use the TLS registry, you can also use the registry API to access the TLS configuration programmatically.

若要访问 TLS 配置，请注入 TlsConfigurationRegistry bean，通过名称（或默认名称）获取 TLS 配置：

To access the TLS configuration, inject the TlsConfigurationRegistry bean and gets the TLS configuration by name (or the default one):

 @Inject
 TlsConfigurationRegistry certificates;
// ...
TlsConfiguration def = certificates.getDefault().orElseThrow();
TlsConfiguration named = certificates.get("name").orElseThrow();
//...

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

The TlsConfiguration object contains the key stores, trust stores, cipher suites, protocols, and other properties. It also provides a way to create an SSLContext from the configuration.

由于 Vert.x 存在于 Quarkus 的各个方面，因此你还可以使用 TlsConfiguration 对象，配置 Vert.x 客户端或服务器，例如 KeyCertOptions、TrustOptions 等。

As Vert.x is omnipresent in Quarkus, you can also use the TlsConfiguration object to configure the Vert.x client or server such as KeyCertOptions, TrustOptions, and so on.

Registering a certificate from an extension

此部分仅供扩展开发者使用。扩展可以注册 TLS 注册表中的证书。当扩展需要为应用程序提供证书或提供不同格式时，此举很有用。

This section is only for extension developers. An extension can register a certificate in the TLS registry. This is useful when an extension needs to provide a certificate to the application or provides a different format.

为了实现此目的，扩展 processor 必须生成 TlsCertificateBuildItem。TlsCertificateBuildItem 由名称和 CertificateSupplier 组成。

To achieve this, the extension processor must produce a TlsCertificateBuildItem. A TlsCertificateBuildItem is composed of a name and a CertificateSupplier.

TlsCertificateBuildItem item = new TlsCertificateBuildItem("named",
    new MyCertificateSupplier());

证书供应商是运行时对象，通常使用记录器方法进行检索。以下是证书供应商示例：

The certificate supplier is a runtime object that is generally retrieved using a recorder method. Here is an example of a certificate supplier:

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);
            }
        }
    }

Startup checks

在应用程序启动时，TLS 注册表会执行一些检查以确保配置正确：

When the application starts, the TLS registry performs some checks to ensure the configuration is correct:

  • the key stores and trust stores are accessible

  • the aliases are available and accessible in the key stores and trust stores

  • the certificates are valid

  • the cipher suites and protocols are valid

  • the CRLs are valid

如果这些检查有任何一项失败，应用程序都将无法启动。

If any of these checks fail, the application will fail to start.

Reloading certificates

从 TLSConfigurationRegistry 获取的 TlsConfiguration 包含用于重新加载证书的机制。reload 方法刷新密钥库和信任库，通常会从文件系统重新加载。

The TlsConfiguration obtained from the TLSConfigurationRegistry includes a mechanism for reloading certificates. The reload method refreshes the key stores and trust stores, typically by reloading them from the file system.

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

The reload operation is not automatic and must be triggered manually. Additionally, the TlsConfiguration implementation must support reloading (which is the case for the configured certificate).

reload 方法返回 boolean，用于指示重新加载是否成功。值为 true 意味着重新加载操作成功，但并不一定意味着证书已有更新。

The reload method returns a boolean indicating whether the reload was successful. A value of true means the reload operation was successful, not necessarily that there were updates to the certificates.

在 TlsConfiguration 重新加载后，使用此配置的服务器和客户端可能需要执行特定操作来应用新证书。建议的做法是触发服务器和客户端可以侦听并做出必要更改的 CDI 事件 (CertificateReloadedEvent)：

After a TlsConfiguration has been reloaded, servers and clients using this configuration may need to perform specific actions to apply the new certificates. The recommended approach is to fire a CDI event (CertificateReloadedEvent) that servers and clients can listen to and make the necessary changes:

@Inject
TlsConfigurationRegistry registry;

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

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

这些 API 提供了一种实现自定义证书重新加载的方法。

These APIs provide a way to implement custom certificate reloading.

Periodic reloading

TLS 注册表确实包括一种内置机制，用于定期检查文件系统中的更改并重新加载证书。你可以使用属性配置定期重新加载证书。reload-period 属性指定重新加载证书的时间间隔，并会发出 CertificateReloadedEvent。

The TLS registry does include a built-in mechanism for periodically checking the file system for changes and reloading the certificates. You can configure periodic reloading of certificates using properties. The reload-period property specifies the interval at which certificates are reloaded, and it will emit a CertificateReloadedEvent.

quarkus.tls.reload-period=1h
quarkus.tls.key-store.pem.0.cert=tls.crt
quarkus.tls.key-store.pem.0.key=tls.key

你可以在每个命名的配置中设置特定重新加载时间：

For each named configuration, you can set a specific reload period:

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

请记住，受影响的服务器和客户端可能需要侦听 CertificateReloadedEvent 以应用新证书。Quarkus HTTP 服务器（包括启用的管理界面）会自动完成此操作。

Remember that the impacted server and client may need to listen to the CertificateReloadedEvent to apply the new certificates. This is automatically done for the Quarkus HTTP server (including the management interface if enabled).

Using Kubernetes secrets or cert-manager

在 Kubernetes 中运行时，可以使用 Kubernetes 秘钥来存储密钥库和信托库。

When running in Kubernetes, you can use Kubernetes secrets to store the key stores and trust stores.

Using Kubernetes secrets

要使用 Kubernetes 秘钥，需要使用密钥库和信托库创建一个秘钥。我们以以下秘钥为例：

To use Kubernetes secrets, you need to create a secret with the key stores and trust stores. Let’s take the following secret as an example:

apiVersion: v1
data:
  tls.crt: ...
  tls.key: ...
kind: Secret
metadata:
  name: my-certs
type: kubernetes.io/tls

使用这些证书的最简单方法是将秘钥作为 Pod 中的一个卷进行挂载：

The easiest way to uses these certificates is to mount the secret as a volume in the pod:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/name: demo
    app.kubernetes.io/version: 1.0.0-SNAPSHOT
    app.kubernetes.io/managed-by: quarkus
  name: demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: demo
      app.kubernetes.io/version: 1.0.0-SNAPSHOT
  template:
    metadata:
      labels:
        app.kubernetes.io/managed-by: quarkus
        app.kubernetes.io/name: demo
        app.kubernetes.io/version: 1.0.0-SNAPSHOT
    spec:
      containers:
        - env:
            - name: KUBERNETES_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
          image: ...
          imagePullPolicy: IfNotPresent
          name: demo
          ports:
            - containerPort: 8443 # Configure the port to be HTTPS
              name: http
              protocol: TCP
          volumeMounts:
            - mountPath: /certs
              name: my-volume
      volumes:
        - name: my-volume
          secret:
            defaultMode: 0666 # Set the permissions, otherwise the pod may not be able to read the files
            optional: false
            secretName: my-certs # Reference the secret

然后，可以将 TLS 注册表配置为使用这些证书：

Then, you can configure the TLS registry to use the certificates:

# ...
# TLS Registry configuration
%prod.quarkus.tls.http.key-store.pem.0.cert=/certs/tls.crt
%prod.quarkus.tls.http.key-store.pem.0.key=/certs/tls.key

# HTTP server configuration:
%prod.quarkus.http.tls-configuration-name=http
%prod.quarkus.http.insecure-requests=disabled

可以结合周期性重新加载来在证书更改时自动重新加载证书。

You can combine this with the periodic reloading to automatically reload the certificates when they change.

Using cert-manager

在 Kubernetes 中运行时，可以使用 cert-manager 自动生成和更新证书。cert-manager 将生成带有密钥库和信托库的秘钥。因此，配置 TLS 注册表与使用 Kubernetes 秘钥时相同。生成的秘钥使用以下文件：

When running in Kubernetes, you can use cert-manager to automatically generate and renew certificates. Cert-manager will produce a secret with the key stores and trust stores. So, configuring the TLS registry is the same as when using Kubernetes secrets. The generated secret uses the following files:

  • tls.crt for the certificate

  • tls.key for the private key

  • ca.crt for the CA certificate (if needed)

要处理更新，可以使用周期性重新加载机制：

To handle the renewal, you can use the periodic reloading mechanism:

# ...
# TLS Registry configuration
%prod.quarkus.tls.http.key-store.pem.0.cert=/certs/tls.crt
%prod.quarkus.tls.http.key-store.pem.0.key=/certs/tls.key
%prod.quarkus.tls.http.reload-period=24h

# HTTP server configuration:
%prod.quarkus.http.tls-configuration-name=http
%prod.quarkus.http.insecure-requests=disabled

Utilizing OpenShift serving certificates

在 OpenShift 中运行应用程序时，可以利用 OpenShift serving certificates 自动生成和更新 TLS 证书。Quarkus TLS 注册表可以使用这些证书和证书颁发机构 (CA) 文件来安全地处理 HTTPS 流量并验证证书。

When running your application in OpenShift, you can leverage the OpenShift serving certificates to automatically generate and renew TLS certificates. The Quarkus TLS registry can use these certificates and Certificate Authority (CA) files to handle HTTPS traffic securely and to validate certificates.

Acquiring a certificate

要让 OpenShift 生成证书，需要为现有 Service 对象添加注释。生成的证书将存储在秘钥中，然后可以将其挂载到 Pod 中。

To have OpenShift generate a certificate, you need to annotate an existing Service object. The generated certificate will be stored in a secret, which you can then mount in your pod.

考虑以下 Service 示例：

Consider the following Service example:

---
apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.openshift.io/serving-cert-secret-name: my-tls-secret
  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

注释 service.beta.openshift.io/serving-cert-secret-name 指示 OpenShift 生成证书并将证书存储在名为 my-tls-secret 的秘钥中。如果服务已在运行，可以使用以下命令添加此注释：

The annotation service.beta.openshift.io/serving-cert-secret-name instructs OpenShift to generate a certificate and store it in a secret named my-tls-secret. If your service is already running, you can add this annotation with the following command:

oc annotate service hero-service \
     service.beta.openshift.io/serving-cert-secret-name=my-tls-secret

接下来，更新 Deployment 配置以包括卷并将秘钥挂载，从而在 Pod 中挂载秘钥：

Next, mount the secret in your pod by updating your Deployment configuration to include a volume and mount the secret:

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
1 Define a volume to mount the secret. Use the same name as the secret declared above.
2 Set up the key store with the paths to the certificate and private key. This can be configured using environment variables or configuration files. Here, we use environment variables. OpenShift serving certificates always create the tls.crt and tls.key files.
3 Mount the secret in the container. Ensure the path matches the one used in the configuration (here /etc/tls).
4 Configure the port to serve HTTPS.

通过设置 quarkus.tls.key-store.pem.acme.cert 和 quarkus.tls.key-store.pem.acme.key 变量（或其如上所示的环境变量变体），TLS 注册表将使用密钥中的证书和私钥。这配置了 Quarkus HTTP 服务器的默认密钥存储，从而允许其使用该证书。有关在命名配置中使用此证书的信息，请参阅 Referencing a TLS configuration。

By setting the quarkus.tls.key-store.pem.acme.cert and quarkus.tls.key-store.pem.acme.key variables (or their environment variable variant as done above), the TLS registry will use the certificate and private key from the secret. This configures the default key store for the Quarkus HTTP server, allowing it to use the certificate. For using this certificate in a named configuration, refer to Referencing a TLS configuration.

部署您的应用程序，它将利用 OpenShift 生成的证书，使该服务可以通过 HTTPS 使用。

Deploy your application, and it will utilize the certificate generated by OpenShift, making the service available over HTTPS.

Trusting the Certificate Authority (CA)

现在您的服务使用了 OpenShift 发布的证书，您可能需要配置您的客户端应用程序以信任此证书。要完成此操作，创建一个 ConfigMap 包含 CA 证书并将其安装在应用程序的 pod 中。

Now that your service uses a certificate issued by OpenShift, you might need to configure your client applications to trust this certificate. To accomplish this, create a ConfigMap that holds the CA certificate and mount it in the application’s pod.

在本示例中，我们将使用 Quarkus REST 客户端，但相同原理适用于任何客户端。

In this example, we’ll use a Quarkus REST client, but the same principle applies to any client.

首先，为 CA 证书创建一个 ConfigMap。首先定义一个 empty ConfigMap，该 ConfigMap 将使用 CA 证书填充：

First, create a ConfigMap for the CA certificate. Start by defining an empty ConfigMap, which will be populated with the CA certificate:

apiVersion: v1
kind: ConfigMap
metadata:
  name: client-tls-config
  annotations:
    service.beta.openshift.io/inject-cabundle: "true"

service.beta.openshift.io/inject-cabundle 注释用于将 CA 证书注入到 ConfigMap 中。注意，ConfigMap 最初没有数据——它是空的。在处理期间，OpenShift 将 CA 证书注入到 service-ca.crt 文件中的 ConfigMap 中。

The service.beta.openshift.io/inject-cabundle annotation is used to inject the CA certificate into the ConfigMap. Note that the ConfigMap initially has no data — it is empty. During its processing, OpenShift injects the CA certificate into the ConfigMap in the service-ca.crt file.

接下来，通过添加一个卷并将其安装到您的 Deployment 配置中来挂载 ConfigMap：

Next, mount the ConfigMap by adding a volume and mount it in your Deployment configuration:

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
1 Mount the ConfigMap in the container. Ensure the path matches the one used in the configuration (here /deployments/tls).
2 Define a volume to mount the ConfigMap and reference the ConfigMap that receives the CA certificate.

最后，配置 REST 客户端以使用此 CA 证书。考虑以下 REST 客户端界面：

Finally, configure the REST client to use this CA certificate. Consider the following REST client interface:

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();

}
1 Configure the base URI and the configuration key. The name must be in the format <service-name>.<namespace>.svc, otherwise the certificate will not be trusted. Ensure to also configure the configKey.

接下来，配置 REST 客户端以信任 CA 证书：

Next, configure the REST client to trust the CA certificate:

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)
1 Configure the hero REST client with the TLS configuration named my-service-tls.
2 Set up the my-service-tls TLS configuration, specifically the trust store with the CA certificate. Ensure the path matches the one used in the Kubernetes Deployment configuration. The file is always named service-ca.crt.

现在，REST 客户端已配置为信任 OpenShift 生成的证书。

Now, the REST client is configured to trust the certificate generated by OpenShift.

Certificate renewal

OpenShift 会自动更新它生成的证书。当证书更新时，密钥将使用新证书和私钥更新。

OpenShift automatically renews the certificates it generates. When the certificate is renewed, the secret is updated with the new certificate and private key.

为了确保您的应用程序使用新证书，您可以利用 Quarkus TLS 注册表的定期重新加载功能。通过设置 reload-period 属性，TLS 注册表将定期检查密钥存储和信任存储是否发生更改，并在需要时重新加载它们：

To ensure your application uses the new certificate, you can leverage the Quarkus TLS registry’s periodic reloading feature. By setting the reload-period property, the TLS registry will periodically check the key stores and trust stores for changes and reload them if needed:

quarkus.tls.reload-period=24h

您还可以实现一种自定义机制，在密钥更新时重新加载证书。有关详细信息，请参阅 Reloading certificates。

You can also implement a custom mechanism to reload the certificates when the secret is updated. See Reloading certificates for more information.

Quarkus CLI commands and development CA (Certificate Authority)

TLS 注册表提供 CLI 命令来生成开发 CA 和受信任的证书。这避免了在本地使用自签名证书。

The TLS registry provides CLI commands to generate a development CA and trusted certificates. This avoids having to use self-signed certificates locally.

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

在大多数情况下，你生成 Quarkus 开发 CA 一次，然后生成这个 CA 签署的证书。Quarkus 开发 CA 是一款可用于本地签署证书的证书颁发机构。它仅对开发用途有效，仅在本地机器上受信任。生成的 CA 位于 $HOME/.quarkus/quarkus-dev-root-ca.pem，并安装在系统受信存储区中。

In most cases, you generate the Quarkus Development CA once, and then generate certificates signed by this CA. The Quarkus Development CA is a Certificate Authority that can be used to sign certificates locally. It is only valid for development purposes and only trusted on the local machine. The generated CA is located in $HOME/.quarkus/quarkus-dev-root-ca.pem, and installed in the system trust store.

CA, signed vs. self-signed certificates

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

When developing with TLS, you can use two types of certificates:

  • a self-signed certificate: the certificate is signed by the same entity that uses it. It is not trusted by default. It’s generally what we use when we don’t have a CA, or don’t want to dig too much into TLS. This is not a production setup, and may be used only for development.

  • a signed certificate: the certificate is signed by a Certificate Authority (CA). The CA is a trusted entity that signs the certificate. The certificate is trusted by default. This is what we use in production.

当在本地运行应用程序时，我们可以使用自签名证书，但并不总是方便。通常，浏览器不会信任证书，你必须手动导入它。curl、wget、`httpie`等工具也不会信任证书。

We could use self-signed certificate when running application locally, but it’s not always convenient. Typically, browsers will not trust the certificate, and you will have to import it manually. curl, wget, httpie and other tools will also not trust the certificate.

为避免这种情况，我们可以使用开发 CA 来签署证书，并将其安装到系统受信存储区中。这样，由该 CA 签署的每个证书都将受到系统的信任。

To avoid this, we can use a development CA to sign the certificates, and install it into the system trust store. Thus, every certificate signed by this CA will be trusted by the system.

Quarkus 可以轻松生成开发 CA 和由该 CA 签署的证书。

Quarkus makes it easy to generate a development CA and certificates signed by this CA.

Generate a development CA

开发 CA 是一款可用于本地签署证书的证书颁发机构。请注意，生成的 CA 仅对开发用途有效，并且仅在本地机器上受信任。

The development CA is a Certificate Authority that can be used to sign certificates locally. Note that the generated CA is only valid for development purposes, and only trusted on the local machine.

要生成开发 CA，请使用以下命令：

To generate a development CA, use the following command:

quarkus tls generate-ca-certificate --install --renew --truststore

--install`将 CA 安装到系统受信存储区中。支持 Windows、Mac 和 Linux (Fedora 和 Ubuntu)。但是，根据你的浏览器，你可能需要手动导入生成的 CA。有关更多信息，请参阅浏览器文档。生成的 CA 位于 `$HOME/.quarkus/quarkus-dev-root-ca.pem。

--install installs the CA in the system trust store. Windows, Mac and Linux (Fedora and Ubuntu) are supported. However, depending on your browser, you may need to import the generated CA manually. Refer to the browser documentation for more information. The generated CA is located in $HOME/.quarkus/quarkus-dev-root-ca.pem.

安装证书时，系统可能会要求你提供密码才能将证书安装到系统受信存储区，或者在对话框中要求你确认（在 Windows 上）。

When installing the certificate, your system may ask for your password to install the certificate in the system trust store, or ask for confirmation in a dialog (on Windows).

在 Windows 上，请务必从提升的终端（以管理员身份运行）运行命令将 CA 安装到系统受信存储区中。

On Windows, makes sure you run from an elevated terminal (run as administrator) to install the CA in the system trust store.

--renew`如果 CA 已存在，则会更新 CA。当使用此选项时，你需要重新生成由该 CA 签署的证书，因为私钥已更改。请注意，如果 CA 过期，它将自动续订（不传递 `--renew）。

--renew renews the CA if it already exists. When this option is used, you need to re-generate the certificates that were signed by the CA, as the private key is changed. Note that if the CA expires, it will automatically be renewed (without passing --renew).

`--truststore`还会生成一个包含 CA 证书的 PKCS12 信任存储。

--truststore also generates a PKCS12 trust store containing the CA certificate.

Generate a trusted (signed) certificate

安装 Quarkus 开发 CA 后，你可以生成受信任的证书。它将由 Quarkus 开发 CA 签署，因此受到你的系统信任。

Once you have installed the Quarkus Development CA, you can generate a trusted certificate. It will be signed by the Quarkus Development CA, and so trusted by your system.

quarkus tls generate-certificate --name my-cert

这会生成一个由 Quarkus 开发 CA 签署的证书，因此如果正确安装/导入，它将受到系统的信任。

This generates a certificate signed by the Quarkus Development CA, and so if properly installed / imported, will be trusted by your system.

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

The certificate is stored in ./.certs/. Two files are generated:

  • $NAME-keystore.p12 - contains the private key and the certificate. It’s password protected.

  • $NAME-truststore.p12 - contains the CA certificate, that you can used as trust store (for test, for instance).

提供了更多选项：

More options are available:

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

生成证书时，还会生成一个 .env 文件，使 Quarkus 开发模式能够识别这些证书。因此，如果您在开发模式下运行应用程序，它将使用以下证书：

When generating the certificate, a .env file is also generated making the Quarkus dev mode aware of these certificates. So, then, if you run your application in dev mode, it will use these certificates:

./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

现在，您可以使用 HTTPS 打开开发界面： https://localhost:8443/q/dev，或使用 curl 发出请求：

Now, you can open the Dev UI using HTTPS: https://localhost:8443/q/dev, or issue a request using curl:

curl https://localhost:8443/hello
Hello from Quarkus REST%

如果未安装 Quarkus Development CA，则会生成一个自签名证书。

If the Quarkus Development CA is not installed, a self-signed certificate is generated.

Generating a self-signed certificate

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

Even if the Quarkus Development CA is installed, you can generate a self-signed certificate:

quarkus tls generate-certificate --name my-cert --self-signed

此操作会生成一个由 Quarkus Development CA 签署的自签名证书。

This generates a self-signed certificate, not signed by the Quarkus Development CA.

Uninstalling the Quarkus Development CA

从您的系统中卸载 Quarkus Development CA 取决于您的操作系统。

Uninstalling the Quarkus Development CA from your system depends on your OS.

Deleting the CA certificate on Windows

要在 Windows 中删除 CA 证书，请使用具有管理员权限的 Powershell 终端执行以下命令：

To delete the CA certificate on Windows, use the following commands from a Powershell terminal with administrator rights:

# 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.

> certutil -delstore -user -v Root $Serial_Number

使用 CA 证书的序列号替换 $Serial_Number 。

Replace $Serial_Number with the serial number of the CA certificate.

Deleting the CA certificate on Linux

在 Fedora 中，您可以使用以下命令：

On Fedora, you can use the following command:

sudo rm /etc/pki/ca-trust/source/anchors/quarkus-dev-root-ca.pem
sudo update-ca-trust

在 Ubuntu 中，您可以使用以下命令：

On Ubuntu, you can use the following command:

sudo rm /usr/local/share/ca-certificates/quarkus-dev-root-ca.pem
sudo update-ca-certificates

Deleting the CA certificate on Mac

在 Mac 中，您可以使用以下命令：

On Mac, you can use the following command:

sudo security -v remove-trusted-cert -d /Users/clement/.quarkus/quarkus-dev-root-ca.pem

Automatic certificate management with Let’s Encrypt

Let’s Encrypt 是由 Internet Security Research Group 提供的免费自动证书颁发机构。

Let’s Encrypt is a free, automated certificate authority provided by Internet Security Research Group.

Let’s Encrypt 使用 Automated certificate management environment (ACME) protocol 来支持自动证书签发和续订。请阅读 Let’s Encrypt documentation 以了解有关 Let’s Encrypt 和 ACME 的更多信息。

Let’s Encrypt uses Automated certificate management environment (ACME) protocol to support an automatic certificate issuance and renewal. Please read Let’s Encrypt documentation to learn more about Let’s Encrypt and ACME.

TLS 注册项目提供了一个 CLI ACME 客户端来签发和续订 Let’s Encrypt 证书。您的应用程序使用 TLS 注册来解决 ACME 协议挑战。

TLS registry project provides a CLI ACME client to issue and renew Let’s Encrypt certificates. Your application uses TLS registry to resolve ACME protocol challenges.

按照以下步骤，为您的 Quarkus 应用程序做好准备，并使用新的和续订的 Let’s Encrypt 证书自动更新。

Follow the steps below to have your Quarkus application prepared and automatically updated with new and renewed Let’s Encrypt certificates.

Prerequisites

确保有一个完全可解析的 DNS 域名，并且可以用来访问您的应用程序。将该域名用于创建 Let’s Encrypt 帐户，并支持 Let’s Encrypt ACME 挑战以证明您拥有此域名。您可以使用 Ngrok 开始尝试 Quarkus Let’s Encrypt ACME 功能，有关更多信息，请参见下面的 Use NGrok for testing 部分。

Make sure that a fully resolvable DNS domain name is available and can be used to access your application. This domain name is used for creating a Let’s Encrypt account, and supporting Let’s Encrypt ACME challenges to prove that you own this domain. You can use Ngrok to start experimenting with the Quarkus Let’s Encrypt ACME feature, see Use NGrok for testing section below for more information.

您的 Quarkus HTTPS 应用程序必须使用 build-time 属性来启用 Let’s Encrypt ACME 挑战路由：

Your Quarkus HTTPS application must use a build-time property to enable a Let’s Encrypt ACME challenge route:

quarkus.tls.lets-encrypt.enabled=true

TLS 注册可以通过主 HTTP 接口或管理接口管理挑战过程。*strongly*建议使用管理接口，以便让 Quarkus 将 ACME 挑战配置与主应用程序的部署和安全要求分开处理：

The TLS registry can manage the challenge process from either the main HTTP interface or from the management interface. Using a management interface is strongly recommended to let Quarkus deal with ACME challenge configuration separately to the main application’s deployment and security requirements:

quarkus.tls.lets-encrypt.enabled=true
quarkus.management.enabled=true

挑战本身由主 HTTP 界面提供（可通过你的 DNS 域名访问）。

The challenge itself is served from the primary HTTP interface (the one accessible from your DNS domain name).

不要在此处启动你的应用程序。

Do not start your application yet.

Application preparation

在你请求 Let’s Encrypt 证书之前，你必须运行 TLS 注册表 Let’s Encrypt CLI prepare 命令，来为你的应用程序做准备：

Before you request a Let’s Encrypt certificate, you must run TLS registry Let’s Encrypt CLI prepare command to prepare your application:

quarkus tls lets-encrypt prepare --domain=<domain-dns-name>

确保在你的应用程序根目录中运行准备命令。

Make sure you run a prepare command in the root directory of your application.

prepare 命令执行以下操作：

The prepare command does the following:

  • Creates a .letsencrypt folder in your application’s root directory

  • Creates a self-signed domain certificate and private key for your application configured in the previous Prerequisites step to be able to start and accept HTTPS requests.

  • Create a .env configuration file in your application’s root directory configure the application to use the self-signed domain certificate and private key (until we get the Let’s Encrypt certificate).

下文展示了生成的 .env 文件示例：

The following snippet shows an example of the generated .env file:

quarkus.tls.key-store.pem.acme.cert=.letsencrypt/lets-encrypt.crt
quarkus.tls.key-store.pem.acme.key=.letsencrypt/lets-encrypt.key

.env 文件不包含 quarkus.tls.lets-encrypt.enabled 和 quarkus.management.enabled 属性，因为它们是生成时属性，需要重新生成应用程序。

The .env file does not contain the quarkus.tls.lets-encrypt.enabled and quarkus.management.enabled properties as they are build-time properties requiring a rebuild of the application.

Start your application

你可以启动你的应用程序：

You can start your application:

java -jar quarkus-run.jar

使用 https://your-domain-name:8443/ 访问你的应用程序端点，例如，https://your-domain-name:8443/hello，在浏览器中接收自签名证书。

Access your application endpoint using https://your-domain-name:8443/, for example, https://your-domain-name:8443/hello, accept a self-signed certificate in the browser.

接下来，保持应用程序运行，并请求你的第一个 Let’s Encrypt 证书。

Next, keep the application running and request your first Let’s Encrypt certificate.

Issue certificate

从应用程序目录，运行 issue-certificate 命令来获取你的第一个 Let’s Encrypt 证书：

From the application directory, run the issue-certificate command to acquire your first Let’s Encrypt certificate:

quarkus tls lets-encrypt issue-certificate \
  --domain=<domain-dns-name> \ 1
  --email=<your contact email> \ 2
  --management-url=https://localhost:9000 3
1 Set your domain name.
2 Provide your contact email address that Let’s Encrypt can use to contact you in case of any issues with your Let’s Encrypt account.
3 Set your application management URL which can be used to handle ACME challenges. Use https://localhost:8443/ if you chose not to enable a management router in the Prerequisites step.

在此命令期间，TLS 注册表 CLI 检查应用程序是否已准备就绪，可提供挑战、创建和记录 Let’s Encrypt 帐户信息、发布 Let’s Encrypt 证书请求，并与 Quarkus 应用程序交互，以解决 ACME 挑战。

During this command, the TLS registry CLI checks if the application is prepared to serve the challenge, creates and records Let’s Encrypt account information, issues a Let’s Encrypt certificate request, and interacts with the Quarkus application to resolve ACME challenges.

在成功获取 Let’s Encrypt 证书链和私钥之后，它们会被转换为 PEM 格式并复制到你的应用程序的 .letsencrypt 文件夹。TLS 注册表将被告知已有新的证书和私钥准备就绪，并将自动重新加载它们。

Once the Let’s Encrypt certificate chain and private key have been successfully acquired, they are converted to PEM format and copied to your application’s .letsencrypt folder. The TLS registry is informed that a new certificate and private key are ready, and reloads them automatically.

现在，再次使用 https://your-domain-name:8443/ 访问你的应用程序的端点。在浏览器中确认你的域证书现已由 Let’s Encrypt 证书颁发机构签名。

Now, access your application’s endpoint using https://your-domain-name:8443/ again. Confirm in the browser that your domain certificate is now signed by the Let’s Encrypt certificate authority.

请注意，目前 Let’s Encrypt 帐户是通过 `issue-certificate`命令隐式创建的，以便用户轻松开始使用 ACME 协议。对 Let’s Encrypt 帐户管理的支持将会进一步发展。

Note that currently, a Let’s Encrypt account is created implicitly by the issue-certificate command to make it easy for users to get started with the ACME protocol. Support for the Let’s Encrypt account management will evolve further.

Renew certificate

更新证书与签发第一张证书类似，但需要在 Issue certificate步骤中创建一个现有帐户。

Renewing certificates is similar to issuing the first certificate, but it requires an existing account created during the Issue certificate step.

运行以下命令以更新 Let’s Encrypt 证书：

Run the following command to renew your Let’s Encrypt certificate:

quarkus tls lets-encrypt renew-certificate \
  --domain=<domain-dns-name> 1
1 Set your domain name.

在该命令期间，TLS 注册表 CLI 会读取在 Issue certificate步骤中录制的 Let’s Encrypt 帐户信息、签发 Let’s Encrypt 证书请求，并与 Quarkus 应用程序通信以便解决 ACME 质询。

During this command, TLS registry CLI reads a Let’s Encrypt account information recorded during the Issue certificate step, issues a Let’s Encrypt certificate request, and communicates with a Quarkus application to have ACME challenges resolved.

一旦 Let’s Encrypt 证书链和私钥更新成功，它们将被转换为 PEM 格式并复制到应用程序的 `.letsencrypt`文件夹。TLS 注册表将获悉已准备好新证书和私钥，它会自动重新加载它们。

Once the Let’s Encrypt certificate chain and private key have been successfully renewed, they are converted to PEM format and copied to your application’s .letsencrypt folder. TLS registry is informed that a new certificate and private key are ready and it reloads them automatically.

Use NGrok for testing

Ngrok可用于向运行在 localhost 上的应用程序提供安全的 HTTPS 通道，并让 HTTPS 根据应用程序轻松进行测试。

Ngrok can be used to provide a secure HTTPS tunnel to your application running on localhost, and make it easy to test HTTPS based applications.

使用 Ngrok 提供了最简单的选项来开始使用 Quarkus Let’s Encrypt ACME 功能。

Using Ngrok provides an easiest option to get started with the Quarkus Let’s Encrypt ACME feature.

使用 Ngrok 的第一件事是要求它预留一个域。您可以在开发模式中使用 Quarkiverse NGrok，或直接在 Ngrok 仪表盘中进行预留。

The first thing you have to do with Ngrok is to ask it to reserve a domain. You can use Quarkiverse NGrok in devmode, or have it reserved directly in the NGrok dashboard.

遗憾的是，您无法立即使用 Ngrok 域来测试 Quarkus Let’s Encrypt ACME 功能。这是因为 Ngrok 本身正在使用 Let’s Encrypt，并且会拦截由 Quarkus 应用程序处理的 ACME 质询。

Unfortunately, you can’t use your NGrok domain to test the Quarkus Let’s Encrypt ACME feature immediately. This is due to the fact that Ngrok is itself using Let’s Encrypt and intercepts ACME challenges which are meant to be handled by the Quarkus application instead.

因此，您需要从 Ngrok 域中删除 Ngrok Let’s Encrypt 证书政策：

Therefore, you need to remove an NGrok Let’s Encrypt certificate policy from your NGrok domain:

ngrok api --api-key <YOUR-API-KEY> reserved-domains delete-certificate-management-policy <YOUR-RESERVED-DOMAIN-ID>

`YOUR-RESERVED-DOMAIN-ID`是您的预留域的 ID，它从 `rd_`开始，您可以在 NGrok dashboard domains section中找到它。

YOUR-RESERVED-DOMAIN-ID is your reserved domain’s id which starts from rd_, you can find it in the NGrok dashboard domains section.

现在，Ngrok 将仅通过 HTTP 转发 ACME 质询，因此您需要像这样启动 Ngrok：

Now, NGrok will forward ACME challenges over HTTP only, therefore you need to start Ngrok like this:

ngrok http --domain <YOUR-NGROK-DOMAIN> 8080 --scheme http

其中 `8080`是应用程序正在监听的 localhost HTTP 端口。

where 8080 is the localhost HTTP port that your application is listening on.

您现在可以从本地计算机测试 Quarkus Let’s Encrypt ACME 功能。

You can now test the Quarkus Let’s Encrypt ACME feature from your local machine.