Oracle Key Vault Client SDK TTLV Object APIs

The SDK TTLV object APIs enable you to perform activities such as getting the child of an OKVTTLV object.

• About the Oracle Key Vault Client SDK TTLV Object APIs

  Oracle Key Vault provides interfaces for the Oracle Key Vault KMIP parser and builder, which help build the OKVTTLV objects and help parse them.

• okvTTLVAddToObject

  okvTTLVAddToObject creates an OKVTTLV object and makes this object a child object of the OKVTTLV parent object.

• okvTTLVAddToObjectByTag

  okvTTLVAddToObjectByTag creates an OKVTTLV object and makes this object a child object of the OKVTTLV parent object.

• okvTTLVGetChild

  okvTTLVGetChild retrieves a child OKVTTLV object from the OKVTTLV object at the given element index.

• okvTTLVGetChildByTag

  okvTTLVGetChildByTag retrieves a child OKVTTLV object from the OKVTTLV object with the specified tag.

• okvTTLVGetChildCount

  okvTTLVGetChildCount returns the number of child OKVTTLV objects of the specified OKVTTLV parent object.

• okvTTLVGetChildCountByTag

  okvTTLVGetChildCountByTag will return the number of child OKVTTLV objects of the specified OKVTTLV parent object that have the given tag.

• okvTTLVGetFirstChildByTag

  okvTTLVGetFirstChildByTag retrieves the first child of the OKVTTLV object that has the specified tag.

• okvTTLVGetLen

  okvTTLVGetLen returns the length of the value of the OKVTTLV object.

• okvTTLVGetRequest

  okvTTLVGetRequest returns the OKVTTLV request object of the operation.

• okvTTLVGetResponse

  okvTTLVGetResponse returns the OKVTTLV response object of the custom KMIP operation.

• okvTTLVGetTag

  okvTTLVGetTag returns the tag value of the OKVTTLV object.

• okvTTLVGetType

  okvTTLVGetType returns the type value of the OKVTTLV object.

• okvTTLVGetValue

  okvTTLVGetValue returns the pointer to the value of the OKVTTLV object.

• okvTTLVGetValueCopy

  okvTTLVGetValueCopy copies the value of the OKVTTLV object into the supplied buffer.

About the Oracle Key Vault Client SDK TTLV Object APIs

Oracle Key Vault provides interfaces for the Oracle Key Vault KMIP parser and builder, which help build the OKVTTLV objects and help parse them.

TTLV stands for tag type length value. The element and attribute indexes used in the Oracle Key Vault SDK TTLV object APIs have same meaning as the Oracle Key Vault KMIP attribute APIs.

Related Topics

• About the Oracle Key Vault KMIP Attribute APIs

okvTTLVAddToObject

okvTTLVAddToObject creates an OKVTTLV object and makes this object a child object of the OKVTTLV parent object.

Category

KMIP extension TTLV object API

Purpose

okvTTLVAddToObject will create an OKVTTLV object and make the newly created OKVTTLV object a child object of the OKVTTLV parent object.

Syntax

OKVTTLV *okvTTLVAddToObject(OKVEnv *env, OKVTTLV *ttlv,
                            OKVTag tag, OKVType typ, void *val, ub4 len);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
ttlv	IN	OKVTTLV parent object.
tag	IN	Tag of the OKVTTLV object.
typ	IN	Type of the OKVTTLV object.
val	IN	Value of the OKVTTLV object.
len	IN	Length of value of the OKVTTLV object.

Return Values

Return Value	Description
OKVTTLV*	OKVTTLV object. Success: A valid pointer to the created OKVTTLV object is returned. Failure: A NULL pointer is returned.

Comments

None.

Example

