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 設定のみに適用されます。

こちら で詳しく説明されているように、Quarkus のクライアントエクステンション (REST、gRPC など) は、デフォルトの (つまり名前のない) TLS 設定で定義されたプロパティーを無視します。quarkus.tls.trust-all プロパティーが唯一の例外です。

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 です。

スコープを短くすることで、証明書の再読み込み後に作成されたインスタンスが最新の証明書を使用するようにします。

動的クライアントは @Dependent スコープです。動的クライアントは適切なスコープを持つコンポーネントに注入してください。

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

JDK ディストリビューションには通常、$JAVA_HOME/lib/security/cacerts ファイルにトラストストアが含まれています。SunJSSE は、このトラストストアをデフォルトのトラストストアとして使用します。SunJSSE は、Java Secure Socket Extension (JSSE) のデフォルト実装です。

javax.net.ssl.HttpsURLConnection などの Java ランタイムコンポーネントは、SSL および TLS を JSSE に依存しています。

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

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

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

  • それ以外の場合は、$JAVA_HOME/lib/security/jssecacerts および $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 つだけ含まれます。

複数のペアが設定されている場合、設定された証明書と秘密鍵のペアの選択は 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 で暗号化)

暗号化された PKCS#8 秘密鍵の場合、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 設定を指定します。デフォルトの 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. 認証情報プロバイダー

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

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

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

# 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 設定を指定します。デフォルトの 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 プロトコルバージョンは、カンマで区切られた順序付きリストとして指定されます。関連する設定プロパティーは、名前付き TLS 設定の場合、quarkus.tls.protocols または quarkus.tls.<name>.protocols です。セキュリティー向上のため、特に設定しない限り、デフォルトは TLSv1.3 になります。

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

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

quarkus.tls."services-requiring-v1.2".protocols=TLSv1.3,TLSv1.2

特定のサービスのみが TLSv1.2 を必要とする場合は、それらのサービス用に専用の名前付き TLS 設定を構成し、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 に追加して、信頼する当事者にそれを信頼しないよう通知します。

DER または PKCS#7 (P7B) 形式で、信頼しなくなった証明書ファイルのリストを含むように CRL を設定できます。

  • DER 形式の場合は、DER エンコードされた CRL を渡します。

  • PKCS#7 形式の場合は、唯一の重要なフィールドが crls である SignedData オブジェクトを渡します。

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

文字列のリスト

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.pem.cert-dirs

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

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

文字列のリスト

quarkus.tls.protocols

Sets the ordered list of enabled TLS protocols.

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

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

Environment variable: QUARKUS_TLS_PROTOCOLS

Show more

文字列のリスト

TLSv1.3

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

文字列のリスト

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.pem.cert-dirs

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

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

文字列のリスト

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

Sets the ordered list of enabled TLS protocols.

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

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

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__PROTOCOLS

Show more

文字列のリスト

TLSv1.3

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 レジストリーに証明書を登録するには、processor エクステンションが名前と 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 イベントを注入し、再読み込みが発生したときにそれを発生させます。

TLS 設定を手動で再読み込みし、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 HTTP、REST、gRPC、および WebSocket サーバー、ならびに有効な場合は管理インターフェイスに対して自動的に処理されます。クライアント側では、Quarkus REST Client が証明書更新イベントを自動的に処理します。
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 開発用 CA を一度生成してから、この CA によって署名された証明書を生成します。Quarkus 開発用 CA は、ローカルで証明書に署名するために使用できる認証局です。これは開発目的でのみ有効であり、ローカルマシン上でのみ信頼されます。

生成された CA は $HOME/.quarkus/quarkus-dev-root-ca.pem に配置され、システムトラストストアにインストールされます。

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

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

  • 自己署名証明書: 所有者が自身の鍵で証明書に署名します。クライアントはデフォルトでこの証明書を信頼しません。認証局 (CA) が利用できない場合や、簡単なセットアップが必要な場合に使用してください。実稼働環境には適しておらず、開発目的のみを意図しています。

  • CA 署名証明書: 信頼されたエンティティーである CA が証明書に署名します。クライアントはデフォルトでこの証明書を信頼し、実稼働環境では標準的な選択肢となります。

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

この問題を回避するには、開発用 CA を使用して証明書に署名し、その CA をシステムトラストストアにインストールします。これにより、システムは CA によって署名されたすべての証明書を信頼するようになります。Quarkus は、開発用 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 によって署名された証明書を生成します。これは、適切にインストールまたはインポートされていれば、システムによって信頼されます。

      証明書は ./.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 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 を使用して Dev UI を開きます。 https://localhost:8443/q/dev または curl リクエストを発行します。

      curl https://localhost:8443/hello
Hello from Quarkus REST%
      Quarkus 開発用 CA がインストールされていない場合、Quarkus は自己署名証明書を生成します。

10.4. 自己署名証明書の生成

Quarkus 開発用 CA がインストールされている場合でも、自己署名証明書を生成できます。

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

