Oracle Key VaultクライアントSDKのプログラム構造

5 Oracle Key VaultクライアントSDKのプログラム構造

Oracle Key VaultクライアントSDKのプログラム構造では、プログラムのフロー、タイプ、環境、接続、セッションなどの領域について説明します。

Oracle Key VaultクライアントSDKのプログラム構造について
Oracle Key Vault SDKプログラムのプログラム構造では、Oracle Key VaultクライアントがエンドポイントSDKプログラムを作成するために取り入れるアプローチについて説明します。
Oracle Key Vaultプログラムのフロー
Oracle Key Vaultの一般的なプログラムのフローには、環境ハンドルの作成、接続およびセッションの作成、終了および解放の順に進む処理が含まれます。
Oracle Key Vaultプログラム環境
Oracle Key Vaultプログラム環境は、Oracle Key Vault関数が実行されるエンドポイントのリージョンまたはブロックです。
Oracle Key Vaultプログラム接続
Oracle Key Vaultプログラム接続には、明示的な接続と内在的な接続の2つのタイプがあります。
Oracle Key Vaultプログラム・セッション
Oracle Key Vaultプログラム・セッションには、Oracle Key VaultセッションとOracle Key Vaultコール・セッションの2つのタイプがあります。

親トピック: Oracle Key VaultクライアントSDKの概要

5.1 Oracle Key VaultクライアントSDKのプログラム構造について

Oracle Key Vault SDKプログラムのプログラム構造では、Oracle Key VaultクライアントがエンドポイントSDKプログラムを作成するために取り入れるアプローチについて説明します。

Oracle Key Vault SDK自体は、特定の前提を使用して記述されています。Oracle Key Vaultクライアントは、これらの前提と矛盾しない方法でエンドポイント・プログラムのコードを記述する必要があります。

Oracle Key VaultクライアントSDKは、CおよびJavaのプラットフォームで使用できます。Oracle Key Vault SDKは、プログラミング言語のデータ型、コール規則、構文およびセマンティクスに従っています。

エンドポイントSDKプログラムは、その他のCまたはJavaアプリケーションと同じ方法でコンパイルおよびリンクできます。処理前やコンパイル後の別途のステップは不要です。

エンドポイント・プログラムがOracle Key Vaultサーバーと通信するには、エンドポイントSDKプログラムがプログラムのフローに従っていること、Oracle Key VaultクライアントSDKライブラリをリンクしていること、Oracle Key Vaultプログラムの特徴を理解していることが必要になります。

親トピック: Oracle Key VaultクライアントSDKのプログラム構造

5.2 Oracle Key Vaultプログラムのフロー

Oracle Key Vaultの一般的なプログラムのフローには、環境ハンドルの作成、接続およびセッションの作成、終了および解放の順に進む処理が含まれます。

Oracle Key Vaultプログラムのフローは、フローの構造とフローの記述に必要なKMIP詳細の程度によって分類されます(基本および高度)。

基本的なプログラムのフロー
基本的なプログラムは、KMIPプログラムとシームレスに連携します。
高度なプログラムのフロー
高度なプログラムのフローは、バッチ処理を伴うOracle Key Vaultプログラムおよび詳細なOracle Key Vaultプログラムとして分類できます。

親トピック: Oracle Key VaultクライアントSDKのプログラム構造

5.2.1 基本的なプログラムのフロー

基本的なプログラムは、KMIPプログラムとシームレスに連携します。

基本的なOracle Key Vaultプログラムの特徴は次のとおりです。

Oracle Key Vaultサーバーで広範なKMIP操作(キーまたは資格証明の作成、アクティブ化、取得、登録など)を実行するOracle Key VaultクライアントSDKの関数で構成されます。
クライアントは、関数の使用時に複雑なKMIPの詳細を認識する必要はありません。
KMIP仕様の詳細の取扱いやOracle Key Vaultとの接続の設定などの操作に注意を払うことなく、クライアントがキーの作成やローテーションなどの機能に集中できるようにする関数が含まれています。

基本的なプログラムの長所は次のとおりです。

ユースケース主導型です。
KMIPに依存しません。該当する関数の使用に必要なKMIPの知識はごくわずかです。
短時間でデプロイできます。
簡単に統合できます。

基本的なプログラムの短所は、サポートされないKMIP詳細があることです。

基本的なプログラムのフローの構造は次のとおりです。

