10 Oracle Key Vault Client SDK KMIP and Batch APIs

The SDK KMIP APIs provide functions for creating keys, activating keys, adding attributes to keys, destroying keys, and other operations. The batch APIs enable you to perform these activities in a batch operation.

• Oracle Key Vault Client SDK KMIP APIs
  This section describes the interfaces for the Oracle Key Vault functions for KMIP operations.
• Oracle Key Vault Client SDK Batch APIs
  This section describes the interfaces for the Oracle Key Vault KMIP batch functions.

10.1 Oracle Key Vault Client SDK KMIP APIs

This section describes the interfaces for the Oracle Key Vault functions for KMIP operations.

• About the Oracle Key Vault Client SDK KMIP APIs
  The Oracle Key Vault KMIP APIs enable you to perform actions such as managing keys and secret data.
• okvActivate
  okvActivate implements the KMIP Activate operation.
• okvAddAttribute
  okvAddAttribute implements the KMIP add attribute operation.
• okvCreateKey
  okvCreateKey implements the KMIP Create operation for the KMIP symmetric key object.
• okvDeleteAttribute
  okvDeleteAttribute implements the KMIP delete attribute operation.
• okvDestroy
  okvDestroy implements the KMIP destroy operation.
• okvGetAttributeList
  okvGetAttributeList implements KMIP get attribute list operation.
• okvGetAttributes
  okvGetAttributes implements KMIP get attribute operation.
• okvGetKey
  okvGetKey implements the KMIP get operation for the KMIP symmetric key object.
• okvGetOpaqueData
  okvGetOpaqueData implements the KMIP get operation for the KMIP opaque data object.
• okvGetSecretData
  okvGetSecretData implements the KMIP get operation for the KMIP secret data object.
• okvGetTemplate
  okvGetTemplate implements the KMIP Get operation for the KMIP template object.
• okvLocate
  okvLocate implements the KMIP locate operation.
• okvModifyAttribute
  okvModifyAttribute implements the KMIP modify attribute operation.
• okvQueryCapability
  okvQueryCapability implements the KMIP query operation.
• okvRegKey
  okvRegKey implements the KMIP register operation for the KMIP symmetric key object.
• okvRegOpaqueData
  okvRegOpaqueData implements the KMIP register operation for the KMIP opaque data object.
• okvRegSecretData
  okvRegSecretData implements the KMIP Register operation for the KMIP secret data object.
• okvRegTemplate
  okvRegTemplate implements the KMIP Register operation for the KMIP template object.
• okvRekey
  okvRekey implements the KMIP rekey operation.
• okvRevoke
  okvRevoke implements the KMIP revoke operation.

10.1.1 About the Oracle Key Vault Client SDK KMIP APIs

The Oracle Key Vault KMIP APIs enable you to perform actions such as managing keys and secret data.

Many of these functions take unique identifier as an input argument. As per KMIP v1.1, the unique identifier can be optional when the commands are batched given that the KMIP server can determine a single unique identifier from the previous commands. So if the previous command like locate returns only one unique identifier for possible use-cases, and the following commands operate on this unique identifier, the unique identifier can be omitted from the following commands.

The unique identifiers, along with their lengths, will be returned from the KMIP API functions. The unique identifiers needs to be NULL terminated by the endpoint program.

The endpoint program can pass in a larger buffer and the length will be used to determine the actual unique identifier bits in the larger buffer.

10.1.2 okvActivate

okvActivate implements the KMIP Activate operation.

Category

KMIP API

Purpose

okvActivate implements the KMIP Activate operation. It will activate the KMIP Object identified by unique identifier.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier (can be NULL for batching).

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

None.

Example

