7 Oracle Key Vault Management APIs

The Oracle Key Vault management APIs control the Oracle Key Vault Interface program environment.

• okvEnvCreate
  okvEnvCreate creates the Oracle Key Vault environment handle and the Oracle Key Vault SDK program begins with a successful call to this function.
• okvEnvFree
  okvEnvFree frees the Oracle Key Vault environment handle, which marks the end of the Oracle Key Vault environment.
• okvEnvFreeResultObj
  okvEnvFreeResultObj frees the OKVTTLV result descriptor that was returned by the Oracle Key Vault functions.
• okvEnvGetOpRequestObj
  okvEnvGetOpRequestObj gets the root (top-level parent) of the OKVTTLV descriptor for Oracle Key Vault KMIP functions.
• okvEnvSetConfig
  okvEnvSetConfig sets up the Oracle Key Vault connection configuration context.
• okvEnvSetTrace
  okvEnvSetTrace sets up the Oracle Key Vault trace configuration context.

7.1 okvEnvCreate

okvEnvCreate creates the Oracle Key Vault environment handle and the Oracle Key Vault SDK program begins with a successful call to this function.

Category

Management API

Purpose

okvEnvCreate is used to create the Oracle Key Vault environment handle which in turn holds error handle, tracing context and the various Service Provider Interface handles required by the Endpoint program. All of the Oracle Key Vault functions are done within the purview of this handle. The Oracle Key Vault environment begins with a successful call to this function.

Syntax

OKVEnv *okvEnvCreate(OKVMemoryCtx *memctx);

Parameters

Parameter	IN/OUT	Description
memctx	IN	Oracle Key Vault memory management context.

Return Values

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

Comments

Endpoints using the Oracle Key Vault memory management should pass in OKV_MEMORY_FUNCTIONS to okvEnvCreate.

The Oracle Key Vault client SDK provides the client with an option to define their own memory management context and memory management functions.

Suppose the client has defined clientMalloc(), clientRealloc(), clientFree(), and clientCtxP for memory management. The client can make use of these functions by initializing the Oracle Key Vault environment handle with the Oracle Key Vault memory context structure.

...
OKVMemoryCtx clientMemory;
clientMemory.ctx = clientCtxP;
clientMemory.okvMalloc = &clientMalloc;
clientMemory.okvRealloc = &clientRealloc;
clientMemory.okvFree = &clientFree;
okvEnvCreate(&clientMemory);
...

Example

OKVEnv  *env = (OKVEnv *) NULL;

/* Setup the Oracle Key Vault Environment handle */
printf("\nSetting up Oracle Key Vault Environment handle\n");
env = okvEnvCreate(OKV_MEMORY_FUNCTIONS);
if (!env)
{
   printf("\tCould not setup the Oracle Key Vault Environment handle\n");
   return 1;
}
else
{
   printf("\tSuccessfully setup Oracle Key Vault Environment handle\n\n");
}

7.2 okvEnvFree

okvEnvFree frees the Oracle Key Vault environment handle, which marks the end of the Oracle Key Vault environment.

Category

Management API

Purpose

okvEnvFree is used to free the Oracle Key Vault environment handle. It marks the end of Oracle Key Vault environment.

Syntax

void okvEnvFree(OKVEnv **env);

Parameters

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

Return Values

Comments

No values returned.

None.

Example

OKVEnv  *env = (OKVEnv *) NULL;

/* Setup the Oracle Key Vault Environment handle */
printf("\nSetting up Oracle Key Vault Environment handle\n");
env = okvEnvCreate(OKV_MEMORY_FUNCTIONS);

if (!env)
{
   printf("\tCould not setup the Oracle Key Vault Environment handle\n");
   return 1;
}
else
{
   printf("\tSuccessfully setup Oracle Key Vault Environment handle\n\n");
}
...
/* Do some KMIP operations */
...
/* Free the env handle */
printf("Releasing the Environment handle\n");
okvEnvFree(&env);
return 0;

7.3 okvEnvFreeResultObj

okvEnvFreeResultObj frees the OKVTTLV result descriptor that was returned by the Oracle Key Vault functions.

Category

Management API

Purpose

okvEnvFreeResultObj will free the OKVTTLV result descriptor that was returned by the Oracle Key Vault functions.

Oracle Key Vault KMIP functions at times return OKVTTLV descriptors that have to be explored further either using Oracle Key Vault helper or Oracle Key Vault KMIP Extension functions. The OKVTTLV parent for the result descriptor is stored in Oracle Key Vault environment handle and is not freed upon completion of the Oracle Key Vault function.

