この章では、アプリケーションの開発時にキーストア・サービスを利用する方法について説明します。
この章では、キーストア・サービスAPIの概要に続いてアプリケーションでサービスを呼び出す際に必要な知識について説明し、サービスの構成方法を説明し、一般的なキーストア操作の例および実行時のキーの取得方法を示します。
この章は、次の項で構成されています。
キーストアは、キーおよび証明書の安全な格納とアクセスに使用します。キーストア・サービスAPIは、キーストアにアクセスして操作を実行するために使用します。
キーストア・サービスの特徴
キーおよび証明書の安全な管理を可能にします。
各種バックエンド・リポジトリでのキーおよび証明書の格納、取得および管理のためのAPIを提供します。
ファイルベース、データベース・ベースおよびLDAPベースのキーストア管理をサポートします。
キーストア・サービスAPIは、次のような重要な機能(作成、更新、削除)を提供します。
キーストアの作成
キーストアの削除
ドメイン・トラスト・ストアへのハンドルの取得
キーストアへのハンドルの取得
キーストアに対する構成済のプロパティの取得
アプリケーション・ストライプ内のキーストアのリストの取得
KeyStore
に対する操作は、キーストア・サービスで使用されるファイングレイン・アクセス制御モデルを実装するKeyStoreAccessPermission
によって保護されます。
アプリケーションがキーストア・サービスと連携するように設計するうえで、次の項目に関する知識が役立ちます。
使用する適切なアプリケーション・ストライプとキーストア名の決定。
Javaセキュリティ・ポリシーのプロビジョニング。
ポリシー・パーミッションは、ファイルベース(system-jazn-data.xml
)またはLDAPベースのポリシー・ストアに設定されます。データのセキュリティを損なわずにアプリケーションの使用を可能にする適切なパーミッションを設定するには、十分な配慮が必要です。
jps-config.xml
でのキーストア・サービスの定義。
jps-config.xml
でのサービス・インスタンスの定義は、構成ファイルをマニュアルで作成する場合のみ必要です。
環境の設定手順。
スタンドアロン・アプリケーションの場合と、Oracle WebLogic Server環境で動作するアプリケーションの場合は手順が異なります。
Oracle Platform Security Servicesキーストア・プロバイダは、サーバーの起動時に設定されます。プロバイダがファイルベースの場合、データはsystem-jazn-data.xml
に格納されます。
キーストア・サービスでは、次のレベルでのキーの保護をサポートしています。
アプリケーション・ストライプ・レベル
キーストア・レベル
特定の<application stripe, keystore, key>
に対するきめ細やかな保護
注意:
|
この項では、キーストア・オブジェクトへのパーミッションの付与に関するガイドラインおよびいくつかの例を紹介します。
注意: この例では、アプリケーションのjarファイル名は |
キーストア・サービスでは、Javaパーミッションを使用して、キーストアまたはキー・オブジェクトにパーミッションを付与します。必要なパーミッションのみを付与して、それ以外は付与しないことを強くお薦めします。
警告: 不要なパーミッション、特にすべてのアプリケーション・ストライプやキーストアにアクセスできるパーミッションを付与することは危険であり、お薦めできません。 |
キーストア・サービスでは、オブジェクトは階層に格納されます。
アプリケーション・ストライプ -> キーストア -> キー/証明書
この例では、特定のアプリケーション・ストライプおよびそのストライプ内の特定のキーストア名に対するパーミッションを付与します。
<jazn-policy> <grant> <grantee> <principals>...</principals> <!-- This is the location of the jar --> <!-- as loaded with the run-time --> <codesource> <url>file:${oracle.deployed.app.dir}/<MyApp>${oracle.deployed.app.ext}</url> </codesource> </grantee> <permissions> <permission> <class>oracle.security.jps.service.keystore. KeyStoreAccessPermission</class> <name>stripeName=keystoreapp,keystoreName=ks1,alias=*</name> <!-- All actions are granted --> <actions>*</actions> </permission> </permissions> </grant> </jazn-policy>
説明:
stripeName
は、これらのパーミッション(ワイルドカード・アクションで示した読取り、書込み、更新および削除パーミッション)を付与するアプリケーション・ストライプの名前(通常はアプリケーション名)です。
keystoreName
は、使用中のキーストア名です。
alias
はキーストア内のキー別名を示します。
注意: ワイルドカードは、すべての別名に対するパーミッションがアプリケーションに付与されることを意味します。 |
この例では、特定のアプリケーション・ストライプ名およびそのすべてのキーストアに対するパーミッションが付与されます。
<jazn-policy> <grant> <grantee> <principals>...</principals> <codesource> <url>file:${oracle.deployed.app.dir}/<MyApp>${oracle.deployed.app.ext}</url> </codesource> </grantee> <permissions> <permission> <class>oracle.security.jps.service.keystore. KeyStoreAccessPermission</class> <name>stripeName=keystoreapp,keystoreName=*,alias=*</name> <!-- Certain actions are explicitly specified --> <!-- Compare to wild-card grant in previous example --> <actions>read,write,update,delete</actions> </permission> </permissions> </grant> </jazn-policy>
この例では、アプリケーション・ストライプ名内の特定のキー別名およびキーストアに対する読取りパーミッションが付与されます。
<jazn-policy>
<grant>
<grantee>
<principals>...</principals>
<codesource>
<url>file:${oracle.deployed.app.dir}/<MyApp>${oracle.deployed.app.ext}</url>
</codesource>
</grantee>
<permissions>
<permission>
<class>oracle.security.jps.service.keystore.
KeyStoreAccessPermission</class>
<name>stripeName=keystoreapp,keystoreName=ks1,alias=orakey</name>
<actions>read</actions>
</permission>
</permissions>
</grant>
</jazn-policy>
キーストアの場所とプロバイダ・クラスに関する情報が含まれている構成ファイル内で、キーストア・サービス・インスタンスを定義する必要があります。構成ファイルは、次の場所にあります。
$DOMAIN_HOME/config/fmwconfig
名前は次のとおりです。
jps-config.xml
(Oracle WebLogic Serverの場合)
jps-config-jse.xml
(Java SEの場合)
キーストア・サービスは、Oracle WebLogic Server内またはスタンドアロン環境で使用できます。
Java SEアプリケーションでキーストア・サービスAPIを使用するには、次の手順を実行します。
クラスパスを設定します。jps-manifest.jar
ファイルがそのクラスパスに入っていることを確認します。詳細は、第1.5.3項「シナリオ3: Java SEアプリケーションの保護」の「クラスパスで指定する必要のあるJAR」を参照してください。
ポリシーを設定します。キーストア・サービスAPIにアクセスできるようにするには、参照ポリシー・ストアでアクセス・パーミッションを構成する必要があります。例は、第27.3項「Javaセキュリティ・ポリシーのパーミッションの設定」を参照してください。
JVMコマンド・オプションを設定します。詳細は、次を参照してください。
アプリケーションを実行します。
コマンドライン・オプションは次のとおりです。
-Doracle.security.jps.config
構成ファイルjps-config.xml
へのフル・パスを指定します。通常、domain_home/config/fmwconfig
ディレクトリに存在します。
-Djava.security.policy
OPSS/Oracle WebLogic Serverポリシー・ファイルweblogic.policy
の場所を指定します。通常、wl_home/server/lib
ディレクトリに存在します。
-Dcommon.components.home
Middlewareホームの下にあるoracle_commonディレクトリの場所を指定します。
-Djrf.version
環境で使用されるバージョンの値、11.1.1を指定します。
-Djava.security.debug=all
デバッグに役立ちます。
Java EEアプリケーションでAPIを使用するには、次の手順を実行します。
出荷時、jps-config.xml
ファイルのキーストア・サービス・プロバイダ・セクションは、次のディレクトリに構成されています。
$DOMAIN_HOME/config/fmwconfig
必要に応じて、LDAPストアまたはデータベース・ストアへの再関連付けを行ってください。
ポリシーを設定します。キーストア・サービスAPIにアクセスできるようにするには、参照ポリシー・ストアでアクセス・パーミッションを構成する必要があります。例は、第27.3項「Javaセキュリティ・ポリシーのパーミッションの設定」を参照してください。
Oracle WebLogic Serverを起動します。
アプリケーションをデプロイしてテストします。
この項では、キーストア・サービスAPIの使用例を紹介します。内容は次のとおりです。
次のJavaコードは、一般的なキーストア・サービス操作を示しています。
import oracle.security.jps.JpsContext; import oracle.security.jps.JpsContextFactory; import oracle.security.jps.JpsException; import oracle.security.jps.service.keystore.KeyStoreProperties; import oracle.security.jps.service.keystore.KeyStoreService; import oracle.security.jps.service.keystore.KeyStoreServiceException; import java.security.AccessController; import java.security.PrivilegedAction; public class KeyStoreTest { private static KeyStoreService ks = null; public KeyStoreTest() { super(); } /* * This method performs a non-privileged operation. Either all code * in the call stack must have KeyStoreAccessPermission * OR * the caller must have the KeyStoreAccessPermission only and * invoke this operation in doPrivileged block */ public static void doKeyStoreOperation() { doOperation(); } /* * Since this method performs a privileged operation, only current class or * jar containing this class needs KeyStoreAccessPermission */ public static void doPrivilegedKeyStoreOperation() { AccessController.doPrivileged(new PrivilegedAction<String>() { public String run() { doOperation(); return "done"; } }); } private static void doOperation() { try { ks.deleteKeyStore("keystoreapp", "ks1", null); } catch(KeyStoreServiceException e) { e.printStackTrace(); } public static void main(String args[]) throws Exception { try { new JpsStartup().start(); JpsContext ctx = JpsContextFactory.getContextFactory().getContext(); ks = ctx.getServiceInstance(KeyStoreService.class); // #1 - this call is in a doPrivileged block // #1 - this should succeed. doPrivilegedKeyStoreOperation(); // #2 - this will also pass since granted all application // code necessary permission // NOTE: Since this call is not in a doPrivileged block, // this call would have failed if KeyStoreAccessPermission // wasn't granted to this class. /* doKeyStoreOperation(); */ } catch (JpsException je) { je.printStackTrace(); } } }
この項では、アプリケーションが実行時にキーストア・アーティファクトにアクセスする方法について説明します。内容は次のとおりです。
実行時にキーストアにアクセスしてキーと証明書を取得するには、アプリケーションは最初に、キーストア・サービスからキーストア・ハンドルを取得する必要があります。
このタスクの方法は2つあります。
アプリケーション・ストライプおよびキーストア名を個別のパラメータとして明示的に指定し、ハンドルを取得
アプリケーション・ストライプおよびキーストア名を1つのパラメータとして指定し、ハンドルを取得
アプリケーションはいずれのメソッドも自由に使用できます。いずれのメソッドも、まったく同じ方法でキーおよび証明書を取得する動作をします。唯一の相違はキーストアのロード方法です。メソッド1ではOPSS APIを使用するのに対して、メソッド2ではJDKキーストアAPIを使用します。
次の例では最初のメソッドを示します。ここでは、アプリケーション・ストライプおよびキーストア名は個別のパラメータです。
// First get the KeyStoreService handle from JpsContext JpsContext ctx = JpsContextFactory.getContextFactory().getContext(); KeyStoreService kss = ctx.getServiceInstance(KeyStoreService.class); // Now get the keystore handle from KeyStoreService. There are two ways to // do this: // Method 1: Explicitly specify application stripe and keystore name as // separate parameters. In this example, the last parameter is null since // we are demonstrating a permission-protected keystore. java.security.KeyStore keyStore = kss.getKeyStore("keystoreapp", "ks1", null); // If this keystore is password-protected, provide the keystore password as the // last parameter. // java.security.KeyStore.ProtectionParameter pwd = new java.security.KeyStore.PasswordProtection("password".toCharArray()); // java.security.KeyStore keyStore = kss.getKeyStore("keystoreapp", "ks1", pwd); // Method 2: Specify application stripe and keystore name as one parameter // using KSS URI. The last parameter is the keystore password, which is // set to null in this example due to permission protected keystore. // For password-protected keystore, set it to the keystore password. // Since we are demonstrating Method 1 in this // example, method 2 is commented out // java.security.KeyStore keyStore kss.getKeyStore("kss://keystoreapp/ks1", null); // Now you have a handle to the JDK KeyStore object. Use this handle to get // key(s) and/or certificate(s) // Get the private key or secret key associated with this alias. Pass the // key password as the second parameter. In this case, it is null due to // permission protected keystore. Key key = keyStore.getKey("key-alias", null); // Get the certificate associated with this alias Certificate cert = keyStore.getCertificate("cert-alias");
注意: 次のコードの一部には示されていませんが、 |
次の例では、JDKキーストアURIを使用した、アプリケーション・ストライプおよびキーストア名が1つのパラメータとして指定されるメソッドを示します。
// Create an object with parameters indicating the keystore to be loaded FarmKeyStoreLoadStoreParameter param = new FarmKeyStoreLoadStoreParameter(); param.setAppStripeName("keystoreapp"); param.setKeyStoreName("ks1"); // The password is set to null in this example since it assumes this is a // permission protected keystore. param.setProtectionParameter(null); // If the keystore is password protected, use the following lines instead // java.security.KeyStore.ProtectionParameter pwd = new java.security.KeyStore.PasswordProtection("password".toCharArray()); // param.setProtectionParameter(pwd); // Initialize the keystore object by setting keystore type and provider java.security.KeyStore keyStore = KeyStore.getInstance("KSS", new FarmKeyStoreProvider()); // Load the keystore. There are two ways to do this: // Method 1: Explicitly specify application stripe and keystore name as // separate parameters in param object // keyStore.load(param); // Method 2: Specify application stripe and keystore name as one parameter // using KSS URI. Since we demonstrate method 2, in this // example, method 1 is commented out FarmKeyStoreLoadStoreParameter param = new FarmKeyStoreLoadStoreParameter(); param.setKssUri("kss://keystoreapp/ks1"); param.setProtectionParameter(null); keyStore.load(param); // Now you have a handle to JDK KeyStore object. Use this handle to get // key(s) and/or certificate(s) // Get the private key or secret key associated with this alias Key key = keyStore.getKey("key-alias", null); // Get the certificate associated with this alias Certificate cert = keyStore.getCertificate("cert-alias");
注意: 次のコードの一部には示されていませんが、 |
この例では、ストアから特定のキーストアへのアクセスに必要とされる適切なパーミッションを持つXMLベースのポリシー・ストア・ファイル(system-jazn-data.xml
)を使用して説明しています。このファイルでは、アプリケーション・ストライプとキーストア名の様々な組合せに対するパーミッションを定義します。他の組合せや、ここで定義されたパーミッションを超えたストアへのアクセスは、許可されません。
注意: この権限付与は、 |
ここでは、システム・プロパティprojectsrc.home
はJava SEアプリケーションを格納しているディレクトリを指し示すように設定されており、clientApp.jar
はサブディレクトリdistにあるアプリケーションjarファイルです。
対応するポリシー付与は、次のようになります。
<grant>
<grantee>
<codesource>
<url>file:${projectsrc.home}/dist/clientApp.jar</url>
</codesource>
</grantee>
<permissions>
<permission>
<class>oracle.security.jps.service.keystore.KeyStoreAccessPermission
</class>
<name>stripeName=keystoreapp,keystoreName=ks1,alias=*</name>
<actions>*</actions>
</permission>
</permissions>
</grant>
サンプル構成ファイル(jps-config-jse.xml
)を示します。キーストア・サービスのkeystore.file.path
プロパティは、keystores.xml
ファイルを含むディレクトリを示しています。
注意: 完全な構成ファイルについては、製品に付属しているデフォルトのファイル( |
<jpsConfig> ... <serviceInstances> <serviceInstance name="keystore_file_instance" provider="keystore_file_provider"> <property name="keystore.file.path" value="store" /> <property name="keystore.provider.type" value="file" /> </serviceInstance> </serviceInstances> ... </jpsConfig>
Java SE環境では、次の2つのコールは同等です。
KeyStoreService store = JpsServiceLocator.getServiceLocator().lookup(KeyStoreService.class);
および
KeyStoreService store = JpsContextFactory.getContextFactory().getContext().getServiceInstance
(KeyStoreService.class);
クラスタ環境でストアがファイルベースの場合は、キーストア・サービスAPI上でキーストア・サービスMBean APIを使用して、アプリケーションに対するキーの作成、取得、更新および削除を行います。
ただし、単にキーを読み取るだけの場合は、いずれのAPIも使用できます。