1. Developer's Guide
  2. Oracle Key Vault Client C SDK API Reference
  3. Oracle Key Vault Client SDK TTLV Object APIs

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

Parent topic: Oracle Key Vault Client C SDK API Reference

14.1 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.2 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.3 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.4 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.5 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.6 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.7 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.8 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.9 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.10 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.11 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.12 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.13 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.14 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs

14.15 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

Parent topic: Oracle Key Vault Client SDK TTLV Object APIs