After the Oracle Key Vault function result descriptor has been interpreted, it can be freed using okvEnvFreeResultObj.

Syntax

void okvEnvFreeResultObj(OKVEnv *env);

Parameters

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

Return Values

No values returned.

Comments

The subsequent Oracle Key Vault functions calls will free the result descriptor of the previous Oracle Key Vault function.

Example

/* Setup the Oracle Key Vault Environment handle 'env' */
...
/* Do some KMIP operations */
...
okvEnvFreeResultObj(env);

7.4 okvEnvGetOpRequestObj

okvEnvGetOpRequestObj gets the root (top-level parent) of the OKVTTLV descriptor for Oracle Key Vault KMIP functions.

Category

Management API

Purpose

Some KMIP functions will use an OKVTTLV descriptor argument to build the TTLV Request. okvEnvGetOpRequestObj is used to get the root (top-level parent) of the OKVTTLV descriptor for Oracle Key Vault KMIP functions.

Oracle Key Vault functions like okvAttrAddUniqueID will create an OKVTTLV attribute descriptor but these functions need a parent OKVTTLV descriptor. okvEnvGetOpRequestObj() returns the parent OKVTTLV descriptor for such Oracle Key Vault functions.

Syntax

OKVTTLV *okvEnvGetOpRequestObj(OKVEnv *env);

Parameters

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

Return Values

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

Comments

None.

Example

OKVTTLV *request = (OKVTTLV *)NULL;
...
/* Setup the Oracle Key Vault Environment handle 'env' */
...
request = okvEnvGetOpRequestObj(env);

7.5 okvEnvSetConfig

okvEnvSetConfig sets up the Oracle Key Vault connection configuration context.

Category

Management API

Purpose

okvEnvSetConfig is used to specify the password for the SSL connection wallet. The SSL connection wallet will be created at the time of enrollment. The password specified at the time of endpoint enrollment is the one used with this function. If no password was specified at the time of enrollment, NULL should be used as the password.

okvEnvSetConfig will also specify the configuration file that will be used to set up the connection configuration for holding details like the server IP address, server port number, and other information which will be needed during establishing connection with the Oracle Key Vault server.

Syntax

OKVErrNo okvEnvSetConfig(OKVEnv *env, oratext *conn_config_file,
                         oratext *conn_pwd);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
conn_config_file	IN	Oracle Key Vault connection configuration file.
conn_pwd	IN	Password of the SSL connection wallet.

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 connection configuration file is the okvclient.ora file, which is created at the time of Oracle Key Vault endpoint enrollment.

If you do not specify the full path to the connection configuration file, then the API tries to look for configuration file under $OKV_HOME/conf. Make sure to set up the $OKV_HOME to the directory where the endpoint software was installed.

Example

oratext *pwd = (oratext *)NULL;
...
/* Setup the Oracle Key Vault Environment handle 'env' */
...
printf("Setting up Oracle Key Vault connection configuration\n");
okvEnvSetConfig(env, (oratext *)NULL, (oratext *)pwd);

7.6 okvEnvSetTrace

okvEnvSetTrace sets up the Oracle Key Vault trace configuration context.

Category

Management API

Purpose

okvEnvSetTrace is used to specify the location of the trace file and also the trace level. The trace file will record the internal traces generated by the endpoint SDK program and can be useful for diagnostics and debugging. The level of tracing determines how fine-grained or coarse-grained the tracing should be. In ascending order, debug levels take the following values:

• OKV_TRACE_OFF - No tracing
• OKV_TRACE_FATAL - Fatal level only tracing
• OKV_TRACE_ERROR - Error tracing
• OKV_TRACE_WARN - Warning tracing
• OKV_TRACE_INFO – Informational tracing
• OKV_TRACE_DEBUG – Debug tracing
• OKV_TRACE_ALL - All tracing

Syntax

OKVErrNo okvEnvSetTrace(OKVEnv *env, oratext *trace_file, ub1 debug_level);

Parameters

Parameter	IN/OUT	Description
env	IN	Oracle Key Vault environment handle.
trace_file	IN	Location of client SDK trace file.
debug_level	IN	Level of tracing.

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

oratext *trace_dir = (oratext *)NULL;
...
/* Setup the Oracle Key Vault Environment handle 'env' */
...
trace_dir = (oratext *)"/tmp";
printf("Setting up Tracing\n");
okvEnvSetTrace(env, (oratext *)trace_dir, OKV_TRACE_INFO);