/* 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");
}

10.1.3 okvAddAttribute

okvAddAttribute implements the KMIP add attribute operation.

Catetory

KMIP API

Purpose

okvAddAttribute implements the KMIP add attribute operation. It adds an attribute to the KMIP Object specified by the unique identifier.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier (can be NULL for batching).
attr	IN	Attribute object to be added to the KMIP object.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

The API has the below exceptions when used with Oracle Key Vault server:

• If attributes are added to opaque or template objects using this API, the Oracle Key Vault server will give a general failure error and the attributes will not be added to the KMIP object. As a workaround the attributes can be added during the registration using APIs okvRegOpaqueData and okvRegTemplate.
• If a single instance attribute is added to an object using this API and the object already has an instance of the attribute, then the attribute won’t get overwritten, but a general failure error will be thrown. Please use the okvModifyAttribute API to modify attribute values.
• If a protect stop date later than the deactivation date is passed in request TTLV, the server will not give an error and the protect stop date will be added to registered KMIP object.
• If a process start date is added using this API, the server will give permission denied error. As a workaround the attribute can be added during registration using APIs okvRegKey, okvRegSecretData, okvRegOpaqueData, and okvRegTemplate.

Example

/* 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");
}

10.1.4 okvCreateKey

okvCreateKey implements the KMIP Create operation for the KMIP symmetric key object.

Category

KMIP API

Purpose

okvCreateKey implements the KMIP Create operation for the KMIP symmetric key object. The unique identifier of the symmetric key object generated by the OKV server is returned as ouid. The maximum length of the unique ID for Oracle Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
alg	IN	Symmetric key algorithm.
len	IN	Key length of the symmetric key.
mask	IN	Cryptographic mask usage of the symmetric key.
template_names_attrs	IN	Template names or attributes that will form the template-attribute.
wallet_name	IN	Wallet name value.
wallet_namel	IN	Length of the wallet name value.
ouid	OUT	Unique identifier of the generated key.
ouidl	OUT	Unique identifier length of the generated key.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

It is recommended to add a KMIP Name attribute to symmetric key object to help identify it in future.

The caller has to allocate the memory for the unique identifier returned by this function. The length of allocated memory is passed in via the length of the unique identifier argument ouidl. Sufficient memory to store the returned unique identifier should be allocated.

A symmetric key of the specified length for the specified algorithm and for a specific use (cryptographic usage mask) is generated in wallet wallet_name if specified else it is generated in the default wallet if present with the endpoint.

Example

/* 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");
}

10.1.5 okvDeleteAttribute

okvDeleteAttribute implements the KMIP delete attribute operation.

Catetory

KMIP API

Purpose

okvDeleteAttribute implements the KMIP delete attribute operation. It deletes an attribute specified by an attribute name and attribute index of the KMIP object specified by the unique identifier.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier (can be NULL for batching).
attr_name	IN	Name of attribute to be deleted.
attr_index	IN	Index of the attribute to be deleted.
attr	OUT	Attribute object deleted from the KMIP object.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

None.

Example

/* 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");
}

10.1.6 okvDestroy

okvDestroy implements the KMIP destroy operation.

Catetory

KMIP API

Purpose

okvDestroy implements the KMIP destroy operation. It will destroy the KMIP object specified by unique identifier.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier (can be NULL for batching).

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

None.

Example

/* 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");
}

10.1.7 okvGetAttributeList

okvGetAttributeList implements KMIP get attribute list operation.

Catetory

KMIP API

Purpose

okvGetAttributeList implements KMIP get attribute list operation. It retrieves the names of the regular and custom attributes of a KMIP object specified by the unique identifier.

attr_names_count specifies how many attr_names can be accommodated in attr_names and okvGetAttributeList() will only copy that many attribute names. If there are more attributes then attr_names_count will be modified to store the actual number of attributes in the returned request.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault Interface environment handle.
uid	IN	Unique identifier (can be NULL for batching).
attr_names_count	IN/OUT	Count of names of the attributes names retrieved.
attr_names	OUT	Names of the attributes names retrieved.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

The list retrieved is unordered.

Example

/* 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");
}

10.1.8 okvGetAttributes

okvGetAttributes implements KMIP get attribute operation.

Catetory

KMIP API

Purpose

okvGetAttributes implements KMIP Get Attribute operation. It retrieves the specified list of regular and custom attributes for a given KMIP object specified by the unique identifier.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier (can be NULL for batching).
attr_names_count	IN	Count of names of the attributes retrieved.
attr_names	IN	Names of the attributes to be retrieved.
attrs	OUT	Attributes retrieved.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

The list retrieved is unordered.

Example

/* 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");
}

10.1.9 okvGetKey

okvGetKey implements the KMIP get operation for the KMIP symmetric key object.

Catetory

KMIP API

Purpose

okvGetKey implements the KMIP get operation for the KMIP symmetric key object.

For the specified unique identifier of the symmetric key, the key length, key algorithm, the actual key bytes in the endpoint program supplied buffer and the actual length of the key bytes are returned.

If the length of the key buffer supplied is smaller than the length of the actual key retrieved from the Oracle Key Vault Server, then the keyl is populated with the actual key length but key is set to NULL.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier of the key (can be NULL for batching).
key_alg	OUT	Symmetric key algorithm.
key_len	OUT	Key length of the symmetric key provided at the time of creation.
key	OUT	Symmetric key.
keyl	OUT	Length of the symmetric key.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

None.

Example

/* 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");
}

10.1.10 okvGetOpaqueData

okvGetOpaqueData implements the KMIP get operation for the KMIP opaque data object.

Catetory

KMIP API

Purpose

okvGetOpaqueData implements the KMIP get operation for the KMIP opaque data object.

For the specified unique identifier of the opaque data, the opaque data type, the opaque data length and the opaque data bytes in the endpoint program supplied buffer is returned.

If the length of the opaque data buffer supplied is smaller than the length of the actual opaque data retrieved from the Oracle Key Vault server, then opaque_datal is populated with the actual opaque data length but opaque_data is set to NULL.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier of the opaque object (can be NULL for batching).
opaque_data_type	OUT	Type of opaque object.
opaque_data	OUT	Opaque object.
opaque_datal	OUT	Length of opaque object.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

None.

Example

/* 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");
}

10.1.11 okvGetSecretData

okvGetSecretData implements the KMIP get operation for the KMIP secret data object.

Catetory

KMIP API

Purpose

okvGetSecretData implements the KMIP get operation for the KMIP secret data object.

For the specified unique identifier of the secret data, the secret data type, the secret data length and the secret data bytes in the endpoint program supplied buffer is returned.

If the length of the secret data buffer supplied is smaller than the length of the actual secret data retrieved from the Oracle Key Vault server, then the secret_datal is populated with the actual secret data length but secret_data is set to NULL.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier of the secret data (can be NULL for batching).
secret_data_type	OUT	Type of secret data.
secret_data	OUT	Secret data.
secret_datal	OUT	Length of secret data.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

None.

Example

/* 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");
}

10.1.12 okvGetTemplate

okvGetTemplate implements the KMIP Get operation for the KMIP template object.

Catetory

KMIP API

Purpose

okvGetTemplate implements the KMIP Get operation for the KMIP template object.

The template is a list of attributes, which can be interpreted using the Oracle Key Vault utility or Oracle Key Vault KMIP extension functions. For the specified unique identifier of the template, the attributes of the template object are returned.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier of the template (can be NULL for Batching).
attrs_template	OUT	Attributes of the template.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

This API will throw a general failure error while retrieving the template with process start date and protect stop date in the case if we register the template with these attributes.

Example

/* 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");
}

10.1.13 okvLocate

okvLocate implements the KMIP locate operation.

Catetory

KMIP API

Purpose

okvLocate implements the KMIP locate operation.

The locate operation will look up all the objects in Oracle Key Vault that match the attributes specified in the locate_attrs.

uid_cnt should indicate the actual number of unique identifiers strings.

uids are the UIDS of the objects that match the attributes specified in locate_attrs.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid_max	IN	Maximum number of unique identifiers expected.
storage_status	IN	Look for archived or online objects.
locate_attrs	IN	Attributes that define the locate search.
uid_cnt	OUT	Number of unique identifiers returned by the server.
uids	OUT	Unique identifiers that match the locate attributes and storage status criteria.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

The caller has to allocate sufficient memory for the unique identifiers uids returned by this function. The only exception is irrespective of what the uid_max value is, all the UIDs are returned by the Oracle Key Vault server that match the attributes specified in locate_attrs.

Example

/* 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");
}

10.1.14 okvModifyAttribute

okvModifyAttribute implements the KMIP modify attribute operation.

Catetory

KMIP API

Purpose

okvModifyAttribute implements the KMIP modify attribute operation. It modifies an attribute of the KMIP Object specified by the unique identifier.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier (can be NULL for batching).
attr	IN	Attribute object to be modified by the KMIP object.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

None.

Example

/* 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");
}

10.1.15 okvQueryCapability

okvQueryCapability implements the KMIP query operation.

Catetory

KMIP API

Purpose

okvQueryCapability implements the KMIP query operation.

KMIP query operation returns the Oracle Key Vault server supported items such as KMIP operations, objects, server information. Items can also be retrieved one at a time. Query function specifies which items should be returned. The supported values of query functions are

• OKVDEF_QUERY_OPERATIONS
• OKVDEF_QUERY_OBJECTS
• OKVDEF_QUERY_SERVER_INFO

The count of the item not requested in the query function will be zero. If server information is not requested then server_information can be NULL.

Syntax

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);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
query_function_cnt	IN	Count of KMIP functions requested.
query_function	IN	KMIP functions requested.
operation_cnt	OUT	Count of KMIP operations supported.
operation	OUT	KMIP operations supported.
object_type_cnt	OUT	Count of KMIP managed objects supported.
object_type	OUT	KMIP managed objects supported.
server_information	OUT	Oracle Key Vault specific information.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

None.

Example

/* 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");
}

10.1.16 okvRegKey

okvRegKey implements the KMIP register operation for the KMIP symmetric key object.

Catetory

KMIP API

Purpose

okvRegKey implements the KMIP register operation for the KMIP symmetric key object.

The unique identifier of the symmetric key object created by the Oracle Key Vault server is returned as ouid.

The maximum length of the unique ID for Oracle Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN.

The new key created can take in additional attributes specified with the help of attributes or also with the template names. The attributes, and also the template names if specified, will be the template attribute added to KMIP register operation.

Syntax

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);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
key_alg	IN	Symmetric key algorithm.
key_len	IN	Key length of the symmetric key.
key	IN	Symmetric key.
keyl	IN	Symmetric key length.
mask	IN	Cryptographic mask usage of the symmetric key.
template_names_attrs	IN	Template names or attributes that will form the template-attribute.
wallet_name	IN	Wallet name value.
wallet_namel	IN	Length of the wallet name value.
ouid	OUT	Unique identifier of the generated key.
ouidl	OUT	Unique identifier length of the generated key.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

It is recommended to add a KMIP name attribute to symmetric key object to help identify it in future.

The caller has to allocate the memory for the unique identifier returned by this function. The length of allocated memory is passed in via the length of the unique identifier argument ouidl. Sufficient memory to store the returned unique identifier should be allocated.

A symmetric key of the specified length for a specified algorithm and use (cryptographic usage mask) is registered with Oracle Key Vault server in wallet wallet_name if specified else it is registered in the default wallet if present with the endpoint.

Example

/* 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");
}

10.1.17 okvRegOpaqueData

okvRegOpaqueData implements the KMIP register operation for the KMIP opaque data object.

Catetory

KMIP API

Purpose

okvRegOpaqueData implements the KMIP register operation for the KMIP opaque data object.

The opaque data is a byte string. A text file, text string, binary file, or key can also be uploaded as an opaque data.

The unique identifier of the opaque data object created in the Oracle Key Vault server for the registered opaque data is returned as ouid.

The maximum length of the unique ID for Oracle Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN.

The new opaque data created can take in additional attributes specified with the help of attributes or also with the template names. The attributes, and also the template names if specified, will be the template attribute added to KMIP Register operation.

Syntax

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); 

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
opaque_data_type	IN	Type of opaque object being registered.
opaque_data	IN	Opaque object being registered.
opaque_data1	IN	Length of opaque object being registered
template_names_attrs	IN	Template names or attributes that will form the template-attribute.
wallet_name	IN	Wallet name value.
wallet_namel	IN	Length of the wallet name value.
ouid	OUT	Unique identifier of the registered opaque object.
ouid1	OUT	Unique identifier length of the registered opaque object.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

It is recommended to add a KMIP Name attribute to opaque data object to help identify it in future.

The caller has to allocate the memory for the unique identifier returned by this function. The length of allocated memory is passed in via the length of the unique identifier argument ouidl. Sufficient memory to store the returned unique identifier should be allocated.

An opaque data of a specific type is registered with Oracle Key Vault server in wallet wallet_name if specified else it is registered in the default wallet if present with the endpoint. The size of the opaque data is limited by the maximum size of the object handled by the Oracle Key Vault server.

An exception is that the attributes lease time, deactivation date, destroy date, compromise occurrence date, compromise date, and revocation reason are not supported for opaque objects.

Example

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");
}

10.1.18 okvRegSecretData

okvRegSecretData implements the KMIP Register operation for the KMIP secret data object.

Catetory

KMIP API

Purpose

okvRegSecretData implements the KMIP Register operation for the KMIP secret data object.

Secret data is usually a password or a string.

The unique identifier of the secret data object created in the Oracle Key Vault server for the registered secret data is returned as ouid.

The maximum length of the unique ID for Oracle Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN.

The new secret data created can take in additional attributes specified with the help of attributes or also with the template names. The attributes, and also the template names if specified, will be the template attribute added to KMIP register operation.

Syntax

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);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
secret_data_type	IN	Type of secret data being registered.
secret_data	IN	Secret data being registered.
secret_datal	IN	Length of secret data being registered.
mask	IN	Cryptographic mask usage of the symmetric key.
template_names_attrs	IN	Template names or attributes that will form the template-attribute.
wallet_name	IN	Wallet name value.
wallet_namel	IN	Length of the wallet name value.
ouid	OUT	Unique identifier of the registered secret data.
ouidl	OUT	Unique identifier length of the registered secret data.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

It is recommended to add a KMIP name attribute to secret data object to help identify it in future.

The caller has to allocate the memory for the unique identifier returned by this function. The length of allocated memory is passed in via the length of the unique identifier (ouidl) argument. Sufficient memory to store the returned unique identifier should be allocated.

A secret data of a specific type is registered with Oracle Key Vault server in wallet (wallet_name) if specified else it is registered in the default wallet if present with the endpoint.

The size of the secret data is limited by the maximum size of the object handled by the Oracle Key Vault server.

Example

/* 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");
}

10.1.19 okvRegTemplate

okvRegTemplate implements the KMIP Register operation for the KMIP template object.

Catetory

KMIP API

Purpose

okvRegTemplate implements the KMIP Register operation for the KMIP template object (not to be confused with KMIP template-attribute object).

A template object is a collection of attributes.

The unique identifier of the template object created with the specified attributes in Oracle Key Vault for the registered template is returned as ouid.

The maximum length of the unique identifier for Oracle Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
attrs_template	IN	Attributes of the template.
wallet_name	IN	Wallet name value.
wallet_namel	IN	Length of the wallet name value.
ouid	OUT	Unique identifier of the registered template.
ouid1	OUT	Unique identifier length of the registered template.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

The caller has to allocate the memory for the unique identifier returned by this function. The length of allocated memory is passed in via the length of the unique identifier (ouidl) argument. Sufficient memory to store the returned unique identifier should be allocated.

The template will be registered with the wallet specified in wallet_name argument else it will be registered with the default wallet associated with the endpoint in case the default wallet exists.

Example

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");
}

10.1.20 okvRekey

okvRekey implements the KMIP rekey operation.

Catetory

KMIP API

Purpose

okvRekey implements the KMIP rekey operation.

The rekey operation requires the unique identifier of the symmetric key that needs to be re-keyed. Most of the attributes are carried over from the old key. Some attributes are modified per KMIP defined rules.

The unique identifier of the new symmetric key object generated by the Oracle Key Vault server is returned as ouid.

The maximum length of the unique ID for Oracle Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier of the key being rekeyed (can be NULL for Batching).
offset	IN	Time interval between initialization (creation) date and activation date.
template_names_attrs	IN	Template names or attributes that will form the template-attribute for rekey.
ouid	OUT	Unique identifier of the new generated symmetric key.
ouidl	OUT	Unique identifier length of the newly generated symmetric key.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

The caller has to allocate the memory for the unique identifier of the new symmetric key returned by this function. The length of allocated memory is passed in via the length of the unique identifier (ouidl) argument.

The API has the below exceptions when used with Oracle Key Vault server:

• The server doesn’t impose any restrictions on the number of times a key can be rekeyed. For example, if a key K1 is rekeyed and a new key K2 is created, the server allows the key K1 to be rekeyed again and key K3 would be created.
• If a template is passed for rekey, the template attributes are not added for the new key. As a workaround, this can be added post rekey using okvAddAttribute.

Example

/* 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");
}

10.1.21 okvRevoke

okvRevoke implements the KMIP revoke operation.

Catetory

KMIP API

Purpose

okvRevoke implements the KMIP revoke operation. It revokes the KMIP object specified by the unique identifier with a revocation reason and the date when the object was compromised.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier (can be NULL for batching).
revocation_reason	IN	Revocation reason for revoking the KMIP object.
revocation_msg	IN	Revocation message for revoking the KMIP object.
comp_occurrence_date	IN	Date when the KMIP object compromise occurred.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

None.

Example

/* 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");
}

10.2 Oracle Key Vault Client SDK Batch APIs

This section describes the interfaces for the Oracle Key Vault KMIP batch functions.

• okvBatchCreate
  okvBatchCreate will mark the start of Oracle Key Vault batching.
• okvBatchExecute
  okvBatchExecute will execute the batched Oracle Key Vault functions.
• okvBatchFree
  okvBatchFree will mark the end of Oracle Key Vault batching.
• okvGetBatchOperationCount
  okvGetBatchOperationCount gets the count of batched Oracle Key Vault operations.
• okvGetBatchOperationName
  okvGetBatchOperationName returns the name of the respective batch job number that is passed with this function.

10.2.1 okvBatchCreate

okvBatchCreate will mark the start of Oracle Key Vault batching.

Catetory

KMIP batch API

Purpose

okvBatchCreate will mark the start of Oracle Key Vault batching. All Oracle Key Vault functions after this command will be batched.

Syntax

OKVErrNo okvBatchCreate(OKVEnv *env);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

None.

Example

/* 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 */

