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. - okvDecrypt
okvDecrypt
performs the decryption operation on the provided data using KMIP object. - okvDeleteAttribute
okvDeleteAttribute
implements the KMIP Delete attribute operation. - okvDestroy
okvDestroy
implements the KMIP Destroy operation. - okvEncrypt
okvEncrypt
performs the encryption operation on the provided data using KMIP object. - 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. - okvSign
okvSign
implements the KMIP Sign operation. - okvSignVerify
okvSignVerify
implements the KMIP Signature Verify operation. - okvCreateKeyPair
okvCreateKeyPair
implements the KMIP Create Key Pair 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.
Category
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 okvDecrypt
okvDecrypt
performs the decryption operation on the
provided data using KMIP object.
Category
KMIP API
Purpose
okvDecrypt
performs the decryption operation on the
provided data using KMIP object.
Syntax
OKVErrNo okvDecrypt(OKVEnv *env, oratext *uid, ub1 *data, ub4 datal, OKVCryptoContext *crypto_context, OKVDecryptResponse *decrypt_response);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
uid |
|
Unique identifier (can be NULL for batching). |
data |
|
Data to be decrypted. |
datal |
|
Length of the data to be decrypted. |
crypto_context |
|
Cryptographic context contains required parameters for decryption like cryptographic parameters and IV. |
decrypt_response |
|
Contains the decrypt operation response details. |
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. |
Supported Versions
Oracle Key Vault C SDK release 21.4.0.0.0 and later.
Comments
crypto_context
can be created and freed using
okvCryptoContextCreate
and
okvCryptoContextFree
helper APIs. It contains the required
parameters for decryption and the user will need to set it explicitly by making use
of helper APIs like okvCryptoContextSetBlockCipherMode
,
okvCryptoContextSetPadding
,
okvCryptoContextSetRandomIV
,
okvCryptoContextSetIV
,
okvCryptoContextSetAuthEncryptionAdditionalData
, and
okvCryptoContextSetAuthEncryptionTag
. The user can also get the
respective parameter values that were set in crypto_context
using
helper APIs okvCryptoContextGetBlockCipherMode
,
okvCryptoContextGetPadding
,
okvCryptoContextGetRandomIV
,
okvCryptoContextGetIV
,
okvCryptoContextGetAuthEncryptionAdditionalData
, and
okvCryptoContextGetAuthEncryptionTag
.
decrypt_response
will need to explicitly be allocated using helper
API okvDecryptResponseCreate
before passing it as an OUT parameter
to okvDecrypt
API. Once the decrypt operation is completed, we can
get the decrypted data details from decrypt_response
using helper
API okvCryptoResponseGetDecryptedData
.
decrypt_response
needs to be freed using
okvDecryptResponseFree
helper API.
Example
/* Create a Symmetric Key for example and get its unique identifier as part of its creation in uid, we can use the 'uid' for decrypting the encrypted data as shown below */ OKVCryptoContext *crypto_context = (OKVCryptoContext *)NULL; OKVEncryptResponse *encrypt_response = (OKVEncryptResponse *)NULL; OKVDecryptResponse *decrypt_response = (OKVDecryptResponse *)NULL; ub1 data[] = "OKV crypto operations demo."; ub4 datal = strlen((const char *) data); ub1 iv[] = "5432109876543210"; ub4 ivl = strlen((const char *) iv); ub1 encrypted_data[100]; ub4 encrypted_datal = sizeof(encrypted_data); ub1 decrypted_data[100]; ub4 decrypted_datal = sizeof(decrypted_data); /* Encrypt */ crypto_context = okvCryptoContextCreate(env, OKVOpEncrypt); okvCryptoContextSetBlockCipherMode(env, crypto_context, BLK_CIPHER_CBC); okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS5); okvCryptoContextSetIV(env, crypto_context, iv, ivl); encrypt_response = okvEncryptResponseCreate(env); okvEncrypt(env, uid, data, datal, crypto_context, encrypt_response); if (okvErrGetNum(env)) { printf("Error while performing the encryption operation.\n"); } memset(encrypted_data, 0, encrypted_datal); okvCryptoResponseGetEncryptedData(env, encrypt_response, encrypted_data, &encrypted_datal); printf("Successfully encrypted the data\n"); printf("\tEncrypted Data Length: %d\n", encrypted_datal); printf("\tEncrypted Data: %s\n", encrypted_data); okvCryptoContextFree(env, &crypto_context); okvEncryptResponseFree(env, &encrypt_response); /*Decrypt */ crypto_context = okvCryptoContextCreate(env, OKVOpEncrypt); okvCryptoContextSetBlockCipherMode(env, crypto_context, BLK_CIPHER_CBC); okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS5); okvCryptoContextSetIV(env, crypto_context, iv, ivl); decrypt_response = okvDecryptResponseCreate(env); okvDecrypt(env, uid, encrypted_data, encrypted_datal, crypto_context, decrypt_response); if (okvErrGetNum(env)) { printf("Error while performing the decryption operation.\n"); } memset(decrypted_data, 0, decrypted_datal); okvCryptoResponseGetDecryptedData(env, decrypt_response, decrypted_data, &decrypted_datal); printf("Successfully decrypted the data\n"); printf("\tDecrypted Data Length: %d\n", decrypted_datal); printf("\tDecrypted Data: %s\n", decrypted_data); okvCryptoContextFree(env, &crypto_context); okvDecryptResponseFree(env, &decrypt_response);
Related Topics
- okvCryptoContextCreate
- okvCryptoContextFree
- okvCryptoContextGetAuthEncryptionAdditionalData
- okvCryptoContextGetAuthEncryptionTag
- okvCryptoContextGetBlockCipherMode
- okvCryptoContextGetIV
- okvCryptoContextGetPadding
- okvCryptoContextGetRandomIV
- okvCryptoContextSetAuthEncryptionAdditionalData
- okvCryptoContextSetAuthEncryptionTag
- okvCryptoContextSetBlockCipherMode
- okvCryptoContextSetIV
- okvCryptoContextSetPadding
- okvCryptoContextSetRandomIV
- okvCryptoResponseGetDecryptedData
- okvDecryptResponseCreate
- okvDecryptResponseFree
- okvEncrypt
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.6 okvDeleteAttribute
okvDeleteAttribute
implements the KMIP Delete attribute
operation.
Category
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.7 okvDestroy
okvDestroy
implements the KMIP Destroy
operation.
Category
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.8 okvEncrypt
okvEncrypt
performs the encryption operation on the
provided data using KMIP object.
Category
KMIP API
Purpose
okvEncrypt
performs the encryption operation on the
provided data using KMIP object.
Syntax
OKVErrNo okvEncrypt(OKVEnv *env, oratext *uid, ub1 *data, ub4 datal, OKVCryptoContext *crypto_context, OKVEncryptResponse *encrypt_response);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
uid |
|
Unique identifier (can be NULL for batching). |
data |
|
Data to be encrypted. |
datal |
|
Length of the data to be encrypted. |
crypto_context |
|
Cryptographic context contains required parameters for encryption like cryptographic parameters and IV. |
encrypt_response |
|
Contains the encrypt operation response details. |
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. |
Supported Versions
Oracle Key Vault C SDK release 21.4.0.0.0 and later.
Comments
crypto_context
can be created and freed using
okvCryptoContextCreate
and
okvCryptoContextFree
helper APIs. It contains the required parameters
for encryption and the user will need to set it explicitly by making use of helper
APIs like okvCryptoContextSetBlockCipherMode
,
okvCryptoContextSetPadding
,
okvCryptoContextSetRandomIV
,
okvCryptoContextSetIV
,
okvCryptoContextSetAuthEncryptionAdditionalData
, and
okvCryptoContextSetAuthEncryptionTag
. The user can also get the
respective parameter values that was set in crypto_context
using
helper APIs okvCryptoContextGetBlockCipherMode
,
okvCryptoContextGetPadding
,
okvCryptoContextGetRandomIV
,
okvCryptoContextGetIV
,
okvCryptoContextGetAuthEncryptionAdditionalData
, and
okvCryptoContextGetAuthEncryptionTag
.
encrypt_response
will need to explicitly be allocated using helper
API okvEncryptResponseCreate
before passing it as an OUT parameter
to okvEncrypt API
. Once the encrypt operation is completed, we can
get the encrypted data details from encrypt_response
using helper
APIs okvCryptoResponseGetEncryptedData
,
okvCryptoResponseGetIV
, and
okvCryptoResponseGetAuthEncryptionTag
.
encrypt_response
needs to be freed using
okvEncryptResponseFree
helper API.
Example
/* Create a Symmetric Key for example and get its unique identifier as part of its creation in ‘uid’, we can use the 'uid' for encryption as shown below */ OKVCryptoContext *crypto_context = (OKVCryptoContext *)NULL; OKVEncryptResponse *encrypt_response = (OKVEncryptResponse *)NULL; ub1 data[] = "OKV crypto operations demo."; ub4 datal = strlen((const char *) data); ub1 iv[] = "5432109876543210"; ub4 ivl = strlen((const char *) iv); ub1 encrypted_data[100]; ub4 encrypted_datal = sizeof(encrypted_data); /* Encrypt */ crypto_context = okvCryptoContextCreate(env, OKVOpEncrypt); okvCryptoContextSetBlockCipherMode(env, crypto_context, BLK_CIPHER_CBC); okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS5); okvCryptoContextSetIV(env, crypto_context, iv, ivl); encrypt_response = okvEncryptResponseCreate(env); okvEncrypt(env, uid, data, datal, crypto_context, encrypt_response); if (okvErrGetNum(env)) { printf("Error while performing the encryption operation.\n"); } memset(encrypted_data, 0, encrypted_datal); okvCryptoResponseGetEncryptedData(env, encrypt_response, encrypted_data, &encrypted_datal); printf("Successfully encrypted the data\n"); printf("\tEncrypted Data Length: %d\n", encrypted_datal); printf("\tEncrypted Data: %s\n", encrypted_data); okvCryptoContextFree(env, &crypto_context); okvEncryptResponseFree(env, &encrypt_response);
Related Topics
- okvCryptoContextCreate
- okvCryptoContextFree
- okvCryptoContextGetAuthEncryptionAdditionalData
- okvCryptoContextGetAuthEncryptionTag
- okvCryptoContextGetBlockCipherMode
- okvCryptoContextGetIV
- okvCryptoContextGetPadding
- okvCryptoContextGetRandomIV
- okvCryptoContextSetAuthEncryptionAdditionalData
- okvCryptoContextSetAuthEncryptionTag
- okvCryptoContextSetBlockCipherMode
- okvCryptoContextSetIV
- okvCryptoContextSetPadding
- okvCryptoContextSetRandomIV
- okvCryptoResponseGetAuthEncryptionTag
- okvCryptoResponseGetEncryptedData
- okvCryptoResponseGetIV
- okvDecrypt
- okvEncryptResponseCreate
- okvEncryptResponseFree
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.9 okvGetAttributeList
okvGetAttributeList
implements KMIP Get attribute list
operation.
Category
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.10 okvGetAttributes
okvGetAttributes
implements KMIP Get attribute operation.
Category
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.11 okvGetCertificate
okvGetCertificate
implements the KMIP Get operation for the
Certificate object.
Category
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.12 okvGetCertificateRequest
okvGetCertificateRequest
implements the KMIP Get operation
for the Certificate request object.
Category
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.13 okvGetKey
okvGetKey
implements the KMIP Get operation for the KMIP
symmetric key object.
Category
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.14 okvGetOpaqueData
okvGetOpaqueData
implements the KMIP Get operation for the
KMIP opaque data object.
Category
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.15 okvGetPrivateKey
okvGetPrivateKey
implements the KMIP Get operation for the
KMIP private key object.
Category
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.16 okvGetPublicKey
okvGetPublicKey
implements the KMIP Get operation for the
KMIP public key object.
Category
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.17 okvGetSecretData
okvGetSecretData
implements the KMIP Get operation for the
KMIP secret data object.
Category
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.18 okvGetTemplate
okvGetTemplate
implements the KMIP Get operation for the KMIP template object.
Category
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.19 okvLocate
okvLocate
implements the KMIP Locate operation.
Category
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
.
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.
Prior to Oracle Key Vault 21.7 release, Oracle Key Vault server returned
all the object unique identifiers that matched the conditions in the
Locate
operation request irrespective of whether the maximum number
of requested items field (uid_max
) are present or not in the request.
Starting with Oracle Key Vault 21.7 release, the Oracle Key Vault server now supports
the maximum Items field (uid_max
) for Locate
operation, that is only requested number (or up to maximum of
'uid_max
') of object Unique ID's is returned by the server. If you want
to skip this field in the locate operation, then please use constant
'OKV_NO_MAX_ITEMS
' in place of 'uid_max
' parameter.
As of today, Storage Status Mask (storage_status
) field is not
supported by the Oracle Key Vault server and hence any values passed into this field is
not taken into account by the server during locate operation.
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.20 okvModifyAttribute
okvModifyAttribute
implements the KMIP Modify attribute
operation.
Category
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.21 okvQueryCapability
okvQueryCapability
implements the KMIP Query
operation.
Category
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.22 okvRegCertificate
okvRegCertificate
implements the KMIP Register operation for
the KMIP certificate object.
Category
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.23 okvRegCertificateRequest
okvRegCertificateRequest
implements the KMIP Register
operation for the certificate request object.
Category
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.24 okvRegKey
okvRegKey
implements the KMIP Register operation for the
KMIP symmetric key object.
Category
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.25 okvRegOpaqueData
okvRegOpaqueData
implements the KMIP Register operation for
the KMIP opaque data object.
Category
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.26 okvRegPrivateKey
okvRegPrivateKey
implements the KMIP Register operation for
the KMIP private key object.
Category
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.27 okvRegPublicKey
okvRegPublicKey
implements the KMIP Register operation for
the KMIP public key object.
Category
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.28 okvRegSecretData
okvRegSecretData
implements the KMIP Register operation for the KMIP secret data object.
Category
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.29 okvRegTemplate
okvRegTemplate
implements the KMIP Register operation for
the KMIP template object.
Category
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.30 okvRekey
okvRekey
implements the KMIP Rekey operation.
Category
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.
Prior to Oracle Key Vault release 21.7, rekey operation was allowed more than once on the same key. Starting with Oracle Key Vault release 21.7, rekey operation is allowed only once on a given key.
- 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.31 okvRevoke
okvRevoke
implements the KMIP Revoke operation.
Category
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.1.32 okvSign
okvSign
implements the KMIP Sign operation.
Category
KMIP API
Purpose
okvSign
performs the sign operation on the provided
data using a KMIP object.
Syntax
OKVErrNo okvSign(OKVEnv *env, oratext *uid,
ub1 *data, ub4 datal, ub4 data_type,
OKVCryptoContext *crypto_context,
OKVSignResponse *sign_response);
Parameters
Table 11-1 Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
uid |
IN |
Unique identifier (can be NULL for batching). |
data |
IN |
Data to be signed. |
datal |
IN |
Length of the data to be signed. |
data_type |
IN |
Type of the data to be signed, either
OKV_DATA_TYPE_RAW or
OKV_DATA_TYPE_DIGEST .
|
crypto_context |
IN |
Cryptographic context contains required parameters for signing like the cryptographic algorithm and hashing algorithm. |
sign_response |
OUT |
Contains the sign operation response details. |
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. |
Supported Versions
Oracle Key Vault C SDK release 21.6.0.0.0 and later.
Comments
crypto_context
can be created and freed using
okvCryptoContextCreate
and
okvCryptoContextFree
helper APIs. It contains the required
parameters for signing and the user will need to set it explicitly by making use of
helper APIs like okvCryptoContextSetCryptoAlgo
,
okvCryptoContextSetHashingAlgo
,
okvCryptoContextSetPadding
, and
okvCryptoContextSetDigitalSignAlgo
. The user can also get the
respective parameter values that was set in crypto_context
using
helper APIs okvCryptoContextGetCryptoAlgo
,
okvCryptoContextGetHashingAlgo
,
okvCryptoContextGetPadding
, and
okvCryptoContextGetDigitalSignAlgo
.
sign_response
will need to explicitly be allocated using helper API
okvSignResponseCreate
before passing it as an OUT parameter to
okvSign
API. Once the sign operation is completed, we can get
the signature data details from sign_response
using helper API
okvCryptoResponseGetSignatureData
.
sign_response
needs to be freed using
okvSignResponseFree
helper API.
Example
OKVCryptoContext *crypto_context = (OKVCryptoContext *)NULL; OKVSignResponse *sign_response = (OKVSignResponse *)NULL; ub1 data[] = "OKV signature operations demo."; ub4 datal = strlen((const char *) data); ub1 signature_data[OKV_OBJECT_MAXLEN]; ub4 signature_datal = sizeof(signature_data); /* Sign */ crypto_context = okvCryptoContextCreate(env, OKVOpSign); okvCryptoContextSetCryptoAlgo(env, crypto_context, CRYPTO_ALG_RSA); okvCryptoContextSetHashingAlgo(env, crypto_context, HASH_ALG_SHA_256); okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS1_V1_5); sign_response = okvSignResponseCreate(env); okvSign(env, private_key_unique_id, data, datal, OKV_DATA_TYPE_RAW, crypto_context, sign_response); memset(signature_data, 0, signature_datal); okvCryptoResponseGetSignatureData(env, sign_response, signature_data, &signature_datal);
11.1.33 okvSignVerify
okvSignVerify
implements the KMIP Signature Verify
operation.
Category
KMIP API
Purpose
okvSignVerify
performs the signature verify operation on the
provided data and signature using a KMIP object.
Syntax
OKVErrNo okvSignVerify(OKVEnv *env, oratext *uid, ub1 *data, ub4 datal, ub4 data_type, ub1 *signature_data, ub4 signature_datal, OKVCryptoContext *crypto_context, OKVSignVerifyResponse *sign_verify_response);
Parameters
Table 11-2 Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
uid |
IN |
Unique identifier (can be NULL for batching). |
data |
IN |
The data that was signed. |
datal |
IN |
Length of the data that was signed. |
data_type |
IN |
Type of the data that was signed,
either OKV_DATA_TYPE_RAW or
OKV_DATA_TYPE_DIGEST. |
signature_data |
IN |
Signature to be verified. |
signature_datal |
IN |
Length of the signature. |
crypto_context |
IN |
Cryptographic context contains required parameters for signature verification like the cryptographic algorithm and hashing algorithm. |
sign_verify_response |
OUT |
Contains the sign operation response details. |
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. |
Supported Versions
Oracle Key Vault C SDK release 21.6.0.0.0 and later.
Comments
crypto_context
can be created and freed using
okvCryptoContextCreate
and
okvCryptoContextFree
helper APIs. It contains the
required parameters for verifying a signature and the user will need to set
it explicitly by making use of helper APIs like
okvCryptoContextSetCryptoAlgo
,
okvCryptoContextSetHashingAlgo
,
okvCryptoContextSetPadding
, and
okvCryptoContextSetDigitalSignAlgo
. The user can also
get the respective parameter values that was set in
crypto_context
using helper APIs
okvCryptoContextGetCryptoAlgo
,
okvCryptoContextGetHashingAlgo
,
okvCryptoContextGetPadding
, and
okvCryptoContextGetDigitalSignAlgo
.
sign_verify_response
will need to explicitly be allocated
using helper API okvSignVerifyResponseCreate
before passing
it as an OUT parameter to okvSignVerify
API. Once the
signature verify operation is completed, we can get the verification details
from sign_verify_response
using helper APIs
okvCryptoResponseGetValidity
and
okvCryptoResponseGetRecoveredData.
sign_verify_response
needs to be freed using
okvSignVerifyResponseFree
helper API.
Example
OKVCryptoContext *crypto_context = (OKVCryptoContext *)NULL; OKVSignResponse *sign_response = (OKVSignResponse *)NULL; OKVSignVerifyResponse *verify_response = (OKVSignVerifyResponse *)NULL; ub1 data[] = "OKV signature operations demo."; ub4 datal = strlen((const char *) data); ub4 iter = 0; ub1 signature_data[OKV_OBJECT_MAXLEN]; ub4 signature_datal = sizeof(signature_data); ub4 validity = 0; /* Sign */ crypto_context = okvCryptoContextCreate(env, OKVOpSign); okvCryptoContextSetCryptoAlgo(env, crypto_context, CRYPTO_ALG_RSA); okvCryptoContextSetHashingAlgo(env, crypto_context, HASH_ALG_SHA_256); okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS1_V1_5); sign_response = okvSignResponseCreate(env); okvSign(env, private_key_unique_id, data, datal, OKV_DATA_TYPE_RAW, crypto_context, sign_response); memset(signature_data, 0, signature_datal); okvCryptoResponseGetSignatureData(env, sign_response, signature_data, &signature_datal); printf("Successfully signed the data\n"); printf("\tSignature Data Length: %d\n", signature_datal); printf("\tSignature Data: "); for (iter = 0; iter < signature_datal; iter++) { printf("%02X", signature_data[iter]); } printf("\n"); okvCryptoContextFree(env, &crypto_context); okvSignResponseFree(env, &sign_response); /* Verify */ crypto_context = okvCryptoContextCreate(env, OKVOpSignVerify); okvCryptoContextSetCryptoAlgo(env, crypto_context, CRYPTO_ALG_RSA); okvCryptoContextSetHashingAlgo(env, crypto_context, HASH_ALG_SHA_256); okvCryptoContextSetPadding(env, crypto_context, PADDING_PKCS1_V1_5); verify_response = okvSignVerifyResponseCreate(env); okvSignVerify(env, public_key_unique_id, data, datal, OKV_DATA_TYPE_RAW, signature_data, signature_datal, crypto_context, verify_response); okvCryptoResponseGetValidity(env, verify_response, &validity); if (validity == OKVDEF_VALIDITY_VALID) { printf("Signature is valid\n\n"); } else if (validity == OKVDEF_VALIDITY_INVALID) { printf("Signature is invalid\n\n"); } else { printf("Signature validity is unknown\n\n"); } okvCryptoContextFree(env, &crypto_context); okvSignVerifyResponseFree(env, &verify_response);
Related Topics
Parent topic: Oracle Key Vault Client SDK KMIP APIs
11.1.34 okvCreateKeyPair
okvCreateKeyPair
implements the KMIP Create Key Pair
operation.
Category
KMIP API
Purpose
okvCreateKeyPair
implements the KMIP Create Pair
operation. The unique identifiers of the generated key pair by the Oracle Key Vault
server is returned as private_key_uid
and
public_key_uid
. The maximum length of the unique ID for Oracle
Key Vault SDK is defined by OKV_UNIQUE_ID_MAXLEN
.
Syntax
OKVErrNo okvCreateKeyPair(OKVEnv *env, OKVType alg, ub4 len, ub4 private_key_mask, ub4 public_key_mask, OKVTTLV *common_template_names_attrs, OKVTTLV *private_key_template_names_attrs, OKVTTLV *public_key_template_names_attrs, oratext *wallet_name, ub4 wallet_namel, oratext *private_key_uid, ub4 *private_key_uidl, oratext *public_key_uid, ub4 *public_key_uidl);
Parameters
Table 11-3 Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
alg |
IN |
Asymmetric key algorithm. |
len |
IN |
Key length of the asymmetric key algorithm. |
private_key_mask |
IN |
Cryptographic usage mask of the private key. |
public_key_mask |
IN |
Cryptographic usage mask of the public key. |
common_template_names_attrs |
IN |
Template names or attributes that are common to both public and private keys and will form the common template-attribute. |
private_key_template_names_attrs |
IN |
Template names or attributes of private key and will form the private key template-attribute. |
public_key_template_names_attrs |
IN |
Template names or attributes of public key that will form the public key template-attribute. |
wallet_name |
IN |
Wallet name value. |
wallet_namel |
IN |
Length of the wallet name value. |
private_key_uid |
OUT |
Unique identifier of the generated private key. |
private_key_uidl |
OUT |
Unique identifier length of the generated private key. |
public_key_uid |
OUT |
Unique identifier of the generated public key. |
public_key_uidl |
OUT |
Unique identifier length of the generated public key. |
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. |
Supported Versions
Oracle Key Vault C SDK release 21.6.0.0.0 and later.
Comments
It is recommended to add a KMIP custom or name attribute to both the private and
public key objects to help identify it in future. The caller has to allocate the
memory for the unique identifiers returned by this function. The length of allocated
memory is passed in via the length of the unique identifier arguments
private_key_uidl
and public_key_uidl
. A public
and private key pair 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 key pair */
OKVType algo = CRYPTO_ALG_RSA;
ub4 key_len = 2048;
ub4 pri_key_usage_mask = CRYPTO_MASK_SIGN;
ub4 pub_key_usage_mask = CRYPTO_MASK_VERIFY;
OKVTTLV *request = (OKVTTLV *)NULL;
OKVTTLV *pri_key_attr = (OKVTTLV *)NULL;
OKVTTLV *pub_key_attr = (OKVTTLV *)NULL;
OKVTTLV *pri_key_attr_name_template = (OKVTTLV *)NULL;
OKVTTLV *pub_key_attr_name_template = (OKVTTLV *)NULL;
oratext pri_key_unique_id[OKV_UNIQUE_ID_MAXLEN + 1];
ub4 pri_key_unique_id_len = sizeof(pri_key_unique_id);
oratext pub_key_unique_id[OKV_UNIQUE_ID_MAXLEN + 1];
ub4 pub_key_unique_id_len = sizeof(pub_key_unique_id);
/* Set up the environment handle 'env' and also the memory and connection management as shown in previous sections */
memset(pri_key_unique_id, 0, pri_key_unique_id_len);
memset(pub_key_unique_id, 0, pub_key_unique_id_len);
request = okvEnvGetOpRequestObj(env);
/* Add name attribute object to both private and public template attribute */
pri_key_attr_name_template = okvTTLVAddToObject(env, request, OKVDEF_TAG_PRIVATE_KEY_TEMPLATE_ATTR_ST, OKVDEF_ITEM_TYPE_STRUCT, (void *)NULL, (ub4)0);
pri_key_attr = okvAddAttributeObject(env, pri_key_attr_name_template, OKVAttrName, (ub4)0);
okvAttrAddName(env, pri_key_attr, (oratext *) "Private Key", strlen("Private Key"), 1);
pub_key_attr_name_template = okvTTLVAddToObject(env, request, OKVDEF_TAG_PUBLIC_KEY_TEMPLATE_ATTR_ST, OKVDEF_ITEM_TYPE_STRUCT, (void *)NULL, (ub4)0);
pub_key_attr = okvAddAttributeObject(env, pub_key_attr_name_template, OKVAttrName, (ub4)0);
okvAttrAddName(env, pub_key_attr, (oratext *) "Public Key", strlen("Public Key"), 1);
printf("\nCreating a Key Pair on Oracle Key Vault server\n");
okvCreateKeyPair(env, algo, key_len, pri_key_usage_mask, pub_key_usage_mask, (OKVTTLV *)NULL, pri_key_attr_name_template, pub_key_attr_name_template, OKV_NO_WALLET, OKV_NO_WALLET_LEN, pri_key_unique_id, &pri_key_unique_id_len, pub_key_unique_id, &pub_key_unique_id_len);
pri_key_unique_id[pri_key_unique_id_len] = '\0';
pub_key_unique_id[pub_key_unique_id_len] = '\0';
if (okvErrGetNum(env))
{
printf("Error while creating the key pair\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.
Category
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.
Category
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.
Category
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.
Category
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.
Category
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 batch_job_no);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
batch_job_no |
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
.
batch_job_no
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,
batch_job_no
for create a key is 1, batch_job_no
for activate a key is 2, batch_job_no
for revoke is 3, and
batch_job_no
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