The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Back to Guides
このページを編集

TLS レジストリーリファレンス

TLS レジストリーは、TLS 設定を一元管理する Quarkus エクステンションです。アプリケーション全体のセキュアな接続の管理と保守を容易にします。 TLS 設定を 1 カ所で集中して定義する場合、TLS レジストリーを使用して、アプリケーション内の複数のコンポーネントからこの設定を参照できます。これにより、一貫性が確保され、設定エラーの可能性が軽減されます。

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 設定を受け入れることができます。

デフォルトの TLS 設定は、フォールバック/グローバル設定ではありません。 名前付き TLS 設定 (または TLS バケット) はそれぞれ独自のプロパティーを提供する必要があります。 たとえば、quarkus.tls.reload-period はデフォルトの TLS 設定のみに適用されます。

1.1. HTTP サーバーの HTTPS の設定

クライアントとサーバー間のセキュアな通信を確保するには、多くの場合、クライアントがサーバーの信頼性を検証する必要があります。

  • サーバーは、証明書と秘密鍵を含むキーストアを使用する必要があります。

  • サーバーの証明書を検証するために、クライアントにトラストストアを設定する必要があります。

TLS ハンドシェイク中に、サーバーは証明書を提示し、クライアントはそれを検証します。 これにより、中間者攻撃を防ぎ、データ転送をセキュアに行うことができます。

次のセクションでは、PEM または PKCS12 キーストアタイプを使用して HTTPS を設定する方法を説明します。 さらに、名前付き設定を使用して複数の TLS 設定を一度に指定および管理する方法も説明します。この方法を使用すると、それぞれに個別の設定を定義できます。

キーストアタイプに応じて、次のいずれかの設定例を使用してください。

  • PEM ファイルを使用する場合:

    quarkus.tls.key-store.pem.0.cert=server.crt
quarkus.tls.key-store.pem.0.key=server.key
quarkus.http.insecure-requests=disabled # Reject HTTP requests

  • 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=true

1.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=false

    この設定により、サーバーとクライアントの両方が互いの証明書を検証することで mTLS が有効になり、セキュリティーがさらに強化されます。

2. TLS 設定の参照

TLS レジストリーの使用 で説明されているように、quarkus.tls.<name>.* プロパティーを使用して作成したサンプルの 名前付き 設定を参照するには、次の例に示すように tls-configuration-name プロパティーを使用します。

コア HTTP サーバーの設定例:
# Reference the named configuration
quarkus.http.tls-configuration-name=MY_TLS_CONFIGURATION
gRPC クライアントの設定例:
quarkus.grpc.clients.hello.tls-configuration-name=MY_TLS_CONFIGURATION
SmallRye GraphQL クライアントの設定例:
quarkus.smallrye-graphql-client.my-client.tls-configuration-name=MY_TLS_CONFIGURATION

証明書リロードメカニズムとともに Typesafe GraphQL クライアントを使用する場合 (証明書の再読み込み セクション参照)、Bean のスコープを RequestScoped またはアプリケーションより短い同様のスコープにオーバーライドする必要があります。 これは、デフォルトでは Typesafe クライアントがアプリケーションスコープの Bean であるためです。 スコープを短くすることで、証明書のリロード後に作成されたBean の新しいインスタンスが最新の証明書で設定されます。 動的クライアントは @Dependent スコープであるため、適切なスコープを持つコンポーネントに注入します。

2.1. SunJSSE のデフォルトのトラストストアを参照する

JDK ディストリビューションには通常、$JAVA_HOME/lib/security/cacerts ファイルにトラストストアが含まれています。 このトラストストアは、Java Secure Socket Extension (JSSE) のデフォルト実装である SunJSSE によってデフォルトのトラストストアとして使用されます。 SunJSSE によって提供される SSL/TLS 機能は、javax.net.ssl.HttpsURLConnection などのさまざまな Java Runtime コンポーネントによって活用されます。

Quarkus エクステンションは通常、SunJSSE のデフォルトのトラストストアを尊重しませんが、状況によってはそれを使用することが実用的です。 これは、従来のテクノロジーから移行する場合、または SunJSSE トラストストアがオペレーティングシステム (OS) と同期されている Linux ディストリビューションで実行する場合に適用されます。

SunJSSE トラストストアの使用を簡素化するために、Quarkus TLS レジストリーは、SunJSSE のデフォルトの動作を模倣した javax.net.ssl という名前の TLS 設定を提供します。

  • javax.net.ssl.trustStore システムプロパティーが定義されている場合、その値はトラストストアとして尊重されます。

  • それ以外の場合は、$JAVA_HOME/lib/security/jssecacerts and $JAVA_HOME/lib/security/cacerts のパスがチェックされ、最初の既存のファイルがトラストストアとして使用されます。

  • どちらの条件も満たされない場合は、IllegalStateException がスローされます。

トラストストアを開くためのパスワードは、javax.net.ssl.trustStorePassword システムプロパティーから取得されます。 このプロパティーが設定されていない場合は、デフォルトのパスワード changeit が使用されます。

javax.net.ssl 設定は、以下に示すように、さまざまな *.tls-configuration-name プロパティーの値として使用できます。

gRPC クライアントの設定例:
quarkus.grpc.clients.hello.tls-configuration-name=javax.net.ssl

javax.net.ssl TLS 設定は、カスタマイズもオーバーライドもできません。

3. TLS の設定

TLS 設定には、主にキーストアとトラストストアの管理が含まれます。 具体的な設定は、使用されるフォーマット (PEM、P12、JKS など) により異なります。

次のセクションでは、TLS を設定するために使用できるさまざまなプロパティーを説明します。

3.1. キーストア