10.2.2 okvBatchExecute

okvBatchExecute will execute the batched Oracle Key Vault functions.

Catetory

KMIP batch API

Purpose

okvBatchExecute will execute the batched Oracle Key Vault functions. The batched Oracle Key Vault functions are functions between okvBatchCreate and okvBatchExecute. If there are errors, then the errors for all the batched Oracle Key Vault functions should be checked to verify which operations failed and which were successful.

Syntax

OKVErrNo okvBatchExecute(OKVEnv *env);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

To check for individual operations in the batch after its execution, these APIs can be made use of: okvErrGetNumForBatch, okvErrGetDepthForBatch, and okvErrGetNumAtDepthForBatch. The errors for individual batch operations can be checked only before freeing the batch context, that is, before calling okvBatchFree.

Example

/* 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");
}

10.2.3 okvBatchFree

okvBatchFree will mark the end of Oracle Key Vault batching.

Catetory

KMIP batch API

Purpose

okvBatchFree will mark the end of Oracle Key Vault batching. Essentially the memory allocated for complex arguments will be released. Subsequent Oracle Key Vault functions will not be batched unless okvBatchCreate is called again.

Syntax

OKVErrNo okvBatchFree(OKVEnv *env);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.

Return Values

Return Value	Description
OKVErrNo	Oracle Key Vault error number. Success: OKV_SUCCESS (0) is returned. Failure: A valid error number is returned for the error on top of the error stack.

Comments

The errors for individual batch operations can be checked only before freeing the batch context, that is, before calling okvBatchFree.

Example

/* 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");
}

10.2.4 okvGetBatchOperationCount

okvGetBatchOperationCount gets the count of batched Oracle Key Vault operations.

Catetory

KMIP batch API

Purpose

okvGetBatchOperationCount gets the count of batched Oracle Key Vault operations.

Syntax

ub4 okvGetBatchOperationCount(OKVEnv *env);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.

Return Values

Return Value	Description
ub4	Count of the batched operations. Success: A valid positive non-zero number is returned. Failure: Zero.

Comments

This function should be called before calling okvBatchFree else it will return zero.

Example

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);

10.2.5 okvGetBatchOperationName

okvGetBatchOperationName returns the name of the respective batch job number that is passed with this function.

Catetory

KMIP batch API

Purpose

okvGetBatchOperationName returns the name of the respective batch job number that is passed with this function.

Syntax

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

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
batchjobnum	IN	Batch job number.

Return Values

Return Value	Description
oratext *	Batch job operation name. Success: A pointer to batch job operation name is returned. Failure: NULL pointer is returned.

Comments

This function should be called before calling okvBatchFree else it will return a pointer to NULL.

batchjobnum is the number in which the operations are batched. For example, if the user wants to create a key, activate a key, revoke it, and then destroy it, all of these operations are batched in the same order, that is, batchjobnum for create a key is 1, batchjobnum for activate a key is 2, batchjobnum for revoke is 3, and batchjobnum for destroy is 4.

Example

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));
   }
}