8 Oracle Key Vault Client SDK Connection Management APIs
This section describes the interfaces for Oracle Key Vault connection management.
- okvConnect
okvConnect
begins the Oracle Key Vault interface session and creates a connection to the Oracle Key Vault server. - okvConnSendRecvBytes
okvConnSendRecvBytes
sends a KMIP request message to the Oracle Key Vault server and retrieves the KMIP response message sent back from the Oracle Key Vault server. - okvConnSet
okvConnSet
can be used to set up the user client connection provider which can be used to establish connection to the Oracle Key Vault server. - okvConnUnSet
okvConnUnSet
is used to free the client connection provider. - okvDisconnect
okvDisconnect
ends the Oracle Key Vault interface session and disconnects the Secure Sockets Layer (SSL) connection between the endpoint and the Oracle Key Vault server.
Parent topic: Oracle Key Vault Client C SDK API Reference
8.1 okvConnect
okvConnect
begins the Oracle Key Vault interface session and creates a connection to the Oracle Key Vault server.
Category
Connection management API
Purpose
okvConnect
is used to begin the Oracle Key Vault session and create
a connection to the Oracle Key Vault Server. Subsequent Oracle Key Vault functions will
use this connection for communicating with the Oracle Key Vault Server.
Syntax
OKVErrNo okvConnect(OKVEnv *env);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
|
IN |
Oracle Key Vault environment handle. |
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
OKVErrNo err_no; ... /* Setup the Oracle Key Vault Environment handle 'env' */ ... printf("Setting up Oracle Key Vault session\n"); err_no = okvConnect(env); if (err_no) { printf("Could not setup the Oracle Key Vault session\n"); return 1; } else { printf("Successfully setup Oracle Key Vault Session\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK Connection Management APIs
8.2 okvConnSendRecvBytes
okvConnSendRecvBytes
sends a KMIP request message to the Oracle Key Vault server and retrieves the KMIP response message sent back from the Oracle Key Vault server.
Category
Connection management API
Purpose
okvConnSendRecvBytes
is used to send a KMIP request message to the Oracle Key Vault server and retrieve the KMIP response message sent back from the Oracle Key Vault server. The response returned by the Oracle Key Vault server cannot exceed the maximum payload supported between the Oracle Key Vault client and server.
Syntax
OKVErrNo okvConnSendRecvBytes(OKVEnv *env, ub1 *reqmsg, ub4 reqmsgl, ub1 **respmsg, ub4 *respmsgl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
reqmsg |
IN |
KMIP TTLV request message. |
reqmsg1 |
IN |
KMIP TTLV request message length. |
|
|
KMIP TTLV response message. |
|
|
KMIP TTLV response message length. |
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 endpoint program needs to allocate space for the response message. If the response message cannot fit in the allocated space the function will return an error.
Example
OKVErrNo err_no; ... /* Setup the Oracle Key Vault Environment handle 'env' */ ... err_no = okvConnSendRecvBytes(env, (ub1 *)NULL, (ub4)0, (ub1 **)NULL, (ub4 *)0); if (err_no) { printf("Error while executing okvConnSendRecvBytes\n"); return 1; } else { printf("Successfully executed okvConnSendRecvBytes\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK Connection Management APIs
8.3 okvConnSet
okvConnSet
can be used to set up the user client connection provider which can be used to establish connection to the Oracle Key Vault server.
Category
Connection management API
Purpose
okvConnSet
can be used to set up the user client connection provider which can be used to establish connection to the Oracle Key Vault server. Subsequent Oracle Key Vault functions will use this connection for communicating with the Oracle Key Vault server.
Syntax
OKVErrNo okvConnSet(OKVEnv *env, void *connCtx, OKVErrNo (*connectFn)(void *ctx), void (*disconnectFn)(void *ctx), OKVErrNo (*sendRecvFn)(void *ctx, ub1 *send_bytes, ub4 send_bytes_len, ub1 **recv_bytes, ub4 *recv_bytes_len));
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
connCtx |
IN |
Client defined connection context. |
connectFn |
IN |
Client defined connect function. |
disconnectFn |
IN |
Client defined disconnect function. |
sendRecvFn |
IN |
Client defined send response to Oracle Key Vault server and receive response from Oracle Key Vault server function. |
ctx |
IN |
Client defined connection context. |
send_bytes |
IN |
KMIP TTLV request message. |
send_bytes_len |
IN |
KMIP TTLV request message length. |
recv_bytes |
IN/OUT |
KMIP TTLV response message. |
recv_bytes_len |
IN/OUT |
KMIP TTLV response message length. |
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 Oracle Key Vault Client SDK also provides native connection management support. The endpoint program does not have to do anything special if it wants the Oracle Key Vault client SDK to take care of connection management.
Example
/* Suppose the client has defined clientConnect(), clientDisconnect(), clientSendRecv() and clientNatCtxP for connection management. The client can make use of these functions by initializing the Oracle Key Vault environment handle with the Oracle Key Vault connection context structure */ ... OKVErrNo err_no; err_no = okvConnSet(env, clientNatCtxP, clientConnect(...), clientDisconnect(...), clientSendRecv(...)); if (err_no) { printf("Error while setting the client defined connection functions to environment handle\n"); } else { printf("Successfully set the environment handle with client defined connection functions"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK Connection Management APIs
8.4 okvConnUnSet
okvConnUnSet
is used to free the client connection provider.
Category
Connection management API
Purpose
okvConnUnSet
is used to free the client connection provider.
Syntax
void okvConnUnSet(OKVEnv *env);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
Return Values
No values returned.
Comments
The Oracle Key Vault client SDK also provides native connection management support. The endpoint program does not have to do anything special if it wants the Oracle Key Vault client SDK to take care of connection management.
Example
okvConnUnSet(env);
Related Topics
Parent topic: Oracle Key Vault Client SDK Connection Management APIs
8.5 okvDisconnect
okvDisconnect
ends the Oracle Key Vault interface session and disconnects the Secure Sockets Layer (SSL) connection between the endpoint and the Oracle Key Vault server.
Category
Connection management API
Purpose
okvDisconnect
ends the Oracle Key Vault session and will disconnect SSL connection between the endpoint program and the Oracle Key Vault server.
Syntax
OKVErrNo okvDisconnect(OKVEnv *env);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
|
|
Oracle Key Vault environment handle. |
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
OKVErrNo err_no; printf("Disconnnecting Oracle Key Vault Session\n"); err_no = okvDisconnect(env); if (err_no) { printf("Could not disconnect from Oracle Key Vault session\n"); return 1; } else { printf("Successfully disconnected from Oracle Key Vault Session\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK Connection Management APIs