11 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.

11.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.
• okvDecrypt
  okvDecrypt performs the decryption operation on the provided data using KMIP object.
• okvDeleteAttribute
  okvDeleteAttribute implements the KMIP Delete attribute operation.
• okvDestroy
  okvDestroy implements the KMIP Destroy operation.
• okvEncrypt
  okvEncrypt performs the encryption operation on the provided data using KMIP object.
• okvGetAttributeList
  okvGetAttributeList implements KMIP Get attribute list operation.
• okvGetAttributes
  okvGetAttributes implements KMIP Get attribute operation.
• okvGetCertificate
  okvGetCertificate implements the KMIP Get operation for the Certificate object.
• okvGetCertificateRequest
  okvGetCertificateRequest implements the KMIP Get operation for the Certificate request object.
• 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.
• okvGetPrivateKey
  okvGetPrivateKey implements the KMIP Get operation for the KMIP private key object.
• okvGetPublicKey
  okvGetPublicKey implements the KMIP Get operation for the KMIP public key 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.
• okvRegCertificate
  okvRegCertificate implements the KMIP Register operation for the KMIP certificate object.
• okvRegCertificateRequest
  okvRegCertificateRequest implements the KMIP Register operation for the certificate request object.
• 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.
• okvRegPrivateKey
  okvRegPrivateKey implements the KMIP Register operation for the KMIP private key object.
• okvRegPublicKey
  okvRegPublicKey implements the KMIP Register operation for the KMIP public key 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.
• okvSign
  okvSign implements the KMIP Sign operation.
• okvSignVerify
  okvSignVerify implements the KMIP Signature Verify operation.
• okvCreateKeyPair
  okvCreateKeyPair implements the KMIP Create Key Pair operation.

11.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.

11.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 its 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\n");
}

11.1.3 okvAddAttribute

okvAddAttribute implements the KMIP Add attribute operation.

Category

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

11.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 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 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 usage mask 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 */
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");
}

11.1.5 okvDecrypt

okvDecrypt performs the decryption operation on the provided data using KMIP object.

Category

KMIP API

Purpose

okvDecrypt performs the decryption operation on the provided data using KMIP object.

Syntax

OKVErrNo okvDecrypt(OKVEnv *env, oratext *uid, ub1 *data, ub4 datal,
                    OKVCryptoContext *crypto_context,
                    OKVDecryptResponse *decrypt_response);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier (can be NULL for batching).
data	IN	Data to be decrypted.
datal	IN	Length of the data to be decrypted.
crypto_context	IN	Cryptographic context contains required parameters for decryption like cryptographic parameters and IV.
decrypt_response	OUT	Contains the decrypt operation response details.

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.

Supported Versions

Oracle Key Vault C SDK release 21.4.0.0.0 and later.

Comments

crypto_context can be created and freed using okvCryptoContextCreate and okvCryptoContextFree helper APIs. It contains the required parameters for decryption and the user will need to set it explicitly by making use of helper APIs like okvCryptoContextSetBlockCipherMode, okvCryptoContextSetPadding, okvCryptoContextSetRandomIV, okvCryptoContextSetIV, okvCryptoContextSetAuthEncryptionAdditionalData, and okvCryptoContextSetAuthEncryptionTag. The user can also get the respective parameter values that were set in crypto_context using helper APIs okvCryptoContextGetBlockCipherMode, okvCryptoContextGetPadding, okvCryptoContextGetRandomIV, okvCryptoContextGetIV, okvCryptoContextGetAuthEncryptionAdditionalData, and okvCryptoContextGetAuthEncryptionTag.

decrypt_response will need to explicitly be allocated using helper API okvDecryptResponseCreate before passing it as an OUT parameter to okvDecrypt API. Once the decrypt operation is completed, we can get the decrypted data details from decrypt_response using helper API okvCryptoResponseGetDecryptedData. decrypt_response needs to be freed using okvDecryptResponseFree helper API.

Example

/* Create a Symmetric Key for example and get its unique identifier as part of its creation in uid, we can use the 'uid' for decrypting the encrypted data as shown below */

OKVCryptoContext *crypto_context = (OKVCryptoContext *)NULL;
OKVEncryptResponse *encrypt_response = (OKVEncryptResponse *)NULL;
OKVDecryptResponse *decrypt_response = (OKVDecryptResponse *)NULL;
ub1 data[] = "OKV crypto operations demo.";
ub4 datal = strlen((const char *) data);
ub1 iv[] = "5432109876543210";
ub4 ivl = strlen((const char *) iv);
ub1 encrypted_data[100];
ub4 encrypted_datal = sizeof(encrypted_data);
ub1 decrypted_data[100];
ub4 decrypted_datal = sizeof(decrypted_data);

/* Encrypt */
crypto_context = okvCryptoContextCreate(env, OKVOpEncrypt);
okvCryptoContextSetBlockCipherMode(env, crypto_context, BLK_CIPHER_CBC);
okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS5);
okvCryptoContextSetIV(env, crypto_context, iv, ivl);

encrypt_response = okvEncryptResponseCreate(env);

okvEncrypt(env, uid, data, datal, crypto_context, encrypt_response);
if (okvErrGetNum(env))
{
  printf("Error while performing the encryption operation.\n");
}