OKVTTLV *req = (OKVTTLV *) NULL;
OKVTTLV *template;
...
OKVOps *ops  = okvOpsCreate(env, OKVOpCreate);
req  = okvTTLVGetRequest(env, ops);
...
template = okvTTLVAddToObject(env, req, OKVDEF_TAG_TEMPLATE_ATTR_ST,
                              OKVDEF_ITEM_TYPE_STRUCT, (void *) NULL,
                              (ub4) 0);

Related Topics

• okvTTLVAddToObjectByTag

okvTTLVAddToObjectByTag

okvTTLVAddToObjectByTag creates an OKVTTLV object and makes this object a child object of the OKVTTLV parent object.

Category

KMIP extension TTLV object API

Purpose

okvTTLVAddToObjectByTag will create an OKVTTLV object and make the newly created OKVTTLV object a child object of the OKVTTLV parent object.

Syntax

OKVTTLV *okvTTLVAddToObjectByTag(OKVEnv *env, OKVTTLV *ttlv,
                                 OKVTag tag, void *val, ub4 len);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle
ttlv	IN	OKVTTLV parent object
tag	IN	Tag of the OKVTTLV object
val	IN	Value of the OKVTTLV object
len	IN	Length of the value of the OKVTTLV object

Return Values

Return Value	Description
OKVTTLV*	OKVTTLV object Success: A valid pointer to the created OKVTTLV object is returned. Failure: A NULL pointer is returned.

Comments

The difference between okvTTLVAddToObjectByTag and okvTTLVAddToObject is that okvTTLVAddToObjectByTag will try to interpret the type from the tag. This can be done most of the times but not always.

Example

OKVTTLV *req = (OKVTTLV *) NULL;
OKVTTLV *template;
...
OKVOps *ops  = okvOpsCreate(env, OKVOpCreate);
req  = okvTTLVGetRequest(env, ops);
...
template = okvTTLVAddToObjectByTag(env, req,
                                   OKVDEF_TAG_TEMPLATE_ATTR_ST,
                                   (void *) NULL, (ub4) 0);

Related Topics

• okvTTLVAddToObject

okvTTLVGetChild

okvTTLVGetChild retrieves a child OKVTTLV object from the OKVTTLV object at the given element index.

Category

KMIP extension TTLV object API

Purpose

okvTTLVGetChild retrieves a child OKVTTLV object from the OKVTTLV object at the given element index. The tag and type of the OKVTTLV object and length of the value of the OKVTTLV object are also returned.

Syntax

OKVTTLV *okvTTLVGetChild(OKVEnv *env, OKVTTLV *ttlv,
                         ub4 elem_index,
                         OKVTag *tag, OKVType *typ, ub4 *len);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle
ttlv	IN	OKVTTLV parent object
elem_index	IN	Element index of the child OKVTTLV object
tag	OUT	Tag of the child OKVTTLV object being retrieved
typ	OUT	Type of the OKVTTLV object being retrieved
len	OUT	Length of the value of the OKVTTLV object

Return Values

Return Value	Description
OKVTTLV*	Child OKVTTLV object at element index elem_index. Success: A valid pointer to the child OKVTTLV object at element index elem_index is returned. Failure: A NULL pointer is returned..

Comments

• If elem_index exceeds the number of children, then NULL is returned.

• The tag of the value of OKVTTLV object is also returned if tag is not NULL.

• The type of the value of OKVTTLV object is also returned if typ is not NULL.

• The length of the value of OKVTTLV object is also returned if len is not NULL.

Example

OKVTTLV *resp = (OKVTTLV *) NULL;
OKVTTLV *tagid = (OKVTTLV *) NULL;
OKVTag ctag;
OKVType ctyp;
ub4 clen;
...
OKVOps *ops  = okvOpsCreate(env, OKVOpCreate);
resp  = okvTTLVGetResponse(env, ops);
tagid = okvTTLVGetChild(env, resp, 1, &ctag, &ctyp, &clen);

Related Topics

• okvTTLVGetChildByTag

• okvTTLVGetFirstChildByTag

okvTTLVGetChildByTag