キーストアには秘密鍵と証明書が保存されます。 これらは主にサーバー側で使用されますが、mTLS を使用する場合はクライアント側でも使用できます。

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 が有効になっていることを確認してください。

複数の鍵ペアまたは証明書ペアを設定する場合、前の例の store.pem.a と store.pem.b で示されているように、サーバーはデフォルトで設定されたペアを名前の辞書順に実行します。 辞書順が最も下位のペアが最初に実行されます。 これを変更するには、quarkus.tls.key-store.pem.order プロパティーを使用して順序を定義します。 たとえば、quarkus.tls.key-store.pem.order=b,c,a です。

この設定は、最初に指定されたペアをデフォルトとして使用するため、SNI を使用する場合に重要です。

PEM キーストアを使用する場合、次のフォーマットがサポートされます。

  • PKCS#8 秘密鍵 (非暗号化)

  • PKCS#1 RSA 秘密鍵 (非暗号化)

  • 暗号化された PKCS#8 秘密鍵 (AES-128-CBC で暗号化)

後者の場合、quarkus.tls.key-store.pem.password または quarkus.tls.key-store.pem.<name>.password プロパティーは、秘密鍵の複合に使用するパスワードに設定する必要があります。

暗号化された PEM キーストアの設定例: 
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=password

3.1.2. PKCS12 キーストア

PKCS12 キーストアは、証明書と秘密鍵を含む単一のファイルです。

PKCS12 キーストアを設定するには、次のように指定します。

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

.p12 ファイルはパスワードで保護されているため、キーストアを開くにはパスワードを指定する必要があります。

このファイルには、複数の証明書と秘密鍵を含めることができます。 その場合は、次のいずれかの操作を実行してください。

  • 使用する証明書と秘密鍵のエイリアスを指定して設定します。

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

  • または、SNI を使用して適切な証明書と秘密鍵を選択します。 すべてのキーに同じパスワードを使用する必要があることに注意してください。

3.1.3. JKS キーストア

JKS キーストアは、サーバーまたはクライアントの証明書と秘密鍵を含む単一のファイルです。TLS/SSL 接続で認証してセキュアな通信を確立するために使用されます。

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 ファイルはパスワードで保護されているため、キーストアを開くにはパスワードを入力する必要があります。 また、複数の証明書と秘密鍵を含めることもできます。 この場合、次のことが可能です。

  • 使用する証明書と秘密鍵のエイリアスを指定して設定します。

    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. 提供されたキーストア

TLS 設定で使用されるキーストアをより細かく制御する必要がある場合は、io.quarkus.tls.runtime.KeyStoreProvider`インターフェイスを実装する CDI Bean を提供できます。Quarkus は TLS 設定が最初に作成される 場合、および設定が リロード されるたびに、`KeyStoreProvider::getKeyStore を呼び出します。結果として得られるキーストアとオプションは、TlsConfiguration::getKeyStore と TlsConfiguration::getKeyStoreOptions を介して利用できるようになります。

KeyStoreProvider の例
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 KeyStoreProvider インターフェイスを実装する CDI Bean は、@ApplicationScoped、@Singleton、または @Dependent にすることができます。
2 @Identifier 修飾子を使用して、キーストアオプションを提供する名前付き TLS 設定を指定します。修飾子を省略 (または明示的に @Default を使用) して、デフォルトの TLS 設定を指定します。詳細は、TLS 設定の参照 を参照してください。
3 キーストアマテリアルへの実行時アクセスのために、他の CDI Bean を注入できます。

3.1.5. SNI

Server Name Indication (SNI) は、TLS ハンドシェイク中にクライアントが接続を試みるホスト名を指定できるようにする TLS エクステンションです。 SNI を使用すると、サーバーが単一の IP アドレス上の複数のドメインに対して異なる TLS 証明書を提示できるようになります。これにより、仮想ホスティングシナリオでセキュアな通信が容易になります。

SNI を有効にするには、次のように指定します。

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

SNI が有効な場合、クライアントは TLS ハンドシェイク中にサーバー名を示します。これにより、サーバーが適切な証明書を選択できるようになります。

  • PEM ファイルを使用してキーストアを設定する場合は、複数の証明書 (CRT) ファイルと鍵ファイルを提供する必要があります。 CRT は、X.509 証明書ファイルの一般的なファイル拡張子であり、通常は PEM (Privacy-Enhanced Mail) フォーマットです。 このファイルには公開証明書が含まれています。

  • JKS または P12 ファイルを使用してキーストアを設定する場合、サーバーが TLS ハンドシェイク中にクライアントによって提供された SNI ホスト名に基づいて適切な証明書を選択します。 サーバーは、SNI ホスト名を、キーストアに保存されている証明書に設定されているコモンネーム (CN) またはサブジェクト代替名 (SAN) と照合します。 すべてのキーストアとエイリアスのパスワードが同一である必要があります。

3.1.6. 認証情報プロバイダー

設定でキーストアのパスワードとエイリアスのパスワードを渡す代わりに、認証情報プロバイダーを使用できます。

認証情報プロバイダーは、キーストアとエイリアスのパスワードを取得する方法として機能します。 認証情報プロバイダーは、設定でパスワードまたはエイリアスパスワードが設定されていない場合にのみ使用されることに注意してください。

認証情報プロバイダーを設定するには、次のように指定します。

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

3.2.2. PKCS12 トラストストア

PKCS12 トラストストアは、証明書を含む単一のファイルです。 複数の証明書が含まれている場合は、エイリアスを使用して適切な証明書を選択できます。

PKCS12 トラストストアを設定するには、次のように指定します。

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

.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 を介して利用できるようになります。