memset(encrypted_data, 0, encrypted_datal);
okvCryptoResponseGetEncryptedData(env, encrypt_response, encrypted_data, &encrypted_datal);
printf("Successfully encrypted the data\n");
printf("\tEncrypted Data Length: %d\n", encrypted_datal);
printf("\tEncrypted Data: %s\n", encrypted_data);

okvCryptoContextFree(env, &crypto_context);
okvEncryptResponseFree(env, &encrypt_response);


/*Decrypt */
crypto_context = okvCryptoContextCreate(env, OKVOpEncrypt);
okvCryptoContextSetBlockCipherMode(env, crypto_context, BLK_CIPHER_CBC);
okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS5);
okvCryptoContextSetIV(env, crypto_context, iv, ivl);

decrypt_response = okvDecryptResponseCreate(env);
okvDecrypt(env, uid, encrypted_data, encrypted_datal, crypto_context, decrypt_response);
if (okvErrGetNum(env))
{
  printf("Error while performing the decryption operation.\n");
}

memset(decrypted_data, 0, decrypted_datal);
okvCryptoResponseGetDecryptedData(env, decrypt_response, decrypted_data, &decrypted_datal);
printf("Successfully decrypted the data\n");
printf("\tDecrypted Data Length: %d\n", decrypted_datal);
printf("\tDecrypted Data: %s\n", decrypted_data);

okvCryptoContextFree(env, &crypto_context);
okvDecryptResponseFree(env, &decrypt_response);

11.1.6 okvDeleteAttribute

okvDeleteAttribute implements the KMIP Delete attribute operation.

Category

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

11.1.7 okvDestroy

okvDestroy implements the KMIP Destroy operation.

Category

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

11.1.8 okvEncrypt

okvEncrypt performs the encryption operation on the provided data using KMIP object.

Category

KMIP API

Purpose

okvEncrypt performs the encryption operation on the provided data using KMIP object.

Syntax

OKVErrNo okvEncrypt(OKVEnv *env, oratext *uid, ub1 *data, ub4 datal,
                    OKVCryptoContext *crypto_context,
                    OKVEncryptResponse *encrypt_response);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier (can be NULL for batching).
data	IN	Data to be encrypted.
datal	IN	Length of the data to be encrypted.
crypto_context	IN	Cryptographic context contains required parameters for encryption like cryptographic parameters and IV.
encrypt_response	OUT	Contains the encrypt operation response details.

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.

Supported Versions

Oracle Key Vault C SDK release 21.4.0.0.0 and later.

Comments

crypto_context can be created and freed using okvCryptoContextCreate and okvCryptoContextFree helper APIs. It contains the required parameters for encryption and the user will need to set it explicitly by making use of helper APIs like okvCryptoContextSetBlockCipherMode, okvCryptoContextSetPadding, okvCryptoContextSetRandomIV, okvCryptoContextSetIV, okvCryptoContextSetAuthEncryptionAdditionalData, and okvCryptoContextSetAuthEncryptionTag. The user can also get the respective parameter values that was set in crypto_context using helper APIs okvCryptoContextGetBlockCipherMode, okvCryptoContextGetPadding, okvCryptoContextGetRandomIV, okvCryptoContextGetIV, okvCryptoContextGetAuthEncryptionAdditionalData, and okvCryptoContextGetAuthEncryptionTag.

encrypt_response will need to explicitly be allocated using helper API okvEncryptResponseCreate before passing it as an OUT parameter to okvEncrypt API. Once the encrypt operation is completed, we can get the encrypted data details from encrypt_response using helper APIs okvCryptoResponseGetEncryptedData, okvCryptoResponseGetIV, and okvCryptoResponseGetAuthEncryptionTag. encrypt_response needs to be freed using okvEncryptResponseFree helper API.

Example

/* Create a Symmetric Key for example and get its unique identifier as part of its creation in ‘uid’, we can use the 'uid' for encryption as shown below */

OKVCryptoContext *crypto_context = (OKVCryptoContext *)NULL;
OKVEncryptResponse *encrypt_response = (OKVEncryptResponse *)NULL;
ub1 data[] = "OKV crypto operations demo.";
ub4 datal = strlen((const char *) data);
ub1 iv[] = "5432109876543210";
ub4 ivl = strlen((const char *) iv);
ub1 encrypted_data[100];
ub4 encrypted_datal = sizeof(encrypted_data);

/* Encrypt */
crypto_context = okvCryptoContextCreate(env, OKVOpEncrypt);
okvCryptoContextSetBlockCipherMode(env, crypto_context, BLK_CIPHER_CBC);
okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS5);
okvCryptoContextSetIV(env, crypto_context, iv, ivl);

encrypt_response = okvEncryptResponseCreate(env);

okvEncrypt(env, uid, data, datal, crypto_context, encrypt_response);
if (okvErrGetNum(env))
{
  printf("Error while performing the encryption operation.\n");
}

memset(encrypted_data, 0, encrypted_datal);
okvCryptoResponseGetEncryptedData(env, encrypt_response, encrypted_data, &encrypted_datal);
printf("Successfully encrypted the data\n");
printf("\tEncrypted Data Length: %d\n", encrypted_datal);
printf("\tEncrypted Data: %s\n", encrypted_data);

okvCryptoContextFree(env, &crypto_context);
okvEncryptResponseFree(env, &encrypt_response);

11.1.9 okvGetAttributeList

okvGetAttributeList implements KMIP Get attribute list operation.

Category

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 the attributes.
attr_names	OUT	Names of the attributes.

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