Oracle Key Vault環境ハンドルを作成します。
オプションで、トレース情報を構成します。
接続情報を構成します。
オプションで、Oracle Key Vaultプログラム・セッションを設定します。
- Oracle Key Vault操作または関数の引数を作成します(必要な場合)。
- Oracle Key Vaultの操作または関数を実行します。
- Oracle Key Vaultの操作または関数の結果を解釈してから解放します(必要な場合)。
前の手順でOracle Key Vaultプログラム・セッションを確立していた場合はセッションを終了します。
Oracle Key Vault環境ハンドルを解放します。

図5-1 基本的なOracle Key Vaultプログラムのフローチャート

「図5-1 基本的なOracle Key Vaultプログラムのフローチャート」の説明

例5-1 基本的なOracle Key Vaultプログラム

...
OKVEnv  *env = okvEnvCreate(OKV_MEMORY_FUNCTIONS);
okvEnvSetConfig(env, (oratext *)config_file, (oratext *) connection_pwd);
okvEnvSetTrace(env, (oratext *)trace_dir, OKV_TRACE_DEBUG);
okvConnect(env);
okvCreateKey(env, ...,  unique_id, &unique_id_len);
printf("unique identifier %s", unique_id);
okvActivate(env, unique_id);
okvDisconnect(env);
okvDestroy(env, unique_id);
okvEnvFree(&env);
...

親トピック: Oracle Key Vaultプログラムのフロー

5.2.2 高度なプログラムのフロー

高度なプログラムのフローは、バッチ処理を伴うOracle Key Vaultプログラムおよび詳細なOracle Key Vaultプログラムとして分類できます。

バッチ処理を伴うOracle Key Vaultプログラム
オブジェクトの検索やアクティブ化などの多くのKMIP操作は、okvBatchCreate APIを使用してバッチ処理できます。
詳細なOracle Key Vaultプログラム
詳細なOracle Key Vaultプログラムは、KMIPプロトコルで許可されているほとんどのユースケースに対応できます。

親トピック: Oracle Key Vaultプログラムのフロー

5.2.2.1 バッチ処理を伴うOracle Key Vaultプログラム

オブジェクトの検索やアクティブ化などの多くのKMIP操作は、okvBatchCreate APIを使用してバッチ処理できます。

複数のKMIP操作のバッチ処理は、両方の操作のKMIP要求パケットが集約されて、1つのスーパー(バッチ化された) KMIPパケットでOracle Key Vaultサーバーにまとめて送信さされることを意味します。これにより、クライアントSDKとOracle Key Vaultサーバーの間で交換される情報のラウンドトリップが減少します。

バッチ処理を伴うOracle Key Vaultプログラムの構造は次のとおりです。

Oracle Key Vault環境ハンドルを作成します。
オプションで、トレース情報を構成します。
接続情報を構成します。
- オプションで、Oracle Key Vaultプログラム・セッションを設定します。
- バッチ処理を開始します。
  - Oracle Key Vault KMIP TTLV関数の引数を作成します(必要な場合)。
  - Oracle Key Vault関数を作成します。
- バッチ化された操作を実行します。これにより、すべてのOracle Key Vault関数が実行されるようになります。場合によっては、KMIPサーバーから返されたデータを処理することもあります。
  - Oracle Key Vault関数の結果を解釈します(必要な場合)。
- バッチ処理を終了します。
- 前の手順でOracle Key Vaultプログラム・セッションを確立した場合はセッションを終了します。
Oracle Key Vault環境ハンドルを解放します。

バッチ処理を伴うOracle Key Vaultプログラムのフローは、次の図に示すように基本的なプログラム・フローと同じですが、Oracle Key Vault関数の実行部分が異なります。

図5-2 バッチ処理を伴う高度なOracle Key Vaultプログラムのフローチャート

「図5-2 バッチ処理を伴う高度なOracle Key Vaultプログラムのフローチャート」の説明

図5-2 バッチ処理を伴う高度なOracle Key Vaultプログラム

...
OKVEnv  *env = okvEnvCreate(OKV_MEMORY_FUNCTIONS);
okvEnvSetConfig(env, (oratext *)config_file, (oratext *) connection_pwd);
okvEnvSetTrace(env, (oratext *)trace_dir, OKV_TRACE_DEBUG);
okvBatchCreate(env);
okvCreateKey(env, ...,  unique_id, &unique_id_len);
okvActivate(env, (oratext *)NULL);
okvDestroy(env, (oratext *)NULL);
okvBatchExecute(env);
printf("unique identifier %s", unique_id);
okvBatchFree(env);
okvEnvFree(&env);
...

親トピック: 高度なプログラムのフロー

5.2.2.2 詳細なOracle Key Vaultプログラム

