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

14 Oracle Key Vault Client SDK Utility APIs

You can use the Oracle Key Vault client SDK utility APIs with other Oracle Key Vault functions to simplify common operations.

The element and attribute index used in the Oracle Key Vault utility functions have the same meaning as described in section Attribute Index and Element Index.

  • About the Oracle Key Vault Client SDK Utility APIs
    You can use the Oracle Key Vault SDK utility APIs with other Oracle Key Vault APIs to simplify commonly used operations.
  • okvAttrExtractTTLV
    okvAttrExtractTTLV converts the attributes that are child OKVTTLV objects of the specified OKVTTLV parent object into OKVAttr.
  • okvAttrMakeTTLV
    okvAttrMakeTTLV converts the OKVAttr into an OKVTTLV structure.
  • okvGetTextForAttributeNum
    okvGetTextForAttributeNum returns the attribute name for a given Oracle Key Vault attribute number.
  • okvGetTextForTag
    okvGetTextForTag returns the name of the valid KMIP tag.
  • okvGetTextForTagEnum
    okvGetTextForTagEnum returns the name of the enumerated value for a valid KMIP tag of ENUMERATION type.
  • okvGetTextForTagType
    okvGetTextForTagType returns the name of the valid KMIP type.
  • okvGetTextLenForAttributeNum
    okvGetTextLenForAttributeNum returns the length of the name of the attribute for a given Oracle Key Vault attribute number.
  • okvObjGetAttrNo
    okvObjGetAttrNo will return the Oracle Key Vault attribute number for a given TTLV object.

Parent topic: Oracle Key Vault Client C SDK API Reference

14.1 About the Oracle Key Vault Client SDK Utility APIs

You can use the Oracle Key Vault SDK utility APIs with other Oracle Key Vault APIs to simplify commonly used operations.

The client SDK utility API element and attribute indexes have the same structure as the Oracle Key Vault KMIP attribute APIs.

Related Topics

Parent topic: Oracle Key Vault Client SDK Utility APIs

14.2 okvAttrExtractTTLV

okvAttrExtractTTLV converts the attributes that are child OKVTTLV objects of the specified OKVTTLV parent object into OKVAttr.

Category

KMIP utility API

Purpose

okvAttrExtractTTLV will convert the attributes that are child OKVTTLV objects of the specified OKVTTLV parent object into OKVAttr.

Syntax

OKVErrNo okvAttrExtractTTLV(OKVEnv *env, OKVTTLV *attr_ttlv,
                            OKVAttr *attr_col);

Parameters

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

TTLV parent object containing attributes.

attr_col OUT

Collection of 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

None.

Example

OKVAttr attr_struct;
ub4 index = 0;
memset((void *)&attr_struct, 0, sizeof(attr_struct));
...
okvAttrExtractTTLV(env, ttlv, &attr_struct);
printf("\nAttributes Extracted:");
printf("\nName: %s ", attr_struct.name[index].name);
printf("\nName Length: %d ", attr_struct.name[index].namel);

/* Null terminate the unique identifier */
attr_struct.unique_identifier.id[attr_struct.unique_identifier.idl] = 0;
printf("\nUnique ID: %s ", attr_struct.unique_identifier.id);
printf("\nUnique ID Length: %d ", attr_struct.unique_identifier.idl);
printf("\nCryptographic Algorithm: %d ", attr_struct.crypto_algorithm);

Related Topics

Parent topic: Oracle Key Vault Client SDK Utility APIs

14.3 okvAttrMakeTTLV

okvAttrMakeTTLV converts the OKVAttr into an OKVTTLV structure.

Category

KMIP utility API

Purpose

okvAttrMakeTTLV will convert the OKVAttr into an OKVTTLV structure and all the new attributes in the OKVTTLV will be collected under the specified OKVTTLV parent object.

Syntax

OKVErrNo okvAttrMakeTTLV(OKVEnv *env, OKVAttr *attr_col  
                         OKVTTLV *attr_ttlv);

Parameters

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

Collection of attributes.
attr_ttlv OUT

TTLV parent object containing 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

For multi-instance attributes, the count of the attribute must be set. For example, name is a multi-instance attribute. Hence, if name is being added, name_count must also be specified.

Example

OKVTTLV *ttlv = (OKVTTLV *)NULL;
OKVOps *ops;
OKVAttr attrs;
memset((void *)&attrs, 0, sizeof(attrs));
...

/* Adding name attribute to the structure */
ub4 index = 0;
attrs.name_count = 1;
attrs.name[index].name = "attr_name";
attrs.name[index].namel = strlen(attrs.name[index].name);
attrs.name[index].type = 1;
 
/* Adding cryptographic algo attribute to the structure */
attrs.crypto_algorithm = CRYPTO_ALG_AES;

/* Adding unique identifier attribute to the structure */
attrs.unique_identifier.id = uid;
attrs.unique_identifier.idl = strlen(attrs.unique_identifier.id);
ops = okvOpsCreate(env, OKVOpAddAttribute);
ttlv = okvTTLVGetRequest(env, ops);

/* Convert OKVAttr structure to TTLV Attributes Object */
okvAttrMakeTTLV(env, &attrs, ttlv);

Related Topics

Parent topic: Oracle Key Vault Client SDK Utility APIs

14.4 okvGetTextForAttributeNum

okvGetTextForAttributeNum returns the attribute name for a given Oracle Key Vault attribute number.