11.1.10 okvGetAttributes

okvGetAttributes implements KMIP Get attribute operation.

Category

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 the attributes to be 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");
}

11.1.11 okvGetCertificate

okvGetCertificate implements the KMIP Get operation for the Certificate object.

Category

KMIP API

Purpose

okvGetCertificate implements the KMIP Get operation for the Certificate object.

For the specified unique identifier of the certificate, the certificate type, certificate length, the actual certificate bytes in the endpoint program supplied buffer and the actual length of the certificate bytes are returned.

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

Syntax

OKVErrNo okvGetCertificate(OKVEnv *env, oratext *uid,
                           ub4 *certificate_type,
                           ub1 *certificate, ub4 *certificatel);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier of the certificate (can be NULL for batching).
certificate_type	OUT	Type of certificate.
certificate	OUT	Certificate.
certificatel	OUT	Length of the certificate.

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.

Supported Versions

Oracle Key Vault C SDK version 21.2.0.0.0 and later.

Comments

None.

Example

/* Create a Certificate for example and get its unique
   identifier as part of its creation in 'uid' */
...
ub1 *cert;
ub4  certl = 128001;
ub4  cert_type = 0;
cert = (ub1 *)malloc(certl * sizeof(ub1));

printf("\tGetting the certificate\n");

okvGetCertificate(env, uid, &cert_type, cert, &certl);

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

/* Free 'cert' */

11.1.12 okvGetCertificateRequest

okvGetCertificateRequest implements the KMIP Get operation for the Certificate request object.

Category

KMIP API

Purpose

okvGetCertificateRequest implements the KMIP Get operation for the Certificate request object.

For the specified unique identifier of the certificate request, the certificate request type, certificate request length, the actual certificate request bytes in the endpoint program supplied buffer and the actual length of the certificate request bytes are returned.

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

Syntax

OKVErrNo okvGetCertificateRequest(OKVEnv *env, oratext *uid,
                                  ub4 *certificate_request_type,
                                  ub1 *certificate_request,
                                  ub4 *certificate_requestl);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier of the certificate request (can be NULL for batching).
certificate_request_type	OUT	Type of certificate request.
certificate_request	OUT	Certificate request.
certificate_requestl	OUT	Length of the certificate request.

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.

Supported Versions

Oracle Key Vault C SDK version 21.2.0.0.0 and later.

Comments

None.

Example

/* Create a Certificate Request for example and get its unique
   identifier as part of its creation in 'uid' */
...
ub1 *cert_req;
ub4  cert_reql = 128001;
ub4  cert_req_type = 0;

cert_req = (ub1 *)malloc(cert_reql * sizeof(ub1));
printf("\tGetting the certificate request\n");

okvGetCertificateRequest(env, uid, &cert_req_type, cert_req,
                         &cert_reql);

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

/* Free 'cert_req' */

11.1.13 okvGetKey

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

Category

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' */
...
ub1 *key;
ub4 keyl = 128001;
ub4 key_algo = 0;
ub4 key_len = 0;
key = (ub1 *)malloc(keyl * sizeof(ub1));
printf("\tGetting the key\n");
okvGetKey(env, uid, &key_algo, &key_len, key, &keyl);
key[keyl] = 0;

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

/* Free ‘key’ */

11.1.14 okvGetOpaqueData

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

Category

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     *opaque_data;
ub4      opaque_data_len = 128001;
ub4      opaque_data_type = 0;
opaque_data = (ub1 *)malloc(opaque_data_len*sizeof(ub1));

okvGetOpaqueData(env, &uid[0], &opaque_data_type, &opaque_data[0], &opaque_data_len);

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

/* Free "opaque_data" */

11.1.15 okvGetPrivateKey

okvGetPrivateKey implements the KMIP Get operation for the KMIP private key object.

Category

KMIP API

Purpose

okvGetPrivateKey implements the KMIP Get operation for the KMIP private key object.

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

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

Syntax

OKVErrNo okvGetPrivateKey(OKVEnv *env, oratext *uid,
                          ub4 *private_key_alg, ub4 *private_key_len,
                          ub1 *private_key, ub4 *private_keyl);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier of the private key (can be NULL for batching).
private_key_alg	OUT	Private key algorithm.
private_key_len	OUT	Key length of the private key provided at the time of creation.
private_key	OUT	Private key.
private_keyl	OUT	Length of the private 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.

Supported Versions

Oracle Key Vault C SDK version 21.2.0.0.0 and later.

Comments

None.

Example

/* Create a Private Key for example and get its unique
   identifier as part of its creation in 'uid' */
...
ub1 *private_key;
ub4  private_keyl = 128001;
ub4  private_key_algo = 0;
ub4  private_key_len = 0;
private_key = (ub1 *)malloc(private_keyl * sizeof(ub1));

printf("\tGetting the private key\n");

okvGetPrivateKey(env, uid, &private_key_algo, &private_key_len,
                 private_key, &private_keyl);

private_key[private_keyl] = 0;

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

/* Free 'private_key' */

11.1.16 okvGetPublicKey

okvGetPublicKey implements the KMIP Get operation for the KMIP public key object.

Category

KMIP API

Purpose

okvGetPublicKey implements the KMIP Get operation for the KMIP public key object.

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

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

Syntax

OKVErrNo okvGetPublicKey(OKVEnv *env, oratext *uid,
                         ub4 *public_key_alg, ub4 *public_key_len,
                         ub1 *public_key, ub4 *public_keyl);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier of the public key (can be NULL for batching).
