11 Oracle Key Vault Client SDK KMIP and Batch APIs
The SDK KMIP APIs provide functions for creating keys, activating keys, adding attributes to keys, destroying keys, and other operations. The batch APIs enable you to perform these activities in a batch operation.
- Oracle Key Vault Client SDK KMIP APIs
This section describes the interfaces for the Oracle Key Vault functions for KMIP operations. - Oracle Key Vault Client SDK Batch APIs
This section describes the interfaces for the Oracle Key Vault KMIP batch functions.
Parent topic: Oracle Key Vault Client C SDK API Reference
11.1 Oracle Key Vault Client SDK KMIP APIs
This section describes the interfaces for the Oracle Key Vault functions for KMIP operations.
- About the Oracle Key Vault Client SDK KMIP APIs
The Oracle Key Vault KMIP APIs enable you to perform actions such as managing keys and secret data. - okvActivate
okvActivate
implements the KMIP Activate operation. - okvAddAttribute
okvAddAttribute
implements the KMIP Add attribute operation. - okvCreateKey
okvCreateKey
implements the KMIP Create operation for the KMIP symmetric key object. - okvDeleteAttribute
okvDeleteAttribute
implements the KMIP Delete attribute operation. - okvDestroy
okvDestroy
implements the KMIP Destroy operation. - okvGetAttributeList
okvGetAttributeList
implements KMIP Get attribute list operation. - okvGetAttributes
okvGetAttributes
implements KMIP Get attribute operation. - okvGetCertificate
okvGetCertificate
implements the KMIP Get operation for the Certificate object. - okvGetCertificateRequest
okvGetCertificateRequest
implements the KMIP Get operation for the Certificate request object. - okvGetKey
okvGetKey
implements the KMIP Get operation for the KMIP symmetric key object. - okvGetOpaqueData
okvGetOpaqueData
implements the KMIP Get operation for the KMIP opaque data object. - okvGetPrivateKey
okvGetPrivateKey
implements the KMIP Get operation for the KMIP private key object. - okvGetPublicKey
okvGetPublicKey
implements the KMIP Get operation for the KMIP public key object. - okvGetSecretData
okvGetSecretData
implements the KMIP Get operation for the KMIP secret data object. - okvGetTemplate
okvGetTemplate
implements the KMIP Get operation for the KMIP template object. - okvLocate
okvLocate
implements the KMIP Locate operation. - okvModifyAttribute
okvModifyAttribute
implements the KMIP Modify attribute operation. - okvQueryCapability
okvQueryCapability
implements the KMIP Query operation. - okvRegCertificate
okvRegCertificate
implements the KMIP Register operation for the KMIP certificate object. - okvRegCertificateRequest
okvRegCertificateRequest
implements the KMIP Register operation for the certificate request object. - okvRegKey
okvRegKey
implements the KMIP Register operation for the KMIP symmetric key object. - okvRegOpaqueData
okvRegOpaqueData
implements the KMIP Register operation for the KMIP opaque data object. - okvRegPrivateKey
okvRegPrivateKey
implements the KMIP Register operation for the KMIP private key object. - okvRegPublicKey
okvRegPublicKey
implements the KMIP Register operation for the KMIP public key object. - okvRegSecretData
okvRegSecretData
implements the KMIP Register operation for the KMIP secret data object. - okvRegTemplate
okvRegTemplate
implements the KMIP Register operation for the KMIP template object. - okvRekey
okvRekey
implements the KMIP Rekey operation. - okvRevoke
okvRevoke
implements the KMIP Revoke operation.
Parent topic: Oracle Key Vault Client SDK KMIP and Batch APIs
11.1.1 About the Oracle Key Vault Client SDK KMIP APIs
The Oracle Key Vault KMIP APIs enable you to perform actions such as managing keys and secret data.
Many of these functions take unique identifier as an input argument. As per KMIP v1.1, the unique identifier can be optional when the commands are batched given that the KMIP server can determine a single unique identifier from the previous commands. So if the previous command like locate returns only one unique identifier for possible use-cases, and the following commands operate on this unique identifier, the unique identifier can be omitted from the following commands.
The unique identifiers, along with their lengths, will be returned from the KMIP API functions. The unique identifiers needs to be NULL terminated by the endpoint program.
The endpoint program can pass in a larger buffer and the length will be used to determine the actual unique identifier bits in the larger buffer.
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.2 okvActivate
okvActivate
implements the KMIP Activate
operation.
Category
KMIP API
Purpose
okvActivate
implements the KMIP Activate operation. It
will activate the KMIP object identified by its unique identifier.
Syntax
OKVErrNo okvActivate(OKVEnv *env, oratext *uid);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
uid |
|
Unique identifier (can be |
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
/* Create the KMIP object, say Key for example and get its unique identifier as part of its creation in ‘uid’ and then activate it as below */ okvActivate(env, &uid[0]); if (okvErrGetNum(env)) { printf("Error while activating the object\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.3 okvAddAttribute
okvAddAttribute
implements the KMIP Add attribute
operation.
Catetory
KMIP API
Purpose
okvAddAttribute
implements the KMIP Add attribute operation. It adds
an attribute to the KMIP object specified by the unique identifier.
Syntax
OKVErrNo okvAddAttribute(OKVEnv *env, oratext *uid, OKVTTLV **attr);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
uid |
IN |
Unique identifier (can be |
attr |
IN |
Attribute to be added to the KMIP object. |
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
- If attributes are added to opaque or template objects using this API, the Oracle
Key Vault server will give a general failure error and the attributes will not be
added to the KMIP object. As a workaround the attributes can be added during the
registration using APIs
okvRegOpaqueData
andokvRegTemplate
. - If a single instance attribute is added to an object using this API and the
object already has an instance of the attribute, then the attribute won’t get
overwritten, but a general failure error will be thrown. Please use the
okvModifyAttribute
API to modify attribute values. - If a protect stop date later than the deactivation date is passed in request TTLV, the server will not give an error and the protect stop date will be added to registered KMIP object.
- If a process start date is added using this API, the server will give permission
denied error. As a workaround the attribute can be added during registration using
APIs
okvRegKey
,okvRegSecretData
,okvRegOpaqueData
, andokvRegTemplate
.
Example
/* Create the KMIP object, say Key for example and get its unique identifier as part of its creation in ‘uid’, we can add an attribute to it as shown below */ OKVTTLV *attr_in = (OKVTTLV *)NULL; OKVTTLV *req = (OKVTTLV *)NULL; oratext *name_value = (oratext *)"attribute_name"; ub4 name_valuel = strlen("attribute_name"); req = okvEnvGetOpRequestObj(env); attr_in = okvAddAttributeObject(env, req, OKVAttrName, (ub4) 0); okvAttrAddName(env, attr_in, name_value, name_valuel, 1); okvAddAttribute(env, &uid[0], &attr_in); if (okvErrGetNum(env)) { printf("Error while adding Name attribute to the object\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.4 okvCreateKey
okvCreateKey
implements the KMIP Create operation for the KMIP symmetric key object.
Category
KMIP API
Purpose
okvCreateKey
implements the KMIP Create operation for the KMIP
symmetric key object. The unique identifier of the symmetric key object generated by the
Oracle Key Vault server is returned as ouid
. The maximum length of the
unique ID for Oracle Key Vault SDK is defined by
OKV_UNIQUE_ID_MAXLEN
.
Syntax
OKVErrNo okvCreateKey(OKVEnv *env, OKVType alg, ub4 len, ub4 mask, OKVTTLV *template_names_attrs, oratext *wallet_name, ub4 wallet_namel, oratext *ouid, ub4 *ouidl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
|
|
Oracle Key Vault environment handle. |
|
|
Symmetric key algorithm. |
|
|
Key length of the symmetric key. |
|
|
Cryptographic usage mask of the symmetric key. |
|
IN |
Template names or attributes that will form the template-attribute. |
|
IN |
Wallet name value. |
|
IN |
Length of the wallet name value. |
|
|
Unique identifier of the generated key. |
|
|
Unique identifier length of the generated key. |
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
It is recommended to add a KMIP Name attribute to symmetric key object to help identify it in future.
The caller has to allocate the memory for the unique identifier returned by this
function. The length of allocated memory is passed in via the length of the unique
identifier argument ouidl
. Sufficient memory to store the returned
unique identifier should be allocated.
A symmetric key of the specified length for the specified algorithm and for a specific
use (cryptographic usage mask) is generated in wallet wallet_name
if
specified else it is generated in the default wallet if present with the endpoint.
Example
/* Parameters to create symmetric key */ OKVType algo = CRYPTO_ALG_AES; /* Key length 128, because AES keys are 128, 192 or 256 bits in length*/ ub4 key_len = 128; ub4 usage_mask = CRYPTO_MASK_ENCRYPT | CRYPTO_MASK_DECRYPT; oratext uid[OKV_UNIQUE_ID_MAXLEN + 1]; ub4 uidl = sizeof(uid); OKVTTLV *template = (OKVTTLV *)NULL; OKVTTLV *attr_in = (OKVTTLV *)NULL; /* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections */ memset(uid, 0, uidl); template = okvEnvGetOpRequestObj(env); /* Add name attribute object to template attribute */ attr_in = okvAddAttributeObject(env, template, OKVAttrName, (ub4) 0); okvAttrAddName(env, attr_in, (oratext *)"My New Key", strlen("My New Key"), 1); printf("\tCreating a Symmetric key\n"); okvCreateKey(env, algo, key_len, usage_mask, template, (oratext *)NULL, (ub4)0, &uid[0], uidl); if (okvErrGetNum(env)) { printf("Error while creating the key\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.5 okvDeleteAttribute
okvDeleteAttribute
implements the KMIP Delete attribute
operation.
Catetory
KMIP API
Purpose
okvDeleteAttribute
implements the KMIP Delete attribute operation.
It deletes an attribute specified by an attribute name and attribute index of the KMIP
object specified by the unique identifier.
Syntax
OKVErrNo okvDeleteAttribute(OKVEnv *env, oratext *uid, oratext *attr_name, ub4 attr_index, OKVTTLV **attr);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
uid |
IN |
Unique identifier (can be NULL for batching).
|
attr_name |
IN |
Name of attribute to be deleted. |
attr_index |
IN |
Index of the attribute to be deleted. |
attr |
OUT |
Attribute to be deleted from the KMIP object. |
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
/* Create the KMIP object, say Key for example and get its unique identifier as part of its creation in 'uid'. Add contact information attribute and to delete it, it can done as shown below */ OKVTTLV *attr_del = (OKVTTLV *) NULL; oratext *attr_name = okvGetTextForAttributeNum(OKVAttrContactInfo); /* Passing Contact Info attribute to be deleted at attribute index 0 */ okvDeleteAttribute(env, &uid[0], attr_name, (ub4)0, &attr_del); if (okvErrGetNum(env)) { printf("Error while deleting the contact info attribute of the object\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.6 okvDestroy
okvDestroy
implements the KMIP Destroy
operation.
Catetory
KMIP API
Purpose
okvDestroy
implements the KMIP Destroy operation. It will destroy
the KMIP object specified by unique identifier.
Syntax
OKVErrNo okvDestroy(OKVEnv *env, oratext *uid);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
uid |
IN |
Unique identifier (can be |
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
/* Create the KMIP object, say Key for example and get its unique identifier as part of its creation in 'uid', activate it, revoke it and then you can destroy it as below */ okvDestroy(env, &uid[0]); if (okvErrGetNum(env)) { printf("Error while destroying the object\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.7 okvGetAttributeList
okvGetAttributeList
implements KMIP Get attribute list
operation.
Catetory
KMIP API
Purpose
okvGetAttributeList
implements KMIP Get attribute list operation.
It retrieves the names of the regular and custom attributes of a KMIP object specified
by the unique identifier.
attr_names_count
specifies how many attr_names
can
be accommodated in attr_names
and
okvGetAttributeList()
will only copy that many attribute names. If
there are more attributes then attr_names_count
will be modified to
store the actual number of attributes in the returned request.
Syntax
OKVErrNo okvGetAttributeList(OKVEnv *env, oratext *uid, ub4 *attr_names_count, oratext **attr_names);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault Interface environment handle. |
uid |
IN |
Unique identifier (can be |
attr_names_count |
IN/OUT |
Count of the attributes. |
attr_names |
OUT |
Names of the attributes. |
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 list retrieved is unordered.
Example
/* Create the KMIP object, say Key for example and get its unique identifier as part of its creation in 'uid'. Add attributes like say name, contact info and then names of these attributes can be retrieved as below */ … ub4 attr_list_count = 0; oratext **attr_names = (oratext **)NULL; printf("\tGetting the count of attributes associated with the key\n"); okvGetAttributeList(env, uid, &attr_list_count, (oratext **)NULL); if (okvErrGetNum(env)) { printf("Error while getting the attribute list count\n"); } printf("\tGetting the attribute names associated with the key\n"); attr_names = (oratext **)calloc(attr_list_count, sizeof(oratext *)); for (i = 0; i < attr_list_count; i++) { /* Allocate memory to hold attribute names */ attr_names[i] = (oratext *)calloc(OKV_NAME_MAXLEN, sizeof(oratext)); } okvGetAttributeList(env, uid, &attr_list_count, (oratext **)attr_names); if (okvErrGetNum(env)) { printf("Error while getting the attribute list names\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.8 okvGetAttributes
okvGetAttributes
implements KMIP Get attribute operation.
Catetory
KMIP API
Purpose
okvGetAttributes
implements KMIP Get attribute operation. It
retrieves the specified list of regular and custom attributes for a given KMIP object
specified by the unique identifier.
Syntax
OKVErrNo okvGetAttributes(OKVEnv *env, oratext *uid, ub4 attr_names_count, oratext **attr_names, OKVTTLV **attrs);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
uid |
IN |
Unique identifier (can be |
attr_names_count |
IN |
Count of the attributes to be retrieved. |
attr_names |
IN |
Names of the attributes to be retrieved. |
attrs |
OUT |
Attributes retrieved. |
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 list retrieved is unordered.
Example
/* Create the KMIP object, say Key for example and get its unique identifier as part of its creation in 'uid'. Add contact information Name, Cryptographic Alogirthm, Cryptographic Length attributes to the created key and then all of these attributes can be retrieved as below */ ... OKVTTLV *attrs = (OKVTTLV *) NULL; oratext *attr_name_list[3]; attr_name_list[0] = okvGetTextForAttributeNum(OKVAttrName); attr_name_list[1] = okvGetTextForAttributeNum(OKVAttrCryptoAlg); attr_name_list[2] = okvGetTextForAttributeNum(OKVAttrCryptoLen); okvGetAttributes(env, uid, 3, (oratext **) attr_name_list, &attrs); if (okvErrGetNum(env)) { printf("Error while getting the attributes of the object\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.9 okvGetCertificate
okvGetCertificate
implements the KMIP Get operation for the
Certificate object.
Catetory
KMIP API
Purpose
okvGetCertificate
implements the KMIP Get operation for
the Certificate object.
For the specified unique identifier of the certificate, the certificate type, certificate length, the actual certificate bytes in the endpoint program supplied buffer and the actual length of the certificate bytes are returned.
If the length of the certificate buffer supplied is smaller than the
length of the actual certificate retrieved from the Oracle Key Vault Server, then
certificatel
is populated with the actual
certificate
length but certificate is set to NULL.
Syntax
OKVErrNo okvGetCertificate(OKVEnv *env, oratext *uid, ub4 *certificate_type, ub1 *certificate, ub4 *certificatel);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
uid |
|
Unique identifier of the certificate (can be NULL for batching). |
certificate_type |
|
Type of certificate. |
certificate |
|
Certificate. |
certificatel |
|
Length of the certificate. |
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. |
Supported Versions
Oracle Key Vault C SDK version 21.2.0.0.0 and later.
Comments
None.
Example
/* Create a Certificate for example and get its unique identifier as part of its creation in 'uid' */ ... ub1 *cert; ub4 certl = 128001; ub4 cert_type = 0; cert = (ub1 *)malloc(certl * sizeof(ub1)); printf("\tGetting the certificate\n"); okvGetCertificate(env, uid, &cert_type, cert, &certl); if (okvErrGetNum(env)) { printf("Error while getting the certificate\n"); } /* Free 'cert' */
Related Topics
- okvActivate
- okvAddAttribute
- okvCreateKey
- okvDeleteAttribute
- okvDestroy
- okvGetAttributeList
- okvGetAttributes
- okvGetCertificateRequest
- okvGetKey
- okvGetOpaqueData
- okvGetPrivateKey
- okvGetPublicKey
- okvGetSecretData
- okvGetTemplate
- okvLocate
- okvModifyAttribute
- okvQueryCapability
- okvRegCertificate
- okvRegCertificateRequest
- okvRegKey
- okvRegOpaqueData
- okvRegPrivateKey
- okvRegPublicKey
- okvRegSecretData
- okvRegTemplate
- okvRevoke
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.10 okvGetCertificateRequest
okvGetCertificateRequest
implements the KMIP Get operation
for the Certificate request object.
Catetory
KMIP API
Purpose
okvGetCertificateRequest
implements the KMIP Get
operation for the Certificate request object.
For the specified unique identifier of the certificate request, the certificate request type, certificate request length, the actual certificate request bytes in the endpoint program supplied buffer and the actual length of the certificate request bytes are returned.
If the length of the certificate request buffer supplied is smaller than the length
of the actual certificate request retrieved from the Oracle Key Vault Server, then
the certificate_requestl
is populated with the actual certificate
request length but certificate_request
is set to NULL.
Syntax
OKVErrNo okvGetCertificateRequest(OKVEnv *env, oratext *uid, ub4 *certificate_request_type, ub1 *certificate_request, ub4 *certificate_requestl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
uid |
|
Unique identifier of the certificate request (can be NULL for batching). |
certificate_request_type |
|
Type of certificate request. |
certificate_request |
|
Certificate request. |
certificate_requestl |
|
Length of the certificate request. |
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. |
Supported Versions
Oracle Key Vault C SDK version 21.2.0.0.0 and later.
Comments
None.
Example
/* Create a Certificate Request for example and get its unique identifier as part of its creation in 'uid' */ ... ub1 *cert_req; ub4 cert_reql = 128001; ub4 cert_req_type = 0; cert_req = (ub1 *)malloc(cert_reql * sizeof(ub1)); printf("\tGetting the certificate request\n"); okvGetCertificateRequest(env, uid, &cert_req_type, cert_req, &cert_reql); if (okvErrGetNum(env)) { printf("Error while getting the certificate request\n"); } /* Free 'cert_req' */
Related Topics
- okvActivate
- okvAddAttribute
- okvCreateKey
- okvDeleteAttribute
- okvDestroy
- okvGetAttributeList
- okvGetAttributes
- okvGetCertificate
- okvGetKey
- okvGetOpaqueData
- okvGetPrivateKey
- okvGetPublicKey
- okvGetSecretData
- okvGetTemplate
- okvLocate
- okvModifyAttribute
- okvQueryCapability
- okvRegCertificate
- okvRegCertificateRequest
- okvRegKey
- okvRegOpaqueData
- okvRegPrivateKey
- okvRegPublicKey
- okvRegSecretData
- okvRegTemplate
- okvRevoke
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.11 okvGetKey
okvGetKey
implements the KMIP Get operation for the KMIP
symmetric key object.
Catetory
KMIP API
Purpose
okvGetKey
implements the KMIP Get operation for the KMIP symmetric
key object.
For the specified unique identifier of the symmetric key, the key length, key algorithm, the actual key bytes in the endpoint program supplied buffer and the actual length of the key bytes are returned.
If the length of the key buffer supplied is smaller than the length of the actual key retrieved from the Oracle Key Vault Server, then the keyl
is populated with the actual key length but key is set to NULL
.
Syntax
OKVErrNo okvGetKey(OKVEnv *env, oratext *uid, ub4 *key_alg, ub4 *key_len, ub1 *key, ub4 *keyl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
uid |
|
Unique identifier of the key (can be |
key_alg |
|
Symmetric key algorithm. |
key_len |
|
Key length of the symmetric key provided at the time of creation. |
key |
|
Symmetric key. |
keyl |
|
Length of the symmetric key. |
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
/* Create a Symmetric Key for example and get its unique identifier as part of its creation in 'uid' */ ... ub1 *key; ub4 keyl = 128001; ub4 key_algo = 0; ub4 key_len = 0; key = (ub1 *)malloc(keyl * sizeof(ub1)); printf("\tGetting the key\n"); okvGetKey(env, uid, &key_algo, &key_len, key, &keyl); key[keyl] = 0; if (okvErrGetNum(env)) { printf("Error while getting the key\n"); } /* Free ‘key’ */
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.12 okvGetOpaqueData
okvGetOpaqueData
implements the KMIP Get operation for the
KMIP opaque data object.
Catetory
KMIP API
Purpose
okvGetOpaqueData
implements the KMIP Get operation for the KMIP
opaque data object.
For the specified unique identifier of the opaque data, the opaque data type, the opaque data length and the opaque data bytes in the endpoint program supplied buffer is returned.
If the length of the opaque data buffer supplied is smaller than the length of the actual opaque data retrieved from the Oracle Key Vault server, then opaque_datal
is populated with the actual opaque data length but opaque_data
is set to NULL
.
Syntax
OKVErrNo okvGetOpaqueData(OKVEnv *env, oratext *uid, ub4 *opaque_data_type, ub1 *opaque_data, ub4 *opaque_datal);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
|
|
Oracle Key Vault environment handle. |
|
|
Unique identifier of the opaque object (can be |
|
|
Type of opaque object. |
|
|
Opaque object. |
|
|
Length of opaque object. |
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
/* Create an opaque data for example and get its unique identifier as part of its creation in 'uid' */ ... ub1 *opaque_data; ub4 opaque_data_len = 128001; ub4 opaque_data_type = 0; opaque_data = (ub1 *)malloc(opaque_data_len*sizeof(ub1)); okvGetOpaqueData(env, &uid[0], &opaque_data_type, &opaque_data[0], &opaque_data_len); if (okvErrGetNum(env)) { printf("Error while getting the opaque data\n"); } /* Free "opaque_data" */
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.13 okvGetPrivateKey
okvGetPrivateKey
implements the KMIP Get operation for the
KMIP private key object.
Catetory
KMIP API
Purpose
okvGetPrivateKey
implements the KMIP Get operation for
the KMIP private key object.
For the specified unique identifier of the private key, the private key length, private key algorithm, the actual private key bytes in the endpoint program supplied buffer and the actual length of the private key bytes are returned.
If the length of the private key buffer supplied is smaller than the
length of the actual private key retrieved from the Oracle Key Vault server, then
private_keyl
is populated with the actual private key length
but private_key
is set to NULL.
Syntax
OKVErrNo okvGetPrivateKey(OKVEnv *env, oratext *uid, ub4 *private_key_alg, ub4 *private_key_len, ub1 *private_key, ub4 *private_keyl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
uid |
|
Unique identifier of the private key (can be NULL for batching). |
private_key_alg |
|
Private key algorithm. |
private_key_len |
|
Key length of the private key provided at the time of creation. |
private_key |
|
Private key. |
private_keyl |
|
Length of the private key. |
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. |
Supported Versions
Oracle Key Vault C SDK version 21.2.0.0.0 and later.
Comments
None.
Example
/* Create a Private Key for example and get its unique identifier as part of its creation in 'uid' */ ... ub1 *private_key; ub4 private_keyl = 128001; ub4 private_key_algo = 0; ub4 private_key_len = 0; private_key = (ub1 *)malloc(private_keyl * sizeof(ub1)); printf("\tGetting the private key\n"); okvGetPrivateKey(env, uid, &private_key_algo, &private_key_len, private_key, &private_keyl); private_key[private_keyl] = 0; if (okvErrGetNum(env)) { printf("Error while getting the private key\n"); } /* Free 'private_key' */
Related Topics
- okvActivate
- okvAddAttribute
- okvCreateKey
- okvDeleteAttribute
- okvDestroy
- okvGetAttributeList
- okvGetAttributes
- okvGetCertificate
- okvGetCertificateRequest
- okvGetKey
- okvGetOpaqueData
- okvGetPublicKey
- okvGetSecretData
- okvGetTemplate
- okvLocate
- okvModifyAttribute
- okvQueryCapability
- okvRegCertificate
- okvRegCertificateRequest
- okvRegKey
- okvRegOpaqueData
- okvRegPrivateKey
- okvRegPublicKey
- okvRegSecretData
- okvRegTemplate
- okvRevoke
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.14 okvGetPublicKey
okvGetPublicKey
implements the KMIP Get operation for the
KMIP public key object.
Catetory
KMIP API
Purpose
okvGetPublicKey
implements the KMIP Get operation for
the KMIP public key object.
For the specified unique identifier of the public key, the public key length, public key algorithm, the actual public key bytes in the endpoint program supplied buffer and the actual length of the public key bytes are returned.
If the length of the public key buffer supplied is smaller than the
length of the actual public key retrieved from the Oracle Key Vault Server, then the
public_keyl
is populated with the actual public key length but
public_key
is set to NULL.
Syntax
OKVErrNo okvGetPublicKey(OKVEnv *env, oratext *uid, ub4 *public_key_alg, ub4 *public_key_len, ub1 *public_key, ub4 *public_keyl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
uid |
|
Unique identifier of the public key (can be NULL for batching). |
public_key_alg |
|
Public key algorithm. |
public_key_len |
|
Key length of the public key provided at the time of creation. |
public_key |
|
Public key. |
public_keyl |
|
Length of the public key. |
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. |
Supported Versions
Oracle Key Vault C SDK version 21.2.0.0.0 and later.
Comments
None.
Example
/* Create a Public Key for example and get its unique identifier as part of its creation in 'uid' */ ... ub1 *public_key; ub4 public_keyl = 128001; ub4 public_key_algo = 0; ub4 public_key_len = 0; public_key = (ub1 *)malloc(public_keyl * sizeof(ub1)); printf("\tGetting the public key\n"); okvGetPublicKey(env, uid, &public_key_algo, &public_key_len, public_key, &public_keyl); public_key[public_keyl] = 0; if (okvErrGetNum(env)) { printf("Error while getting the public key\n"); } /* Free 'public_key' */
Related Topics
- okvActivate
- okvAddAttribute
- okvCreateKey
- okvDeleteAttribute
- okvDestroy
- okvGetAttributeList
- okvGetAttributes
- okvGetCertificate
- okvGetCertificateRequest
- okvGetKey
- okvGetOpaqueData
- okvGetPrivateKey
- okvGetSecretData
- okvGetTemplate
- okvLocate
- okvModifyAttribute
- okvQueryCapability
- okvRegCertificate
- okvRegCertificateRequest
- okvRegKey
- okvRegOpaqueData
- okvRegPrivateKey
- okvRegPublicKey
- okvRegSecretData
- okvRegTemplate
- okvRevoke
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.15 okvGetSecretData
okvGetSecretData
implements the KMIP Get operation for the
KMIP secret data object.
Catetory
KMIP API
Purpose
okvGetSecretData
implements the KMIP Get operation for the KMIP
secret data object.
For the specified unique identifier of the secret data, the secret data type, the secret data length and the secret data bytes in the endpoint program supplied buffer is returned.
If the length of the secret data buffer supplied is smaller than the length of the actual secret data retrieved from the Oracle Key Vault server, then the secret_datal
is populated with the actual secret data length but secret_data
is set to NULL
.
Syntax
OKVErrNo okvGetSecretData(OKVEnv *env, oratext *uid, ub4 *secret_data_type, ub1 *secret_data, ub4 *secret_datal);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
|
|
Oracle Key Vault environment handle. |
|
|
Unique identifier of the secret data (can be |
|
|
Type of secret data. |
|
|
Secret data. |
|
|
Length of secret data. |
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
/* Create a secret data for example and get its unique identifier as part of its creation in 'uid' */ ... ub1 *secret_data; ub4 secret_data_len = 128001; ub4 secret_data_type = 0; secret_data = (ub1 *)malloc(secret_data_len*sizeof(ub1)); okvGetSecretData(env, &uid[0], &secret_data_type, &secret_data[0], &secret_data_len); if (okvErrGetNum(env)) { printf("Error while getting the secret data\n"); } /* Free "secret_data" */
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.16 okvGetTemplate
okvGetTemplate
implements the KMIP Get operation for the KMIP template object.
Catetory
KMIP API
Purpose
okvGetTemplate
implements the KMIP Get operation for the KMIP template object.
The template is a list of attributes, which can be interpreted using the Oracle Key Vault utility or Oracle Key Vault KMIP extension functions. For the specified unique identifier of the template, the attributes of the template object are returned.
Syntax
OKVErrNo okvGetTemplate(OKVEnv *env, oratext *uid, OKVTTLV **attrs_template);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
|
|
Oracle Key Vault environment handle. |
|
|
Unique identifier of the template (can be NULL for Batching). |
|
|
Attributes of the template. |
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
This API will throw a general failure error while retrieving the template with process start date and protect stop date in the case if we register the template with these attributes.
For each create or register operation that uses retrieved attributes of the template
object, okvGetTemplate
should be used before that operation.
Example
/* Create a template for example and get its unique identifier as part of its creation in 'uid' */ ... OKVTTLV *template = (OKVTTLV *) NULL; okvGetTemplate(env, uid, &template); if (okvErrGetNum(env)) { printf("Error while getting the template\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.17 okvLocate
okvLocate
implements the KMIP Locate operation.
Catetory
KMIP API
Purpose
okvLocate
implements the KMIP Locate operation.
The locate operation will look up all the objects in Oracle Key Vault that match the
attributes specified in the locate_attrs
.
uid_cnt
should indicate the actual number of unique identifiers
strings.
uids
are the UIDS of the objects that match the attributes specified in
locate_attrs
.
Syntax
OKVErrNo okvLocate(OKVEnv *env, ub4 uid_max, ub4 storage_status, OKVTTLV *locate_attrs, ub4 *uid_cnt, oratext **uids);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
|
|
Oracle Key Vault environment handle. |
|
|
Maximum number of unique identifiers expected. |
|
|
Look for archived or online objects. |
|
|
Attributes that define the locate search. |
|
|
Number of unique identifiers returned by the server. |
|
|
Unique identifiers that match the locate attributes and storage status criteria. |
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 caller has to allocate sufficient memory for the unique identifiers
uids
returned by this function. The only exception is irrespective
of what the uid_max
value is, all the UIDs are returned by the Oracle
Key Vault server that match the attributes specified in
locate_attrs
.
Example
/* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections. Create a key with a name attribute value "MyNewKey" for example and get its unique identifier as part of its creation in 'uid'. Locate operation can be done as shown below. */ ... ub4 locate_count = 0; ub4 uid_max = 1; OKVTTLV *loc_attrs = (OKVTTLV *)NULL; OKVTTLV *attr_in = (OKVTTLV *)NULL; oratext **locate_uids = (oratext **) malloc(uid_max * sizeof(oratext *)); ub4 itr = 0; for (itr = 0; itr < uid_max; itr++) { locate_uids[itr] = (oratext *) malloc(OKV_UNIQUE_ID_MAXLEN * sizeof(oratext)); } loc_attrs = okvEnvGetOpRequestObj(env); attr_in = okvAddAttributeObject(env, loc_attrs, OKVAttrName, (ub4) 0); /* Add name attribute value to name attribute object */ okvAttrAddName(env, attr_in, (oratext *) "MyNewKey", strlen("MyNewKey"), 1); okvLocate(env, uid_max, 1, loc_attrs, &locate_count, locate_uids); if (okvErrGetNum(env)) { printf("Error while Locating the Key: MyNewKey\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.18 okvModifyAttribute
okvModifyAttribute
implements the KMIP Modify attribute
operation.
Catetory
KMIP API
Purpose
okvModifyAttribute
implements the KMIP Modify attribute operation.
It modifies an attribute of the KMIP Object specified by the unique identifier.
Syntax
OKVErrNo okvModifyAttribute(OKVEnv *env, oratext *uid, OKVTTLV **attr);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
uid |
IN |
Unique identifier (can be |
attr |
IN |
Attribute of the KMIP object that needs to be modified. |
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
/* Create the KMIP object, say Key for example and get its unique identifier as part of its creation in 'uid', we can add an attribute and modify it as shown shown below */ OKVTTLV *templ = (OKVTTLV *) NULL; OKVTTLV *req = (OKVTTLV *) NULL; OKVTTLV *attr_temp = (OKVTTLV *) NULL; OKVTTLV *attr_in = (OKVTTLV *) NULL; oratext *contact = (oratext *)"9123456789"; ub4 contactl = strlen((char *) contact); oratext *new_contact = (oratext *)"abc.xyz@com"; ub4 new_contactl = strlen((char *) new_contact); templ = okvEnvGetOpRequestObj(env); attr_temp = okvAddAttributeObject(env, templ, OKVAttrContactInfo, (ub4) 0); okvAttrAddContactInfo(env, attr_temp, contact, contactl); okvAddAttribute(env, &uid[0], &attr_temp); /* Now let's modify the contact info attribute */ req = okvEnvGetOpRequestObj(env); attr_in = okvAddAttributeObject(env, req, OKVAttrContactInfo, (ub4) 0); okvAttrAddContactInfo(env, attr_in, new_contact, new_contactl); okvModifyAttribute(env, &uid[0], &attr_in); if (okvErrGetNum(env)) { printf("Error while modifying the contact info attribute of the object\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.19 okvQueryCapability
okvQueryCapability
implements the KMIP Query
operation.
Catetory
KMIP API
Purpose
okvQueryCapability
implements the KMIP Query operation.
OKVDEF_QUERY_OPERATIONS
OKVDEF_QUERY_OBJECTS
OKVDEF_QUERY_SERVER_INFO
The count of the item not requested in the query function will be zero. If server information is not requested then server_information
can be NULL
.
Syntax
OKVErrNo okvQueryCapability(OKVEnv *env, ub4 query_function_cnt, ub4 *query_function, ub4 *operation_cnt, OKVOpsNo *operation, ub4 *object_type_cnt, OKVObjNo *object_type, OKVServerInformation *server_information);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
|
|
Oracle Key Vault environment handle. |
|
|
Count of KMIP functions requested. |
|
|
KMIP functions requested. |
|
|
Count of KMIP operations supported. |
|
|
KMIP operations supported. |
|
|
Count of KMIP managed objects supported. |
|
|
KMIP managed objects supported. |
|
|
Oracle Key Vault server specific information. |
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
/* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections. */ ... OKVServerInformation s; ub4 query_function[1]; ub4 operation_cnt = 30; OKVOpsNo operation[30]; ub4 object_type_cnt = 30; OKVObjNo object_type[30]; query_function[0] = 3; okvQueryCapability(env,1, query_function, &operation_cnt, operation, &object_type_cnt, object_type, &s); if (okvErrGetNum(env)) { printf("Error while executing okvQueryCapability"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.20 okvRegCertificate
okvRegCertificate
implements the KMIP Register operation for
the KMIP certificate object.
Catetory
KMIP API
Purpose
okvRegCertificate
implements the KMIP Register
operation for the KMIP certificate object.
The certificate of a specific type is registered with Oracle Key Vault Server. The
unique identifier of the certificate object generated by the Oracle Key Vault server
is returned as ouid
.
The maximum length of the unique ID for Oracle Key Vault SDK is defined by
OKV_UNIQUE_ID_MAXLEN
.
The new certificate being registered can take in additional attributes specified with the help of attributes or also with the template names. The attributes, and also the template names if specified, will be the template attribute added to KMIP register operation.
Syntax
OKVErrNo okvRegCertificate(OKVEnv *env, ub4 certificate_type, ub4 certificate_subtype, ub1 *certificate, ub4 certificatel, ub4 mask, OKVTTLV *template_names_attrs, oratext *private_key_uid, ub4 private_key_uidl, oratext *wallet_name, ub4 wallet_namel, oratext *ouid, ub4 *ouidl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
certificate_type |
|
Certificate type. |
certificate_subtype |
|
Certificate sub-type. |
certificate |
|
Certificate. |
certificatel |
|
Certificate length. |
mask |
|
Cryptographic usage mask of the certificate. |
template_names_attrs |
|
Template names or attributes that will form the template-attribute. |
private_key_uid |
|
Unique identifier of the private key associated with the certificate (optional). |
private_key_uidl |
|
Unique identifier length of the private key associated with the certificate (optional). |
wallet_name |
|
Wallet name value. |
wallet_namel |
|
Length of the wallet name value. |
ouid |
|
Unique identifier of the registered certificate. |
ouidl |
|
Unique identifier length of the registered certificate. |
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. |
Supported Versions
Oracle Key Vault C SDK version 21.2.0.0.0 and later.
Comments
It is recommended to add a KMIP name attribute to certificate object to help identify it in future.
The caller has to allocate the memory for the unique identifier returned
by this function. The length of allocated memory is passed in via the length of the
unique identifier argument ouidl
. Sufficient memory to store the
returned unique identifier should be allocated.
The certificate being registered can optionally be associated with a
private key by providing the UID of the private key
(private_key_uid
). Validate the existence of
private_key_uid
by performing a locate operation (using
okvLocate
API) before passing it as an argument to this
API.
certificate_subtype
argument:
OKV_CERT_SUBTYPE_USER_CERT
: represents User Certificate.OKV_CERT_SUBTYPE_TRUSTPOINT
: represents Trustpoint.
The certificate is registered with Oracle Key Vault server in wallet
wallet_name
if specified else it is registered in the default
wallet if present with the endpoint.
Example
/* X.509 Certificate type */ ub4 cert_type = OKVDEF_CERT_TYPE_X509; /* Certificate Subtype */ ub4 cert_subtype = OKV_CERT_SUBTYPE_USER_CERT; /* Usage mask */ ub4 cert_mask = CRYPTO_MASK_ENCRYPT; ub1 cert[] = "-----BEGIN CERTIFICATE----- MIIEvQIBADANBgkqhkiG9w0BAQE…………………………………. -----END CERTIFICATE-----"; ub4 certl = strlen((const char *)cert); oratext uid[OKV_UNIQUE_ID_MAXLEN + 1]; ub4 uidl = sizeof(uid); OKVTTLV *template = (OKVTTLV *)NULL; OKVTTLV *attr_in = (OKVTTLV *)NULL; /* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections */ memset(uid, 0, uidl); template = okvEnvGetOpRequestObj(env); /* Add name attribute object to request handle */ attr_in = okvAddAttributeObject(env, template, OKVAttrName, (ub4) 0); /* Add name attribute value to name attribute object */ okvAttrAddName(env, attr_in, (oratext *)"My Certificate for Register operation", strlen("My Certificate for Register operation"), 1); okvRegCertificate(env, cert_type, cert_subtype, cert, certl, cert_mask , template, (oratext *)NULL, (ub4)0, OKV_NO_WALLET, OKV_NO_WALLET_LEN, uid, &uidl); uid[*uidl] = '\0'; if (okvErrGetNum(env)) { printf("Error while registering the certificate\n"); }
Related Topics
- okvActivate
- okvAddAttribute
- okvCreateKey
- okvDeleteAttribute
- okvDestroy
- okvGetAttributeList
- okvGetAttributes
- okvGetCertificate
- okvGetCertificateRequest
- okvGetKey
- okvGetOpaqueData
- okvGetPrivateKey
- okvGetPublicKey
- okvGetSecretData
- okvGetTemplate
- okvLocate
- okvModifyAttribute
- okvQueryCapability
- okvRegCertificateRequest
- okvRegKey
- okvRegOpaqueData
- okvRegPrivateKey
- okvRegPublicKey
- okvRegSecretData
- okvRegTemplate
- okvRevoke
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.21 okvRegCertificateRequest
okvRegCertificateRequest
implements the KMIP Register
operation for the certificate request object.
Catetory
KMIP API
Purpose
okvRegCertificateRequest
implements the KMIP Register
operation for the certificate request object.
The certificate request object is registered as an opaque object with Oracle Key
Vault Server. The unique identifier of the certificate request object generated by
the Oracle Key Vault server is returned as ouid
.
The maximum length of the unique ID for Oracle Key Vault SDK is defined by
OKV_UNIQUE_ID_MAXLEN
.
The new certificate request being registered can take in additional attributes specified with the help of attributes or also with the template names. The attributes, and also the template names if specified, will be the template attribute added to KMIP register operation.
Syntax
OKVErrNo okvRegCertificateRequest(OKVEnv *env, ub4 certificate_request_type, ub1 *certificate_request, ub4 certificate_requestl, OKVTTLV *template_names_attrs, oratext *private_key_uid, ub4 private_key_uidl, oratext *wallet_name, ub4 wallet_namel, oratext *ouid, ub4 *ouidl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
certificate_request_type |
|
Certificate request type. |
certificate_request |
|
Certificate request. |
certificate_requestl |
|
Certificate request length. |
template_names_attrs |
|
Template names or attributes that will form the template-attribute. |
private_key_uid |
|
Unique identifier of the private key associated with the certificate request (mandatory). |
private_key_uidl |
|
Unique identifier length of the private key associated with the certificate request (mandatory). |
wallet_name |
|
Wallet name value. |
wallet_namel |
|
Length of the wallet name value. |
ouid |
|
Unique identifier of the registered certificate request. |
ouidl |
|
Unique identifier length of the registered certificate request. |
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. |
Supported Versions
Oracle Key Vault C SDK version 21.2.0.0.0 and later.
Comments
It is recommended to add a KMIP name attribute to certificate request object to help identify it in future.
The caller has to allocate the memory for the unique identifier returned by this
function. The length of allocated memory is passed in via the length of the unique
identifier argument ouidl
. Sufficient memory to store the returned
unique identifier should be allocated.
The certificate request being registered should be associated with a private key by
providing the UID of the private key (private_key_uid
). Validate
the existence of private_key_uid
by performing a locate operation
(using okvLocate
API) before passing it as an argument to this
API.
The certificate request is registered with Oracle Key Vault server in wallet
wallet_name
if specified else it is registered in the default
wallet if present with the endpoint.
Example
/* Certificate Request type */ ub4 cert_req_type = OKVDEF_CERT_REQ_TYPE_PEM; ub1 cert_req[] = "-----BEGIN CERTIFICATE REQUEST----- MIIEvQIBADANBgkqhkiG9w0BAQE…………………………………. -----END CERTIFICATE REQUEST-----"; ub4 cert_reql = strlen((const char *)cert_req); oratext uid[OKV_UNIQUE_ID_MAXLEN + 1]; ub4 uidl = sizeof(uid); OKVTTLV *template = (OKVTTLV *)NULL; OKVTTLV *attr_in = (OKVTTLV *)NULL; /* Please make sure to pass a valid Private Key UID */ oratext *private_key_uid = "64281937-768D-4F78-BF39-EBD5985BFAB2"; ub4 private_key_uidl = strlen((const char *)private_key_uid); /* Set up the environment handle ‘env’ and also the memory and connection management as shown in previous sections */ memset(uid, 0, uidl); template = okvEnvGetOpRequestObj(env); /* Add name attribute object to request handle */ attr_in = okvAddAttributeObject(env, template, OKVAttrName, (ub4) 0); /* Add name attribute value to name attribute object */ okvAttrAddName(env, attr_in, (oratext *)"My Certificate Request for Register operation", strlen("My Certificate Request for Register operation"), 1); okvRegCertificateRequest(env, cert_req_type, cert_req, cert_reql, template, private_key_uid, private_key_uidl, OKV_NO_WALLET, OKV_NO_WALLET_LEN, uid, &uidl); uid[*uidl] = '\0'; if (okvErrGetNum(env)) { printf("Error while registering the certificate request\n"); }
Related Topics
- okvActivate
- okvAddAttribute
- okvCreateKey
- okvDeleteAttribute
- okvDestroy
- okvGetAttributeList
- okvGetAttributes
- okvGetCertificate
- okvGetCertificateRequest
- okvGetKey
- okvGetOpaqueData
- okvGetPrivateKey
- okvGetPublicKey
- okvGetSecretData
- okvGetTemplate
- okvLocate
- okvModifyAttribute
- okvQueryCapability
- okvRegCertificate
- okvRegKey
- okvRegOpaqueData
- okvRegPrivateKey
- okvRegPublicKey
- okvRegSecretData
- okvRegTemplate
- okvRevoke
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.22 okvRegKey
okvRegKey
implements the KMIP Register operation for the
KMIP symmetric key object.
Catetory
KMIP API
Purpose
okvRegKey
implements the KMIP Register operation for the
KMIP symmetric key object.
The unique identifier of the symmetric key object created by the Oracle Key Vault server
is returned as ouid
.
The maximum length of the unique ID for Oracle Key Vault SDK is defined by
OKV_UNIQUE_ID_MAXLEN
.
The new key created can take in additional attributes specified with the help of attributes or also with the template names. The attributes, and also the template names if specified, will be the template attribute added to KMIP register operation.
Syntax
OKVErrNo okvRegKey(OKVEnv *env, OKVType key_alg, ub4 key_len, ub1 *key, ub4 keyl, ub4 mask, OKVTTLV *template_names_attrs, oratext *wallet_name, ub4 wallet_namel, oratext *ouid, ub4 *ouidl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
key_alg |
|
Symmetric key algorithm. |
key_len |
|
Key length of the symmetric key. |
key |
|
Symmetric key. |
keyl |
|
Symmetric key length. |
mask |
|
Cryptographic usage mask of the symmetric key. |
template_names_attrs |
|
Template names or attributes that will form the template-attribute. |
|
IN |
Wallet name value. |
|
IN |
Length of the wallet name value. |
ouid |
|
Unique identifier of the registered key. |
ouidl |
|
Unique identifier length of the registered key. |
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
It is recommended to add a KMIP name attribute to symmetric key object to help identify it in future.
The caller has to allocate the memory for the unique identifier returned by this
function. The length of allocated memory is passed in via the length of the unique
identifier argument ouidl
. Sufficient memory to store the returned
unique identifier should be allocated.
A symmetric key of the specified length for a specified algorithm and use (cryptographic
usage mask) is registered with Oracle Key Vault server in wallet
wallet_name
if specified else it is registered in the default wallet
if present with the endpoint.
Example
/* Tag for Cryptographic Algortihm AES */ OKVType algo = CRYPTO_ALG_AES; /* Key length 128, because AES keys are 128, 192 or 256 bits in length*/ ub4 key_len = 128; ub4 usage_mask = CRYPTO_MASK_ENCRYPT | CRYPTO_MASK_DECRYPT; /* Key */ ub1 key[] = "770A8A65DA156D24"; /* Length of symmetric key */ ub4 keyl = strlen((const char *)key); oratext uid[OKV_UNIQUE_ID_MAXLEN + 1]; ub4 uidl = sizeof(uid); OKVTTLV *template = (OKVTTLV *)NULL; OKVTTLV *attr_in = (OKVTTLV *)NULL; /* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections */ memset(uid, 0, uidl); template = okvEnvGetOpRequestObj(env); /* Add name attribute object to request handle */ attr_in = okvAddAttributeObject(env, template, OKVAttrName, (ub4) 0); /* Add name attribute value to name attribute object */ okvAttrAddName(env, attr_in, (oratext *)"My Key for Register operation", strlen("My Key for Register operation"), 1); okvRegKey(env, algo, key_len, &key[0], keyl, usage_mask, template, (oratext *)NULL, (ub4)0, uid, &uidl); if (okvErrGetNum(env)) { printf("Error while registering the key\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.23 okvRegOpaqueData
okvRegOpaqueData
implements the KMIP Register operation for
the KMIP opaque data object.
Catetory
KMIP API
Purpose
okvRegOpaqueData
implements the KMIP register operation for
the KMIP opaque data object.
The opaque data is a byte string. A text file, text string, binary file, or key can also be uploaded as an opaque data.
The unique identifier of the opaque data object created in the Oracle Key Vault server
for the registered opaque data is returned as ouid
.
The maximum length of the unique ID for Oracle Key Vault SDK is defined by
OKV_UNIQUE_ID_MAXLEN
.
The new opaque data created can take in additional attributes specified with the help of attributes or also with the template names. The attributes, and also the template names if specified, will be the template attribute added to KMIP Register operation.
Syntax
OKVErrNo okvRegOpaqueData(OKVEnv *env, ub4 opaque_data_type, ub1 *opaque_data, ub4 opaque_datal, OKVTTLV *template_names_attrs, oratext *wallet_name, ub4 wallet_namel, oratext *ouid, ub4 *ouidl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
opaque_data_type |
IN |
Type of opaque object being registered. |
opaque_data |
IN |
Opaque object being registered. |
opaque_data1 |
IN |
Length of opaque object being registered. |
template_names_attrs |
IN |
Template names or attributes that will form the template-attribute. |
|
IN |
Wallet name value. |
|
IN |
Length of the wallet name value. |
ouid |
OUT |
Unique identifier of the registered opaque object. |
ouid1 |
OUT |
Unique identifier length of the registered opaque object. |
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
It is recommended to add a KMIP name attribute to opaque data object to help identify it in future.
The caller has to allocate the memory for the unique identifier returned by this
function. The length of allocated memory is passed in via the length of the unique
identifier argument ouidl
. Sufficient memory to store the returned
unique identifier should be allocated.
An opaque data of a specific type is registered with Oracle Key Vault server
in wallet wallet_name
if specified else it is registered in the default
wallet if present with the endpoint. The size of the opaque data is limited by the
maximum size of the object handled by the Oracle Key Vault server.
An exception is that the attributes lease time, deactivation date, destroy date, compromise occurrence date, compromise date, and revocation reason are not supported for opaque objects.
Example
oratext *opaque_data = (oratext *)"MyNewData"; ub4 opaque_datal = strlen("MyNewData"); oratext uid[OKV_UNIQUE_ID_MAXLEN + 1]; ub4 uidl = sizeof(uid); /* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections */ memset(uid, 0, uidl); /* Register Opaque Data */ printf("\tRegistering opaque data\n"); okvRegOpaqueData(env, OKVDEF_TAG_OPAQUE_DATA_TYPE, opaque_data, opaque_datal, (OKVTTLV *)NULL, (oratext *)NULL, (ub4)0, &uid[0], uidl); if (okvErrGetNum(env)) { printf("Error while registering the opaque data\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.24 okvRegPrivateKey
okvRegPrivateKey
implements the KMIP Register operation for
the KMIP private key object.
Catetory
KMIP API
Purpose
okvRegPrivateKey
implements the KMIP Register operation
for the KMIP private key object.
The unique identifier of the private key object registered by the Oracle Key Vault
server is returned as ouid
. The maximum length of the unique ID for
Oracle Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN
.
The new private key being registered can take in additional attributes specified with the help of attributes or also with the template names. The attributes, and also the template names if specified, will be the template attribute added to KMIP register operation.
Syntax
OKVErrNo okvRegPrivateKey(OKVEnv *env, OKVType private_key_alg, ub4 private_key_len, ub1 *private_key, ub4 private_keyl, ub4 mask, OKVTTLV *template_names_attrs, oratext *wallet_name, ub4 wallet_namel, oratext *ouid, ub4 *ouidl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
private_key_alg |
IN |
Private key algorithm. |
private_key_len |
IN |
Key length of the private key. |
private_key |
IN |
Private key. |
private_keyl |
IN |
Private key length. |
mask |
IN |
Cryptographic usage mask of the private key. |
template_names_attrs |
IN |
Template names or attributes that will form the template-attribute. |
wallet_name |
IN |
Wallet name value. |
wallet_namel |
IN |
Length of the wallet name value. |
ouid |
OUT |
Unique identifier of the registered private key. |
ouidl |
OUT |
Unique identifier length of the registered private key. |
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. |
Supported Versions
Oracle Key Vault C SDK version 21.2.0.0.0 and later.
Comments
It is recommended to add a KMIP name attribute to private key object to help identify it in future.
The caller has to allocate the memory for the unique identifier returned by this
function. The length of allocated memory is passed in via the length of the unique
identifier argument ouidl
. Sufficient memory to store the returned
unique identifier should be allocated.
A private key of the specified length for a specified algorithm and use
(cryptographic usage mask) is registered with Oracle Key Vault server in wallet
wallet_name
if specified else it is registered in the default
wallet if present with the endpoint.
Example
/* Key Algorithm */ OKVType private_key_algo = CRYPTO_ALG_RSA; /* Key Size */ ub4 private_key_len = 2048; ub1 private_key[] = "45687942323587........"; ub4 private_keyl = strlen((const char *)private_key); /* Usage mask */ ub4 private_key_mask = CRYPTO_MASK_DECRYPT; oratext uid[OKV_UNIQUE_ID_MAXLEN + 1]; ub4 uidl = sizeof(uid); OKVTTLV *template = (OKVTTLV *)NULL; OKVTTLV *attr_in = (OKVTTLV *)NULL; /* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections */ memset(uid, 0, uidl); template = okvEnvGetOpRequestObj(env); /* Add name attribute object to request handle */ attr_in = okvAddAttributeObject(env, template, OKVAttrName, (ub4) 0); /* Add name attribute value to name attribute object */ okvAttrAddName(env, attr_in, (oratext *)"My Private Key for Register operation", strlen("My Private Key for Register operation"), 1); okvRegPrivateKey(env, private_key_algo, private_key_len, private_key, private_keyl, private_key_mask, template, OKV_NO_WALLET, OKV_NO_WALLET_LEN, uid, &uidl); uid[*uidl] = '\0'; if (okvErrGetNum(env)) { printf("Error while registering the private key\n"); }
Related Topics
- okvActivate
- okvAddAttribute
- okvCreateKey
- okvDeleteAttribute
- okvDestroy
- okvGetAttributeList
- okvGetAttributes
- okvGetCertificate
- okvGetCertificateRequest
- okvGetKey
- okvGetOpaqueData
- okvGetPrivateKey
- okvGetPublicKey
- okvGetSecretData
- okvGetTemplate
- okvLocate
- okvModifyAttribute
- okvQueryCapability
- okvRegCertificate
- okvRegCertificateRequest
- okvRegKey
- okvRegOpaqueData
- okvRegPublicKey
- okvRegSecretData
- okvRegTemplate
- okvRevoke
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.25 okvRegPublicKey
okvRegPublicKey
implements the KMIP Register operation for
the KMIP public key object.
Catetory
KMIP API
Purpose
okvRegPublicKey
implements the KMIP Register operation for the KMIP
public key object.
The unique identifier of the public key object registered by the Oracle
Key Vault server is returned as ouid
.
The maximum length of the unique ID for Oracle Key Vault SDK is defined by
OKV_UNIQUE_ID_MAXLEN
.
The new public key being registered can take in additional attributes specified with the help of attributes or also with the template names. The attributes, and also the template names if specified, will be the template attribute added to KMIP register operation.
Syntax
OKVErrNo okvRegPublicKey(OKVEnv *env, OKVType public_key_alg, ub4 public_key_len, ub1 *public_key, ub4 public_keyl, ub4 mask, OKVTTLV *template_names_attrs, oratext *private_key_uid, ub4 private_key_uidl, oratext *wallet_name, ub4 wallet_namel, oratext *ouid, ub4 *ouidl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
public_key_alg |
IN |
Public key algorithm. |
public_key_len |
IN |
Key length of the public key. |
public_key |
IN |
Public key. |
public_keyl |
IN |
Public key length. |
mask |
IN |
Cryptographic usage mask of the public key. |
template_names_attrs |
IN |
Template names or attributes that will form the template-attribute. |
private_key_uid |
IN |
Unique identifier of the private key associated with the public key (optional). |
private_key_uidl |
IN |
Unique identifier length of the private key associated with the public key (optional). |
wallet_name |
IN |
Wallet name value. |
wallet_namel |
IN |
Length of the wallet name value. |
ouid |
OUT |
Unique identifier of the registered public key. |
ouidl |
OUT |
Unique identifier length of the registered public key. |
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. |
Supported Versions
Oracle Key Vault C SDK version 21.2.0.0.0 and later.
Comments
It is recommended to add a KMIP name attribute to public key object to help identify it in future.
The caller has to allocate the memory for the unique identifier returned by this
function. The length of allocated memory is passed in via the length of the unique
identifier argument ouidl
. Sufficient memory to store the returned
unique identifier should be allocated.
A public key of the specified length for a specified algorithm and use (cryptographic
usage mask) is registered with Oracle Key Vault server in wallet
wallet_name
if specified else it is registered in the default
wallet if present with the endpoint.
The public key being registered can be optionally associated with a private key by
providing the UID of the private key (private_key_uid
). Validate
the existence of private_key_uid
by performing a locate operation
(using okvLocate
API) before passing it as an argument to this
API.
Example
/* Key Algorithm */ OKVType public_key_algo = CRYPTO_ALG_RSA; /* Key Size */ ub4 public_key_len = 2048; ub1 public_key[] = "7698767245345566789823428..........."; ub4 public_keyl = strlen((const char *)public_key); /* Usage mask */ ub4 public_key_mask = CRYPTO_MASK_ENCRYPT; oratext uid[OKV_UNIQUE_ID_MAXLEN + 1]; ub4 uidl = sizeof(uid); OKVTTLV *template = (OKVTTLV *)NULL; OKVTTLV *attr_in = (OKVTTLV *)NULL; /* Set up the environment handle ‘env’ and also the memory and connection management as shown in previous sections */ memset(uid, 0, uidl); template = okvEnvGetOpRequestObj(env); /* Add name attribute object to request handle */ attr_in = okvAddAttributeObject(env, template, OKVAttrName, (ub4) 0); /* Add name attribute value to name attribute object */ okvAttrAddName(env, attr_in, (oratext *)"My Public Key for Register operation", strlen("My Public Key for Register operation"), 1); okvRegPublicKey(env, public_key_algo, public_key_len, public_key, public_keyl, public_key_mask, template, (oratext *)NULL, (ub4)0, OKV_NO_WALLET, OKV_NO_WALLET_LEN, uid, &uidl); uid[*uidl] = '\0'; if (okvErrGetNum(env)) { printf("Error while registering the public key\n"); }
Related Topics
- okvActivate
- okvAddAttribute
- okvCreateKey
- okvDeleteAttribute
- okvDestroy
- okvGetAttributeList
- okvGetAttributes
- okvGetCertificate
- okvGetCertificateRequest
- okvGetKey
- okvGetOpaqueData
- okvGetPrivateKey
- okvGetPublicKey
- okvGetSecretData
- okvGetTemplate
- okvLocate
- okvModifyAttribute
- okvQueryCapability
- okvRegCertificate
- okvRegCertificateRequest
- okvRegKey
- okvRegOpaqueData
- okvRegPrivateKey
- okvRegSecretData
- okvRegTemplate
- okvRevoke
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.26 okvRegSecretData
okvRegSecretData
implements the KMIP Register operation for the KMIP secret data object.
Catetory
KMIP API
Purpose
okvRegSecretData
implements the KMIP Register operation for the KMIP secret data object.
Secret data is usually a password or a string.
The unique identifier of the secret data object created in the Oracle Key Vault server for the registered secret data is returned as ouid
.
The maximum length of the unique ID for Oracle Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN
.
The new secret data created can take in additional attributes specified with the help of attributes or also with the template names. The attributes, and also the template names if specified, will be the template attribute added to KMIP register operation.
Syntax
OKVErrNo okvRegSecretData(OKVEnv *env, ub4 secret_data_type, ub1 *secret_data, ub4 secret_datal, ub4 mask, OKVTTLV *template_names_attrs, oratext *wallet_name, ub4 wallet_namel, oratext *ouid, ub4 *ouidl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
secret_data_type |
|
Type of secret data being registered. |
secret_data |
|
Secret data being registered. |
secret_datal |
|
Length of secret data being registered. |
mask |
IN |
Cryptographic usage mask of the secret. |
template_names_attrs |
|
Template names or attributes that will form the template-attribute. |
|
IN |
Wallet name value. |
|
IN |
Length of the wallet name value. |
ouid |
|
Unique identifier of the registered secret data. |
ouidl |
|
Unique identifier length of the registered secret data. |
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
It is recommended to add a KMIP name attribute to secret data object to help identify it in future.
The caller has to allocate the memory for the unique identifier returned by this function. The length of allocated memory is passed in via the length of the unique identifier (ouidl
) argument. Sufficient memory to store the returned unique identifier should be allocated.
A secret data of a specific type is registered with Oracle Key Vault server in wallet (wallet_name
) if specified else it is registered in the default wallet if present with the endpoint.
The size of the secret data is limited by the maximum size of the object handled by the Oracle Key Vault server.
Example
/* Parameters for registering secret data */ /* Tag for secret data type */ OKVType type = OKVDEF_SECRET_DATA_TYPE_PASSWORD; ub4 usage_mask = CRYPTO_MASK_ENCRYPT | CRYPTO_MASK_DECRYPT; oratext *secret = (oratext *)"MyNewSecret"; ub4 secretl = strlen("MyNewSecret"); oratext uid[OKV_UNIQUE_ID_MAXLEN + 1]; ub4 uidl = sizeof(uid); /* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections */ memset(uid, 0, uidl); /* Register Secret data */ printf("\tRegistering the secret data\n"); okvRegSecretData(env, type, secret, secretl, usage_mask, (OKVTTLV *)NULL, (oratext *)NULL, (ub4)0, &uid[0], uidl); if (okvErrGetNum(env)) { printf("Error while registering the secret data\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.27 okvRegTemplate
okvRegTemplate
implements the KMIP Register operation for
the KMIP template object.
Catetory
KMIP API
Purpose
okvRegTemplate
implements the KMIP Register operation for the KMIP template object (not to be confused with KMIP template-attribute object).
A template object is a collection of attributes.
The unique identifier of the template object created with the specified attributes in Oracle Key Vault for the registered template is returned as ouid
.
The maximum length of the unique identifier for Oracle Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN
.
Syntax
OKVErrNo okvRegTemplate(OKVEnv *env, OKVTTLV *attrs_template, oratext *wallet_name, ub4 wallet_namel, oratext *ouid, ub4 *ouidl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
attrs_template |
IN |
Attributes of the template. |
|
IN |
Wallet name value. |
|
IN |
Length of the wallet name value. |
ouid |
OUT |
Unique identifier of the registered template. |
ouid1 |
OUT |
Unique identifier length of the registered template. |
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 caller has to allocate the memory for the unique identifier returned by this function. The length of allocated memory is passed in via the length of the unique identifier (ouidl
) argument. Sufficient memory to store the returned unique identifier should be allocated.
The template will be registered with the wallet specified in wallet_name
argument else it will be registered with the default wallet associated with the endpoint in case the default wallet exists.
Example
oratext uid[OKV_UNIQUE_ID_MAXLEN + 1]; ub4 uidl = sizeof(uid); /* Set up the environment handle 'env' also the memory and connection management as shown in previous sections */ memset(uid, 0, uidl); okvRegTemplate(env, (OKVTTLV *)NULL, (oratext *)NULL, (ub4)0, &uid[0], &uidl); if (okvErrGetNum(env)) { printf("Error while registering the Template\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.28 okvRekey
okvRekey
implements the KMIP Rekey operation.
Catetory
KMIP API
Purpose
okvRekey
implements the KMIP Rekey operation.
The rekey operation requires the unique identifier of the symmetric key that needs to be re-keyed. Most of the attributes are carried over from the old key. Some attributes are modified per KMIP defined rules.
The unique identifier of the new symmetric key object generated by the Oracle Key Vault server is returned as ouid
.
The maximum length of the unique ID for Oracle Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN
.
Syntax
OKVErrNo okvRekey(OKVEnv *env, oratext *uid, ub4 offset, OKVTTLV *template_names_attrs, oratext *ouid, ub4 *ouidl);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
|
|
Oracle Key Vault environment handle. |
|
|
Unique identifier of the key being rekeyed (can be NULL for Batching). |
|
|
Time interval between initialization (creation) date and activation date. |
|
|
Template names or attributes that will form the template-attribute for rekey. |
|
|
Unique identifier of the newly generated symmetric key. |
|
|
Unique identifier length of the newly generated symmetric key. |
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 caller has to allocate the memory for the unique identifier of the new symmetric key returned by this function. The length of allocated memory is passed in via the length of the unique identifier (ouidl
) argument.
- The server doesn’t impose any restrictions on the number of times a key can be rekeyed. For example, if a key K1 is rekeyed and a new key K2 is created, the server allows the key K1 to be rekeyed again and key K3 would be created.
- If a template is passed for rekey, the template attributes are not added for the new key. As a workaround, this can be added post rekey using
okvAddAttribute
.
Example
/* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections. Create a key for example and get its unique identifier as part of its creation in 'uid'. Rekey can done as shown below */ … oratext rekey_uid[OKV_UNIQUE_ID_MAXLEN + 1]; ub4 rekey_uidl = sizeof(rekey_uid); memset(rekey_uid, 0, rekey_uidl); okvRekey(env, uid, (ub4)0, (OKVTTLV *)NULL, &rekey_uid[0], &rekey_uidl); if (okvErrGetNum(env)) { printf("Error while Re-Keying the Key\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.29 okvRevoke
okvRevoke
implements the KMIP Revoke operation.
Catetory
KMIP API
Purpose
okvRevoke
implements the KMIP Revoke operation. It revokes the KMIP
object specified by the unique identifier with a revocation reason and the date when the
object was compromised.
Syntax
OKVErrNo okvRevoke(OKVEnv *env, oratext *uid, ub4 revocation_reason, oratext *revocation_msg, ub8 comp_occurrence_date);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
uid |
IN |
Unique identifier (can be NULL for batching). |
revocation_reason |
IN |
Revocation reason for revoking the KMIP object. |
revocation_msg |
IN |
Revocation message for revoking the KMIP object. |
comp_occurrence_date |
IN |
Date when the KMIP object compromise occurred. |
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
/* Create the KMIP object, say Key for example and get its unique identifier as part of its creation in 'uid', activate it and then revoke it as below */ okvRevoke(env, &uid[0], (ub4)1, (oratext *)"Retiring the key", (ub8)time((time_t *)NULL)); if (okvErrGetNum(env)) { printf("Error while revoking the object\n"); }
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.2 Oracle Key Vault Client SDK Batch APIs
This section describes the interfaces for the Oracle Key Vault KMIP batch functions.
- okvBatchCreate
okvBatchCreate
will mark the start of Oracle Key Vault batching. - okvBatchExecute
okvBatchExecute
will execute the batched Oracle Key Vault functions. - okvBatchFree
okvBatchFree
will mark the end of Oracle Key Vault batching. - okvGetBatchOperationCount
okvGetBatchOperationCount
gets the count of batched Oracle Key Vault operations. - okvGetBatchOperationName
okvGetBatchOperationName
returns the KMIP operation name of the respective batch job number that is passed with this function.
Parent topic: Oracle Key Vault Client SDK KMIP and Batch APIs
11.2.1 okvBatchCreate
okvBatchCreate
will mark the start of Oracle Key Vault batching.
Catetory
KMIP Batch API
Purpose
okvBatchCreate
will mark the start of Oracle Key Vault batching. All Oracle Key Vault functions after this command will be batched.
Syntax
OKVErrNo okvBatchCreate(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
/* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections. */ printf("Start preparing batch operations\n"); okvBatchCreate(env); if (okvErrGetNum(env)) { printf("Error while initiating the Batch"); } ... /* All Oracle Key Vault APIs from this point will be batched */
Parent topic: Oracle Key Vault Client SDK Batch APIs
11.2.2 okvBatchExecute
okvBatchExecute
will execute the batched Oracle Key Vault
functions.
Catetory
KMIP Batch API
Purpose
okvBatchExecute
will execute the batched Oracle Key Vault
functions. The batched Oracle Key Vault functions are functions between
okvBatchCreate
and okvBatchExecute
. If there are
errors, then the errors for all the batched Oracle Key Vault functions should be checked
to verify which operations failed and which were successful.
Syntax
OKVErrNo okvBatchExecute(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
To check for individual operations in the batch after its execution, these APIs can
be made use of: okvErrGetNumForBatch
,
okvErrGetDepthForBatch
, and
okvErrGetNumAtDepthForBatch
. The errors for individual batch
operations can be checked only before freeing the batch context, that is, before calling
okvBatchFree
.
Example
/* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections. */ printf("Start preparing batch operations\n"); okvBatchCreate(env); ... /* All Oracle Key Vault KMIP APIs from this point will be batched */ ... printf("Executing batch operation\n"); okvBatchExecute(env); if (okvErrGetNum(env)) { printf("Error while executing the batch"); }
11.2.3 okvBatchFree
okvBatchFree
will mark the end of Oracle Key Vault batching.
Catetory
KMIP Batch API
Purpose
okvBatchFree
will mark the end of Oracle Key Vault batching. Essentially the memory allocated for complex arguments will be released. Subsequent Oracle Key Vault functions will not be batched unless okvBatchCreate
is called again.
Syntax
OKVErrNo okvBatchFree(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
The errors for individual batch operations can be checked only before freeing the
batch context, that is, before calling okvBatchFree
.
Example
/* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections. */ printf("Start preparing batch operations\n"); okvBatchCreate(env); ... /* All Oracle Key Vault KMIP APIs from this point will be batched */ ... printf("Executing batch operation\n"); okvBatchExecute(env); ... /* Check for Individual Batch Operation errors */ ... printf("Ending batch operations\n\n"); okvBatchFree(env); if (okvErrGetNum(env)) { printf("Error while ending the batch"); }
Parent topic: Oracle Key Vault Client SDK Batch APIs
11.2.4 okvGetBatchOperationCount
okvGetBatchOperationCount
gets the count of batched Oracle
Key Vault operations.
Catetory
KMIP Batch API
Purpose
okvGetBatchOperationCount
gets the count of batched Oracle Key
Vault operations.
Syntax
ub4 okvGetBatchOperationCount(OKVEnv *env);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
Return Values
Return Value | Description |
---|---|
ub4 |
Count of the batched operations. Success: A valid positive non-zero number is returned. Failure: Zero. |
Comments
This function should be called before calling okvBatchFree
else it will return zero.
Example
ub4 batch_cnt = 0; /* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections. */ printf("\t\tStart preparing batch operations\n"); okvBatchCreate(env); ... * All Oracle Key Vault KMIP APIs from this point will be batched */ ... printf("\t\tExecuting batch operation\n"); okvBatchExecute(env); ... /* Check for Individual Batch Operation errors */ ... batch_cnt = okvGetBatchOperationCount(env); printf("Count of the KMIP operations that are batched: %d", batch_cnt);
Related Topics
Parent topic: Oracle Key Vault Client SDK Batch APIs
11.2.5 okvGetBatchOperationName
okvGetBatchOperationName
returns the KMIP operation name of
the respective batch job number that is passed with this function.
Catetory
KMIP Batch API
Purpose
okvGetBatchOperationName
returns the KMIP operation name of the
respective batch job number that is passed with this function.
Syntax
oratext *okvGetBatchOperationName(OKVEnv *env, ub1 batchjobnum);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
batchjobnum |
IN |
Batch job number. |
Return Values
Return Value | Description |
---|---|
oratext * |
KMIP operation name that was batched. Success: A pointer to batch job operation name is returned. Failure: |
Comments
This function should be called before calling okvBatchFree
else it
will return a pointer to NULL
.
batchjobnum
is the number in which the operations are batched. For
example, if the user wants to create a key, activate a key, revoke it, and then destroy
it, all of these operations are batched in the same order, that is,
batchjobnum
for create a key is 1, batchjobnum
for
activate a key is 2, batchjobnum
for revoke is 3, and
batchjobnum
for destroy is 4.
Example
ub4 batch_cnt = 0; ub4 batch_job_num = 0; /* Set up the environment handle 'env' also the memory and connection management as shown in previous sections. */ printf("\t\tStart preparing batch operations\n"); okvBatchCreate(env); ... /* All Oracle Key Vault KMIP APIs from this point will be batched */ ... printf("\t\tExecuting batch operation\n"); okvBatchExecute(env); ... /* Check for Individual Batch Operation errors */ ... batch_cnt = okvGetBatchOperationCount(env); printf("Batch Operations count is: %d\n", batch_cnt); if (batch_cnt) { for(batch_job_num=1; batch_job_num<=batch_cnt; batch_job_num++) { printf("\t\t\t%d: %s\n", batch_job_num, okvGetBatchOperationName(env, batch_job_num)); } }
Related Topics
Parent topic: Oracle Key Vault Client SDK Batch APIs