InterSystems IRIS との通信に TLS を使用するための 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 オブジェクトの使用法

DriverManager では、以下の手順を実行します。

1. Java Properties オブジェクトを作成します。

2. このオブジェクトの各種プロパティに値を設定します。

3. クライアントから 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 の呼び出しを行わないようにします。