TrustStoreProvider の例
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 TrustStoreProvider インターフェイスを実装する CDI Bean は、@ApplicationScoped、@Singleton、または @Dependent にすることができます。
2 @Identifier 修飾子を使用して、トラストストアオプションを提供する名前付き TLS 設定を指定します。修飾子を省略 (または明示的に @Default を使用) して、デフォルトの TLS 設定を指定します。詳細は、TLS 設定の参照 を参照してください。
3 トラストストアマテリアルへの実行時アクセスのために、他の CDI Bean を注入できます。

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_SHA384

3.3.2. TLS プロトコルのバージョン

TLS プロトコルバージョンは、TLS ハンドシェイク中に使用できるプロトコルのリストです。 有効な TLS プロトコルバージョンを、コンマ区切りの順序付きリストとして指定します。 関連する設定プロパティー、quarkus.tls.protocols または 名前付き TLS 設定の quarkus.tls.<name>.protocols です。 設定されていない場合は、デフォルトで TLSv1.3, TLSv1.2 になります。

使用可能なオプションは、TLSv1、TLSv1.1、TLSv1.2、TLSv1.3 です。

たとえば TLSv1.3 のみを有効にするには、次のように指定します。

quarkus.tls.protocols=TLSv1.3

3.3.3. ハンドシェイクタイムアウト

TLS 接続が確立されると、ハンドシェイクフェーズが最初のステップになります。 このフェーズでは、クライアントとサーバーは接続を確立するための情報 (通常は暗号スイート、TLS プロトコルバージョン、証明書の検証などが含まれる) を交換します。

ハンドシェイクフェーズのタイムアウトを設定するには、次のように指定します。

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

3.3.4. ALPN

Application-Layer Protocol Negotiation (ALPN) は、TLS ハンドシェイク中にクライアントとサーバーが通信に使用するプロトコルをネゴシエートできるようにする TLS エクステンションです。 ALPN は、TLS 接続を確立する前に、クライアントが優先アプリケーションプロトコルをサーバーに指定できるようにすることで、より効率的な通信を可能にします。

これは、複数のプロトコルが利用できる可能性がある HTTP/2 などのシナリオで役立ち、プロトコルの選択を高速化します。

ALPN はデフォルトで有効になっています。

  • 無効にするには、次のように指定します。

    quarkus.tls.alpn=false

    ALPN を無効にすることは、エキスパート以外には推奨されません。特に HTTP/2 などのプロトコルで、パフォーマンスの低下、プロトコルネゴシエーションの問題、予期しない動作が発生する可能性があるためです。 ただし、ALPN の無効化は、プロトコルネゴシエーションによって競合が発生する特殊なケースで、固有の不整合を診断したり、パフォーマンスをテストしたりするのに役立ちます。

3.3.5. 証明書失効リスト (CRL)

証明書失効リスト (CRL) は、予定の有効期限より前に発行元の認証局 (CA) によって失効させられたデジタル証明書のリストです。 証明書が侵害されたり、不要になったり、無効と判断されたりした場合、CA は証明書を CRL に追加して、その証明書を信頼しないよう証明書利用者に通知します。

CRL は、DER または PKCS#7 (P7B) フォーマットを使用して、信頼できなくなった証明書ファイルのリストで設定できます。

  • DER フォーマットの場合、DER でエンコードされた CRL を渡します。

  • PKCS#7 フォーマットの場合、SignedData オブジェクトを渡します。この場合、重要なフィールドは crls だけです。

CRL を設定するには、次のように指定します。

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

3.3.6. すべての証明書とホスト名の検証を信頼する

すべての証明書を信頼し、ホスト名の検証を無効にするように TLS 接続を設定できます。 これらは 2 つの異なるプロセスであることに注意してください。

  • すべての証明書を信頼すると、証明書の検証が無視されるため、すべての証明書が信頼されます。 この方法は自己署名証明書を使用したテストには便利ですが、実稼働環境では使用しないでください。

  • ホスト名の検証は、サーバーのアイデンティティーを検証するプロセスです。

これは中間者攻撃を防ぐのに役立ち、多くの場合、デフォルトで HTTPS または LDAPS に設定されます。

これら 2 つのプロパティーは、実稼働環境では使用しないでください。

すべての証明書を信頼するには、次のように指定します。

quarkus.tls.trust-all=true

ホスト名の検証を無効にするには、次のように指定します。

quarkus.tls.hostname-verification-algorithm=NONE

3.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=true

    Quarkus が提供する 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

タイプ

デフォルト

quarkus.tls.lets-encrypt.enabled

Set to true to enable let’s encrypt support.

Environment variable: QUARKUS_TLS_LETS_ENCRYPT_ENABLED

Show more

ブーリアン

false

quarkus.tls.key-store.pem.order

The order of the key/cert files, based on the names in the keyCerts map.

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: QUARKUS_TLS_KEY_STORE_PEM_ORDER

Show more

list of string

quarkus.tls.key-store.p12.path

Path to the key store file (P12 / PFX format).

Environment variable: QUARKUS_TLS_KEY_STORE_P12_PATH

Show more

path

required

quarkus.tls.key-store.p12.password

Password of the key store. When not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_KEY_STORE_P12_PASSWORD

Show more

string

quarkus.tls.key-store.p12.alias

Alias of the private key and certificate in the key store.

Environment variable: QUARKUS_TLS_KEY_STORE_P12_ALIAS

Show more

string

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

Password of the alias in the key store. If not set, the password will be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_KEY_STORE_P12_ALIAS_PASSWORD

Show more

string

quarkus.tls.key-store.p12.provider

Provider of the key store.

Environment variable: QUARKUS_TLS_KEY_STORE_P12_PROVIDER

Show more

string

quarkus.tls.key-store.jks.path

Path to the keystore file (JKS format).

Environment variable: QUARKUS_TLS_KEY_STORE_JKS_PATH

Show more

