1. 開発者ガイド
  2. Oracle Key VaultクライアントC SDK APIリファレンス
  3. Oracle Key VaultクライアントSDKのKMIPおよびバッチAPI

10 Oracle Key VaultクライアントSDKのKMIPおよびバッチAPI

SDKのKMIP APIには、キーの作成、キーのアクティブ化、キーへの属性の追加、キーの破棄などの操作に対応する関数が用意されています。そうしたアクティビティは、バッチAPIによってバッチ操作で実行できます。

親トピック: Oracle Key VaultクライアントC SDK APIリファレンス

10.1 Oracle Key VaultクライアントSDKのKMIP API

この項では、KMIP操作のためのOracle Key Vault関数に対応するインタフェースについて説明します。

  • Oracle Key VaultクライアントSDKのKMIP APIについて
    Oracle Key Vault KMIP APIを使用すると、キーおよびシークレット・データの管理などの作業を実行できます。
  • okvActivate
    okvActivateでは、KMIPアクティブ化操作を実装します。
  • okvAddAttribute
    okvAddAttributeでは、KMIP属性追加操作を実装します。
  • okvCreateKey
    okvCreateKeyでは、KMIP対称キー・オブジェクトのKMIP作成操作を実装します。
  • okvDeleteAttribute
    okvDeleteAttributeでは、KMIP属性削除操作を実装します。
  • okvDestroy
    okvDestroyでは、KMIP破棄操作を実装します。
  • okvGetAttributeList
    okvGetAttributeListでは、KMIP属性リスト取得操作を実装します。
  • okvGetAttributes
    okvGetAttributesでは、KMIP属性取得操作を実装します。
  • okvGetKey
    okvGetKeyでは、KMIP対称キー・オブジェクトのKMIP取得操作を実装します。
  • okvGetOpaqueData
    okvGetOpaqueDataでは、KMIP不透明データ・オブジェクトのKMIP取得操作を実装します。
  • okvGetSecretData
    okvGetSecretDataでは、KMIPシークレット・データ・オブジェクトのKMIP取得操作を実装します。
  • okvGetTemplate
    okvGetTemplateでは、KMIPテンプレート・オブジェクトのKMIP取得操作を実装します。
  • okvLocate
    okvLocateでは、KMIP検索操作を実装します。
  • okvModifyAttribute
    okvModifyAttributeでは、KMIP属性変更操作を実装します。
  • okvQueryCapability
    okvQueryCapabilityでは、KMIP問合せ操作を実装します。
  • okvRegKey
    okvRegKeyでは、KMIP対称キー・オブジェクトのKMIP登録操作を実装します。
  • okvRegOpaqueData
    okvRegOpaqueDataでは、KMIP不透明データ・オブジェクトのKMIP登録操作を実装します。
  • okvRegSecretData
    okvRegSecretDataでは、KMIPシークレット・データ・オブジェクトのKMIP登録操作を実装します。
  • okvRegTemplate
    okvRegTemplateでは、KMIPテンプレート・オブジェクトのKMIP登録操作を実装します。
  • okvRekey
    okvRekeyでは、KMIPキー更新操作を実装します。
  • okvRevoke
    okvRevokeでは、KMIP失効操作を実装します。

親トピック: Oracle Key VaultクライアントSDKのKMIPおよびバッチAPI

10.1.1 Oracle Key VaultクライアントSDKのKMIP APIについて

Oracle Key Vault KMIP APIを使用すると、キーおよびシークレット・データの管理などの作業を実行できます。

こうした関数の多くは、入力引数として一意識別子を受け取ります。KMIP v1.1によると、KMIPサーバーが以前のコマンドから単一の一意識別子を判別できる場合は、コマンドがバッチ化されているときの一意識別子はオプションになります。そのため、以前のコマンド(検索など)で、考えられるユースケースに対して1つのみの一意識別子が返されたときに、その後のコマンドでこの一意識別子に対する操作を続ける場合、それ以降のコマンドの一意識別子は省略できます。

一意識別子とその長さがは、KMIP API関数から返されます。一意識別子は、エンドポイント・プログラムでNULL終端する必要があります。

エンドポイント・プログラムでは一意識別子を大きめのバッファで渡すことができるため、大きなバッファ内にある一意識別子の実際のビット数を判断するために長さが使用されます。

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.2 okvActivate

okvActivateでは、KMIPアクティブ化操作を実装します。

カテゴリ

KMIP API

用途

okvActivateでは、KMIPアクティブ化操作を実装します。一意識別子で識別されるKMIPオブジェクトをアクティブ化します。

構文

OKVErrNo okvActivate(OKVEnv *env, oratext *uid);

パラメータ

パラメータ IN/OUT 説明
env IN

Oracle Key Vault環境ハンドル。
uid

IN

一意識別子(バッチ処理の場合はNULLも可)。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

なし。

例

/* Create the KMIP object, say Key for example and get its unique
   identifier as part of its creation in ‘uid’ and then activate
   it as below
*/

okvActivate(env, &uid[0]);