詳細なOracle Key Vaultプログラムは、KMIPプロトコルで許可されているほとんどのユースケースに対応できます。

詳細なOracle Key Vaultプログラムは、Oracle Key VaultクライアントSDK関数のセットで構成されます。クライアントは、そのセットによってサーバーに転送されるKMIPパケットの実際の表現であるプログラムを記述できるようになります。そのため、クライアントはKMIPプロトコルについての詳しい知識が必要になります。

基本的なSDKプログラムは、ほとんどの一般的なユースケースに対応します。それよりも複雑な操作やユースケースは、詳細なOracle Key Vaultプログラムを使用することで実行できます。

プログラム構造は、基本的なOracle Key Vaultプログラムの構造とほとんど同じです。ただし、KMIP操作の定義に使用する追加の操作ハンドルがあります。

詳細なOracle Key Vaultプログラムのフローでは、複数のKMIP操作をバッチ処理することもできます。

詳細なOracle Key Vaultプログラムの特徴は次のとおりです。

Oracle Key Vault環境ハンドルを作成します。
オプションで、トレース情報を構成します。
接続情報を構成します。
- オプションで、Oracle Key Vaultプログラム・セッションを構成します。
  - 複数のKMIP操作のためのOracle Key Vault操作配列を作成します。
  - Oracle Key Vault操作のKMIPリクエスト・メッセージを作成します。
  - バッチ・モードなどでOracle Key Vault操作を実行します。
  - Oracle Key Vault操作のKMIPレスポンス・メッセージをアンラップします。
  - Oracle Key Vault操作配列を解放します。
- 前の手順でOracle Key Vaultプログラム・セッションを確立していた場合はセッションを終了します。
Oracle Key Vault環境ハンドルを解放します。

詳細なOracle Key Vaultプログラムのフローは、次の図に示すように基本的なプログラム・フローと同じですが、Oracle Key Vault関数の実行部分が異なります。

図5-3 詳細なOracle Key Vaultプログラムのフローチャート

「図5-3 詳細なOracle Key Vaultプログラムのフローチャート」の説明

例5-3 高度なOracle Key Vault詳細プログラム

...
OKVEnv  *env = okvEnvCreate(OKV_MEMORY_FUNCTIONS);

/* Allocate Operation array for two KMIP operations */  
OKVOps  *ops[2];           
ub4 alg = CRYPTO_ALG_AES;
okvEnvSetConfig(env, (oratext *)config_file, (oratext *) connection_pwd);
okvEnvSetTrace(env, (oratext *)trace_file, OKV_TRACE_DEBUG);

/* First OKV KMIP Operation */
ops[0] = okvOpsCreate(env, OKVOpCreate);
req = okvTTLVGetRequest(env, ops[0]);
okvTTLVAddToObject(env, req, OKVDEF_TAG_OBJ_TYPE, ...);
template = okvTTLVAddToObject(env, req, OKVDEF_TAG_TEMPLATE_ATTR_ST, ..);
attr = okvTTLVAddToObject(env, template, OKVDEF_TAG_ATTR_ST, ...);
okvTTLVAddToObject(env, attr, OKVDEF_TAG_ATTR_NAME, "Cryptographic Algorithm" ...);
okvTTLVAddToObject(env, attr, OKVDEF_TAG_ATTR_INDEX, &ind, ..);
okvTTLVAddToObject(env, attr, OKVDEF_TAG_ATTR_VALUE, &alg, ..);

... so on for crypto algorithm len and crypto mask attributes ...

/* Second OKV KMIP Operation */
ops[1] = okvOpsCreate(env, OKVOpActivate);
req = okvTTLVGetRequest(env, ops[1]);

/* Note KMIP ID for activation is implicit since detailed operations are always batched. */

/* Execute OKV KMIP Operations in Batch mode */
okvOpsExecuteOp(env, ops, 2);

/* Parse the result of the first OKV KMIP Operation */
resp = okvTTLVGetResponse(env, ops[0]);
tagid = okvTTLVGetChild(env, resp, 1, OKVDEF_TAG_ID, 0, &ctag_id_len);
ctag_id = okvTTLVGetValue(tagid);
ctag_id[ctag_id_len] = 0;
printf("\nCreated Key %s", ctag_id);

/* Parse the result of the second OKV KMIP Operation */
resp = okvTTLVGetResponse(env, ops[1]);
tagid = okvTTLVGetChild(env, resp, 0, OKVDEF_TAG_ID, 0, &atag_id_len);
atag_id = okvTTLVGetValue(tagid);
atag_id[atag_id_len] = 0;
printf("\nActivated Key %s", atag_id);