path

required

quarkus.tls.key-store.jks.password

Password of the key store. When not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_KEY_STORE_JKS_PASSWORD

Show more

string

quarkus.tls.key-store.jks.alias

Alias of the private key and certificate in the key store.

Environment variable: QUARKUS_TLS_KEY_STORE_JKS_ALIAS

Show more

string

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

Password of the alias in the key store. When not set, the password may be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_KEY_STORE_JKS_ALIAS_PASSWORD

Show more

string

quarkus.tls.key-store.jks.provider

Provider of the key store.

Environment variable: QUARKUS_TLS_KEY_STORE_JKS_PROVIDER

Show more

string

quarkus.tls.key-store.sni

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 password and alias-password properties. Do not set the alias property.

Environment variable: QUARKUS_TLS_KEY_STORE_SNI

Show more

ブーリアン

false

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

The name of the "credential" bucket (map key → passwords) to retrieve from the io.quarkus.credentials.CredentialsProvider. If not set, the credential provider will not be used.

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: QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_NAME

Show more

string

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

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 @Named annotation set to the configured name to be selected.

If not set, the default credential provider is used.

Environment variable: QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

Show more

string

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

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: QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

Show more

string

password

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

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 private key from the key store.

Environment variable: QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_ALIAS_PASSWORD_KEY

Show more

string

alias-password

quarkus.tls.trust-store.pem.certs

List of the trusted cert paths (Pem format).

Environment variable: QUARKUS_TLS_TRUST_STORE_PEM_CERTS

Show more

list of path

quarkus.tls.trust-store.p12.path

Path to the trust store file (P12 / PFX format).

Environment variable: QUARKUS_TLS_TRUST_STORE_P12_PATH

Show more

path

required

quarkus.tls.trust-store.p12.password

Password of the trust store. If not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_TRUST_STORE_P12_PASSWORD

Show more

string

quarkus.tls.trust-store.p12.alias

Alias of the trust store.

Environment variable: QUARKUS_TLS_TRUST_STORE_P12_ALIAS

Show more

string

quarkus.tls.trust-store.p12.provider

Provider of the trust store.

Environment variable: QUARKUS_TLS_TRUST_STORE_P12_PROVIDER

Show more

string

quarkus.tls.trust-store.jks.path

Path to the trust store file (JKS format).

Environment variable: QUARKUS_TLS_TRUST_STORE_JKS_PATH

Show more

path

required

quarkus.tls.trust-store.jks.password

Password of the trust store. If not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_TRUST_STORE_JKS_PASSWORD

Show more

string

quarkus.tls.trust-store.jks.alias

Alias of the key in the trust store.

Environment variable: QUARKUS_TLS_TRUST_STORE_JKS_ALIAS

Show more

string

quarkus.tls.trust-store.jks.provider

Provider of the trust store.

Environment variable: QUARKUS_TLS_TRUST_STORE_JKS_PROVIDER

Show more

string

quarkus.tls.trust-store.certificate-expiration-policy

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: QUARKUS_TLS_TRUST_STORE_CERTIFICATE_EXPIRATION_POLICY

Show more

ignoreIgnore the expiration date., warnLog a warning when the certificate is expired., rejectReject the certificate if it is expired.

warnLog a warning when the certificate is expired.

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

The name of the "credential" bucket (map key → passwords) to retrieve from the io.quarkus.credentials.CredentialsProvider. If not set, the credential provider will not be used.

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: QUARKUS_TLS_TRUST_STORE_CREDENTIALS_PROVIDER_NAME

Show more

string

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

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 @Named annotation set to the configured name to be selected.

If not set, the default credential provider is used.

Environment variable: QUARKUS_TLS_TRUST_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

Show more

string

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

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: QUARKUS_TLS_TRUST_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

Show more

string

password

quarkus.tls.cipher-suites

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 SSLEngineOptions in use.

Environment variable: QUARKUS_TLS_CIPHER_SUITES

Show more

list of string

quarkus.tls.protocols

Sets the ordered list of enabled TLS protocols.

If not set, it defaults to "TLSv1.3, TLSv1.2". The following list of protocols are supported: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. To only enable TLSv1.3, set the value to to "TLSv1.3".

Note that setting an empty list, and enabling TLS is invalid. You must at least have one protocol.

Also, setting this replaces the default list of protocols.

Environment variable: QUARKUS_TLS_PROTOCOLS

Show more

list of string

TLSv1.3,TLSv1.2

quarkus.tls.handshake-timeout

The timeout for the TLS handshake phase.

If not set, it defaults to 10 seconds.

Environment variable: QUARKUS_TLS_HANDSHAKE_TIMEOUT

Show more

Duration 

10S

quarkus.tls.alpn

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: QUARKUS_TLS_ALPN

Show more

ブーリアン

true

quarkus.tls.certificate-revocation-list

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 SignedData object, with the only significant field being crls.

Environment variable: QUARKUS_TLS_CERTIFICATE_REVOCATION_LIST

Show more

list of path

quarkus.tls.trust-all

If set to true, the server trusts all certificates.

This is useful for testing, but should not be used in production.

Environment variable: QUARKUS_TLS_TRUST_ALL

Show more

ブーリアン

false

quarkus.tls.hostname-verification-algorithm

The hostname verification algorithm to use in case the server’s identity should be checked. Should be HTTPS (default), LDAPS or NONE.

If set to NONE, it does not verify the hostname.

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: QUARKUS_TLS_HOSTNAME_VERIFICATION_ALGORITHM

Show more

string

quarkus.tls.reload-period

When configured, the server will reload the certificates (from the file system for example) and fires a CertificateUpdatedEvent if the reload is successful

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 io.quarkus.tls.TlsConfiguration#reload() method, and then fire the CertificateUpdatedEvent manually.

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: QUARKUS_TLS_RELOAD_PERIOD

