InterSystems IRIS との通信に TLS を使用するための Java クライアントの構成
Java クライアント・アプリケーションで InterSystems IRIS® データ・プラットフォームと通信するときに TLS が使用されるようにこのアプリケーションを構成できます。この通信はスーパーサーバ経由で行われるため、このスーパーサーバが TLS を使用するように設定する必要があります。詳細は、"TLS を使用するための InterSystems IRIS スーパーサーバの構成" で説明しています。Java クライアントは、JDBC またはオブジェクトのバインディングを使用して実装できます。
TLS を InterSystems IRIS で使用するように Java クライアントのアプリケーションを構成する手順は以下のとおりです。
-
クライアントでキーストアまたはトラストストアが必要であるかどうかを判断します。これは InterSystems IRIS サーバでクライアント認証を要求するかまたは必須とするか、サーバ認証が必須であるか、暗号スウィートが使用されているかどうかなど、いくつかの要因によって変わります。詳細は、“キーストアおよびトラストストアが必要かどうかの判断” を参照してください。
-
これらの機能を提供するためのプロパティを持つ構成ファイルを作成します。詳細は、“クライアント構成の生成” を参照してください。
-
クライアント・アプリケーションのコードで、必要に応じて、クライアント構成の名前を指定します。名前を指定しなかった場合は、既定の構成情報が使用されます。詳細は、“クライアント構成の使用の指定” を参照してください。
キーストアおよびトラストストアが必要かどうかの判断
キーストアは、クライアントの秘密鍵、公開鍵証明書、および認証局 (CA) 情報のリポジトリの役割を果たします。この情報は、(1) InterSystems IRIS サーバによりクライアント認証が要求される場合、または (2) 使用している暗号スウィートによりクライアント・キーのペアが要求される場合に必要です。
-
InterSystems IRIS サーバがクライアント認証を必要としているかどうかは、その InterSystems IRIS インスタンスの “%SuperServer” TLS 構成に関する [SSL/TLS 構成を編集] ページの [相手証明書認証レベル] フィールドに指定されている値によって判断されます。このフィールドの値が [必要] の場合、クライアントには証明書が必要です。[要求] の場合、サーバにより証明書があるかどうかがチェックされます。
-
クライアントとサーバは使用する暗号スウィートについて合意します。この暗号スウィートにより、クライアント証明書、キーのペア、またはこの両方が存在するかどうかが判断されます。有効化されたサーバの暗号スウィートは、その InterSystems IRIS インスタンスの “%SuperServer” TLS 構成に関する [SSL/TLS 構成を編集] ページの [有効な暗号化スウィート] フィールドに指定されている値によって決定されます。クライアントで使用できる暗号スウィートは、使用している Java のバージョンによって異なります。
クライアントが秘密鍵と証明書を持っている場合、これらはクライアントのキーストアに格納されています。このキーストアには、クライアントのルート CA 証明書とすべての中間 CA 証明書を保存できます。クライアントがサーバを認証するには、このサーバのルート CA 証明書と中間 CA 証明書が必要になります。これらは、クライアントのトラストストアに格納するか、またはクライアント証明書情報と共にキーストアに格納することができます。キーストアとトラストストアの詳細は、"Java Secure Socket Extension (JSSE) リファレンスガイドOpens in a new tab" の “キーストアとトラストストア” を参照してください。
クライアント構成の生成
Java クライアントの動作は、その構成で指定されているプロパティの値により異なります。この構成ではこれらの値を “構成ファイル” というファイルから取得します。具体的な値は、構成ファイルの既定値またはその構成固有の値のいずれかです。以下のセクションでは、構成ファイルの機能について説明します。
構成ファイル、構成、プロパティ、値、および既定
各構成ファイルでは、1 つ以上の構成で使用するプロパティの値を指定します。このファイルには、名前と値のペアの形式で、既定値と構成固有の値の両方が記述されています。一般的にこのペアでは、バージョン管理していないプロパティの名前に対しては既定値を指定し、バージョン管理しているプロパティの名前に対しては構成固有の値を指定します。
構成ファイルに記述されている構成定義が 1 つのみの場合、構成側ではバージョン管理していないプロパティを使用できます。ただし、関連付けられた name プロパティを持つことはできません。名前付き構成を使用しない場合は、名前を指定せずに構成を呼び出します (“クライアント構成の使用の指定” および “名前なしでの構成の指定” を参照)。
構成ファイルに複数の構成がある場合は、構成のバージョン番号 n を付加して name.n の形式とした name プロパティを指定することで各構成を定義します。構成のその他のプロパティ名では、name プロパティと同じバージョン番号が使用されます。したがって、名前の形式は propertyname.n となります。ここで、propertyname にはプロパティの名前、n には構成の番号が入ります。
構成ファイル内の定義では、大文字と小文字は区別されます。スペースは自由に使用できます。また、プロパティ定義の順番も自由です。
すべての構成で使用されるプロパティの既定値を指定するには、バージョン管理されていないプロパティ名とその値を次の形式で指定します。
propertyName = propertyValue
例えば、keyStoreType プロパティの既定値を pkcs12 に指定するには、以下の形式とします。
keyStoreType = pkcs12
このプロパティの既定値より優先する値を使用するには、次のようにバージョン管理しているプロパティ名を指定します。
keyStoreType.1 = jceks
1 つの構成ファイルに複数の構成定義がある場合は、そのバージョン番号順に構成を使用する必要があります。クライアント・アプリケーション・コードで参照する構成番号が連続していない場合はエラーになります。例えば、ある構成ファイルにバージョン管理された 3 つの name プロパティ、name.1、name.2、および name.4 があるとします。この場合、name.4 プロパティに関連付けられている構成は作成されず、このプロパティへの参照は失敗し、エラーが表示されます。
Java クライアントの構成プロパティ
以下のようなプロパティがあります。
-
cipherSuites — サポートされている暗号スウィートのコンマ区切りリスト。使用可能な暗号スウィートは、使用しているマシン上の JRE (Java Runtime Environment) によって異なります。TLS ハンドシェイクの実行時に、サーバは、サーバとクライアントの両方でサポートされる最強の暗号スウィートを選択します。(省略可)
-
debug — デバッグ情報を Java system.err ファイルに記録するかどうかを表します。このプロパティには true または false を指定できます (既定値は false)。このプロパティの設定は、例外処理に影響を与えません。(省略可)
-
keyRecoveryPassword — クライアントの秘密鍵へのアクセスに使用されるパスワード。これは秘密鍵のペアと同時に作成されたものです。(秘密鍵がパスワードで保護されていて、アプリケーション・コードが入力パラメータとして秘密鍵に渡されない場合に必須)
-
keyStore — クライアントの秘密鍵と証明書情報を格納するためのファイル。また、キーストアには、一般にトラストストアに関連付けられるコンテンツも格納できます。(省略可)
-
keyStorePassword — キーストアにアクセスするためのパスワード。(キーストアの作成時にパスワードを指定した場合には必須)
-
keyStoreType — キーストア・ファイルの形式が指定されている場合はその形式。(省略可)
サポートされる形式は以下のとおりです。
-
jks — Java KeyStore。Java 独自の形式です。(既定)
-
jceks — Java Cryptography Extension KeyStore 形式。
-
pkcs12 — Public Key Certificate Standard #12 形式。
-
-
logFile — Java がエラーの記録に使用するファイル。(省略可)
-
name — バージョン管理している Java クライアント構成の識別子(各 name プロパティはバージョン管理する必要があります。バージョン管理していない name プロパティは意味がなく、無視されます)。 (省略可)
構成ファイルで指定している構成が 1 つのみで、バージョン管理していないプロパティ名のみを使用している場合、name プロパティは必要ありません (“クライアント構成の使用の指定” を参照)。1 つの構成ファイルで複数の構成を指定する方法についての詳細は、"構成ファイル、構成、プロパティ、値、および既定" を参照してください。
-
protocol — 接続に使用される TLS プロトコルのバージョン。(必須)
サポートされている値には以下のものがあります。
-
TLS — TLS プロトコルの任意のバージョン。TLS ハンドシェイクの実行時に、サポートされている最新バージョンのプロトコルがサーバによって選択されます。(既定)
-
TLSv1 — TLS バージョン 1。
-
TLSv1.1 — TLS バージョン 1.1。
-
TLSv1.2 — TLS バージョン 1.2。
-
TLSv1.3 — TLS バージョン 1.3。
-
-
serverHostNameVerification – 中間者攻撃を防止するために、この接続でサーバのホスト名の検証を実行するかどうか。このプロパティには true または false を指定できます (既定値は false)。(省略可)
-
trustStore — サーバのルート CA 証明書を格納するためのファイル。このファイルには、中間 CA の証明書も保持できます(この情報はキーストアに格納することもできます)。(省略可)
-
trustStorePassword — トラストストアにアクセスするためのパスワード。(キーストアの作成時にパスワードを指定した場合には必須)
-
trustStoreType — トラストストア・ファイルの形式が指定されている場合はその形式。(省略可)
サポートされる形式は以下のとおりです。
-
jks — Java KeyStore。Java 独自の形式です。(既定)
-
jceks — Java Cryptography Extension KeyStore 形式。
-
pkcs12 — Public Key Certificate Standard #12 形式。
-
構成ファイルのサンプル
ここでは、Java クライアントで使用できる構成ファイルの例を示します。
debug = false
logFile = javatls.log
protocol = TLSv1.3
cipherSuites = TLS_AES_256_GCM_SHA384
keyStoreType = JKS
keyStore = keystore.jks
keyRecoveryPassword = <password>
keyStorePassword = <password>
trustStoreType = JKS
trustStore = truststore.jks
trustStorePassword = <password>
trustStoreRecoveryPassword = <password>
name.1 = IRISJavaClient1
keyStorePassword.1 = <password>
keyRecoveryPassword.1 = <password>
trustStorePassword.1 = <password>
trustStoreRecoveryPassword.1 = <password>
name.2 = IRISJavaClient2
protocol.2 = TLS
keyStoreType.2 = pkcs12
keyStore.2 = keystore.p12
keyStorePassword.2 = <password>
trustStore.2 = cjc1.ts
trustStorePassword.2 = <password>
name.3 = IRISJavaClient3
protocol.3 = TLSv1.2
debug.3 = true
cipherSuites.3 = TLS_RSA_WITH_AES_128_CBC_SHA
構成ファイルの名前付け
構成ファイルは、SSLConfig.properties という名前で保存するか、Java 環境変数 com.intersystems.SSLConfigFile の値をファイルの名前に設定します。コードは、現在の作業ディレクトリにあるファイルをチェックします。
クライアント構成の使用の指定
定義された構成は、サーバへの接続時にクライアント・アプリケーション・コードによって呼び出されます。これは、DriverManager オブジェクトまたは IRISDataSource オブジェクトの呼び出しで行うことができます。
DriverManager オブジェクトの使用法
DriverManager では、以下の手順を実行します。
-
Java Properties オブジェクトを作成します。
-
このオブジェクトの各種プロパティに値を設定します。
-
クライアントから InterSystems IRIS サーバへの接続のために、このオブジェクトを Java Connection オブジェクトに渡します。
接続で使用する情報を指定するには、まず構成ファイルから Properties オブジェクトを作成し、これに特定のプロパティの値を設定します。この処理を行うコードを最も簡単な形式で表すと、以下のようになります。
java.util.Properties prop = new java.util.Properties();
prop.put("connection security level", "10");
prop.put("SSL configuration name",configName);
prop.put("key recovery password",keyPassword);
各項目の内容は次のとおりです。
-
接続のセキュリティ・レベル 10 は、クライアントが TLS を使用して接続を保護しようとしていることを表します。
-
configName は、Java クライアント構成の名前を値とする変数です。構成ファイルでは既定値のみを指定し、これらの既定値を 1 つの構成でのみ使用する場合は、この行を記述しないでください。詳細は、次の "名前なしでの構成の指定" を参照してください。
-
keyPassword は、キーストアからクライアントの秘密鍵を抽出するために必要なパスワードです。
Properties オブジェクトが存在し、これに値が指定されると、最後の手順として InterSystems IRIS Java クライアントから InterSystems IRIS サーバへの接続にこのオブジェクトが渡されます。これは、DriverManager.getConnection メソッドへの呼び出しによって行われます。これを呼び出すための形式は次のとおりです。
Connection conn = DriverManager.getConnection(IRISServerAddress, prop);
ここで、IRISServerAddress は InterSystems IRIS サーバのアドレスを表す文字列、prop はこの文字列に渡される Properties オブジェクトです。
この呼び出しに成功すると、TLS で保護された接続が確立されます。通常、このセクションで説明したような呼び出しを含むアプリケーション・コードには、正常終了を確認するためのさまざまなチェック機構や、あらゆるエラーに対する保護が含まれます。InterSystems IRIS Java 接続の使用の詳細は、"InterSystems IRIS での Java JDBC の使用法" を参照してください。
IRISDataSource オブジェクトの使用法
IRISDataSource オブジェクトを使用する際は、オブジェクトを作成し、そのメソッドを呼び出して関連値を設定し、接続を確立します。メソッドは以下のとおりです。
-
setConnectionSecurityLevel — このメソッドは単一の引数 (接続のセキュリティ・レベル 10) を取ります。これは、クライアントが TLS を使用して接続を保護しようとしていることを表します。
-
setSSLConfigurationName — このメソッドは単一の引数 (Java クライアント構成の名前を値とする変数) を取ります。構成ファイルでは既定値のみを指定し、これらの既定値を 1 つの構成でのみ使用する場合は、この行を記述しないでください。詳細は、次の "名前なしでの構成の指定" を参照してください。
-
setKeyRecoveryPassword — このメソッドは単一の引数 (キーストアからクライアントの秘密鍵を抽出するために必要なパスワード) を取ります。
この処理を行うコードを最も簡単な形式で表すと、以下のようになります。
try{
IRISDataSource ds = new IRISDataSource();
ds.setURL("jdbc:IRIS://127.0.0.1:1972/TESTNAMESPACE");
ds.setConnectionSecurityLevel(10);
ds.setSSLConfigurationName(configName);
ds.setKeyRecoveryPassword(keyPassword);
Connection dbconnection = ds.getConnection();
}
プロパティの取得と設定に使用するメソッドの完全なリストは、"JDBC クイック・リファレンス" を参照してください。com.intersystems.jdbc.IRISDataSource の JavaDoc は <install-dir>/dev/java/doc/index.html の下にあります。
名前なしでの構成の指定
構成ファイルに記述されている構成定義が 1 つのみの場合、構成側ではバージョン管理していないプロパティを使用できます。ただし、関連付けられた name プロパティを持つことはできません。
DriverManager オブジェクトを扱う場合、Properties オブジェクトでは構成ファイルにある既定値のみを使用します。このオブジェクトを作成するコードは、“SSL 構成名” キーの値を指定する呼び出しがないという点で通常のオブジェクト作成コードとは異なります。
java.util.Properties prop = new java.util.Properties();
prop.put("connection security level", "10");
prop.put("key recovery password",keyPassword);
IRISDataSource オブジェクトを扱う場合、名前のない構成を指定するには、単に setSSLConfigurationName の呼び出しを行わないようにします。