/* Free the two operations */
okvOpsFree(env, &ops[0]);
okvOpsFree(env, &ops[1]);
okvEnvFree(&env);
...

親トピック: 高度なプログラムのフロー

5.3 Oracle Key Vaultプログラム環境

Oracle Key Vaultプログラム環境は、Oracle Key Vault関数が実行されるエンドポイントのリージョンまたはブロックです。

Oracle Key Vaultプログラム環境は、Oracle Key Vault環境ハンドルの初期化によって始まり、このハンドルの解放によって終了します。Oracle Key Vault環境ハンドルの初期化と解放は、異なるエンドポイント・プログラム関数で実行できるため、Oracle Key Vault環境はエンドポイント・プログラムの関数間にわたって存在します。

Oracle Key Vaultプログラム環境は、プロセスまたはスレッドのみに制限されているため、Oracle Key Vault環境はプロセスまたはスレッドの範囲内にのみ存在します。Oracle Key Vault環境ハンドルは、Oracle Key Vault環境の初期化後に分岐したスレッド内またはプロセス内では使用しないでください。分岐したプロセスまたはスレッドには、それぞれに独自のOracle Key Vault環境を設定できます。

親トピック: Oracle Key VaultクライアントSDKのプログラム構造

5.4 Oracle Key Vaultプログラム接続

Oracle Key Vaultプログラム接続には、明示的な接続と内在的な接続の2つのタイプがあります。

明示的な接続: Oracle Key Vaultサーバーに接続するための接続を明示的に構成して、いくつかのOracle Key VaultクライアントSDK操作を実行してから、Oracle Key Vaultサーバーから切断する必要があります。
内在的な接続: 接続を構成して、Oracle Key VaultクライアントSDK関数を実行する必要があります。この関数は、接続を設定し、タスク完了時には接続を終了します。

両者のアプローチの相違点は、エンドポイントのSDKプログラムとOracle Key Vaultサーバーの間の接続を設定する必要がある回数です。この接続はSSL接続であり、パフォーマンス重視のアプリケーションではコストがかかることが明らかになる可能性があります。

接続にアクティビティがない場合、Oracle Key Vaultサーバー接続には2分間のタイムアウトがあります。明示的な接続の場合、接続は切断されたときに自動的にリセットされます。

親トピック: Oracle Key VaultクライアントSDKのプログラム構造

5.5 Oracle Key Vaultプログラム・セッション

Oracle Key Vaultプログラム・セッションには、Oracle Key VaultセッションとOracle Key Vaultコール・セッションの2つのタイプがあります。

Oracle Key Vaultプログラム・セッションは、エンドポイント・プログラムが明示的にOracle Key Vaultサーバーに接続した時点から、明示的にOracle Key Vaultサーバーから切断した時点まで存在します。これは、前の項の最初のケース(明示的な接続)として説明しました。接続が設定されてから切断されるまでのOracle Key Vaultセッションの間に、複数のOracle Key Vault関数コールが存在する場合があります。

前の項で説明した2つ目のケース(内在的な接続)では、1つのOracle Key VaultクライアントSDK関数の実行中にのみ接続が設定されます。この一時的な内部セッションは、Oracle Key Vaultプログラム・コール・セッションまたはOracle Key Vaultコール・セッションと呼ばれます。

一般に、いくつかのKMIP操作が時間内およびプログラム空間内でまとめて実行される場合は、Oracle Key Vaultセッションを設定することをお薦めします。実行する操作が1つか2つで、それらがバッチ化されている場合は、Oracle Key Vaultセッションを明示的に設定する必要はありません。

Oracle Key Vaultプログラム・セッションは、Oracle Key Vaultプログラム環境内に存在します。Oracle Key Vaultプログラム環境内では、複数のOracle Key Vaultセッションがシリアル方式で存在できます。Oracle Key Vaultセッションは、別のOracle Key Vaultセッションに埋め込むことはできません。Oracle Key Vault環境の有効範囲は単一のプロセスまたはスレッドであるため、Oracle Key Vaultセッションもプロセスまたはスレッドに制限されます。

Oracle Key Vaultセッションの定義では、バッチ処理されるものとバッチ処理されないものの両方のOracle Key Vault関数が含まれます。バッチ処理は、Oracle Key Vaultサーバーへのラウンドトリップを削減します。その一方、Oracle Key Vaultセッションは、Oracle Key Vaultサーバーとの接続を繰り返し設定する必要性を少なくします。

親トピック: Oracle Key VaultクライアントSDKのプログラム構造