Catetory

KMIP Utility API

Purpose

okvGetTextForAttributeNum returns the attribute name for a given Oracle Key Vault attribute number.

Syntax

oratext *okvGetTextForAttributeNum(OKVAttrNo attrno);

Parameters

Parameter IN/OUT Description
attrno

IN

Oracle Key Vault attribute number of the KMIP attribute.

Return Values

Return Value Description
oratext*

Name of KMIP attribute.

Success: A valid pointer to the name of the KMIP attribute.

Failure: A NULL pointer is returned.

Comments

None.

Example

printf("%s", okvGetTextForAttributeNum(OKVAttrActivationDate));

Related Topics

Parent topic: Oracle Key Vault Client SDK Utility APIs

14.5 okvGetTextForTag

okvGetTextForTag returns the name of the valid KMIP tag.

Category

KMIP utility API

Purpose

okvGetTextForTag returns the name of the valid KMIP tag. A NULL value is returned for invalid KMIP tag.

Syntax

oratext *okvGetTextForTag(OKVTag tag);

Parameters

Parameter IN/OUT Description
tag IN KMIP tag

Return Values

Return Value Description
oratext*

KMIP tag name.

Success: A valid pointer to the KMIP tag name is returned.

Failure: A NULL pointer is returned.

Comments

None.

Example

printf("%s", okvGetTextForTag(OKVDEF_TAG_ID));

Related Topics

Parent topic: Oracle Key Vault Client SDK Utility APIs

14.6 okvGetTextForTagEnum

okvGetTextForTagEnum returns the name of the enumerated value for a valid KMIP tag of ENUMERATION type.

Category

KMIP utility API

Purpose

okvGetTextForTagEnum will return the name of the enumerated value for a valid KMIP tag of EMUMERATION type.

Syntax

oratext *okvGetTextForTagEnum(OKVTag tag, ub4 val);

Parameters

Parameter IN/OUT Description
tag IN KMIP enum tag
val IN KMIP enum tag value

Return Values

Return Value Description
oratext*

Name of KMIP enum tag value.

Success: A valid pointer to the name of the KMIP enum tag value is returned.

Failure: A NULL pointer is returned.

Comments

A NULL value is returned for invalid KMIP tag or invalid value of the KMIP tag or if the KMIP tag is not of ENUMERATION type.

Example

printf("%s", okvGetTextForTagEnum(OKVDEF_TAG_STATE, OKVDEF_STATE_ACTIVE));

Related Topics

Parent topic: Oracle Key Vault Client SDK Utility APIs

14.7 okvGetTextForTagType

okvGetTextForTagType returns the name of the valid KMIP type.

Category

KMIP utility API

Purpose

okvGetTextForTagType returns the name of the valid KMIP type. A NULL value is returned for invalid KMIP type.

Syntax

oratext *okvGetTextForTagType(OKVType typ);

Parameters

Parameter IN/OUT Description
typ IN KMIP type

Return Values

Return Value Description
oratext*

KMIP type name.

Success: A valid pointer to the KMIP type name is returned.

Failure: A NULL pointer is returned.

Comments

None.

Example

printf("%s", okvGetTextForTagType(OKVDEF_ITEM_TYPE_INT));

Related Topics

Parent topic: Oracle Key Vault Client SDK Utility APIs

14.8 okvGetTextLenForAttributeNum

okvGetTextLenForAttributeNum returns the length of the name of the attribute for a given Oracle Key Vault attribute number.

Catetory

KMIP Utility API

Purpose

okvGetTextLenForAttributeNum returns the length of the name of the attribute for a given Oracle Key Vault attribute number.

Syntax

ub4 okvGetTextLenForAttributeNum(OKVAttrNo attrno);

Parameters

Parameter IN/OUT Description
attrno

IN

Oracle Key Vault attribute number of the KMIP attribute.

Return Values

Return Value Description
ub4

Length of the attribute name.

Success: Length of the buffer is returned.

Failure: 0.

Comments

None.

Example

printf("%d", okvGetTextLenForAttributeNum(OKVAttrActivationDate));

Related Topics

Parent topic: Oracle Key Vault Client SDK Utility APIs

14.9 okvObjGetAttrNo

okvObjGetAttrNo will return the Oracle Key Vault attribute number for a given TTLV object.

Catetory

KMIP Utility API

Purpose

okvObjGetAttrNo will return the Oracle Key Vault attribute number for a given TTLV object.

Syntax

OKVAttrNo okvObjGetAttrNo(OKVEnv *env, OKVTTLV *ttlv);

Parameters

Parameter IN/OUT Description
env

IN

Oracle Key Vault environment handle.
ttlv IN OKVTTLV object.

Return Values

Return Value Description
OKVAttrNo

Oracle Key Vault attribute number for the TTLV object.

Success: Oracle Key Vault attribute number for the given TTLV object is returned.

Failure: OKVAttrInvalid is returned.

Comments

None.

Example

OKVTTLV *ttlv = (OKVTTLV *) NULL;
...
switch (okvObjGetAttrNo(env, ttlv))
{
   ...
   case OKVAttrObjType:
      ...
   case OKVAttrCryptoAlg:
      ...
   case OKVAttrCryptoLen:
      ...
   case OKVAttrCryptoUsageMask:
      ...
}

Parent topic: Oracle Key Vault Client SDK Utility APIs