public_key_alg	OUT	Public key algorithm.
public_key_len	OUT	Key length of the public key provided at the time of creation.
public_key	OUT	Public key.
public_keyl	OUT	Length of the public 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.

Supported Versions

Oracle Key Vault C SDK version 21.2.0.0.0 and later.

Comments

None.

Example

/* Create a Public Key for example and get its unique
   identifier as part of its creation in 'uid' */
...
ub1 *public_key;
ub4  public_keyl = 128001;
ub4  public_key_algo = 0;
ub4  public_key_len = 0;
public_key = (ub1 *)malloc(public_keyl * sizeof(ub1));

printf("\tGetting the public key\n");

okvGetPublicKey(env, uid, &public_key_algo, &public_key_len,
                public_key, &public_keyl);

public_key[public_keyl] = 0;

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

/* Free 'public_key' */

11.1.17 okvGetSecretData

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

Category

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 *secret_data;
ub4 secret_data_len = 128001;
ub4 secret_data_type = 0;
secret_data = (ub1 *)malloc(secret_data_len*sizeof(ub1));

okvGetSecretData(env, &uid[0], &secret_data_type, &secret_data[0], &secret_data_len);

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

/* Free "secret_data" */

11.1.18 okvGetTemplate

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

Category

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.

For each create or register operation that uses retrieved attributes of the template object, okvGetTemplate should be used before that operation.

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

11.1.19 okvLocate

okvLocate implements the KMIP Locate operation.

Category

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

11.1.20 okvModifyAttribute

okvModifyAttribute implements the KMIP Modify attribute operation.

Category

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 of the KMIP object that needs to be modified.

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

11.1.21 okvQueryCapability

okvQueryCapability implements the KMIP Query operation.

Category

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

11.1.22 okvRegCertificate

okvRegCertificate implements the KMIP Register operation for the KMIP certificate object.

Category

KMIP API

Purpose

okvRegCertificate implements the KMIP Register operation for the KMIP certificate object.

The certificate of a specific type is registered with Oracle Key Vault Server. The unique identifier of the certificate 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.

The new certificate being registered 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 okvRegCertificate(OKVEnv *env,
                           ub4 certificate_type, ub4 certificate_subtype,
                           ub1 *certificate, ub4 certificatel,
                           ub4 mask, OKVTTLV *template_names_attrs,
                           oratext *private_key_uid, 
                           ub4 private_key_uidl,
                           oratext *wallet_name, ub4 wallet_namel,
                           oratext *ouid, ub4 *ouidl);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
certificate_type	IN	Certificate type.
certificate_subtype	IN	Certificate sub-type.
certificate	IN	Certificate.
certificatel	IN	Certificate length.
mask	IN	Cryptographic usage mask of the certificate.
template_names_attrs	IN	Template names or attributes that will form the template-attribute.
private_key_uid	IN	Unique identifier of the private key associated with the certificate (optional).
private_key_uidl	IN	Unique identifier length of the private key associated with the certificate (optional).
wallet_name	IN	Wallet name value.
wallet_namel	IN	Length of the wallet name value.
ouid	OUT	Unique identifier of the registered certificate.
ouidl	OUT	Unique identifier length of the registered certificate.

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.

Supported Versions

Oracle Key Vault C SDK version 21.2.0.0.0 and later.

Comments

It is recommended to add a KMIP name attribute to certificate 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.

The certificate being registered can optionally be associated with a private key by providing the UID of the private key (private_key_uid). Validate the existence of private_key_uid by performing a locate operation (using okvLocate API) before passing it as an argument to this API.

Allowed values of the certificate_subtype argument:

• OKV_CERT_SUBTYPE_USER_CERT: represents User Certificate.
• OKV_CERT_SUBTYPE_TRUSTPOINT: represents Trustpoint.

The certificate 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

/* X.509 Certificate type */
ub4      cert_type = OKVDEF_CERT_TYPE_X509;

/* Certificate Subtype */
ub4      cert_subtype = OKV_CERT_SUBTYPE_USER_CERT;

/* Usage mask */
ub4      cert_mask = CRYPTO_MASK_ENCRYPT;
ub1      cert[] = "-----BEGIN CERTIFICATE-----
MIIEvQIBADANBgkqhkiG9w0BAQE………………………………….
-----END CERTIFICATE-----";
ub4      certl = strlen((const char *)cert);
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 Certificate for Register operation",
               strlen("My Certificate for Register operation"), 1);

okvRegCertificate(env, cert_type, cert_subtype,
           cert, certl, 
           cert_mask , template,
           (oratext *)NULL, (ub4)0,
           OKV_NO_WALLET, OKV_NO_WALLET_LEN,
           uid, &uidl);

uid[*uidl] = '\0';

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

11.1.23 okvRegCertificateRequest

okvRegCertificateRequest implements the KMIP Register operation for the certificate request object.

Category

KMIP API

Purpose

okvRegCertificateRequest implements the KMIP Register operation for the certificate request object.

The certificate request object is registered as an opaque object with Oracle Key Vault Server. The unique identifier of the certificate request 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.