Show more

Duration 

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

The path to the key file (in PEM format: PKCS#8, PKCS#1 or encrypted PKCS#8).

Environment variable: QUARKUS_TLS_KEY_STORE_PEM__KEY_CERTS__KEY

Show more

path

required

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

The path to the certificate file (in PEM format).

Environment variable: QUARKUS_TLS_KEY_STORE_PEM__KEY_CERTS__CERT

Show more

path

required

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

When the key is encrypted (encrypted PKCS#8), the password to decrypt it.

Environment variable: QUARKUS_TLS_KEY_STORE_PEM__KEY_CERTS__PASSWORD

Show more

string

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

The path to the key file (in PEM format: PKCS#8, PKCS#1 or encrypted PKCS#8).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_PEM__KEY_CERTS__KEY

Show more

path

required

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

The path to the certificate file (in PEM format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_PEM__KEY_CERTS__CERT

Show more

path

required

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

When the key is encrypted (encrypted PKCS#8), the password to decrypt it.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_PEM__KEY_CERTS__PASSWORD

Show more

string

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

The order of the key/cert files, based on the names in the keyCerts map.

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: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_PEM_ORDER

Show more

list of string

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

Path to the key store file (P12 / PFX format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_PATH

Show more

path

required

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

Password of the key store. When not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_PASSWORD

Show more

string

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

Alias of the private key and certificate in the key store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_ALIAS

Show more

string

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

Password of the alias in the key store. If not set, the password will be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_ALIAS_PASSWORD

Show more

string

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

Provider of the key store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_PROVIDER

Show more

string

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

Path to the keystore file (JKS format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_PATH

Show more

path

required

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

Password of the key store. When not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_PASSWORD

Show more

string

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

Alias of the private key and certificate in the key store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_ALIAS

Show more

string

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

Password of the alias in the key store. When not set, the password may be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_ALIAS_PASSWORD

Show more

string

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

Provider of the key store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_PROVIDER

Show more

string

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

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 password and alias-password properties. Do not set the alias property.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_SNI

Show more

ブーリアン

false

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

The name of the "credential" bucket (map key → passwords) to retrieve from the io.quarkus.credentials.CredentialsProvider. If not set, the credential provider will not be used.

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: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_NAME

Show more

string

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

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 @Named annotation set to the configured name to be selected.

If not set, the default credential provider is used.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

Show more

string

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

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: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

Show more

string

password

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

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 private key from the key store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_ALIAS_PASSWORD_KEY

Show more

string

alias-password

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

List of the trusted cert paths (Pem format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_PEM_CERTS

Show more

list of path

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

Path to the trust store file (P12 / PFX format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_PATH

Show more

path

required

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

Password of the trust store. If not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_PASSWORD

Show more

string

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

Alias of the trust store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_ALIAS

Show more

string

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

Provider of the trust store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_PROVIDER

Show more

string

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

Path to the trust store file (JKS format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_PATH

Show more

path

required

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

Password of the trust store. If not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_PASSWORD

Show more

string

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

Alias of the key in the trust store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_ALIAS

Show more

string

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

Provider of the trust store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_PROVIDER

Show more

string

quarkus.tls."tls-bucket-name".trust-store.certificate-expiration-policy

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: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_CERTIFICATE_EXPIRATION_POLICY

Show more

ignoreIgnore the expiration date., warnLog a warning when the certificate is expired., rejectReject the certificate if it is expired.

warnLog a warning when the certificate is expired.

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

The name of the "credential" bucket (map key → passwords) to retrieve from the io.quarkus.credentials.CredentialsProvider. If not set, the credential provider will not be used.

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: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_CREDENTIALS_PROVIDER_NAME

Show more

string

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

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 @Named annotation set to the configured name to be selected.

If not set, the default credential provider is used.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

Show more

string

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

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: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

Show more

string

password

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

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 SSLEngineOptions in use.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__CIPHER_SUITES

Show more

list of string

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

Sets the ordered list of enabled TLS protocols.

If not set, it defaults to "TLSv1.3, TLSv1.2". The following list of protocols are supported: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. To only enable TLSv1.3, set the value to to "TLSv1.3".

Note that setting an empty list, and enabling TLS is invalid. You must at least have one protocol.

Also, setting this replaces the default list of protocols.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__PROTOCOLS

Show more

list of string

TLSv1.3,TLSv1.2

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

The timeout for the TLS handshake phase.

If not set, it defaults to 10 seconds.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__HANDSHAKE_TIMEOUT

Show more

Duration 

10S

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

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: QUARKUS_TLS__TLS_BUCKET_NAME__ALPN

Show more

ブーリアン

true

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

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 SignedData object, with the only significant field being crls.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__CERTIFICATE_REVOCATION_LIST

Show more

list of path

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

If set to true, the server trusts all certificates.

This is useful for testing, but should not be used in production.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_ALL

Show more

ブーリアン

false

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

The hostname verification algorithm to use in case the server’s identity should be checked. Should be HTTPS (default), LDAPS or NONE.

If set to NONE, it does not verify the hostname.

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: QUARKUS_TLS__TLS_BUCKET_NAME__HOSTNAME_VERIFICATION_ALGORITHM

Show more

string

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

When configured, the server will reload the certificates (from the file system for example) and fires a CertificateUpdatedEvent if the reload is successful

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 io.quarkus.tls.TlsConfiguration#reload() method, and then fire the CertificateUpdatedEvent manually.

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: QUARKUS_TLS__TLS_BUCKET_NAME__RELOAD_PERIOD

Show more

Duration 
期間フォーマットについて

期間の値を書くには、標準の java.time.Duration フォーマットを使います。 詳細は Duration#parse() Java API documentation を参照してください。

数字で始まる簡略化した書式を使うこともできます:

  • 数値のみの場合は、秒単位の時間を表します。

  • 数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます：

  • 数値の後に h 、 m 、 s が続く場合は、その前に PT が付けられます。

  • 数値の後に d が続く場合は、その前に P が付けられます。

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. エクステンションからの証明書の登録

このセクションはエクステンション開発者専用です。 エクステンションは、TLS レジストリーに証明書を登録できます。 これは、エクステンションがアプリケーションに証明書を提供する必要がある場合、または異なるフォーマットを提供する場合に便利です。

エクステンションを使用して 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 がリロードされた後、この設定を使用するサーバーとクライアントが、新しい証明書を適用するために特定の操作を実行する必要がある場合があります。

証明書のリロードについてクライアントとサーバーに通知する方法としては、io.quarkus.tls.CertificateUpdatedEvent タイプの CDI イベントを起動する方法が推奨されます。 これを行うには、このタイプの CDI イベントを注入し、リロードが発生したときにそれを起動します。

  1. 手動で再読み込みをトリガーし、CertificateUpdatedEvent を起動します。

// in the class that performs the reload
@Inject
Event<CertificateUpdatedEvent> event;
@Inject
TlsConfigurationRegistry registry;

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

// In the server (or client) code
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. 定期的なリロード

TLS レジストリーには、ファイルシステムの変更を定期的にチェックし、証明書を再読み込みするためのメカニズムが組み込まれています。 reload-period プロパティーは、証明書をリロードする間隔を指定し、証明書がリロードされるたびに CertificateUpdatedEvent を発行します。

  1. 定期的な証明書の再読み込みを設定するには、次のように指定します。

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

  2. 名前付き設定ごとに、特定のリロード期間を設定できます。

    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

影響を受けるサーバーとクライアントは、新しい証明書を適用するために CertificateUpdatedEvent をリッスンする必要がある場合があります。 これは、Quarkus REST サーバー、gRPC サーバー、WebSocket サーバーなどの Quarkus HTTP サーバー、および管理インターフェイス (有効になっている場合) に対して自動的に実行されます。
Quarkus 開発モードでは、ファイルが変更されると、CertificateUpdatedEvent がより頻繁にトリガーされます。

8. Kubernetes シークレットまたは cert-manager の使用

Kubernetes で実行する場合、Kubernetes シークレットを使用してキーストアとトラストストアを保存できます。

8.1. Kubernetes シークレットの使用

  1. 以下のシークレットを例として、Kubernetes シークレットを使用するためのキーストアとトラストストアが含まれるシークレットを作成します。

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

  2. シークレットを 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

  3. 証明書を使用するように 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 (必要な場合)

    1. 証明書の自動更新を設定するには、定期的なリロードメカニズムを使用します。

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

9. OpenShift 提供証明書の使用

OpenShift でアプリケーションを実行する場合、OpenShift 提供証明書 を使用して、TLS 証明書を自動的に生成および更新できます。 Quarkus TLS レジストリーは、この証明書と認証局 (CA) ファイルを使用して、HTTPS トラフィックを処理し、証明書をセキュアに検証できます。

9.1. 証明書の取得

OpenShift でサービス証明書を生成するには、既存の Service オブジェクトにアノテーションを付けます。 生成された証明書はシークレットに保存され、Pod にマウントできるようになります。

次のスニペットでは、TLS 証明書を生成するためのアノテーションが付いたサンプルの Service オブジェクトを使用しています。

  1. Service オブジェクトの設定を表示します。

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

  2. 証明書を生成するには、すでに作成されている 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 に指示します。

  3. 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: TCP
    1 シークレットをマウントするボリュームを定義します。 上記で宣言したシークレットと同じ名前を使用します。
    2 証明書と秘密鍵へのパスを使用してキーストアを設定します。 これは、環境変数または設定ファイルを使用して設定できます。 この例では環境変数を使用します。 OpenShift 提供証明書は必ず tls.crt ファイルと tls.key ファイルを作成します。
    3 コンテナーにシークレットをマウントします。 パスが、設定で使用されているパス (ここでは /etc/tls) と一致していることを確認します。
    4 HTTPS を提供するポートを設定します。

  4. OpenShift によって生成された証明書を使用するようにアプリケーションをデプロイします。 これにより、HTTPS 経由でサービスが利用できるようになります。

quarkus.tls.key-store.pem.acme.cert および quarkus.tls.key-store.pem.acme.key 変数またはその環境変数バリアントを設定すると、TLS レジストリーがシークレットからの証明書と秘密鍵を使用します。

これにより、Quarkus HTTP サーバーのデフォルトのキーストアが設定され、サーバーが証明書を使用できるようになります。 名前付き設定でこの証明書を使用する方法については、TLS 設定の参照 を参照してください。

9.2. 認証局 (CA) を信頼する

要件

サービスが OpenShift によって発行された証明書を使用するようになったら、この証明書を信頼するようにクライアントアプリケーションを設定します。 これを行うには、CA 証明書を保持する ConfigMap を作成し、それをマウントするように Pod を設定します。 次の手順では、Quarkus REST クライアントを例として使用しますが、どのクライアントでも同じ方法が使用されます。

  1. まず、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 に注入します。

  2. ボリュームを追加して 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-config
    1 ConfigMap をコンテナーにマウントします。 パスが設定で使用されているパスと一致していることを確認します (この例では /deployments/tls)。
    2 ConfigMap をマウントし、CA 証明書を受け取る ConfigMap を参照するためのボリュームを定義します。

  3. この 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 ベース URI と設定鍵を設定します。 名前は、<service-name>.<namespace>.svc フォーマットにします。 そうでない場合、証明書は信頼されません。 configKey も設定されていることを確認してください。

  4. 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 設定を使用して、hero REST クライアントを設定します。
    2 my-service-tls TLS 設定、具体的には CA 証明書を含むトラストストアを設定します。 パスが Kubernetes Deployment 設定で使用されているパスと一致していることを確認します。 ファイルの名前は必ず service-ca.crt になります。

9.3. 証明書の更新

OpenShift は生成した提供証明書を自動的に更新します。 証明書が更新されると、シークレットが新しい証明書と秘密鍵で更新されます。

アプリケーションが新しい証明書を使用するようにするには、Quarkus TLS レジストリーの定期的な再読み込み機能を使用できます。

reload-period プロパティーを設定すると、TLS レジストリーはキーストアとトラストストアの変更を定期的にチェックし、必要に応じて再読み込みします。

quarkus.tls.reload-period=24h

  1. 必要に応じて、シークレットが更新されたときに証明書を再読み込みするカスタムメカニズムを実装します。 詳細は 証明書の再読み込み を参照してください。

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 これは、開発中にアプリケーションと外部サービスまたはクライアント間でセキュアな通信を確立するための証明書を作成するときに便利です。

ほとんどの場合、Quarkus Development CA を一度生成してから、この CA によって署名された証明書を生成します。 Quarkus Development CA は、ローカルで証明書に署名するために使用できる認証局です。 これは開発目的にのみ有効であり、ローカルマシン上でのみ信頼されます。 生成された CA は $HOME/.quarkus/quarkus-dev-root-ca.pem に配置され、システムトラストストアにインストールされます。

10.1. 自己署名証明書と CA 署名証明書の違いについて

TLS を使用して開発する場合、次の 2 種類の証明書を使用できます。

  • 自己署名証明書: この証明書は、それを使用するエンティティーと同じエンティティーによって署名されます。 デフォルトでは信頼されません。 このタイプの証明書は、通常、認証局 (CA) が利用できない場合や、簡単なセットアップが必要な場合に使用されます。 実稼働環境には適しておらず、開発目的でのみ使用する必要があります。

  • CA 署名証明書: 証明書は、信頼済みエンティティーである証明書 CA によって署名されます。 この証明書はデフォルトで信頼されており、実稼働環境での標準的な選択肢です。

ローカル開発には自己署名証明書を使用できますが、制限があります。 通常、curl、wget、httpie などのブラウザーやツールは、自己署名証明書を信頼しないため、オペレーティングシステムに CA を手動でインポートする必要があります。

この問題を回避するには、開発 CA を使用して証明書に署名し、その CA をシステムトラストストアにインストールします。 これにより、システムは CA によって署名されたすべての証明書を信頼するようになります。 Quarkus は、開発 CA とこの CA によって署名される証明書の生成を簡素化します。

10.2. 開発 CA の生成

開発 CA は、ローカルで証明書に署名するために使用できる認証局です。 生成された CA は開発目的でのみ有効であり、ローカルマシン上でのみ信頼できることに注意してください。

開発用 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 トラストストアも生成します。
証明書をインストールするときに、システムのトラストストアに証明書をインストールするためのパスワードの入力を求められたり、Windows のダイアログで確認を求められたりすることがあります。
Windows では、管理者権限を持つターミナルから管理者として実行し、システムのトラストストアに CA をインストールしてください。

10.3. 信頼済み (署名済み) 証明書の生成

要件

  • 開発 CA の生成

    1. 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 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 開発モードがこれらの証明書を認識するようになります。

    1. アプリケーションを開発モードで実行して、これらの証明書を使用します。

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

    2. 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 のアンインストール

システムから Quarkus Development CA をアンインストールする方法は、OS によって異なります。

10.5.1. Windows での CA 証明書の削除

  1. 管理者権限で Powershell ターミナルを使用して、Windows 上の CA 証明書をリスト表示します。

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

  2. 保存されている CA 証明書を削除します。$Serial_Number を CA 証明書のシリアル番号に置き換えます。

    > certutil -delstore -user -v Root $Serial_Number

10.5.2. Linux での CA 証明書の削除

  • Fedora の場合:

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

  • Ubuntu の場合:

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

10.5.3. Mac での CA 証明書の削除

  • Mac の場合:

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

11. Let’s Encrypt による証明書の自動管理

Let’s Encrypt は、Internet Security Research Group が提供する無料の自動化された認証局です。

Let’s Encrypt は、証明書の自動発行と自動更新をサポートするために自動証明書管理環境 (ACME) プロトコル を使用します。 Let’s Encrypt と ACME の詳細は、Let’s Encrypt のドキュメント を参照してください。

TLS レジストリーエクステンションにより、CLI ACME クライアントは Let’s Encrypt 証明書を発行および更新できるようになります。 アプリケーションは、この TLS レジストリーエクステンションを使用して、ACME プロトコルのチャレンジを解決します。

以下のステップに従って、Quarkus アプリケーションを準備し、新しい Let’s Encrypt 証明書と更新された Let’s Encrypt 証明書で自動的に更新します。

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=true

    TLS レジストリーは、メイン HTTP インターフェイスまたは管理インターフェイスのいずれかからチャレンジプロセスを管理できます。 メインアプリケーションのデプロイメントとセキュリティーの要件とは別に、Quarkus が ACME チャレンジ設定を処理できるように、管理インターフェイスを使用することが 強く 推奨されます。

    quarkus.tls.lets-encrypt.enabled=true
quarkus.management.enabled=true
ポート 80

Let’s Encrypt ACME チャレンジでは、アプリケーションがポート 80 (基本的には http://your-dns-name) でアクセスできる必要があります。 ポート 80 がインターネットからアクセス可能であることを確認します。 ホスティングプロバイダーによっては、明示的なセキュリティーポリシーが必要になる場合があります。

また、すべての HTTP リクエストを HTTPS にリダイレクトするために、quarkus.http.insecure-requests を redirect に設定することが推奨されます。 ACME チャレンジは、自己署名証明書と最大で 10 件のリダイレクトを受け入れます。

quarkus.tls.lets-encrypt.enabled=true
quarkus.management.enabled=true
quarkus.http.insecure-requests=redirect

このチャレンジは、DNS ドメイン名からアクセス可能プライマリー HTTP インターフェイスから提供されます。

アプリケーションはまだ開始しないでください。

11.2. アプリケーションの準備

Let’s Encrypt 証明書をリクエストする前に、以下を実行します。

  1. アプリケーションの root ディレクトリーに移動します。

  2. 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.key
      quarkus.tls.lets-encrypt.enabled プロパティーと quarkus.management.enabled プロパティーは、アプリケーションの再構築を必要とするビルド時のプロパティーであるため、.env ファイルには含まれません。

11.3. アプリケーションの起動

  1. アプリケーションを起動します。

    java -jar quarkus-run.jar

    1. https://your-domain-name:8443/ を使用してアプリケーションエンドポイントにアクセスし (例: https://your-domain-name:8443/hello)、ブラウザーで自己署名証明書を受け入れます。

    2. アプリケーションを実行したまま、最初の Let’s Encrypt 証明書をリクエストします。

11.4. 証明書の発行

  1. アプリケーションディレクトリーから 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/ を使用します。

  2. issue-certificate コマンドの処理中に、TLS レジストリー CLI は次のタスクを実行します。

    • アプリケーションがチャレンジに対応する準備ができているか確認します。

    • Let’s Encrypt アカウント情報を作成し、記録します。

    • Let’s Encrypt 証明書リクエストを発行します。

    • Quarkus アプリケーションと対話して ACME チャレンジを解決します。

      Let’s Encrypt 証明書チェーンと秘密鍵が正常に取得されると、それらは PEM フォーマットに変換され、アプリケーションの .letsencrypt フォルダーにコピーされます。 TLS レジストリーには、新しい証明書と秘密鍵の準備ができたことが通知され、それらの自動リロードが実行されます。

  3. https://your-domain-name:8443/ を使用して、アプリケーションのエンドポイントに再度アクセスします。 ブラウザーで、Let’s Encrypt 認証局がドメイン証明書に署名することを確認します。

    現時点では、ユーザーが ACME プロトコルを簡単に開始できるように、issue-certificate コマンドにより暗黙的に Let’s Encrypt アカウントが作成されることに注意してください。 Let’s Encrypt アカウント管理のサポートはさらに今後さらに進化する予定です。

11.5. 証明書の更新

証明書の更新は最初の証明書の発行と似ていますが、Issue certificates with Let’s Encrypt ステップで作成された既存アカウントが必要です。

次のコマンドを実行して、Let’s Encrypt 証明書を更新し、ドメインの DNS 名を設定します。

quarkus tls lets-encrypt renew-certificate \
  --domain=<domain-dns-name>

このコマンドの実行中、TLS レジストリー CLI は Issue certificates with Let’s Encrypt ステップで記録された Let’s Encrypt アカウント情報を読み取り、Let’s Encrypt 証明書リクエストを発行し、ACME チャレンジを解決するために Quarkus アプリケーションと通信します。

Let’s Encrypt 証明書チェーンと秘密鍵が正常に更新されると、それらは PEM フォーマットに変換され、アプリケーションの .letsencrypt フォルダーにコピーされます。 TLS レジストリーには、新しい証明書と秘密鍵の準備ができたことが通知され、それらの自動リロードが実行されます。

11.6. ngrok によるテスト

ngrok を使用すると、ローカルホストで実行されているアプリケーションにセキュアな HTTPS トンネルを提供し、HTTPS ベースのアプリケーションを簡単にテストできるようになります。

ngrok を使用すると、容易に Quarkus Let’s Encrypt ACME 機能を使い始めることができます。

  1. ngrok にドメインを予約するように要求することでテストを開始します。

    開発モードで Quarkiverse ngrok を使用するか、ngrok ダッシュボードで直接予約できます。 残念ながら、ngrok ドメインを使用して Quarkus Let’s Encrypt ACME 機能をすぐにテストすることはできません。 これは、ngrok 自体が Let’s Encrypt を使用し、Quarkus アプリケーションで処理されるはずの ACME チャレンジを傍受するためです。

  2. よって、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-ID は、rd_ で始まる予約済みドメインの ID です。この ID は、 ngrok ダッシュボードドメインセクション で確認できます。

  3. ngrok は ACME チャレンジを HTTP 経由でのみ転送するため、次のコマンドを使用して ngrok を起動します。

    ngrok http --domain <YOUR-NGROK-DOMAIN> 8080 --scheme http (1)
    1 8080 は、アプリケーションがリッスンしているローカルホストの HTTP ポートです。 アプリケーションは、ポート 80 の http://YOUR-NGROK-DOMAIN からアクセスできますが、ポート 8080 のローカルマシンにリダイレクトされることに注意してください。

  4. ローカルマシンから Quarkus Let’s Encrypt ACME 機能をテストします。

関連コンテンツ

同じトピックについて

Quarkusはオープンです。このプロジェクトのすべての依存関係は、Apache Software License 2.0 または互換性のあるライセンスのもとで利用可能です。

このウェブサイトはJekyll で構築され、GitHub Pages にホストされ、完全にオープンソースです。改善したい場合は、ウェブサイトをフォークし、修正してみせてください。

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
CC by 3.0 | Privacy Policy Sponsored by