okvTTLVGetChildByTag retrieves a child OKVTTLV object from the OKVTTLV object with the specified tag.

Category

KMIP extension TTLV object API

Purpose

okvTTLVGetChildByTag is used to retrieve a child OKVTTLV object from the OKVTTLV object with the specified tag at or after element index elem_index. The actual element index is also returned.

Syntax

OKVTTLV *okvTTLVGetChildByTag(OKVEnv *env, OKVTTLV *ttlv,
                              OKVTag tag, ub4 *elem_index);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
ttlv	IN	OKVTTLV parent object.
tag	IN	Tag of the OKVTTLV object being retrieved.
elem_index	IN/OUT	Element index of the child OKVTTLV object.

Return Values

Return Value	Description
OKVTTLV*	OKVTTLV object with the given tag. Success: A valid pointer to the child OKVTTLV object with the given tag at or after element index elem_index is returned. Failure: A NULL pointer is returned.

Comments

If elem_index exceeds the number of children, then NULL is returned.

Example

OKVTTLV *resp = (OKVTTLV *) NULL;
OKVTTLV *tagid = (OKVTTLV *) NULL;
OKVTag ctag;
OKVType ctyp;
ub4 clen;
ub4 elem_index = 0;
...
OKVOps *ops  = okvOpsCreate(env, OKVOpCreate);
resp  = okvTTLVGetResponse(env, ops);
tagid = okvTTLVGetChildByTag(env, resp, OKVDEF_TAG_ID, &elem_index);
ctag  = okvTTLVGetTag(tagid);
ctyp  = okvTTLVGetType(tagid);
clen  = okvTTLVGetLen(tagid);

Related Topics

• okvTTLVGetChild

• okvTTLVGetFirstChildByTag

okvTTLVGetChildCount

okvTTLVGetChildCount returns the number of child OKVTTLV objects of the specified OKVTTLV parent object.

Category

KMIP extension TTLV object API

Purpose

okvTTLVVGetChildCount will return the number of child OKVTTLV objects of the specified OKVTTLV parent object.

Syntax

ub4 okvTTLVGetChildCount(OKVTTLV *ttlv);

Parameters

Parameter	IN/OUT	Description
ttlv	IN	OKVTTLV object

Return Values

Return Value	Description
ub4	Number of child OKVTTLV objects of the specified OKVTTLV object. Success: Count of child OKVTTLV objects of the specified OKVTTLV parent object. Failure: A zero is returned on error or if the OKVTTLV parent object is not a STRUCTURE.

Comments

If the specified OKVTTLV object is not a STRUCTURE, then zero is returned. If the specified OKVTTLV object is a STRUCTURE and there was an error, zero is returned.

Example

OKVTTLV *resp = (OKVTTLV *) NULL;
ub4 child_count;
...
OKVOps *ops  = okvOpsCreate(env, OKVOpCreate);
resp = okvTTLVGetResponse(env, ops);
child_count = okvTTLVGetChildCount(resp);

Related Topics

• okvTTLVGetChildCountByTag

okvTTLVGetChildCountByTag

okvTTLVGetChildCountByTag will return the number of child OKVTTLV objects of the specified OKVTTLV parent object that have the given tag.

Category

KMIP extension TTLV object API

Purpose

okvTTLVGetChildCountByTag will return the number of child OKVTTLV objects of the specified OKVTTLV parent object that have the given tag.

Syntax

ub4 okvTTLVGetChildCountByTag(OKVTTLV *ttlv, OKVTag tag);

Parameters

Parameter	IN/OUT	Description
ttlv	IN	OKVTTLV object
tag	IN	Tag of the child OKVTTLV objects being counted

Return Values

Return Value	Description
ub4	Number of child OKVTTLV Objects of the specified OKVTTLV parent object with the given tag. Success: Count of the child OKVTTLV objects of the specified OKVTTLV parent object with the given tag. Failure: A zero is returned on error or if the OKVTTLV parent object is not a STRUCTURE.