The new certificate request being registered 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 okvRegCertificateRequest(OKVEnv *env,
                                  ub4 certificate_request_type,
                                  ub1 *certificate_request,
                                  ub4 certificate_requestl,
                                  OKVTTLV *template_names_attrs,
                                  oratext *private_key_uid,
                                  ub4 private_key_uidl,
                                  oratext *wallet_name, ub4 wallet_namel,
                                  oratext *ouid, ub4 *ouidl);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
certificate_request_type	IN	Certificate request type.
certificate_request	IN	Certificate request.
certificate_requestl	IN	Certificate request length.
template_names_attrs	IN	Template names or attributes that will form the template-attribute.
private_key_uid	IN	Unique identifier of the private key associated with the certificate request (mandatory).
private_key_uidl	IN	Unique identifier length of the private key associated with the certificate request (mandatory).
wallet_name	IN	Wallet name value.
wallet_namel	IN	Length of the wallet name value.
ouid	OUT	Unique identifier of the registered certificate request.
ouidl	OUT	Unique identifier length of the registered certificate request.

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.

Supported Versions

Oracle Key Vault C SDK version 21.2.0.0.0 and later.

Comments

It is recommended to add a KMIP name attribute to certificate request 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.

The certificate request being registered should be associated with a private key by providing the UID of the private key (private_key_uid). Validate the existence of private_key_uid by performing a locate operation (using okvLocate API) before passing it as an argument to this API.

The certificate request 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

/* Certificate Request type */
ub4      cert_req_type = OKVDEF_CERT_REQ_TYPE_PEM;
ub1      cert_req[] = "-----BEGIN CERTIFICATE REQUEST-----
MIIEvQIBADANBgkqhkiG9w0BAQE………………………………….
-----END CERTIFICATE REQUEST-----";
ub4      cert_reql = strlen((const char *)cert_req);
oratext  uid[OKV_UNIQUE_ID_MAXLEN + 1];
ub4      uidl = sizeof(uid);
OKVTTLV *template = (OKVTTLV *)NULL;
OKVTTLV *attr_in = (OKVTTLV *)NULL;

/* Please make sure to pass a valid Private Key UID */
oratext *private_key_uid = "64281937-768D-4F78-BF39-EBD5985BFAB2";
ub4      private_key_uidl = strlen((const char *)private_key_uid);

/* 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 Certificate Request for Register operation",
               strlen("My Certificate Request for Register operation"), 1);

okvRegCertificateRequest(env, cert_req_type,
                   cert_req, cert_reql, template,
                   private_key_uid, private_key_uidl,
                   OKV_NO_WALLET, OKV_NO_WALLET_LEN,
                   uid, &uidl);

uid[*uidl] = '\0';

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

11.1.24 okvRegKey

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

Category

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 usage mask 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 key.
ouidl	OUT	Unique identifier length of the registered 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");
}

11.1.25 okvRegOpaqueData

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

Category

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

11.1.26 okvRegPrivateKey

okvRegPrivateKey implements the KMIP Register operation for the KMIP private key object.

Category

KMIP API

Purpose

okvRegPrivateKey implements the KMIP Register operation for the KMIP private key object.

The unique identifier of the private key object registered 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 private key being registered 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 okvRegPrivateKey(OKVEnv *env,
                          OKVType private_key_alg, ub4 private_key_len,
                          ub1 *private_key, ub4 private_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.
private_key_alg	IN	Private key algorithm.
private_key_len	IN	Key length of the private key.
private_key	IN	Private key.
private_keyl	IN	Private key length.
mask	IN	Cryptographic usage mask of the private 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 private key.
ouidl	OUT	Unique identifier length of the registered private 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.

Supported Versions

Oracle Key Vault C SDK version 21.2.0.0.0 and later.

Comments

It is recommended to add a KMIP name attribute to private 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 private 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

/* Key Algorithm */
OKVType  private_key_algo = CRYPTO_ALG_RSA;

/* Key Size */
ub4      private_key_len = 2048;
ub1      private_key[] = "45687942323587........";
ub4      private_keyl = strlen((const char *)private_key);

/* Usage mask */
ub4      private_key_mask = 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 request handle */
attr_in = okvAddAttributeObject(env, template, OKVAttrName, (ub4) 0);

/* Add name attribute value to name attribute object */
okvAttrAddName(env, attr_in, (oratext *)"My Private Key for Register operation",
               strlen("My Private Key for Register operation"), 1);

okvRegPrivateKey(env, private_key_algo, private_key_len,
                 private_key, private_keyl,
                 private_key_mask, template,
                 OKV_NO_WALLET, OKV_NO_WALLET_LEN,
                 uid, &uidl);

uid[*uidl] = '\0';

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

11.1.27 okvRegPublicKey

okvRegPublicKey implements the KMIP Register operation for the KMIP public key object.

Category

KMIP API

Purpose

okvRegPublicKey implements the KMIP Register operation for the KMIP public key object.

The unique identifier of the public key object registered 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 public key being registered 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 okvRegPublicKey(OKVEnv *env,
                         OKVType public_key_alg, ub4 public_key_len,
                         ub1 *public_key, ub4 public_keyl,
                         ub4 mask, OKVTTLV *template_names_attrs,
                         oratext *private_key_uid, ub4 private_key_uidl,
                         oratext *wallet_name, ub4 wallet_namel,
                         oratext *ouid, ub4 *ouidl);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