if (okvErrGetNum(env))
{
   printf("Error while activating the object the object\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.3 okvAddAttribute

okvAddAttributeでは、KMIP属性追加操作を実装します。

カテゴリ

KMIP API

用途

okvAddAttributeでは、KMIP属性追加操作を実装します。一意識別子で指定したKMIPオブジェクトに属性を追加します。

構文

OKVErrNo okvAddAttribute(OKVEnv *env, oratext *uid,
                         OKVTTLV **attr);

パラメータ

パラメータ IN/OUT 説明
env IN

Oracle Key Vault環境ハンドル。
uid IN

一意識別子(バッチ処理の場合はNULLも可)。

attr IN

KMIPオブジェクトに追加する属性オブジェクト。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

Oracle Key Vaultサーバーで使用する場合、このAPIには次の例外があります。
  • このAPIを使用して不透明オブジェクトまたはテンプレート・オブジェクトに属性を追加すると、Oracle Key Vaultサーバーで一般的な失敗エラーが発生して、その属性はKMIPオブジェクトに追加されなくなります。回避策として、APIのokvRegOpaqueDataおよびokvRegTemplateを使用することで、その属性を登録時に追加できます。
  • このAPIを使用してオブジェクトに単一インスタンス属性を追加したときに、そのオブジェクトがすでに属性のインスタンスを保持している場合、その属性が上書きされることはありませんが、一般的な失敗エラーがスローされます。属性値の変更には、okvModifyAttribute APIを使用してください。
  • リクエストTTLVで非アクティブ化日より後の保護停止日が渡された場合は、サーバーでエラーが発生することはなく、登録済KMIPオブジェクトに保護停止日が追加されます。
  • このAPIを使用してプロセス開始日を追加すると、サーバーで権限拒否エラーが発生します。回避策として、APIのokvRegKey、okvRegSecretData、okvRegOpaqueDataおよびokvRegTemplateを使用することで、その属性を登録時に追加できます。

例

/* Create the KMIP object, say Key for example and get its unique
   identifier as part of its creation in ‘uid’, we can add an attribute
   to it as shown below */

OKVTTLV *attr_in = (OKVTTLV *)NULL;
OKVTTLV *req = (OKVTTLV *)NULL;
oratext *name_value = (oratext *)"attribute_name";
ub4 name_valuel = strlen("attribute_name");
req = okvEnvGetOpRequestObj(env);
attr_in = okvAddAttributeObject(env, req, OKVAttrName, (ub4) 0);

okvAttrAddName(env, attr_in, name_value, name_valuel, 1);
okvAddAttribute(env, &uid[0], &attr_in);

if (okvErrGetNum(env))
{
   printf("Error while adding Name attribute to the object\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.4 okvCreateKey

okvCreateKeyでは、KMIP対称キー・オブジェクトのKMIP作成操作を実装します。

カテゴリ

KMIP API

用途

okvCreateKeyでは、KMIP対称キー・オブジェクトのKMIP作成操作を実装します。OKVサーバーによって生成された対称キー・オブジェクトの一意識別子は、ouidとして返されます。Oracle Key Vault SDKの一意IDの最大長は、OKV_UNIQUE_ID_MAXLENで定義されます。

構文

OKVErrNo okvCreateKey(OKVEnv *env,
                      OKVType alg, ub4 len, ub4 mask,
                      OKVTTLV *template_names_attrs,
                      oratext *wallet_name, ub4 wallet_namel,
                      oratext *ouid, ub4 *ouidl);

パラメータ

パラメータ IN/OUT 説明

env

IN

Oracle Key Vault環境ハンドル。

alg

IN

対称キー・アルゴリズム。

len

IN

対称キーのキー長。

mask

IN

対称キーの暗号化マスクの使用。

template_names_attrs

 IN テンプレート-属性を形成するテンプレート名または属性。

wallet_name

 IN ウォレット名の値。

wallet_namel

 IN ウォレット名の値の長さ。

ouid

OUT

生成されたキーの一意識別子。

ouidl

OUT

生成されたキーの一意識別子の長さ。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

対称キー・オブジェクトにはKMIP名前属性を追加して、そのオブジェクトが今後識別しやすくなるようにすることをお薦めします。

呼出し側は、この関数から返される一意識別子用にメモリーを割り当てる必要があります。割り当てるメモリーの長さは、一意識別子の長さの引数ouidlで渡されます。返される一意識別子を格納するための十分なメモリーを割り当てる必要があります。

指定したアルゴリズムと特定の用途(暗号化使用方法マスク)に応じて指定した長さの対称キーは、ウォレットwallet_nameが指定されている場合、そのウォレット内に生成されます。指定されていない場合は、デフォルト・ウォレットに生成されます(そのウォレットがエンドポイントに存在する場合)。

例

/* Parameters to create symmetric key */
/* Tag for Cryptographic Algortihm AES */
OKVType  algo = CRYPTO_ALG_AES;

/* Key length 128, because AES keys are 128, 192 or 256 bits in length*/
ub4      key_len = 128;
ub4      usage_mask = CRYPTO_MASK_ENCRYPT | CRYPTO_MASK_DECRYPT;
oratext  uid[OKV_UNIQUE_ID_MAXLEN + 1];
ub4      uidl = sizeof(uid);
OKVTTLV *template = (OKVTTLV *)NULL;
OKVTTLV *attr_in = (OKVTTLV *)NULL;

/* Set up the environment handle 'env' and also the memory and connection
   management as shown in previous sections */
memset(uid, 0, uidl);
template = okvEnvGetOpRequestObj(env);

/* Add name attribute object to template attribute */
attr_in = okvAddAttributeObject(env, template, OKVAttrName, (ub4) 0);
okvAttrAddName(env, attr_in, (oratext *)"My New Key", strlen("My New Key"), 1);
printf("\tCreating a Symmetric key\n");

okvCreateKey(env, algo, key_len, usage_mask, template,
             (oratext *)NULL, (ub4)0, &uid[0], uidl);

if (okvErrGetNum(env))
{
   printf("Error while creating the key\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.5 okvDeleteAttribute

okvDeleteAttributeでは、KMIP属性削除操作を実装します。

カテゴリ

KMIP API

用途

okvDeleteAttributeでは、KMIP属性削除操作を実装します。一意識別子で指定したKMIPオブジェクトから属性名と属性索引で指定した属性を削除します。

構文

OKVErrNo okvDeleteAttribute(OKVEnv *env, oratext *uid,
                            oratext *attr_name,
                            ub4 attr_index,
                            OKVTTLV **attr);

パラメータ

パラメータ IN/OUT 説明
env IN Oracle Key Vault環境ハンドル。
uid IN 一意識別子(バッチ処理の場合はNULLも可)。
attr_name IN

削除する属性の名前。
attr_index IN

削除する属性の索引。
attr OUT

KMIPオブジェクトから削除する属性オブジェクト。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

なし。

例

/* Create the KMIP object, say Key for example and get its unique identifier
   as part of its creation in 'uid'. Add contact information attribute and
   to delete it, it can done as shown below */

OKVTTLV *attr_del = (OKVTTLV *) NULL;
oratext *attr_name = okvGetTextForAttributeNum(OKVAttrContactInfo);

/* Passing Contact Info attribute to be deleted at attribute index 0 */
okvDeleteAttribute(env, &uid[0], attr_name, (ub4)0, &attr_del);

if (okvErrGetNum(env))
{
   printf("Error while deleting the contact info attribute of the object\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.6 okvDestroy

okvDestroyでは、KMIP破棄操作を実装します。

カテゴリ

KMIP API

用途

okvDestroyでは、KMIP破棄操作を実装します。一意識別子で識別されるKMIPオブジェクトを破棄します。

構文

OKVErrNo okvDestroy(OKVEnv *env, oratext *uid);

パラメータ

パラメータ IN/OUT 説明
env IN

Oracle Key Vault環境ハンドル。
uid IN

一意識別子(バッチ処理の場合はNULLも可)。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

なし。

例

/* Create the KMIP object, say Key for example and get its unique
   identifier as part of its creation in 'uid', activate it,
   revoke it and then you can destroy it as below */

okvDestroy(env, &uid[0]);

if (okvErrGetNum(env))
{
   printf("Error while destroying the object\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.7 okvGetAttributeList

okvGetAttributeListでは、KMIP属性リスト取得操作を実装します。

カテゴリ

KMIP API

用途

okvGetAttributeListでは、KMIP属性リスト取得操作を実装します。一意識別子で指定したKMIPオブジェクトの通常属性およびカスタム属性の名前を取得します。

attr_names_countでは、attr_namesに収容できるattr_namesの数を指定します。okvGetAttributeList()は、その数の属性名のみをコピーします。それより多くの属性がある場合は、返されるリクエストでattr_names_countが実際の属性数を格納するように変更されます。

構文

OKVErrNo okvGetAttributeList(OKVEnv *env, oratext *uid,
                             ub4 *attr_names_count, oratext **attr_names);

パラメータ

パラメータ IN/OUT 説明
env IN

Oracle Key Vaultインタフェース環境ハンドル。
uid IN

一意識別子(バッチ処理の場合はNULLも可)。

attr_names_count IN/OUT

取得される属性名の名前の数。
attr_names OUT

取得された属性名の名前。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

取得されたリストは順不同です。

例

/* Create the KMIP object, say Key for example and get its unique identifier
   as part of its creation in 'uid'. Add attributes like say name, contact info
   and then names of these attributes can be retrieved as below */
…
ub4       attr_list_count = 0;
oratext **attr_names = (oratext **)NULL;

printf("\tGetting the count of attributes associated with the key\n");
okvGetAttributeList(env, uid, &attr_list_count, (oratext **)NULL);

if (okvErrGetNum(env))
{
   printf("Error while getting the attribute list count\n");
}

printf("\tGetting the attribute names associated with the key\n");
attr_names = (oratext **)calloc(attr_list_count, sizeof(oratext *));

for (i = 0; i < attr_list_count; i++)
{
   /* Allocate memory to hold attribute names */
   attr_names[i] = (oratext *)calloc(OKV_NAME_MAXLEN,
   sizeof(oratext));
}

okvGetAttributeList(env, uid, &attr_list_count, (oratext **)attr_names);

if (okvErrGetNum(env))
{
   printf("Error while getting the attribute list names\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.8 okvGetAttributes

okvGetAttributesでは、KMIP属性取得操作を実装します。

カテゴリ

KMIP API

用途

okvGetAttributesでは、KMIP属性取得操作を実装します。一意識別子で指定した特定のKMIPオブジェクトについて、通常属性およびカスタム属性の指定したリストを取得します。

構文

OKVErrNo okvGetAttributes(OKVEnv *env, oratext *uid,
                          ub4 attr_names_count,
                          oratext **attr_names,
                          OKVTTLV **attrs);

パラメータ

パラメータ IN/OUT 説明
env IN

Oracle Key Vault環境ハンドル。
uid IN

一意識別子(バッチ処理の場合はNULLも可)。

attr_names_count IN

取得される属性の名前の数。
attr_names IN

取得する属性の名前。
attrs OUT

取得された属性。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

取得されたリストは順不同です。

例

/* Create the KMIP object, say Key for example and get its unique
   identifier as part of its creation in 'uid'. Add contact information
   Name, Cryptographic Alogirthm, Cryptographic Length attributes to the
   created key and then all of these attributes can be retrieved as below */
...
OKVTTLV *attrs = (OKVTTLV *) NULL;
oratext *attr_name_list[3];

attr_name_list[0] = okvGetTextForAttributeNum(OKVAttrName);
attr_name_list[1] = okvGetTextForAttributeNum(OKVAttrCryptoAlg);
attr_name_list[2] = okvGetTextForAttributeNum(OKVAttrCryptoLen);

okvGetAttributes(env, uid, 3, (oratext **) attr_name_list, &attrs);

if (okvErrGetNum(env))
{
   printf("Error while getting the attributes of the object\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.9 okvGetKey

okvGetKeyでは、KMIP対称キー・オブジェクトのKMIP取得操作を実装します。

カテゴリ

KMIP API

用途

okvGetKeyでは、KMIP対称キー・オブジェクトのKMIP取得操作を実装します。

指定した一意識別子の対称キーについて、キー長、キー・アルゴリズム、エンドポイント・プログラムが提供するバッファ内の実際のキー・バイト数およびキー・バイトの実際の長さが返されます。

提供されたキー・バッファの長さがOracle Key Vaultサーバーから取得した実際のキーの長さよりも小さい場合、keylには実際のキーの長さが移入されますが、キーはNULLに設定されます。

構文

OKVErrNo okvGetKey(OKVEnv *env, oratext *uid,
                   ub4 *key_alg, ub4 *key_len,
                   ub1 *key, ub4 *keyl);

パラメータ

パラメータ IN/OUT 説明
env

IN

Oracle Key Vault環境ハンドル。
uid

IN

キーの一意識別子(バッチ処理の場合はNULLも可)。

key_alg

OUT

対称キー・アルゴリズム。
key_len

OUT

作成時に指定した対称キーのキー長。
key

OUT

対称キー。
keyl

OUT

対称キーの長さ。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

なし。

例

/* Create a symmetric Key for example and get its unique
   identifier as part of its creation in 'uid' */
...
ub4 type = 0, key_len = 0, keyl = 0;
ub1 key[100];
memset(key, 0, sizeof(key));
keyl = sizeof(key);
printf("\tGetting the key\n");
okvGetKey(env, &uid[0], &type, &key_len, &key[0], &keyl);

if (okvErrGetNum(env))
{
   printf("Error while getting the key\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.10 okvGetOpaqueData

okvGetOpaqueDataでは、KMIP不透明データ・オブジェクトのKMIP取得操作を実装します。

カテゴリ

KMIP API

用途

okvGetOpaqueDataでは、KMIP不透明データ・オブジェクトのKMIP取得操作を実装します。

指定した一意識別子の不透明データについて、不透明データのタイプ、不透明データの長さ、エンドポイント・プログラムが提供するバッファ内の不透明データのバイト数が返されます。

提供された不透明データ・バッファの長さがOracle Key Vaultサーバーから取得した実際の不透明データの長さよりも小さい場合、opaque_datalには実際の不透明データの長さが移入されますが、opaque_dataはNULLに設定されます。

構文

OKVErrNo okvGetOpaqueData(OKVEnv *env, oratext *uid,
                          ub4 *opaque_data_type,
                          ub1 *opaque_data, ub4 *opaque_datal);

パラメータ

パラメータ IN/OUT 説明

env

IN

Oracle Key Vault環境ハンドル。

uid

IN

不透明データの一意識別子(バッチ処理の場合はNULLも可)。

opaque_data_type

OUT

不透明オブジェクトのタイプ。

opaque_data

OUT

不透明オブジェクト。

opaque_datal

OUT

不透明オブジェクトの長さ。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

なし。

例

/* Create an opaque data for example and get its unique
   identifier as part of its creation in 'uid' */
...
ub1     *data;
ub4      data_len = 128001;
ub4      opaque_data_type = 0;
data = (ub1 *)malloc(data_len*sizeof(ub1));

okvGetOpaqueData(env, &uid[0], &opaque_data_type, &data[0], &data_len);

if (okvErrGetNum(env))
{
   printf("Error while getting the opaque data\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.11 okvGetSecretData

okvGetSecretDataでは、KMIPシークレット・データ・オブジェクトのKMIP取得操作を実装します。

カテゴリ

KMIP API

用途

okvGetSecretDataでは、KMIPシークレット・データ・オブジェクトのKMIP取得操作を実装します。

指定した一意識別子のシークレット・データについて、シークレット・データのタイプ、シークレット・データの長さ、エンドポイント・プログラムが提供するバッファ内のシークレット・データのバイト数が返されます。

提供されたシークレット・データ・バッファの長さがOracle Key Vaultサーバーから取得した実際のシークレット・データの長さよりも小さい場合、secret_datalには実際のシークレット・データの長さが移入されますが、secret_dataはNULLに設定されます。

構文

OKVErrNo okvGetSecretData(OKVEnv *env, oratext *uid,
                          ub4 *secret_data_type,
                          ub1 *secret_data, ub4 *secret_datal);

パラメータ

パラメータ IN/OUT 説明

env

IN

Oracle Key Vault環境ハンドル。

uid

IN

シークレット・データの一意識別子(バッチ処理の場合はNULLも可)。

secret_data_type

OUT

シークレット・データのタイプ。

secret_data

OUT

シークレット・データ。

secret_datal

OUT

シークレット・データの長さ。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

なし。

例

/* Create a secret data for example and get its unique
   identifier as part of its creation in 'uid' */
...
ub1 data[100];
ub4 data_len = sizeof(data);
ub4 secret_data_type;

/* Get Secret Data associated with uid */
printf("\tGetting the secret data\n");

okvGetSecretData(env, &uid[0], &secret_data_type, &data[0], &data_len);

if (okvErrGetNum(env))
{
   printf("Error while getting the secret data\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.12 okvGetTemplate

okvGetTemplateでは、KMIPテンプレート・オブジェクトのKMIP取得操作を実装します。

カテゴリ

KMIP API

用途

okvGetTemplateでは、KMIPテンプレート・オブジェクトのKMIP取得操作を実装します。

テンプレートは属性のリストであり、Oracle Key VaultユーティリティまたはOracle Key Vault KMIP拡張関数を使用すると解釈できます。指定した一意識別子のテンプレートについて、テンプレート・オブジェクトの属性が返されます。

構文

OKVErrNo okvGetTemplate(OKVEnv *env, oratext *uid,
                        OKVTTLV **attrs_template);

パラメータ

パラメータ IN/OUT 説明

env

IN

Oracle Key Vault環境ハンドル。

uid

IN

テンプレートの一意識別子(バッチ処理の場合はNULLも可)。

attrs_template

OUT

テンプレートの属性。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

プロセス開始日と保護停止日を含むテンプレートを登録した場合、このAPIは、それらの属性が含まれているテンプレートを取得するときに一般的な失敗エラーをスローします。

例

/* Create a template for example and get its unique
   identifier as part of its creation in 'uid' */
...
OKVTTLV *template = (OKVTTLV *) NULL;
okvGetTemplate(env, uid, &template);

if (okvErrGetNum(env))
{
   printf("Error while getting the template\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.13 okvLocate

okvLocateでは、KMIP検索操作を実装します。

カテゴリ

KMIP API

用途

okvLocateでは、KMIP検索操作を実装します。

検索操作では、locate_attrsで指定した属性に一致するOracle Key Vault内のすべてのオブジェクトが検索されます。

uid_cntは、一意識別子文字列の実際の数を示します。

uidsは、locate_attrsで指定した属性に一致するオブジェクトのUIDSです。

構文

OKVErrNo okvLocate(OKVEnv *env,
                   ub4 uid_max, ub4 storage_status, OKVTTLV *locate_attrs,
                   ub4 *uid_cnt, oratext **uids);

パラメータ

パラメータ IN/OUT 説明

env

IN

Oracle Key Vault環境ハンドル。

uid_max

IN

予期される一意識別子の最大数。

storage_status

IN

アーカイブ済オブジェクトまたはオンライン・オブジェクトを検索します。

locate_attrs

IN

検索の場所を定義する属性。

uid_cnt

OUT

サーバーから返された一意識別子の数。

uids

OUT

検索属性と記憶域ステータスの基準に一致する一意識別子。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

呼出し側は、この関数から返される一意識別子uids用に十分なメモリーを割り当てる必要があります。唯一の例外は、uid_max値に関係なく、locate_attrsで指定した属性に一致するすべてのUIDがOracle Key Vaultサーバーによって返されることです。

例

/* Set up the environment handle 'env' and also the memory and connection
   management as shown in previous sections. Create a key with a name
   attribute value "MyNewKey" for example and get its unique
   identifier as part of its creation in 'uid'. Locate operation can be done as
   shown below. */
...
ub4       locate_count = 0;
ub4       uid_max = 1;
OKVTTLV  *loc_attrs = (OKVTTLV *)NULL;
OKVTTLV  *attr_in = (OKVTTLV *)NULL;
oratext **locate_uids = (oratext **) malloc(uid_max * sizeof(oratext *));
ub4       itr = 0;

for (itr = 0; itr < uid_max; itr++)
{
   locate_uids[itr] = (oratext *) malloc(OKV_UNIQUE_ID_MAXLEN * sizeof(oratext));
}

loc_attrs = okvEnvGetOpRequestObj(env);
attr_in = okvAddAttributeObject(env, loc_attrs, OKVAttrName, (ub4) 0);

/* Add name attribute value to name attribute object */
okvAttrAddName(env, attr_in, (oratext *) "MyNewKey", strlen("MyNewKey"), 1);
okvLocate(env, uid_max, 1, loc_attrs, &locate_count, locate_uids);

if (okvErrGetNum(env))
{
   printf("Error while Locating the Key: MyNewKey\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.14 okvModifyAttribute

okvModifyAttributeでは、KMIP属性変更操作を実装します。

カテゴリ

KMIP API

用途

okvModifyAttributeでは、KMIP属性変更操作を実装します。一意識別子で指定したKMIPオブジェクトの属性を変更します。

構文

OKVErrNo okvModifyAttribute(OKVEnv *env, oratext *uid,
                            OKVTTLV **attr);

パラメータ

パラメータ IN/OUT 説明
env IN

Oracle Key Vault環境ハンドル。
uid IN

一意識別子(バッチ処理の場合はNULLも可)。

attr IN

KMIPオブジェクトで変更される属性オブジェクト。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

なし。

例

/* Create the KMIP object, say Key for example and get its unique identifier
   as part of its creation in 'uid', we can add an attribute and modify it
   as shown shown below */

OKVTTLV *templ = (OKVTTLV *) NULL;
OKVTTLV *req = (OKVTTLV *) NULL;
OKVTTLV *attr_temp = (OKVTTLV *) NULL;
OKVTTLV *attr_in = (OKVTTLV *) NULL;
oratext *contact = (oratext *)"9123456789";
ub4      contactl = strlen((char *) contact);
oratext *new_contact = (oratext *)"abc.xyz@com";
ub4 new_contactl = strlen((char *) new_contact);
templ = okvEnvGetOpRequestObj(env);
attr_temp = okvAddAttributeObject(env, templ, OKVAttrContactInfo, (ub4) 0);

okvAttrAddContactInfo(env, attr_temp, contact, contactl);
okvAddAttribute(env, &uid[0], &attr_temp);

/* Now let's modify the contact info attribute */
req = okvEnvGetOpRequestObj(env);
attr_in = okvAddAttributeObject(env, req, OKVAttrContactInfo, (ub4) 0);
okvAttrAddContactInfo(env, attr_in, new_contact, new_contactl);
okvModifyAttribute(env, &uid[0], &attr_in);

if (okvErrGetNum(env))
{
   printf("Error while modifying the contact info attribute of the object\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.15 okvQueryCapability

okvQueryCapabilityでは、KMIP問合せ操作を実装します。

カテゴリ

KMIP API

用途

okvQueryCapabilityでは、KMIP問合せ操作を実装します。

KMIP問合せ操作は、Oracle Key Vaultサーバーでサポートされている項目(KMIP操作、オブジェクト、サーバー情報など)を返します。項目を一度に1つずつ取得することもできます。どの項目を返すかは、問合せ関数で指定します。サポートされている問合せ関数の値は次のとおりです。
  • OKVDEF_QUERY_OPERATIONS
  • OKVDEF_QUERY_OBJECTS
  • OKVDEF_QUERY_SERVER_INFO

問合せ関数でリクエストしていない項目の数はゼロになります。サーバー情報をリクエストしない場合は、server_informationをNULLにすることもできます。

構文

OKVErrNo okvQueryCapability(OKVEnv *env,
                            ub4  query_function_cnt, ub4 *query_function,
                            ub4 *operation_cnt, OKVOpsNo *operation,
                            ub4 *object_type_cnt, OKVObjNo *object_type,
                            OKVServerInformation *server_information);

パラメータ

パラメータ IN/OUT 説明

env

IN

Oracle Key Vault環境ハンドル。

query_function_cnt

IN

 リクエストされるKMIP関数の数。

query_function

IN

リクエストされるKMIP関数。

operation_cnt

OUT

サポートされているKMIP操作の数。

operation

OUT

サポートされているKMIP操作。

object_type_cnt

OUT

サポートされているKMIP管理対象オブジェクトの数。

object_type

OUT

サポートされているKMIP管理対象オブジェクト。

server_information

OUT

Oracle Key Vault固有の情報。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

なし。

例

/* Set up the environment handle 'env' and also the memory and
   connection management as shown in previous sections. */
...
OKVServerInformation s;
ub4 query_function[1];
ub4 operation_cnt = 30;
OKVOpsNo operation[30];
ub4 object_type_cnt = 30;
OKVObjNo object_type[30];
query_function[0] = 3;

okvQueryCapability(env,1, query_function, &operation_cnt, operation,
                   &object_type_cnt, object_type, &s);

if (okvErrGetNum(env))
{
   printf("Error while executing okvQueryCapability");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.16 okvRegKey

okvRegKeyでは、KMIP対称キー・オブジェクトのKMIP登録操作を実装します。

カテゴリ

KMIP API

用途

okvRegKeyでは、KMIP対称キー・オブジェクトのKMIP登録操作を実装します。

Oracle Key Vaultサーバーによって作成された対称キー・オブジェクトの一意識別子は、ouidとして返されます。

Oracle Key Vault SDKの一意IDの最大長は、OKV_UNIQUE_ID_MAXLENで定義されます。

新しく作成されるキーには、属性のヘルプまたはテンプレート名を使用して指定する追加の属性を採用できます。この属性とテンプレート名(指定されている場合)は、KMIP登録操作に追加されるテンプレート属性になります。

構文

OKVErrNo okvRegKey(OKVEnv *env,
                   OKVType key_alg, ub4 key_len, ub1 *key, ub4 keyl,
                   ub4 mask, OKVTTLV *template_names_attrs,
                   oratext *wallet_name, ub4 wallet_namel,
                   oratext *ouid, ub4 *ouidl);

パラメータ

パラメータ IN/OUT 説明
env

IN

Oracle Key Vault環境ハンドル。
key_alg

IN

対称キー・アルゴリズム。
key_len

IN

対称キーのキー長。
key

IN

対称キー。
keyl

IN

対称キーの長さ。
mask

IN

対称キーの暗号化マスクの使用。
template_names_attrs

IN

テンプレート-属性を形成するテンプレート名または属性。

wallet_name

 IN ウォレット名の値。

wallet_namel

 IN ウォレット名の値の長さ。
ouid

OUT

生成されたキーの一意識別子。
ouidl

OUT

生成されたキーの一意識別子の長さ。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

対称キー・オブジェクトにはKMIP名前属性を追加して、そのオブジェクトが今後識別しやすくなるようにすることをお薦めします。

呼出し側は、この関数から返される一意識別子用にメモリーを割り当てる必要があります。割り当てるメモリーの長さは、一意識別子の長さの引数ouidlで渡されます。返される一意識別子を格納するための十分なメモリーを割り当てる必要があります。

指定したアルゴリズムと使用方法(暗号化使用方法マスク)に応じて指定した長さの対称キーは、ウォレットwallet_nameが指定されている場合、そのウォレットでOracle Key Vaultサーバーに登録されます。指定されていない場合は、デフォルト・ウォレットで登録されます(このウォレットがエンドポイントに存在している場合)。

例

/* Tag for Cryptographic Algortihm AES */
OKVType   algo = CRYPTO_ALG_AES;

/* Key length 128, because AES keys are 128, 192 or 256 bits in length*/
ub4       key_len = 128;
ub4       usage_mask = CRYPTO_MASK_ENCRYPT | CRYPTO_MASK_DECRYPT;

/* Key */
ub1       key[] = "770A8A65DA156D24";

/* Length of symmetric key */
ub4       keyl = strlen((const char *)key);
oratext   uid[OKV_UNIQUE_ID_MAXLEN + 1];
ub4       uidl = sizeof(uid);
OKVTTLV  *template = (OKVTTLV *)NULL;
OKVTTLV  *attr_in = (OKVTTLV *)NULL;

/* Set up the environment handle 'env' and also the memory
   and connection management as shown in previous sections */
memset(uid, 0, uidl);
template = okvEnvGetOpRequestObj(env);

/* Add name attribute object to request handle */
attr_in = okvAddAttributeObject(env, template, OKVAttrName, (ub4) 0);

/* Add name attribute value to name attribute object */
okvAttrAddName(env, attr_in, (oratext *)"My Key for Register operation",
               strlen("My Key for Register operation"), 1);
okvRegKey(env, algo, key_len, &key[0], keyl, usage_mask, template,
          (oratext *)NULL, (ub4)0, uid, &uidl);

if (okvErrGetNum(env))
{
   printf("Error while registering the key\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.17 okvRegOpaqueData

okvRegOpaqueDataでは、KMIP不透明データ・オブジェクトのKMIP登録操作を実装します。

カテゴリ

KMIP API

用途

okvRegOpaqueDataでは、KMIP不透明データ・オブジェクトのKMIP登録操作を実装します。

不透明データはバイト列です。テキスト・ファイル、テキスト文字列、バイナリ・ファイルまたはキーも不透明データとしてアップロードできます。

登録済の不透明データに対してOracle Key Vaultサーバーで作成された不透明データ・オブジェクトの一意識別子は、ouidとして返されます。

Oracle Key Vault SDKの一意IDの最大長は、OKV_UNIQUE_ID_MAXLENで定義されます。

新しく作成される不透明データには、属性のヘルプまたはテンプレート名を使用して指定する追加の属性を採用できます。この属性とテンプレート名(指定されている場合)は、KMIP登録操作に追加されるテンプレート属性になります。

構文

OKVErrNo okvRegOpaqueData(OKVEnv *env,
                          ub4 opaque_data_type, ub1 *opaque_data,
                          ub4 opaque_datal,
                          OKVTTLV *template_names_attrs,
                          oratext *wallet_name, ub4 wallet_namel,
                          oratext *ouid, ub4 *ouidl);

パラメータ

パラメータ IN/OUT 説明
env IN

Oracle Key Vault環境ハンドル。
opaque_data_type IN 登録する不透明オブジェクトのタイプ。
opaque_data IN 登録する不透明オブジェクト。
opaque_data1 IN 登録する不透明オブジェクトの長さ。
template_names_attrs IN

テンプレート-属性を形成するテンプレート名または属性。

wallet_name

 IN ウォレット名の値。

wallet_namel

 IN ウォレット名の値の長さ。
ouid OUT

登録済不透明オブジェクトの一意識別子。
ouid1 OUT

登録済不透明オブジェクトの一意識別子の長さ。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

不透明データ・オブジェクトにはKMIP名前属性を追加して、そのオブジェクトが今後識別しやすくなるようにすることをお薦めします。

呼出し側は、この関数から返される一意識別子用にメモリーを割り当てる必要があります。割り当てるメモリーの長さは、一意識別子の長さの引数ouidlで渡されます。返される一意識別子を格納するための十分なメモリーを割り当てる必要があります。

指定のタイプの不透明データは、ウォレットwallet_nameが指定されている場合、そのウォレットでOracle Key Vaultサーバーに登録されます。指定されていない場合は、デフォルト・ウォレットで登録されます(このウォレットがエンドポイントに存在している場合)。不透明データのサイズは、Oracle Key Vaultサーバーによって処理されるオブジェクトの最大サイズに制限されます。

例外として、不透明オブジェクトでは、リース期間、非アクティブ化日、破棄日、危殆化発生日、危殆化日および失効理由の各属性はサポートされていません。

例

oratext *opaque_data = (oratext *)"MyNewData";
ub4 opaque_datal = strlen("MyNewData");
oratext  uid[OKV_UNIQUE_ID_MAXLEN + 1];
ub4      uidl = sizeof(uid);

/* Set up the environment handle 'env' and also the memory and
   connection management as shown in previous sections */
memset(uid, 0, uidl);

/* Register Opaque Data */
printf("\tRegistering opaque data\n");

okvRegOpaqueData(env, OKVDEF_TAG_OPAQUE_DATA_TYPE,
                 opaque_data, opaque_datal,
                 (OKVTTLV *)NULL, (oratext *)NULL, (ub4)0,
                 &uid[0], uidl);

if (okvErrGetNum(env))
{
   printf("Error while registering the opaque data\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.18 okvRegSecretData

okvRegSecretDataでは、KMIPシークレット・データ・オブジェクトのKMIP登録操作を実装します。

カテゴリ

KMIP API

用途

okvRegSecretDataでは、KMIPシークレット・データ・オブジェクトのKMIP登録操作を実装します。

通常、シークレット・データはパスワードまたは文字列です。

登録済のシークレット・データに対してOracle Key Vaultサーバーで作成されたシークレット・データの一意識別子は、ouidとして返されます。

Oracle Key Vault SDKの一意IDの最大長は、OKV_UNIQUE_ID_MAXLENで定義されます。

新しく作成されるシークレット・データには、属性のヘルプまたはテンプレート名を使用して指定する追加の属性を採用できます。この属性とテンプレート名(指定されている場合)は、KMIP登録操作に追加されるテンプレート属性になります。

構文

OKVErrNo okvRegSecretData(OKVEnv *env,
                          ub4 secret_data_type, ub1 *secret_data,
                          ub4 secret_datal, ub4 mask,
                          OKVTTLV *template_names_attrs,
                          oratext *wallet_name, ub4 wallet_namel,
                          oratext *ouid, ub4 *ouidl);

パラメータ

パラメータ IN/OUT 説明
env

IN

Oracle Key Vault環境ハンドル。
secret_data_type

IN

登録されるシークレット・データのタイプ。
secret_data

IN

登録されるシークレット・データ。
secret_datal

IN

登録されるシークレット・データの長さ。
mask IN

対称キーの暗号化マスクの使用。
template_names_attrs

IN

テンプレート-属性を形成するテンプレート名または属性。

wallet_name

 IN ウォレット名の値。

wallet_namel

 IN ウォレット名の値の長さ。
ouid

OUT

登録済シークレット・データの一意識別子。
ouidl

OUT

登録済シークレット・データの一意識別子の長さ。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

シークレット・データ・オブジェクトにはKMIP名前属性を追加して、そのオブジェクトが今後識別しやすくなるようにすることをお薦めします。

呼出し側は、この関数から返される一意識別子用にメモリーを割り当てる必要があります。割り当てるメモリーの長さは、一意識別子の長さ(ouidl)の引数によって渡されます。返される一意識別子を格納するための十分なメモリーを割り当てる必要があります。

指定のタイプのシークレット・データは、ウォレット(wallet_name)が指定されている場合、そのウォレットでOracle Key Vaultサーバーに登録されます。指定されていない場合は、デフォルト・ウォレットで登録されます(このウォレットがエンドポイントに存在している場合)。

シークレット・データのサイズは、Oracle Key Vaultサーバーによって処理されるオブジェクトの最大サイズに制限されます。

例

/* Parameters for registering secret data */
/* Tag for secret data type */
OKVType   type = OKVDEF_SECRET_DATA_TYPE_PASSWORD;
ub4       usage_mask = CRYPTO_MASK_ENCRYPT | CRYPTO_MASK_DECRYPT;
oratext  *secret = (oratext *)"MyNewSecret";
ub4       secretl = strlen("MyNewSecret");
oratext   uid[OKV_UNIQUE_ID_MAXLEN + 1];
ub4       uidl = sizeof(uid);

/* Set up the environment handle 'env' and also the memory and
   connection management as shown in previous sections */
memset(uid, 0, uidl);

/* Register Secret data */
printf("\tRegistering the secret data\n");

okvRegSecretData(env, type, secret, secretl,
                 usage_mask, (OKVTTLV *)NULL,
                 (oratext *)NULL, (ub4)0,
                 &uid[0], uidl);

if (okvErrGetNum(env))
{
   printf("Error while registering the secret data\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.19 okvRegTemplate

okvRegTemplateでは、KMIPテンプレート・オブジェクトのKMIP登録操作を実装します。

カテゴリ

KMIP API

用途

okvRegTemplateでは、KMIPテンプレート・オブジェクトのKMIP登録操作を実装します(KMIPテンプレート-属性オブジェクトと混同しないでください)。

テンプレート・オブジェクトは、属性のコレクションです。

Oracle Key Vaultで登録済テンプレートに対して指定の属性によって作成されたテンプレート・オブジェクトの一意識別子は、ouidとして返されます。

Oracle Key Vault SDKの一意識別子の最大長は、OKV_UNIQUE_ID_MAXLENで定義されます。

構文

OKVErrNo okvRegTemplate(OKVEnv *env,
                        OKVTTLV *attrs_template,
                        oratext *wallet_name, ub4 wallet_namel,
                        oratext *ouid, ub4 *ouidl);

パラメータ

パラメータ IN/OUT 説明
env IN

Oracle Key Vault環境ハンドル。
attrs_template IN

テンプレートの属性。

wallet_name

 IN ウォレット名の値。

wallet_namel

 IN ウォレット名の値の長さ。
ouid OUT

登録済テンプレートの一意識別子。
ouid1 OUT

登録済テンプレートの一意識別子の長さ。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

呼出し側は、この関数から返される一意識別子用にメモリーを割り当てる必要があります。割り当てたメモリーの長さは、一意識別子の長さ(ouidl)の引数によって渡されます。返される一意識別子を格納するための十分なメモリーを割り当てる必要があります。

テンプレートは、wallet_name引数で指定したウォレットに登録されます。それ以外の場合は、エンドポイントに関連付けられたデフォルト・ウォレットに登録されます(デフォルト・ウォレットが存在する場合)。

例

oratext  uid[OKV_UNIQUE_ID_MAXLEN + 1];
ub4      uidl = sizeof(uid);

/* Set up the environment handle 'env' also the memory and connection
   management as shown in previous sections */
memset(uid, 0, uidl);
okvRegTemplate(env, (OKVTTLV *)NULL, (oratext *)NULL, (ub4)0, &uid[0], &uidl);

if (okvErrGetNum(env))
{
   printf("Error while registering the Template\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.20 okvRekey

okvRekeyでは、KMIPキー更新操作を実装します。

カテゴリ

KMIP API

用途

okvRekeyでは、KMIPキー更新操作を実装します。

キー更新操作には、キー更新が必要になる対称キーの一意識別子が必須です。ほとんどの属性が、古いキーから引き継がれます。一部の属性は、KMIP定義の規則に従って変更されます。

Oracle Key Vaultサーバーによって生成された新しい対称キー・オブジェクトの一意識別子は、ouidとして返されます。

Oracle Key Vault SDKの一意IDの最大長は、OKV_UNIQUE_ID_MAXLENで定義されます。

構文

OKVErrNo okvRekey(OKVEnv *env, oratext *uid,
                  ub4 offset, OKVTTLV *template_names_attrs,
                  oratext *ouid, ub4 *ouidl);

パラメータ

パラメータ IN/OUT 説明

env

IN

Oracle Key Vault環境ハンドル。

uid

IN

キー更新するキーの一意識別子(バッチ処理の場合はNULLも可)。

offset

IN

初期化(作成)日とアクティブ化日の間の時間間隔。

template_names_attrs

IN

キー更新のテンプレート-属性を形成するテンプレート名または属性。

ouid

OUT

新しく生成された対称キーの一意識別子。

ouidl

OUT

新しく生成された対称キーの一意識別子の長さ。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

呼出し側は、この関数から返される新しい対称キーの一意識別子用にメモリーを割り当てる必要があります。割り当てたメモリーの長さは、一意識別子の長さ(ouidl)の引数によって渡されます。

Oracle Key Vaultサーバーで使用する場合、このAPIには次の例外があります。
  • サーバーは、キーのキー更新可能回数に制限を課しません。たとえば、キーK1がキー更新され、新しいキーK2が作成された場合、サーバーは再度のキーK1のキー更新を許可して、キーK3が作成されます。
  • キー更新に対してテンプレートが渡された場合、そのテンプレート属性は新しいキーに追加されません。回避策として、キー更新後にokvAddAttributeを使用することで、これを追加できます。

例

/* Set up the environment handle 'env' and also the memory and
   connection management as shown in previous sections. Create
   a key for example and get its unique identifier as part of
   its creation in 'uid'. Rekey can done as shown below */
…
oratext  rekey_uid[OKV_UNIQUE_ID_MAXLEN + 1];
ub4      rekey_uidl = sizeof(rekey_uid);

memset(rekey_uid, 0, rekey_uidl);
okvRekey(env, uid, (ub4)0, (OKVTTLV *)NULL, &rekey_uid[0], &rekey_uidl);

if (okvErrGetNum(env))
{
   printf("Error while Re-Keying in the Key\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.1.21 okvRevoke

okvRevokeでは、KMIP失効操作を実装します。

カテゴリ

KMIP API

用途

okvRevokeでは、KMIP失効操作を実装します。失効理由とオブジェクトが危殆化した日付とともに、一意識別子で指定したKMIPオブジェクトを失効させます。

構文

OKVErrNo okvRevoke(OKVEnv *env, oratext *uid,
                   ub4 revocation_reason,
                   oratext *revocation_msg,
                   ub8 comp_occurrence_date);

パラメータ

パラメータ IN/OUT 説明
env IN

Oracle Key Vault環境ハンドル。
uid IN

一意識別子(バッチ処理の場合はNULLも可)。
revocation_reason IN

KMIPオブジェクトの失効処理についての失効理由。
revocation_msg IN

KMIPオブジェクトの失効処理についての失効メッセージ。
comp_occurrence_date IN

KMIPオブジェクトの危殆化が発生した日付。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

なし。

例

/* Create the KMIP object, say Key for example and get its unique identifier
   as part of its creation in 'uid', activate it and then revoke it as below */

okvRevoke(env, &uid[0], (ub4)1, (oratext *)"Retiring the key",
          (ub8)time((time_t *)NULL));

if (okvErrGetNum(env))
{
   printf("Error while revoking the object\n");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのKMIP API

10.2 Oracle Key VaultクライアントSDKのバッチAPI

この項では、Oracle Key Vault KMIPバッチ関数のインタフェースについて説明します。

  • okvBatchCreate
    okvBatchCreateでは、Oracle Key Vaultバッチ処理の開始を示します。
  • okvBatchExecute
    okvBatchExecuteでは、バッチ処理されるOracle Key Vault関数を実行します。
  • okvBatchFree
    okvBatchFreeでは、Oracle Key Vaultバッチ処理の終了を示します。
  • okvGetBatchOperationCount
    okvGetBatchOperationCountでは、バッチ処理されたOracle Key Vault操作の数を取得します。
  • okvGetBatchOperationName
    okvGetBatchOperationNameは、この関数で渡される個別のバッチ・ジョブ番号の名前を返します。

親トピック: Oracle Key VaultクライアントSDKのKMIPおよびバッチAPI

10.2.1 okvBatchCreate

okvBatchCreateでは、Oracle Key Vaultバッチ処理の開始を示します。

カテゴリ

KMIPバッチAPI

用途

okvBatchCreateでは、Oracle Key Vaultバッチ処理の開始を示します。このコマンドの後のすべてのOracle Key Vault関数はバッチ処理されます。

構文

OKVErrNo okvBatchCreate(OKVEnv *env);

パラメータ

パラメータ IN/OUT 説明

env

IN

Oracle Key Vault環境ハンドル。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

なし。

例

/* Set up the environment handle 'env' and also the memory and
   connection management as shown in previous sections. */

printf("Start preparing batch operations\n");
okvBatchCreate(env);

if (okvErrGetNum(env))
{
   printf("Error while initiating the Batch");
}
...
/* All Oracle Key Vault functions will be batched */

関連項目

親トピック: Oracle Key VaultクライアントSDKのバッチAPI

10.2.2 okvBatchExecute

okvBatchExecuteでは、バッチ処理されるOracle Key Vault関数を実行します。

カテゴリ

KMIPバッチAPI

用途

okvBatchExecuteでは、バッチ処理されるOracle Key Vault関数を実行します。バッチ処理されるOracle Key Vault関数は、okvBatchCreateとokvBatchExecuteの間の関数です。エラーが発生した場合は、バッチ処理されたすべてのOracle Key Vault関数のエラーをチェックして、失敗した操作と成功した操作を確認する必要があります。

構文

OKVErrNo okvBatchExecute(OKVEnv *env);

パラメータ

パラメータ IN/OUT 説明

env

IN

Oracle Key Vault環境ハンドル。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

実行後にバッチ内の個別の操作をチェックするために使用できるAPIは、okvErrGetNumForBatch、okvErrGetDepthForBatchおよびokvErrGetNumAtDepthForBatchです。個別のバッチ操作のエラーは、バッチ・コンテキストを解放する前(okvBatchFreeをコールする前)にのみチェックできます。

例

/* Set up the environment handle 'env' and also the memory and
   connection management as shown in previous sections. */
printf("Start preparing batch operations\n");
okvBatchCreate(env);
...
/* All Oracle Key Vault functions will be batched */
...
printf("Executing batch operation\n");
okvBatchExecute(env);

if (okvErrGetNum(env))
{
   printf("Error while executing the batch");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのバッチAPI

10.2.3 okvBatchFree

okvBatchFreeでは、Oracle Key Vaultバッチ処理の終了を示します。

カテゴリ

KMIPバッチAPI

用途

okvBatchFreeでは、Oracle Key Vaultバッチ処理の終了を示します。基本的に、複合の引数に割り当てられたメモリーは解放されます。okvBatchCreateを再度コールしないかぎり、それ以降のOracle Key Vault関数はバッチ処理されません。

構文

OKVErrNo okvBatchFree(OKVEnv *env);

パラメータ

パラメータ IN/OUT 説明

env

IN

Oracle Key Vault環境ハンドル。

戻り値

戻り値 説明
OKVErrNo

Oracle Key Vaultエラー番号。

成功: OKV_SUCCESS (0)が返されます。

失敗: エラー・スタックの最上部にあるエラーの有効なエラー番号が返されます。

コメント

個別のバッチ操作のエラーは、バッチ・コンテキストを解放する前(okvBatchFreeをコールする前)にのみチェックできます。

例

/* Set up the environment handle 'env' and also the memory and
   connection management as shown in previous sections. */
printf("Start preparing batch operations\n");
okvBatchCreate(env);
...
/* All Oracle Key Vault functions will be batched */
...
printf("Executing batch operation\n");
okvBatchExecute(env);
...
/* Check for Individual Batch Operation errors */
...
printf("Ending batch operations\n\n");
okvBatchFree(env);

if (okvErrGetNum(env))
{
   printf("Error while ending the batch");
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのバッチAPI

10.2.4 okvGetBatchOperationCount

okvGetBatchOperationCountでは、バッチ処理されたOracle Key Vault操作の数を取得します。

カテゴリ

KMIPバッチAPI

用途

okvGetBatchOperationCountでは、バッチ処理されたOracle Key Vault操作の数を取得します。

構文

ub4 okvGetBatchOperationCount(OKVEnv *env);

パラメータ

パラメータ IN/OUT 説明
env

IN

Oracle Key Vault環境ハンドル。

戻り値

戻り値 説明
ub4

バッチ処理された操作の数。

成功: ゼロ以外の有効な正の数値が返されます。

失敗: ゼロ。

コメント

この関数は、okvBatchFreeの呼出し前に呼び出す必要があります。それ以外の場合は、ゼロが返されます。

例

ub4 batch_cnt = 0;

/* Set up the environment handle 'env' and also the memory and
   connection management as shown in previous sections. */
printf("\t\tStart preparing batch operations\n");
okvBatchCreate(env);
...
/* All Oracle Key Vault functions will be Batched */
...
printf("\t\tExecuting batch operation\n");
okvBatchExecute(env);
...
/* Check for Individual Batch Operation errors */
...
batch_cnt = okvGetBatchOperationCount(env);
printf("Batch operations count is: %d\n", batch_cnt);

関連項目

親トピック: Oracle Key VaultクライアントSDKのバッチAPI

10.2.5 okvGetBatchOperationName

okvGetBatchOperationNameは、この関数で渡される個別のバッチ・ジョブ番号の名前を返します。

カテゴリ

KMIPバッチAPI

用途

okvGetBatchOperationNameは、この関数で渡される個別のバッチ・ジョブ番号の名前を返します。

構文

oratext *okvGetBatchOperationName(OKVEnv *env, ub1 batchjobnum);

パラメータ

パラメータ IN/OUT 説明
env

IN

Oracle Key Vault環境ハンドル。
batchjobnum IN

バッチ・ジョブ番号。

戻り値

戻り値 説明
oratext *

バッチ・ジョブ操作名。

成功: バッチ・ジョブ操作名へのポインタが返されます。

失敗: NULLポインタが返されます。

コメント

この関数は、okvBatchFreeの呼出し前に呼び出す必要があります。それ以外の場合は、NULLを指すポインタが返されます。

batchjobnumは、バッチ処理される操作の番号です。たとえば、ユーザーがキーを作成し、キーをアクティブ化して失効させてから破棄する場合、これらの操作はすべて同じ順序でバッチ処理されます。つまり、キーの作成のためのbatchjobnumは1、キーのアクティブ化のためのbatchjobnumは2、失効のためのbatchjobnumは3、破棄のためのbatchjobnumは4になります。

例

ub4 batch_cnt = 0;
ub4 batch_job_num = 0;

/* Set up the environment handle 'env' also the memory and
   connection management as shown in previous sections. */
printf("\t\tStart preparing batch operations\n");
okvBatchCreate(env);
...
/* All Oracle Key Vault functions will be Batched */
...
printf("\t\tExecuting batch operation\n");
okvBatchExecute(env);
...
/* Check for Individual Batch Operation errors */
...
batch_cnt = okvGetBatchOperationCount(env);
printf("Batch Operations count is: %d\n", batch_cnt);

if (batch_cnt)
{
   for(batch_job_num=1; batch_job_num<=batch_cnt; batch_job_num++)
   {
      printf("\t\t\t%d: %s\n", batch_job_num, okvGetBatchOperationName(env, batch_job_num));
   }
}

関連項目

親トピック: Oracle Key VaultクライアントSDKのバッチAPI