Comments

If the specified OKVTTLV object is not a STRUCTURE, then zero is returned. If the specified OKVTTLV object is a STRUCTURE and there was an error, zero is returned.

Example

OKVTTLV *resp = (OKVTTLV *) NULL;
ub4 unique_id_count;
...
OKVOps *ops  = okvOpsCreate(env, OKVOpCreate);
resp = okvTTLVGetResponse(env, ops);
unique_id_count = okvTTLVGetChildCountByTag(resp, OKVDEF_TAG_ID);

Related Topics

• okvTTLVGetChildCount

okvTTLVGetFirstChildByTag

okvTTLVGetFirstChildByTag retrieves the first child of the OKVTTLV object that has the specified tag.

Category

KMIP extension TTLV object API

Purpose

okvTTLVGetFirstChildByTag is used to retrieve the first child of the OKVTTLV object that has the specified tag.

Syntax

OKVTTLV *okvTTLVGetFirstChildByTag(OKVEnv *env,
                                   OKVTTLV *ttlv, OKVTag tag);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle
ttlv	IN	OKVTTLV parent object
tag	IN	Tag of the OKVTTLV object being retrieved

Return Values

Return Value	Description
OKVTTLV*	OKVTTLV object with the given tag. Success: A valid pointer to the child OKVTTLV object with the given tag is returned. Failure: A NULL pointer is returned.

Comments

None.

Example

OKVTTLV *resp = (OKVTTLV *) NULL;
OKVTTLV *tagid = (OKVTTLV *) NULL;
OKVTag ctag;
OKVType ctyp;
ub4 clen;
...
OKVOps *ops  = okvOpsCreate(env, OKVOpCreate);
resp = okvTTLVGetResponse(env, ops);
tagid =  okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID);
ctag = okvTTLVGetTag(tagid);
ctyp = okvTTLVGetType(tagid);
clen = okvTTLVGetLen(tagid);

Related Topics

• okvTTLVGetChild

• okvTTLVGetChildByTag

okvTTLVGetLen

okvTTLVGetLen returns the length of the value of the OKVTTLV object.

Category

KMIP extension TTLV object API

Purpose

okvTTLVGetLen will return the length of the value of the OKVTTLV object.

Syntax

ub4 okvTTLVGetLen(OKVTTLV *ttlv);

Parameters

Parameter	IN/OUT	Description
ttlv	IN	OKVTTLV object

Return Values

Return Value	Description
ub4	Length of the OKVTTLV object value Success: Length of the value of the OKVTTLV object is returned. Failure: A zero is returned if the OKVTTLV object is a STRUCTURE or if there was an error.

Comments

If length returned is zero, then it implies an error except when the OKVTTLV type is a STRUCTURE.

Example

OKVTTLV *resp = (OKVTTLV *) NULL;
OKVTTLV *tagid = (OKVTTLV *) NULL;
ub4 clen;
...
OKVOps *ops  = okvOpsCreate(env, OKVOpCreate);
resp = okvTTLVGetResponse(env, ops);
tagid =  okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID);
clen = okvTTLVGetLen(tagid);

Related Topics

• okvTTLVGetTag

• okvTTLVGetType

• okvTTLVGetValue

• okvTTLVGetValueCopy

okvTTLVGetRequest

okvTTLVGetRequest returns the OKVTTLV request object of the operation.

Category

KMIP extension TTLV object API

Purpose

okvTTLVGetRequest will return the OKVTTLV request object of the operation. This object will be the root OKVTTLV object used to build the KMIP Request. All OKVTTLV objects used in the KMIP request will fall under the OKVTTLV request object.

Syntax