public_key_alg	IN	Public key algorithm.
public_key_len	IN	Key length of the public key.
public_key	IN	Public key.
public_keyl	IN	Public key length.
mask	IN	Cryptographic usage mask of the public key.
template_names_attrs	IN	Template names or attributes that will form the template-attribute.
private_key_uid	IN	Unique identifier of the private key associated with the public key (optional).
private_key_uidl	IN	Unique identifier length of the private key associated with the public key (optional).
wallet_name	IN	Wallet name value.
wallet_namel	IN	Length of the wallet name value.
ouid	OUT	Unique identifier of the registered public key.
ouidl	OUT	Unique identifier length of the registered public 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.

Supported Versions

Oracle Key Vault C SDK version 21.2.0.0.0 and later.

Comments

It is recommended to add a KMIP name attribute to public 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 public 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.

The public key being registered can be optionally associated with a private key by providing the UID of the private key (private_key_uid). Validate the existence of private_key_uid by performing a locate operation (using okvLocate API) before passing it as an argument to this API.

Example

/* Key Algorithm */
OKVType  public_key_algo = CRYPTO_ALG_RSA;

/* Key Size */
ub4      public_key_len = 2048;
ub1      public_key[] = "7698767245345566789823428...........";
ub4      public_keyl = strlen((const char *)public_key);

/* Usage mask */
ub4      public_key_mask = CRYPTO_MASK_ENCRYPT;
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 Public Key for Register operation",
               strlen("My Public Key for Register operation"), 1);

okvRegPublicKey(env, public_key_algo, public_key_len,
          public_key, public_keyl,
          public_key_mask, template,
          (oratext *)NULL, (ub4)0,
          OKV_NO_WALLET, OKV_NO_WALLET_LEN,
          uid, &uidl);

uid[*uidl] = '\0';

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

11.1.28 okvRegSecretData

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

Category

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 usage mask of the secret.
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");
}

11.1.29 okvRegTemplate

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

Category

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

11.1.30 okvRekey

okvRekey implements the KMIP Rekey operation.

Category

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 newly 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 the Key\n");
}

11.1.31 okvRevoke

okvRevoke implements the KMIP Revoke operation.

Category

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

11.1.32 okvSign

okvSign implements the KMIP Sign operation.

Category

KMIP API

Purpose

okvSign performs the sign operation on the provided data using a KMIP object.

Syntax

OKVErrNo okvSign(OKVEnv *env, oratext *uid,
                 ub1 *data, ub4 datal, ub4 data_type,
                 OKVCryptoContext *crypto_context,
                 OKVSignResponse *sign_response);

Parameters

Table 11-1 Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier (can be NULL for batching).
data	IN	Data to be signed.
datal	IN	Length of the data to be signed.
data_type	IN	Type of the data to be signed, either OKV_DATA_TYPE_RAW or OKV_DATA_TYPE_DIGEST.
crypto_context	IN	Cryptographic context contains required parameters for signing like the cryptographic algorithm and hashing algorithm.
sign_response	OUT	Contains the sign operation response details.

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.

Supported Versions

Oracle Key Vault C SDK release 21.6.0.0.0 and later.

Comments

crypto_context can be created and freed using okvCryptoContextCreate and okvCryptoContextFree helper APIs. It contains the required parameters for signing and the user will need to set it explicitly by making use of helper APIs like okvCryptoContextSetCryptoAlgo, okvCryptoContextSetHashingAlgo, okvCryptoContextSetPadding, and okvCryptoContextSetDigitalSignAlgo. The user can also get the respective parameter values that was set in crypto_context using helper APIs okvCryptoContextGetCryptoAlgo, okvCryptoContextGetHashingAlgo, okvCryptoContextGetPadding, and okvCryptoContextGetDigitalSignAlgo.

sign_response will need to explicitly be allocated using helper API okvSignResponseCreate before passing it as an OUT parameter to okvSign API. Once the sign operation is completed, we can get the signature data details from sign_response using helper API okvCryptoResponseGetSignatureData. sign_response needs to be freed using okvSignResponseFree helper API.

Example

  OKVCryptoContext *crypto_context = (OKVCryptoContext *)NULL;
  OKVSignResponse *sign_response = (OKVSignResponse *)NULL;
  ub1 data[] = "OKV signature operations demo.";
  ub4 datal = strlen((const char *) data);
  ub1 signature_data[OKV_OBJECT_MAXLEN];
  ub4 signature_datal = sizeof(signature_data);

  /* Sign */
  crypto_context = okvCryptoContextCreate(env, OKVOpSign);
  okvCryptoContextSetCryptoAlgo(env, crypto_context, CRYPTO_ALG_RSA);
  okvCryptoContextSetHashingAlgo(env, crypto_context, HASH_ALG_SHA_256);
  okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS1_V1_5);
  sign_response = okvSignResponseCreate(env);
  okvSign(env, private_key_unique_id, data, datal, OKV_DATA_TYPE_RAW,
          crypto_context, sign_response);

  memset(signature_data, 0, signature_datal);
  okvCryptoResponseGetSignatureData(env, sign_response, signature_data,
                                    &signature_datal);

11.1.33 okvSignVerify

okvSignVerify implements the KMIP Signature Verify operation.

Category

KMIP API

Purpose

okvSignVerify performs the signature verify operation on the provided data and signature using a KMIP object.

Syntax

OKVErrNo okvSignVerify(OKVEnv *env, oratext *uid,
                       ub1 *data, ub4 datal, ub4 data_type,
                       ub1 *signature_data, ub4 signature_datal,
                       OKVCryptoContext *crypto_context,
                       OKVSignVerifyResponse *sign_verify_response);

