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.

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
env	IN	Oracle Key Vault environment handle.

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

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");
}

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.
respmsg	IN/OUT	KMIP TTLV response message.
respmsg1	IN/OUT	KMIP TTLV response message length.

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 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");
}

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: OKV_SUCCESS (0) is returned. 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");
}

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);

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
env	IN	Oracle Key Vault environment handle.

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

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");
}