OKVTTLV *okvTTLVGetRequest(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

Return Value	Description
OKVTTLV*	OKVTTLV request object for the operation. Success: A valid pointer to the OKVTTLV request object is returned. Failure: A NULL pointer is returned.

Comments

None.

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

Related Topics

• okvTTLVGetResponse

okvTTLVGetResponse

okvTTLVGetResponse returns the OKVTTLV response object of the custom KMIP operation.

Category

KMIP extension TTLV object API

Purpose

okvTTLVGetResponse will return the OKVTTLV response object of the custom KMIP operation. This object will be used to parse the KMIP response from the Oracle Key Vault server. All OKVTTLV objects of the KMIP response have to be extracted and processed from the OKVTTLV response object.

Syntax

OKVTTLV *okvTTLVGetResponse(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

Return Value	Description
OKVTTLV*	OKVTTLV response object of the operation. Success: A valid pointer to the OKVTTLV Response object is returned. Failure: A NULL pointer is returned.

Comments

None.

Example

OKVTTLV *resp = (OKVTTLV *) NULL;
OKVTTLV *tagid = (OKVTTLV *) NULL;
OKVTag ctag, rtag;
OKVType ctyp, rtyp;
oratext cval[OKV_UNIQUE_ID_MAXLEN + 1], rval[OKV_UNIQUE_ID_MAXLEN + 1];
ub4 clen, rlen;
OKVOps *ops[2];
...
/* Get the result of the First Batch Operation */
ops[0] = okvOpsCreate(env, OKVOpCreate);
resp = okvTTLVGetResponse(env, ops[0]);

/* Retrieve the Unique Identifier */
tagid = okvTTLVGetChild(env, resp, 1, &ctag, &ctyp, &clen);
printf("\n%d %d %d ", ctag, ctyp, clen);
okvTTLVGetValueCopy(tagid, (void *)cval, clen);
cval[clen] = 0;
printf("%s\n", cval); /* Print the Unique Identifier */

/* Get the result of the Second Batch Operation */
ops[1] = okvOpsCreate(env, OKVOpActivate);
resp = okvTTLVGetResponse(env, ops[1]);

/* Retrieve the Unique Identifier */
tagid =  okvTTLVGetChild(env, resp, 0, &rtag, &rtyp, &rlen);
printf("\n%d %d %d ", rtag, rtyp, rlen);
okvTTLVGetValueCopy(tagid, (void *)rval, rlen);
rval[rlen] = 0;
printf("%s\n", rval); /* Print the Unique Identifier */

Related Topics

• okvTTLVGetRequest

okvTTLVGetTag

okvTTLVGetTag returns the tag value of the OKVTTLV object.

Category

KMIP extension TTLV object API

Purpose

okvTTLVGetTag will return the tag value of the OKVTTLV object.

Syntax

OKVTag okvTTLVGetTag(OKVTTLV *ttlv);

Parameters

Parameter	IN/OUT	Description
ttlv	IN	OKVTTLV object

Return Values

Return Value	Description
OKVTag	Tag of the OKVTTLV object. Success: A valid tag value of the OKVTTLV object is returned. Failure: A zero is returned.

Comments

None.

Example

OKVTTLV *resp = (OKVTTLV *) NULL;
OKVTTLV *tagid = (OKVTTLV *) NULL;
OKVTag ctag;
...
OKVOps *ops  = okvOpsCreate(env, OKVOpCreate);
resp  = okvTTLVGetResponse(env, ops);
tagid = okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID);
ctag  = okvTTLVGetTag(tagid);

Related Topics

• okvTTLVGetType

• okvTTLVGetLen

• okvTTLVGetValue

• okvTTLVGetValueCopy

okvTTLVGetType

okvTTLVGetType returns the type value of the OKVTTLV object.

Category

KMIP extension TTLV object API

Purpose

okvTTLVGetType will return the type value of the OKVTTLV object.

Syntax

OKVType okvTTLVGetType(OKVTTLV *ttlv);

Parameters

Parameter	IN/OUT	Description
ttlv	IN	OKVTTLV object

Return Values

Return Value	Description
OKVType	Type of the OKVTTLV object. Success: A valid Type value of the OKVTTLV object is returned. Failure: A zero is returned if there was an error.

Comments

None.

Example

OKVTTLV *resp = (OKVTTLV *) NULL;
OKVTTLV *tagid = (OKVTTLV *) NULL;
OKVType ctyp;
...
OKVOps *ops  = okvOpsCreate(env, OKVOpCreate);
resp  = okvTTLVGetResponse(env, ops);
tagid = okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID);
ctyp  = okvTTLVGetType(tagid);