Parameters

Table 11-2 Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
uid	IN	Unique identifier (can be NULL for batching).
data	IN	The data that was signed.
datal	IN	Length of the data that was signed.
data_type	IN	Type of the data that was signed, either OKV_DATA_TYPE_RAW or OKV_DATA_TYPE_DIGEST.
signature_data	IN	Signature to be verified.
signature_datal	IN	Length of the signature.
crypto_context	IN	Cryptographic context contains required parameters for signature verification like the cryptographic algorithm and hashing algorithm.
sign_verify_response	OUT	Contains the sign operation response details.

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.

Supported Versions

Oracle Key Vault C SDK release 21.6.0.0.0 and later.

Comments

crypto_context can be created and freed using okvCryptoContextCreate and okvCryptoContextFree helper APIs. It contains the required parameters for verifying a signature and the user will need to set it explicitly by making use of helper APIs like okvCryptoContextSetCryptoAlgo, okvCryptoContextSetHashingAlgo, okvCryptoContextSetPadding, and okvCryptoContextSetDigitalSignAlgo. The user can also get the respective parameter values that was set in crypto_context using helper APIs okvCryptoContextGetCryptoAlgo, okvCryptoContextGetHashingAlgo, okvCryptoContextGetPadding, and okvCryptoContextGetDigitalSignAlgo. sign_verify_response will need to explicitly be allocated using helper API okvSignVerifyResponseCreate before passing it as an OUT parameter to okvSignVerify API. Once the signature verify operation is completed, we can get the verification details from sign_verify_response using helper APIs okvCryptoResponseGetValidity and okvCryptoResponseGetRecoveredData. sign_verify_response needs to be freed using okvSignVerifyResponseFree helper API.

Example

OKVCryptoContext *crypto_context = (OKVCryptoContext *)NULL;
OKVSignResponse *sign_response = (OKVSignResponse *)NULL;
OKVSignVerifyResponse *verify_response = (OKVSignVerifyResponse *)NULL;
ub1 data[] = "OKV signature operations demo.";
ub4 datal = strlen((const char *) data);
ub4 iter = 0;
ub1 signature_data[OKV_OBJECT_MAXLEN];
ub4 signature_datal = sizeof(signature_data);
ub4 validity = 0;

/* Sign */
crypto_context = okvCryptoContextCreate(env, OKVOpSign);
okvCryptoContextSetCryptoAlgo(env, crypto_context, CRYPTO_ALG_RSA);
okvCryptoContextSetHashingAlgo(env, crypto_context, HASH_ALG_SHA_256);
okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS1_V1_5);
sign_response = okvSignResponseCreate(env);
okvSign(env, private_key_unique_id, data, datal, OKV_DATA_TYPE_RAW, crypto_context, sign_response);
memset(signature_data, 0, signature_datal);
okvCryptoResponseGetSignatureData(env, sign_response, signature_data, &signature_datal);

printf("Successfully signed the data\n");
printf("\tSignature Data Length: %d\n", signature_datal);
printf("\tSignature Data: ");
for (iter = 0; iter < signature_datal; iter++) 
{
  printf("%02X", signature_data[iter]);
}
printf("\n");

okvCryptoContextFree(env, &crypto_context);
okvSignResponseFree(env, &sign_response);

/* Verify */
crypto_context = okvCryptoContextCreate(env, OKVOpSignVerify);
okvCryptoContextSetCryptoAlgo(env, crypto_context, CRYPTO_ALG_RSA);
okvCryptoContextSetHashingAlgo(env, crypto_context, HASH_ALG_SHA_256);
okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS1_V1_5);
verify_response = okvSignVerifyResponseCreate(env);
okvSignVerify(env, public_key_unique_id, data, datal, OKV_DATA_TYPE_RAW, signature_data, signature_datal, crypto_context, verify_response);
okvCryptoResponseGetValidity(env, verify_response, &validity);

if (validity == OKVDEF_VALIDITY_VALID)
{
  printf("Signature is valid\n\n");
}
else if (validity == OKVDEF_VALIDITY_INVALID)
{
  printf("Signature is invalid\n\n");
}
else
{
  printf("Signature validity is unknown\n\n");
}

okvCryptoContextFree(env, &crypto_context);
okvSignVerifyResponseFree(env, &verify_response);

11.1.34 okvCreateKeyPair

okvCreateKeyPair implements the KMIP Create Key Pair operation.

Category

KMIP API

Purpose

okvCreateKeyPair implements the KMIP Create Pair operation. The unique identifiers of the generated key pair by the Oracle Key Vault server is returned as private_key_uid and public_key_uid. The maximum length of the unique ID for Oracle Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN.

Syntax

OKVErrNo okvCreateKeyPair(OKVEnv *env,
                          OKVType alg, ub4 len,
                          ub4 private_key_mask, ub4 public_key_mask,
                          OKVTTLV *common_template_names_attrs,
                          OKVTTLV *private_key_template_names_attrs,
                          OKVTTLV *public_key_template_names_attrs,
                          oratext *wallet_name, ub4 wallet_namel,
                          oratext *private_key_uid, ub4 *private_key_uidl,
                          oratext *public_key_uid, ub4 *public_key_uidl);

Parameters

