13 Oracle Key Vault Extension Operation Management APIs

Oracle Key Vault provides operations used to execute custom KMIP requests.

• About the Oracle Key Vault Client SDK Extension Operation Management APIs
  This section describes the interfaces for Oracle Key Vault operations used to execute custom KMIP requests.
• okvOpsCreate
  okvOpsCreate creates the Oracle Key Vault operation handle that will be used to execute custom KMIP operations.
• okvOpsExecuteOp
  okvOpsExecuteOp executes one or more custom KMIP operations.
• okvOpsFree
  okvOpsFree frees the Oracle Key Vault operation handle.

13.1 About the Oracle Key Vault Client SDK Extension Operation Management APIs

This section describes the interfaces for Oracle Key Vault operations used to execute custom KMIP requests.

13.2 okvOpsCreate

okvOpsCreate creates the Oracle Key Vault operation handle that will be used to execute custom KMIP operations.

Category

KMIP extension operation management API

Purpose

okvOpsCreate is used to create the Oracle Key Vault operation handle which will be used to execute custom KMIP operations.

Syntax

OKVOps *okvOpsCreate(OKVEnv *env, OKVOpsNo ops); 

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle
ops	IN	KMIP operation

Return Values

Return Value	Description
OKVOps*	Oracle Key Vault operation handle. Success: A valid pointer to the Oracle Key Vault operation handle is returned. Failure: A NULL pointer is returned.

Comments

Oracle Key Vault KMIP extension APIs can be used to create custom OKVTTLV request packets that can be sent to the Oracle Key Vault server to get a KMIP response packet. An operation with custom OKVTTLV request packet is a custom KMIP operation.

Oracle Key Vault KMIP extention APIs can also parse the KMIP response. Once the operation is executed, Oracle Key Vault operation handle will also hold the OKVTTLV response packet from the Oracle Key Vault server.

Example

OKVTTLV *req = (OKVTTLV *) NULL;
OKVTTLV *attr_in = (OKVTTLV *)NULL;
...
OKVOps *op = okvOpsCreate(env, OKVOpAddAttribute);
req = okvTTLVGetRequest(env, op);
attr_in = okvAddAttributeObject(env, req, OKVAttrName, 0);
okvAttrAddName(env, attr_in, "XYZ", strlen("XYZ"), 1);
okvAddAttribute(env, uid, &attr_in);

13.3 okvOpsExecuteOp

okvOpsExecuteOp executes one or more custom KMIP operations.

Category

KMIP extension operation management API

Purpose

okvOpsExecuteOp is used to execute one or more custom KMIP operations. The operations are batched and executed.

Syntax

OKVErrNo okvOpsExecuteOp(OKVEnv *env, OKVOps **opsr, ub4 ops_cnt); 

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
opsr	IN	Oracle Key Vault operation handle.
ops_cnt	IN	Count of Oracle Key Vault operation 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

opsr is an array of operations to be batched and executed. ops_cnt is the count of the operations batched.

The error handle will hold the error returned by the Oracle Key Vault server. But this error need not be for all the operations in the operation array. Even if there is an error, the Oracle Key Vault operation handle should be checked for valid response packets.

There is no order to interpret the operation array. The result of the third operation can be processed before that of the first one.

Example

OKVTTLV *req = (OKVTTLV *) NULL;
OKVTTLV *attr_in = (OKVTTLV *)NULL;
OKVTTLV *template;
OKVOps *ops[2];
...
/* First Batch Operation */
ops[0]  = okvOpsCreate(env, OKVOpCreate);
req  = okvTTLVGetRequest(env, ops[0]);
okvAttrAddObjectType(env, req, OKVObjSymmetric);
template = okvTTLVAddToObject(env, req, OKVDEF_TAG_TEMPLATE_ATTR_ST,
                              OKVDEF_ITEM_TYPE_STRUCT, (void *) NULL,
                              (ub4) 0);
attr_in = okvAddAttributeObject(env, template, OKVAttrCryptoAlg, 0);
okvAttrAddCryptoAlgo(env, attr_in, (ub4) CRYPTO_ALG_AES);
attr_in = okvAddAttributeObject(env, template, OKVAttrCryptoLen, 0);
okvAttrAddCryptoLen(env, attr_in, (ub4) 128);
attr_in = okvAddAttributeObject(env, template, OKVAttrCryptoUsageMask, 0);
okvAttrAddCryptoUsageMask(env, attr_in, (ub4) 12);

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

/* Execute Batch Operation */
okvOpsExecuteOp(env, ops, 2);

13.4 okvOpsFree

okvOpsFree frees the Oracle Key Vault operation handle.

Category

KMIP extension operation management API

Purpose

okvOpsFree is used to free the Oracle Key Vault operation handle.

Syntax

void okvOpsFree(OKVEnv *env, OKVOps **ops);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle
ops	IN	Oracle Key Vault operation handle

Return Values

None.

Comments

None.

Example

OKVOps ops  = okvOpsCreate(env, OKVOpCreate);
...
okvOpsFree(env, &ops);