Related Topics

• okvTTLVGetTag

• okvTTLVGetLen

• okvTTLVGetValue

• okvTTLVGetValueCopy

okvTTLVGetValue

okvTTLVGetValue returns the pointer to the value of the OKVTTLV object.

Category

KMIP extension TTLV object API

Purpose

okvTTLVGetValue returns the pointer to the value of the OKVTTLV object.

Syntax

void *okvTTLVGetValue(OKVTTLV *ttlv);

Parameters

Parameter	IN/OUT	Description
ttlv	IN	OKVTTLV object

Return Values

Return Value	Description
void*	OKVTTLV object value. Success: Pointer to the value of the OKVTTLV object is returned. Failure: A NULL pointer is returned if there is an error.

Comments

None.

Example

OKVTTLV *resp = (OKVTTLV *) NULL;
OKVTTLV *tagid = (OKVTTLV *) NULL;
ub4 clen;
oratext *cval;
...
OKVOps *ops = okvOpsCreate(env, OKVOpCreate);
resp  = okvTTLVGetResponse(env, ops);
tagid = okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID);
clen  = okvTTLVGetLen(tagid);
cval  = (oratext *) okvTTLVGetValue(tagid);
cval[clen] = 0;
printf("%s", cval);

Related Topics

• okvTTLVGetTag

• okvTTLVGetType

• okvTTLVGetLen

• okvTTLVGetValueCopy

okvTTLVGetValueCopy

okvTTLVGetValueCopy copies the value of the OKVTTLV object into the supplied buffer.

Category

KMIP extension TTLV object API

Purpose

okvTTLVGetValueCopy will copy the value of the OKVTTLV object into the supplied buffer.

Syntax

ub4 okvTTLVGetValueCopy(OKVTTLV *ttlv, void *val, ub4 len);

Parameters

Parameter	IN/OUT	Description
ttlv	IN	OKVTTLV object
val	OUT	Buffer for the OKVTTLV object value
len	IN	Length of the OKVTTLV object value

Return Values

Return Value	Description
ub4	Length of the OKVTTLV object value. Success: Length of the value of the OKVTTLV object is returned. Failure: Zero is returned.

Comments

The memory for the value has to be pre-allocated before making a call to this function.

Depending on the type of the OKVTTLV object, the value can be interpreted differently. For example, if the type of the OKVTTLV object is INTEGER, then the value can be stored in a ub4 variable. However, if the OKVTTLV object is a BYTE STRING, the value is a ub1 array of length len.

This function should not be used for OKVTTLV objects that are of type STRUCTURE.

Example

OKVTTLV *resp = (OKVTTLV *) NULL;
OKVTTLV *tagid = (OKVTTLV *) NULL;
ub4 clen;
oratext cval[OKV_UNIQUE_ID_MAXLEN + 1];
...
OKVOps *ops  = okvOpsCreate(env, OKVOpCreate);
resp  = okvTTLVGetResponse(env, ops);
tagid = okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID);
clen  = okvTTLVGetLen(tagid);
okvTTLVGetValueCopy(tagid, (void *)cval, clen);
cval[clen] = 0;
printf("%s", cval);

Related Topics

• okvTTLVGetTag

• okvTTLVGetType

• okvTTLVGetLen

• okvTTLVGetValue