Table 11-3 Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
alg	IN	Asymmetric key algorithm.
len	IN	Key length of the asymmetric key algorithm.
private_key_mask	IN	Cryptographic usage mask of the private key.
public_key_mask	IN	Cryptographic usage mask of the public key.
common_template_names_attrs	IN	Template names or attributes that are common to both public and private keys and will form the common template-attribute.
private_key_template_names_attrs	IN	Template names or attributes of private key and will form the private key template-attribute.
public_key_template_names_attrs	IN	Template names or attributes of public key that will form the public key template-attribute.
wallet_name	IN	Wallet name value.
wallet_namel	IN	Length of the wallet name value.
private_key_uid	OUT	Unique identifier of the generated private key.
private_key_uidl	OUT	Unique identifier length of the generated private key.
public_key_uid	OUT	Unique identifier of the generated public key.
public_key_uidl	OUT	Unique identifier length of the generated public 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.

Supported Versions

Oracle Key Vault C SDK release 21.6.0.0.0 and later.

Comments

It is recommended to add a KMIP custom or name attribute to both the private and public key objects to help identify it in future. The caller has to allocate the memory for the unique identifiers returned by this function. The length of allocated memory is passed in via the length of the unique identifier arguments private_key_uidl and public_key_uidl. A public and private key pair 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 key pair */

OKVType   algo = CRYPTO_ALG_RSA;
ub4       key_len = 2048;
ub4       pri_key_usage_mask = CRYPTO_MASK_SIGN;
ub4       pub_key_usage_mask = CRYPTO_MASK_VERIFY;

OKVTTLV  *request = (OKVTTLV *)NULL;
OKVTTLV  *pri_key_attr = (OKVTTLV *)NULL;
OKVTTLV  *pub_key_attr = (OKVTTLV *)NULL;
OKVTTLV  *pri_key_attr_name_template = (OKVTTLV *)NULL;
OKVTTLV  *pub_key_attr_name_template = (OKVTTLV *)NULL;
oratext   pri_key_unique_id[OKV_UNIQUE_ID_MAXLEN + 1];
ub4       pri_key_unique_id_len = sizeof(pri_key_unique_id);
oratext   pub_key_unique_id[OKV_UNIQUE_ID_MAXLEN + 1];
ub4       pub_key_unique_id_len = sizeof(pub_key_unique_id);


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

request = okvEnvGetOpRequestObj(env);

/* Add name attribute object to both private and public template attribute */

pri_key_attr_name_template = okvTTLVAddToObject(env, request, OKVDEF_TAG_PRIVATE_KEY_TEMPLATE_ATTR_ST, OKVDEF_ITEM_TYPE_STRUCT, (void *)NULL, (ub4)0);
pri_key_attr = okvAddAttributeObject(env, pri_key_attr_name_template, OKVAttrName, (ub4)0);
okvAttrAddName(env, pri_key_attr, (oratext *) "Private Key", strlen("Private Key"), 1);

pub_key_attr_name_template = okvTTLVAddToObject(env, request, OKVDEF_TAG_PUBLIC_KEY_TEMPLATE_ATTR_ST, OKVDEF_ITEM_TYPE_STRUCT, (void *)NULL, (ub4)0);
pub_key_attr = okvAddAttributeObject(env, pub_key_attr_name_template, OKVAttrName, (ub4)0);
okvAttrAddName(env, pub_key_attr, (oratext *) "Public Key", strlen("Public Key"), 1);

printf("\nCreating a Key Pair on Oracle Key Vault server\n");

okvCreateKeyPair(env, algo, key_len, pri_key_usage_mask, pub_key_usage_mask, (OKVTTLV *)NULL, pri_key_attr_name_template, pub_key_attr_name_template, OKV_NO_WALLET, OKV_NO_WALLET_LEN, pri_key_unique_id, &pri_key_unique_id_len, pub_key_unique_id, &pub_key_unique_id_len);
pri_key_unique_id[pri_key_unique_id_len] = '\0';
pub_key_unique_id[pub_key_unique_id_len] = '\0';

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

11.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 KMIP operation name of the respective batch job number that is passed with this function.

11.2.1 okvBatchCreate

okvBatchCreate will mark the start of Oracle Key Vault batching.

Category

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 APIs from this point will be batched */

11.2.2 okvBatchExecute

okvBatchExecute will execute the batched Oracle Key Vault functions.

Category

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 KMIP APIs from this point will be batched */
...
printf("Executing batch operation\n");
okvBatchExecute(env);

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

11.2.3 okvBatchFree

okvBatchFree will mark the end of Oracle Key Vault batching.

Category

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 KMIP APIs from this point 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");
}

11.2.4 okvGetBatchOperationCount

okvGetBatchOperationCount gets the count of batched Oracle Key Vault operations.

Category

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 KMIP APIs from this point will be batched */
...
printf("\t\tExecuting batch operation\n");
okvBatchExecute(env);
...
/* Check for Individual Batch Operation errors */
...
batch_cnt = okvGetBatchOperationCount(env);
printf("Count of the KMIP operations that are batched: %d", batch_cnt);

11.2.5 okvGetBatchOperationName

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

Category

KMIP Batch API

Purpose

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

Syntax

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

Parameters

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

Return Values

Return Value	Description
oratext *	KMIP operation name that was batched. 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.

batch_job_no 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, batch_job_no for create a key is 1, batch_job_no for activate a key is 2, batch_job_no for revoke is 3, and batch_job_no 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 KMIP APIs from this point 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));
   }
}