TLS レジストリーリファレンス
The TLS Registry is a Quarkus extension that centralizes TLS configuration, making it easier to manage and maintain secure connections across your application.
When defining TLS configurations in a single centralized location, you can use the TLS Registry to reference them from multiple components within the application, ensuring consistency and reducing the risk of configuration errors.
TLS レジストリーは設定を統合し、複数の名前付き設定をサポートしています。 したがって、さまざまなアプリケーションパーツに合わせて TLS 設定をカスタマイズできます。 この柔軟性は、各コンポーネントに異なるセキュリティー設定が必要な場合に特に役立ちます。
Quarkus REST、gRPC、SmallRye GraphQL Client、Reactive Routes などの互換性のあるエクステンションを使用すると、 TLS レジストリーエクステンションがプロジェクトに 自動的に追加されます。
そのため、TLS レジストリーを使用するアプリケーションは、すぐにセキュアな通信を処理できるようになります。
TLS レジストリーは、証明書の自動再読み込み、 Let’s Encrypt (ACME) との統合、 Kubernetes Cert-Manager のサポート、 および PKCS12、PEM、JKS などのさまざまなキーストアフォーマットとの互換性も提供します。
1. TLS レジストリーの使用
キーとトラストストアを含む TLS 接続を設定するには、quarkus.tls.* プロパティーを使用します。
これらのプロパティーは次の場合に必要です。
-
デフォルトの TLS 設定を設定する (
quarkus.tls.*の直下に定義)。 -
quarkus.tls.<name>.*を使用して、個別の名前付き設定を作成します。quarkus.tls.<name>.*プロパティーを使用すると、特定のコンポーネントの TLS 設定を受け入れることができます。
|
The default TLS configuration is not a fallback or global configuration.
Each named TLS configuration, or "TLS bucket," must provide its own properties.
For instance, |
|
As described in detail here, Quarkus client extensions (such as REST, GRPC, and so on) ignore properties defined in default (that is, unnamed) TLS configurations.
The |
1.1. Configuring HTTPS for an HTTP server
クライアントとサーバー間のセキュアな通信を確保するには、多くの場合、クライアントがサーバーの信頼性を検証する必要があります。
-
サーバーは、証明書と秘密鍵を含むキーストアを使用する必要があります。
-
サーバーの証明書を検証するために、クライアントにトラストストアを設定する必要があります。
TLS ハンドシェイク中に、サーバーは証明書を提示し、クライアントはそれを検証します。 これにより、中間者攻撃を防ぎ、データ転送をセキュアに行うことができます。
The following sections guide you through setting up HTTPS by using PEM or PKCS12 keystore types. In addition, they provide guidance on named configurations to specify and manage multiple TLS configurations simultaneously, allowing you to define distinct settings for each.
キーストアタイプに応じて、次のいずれかの設定例を使用してください。
-
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 -
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 -
複数の設定を名前で区別する場合:
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
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=true1.3. mTLS の設定
Quarkus アプリケーションで相互 TLS (mTLS) を設定するには、サーバーとクライアントにキーストアとトラストストアの両方を作成して管理することで、それぞれを設定します。
-
サーバーのキーストア: サーバーの証明書と秘密鍵が格納されます。
-
クライアントのキーストア: クライアントの証明書と秘密鍵が格納されます。
-
サーバーのトラストストア: クライアントを認証するためのクライアント証明書が保存されます。
-
クライアントのトラストストア: サーバーを認証するためのサーバーの証明書が保存されます。
キーストアとトラストストアを指定するための設定例: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=falseThis configuration enables mTLS by ensuring that both the server and the client validate each other’s certificates, which provides an additional layer of security.
2. TLS 設定の参照
TLS レジストリーの使用 で説明されているように、quarkus.tls.<name>.* プロパティーを使用して作成したサンプルの 名前付き 設定を参照するには、次の例に示すように tls-configuration-name プロパティーを使用します。
# Reference the named configuration
quarkus.http.tls-configuration-name=MY_TLS_CONFIGURATIONquarkus.grpc.clients.hello.tls-configuration-name=MY_TLS_CONFIGURATIONquarkus.smallrye-graphql-client.my-client.tls-configuration-name=MY_TLS_CONFIGURATION|
When you configure the Typesafe GraphQL client with certificate reloading, as described in the 証明書の再読み込み section, override the bean scope to A shorter scope ensures that instances created after a certificate reload use the latest certificate. Dynamic clients are |
2.1. SunJSSE のデフォルトのトラストストアを参照する
JDK distributions typically contain a truststore in the $JAVA_HOME/lib/security/cacerts file.
SunJSSE uses this truststore as the default truststore.
SunJSSE is the default implementation of the Java Secure Socket Extension (JSSE).
Java runtime components, such as javax.net.ssl.HttpsURLConnection, rely on JSSE for SSL and TLS.
Quarkus エクステンションは通常、SunJSSE のデフォルトのトラストストアを尊重しませんが、状況によってはそれを使用することが実用的です。 これは、従来のテクノロジーから移行する場合、または SunJSSE トラストストアがオペレーティングシステム (OS) と同期されている Linux ディストリビューションで実行する場合に適用されます。
SunJSSE トラストストアの使用を簡素化するために、Quarkus TLS レジストリーは、SunJSSE のデフォルトの動作を模倣した javax.net.ssl という名前の TLS 設定を提供します。
-
javax.net.ssl.trustStoreシステムプロパティーが定義されている場合、その値はトラストストアとして尊重されます。 -
それ以外の場合は、
$JAVA_HOME/lib/security/jssecacertsand$JAVA_HOME/lib/security/cacertsのパスがチェックされ、最初の既存のファイルがトラストストアとして使用されます。 -
どちらの条件も満たされない場合は、
IllegalStateExceptionがスローされます。
The password to open the truststore is obtained from the javax.net.ssl.trustStorePassword system property.
If this property is not set, the default password changeit is used.
javax.net.ssl 設定は、以下に示すように、さまざまな *.tls-configuration-name プロパティーの値として使用できます。
quarkus.grpc.clients.hello.tls-configuration-name=javax.net.ssl|
The |
3. TLS の設定
TLS 設定には、主にキーストアとトラストストアの管理が含まれます。 具体的な設定は、使用されるフォーマット (PEM、P12、JKS など) により異なります。
The following sections outline the available TLS configuration properties.
3.1. キーストア
Key stores store private keys and certificates. They are mainly used on the server side, but can also be used on the client side when mTLS is used.
3.1.1. PEM キーストア
Privacy Enhanced Mail (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ほとんどの場合、証明書と秘密鍵で構成されるペアが 1 つだけ必要です。 証明書が証明書チェーンの一部である場合でも、キーストアに含まれる秘密鍵は、エンドエンティティー証明書に対応するもの 1 つだけです。
複数のペアが設定されている場合、設定された証明書と秘密鍵のペアの 1 つが、Server Name Indication (SNI) に基づいて選択されます。 クライアントは接続しようとしているサーバーの名前を送信し、サーバーは適切な証明書と秘密鍵のペアを選択します。 この機能を使用するには、クライアントとサーバーの両方で SNI が有効になっていることを確認してください。
|
複数の鍵ペアまたは証明書ペアを設定する場合、前の例の この設定は、最初に指定されたペアをデフォルトとして使用するため、SNI を使用する場合に重要です。 |
When using a PEM keystore, the following formats are supported:
-
PKCS#8 秘密鍵 (非暗号化)
-
PKCS#1 RSA 秘密鍵 (非暗号化)
-
暗号化された PKCS#8 秘密鍵 (AES-128-CBC で暗号化)
For an encrypted PKCS#8 private key, set the quarkus.tls.key-store.pem.password or quarkus.tls.key-store.pem.<name>.password property to the password that decrypts the private key.
quarkus.tls.http.key-store.pem.cert=certificate.crt
quarkus.tls.http.key-store.pem.key=key.key
quarkus.tls.http.key-store.pem.password=password3.1.2. PKCS12 キーストア
PKCS12 キーストアは、証明書と秘密鍵を含む単一のファイルです。
PKCS12 キーストアを設定するには、次のように指定します。
quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret.p12 ファイルはパスワードで保護されているため、キーストアを開くにはパスワードを指定する必要があります。
These files can contain multiple certificates and private keys. If this is the case, take either of the following actions:
-
使用する証明書と秘密鍵のエイリアスを指定して設定します。
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 -
または、SNI を使用して適切な証明書と秘密鍵を選択します。 すべてのキーに同じパスワードを使用する必要があることに注意してください。
3.1.3. JKS キーストア
JKS keystores are single files that contain the server or client certificate and its private key, used to authenticate and establish secure TLS/SSL connections.
|
JKS は古いフォーマットですが、今でも広く使用されている Java 固有のフォーマットです。 ただし、このフォーマットを扱うには、現在では非推奨となっている特定の Java ツールを使用する必要があります。 したがって、Quarkus アプリケーションでの使用は推奨されません。 また、OpenShift cert-manager や Let’s Encrypt は、通常 JKS を提供せず、現在も PEM しか提供しません。 |
JKS キーストアを設定するには、次のように指定します。
quarkus.tls.key-store.jks.path=server-keystore.jks
quarkus.tls.key-store.jks.password=secret.jks files are password-protected, so you need to provide the password to open the keystore.
Also, they can include multiple certificates and private keys.
If this is the case:
-
使用する証明書と秘密鍵のエイリアスを指定して設定します。
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 を使用して適切な証明書と秘密鍵を選択します。 すべてのキーに同じパスワードを使用する必要があることに注意してください。
3.1.4. 提供されたキーストア
If you need more control over the keystore used in a TLS configuration, you can provide a CDI bean implementing the io.quarkus.tls.runtime.KeyStoreProvider interface.
Quarkus calls KeyStoreProvider::getKeyStore when the TLS configuration is initially created and any time the configuration is reloaded.
The resulting keystore and options are then made available via TlsConfiguration::getKeyStore and TlsConfiguration::getKeyStoreOptions.
import io.quarkus.tls.runtime.KeyStoreAndKeyCertOptions;
import io.quarkus.tls.runtime.KeyStoreProvider;
import io.smallrye.common.annotation.Identifier;
import io.vertx.core.Vertx;
import io.vertx.core.buffer.Buffer;
import io.vertx.core.net.PemKeyCertOptions;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
@ApplicationScoped (1)
@Identifier("<name>") (2)
public class ExampleKeyStoreProvider implements KeyStoreProvider {
@Inject (3)
SecurityDatabase securityDatabase;
@Override
public KeyStoreAndKeyCertOptions getKeyStore(Vertx vertx) {
try {
var options = new PemKeyCertOptions()
.addCertValue(Buffer.buffer(securityDatabase.getEntityCertificate()))
.addKeyValue(Buffer.buffer(securityDatabase.getEntityPrivateKey()));
var keyStore = options
.loadKeyStore(vertx);
return new KeyStoreAndKeyCertOptions(keyStore, options);
} catch (Exception e) {
throw new RuntimeException(e);
}
}
}| 1 | The CDI bean implementing the KeyStoreProvider interface can be @ApplicationScoped, @Singleton, or @Dependent. |
| 2 | Use the @Identifier qualifier to indicate the named TLS configuration that provides the keystore options.
Omit the qualifier to indicate the default TLS configuration.
You can also use @Default explicitly to indicate the default TLS configuration.
For more information, see TLS 設定の参照. |
| 3 | You can inject other CDI beans to access keystore material at runtime. |
3.1.5. SNI
Server Name Indication (SNI) is a TLS extension that makes it possible for a client to specify the hostname to which it attempts to connect during the TLS handshake. SNI enables a server to present multiple TLS certificates for different domains on a single IP address, facilitating secure communication in virtual hosting scenarios.
SNI を有効にするには、次のように指定します。
quarkus.tls.key-store.sni=true # Disabled by defaultSNI が有効な場合、クライアントは TLS ハンドシェイク中にサーバー名を示します。これにより、サーバーが適切な証明書を選択できるようになります。
-
PEM ファイルを使用してキーストアを設定する場合は、複数の証明書 (CRT) ファイルと鍵ファイルを提供する必要があります。 CRT は、X.509 証明書ファイルの一般的なファイル拡張子であり、通常は PEM (Privacy-Enhanced Mail) フォーマットです。 このファイルには公開証明書が含まれています。
-
When configuring the keystore with a JKS or P12 file, the server selects the appropriate certificate based on the SNI hostname provided by the client during the TLS handshake. The server matches the SNI hostname with the common name (CN) or subject alternative names (SAN) configured in the certificates stored in the keystore. All keystore and alias passwords must be identical.
3.1.6. 認証情報プロバイダー
You can use a credential provider instead of specifying the keystore and alias passwords in the configuration.
A credential provider offers a way to retrieve the keystore and alias password. Quarkus uses the credential provider only when the configuration does not set the keystore password or alias password.
認証情報プロバイダーを設定するには、次のように指定します。
# 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| 認証情報プロバイダーは、PKCS12 および JKS キーストアでのみ使用できます。 |
3.2. トラストストア
トラストストアは、信頼できる当事者の証明書を保存するために使用されます。 通常の TLS では、クライアントがトラストストアを使用してサーバーを認証します。 相互 TLS (mTLS) では、サーバーとクライアントの両方がトラストストアを使用して相互に認証します。
3.2.1. PEM トラストストア
PEM トラストストアは、.crt または .pem ファイルのリストで構成されます。
それぞれに証明書が含まれています。
PEM トラストストアを設定するには、次のように指定します。
quarkus.tls.trust-store.pem.certs=ca.crt,ca2.pem3.2.2. PKCS12 トラストストア
PKCS12 truststores are single-file containers for certificates. You can use the alias to select the appropriate certificate when multiple certificates are included.
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.p12 ファイルはパスワードで保護されているため、トラストストアを開くにはパスワードを入力する必要があります。
ただし、キーストアとは異なり、トラストストアには秘密鍵ではなく公開証明書が含まれているため、エイリアスにパスワードは必要ありません。
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.jks ファイルはパスワードで保護されているため、トラストストアを開くにはパスワードを入力する必要があります。
ただし、キーストアとは異なり、トラストストアには秘密鍵ではなく公開証明書が含まれているため、エイリアスにパスワードは必要ありません。
3.2.4. 提供されたトラストストア
TLS 設定で使用されるトラストストアをより細かく制御する必要がある場合は、io.quarkus.tls.runtime.TrustStoreProvider`インターフェイスを実装する CDI Bean を提供できます。Quarkus は TLS 設定が最初に作成される 場合、および設定が リロード されるたびに、`TrustStoreProvider::getTrustStore を呼び出します。結果として得られるトラストストアとオプションは、TlsConfiguration::getTrustStore および TlsConfiguration::getTrustStoreOptions を介して利用できるようになります。
import io.quarkus.tls.runtime.TrustStoreAndTrustOptions;
import io.quarkus.tls.runtime.TrustStoreProvider;
import io.smallrye.common.annotation.Identifier;
import io.vertx.core.Vertx;
import io.vertx.core.buffer.Buffer;
import io.vertx.core.net.PemTrustOptions;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
@ApplicationScoped (1)
@Identifier("<name>") (2)
public class ExampleTrustStoreProvider implements TrustStoreProvider {
@Inject (3)
SecurityDatabase securityDatabase;
@Override
public TrustStoreAndTrustOptions getTrustStore(Vertx vertx) {
try {
var options = new PemTrustOptions()
.addCertValue(Buffer.buffer(securityDatabase.getTrustedRootCertificate()));
var trustStore = options
.loadKeyStore(vertx);
return new TrustStoreAndTrustOptions(trustStore, options);
} catch (Exception e) {
throw new RuntimeException(e);
}
}
}| 1 | The CDI bean that implements the TrustStoreProvider interface can be @ApplicationScoped, @Singleton, or @Dependent. |
| 2 | Use the @Identifier qualifier to indicate the named TLS configuration that provides the truststore options.
Omit the qualifier to indicate the default TLS configuration.
You can also use @Default explicitly to indicate the default TLS configuration.
For more information, see TLS 設定の参照. |
| 3 | You can inject other CDI beans to access truststore material at runtime. |
3.2.5. 認証情報プロバイダー
設定でトラストストアのパスワードを渡す代わりに、認証情報プロバイダーを使用できます。 認証情報プロバイダーを使用すると、パスワードやその他の認証情報を取得できます。 認証情報プロバイダーは、設定でパスワードが指定されていない場合にのみ使用されることに注意してください。
認証情報プロバイダーを設定するには、次のように指定します。
# 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| 認証情報プロバイダーは、PKCS12 および JKS トラストストアでのみ使用できます。 |
3.3. その他のプロパティー
キーストアとトラストストアは最も重要なプロパティーですが、TLS を設定するために使用できる他のプロパティーもあります。
| 次の例では デフォルト の設定を使用していますが、プロパティーの前に設定名を付けることで、名前付き 設定を使用することもできます。 |
3.3.1. 暗号スイート
暗号スイートは、TLS ハンドシェイク中に使用できる暗号のリストです。 有効な暗号スイートの順序付きリストを設定できます。 設定されていない場合は、組み込みの暗号の中から適切なデフォルトが選択されます。 ただし、設定を指定すると、その設定が、使用中の SSL エンジンによって定義されているデフォルトスイートよりも優先されます。
暗号スイートを設定するには、次のように指定します。
quarkus.tls.cipher-suites=TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA3843.3.2. TLS プロトコルのバージョン
The TLS protocol versions are the list of protocols that can be used during the TLS handshake.
Enabled TLS protocol versions are specified as an ordered list separated by commas.
The relevant configuration property is quarkus.tls.protocols or quarkus.tls.<name>.protocols for named TLS configurations.
For improved security, it defaults to TLSv1.3 unless configured otherwise.
使用可能なオプションは、TLSv1、TLSv1.1、TLSv1.2、TLSv1.3 です。
For example, to enable both TLSv1.3 and TLSv1.2:
quarkus.tls."services-requiring-v1.2".protocols=TLSv1.3,TLSv1.2|
If only certain services require |
3.3.3. ハンドシェイクタイムアウト
TLS 接続が確立されると、ハンドシェイクフェーズが最初のステップになります。 このフェーズでは、クライアントとサーバーは接続を確立するための情報 (通常は暗号スイート、TLS プロトコルバージョン、証明書の検証などが含まれる) を交換します。
ハンドシェイクフェーズのタイムアウトを設定するには、次のように指定します。
quarkus.tls.handshake-timeout=10S # Default.3.3.4. ALPN
Application-Layer Protocol Negotiation (ALPN) は、TLS ハンドシェイク中にクライアントとサーバーが通信に使用するプロトコルをネゴシエートできるようにする TLS エクステンションです。 ALPN は、TLS 接続を確立する前に、クライアントが優先アプリケーションプロトコルをサーバーに指定できるようにすることで、より効率的な通信を可能にします。
This helps in scenarios such as HTTP/2, where multiple protocols can be available, enabling faster protocol selection.
ALPN はデフォルトで有効になっています。
-
無効にするには、次のように指定します。
quarkus.tls.alpn=falseALPN を無効にすることは、エキスパート以外には推奨されません。特に HTTP/2 などのプロトコルで、パフォーマンスの低下、プロトコルネゴシエーションの問題、予期しない動作が発生する可能性があるためです。 ただし、ALPN の無効化は、プロトコルネゴシエーションによって競合が発生する特殊なケースで、固有の不整合を診断したり、パフォーマンスをテストしたりするのに役立ちます。
3.3.5. 証明書失効リスト (CRL)
証明書失効リスト (CRL) は、予定の有効期限より前に発行元の認証局 (CA) によって失効させられたデジタル証明書のリストです。 証明書が侵害されたり、不要になったり、無効と判断されたりした場合、CA は証明書を CRL に追加して、その証明書を信頼しないよう証明書利用者に通知します。
You can configure the CRL to include the list of certificate files you no longer trust in DER or PKCS#7 (P7B) format.
-
DER フォーマットの場合、DER でエンコードされた CRL を渡します。
-
PKCS#7 フォーマットの場合、
SignedDataオブジェクトを渡します。この場合、重要なフィールドはcrlsだけです。
CRL を設定するには、次のように指定します。
quarkus.tls.certificate-revocation-list=ca.crl, ca2.crl3.3.6. すべての証明書とホスト名の検証を信頼する
You can configure your TLS connection to trust all certificates and disable hostname verification. Note that these are two different processes:
-
Trusting all certificates ignores certificate validation, so the client trusts all certificates. This method is useful for testing with self-signed certificates, but do not use it in production.
-
ホスト名の検証は、サーバーのアイデンティティーを検証するプロセスです。
これは中間者攻撃を防ぐのに役立ち、多くの場合、デフォルトで HTTPS または LDAPS に設定されます。
|
これら 2 つのプロパティーは、実稼働環境では使用しないでください。 |
すべての証明書を信頼するには、次のように指定します。
quarkus.tls.trust-all=trueホスト名の検証を無効にするには、次のように指定します。
quarkus.tls.hostname-verification-algorithm=NONE3.3.7. クライアントの再交渉を防ぐ
クライアント開始の再ネゴシエーションにより、クライアントは確立された TLS 接続中に、異なる暗号スイートなどの新しいセッションパラメーターをリクエストできます。 この機能は柔軟性を提供しますが、TLS 1.2 を使用する場合には潜在的なセキュリティーリスクも発生します。
クライアントが新しい TLS ハンドシェイクを開始すると、通常、サーバーはクライアントよりも大幅に多くの CPU リソースを消費します。このリソースの非対称性は、サービス拒否 (DoS) 攻撃を開始するために悪用され、再ネゴシエーションリクエストでサーバーを圧倒する可能性があります。
TLS 1.3 では再ネゴシエーションのサポートが完全に削除され、この潜在的な攻撃ベクトルが事実上閉じられます。
-
TLS 1.2 以前を保護するには、
jdk.tls.rejectClientInitiatedRenegotiationをtrueに設定して、クライアントが開始した再ネゴシエーションを防止します。# JVM mode: java -Djdk.tls.rejectClientInitiatedRenegotiation=true -jar ... # Native mode ./application -Djdk.tls.rejectClientInitiatedRenegotiation=trueQuarkus が提供する
Dockerfileを JVM モードで使用している場合は、JAVA_OPTS_APPEND環境変数にプロパティーを追加することで、再ネゴシエーションを無効化できます。ENV JAVA_OPTS_APPPEND="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Djdk.tls.rejectClientInitiatedRenegotiation=true"
3.4. 設定リファレンス
次の表は、サポートされるプロパティの一覧です:
ビルド時に固定された設定プロパティー。その他の設定プロパティーは、すべて実行時にオーバーライド可能です。
Configuration property |
タイプ |
デフォルト |
|---|---|---|
Set to Environment variable: Show more |
ブーリアン |
|
The order of the key/cert files, based on the names in the By default, Quarkus sorts the key using a lexicographical order. This property allows you to specify the order of the key/cert files. Environment variable: Show more |
list of string |
|
Path to the key store file (P12 / PFX format). Environment variable: Show more |
path |
required |
Password of the key store. When not set, the password must be retrieved from the credential provider. Environment variable: Show more |
string |
|
Alias of the private key and certificate in the key store. Environment variable: Show more |
string |
|
Password of the alias in the key store. If not set, the password will be retrieved from the credential provider. Environment variable: Show more |
string |
|
Provider of the key store. Environment variable: Show more |
string |
|
Path to the keystore file (JKS format). Environment variable: Show more |
path |
required |
Password of the key store. When not set, the password must be retrieved from the credential provider. Environment variable: Show more |
string |
|
Alias of the private key and certificate in the key store. Environment variable: Show more |
string |
|
Password of the alias in the key store. When not set, the password may be retrieved from the credential provider. Environment variable: Show more |
string |
|
Provider of the key store. Environment variable: Show more |
string |
|
Enables Server Name Indication (SNI). 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. This enables a server to present different SSL certificates for multiple domains on a single IP address, facilitating secure communication for virtual hosting scenarios. 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 (configured with the Environment variable: Show more |
ブーリアン |
|
The name of the "credential" bucket (map key → passwords) to retrieve from the A credential provider offers a way to retrieve the key store password as well as alias password. Note that the credential provider is only used if the passwords are not set in the configuration. Environment variable: Show more |
string |
|
The name of the bean providing the credential provider. The name is used to select the credential provider to use. The credential provider must be exposed as a CDI bean and with the If not set, the default credential provider is used. Environment variable: Show more |
string |
|
The key used to retrieve the key store password. If the selected credential provider does not support the key, the password is not retrieved. Otherwise, the retrieved value is used to open the key store. Environment variable: Show more |
string |
|
The key used to retrieve the key store alias password. If the selected credential provider does not contain the key, the alias password is not retrieved. Otherwise, the retrieved value is used to access the alias Environment variable: Show more |
string |
|
List of the trusted cert paths (Pem format). Environment variable: Show more |
list of path |
|
List of the directories with the trusted certificates (Pem format). The configured directory can be empty. Any file in the configured directories will be treated as a trusted certificate in the Pem format. Environment variable: Show more |
list of path |
|
Path to the trust store file (P12 / PFX format). Environment variable: Show more |
path |
required |
Password of the trust store. If not set, the password must be retrieved from the credential provider. Environment variable: Show more |
string |
|
Alias of the trust store. Environment variable: Show more |
string |
|
Provider of the trust store. Environment variable: Show more |
string |
|
Path to the trust store file (JKS format). Environment variable: Show more |
path |
required |
Password of the trust store. If not set, the password must be retrieved from the credential provider. Environment variable: Show more |
string |
|
Alias of the key in the trust store. Environment variable: Show more |
string |
|
Provider of the trust store. Environment variable: Show more |
string |
|
Enforce certificate expiration. When enabled, the certificate expiration date is verified and the certificate (or any certificate in the chain) is rejected if it is expired. Environment variable: Show more |
|
|
The name of the "credential" bucket (map key → passwords) to retrieve from the A credential provider offers a way to retrieve the key store password as well as alias password. Note that the credential provider is only used if the passwords are not set in the configuration. Environment variable: Show more |
string |
|
The name of the bean providing the credential provider. The name is used to select the credential provider to use. The credential provider must be exposed as a CDI bean and with the If not set, the default credential provider is used. Environment variable: Show more |
string |
|
The key used to retrieve the trust store password. If the selected credential provider does not contain the configured key, the password is not retrieved. Otherwise, the retrieved value is used to open the trust store. Environment variable: Show more |
string |
|
Sets the ordered list of enabled cipher suites. If none is given, a reasonable default is selected from the built-in ciphers. When suites are set, it takes precedence over the default suite defined by the Environment variable: Show more |
list of string |
|
Sets the ordered list of enabled TLS protocols. If not set, it defaults to Note that setting an empty list, and enabling TLS is invalid. You must at least have one protocol. Environment variable: Show more |
list of string |
|
The timeout for the TLS handshake phase. If not set, it defaults to 10 seconds. Environment variable: Show more |
|
|
Enables the Application-Layer Protocol Negotiation (ALPN). Application-Layer Protocol Negotiation 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. This helps in scenarios such as HTTP/2 where multiple protocols may be available, allowing for faster protocol selection. Environment variable: Show more |
ブーリアン |
|
Sets the list of revoked certificates (paths to files). A Certificate Revocation List (CRL) is a list of digital 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. 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 Environment variable: Show more |
list of path |
|
If set to This is useful for testing, but should not be used in production. Environment variable: Show more |
ブーリアン |
|
The hostname verification algorithm to use in case the server’s identity should be checked. Should be If set to If not set, the configured extension decides the default algorithm to use. For example, for HTTP, it will be "HTTPS". For TCP, it can depend on the protocol. Nevertheless, it is recommended to set it to "HTTPS" or "LDAPS". Environment variable: Show more |
string |
|
When configured, the server will reload the certificates (from the file system for example) and fires a This property configures the period to reload the certificates. IF not set, the certificates won’t be reloaded automatically. However, the application can still trigger the reload manually using the The fired event is used to notify the application that the certificates have been updated, and thus proceed with the actual switch of certificates. Environment variable: Show more |
||
The path to the key file (in PEM format: PKCS#8, PKCS#1 or encrypted PKCS#8). Environment variable: Show more |
path |
required |
The path to the certificate file (in PEM format). Environment variable: Show more |
path |
required |
When the key is encrypted (encrypted PKCS#8), the password to decrypt it. Environment variable: Show more |
string |
|
The path to the key file (in PEM format: PKCS#8, PKCS#1 or encrypted PKCS#8). Environment variable: Show more |
path |
required |
The path to the certificate file (in PEM format). Environment variable: Show more |
path |
required |
When the key is encrypted (encrypted PKCS#8), the password to decrypt it. Environment variable: Show more |
string |
|
The order of the key/cert files, based on the names in the By default, Quarkus sorts the key using a lexicographical order. This property allows you to specify the order of the key/cert files. Environment variable: Show more |
list of string |
|
Path to the key store file (P12 / PFX format). Environment variable: Show more |
path |
required |
Password of the key store. When not set, the password must be retrieved from the credential provider. Environment variable: Show more |
string |
|
Alias of the private key and certificate in the key store. Environment variable: Show more |
string |
|
Password of the alias in the key store. If not set, the password will be retrieved from the credential provider. Environment variable: Show more |
string |
|
Provider of the key store. Environment variable: Show more |
string |
|
Path to the keystore file (JKS format). Environment variable: Show more |
path |
required |
Password of the key store. When not set, the password must be retrieved from the credential provider. Environment variable: Show more |
string |
|
Alias of the private key and certificate in the key store. Environment variable: Show more |
string |
|
Password of the alias in the key store. When not set, the password may be retrieved from the credential provider. Environment variable: Show more |
string |
|
Provider of the key store. Environment variable: Show more |
string |
|
Enables Server Name Indication (SNI). 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. This enables a server to present different SSL certificates for multiple domains on a single IP address, facilitating secure communication for virtual hosting scenarios. 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 (configured with the Environment variable: Show more |
ブーリアン |
|
The name of the "credential" bucket (map key → passwords) to retrieve from the A credential provider offers a way to retrieve the key store password as well as alias password. Note that the credential provider is only used if the passwords are not set in the configuration. Environment variable: Show more |
string |
|
The name of the bean providing the credential provider. The name is used to select the credential provider to use. The credential provider must be exposed as a CDI bean and with the If not set, the default credential provider is used. Environment variable: Show more |
string |
|
The key used to retrieve the key store password. If the selected credential provider does not support the key, the password is not retrieved. Otherwise, the retrieved value is used to open the key store. Environment variable: Show more |
string |
|
The key used to retrieve the key store alias password. If the selected credential provider does not contain the key, the alias password is not retrieved. Otherwise, the retrieved value is used to access the alias Environment variable: Show more |
string |
|
List of the trusted cert paths (Pem format). Environment variable: Show more |
list of path |
|
List of the directories with the trusted certificates (Pem format). The configured directory can be empty. Any file in the configured directories will be treated as a trusted certificate in the Pem format. Environment variable: Show more |
list of path |
|
Path to the trust store file (P12 / PFX format). Environment variable: Show more |
path |
required |
Password of the trust store. If not set, the password must be retrieved from the credential provider. Environment variable: Show more |
string |
|
Alias of the trust store. Environment variable: Show more |
string |
|
Provider of the trust store. Environment variable: Show more |
string |
|
Path to the trust store file (JKS format). Environment variable: Show more |
path |
required |
Password of the trust store. If not set, the password must be retrieved from the credential provider. Environment variable: Show more |
string |
|
Alias of the key in the trust store. Environment variable: Show more |
string |
|
Provider of the trust store. Environment variable: Show more |
string |
|
Enforce certificate expiration. When enabled, the certificate expiration date is verified and the certificate (or any certificate in the chain) is rejected if it is expired. Environment variable: Show more |
|
|
The name of the "credential" bucket (map key → passwords) to retrieve from the A credential provider offers a way to retrieve the key store password as well as alias password. Note that the credential provider is only used if the passwords are not set in the configuration. Environment variable: Show more |
string |
|
The name of the bean providing the credential provider. The name is used to select the credential provider to use. The credential provider must be exposed as a CDI bean and with the If not set, the default credential provider is used. Environment variable: Show more |
string |
|
The key used to retrieve the trust store password. If the selected credential provider does not contain the configured key, the password is not retrieved. Otherwise, the retrieved value is used to open the trust store. Environment variable: Show more |
string |
|
Sets the ordered list of enabled cipher suites. If none is given, a reasonable default is selected from the built-in ciphers. When suites are set, it takes precedence over the default suite defined by the Environment variable: Show more |
list of string |
|
Sets the ordered list of enabled TLS protocols. If not set, it defaults to Note that setting an empty list, and enabling TLS is invalid. You must at least have one protocol. Environment variable: Show more |
list of string |
|
The timeout for the TLS handshake phase. If not set, it defaults to 10 seconds. Environment variable: Show more |
|
|
Enables the Application-Layer Protocol Negotiation (ALPN). Application-Layer Protocol Negotiation 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. This helps in scenarios such as HTTP/2 where multiple protocols may be available, allowing for faster protocol selection. Environment variable: Show more |
ブーリアン |
|
Sets the list of revoked certificates (paths to files). A Certificate Revocation List (CRL) is a list of digital 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. 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 Environment variable: Show more |
list of path |
|
If set to This is useful for testing, but should not be used in production. Environment variable: Show more |
ブーリアン |
|
The hostname verification algorithm to use in case the server’s identity should be checked. Should be If set to If not set, the configured extension decides the default algorithm to use. For example, for HTTP, it will be "HTTPS". For TCP, it can depend on the protocol. Nevertheless, it is recommended to set it to "HTTPS" or "LDAPS". Environment variable: Show more |
string |
|
When configured, the server will reload the certificates (from the file system for example) and fires a This property configures the period to reload the certificates. IF not set, the certificates won’t be reloaded automatically. However, the application can still trigger the reload manually using the The fired event is used to notify the application that the certificates have been updated, and thus proceed with the actual switch of certificates. Environment variable: Show more |
|
期間フォーマットについて
期間の値を書くには、標準の 数字で始まる簡略化した書式を使うこともできます:
その他の場合は、簡略化されたフォーマットが解析のために
|
4. レジストリー API
エクステンションは自動的に TLS レジストリーを使用します。一方、ユーザーはレジストリー API を介してプログラムで TLS 設定にアクセスすることもできます。
TLS 設定にアクセスするには、TlsConfigurationRegistry Bean を注入します。
get("<NAME>") を呼び出して名前付き TLS 設定を取得するか、getDefault() を呼び出してデフォルト設定を取得します。
@Inject
TlsConfigurationRegistry certificates;
// ...
TlsConfiguration def = certificates.getDefault().orElseThrow();
TlsConfiguration named = certificates.get("name").orElseThrow();
//...TlsConfiguration オブジェクトには、キーストア、トラストストア、暗号スイート、プロトコル、およびその他のプロパティーが含まれています。
また、設定から SSLContext を作成する方法も提供します。
また、TlsConfiguration オブジェクトを使用して、KeyCertOptions、TrustOptions などの Vert.x クライアントまたはサーバーを設定することもできます。
5. エクステンションからの証明書の登録
The following section is only for extension developers. An extension can register a certificate in the TLS registry. This is useful when an extension provides a certificate to the application or provides the certificate in a different format.
エクステンションを使用して TLS レジストリーに証明書を登録するには、プロセッサー エクステンションで、名前と CertificateSupplier で構成される TlsCertificateBuildItem を生成する必要があります。
TlsCertificateBuildItem item = new TlsCertificateBuildItem("named",
new MyCertificateSupplier());証明書サプライヤーは、通常、レコーダーメソッドを使用して取得されるランタイムオブジェクトです。
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);
}
}
}6. 起動時チェック
TLS エクステンションを使用するアプリケーションが起動すると、TLS レジストリーは、設定が正しいことを確認するために、以下に示すいくつかのチェックを実行します。
-
キーストアとトラストストアにアクセスできる。
-
エイリアスがキーストアとトラストストアで使用可能であり、アクセスできる。
-
証明書が有効である。
-
暗号スイートとプロトコルが有効である。
-
証明書失効リスト (CRL) が有効である。
これらのチェックのいずれかが失敗すると、アプリケーションは起動しません。
7. 証明書の再読み込み
TLSConfigurationRegistry から取得された TlsConfiguration には、証明書をリロードするためのメカニズムが含まれています。
reload メソッドは、通常はファイルシステムからキーストア、トラストストア、CRL をリロードして更新します。
リロード操作は自動ではなく、手動でトリガーする必要があります。
さらに、TlsConfiguration 実装はリロードをサポートする必要があります (設定された証明書の場合と同様)。
|
reload メソッドは、リロードが成功したかどうかを示す boolean を返します。
true 値は、リロード操作が成功したことを意味しますが、必ずしも証明書が更新されたことを意味するわけではありません。
TlsConfiguration がリロードされた後、この設定を使用するサーバーとクライアントが、新しい証明書を適用するために特定の操作を実行する必要がある場合があります。
The preferred approach for informing clients and servers about the certificate reload is to fire a CDI event of type io.quarkus.tls.CertificateUpdatedEvent.
To do so, inject a CDI event of this type and fire it when a reload occurs.
CertificateUpdatedEvent and reacting to it:// 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
private final io.vertx.core.http.HttpServer server;
public void onCertificateUpdate(@Observes CertificateUpdatedEvent reload) {
if ("name".equals(event.getName())) {
server.updateSSLOptions(reload.tlsConfiguration().getSSLOptions());
// Or update the SSLContext.
}
}7.1. 定期的なリロード
The TLS registry includes a built-in mechanism that periodically checks the file system for changes and reloads certificates.
The reload-period property specifies the interval for reloading certificates and emits a CertificateUpdatedEvent each time certificates are reloaded.
-
定期的な証明書の再読み込みを設定するには、次のように指定します。
quarkus.tls.reload-period=1h quarkus.tls.key-store.pem.0.cert=tls.crt quarkus.tls.key-store.pem.0.key=tls.key -
名前付き設定ごとに、特定のリロード期間を設定できます。
quarkus.tls.http.reload-period=30m quarkus.tls.http.key-store.pem.0.cert=tls.crt quarkus.tls.http.key-store.pem.0.key=tls.key
|
Impacted servers and clients might need to listen to the |
In Quarkus dev mode, when files are touched, the CertificateUpdatedEvent is triggered much more frequently.
|
8. Kubernetes シークレットまたは cert-manager の使用
Kubernetes で実行する場合、Kubernetes シークレットを使用してキーストアとトラストストアを保存できます。
8.1. Kubernetes シークレットの使用
-
以下のシークレットを例として、Kubernetes シークレットを使用するためのキーストアとトラストストアが含まれるシークレットを作成します。
apiVersion: v1 data: tls.crt: ... tls.key: ... kind: Secret metadata: name: my-certs type: kubernetes.io/tls -
シークレットを 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 レジストリーを設定します。
# ... # 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これを定期的なリロードと組み合わせて、証明書が変更されたときに自動的にリロードできるようにします。
8.2. cert-manager の使用
Kubernetes で実行する場合、cert-manager を使用して証明書を自動的に生成および更新できます。 cert-manager は、キーストアとトラストストアが含まらえるシークレットを生成します。 TLS レジストリーの設定は、Kubernetes シークレットを使用する場合と同じです。 生成されたシークレットには次のファイルが含まれます。
-
証明書用の
tls.crt -
秘密鍵用の
tls.key -
CA 証明書用の
ca.crt(必要な場合)-
証明書の自動更新を設定するには、定期的なリロードメカニズムを使用します。
-
# ...
# 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=disabled9. OpenShift 提供証明書の使用
When running your application in OpenShift, you can use the OpenShift serving certificates to generate and renew TLS certificates automatically. The Quarkus TLS registry can use these certificates and Certificate Authority (CA) files to handle HTTPS traffic and securely validate certificates.
9.1. 証明書の取得
OpenShift でサービス証明書を生成するには、既存の Service オブジェクトにアノテーションを付けます。 生成された証明書はシークレットに保存され、Pod にマウントできるようになります。
次のスニペットでは、TLS 証明書を生成するためのアノテーションが付いたサンプルの Service オブジェクトを使用しています。
-
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 -
To generate a certificate, add this annotation to your existing OpenShift
service:oc annotate service hero-service \ service.beta.openshift.io/serving-cert-secret-name=my-tls-secretアノテーション
service.beta.openshift.io/serving-cert-secret-nameは、証明書を生成し、それをmy-tls-secretという名前のシークレットに保存するよう OpenShift に指示します。 -
Deployment 設定を更新して、シークレットを 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: TCP1 シークレットをマウントするボリュームを定義します。 上記で宣言したシークレットと同じ名前を使用します。 2 By using environment variables or configuration files, set up the keystore with the paths to the certificate and private key. This example uses environment variables. OpenShift serving certificates always create the tls.crtandtls.keyfiles.3 コンテナーにシークレットをマウントします。 パスが、設定で使用されているパス (ここでは /etc/tls) と一致していることを確認します。4 HTTPS を提供するポートを設定します。 -
OpenShift によって生成された証明書を使用するようにアプリケーションをデプロイします。 これにより、HTTPS 経由でサービスが利用できるようになります。
|
これにより、Quarkus HTTP サーバーのデフォルトのキーストアが設定され、サーバーが証明書を使用できるようになります。 名前付き設定でこの証明書を使用する方法については、TLS 設定の参照 を参照してください。 |
9.2. 認証局 (CA) を信頼する
サービスが OpenShift によって発行された証明書を使用するようになったら、この証明書を信頼するようにクライアントアプリケーションを設定します。 これを行うには、CA 証明書を保持する ConfigMap を作成し、それをマウントするように Pod を設定します。 次の手順では、Quarkus REST クライアントを例として使用しますが、どのクライアントでも同じ方法が使用されます。
-
まず、CA 証明書を入力する 空 の ConfigMap を定義します。
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 に注入します。 -
ボリュームを追加して Deployment 設定にマウントすることで、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-config1 Mount the ConfigMap volume in the container. Ensure that the mount path matches the path referenced in the configuration. In this example, /deployments/tls.2 ConfigMap をマウントし、CA 証明書を受け取る ConfigMap を参照するためのボリュームを定義します。 -
この CA 証明書を使用するように REST クライアントを設定します。
次のような 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(); }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 that theconfigKeyis configured as well. -
OpenShift によって生成された CA 証明書を信頼するように REST クライアントを設定します。
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 my-service-tlsという名前の TLS 設定を使用して、heroREST クライアントを設定します。2 my-service-tlsTLS 設定、具体的には CA 証明書を含むトラストストアを設定します。 パスが Kubernetes Deployment 設定で使用されているパスと一致していることを確認します。 ファイルの名前は必ずservice-ca.crtになります。
9.3. 証明書の更新
OpenShift は生成した提供証明書を自動的に更新します。 証明書が更新されると、シークレットが新しい証明書と秘密鍵で更新されます。
アプリケーションが新しい証明書を使用するようにするには、Quarkus TLS レジストリーの定期的な再読み込み機能を使用できます。
reload-period プロパティーを設定すると、TLS レジストリーはキーストアとトラストストアの変更を定期的にチェックし、必要に応じて再読み込みします。
quarkus.tls.reload-period=24h-
必要に応じて、シークレットが更新されたときに証明書を再読み込みするカスタムメカニズムを実装します。 詳細は 証明書の再読み込み を参照してください。
10. Quarkus CLI コマンドと開発用認証局
TLS レジストリーは、開発用認証局 (CA) と信頼済み証明書を生成するための Quarkus CLI コマンドを備えています。 これにより、自己署名証明書をローカルで使用する必要がなくなります。
次のスニペットは、2 つのサブコマンドを含む 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)| 1 | これは、Quarkus が独自の認証局として機能し、他の証明書に署名するために使用できるため、ローカル開発に便利です。 |
| 2 | これは、開発中にアプリケーションと外部サービスまたはクライアント間でセキュアな通信を確立するための証明書を作成するときに便利です。 |
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 valid only for development purposes and is trusted only on the local machine.
The generated CA is located in $HOME/.quarkus/quarkus-dev-root-ca.pem, and installed in the system truststore.
10.1. 自己署名証明書と CA 署名証明書の違いについて
TLS を使用して開発する場合、次の 2 種類の証明書を使用できます。
-
Self-signed certificate: The owner signs the certificate with their own key. Clients do not trust this certificate by default. Use this certificate when a Certificate Authority (CA) is not available or when you need a simple setup. It is not suitable for production and is intended only for development.
-
CA-signed certificate: CA, a trusted entity, signs the certificate. Clients trust this certificate by default, and it is the standard choice for production environments.
While you can use a self-signed certificate for local development, it has limitations.
Browsers and tools like curl, wget, and httpie typically do not trust self-signed certificates, so you need to import the CA into your operating system manually.
To avoid this issue, use a development CA to sign certificates and install the CA in the system truststore. This ensures that the system trusts all certificates signed by the CA. Quarkus simplifies the generation of a development CA and the certificates it signs.
10.2. 開発 CA の生成
The development CA is a Certificate Authority that can be used to sign certificates locally. Note that the generated CA is valid only for development purposes and can be trusted only on the local machine.
開発用 CA を生成するには、次のように指定します。
quarkus tls generate-quarkus-ca --install \ (1)
--renew \ (2)
--truststore (3)| 1 | --install は、システムトラストストアに CA をインストールします。
Windows、Mac、Linux (Fedora および Ubuntu) がサポートされています。
ただし、ブラウザーによっては、生成された CA を手動でインポートすることを推奨します。
詳細は、ブラウザーのドキュメントを参照してください。
生成された CA は $HOME/.quarkus/quarkus-dev-root-ca.pem に配置されます。 |
| 2 | --renew は、CA がすでに存在する場合にそれを更新します。
このオプションを使用すると、秘密鍵が変更されます。そのため、CA によって署名された証明書を再生成する必要があります。
CA の有効期限が切れると、--renew オプションを必要とせずに自動的に更新されます。 |
| 3 | --truststore は、CA 証明書を含む PKCS12 トラストストアも生成します。 |
| When installing the certificate, your system might prompt for your password to add it to the system truststore, or display a confirmation dialog on Windows. |
| Windows では、管理者権限を持つターミナルから管理者として実行し、システムのトラストストアに CA をインストールしてください。 |
10.3. 信頼済み (署名済み) 証明書の生成
-
-
Quarkus 開発用 CA をインストールしたら、信頼済み証明書を生成します。 この証明書は Quarkus 開発用 CA によって署名され、システムによって信頼されます。
quarkus tls generate-certificate --name my-certこのコマンドは、Quarkus 開発用 CA によって署名された証明書を生成します。開発用 CA は、適切にインストールまたはインポートされた場合にシステムによって信頼されます。
証明書は
./.certs/に保存されます。 以下の 2 つのファイルが生成されます。
-
-
$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 a 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 replacedThe command also generates a
.envfile alongside the certificate so Quarkus dev mode can detect 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リクエストを発行して Dev UI を開きます。curl https://localhost:8443/hello Hello from Quarkus REST%Quarkus 開発用 CA がインストールされていない場合、Quarkus は自己署名証明書を生成します。
-
10.4. 自己署名証明書の生成
Quarkus Development CA がインストールされている場合でも、自己署名証明書を生成できます。
quarkus tls generate-certificate --name my-cert --self-signedこれにより、Quarkus 開発用 CA によって署名されない自己署名証明書が生成されます。
10.5. Quarkus Development CA のアンインストール
Uninstalling the Quarkus Development CA depends on your OS.
10.5.1. Windows での CA 証明書の削除
-
管理者権限で 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. -
保存されている CA 証明書を削除します。
$Serial_Numberを CA 証明書のシリアル番号に置き換えます。> certutil -delstore -user -v Root $Serial_Number
11. Let’s Encrypt による証明書の自動管理
Let’s Encrypt は、Internet Security Research Group が提供する無料の自動化された認証局です。
Let’s Encrypt uses the Automated Certificate Management Environment (ACME) protocol to support automatic certificate issuance and renewal. To learn more about Let’s Encrypt and ACME, see Let’s Encrypt documentation.
TLS レジストリーエクステンションにより、CLI ACME クライアントは Let’s Encrypt 証明書を発行および更新できるようになります。 アプリケーションは、この TLS レジストリーエクステンションを使用して、ACME プロトコルのチャレンジを解決します。
Follow the steps below to prepare your Quarkus application and automatically update it with new and renewed Let’s Encrypt certificates.
11.1. 要件
-
アプリケーションにアクセスするために使用できる、完全に解決可能な DNS ドメイン名が利用可能であることを確認します。 このドメイン名は、Let’s Encrypt アカウントを作成し、Let’s Encrypt ACME チャレンジに成功してこのドメインを所有していることを証明するために使用できます。 ngrok を使用して Quarkus Let’s Encrypt ACME 機能を試すことができます。詳細は、以下の Testing with ngrok セクションを参照してください。
-
Quarkus HTTPS アプリケーションでは、build-time プロパティーを使用して Let’s Encrypt ACME チャレンジルートを有効にする必要があります。
quarkus.tls.lets-encrypt.enabled=trueThe TLS registry can manage the challenge process from either the main HTTP interface or the management interface. Using a management interface is strongly recommended to let Quarkus deal with the ACME challenge configuration separately from the main application’s deployment and security requirements:
quarkus.tls.lets-encrypt.enabled=true quarkus.management.enabled=true
|
ポート 80
Let’s Encrypt ACME チャレンジでは、アプリケーションがポート また、すべての HTTP リクエストを HTTPS にリダイレクトするために、 |
The primary HTTP interface serves the challenge and is accessible from your DNS domain name.
| アプリケーションはまだ開始しないでください。 |
11.2. アプリケーションの準備
Let’s Encrypt 証明書をリクエストする前に、以下を実行します。
-
アプリケーションの root ディレクトリーに移動します。
-
TLS レジストリー Let’s Encrypt CLI の
prepareコマンドを実行します。quarkus tls lets-encrypt prepare --domain=<domain-dns-name>prepareコマンドは以下を実行します。-
アプリケーションの root ディレクトリーに
.letsencryptフォルダーを作成します。 -
HTTPS リクエストを開始して受け入れるために、前の Let’s Encrypt prerequisites ステップで設定したアプリケーション用の自己署名ドメイン証明書と秘密鍵を作成します。
-
アプリケーションの root ディレクトリーに
.env設定ファイルを作成し、Let’s Encrypt 証明書を取得するまで、自己署名ドメイン証明書と秘密鍵を使用するように設定します。次のスニペットは、生成された
.envファイルの例を示しています。quarkus.tls.key-store.pem.acme.cert=.letsencrypt/lets-encrypt.crt quarkus.tls.key-store.pem.acme.key=.letsencrypt/lets-encrypt.keyquarkus.tls.lets-encrypt.enabledプロパティーとquarkus.management.enabledプロパティーは、アプリケーションの再構築を必要とするビルド時のプロパティーであるため、.envファイルには含まれません。
-
11.3. アプリケーションの起動
-
アプリケーションを起動します。
java -jar quarkus-run.jar-
https://your-domain-name:8443/を使用してアプリケーションエンドポイントにアクセスし (例:https://your-domain-name:8443/hello)、ブラウザーで自己署名証明書を受け入れます。 -
アプリケーションを実行したまま、最初の Let’s Encrypt 証明書をリクエストします。
-
11.4. 証明書の発行
-
アプリケーションディレクトリーから
issue-certificateコマンドを実行して、最初の Let’s Encrypt 証明書を取得します。quarkus tls lets-encrypt issue-certificate \ --domain=<domain-dns-name> \ (1) --email=<your contact email> \ (2) --management-url=https://localhost:9000 (3)1 ドメイン名を設定します。 2 Let’s Encrypt アカウントに問題が発生した場合に Let’s Encrypt が連絡するために使用できるメールアドレスを入力します。 3 ACME チャレンジの処理に使用できるアプリケーション管理 URL を設定します。 Let’s Encrypt prerequisites ステップで管理ルーターを有効にしない場合は、 https://localhost:8443/を使用します。 -
issue-certificateコマンドの処理中に、TLS レジストリー CLI は次のタスクを実行します。-
アプリケーションがチャレンジに対応する準備ができているか確認します。
-
Let’s Encrypt アカウント情報を作成し、記録します。
-
Let’s Encrypt 証明書リクエストを発行します。
-
Quarkus アプリケーションと対話して ACME チャレンジを解決します。
After the
issue-certificatecommand acquires the Let’s Encrypt certificate chain and private key, the TLS registry CLI converts them to PEM format and copies them to the.letsencryptfolder. The TLS registry detects the new certificate and private key and reloads them automatically.
-
-
Access your application’s endpoint again at
https://your-domain-name:8443/. Confirm that the browser shows Let’s Encrypt as the certificate issuer.The
issue-certificatecommand currently creates a Let’s Encrypt account automatically to simplify initial ACME setup. The TLS registry CLI continues to add more support for Let’s Encrypt account management.
11.5. 証明書の更新
証明書の更新は最初の証明書の発行と似ていますが、Issue certificates with Let’s Encrypt ステップで作成された既存アカウントが必要です。
次のコマンドを実行して、Let’s Encrypt 証明書を更新し、ドメインの DNS 名を設定します。
quarkus tls lets-encrypt renew-certificate \
--domain=<domain-dns-name>During this command, the TLS registry CLI reads the Let’s Encrypt account information recorded during the Issue certificates with Let’s Encrypt step, issues a Let’s Encrypt certificate request, and communicates with the Quarkus application to resolve ACME challenges.
After the renew-certificate command renews the Let’s Encrypt certificate chain and private key, the TLS registry CLI converts them to PEM format and copies them to the .letsencrypt folder.
The TLS registry detects the new certificate and private key and reloads them automatically.
11.6. ngrok によるテスト
ngrok provides a secure HTTPS tunnel to an application running on localhost and helps you test HTTPS-based applications.
ngrok provides a simple way to get started with the Quarkus Let’s Encrypt ACME feature.
-
Start testing by reserving a domain in ngrok:
You can reserve the domain by using Quarkiverse ngrok in dev mode or by reserving it directly in the ngrok dashboard. You cannot use the ngrok domain to test the Quarkus Let’s Encrypt ACME feature immediately.
ngrok uses Let’s Encrypt and intercepts ACME challenges that the Quarkus application would otherwise handle.
-
よって、ngrok ドメインから ngrok Let’s Encrypt 証明書ポリシーを削除します。
ngrok api --api-key <YOUR-API-KEY> reserved-domains delete-certificate-management-policy <YOUR-RESERVED-DOMAIN-ID>YOUR-RESERVED-DOMAIN-IDis your reserved domain’s ID, which starts fromrd_; you can find it in the ngrok dashboard domains section. -
Because ngrok only forwards ACME challenges over HTTP, start ngrok with the following command:
ngrok http --domain <YOUR-NGROK-DOMAIN> 8080 --scheme http (1)1 8080は、アプリケーションがリッスンしているローカルホストの HTTP ポートです。 アプリケーションは、ポート80のhttp://YOUR-NGROK-DOMAINからアクセスできますが、ポート8080のローカルマシンにリダイレクトされることに注意してください。 -
ローカルマシンから Quarkus Let’s Encrypt ACME 機能をテストします。
