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.
Parent topic: Oracle Key Vault Client C SDK API Reference
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 |
---|---|---|
|
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 |
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"); }
Parent topic: Oracle Key Vault Management APIs
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;
Related Topics
Parent topic: Oracle Key Vault Management APIs
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);
Related Topics
Parent topic: Oracle Key Vault Management APIs
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 |
Comments
None.
Example
OKVTTLV *request = (OKVTTLV *)NULL; ... /* Setup the Oracle Key Vault Environment handle 'env' */ ... request = okvEnvGetOpRequestObj(env);
Related Topics
Parent topic: Oracle Key Vault Management APIs
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. |
|
IN |
Oracle Key Vault connection configuration file. |
|
IN |
Password of the SSL connection wallet. |
Return Values
Return Value | Description |
---|---|
OKVErrNo |
Oracle Key Vault error number. Success: 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);
Related Topics
Parent topic: Oracle Key Vault Management APIs
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 tracingOKV_TRACE_FATAL
- Fatal level only tracingOKV_TRACE_ERROR
- Error tracingOKV_TRACE_WARN
- Warning tracingOKV_TRACE_INFO
– Informational tracingOKV_TRACE_DEBUG
– Debug tracingOKV_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: 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);
Parent topic: Oracle Key Vault Management APIs