これにより、Quarkus 開発用 CA によって署名されない自己署名証明書が生成されます。

10.5. Quarkus 開発用 CA のアンインストール

Quarkus 開発用 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 アプリケーションでは、ビルド時プロパティーを使用して 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

プライマリー HTTP インターフェイスがチャレンジを提供し、DNS ドメイン名からアクセス可能です。

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

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

Let’s Encrypt 証明書をリクエストする前に。

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

  2. TLS レジストリー Let’s Encrypt CLI の prepare コマンドを実行します。

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

    prepare コマンドは以下を実行します。

    • アプリケーションのルートディレクトリーに .letsencrypt フォルダーを作成します。

    • HTTPS リクエストを開始して受け入れられるように、前の Let’s Encrypt prerequisites ステップで設定したアプリケーション用に自己署名ドメイン証明書と秘密鍵を作成します。

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

    追加のオプションも利用可能です。

      --acme-server-url=<url>         Custom ACME production server URL (default: Let's Encrypt production)
  --acme-staging-server-url=<url> Custom ACME staging server URL (default: Let's Encrypt staging)
  --staging                       Use staging environment (default: false)
  --insecure                      Disable SSL certificate validation for the management endpoint (INSECURE - development/testing only)

    These options allow you to:

    • Use alternative ACME providers such as ZeroSSL or custom ACME servers to issue certificates from different providers.

    • Test with staging environments to avoid rate limits during development.

    • Disable SSL validation for testing with self-signed management certificates (not recommended for production).

      If --staging is set to true, the TLS registry CLI uses the staging server URL, which is either the default Let’s Encrypt staging server or the custom staging server provided with --acme-staging-server-url.

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

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

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

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

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

      issue-certificate コマンドが Let’s Encrypt 証明書チェーンと秘密鍵を取得した後、TLS レジストリー CLI はそれらを PEM 形式に変換し、 .letsencrypt フォルダーにコピーします。TLS レジストリーは新しい証明書と秘密鍵を検出し、自動的に再読み込みします。

  3. https://your-domain-name:8443/ でアプリケーションのエンドポイントに再度アクセスします。ブラウザーに証明書発行者として Let’s Encrypt が表示されていることを確認します。

    初期の ACME セットアップを簡素化するために、 issue-certificate コマンドは現在 Let’s Encrypt アカウントを自動的に作成します。TLS レジストリー CLI は、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> \
  --management-url=https://localhost:9000

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

renew-certificate コマンドが Let’s Encrypt 証明書チェーンと秘密鍵を更新した後、TLS レジストリー CLI はそれらを PEM 形式に変換し、 .letsencrypt フォルダーにコピーします。TLS レジストリーは新しい証明書と秘密鍵を検出し、自動的に再読み込みします。

Additional options are available to support alternative ACME providers:

  --acme-server-url=<url>         Custom ACME production server URL (default: Let's Encrypt production)
  --acme-staging-server-url=<url> Custom ACME staging server URL (default: Let's Encrypt staging)
  --insecure                      Disable SSL certificate validation for the management endpoint (INSECURE - development/testing only)

For example, to renew a certificate from ZeroSSL:

quarkus tls lets-encrypt renew-certificate \
  --domain=<domain-dns-name> \
  --management-url=https://localhost:9000 \
  --acme-server-url=https://acme.zerossl.com/v2/DV90

11.6. Using alternative ACME providers

While Let’s Encrypt is the default ACME provider, you can use other ACME-compatible certificate authorities by specifying custom server URLs. This is useful for:

  • Disaster recovery: Failover to different providers if Let’s Encrypt experiences outages

  • Regional requirements: Use providers that better serve specific geographic regions

  • Organizational policies: Comply with company requirements for specific CAs

  • Testing: Use custom staging servers during development

11.6.1. Supported ACME providers

The following ACME providers are known to work with Quarkus:

プロバイダー Production URL Staging URL

Let’s Encrypt (default)

https://acme-v02.api.letsencrypt.org/directory

https://acme-staging-v02.api.letsencrypt.org/directory

ZeroSSL

https://acme.zerossl.com/v2/DV90

N/A (use Let’s Encrypt staging for testing)

BuyPass Go

https://api.buypass.com/acme/directory

https://api.test4.buypass.no/acme/directory

Google Trust Services

https://dv.acme-v02.api.pki.goog/directory

https://dv.acme-v02.test-api.pki.goog/directory

11.6.2. Example: Using ZeroSSL

To issue a certificate from ZeroSSL instead of Let’s Encrypt:

quarkus tls lets-encrypt issue-certificate \
  --domain=example.com \
  --email=admin@example.com \
  --management-url=https://localhost:9000 \
  --acme-server-url=https://acme.zerossl.com/v2/DV90
Each ACME provider may have different rate limits, account requirements, and supported features. Consult the provider’s documentation before using them in production.

11.7. 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 です。これは 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 または互換性のあるライセンスの下で利用可能です。 CC by 3.0

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

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.