6 Oracle Key Vault Datatypes and Structures
This section describes the Oracle Key Vault datatypes and structures.
- Oracle Key Vault Datatypes
This section describes the datatypes provided with the Oracle Key Vault SDK. - Oracle Key Vault Structures and Enumerations
This section describes the structures and enumerations provided with the Oracle Key Vault SDK.
Parent topic: Oracle Key Vault Client C SDK API Reference
6.1 Oracle Key Vault Datatypes
This section describes the datatypes provided with the Oracle Key Vault SDK.
Oracle Key Vault client SDK defines a set of C datatypes that are used throughout the Oracle Key Vault client SDK. These definitions are available to the endpoint program upon inclusion of okvcsdk.h. The following table lists the datatypes and their description.
Table 6-1 Oracle Key Vault Datatypes
Datatype | Description |
---|---|
ub1 |
Unsigned byte of at least 1 byte. |
sb1 |
Signed byte of at least 1 byte. |
ub2 |
Unsigned byte of at least 2 bytes. |
sb2 |
Signed byte of at least 2 bytes. |
ub4 |
Unsigned byte of at least 4 bytes. |
sb4 |
Signed byte of at least 4 bytes. |
ub8 |
Unsigned byte of at least 8 bytes. |
sb8 |
Signed byte of at least 8 bytes. |
OKVErrNo |
Same as ub4. |
OKVTag |
Same as ub4. |
OKVType |
Same as ub1. |
oratext |
Character byte of size 1 byte. |
Parent topic: Oracle Key Vault Datatypes and Structures
6.2 Oracle Key Vault Structures and Enumerations
This section describes the structures and enumerations provided with the Oracle Key Vault SDK.
- OKVAttr
OKVAttr
has a collection of all the KMIP attributes, single or multi-instance attributes, supported by the KMIP specification. - OKVAttrNo
OKVAttrNo
defines the KMIP attributes withOKVATTRMAX
as the count of the KMIP attributes. - OKVCryptoContext
OKVCryptoContext
holds the required parameters for cryptographic operations. - OKVDecryptResponse
OKVDecryptResponse
contains the decrypt operation response details. - OKVEncryptResponse
OKVEncryptResponse
contains the encrypt operation response details. - OKVEnv
OKVEnv
is the Oracle Key Vault environment handle that controls the endpoint SDK program behavior. - OKVErr
OKVErr
is the Oracle Key Vault error management handle that captures errors in an Oracle Key Vault operation. - OKVMemoryCtx
OKVMemoryCtx
is the Oracle Key Vault memory management context that holds the memory context and pointers to endpoint defined memory functions. - OKVObjNo
OKVObjNo
defines the KMIP managed object types withOKVOBJMAX
as the maximum possible count of the KMIP managed object types. - OKVOps
OKVOps
is the Oracle Key Vault operation handle. - OKVOpsNo
OKVOpsNo
defines the KMIP Operations withOKVOPSMAX
as the count of the maximum possible KMIP operations. - OKVServerInformation
OKVServerInformation
is the Oracle Key Vault specific information that is returned by the Oracle Key Vault server for the Oracle Key Vault query operation. - OKVTTLV
OKVTTLV
defines the Oracle Key Vault structure for a TTLV object. - OKVSignResponse
OKVSignResponse
contains the sign operation response details. - OKVSignVerifyResponse
OKVSignVerifyResponse
contains the signature verify operation response details.
Parent topic: Oracle Key Vault Datatypes and Structures
6.2.1 OKVAttr
OKVAttr
has a collection of all the KMIP attributes, single
or multi-instance attributes, supported by the KMIP specification.
Multi-instance attributes also have a field for the count of the multi-instance attribute. Attributes that have text string and byte string have a length associated with the value pointers.
Definition
/* Client SDK collection of attribtues */ struct OKVAttr { struct { oratext *id; ub4 idl; } unique_identifier; ub4 name_count; struct { oratext *name; ub4 namel; ub4 type; } name[OKV_MAX_ATTR_INSTANCES]; OKVObjNo object_type; ub4 crypto_algorithm; ub4 crypto_length; ub4 crypto_parameters_count; struct { ub4 block_cipher_mode; ub4 padding_method; ub4 hashing_algorithm; ub4 key_role_type; } crypto_parameters[OKV_MAX_ATTR_INSTANCES]; ub4 cert_type; ub4 cert_length; struct { ub1 *issuer; ub4 issuerl; ub1 *serial_number; ub4 serial_numberl; } X509_cert_identifier; struct { ub1 *distinguished_name; ub4 distinguished_namel; ub4 alternative_name_count; struct { ub1 *name; ub4 namel; } alternative_name[OKV_MAX_ALTERNATE_NAMES]; } X509_cert_subject; struct { ub1 *distinguished_name; ub4 distinguished_namel; ub4 alternative_name_count; struct { ub1 *name; ub4 namel; } alternative_name[OKV_MAX_ALTERNATE_NAMES]; } X509_cert_issuer; ub4 digital_signature_algorithm_count; ub4 digital_signature_algorithm[OKV_MAX_ATTR_INSTANCES]; ub4 digest_count; struct { ub4 hashing_algorithm; ub4 key_format_type; ub1 *digest_value; ub4 digest_valuel; } digest[OKV_MAX_ATTR_INSTANCES]; ub4 crypto_usage_mask; ub4 lease_time; struct { ub8 total; ub8 count; ub4 unit; } usage_limits; ub4 state; ub8 initial_date; ub8 activation_date; ub8 process_start_date; ub8 protect_stop_date; ub8 deactivation_date; ub8 destroy_date; ub8 compromise_occurrence_date; ub8 compromise_date; struct { ub4 reason_code; oratext *message; ub4 messagel; } revocation_reason; ub8 archive_date; ub8 fresh; ub4 link_count; struct { ub4 type; oratext *linked_object_identifier; ub4 linked_object_identifierl; } link[OKV_MAX_ATTR_INSTANCES]; ub8 last_change_date; ub8 extractable; ub8 never_extractable; /* Un-Supported Attributes * / Crypto Domain Parameters Cert_Identifier Cert_Subject Cert_Issuer Object_Group[] Contact_Information Application_Specific_Information[] Operation_Policy_Name */ }; typedef struct OKVAttr OKVAttr;
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.2 OKVAttrNo
OKVAttrNo
defines the KMIP attributes with
OKVATTRMAX
as the count of the KMIP attributes.
Definition
/* KMIP Attributes */ typedef enum { OKVAttrNone = 0, OKVAttrUniqueId, OKVAttrName, OKVAttrObjType, OKVAttrCryptoAlg, OKVAttrCryptoLen, OKVAttrCryptoParams, OKVAttrCryptoDomainParams, OKVAttrCertType, OKVAttrCertLength, OKVAttrX509CertId, OKVAttrX509CertSubject, OKVAttrX509CertIssuer, OKVAttrCertId, OKVAttrCertSubject, OKVAttrCertIssuer, OKVAttrDigitalSignAlgo, OKVAttrDigest, OKVAttrOpsPolicyName, OKVAttrCryptoUsageMask, OKVAttrLeaseTime, OKVAttrUsageLimits, OKVAttrState, OKVAttrInitialDate, OKVAttrActivationDate, OKVAttrProcessStartDate, OKVAttrProtectStopDate, OKVAttrDeactivationDate, OKVAttrDestroyDate, OKVAttrCompromiseOccurrenceDate, OKVAttrCompromiseDate, OKVAttrRevocationReason, OKVAttrArchiveDate, OKVAttrObjectGroup, OKVAttrFresh, OKVAttrLink, OKVAttrAppSpecificInfo, OKVAttrContactInfo, OKVAttrLastChangeDate, OKVAttrExtractable, OKVAttrNeverExtractable, OKVAttrInvalid = 255 } OKVAttrNo; #define OKVATTRMAX 42
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.3 OKVCryptoContext
OKVCryptoContext
holds the required parameters for
cryptographic operations.
Definition
/* Crypto Context */ struct OKVCryptoContext { OKVOpsNo crypto_operation; ub4 block_cipher_mode; ub4 padding; ub8 random_iv; ub1 *iv; ub4 ivl; ub1 *auth_encryption_additional_data; ub4 auth_encryption_additional_datal; ub1 *auth_encryption_tag; ub4 auth_encryption_tagl; ub4 crypto_algo; ub4 hashing_algo; ub4 digital_sign_algo; }; typedef struct OKVCryptoContext OKVCryptoContext;
Parameters
Parameter | Description |
---|---|
|
Type of cryptographic operation. |
|
Block Cipher Mode value. |
|
Padding value. |
|
Random IV value. |
|
IV value. |
|
IV value length. |
|
Authenticated encryption additional data value. |
|
Authenticated encryption additional data value length. |
|
Authenticated encryption tag value. |
|
Authenticated encryption tag value length. |
crypto_algo |
Cryptographic algorithm. |
hashing_algo |
Hashing algorithm. |
digital_sign_algo |
Digital signature algorithm. |
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.4 OKVDecryptResponse
OKVDecryptResponse
contains the decrypt operation response
details.
Definition
struct OKVDecryptResponse { ub1 *decrypted_data; ub4 decrypted_datal; }; typedef struct OKVDecryptResponse OKVDecryptResponse;
Parameters
Parameter | Description |
---|---|
|
Decrypted data value. |
|
Decrypted data value length. |
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.5 OKVEncryptResponse
OKVEncryptResponse
contains the encrypt operation response
details.
Definition
struct OKVEncryptResponse { ub1 *encrypted_data; ub4 encrypted_datal; ub1 *iv; ub4 ivl; ub1 *auth_encryption_tag; ub4 auth_encryption_tagl; }; typedef struct OKVEncryptResponse OKVEncryptResponse;
Parameters
Parameter | Description |
---|---|
|
Encrypted data value. |
|
Encrypted data value length. |
|
IV value. |
|
IV value length. |
|
Authenticated encryption tag value. |
|
Authenticated encryption tag value length. |
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.6 OKVEnv
OKVEnv
is the Oracle Key Vault environment handle that
controls the endpoint SDK program behavior.
OKVEnv
also holds Service Provider Interfaces (SPI) handles used in
the endpoint SDK program, the request and result OKVTTLV objects for Oracle Key
Vault functions.
Definition
/* Oracle Key Vault Environment */ struct OKVEnv { OKVConnCtx *conn_spi; OKVMemoryCtx *mem_spi; OKVParseCtx *parse_spi; ub4 flag; #define OKVENV_CONN_SETUP 0x00000001 #define OKVENV_BATCH_MODE 0x00000002 #define OKVENV_CONN_SPI 0x00000004 #define OKVENV_NATCONN_SPI 0x00000008 #define OKVENV_MEM_SPI 0x00000010 #define OKVENV_NATMEM_SPI 0x00000020 #define OKVENV_PACK_XML 0x00000040 OKVTTLV *request_obj; OKVTTLV *result_obj; OKVErr *err; OKVTrcCtx *trc_ctx; ub4 batch_cnt; OKVBatchCtx **batch; ub4 batch_err_ctx_cnt; OKVBatchErrCtx **batch_err_ctx; }; typedef struct OKVEnv OKVEnv;
Parameters
Parameter | Description |
---|---|
|
Stores the handle for the connection management SPI. If the endpoint program does not specify one then it stores the handle for the native connection management. |
|
Stores the handle for the memory management SPI. If the endpoint program does not specify one then it stores the handle for the native memory management. |
|
Stores the context for parse management. Since the serialization of OKVTTLV objects
is internal to Oracle Key Vault Client SDK,
|
|
Controls the operational behavior of the Oracle Key Vault client SDK program. Most of the flags are self explanatory. |
|
For Oracle Key Vault API functions having OKVTTLV objects as arguments, the object
is created beforehand. The allocated memory for this object is
pointed to by |
|
For Oracle Key Vault API functions that return OKVTTLV objects, the object has to be
interpreted by the EndPoint program after the call is done i.e.
the memory for the Oracle Key Vault API functions is cleaned up.
The memory for the OKVTTLV object is not cleaned at the Oracle
Key Vault function call and is pointed to by
|
|
This is the error handle that captures the errors in Oracle Key Vault operation. Multiple errors can be reported for a given operation. These errors will be captured in the error stack. |
|
Stores the handle for trace management. |
|
This is the count of batch operations. |
|
This is the array of batch operations along with the place holders for results. |
|
This is the count of batch error context. |
|
Batch error context will hold the information such as Oracle Key Vault operation name and errors related to that operation if any. |
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.7 OKVErr
OKVErr
is the Oracle Key Vault error management handle that
captures errors in an Oracle Key Vault operation.
Multiple errors can be reported for a given operation. These errors will be captured in the error stack.
Definition
/* Oracle Key Vault Error Management */ struct OKVErr { #define OKVERR_CNT 100 ub1 err_cnt; ub4 err_stack[OKVERR_CNT]; }; typedef struct OKVErr OKVErr;
Parameters
Parameter | Description |
---|---|
err_cnt |
Count of errors in the error stack, which indicates the depth of the error stack. |
err_stack |
Stack of error numbers captured. |
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.8 OKVMemoryCtx
OKVMemoryCtx
is the Oracle Key Vault memory management
context that holds the memory context and pointers to endpoint defined memory
functions.
It also holds pointers to the malloc
, realloc
, and
free
functions supplied by the endpoint program.
Definition
/* Memory Function Context */ struct OKVMemoryCtx { void *ctx; /* Context */ void * (*okvMalloc)(void *ctx, size_t size); /* Malloc */ void * (*okvRealloc)(void *ctx, void **ptr, size_t size); /* Realloc */ void (*okvFree)(void *ctx, void **ptr); /* Free */ }; typedef struct OKVMemoryCtx OKVMemoryCtx;
Parameters
Parameter | Description |
---|---|
ctx |
The endpoint program defined memory context. |
|
Pointer to the endpoint program defined function to allocate memory. This function should clear the memory allocated, that is, set all allocated bytes to zero. |
okvRealloc |
Pointer to the endpoint program defined function to re-allocate the size of the previously allocated and possibly populated memory. |
|
Pointer to the endpoint program defined function to free the memory allocated using
|
Related Topics
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.9 OKVObjNo
OKVObjNo
defines the KMIP managed object types with
OKVOBJMAX
as the maximum possible count of the KMIP managed object
types.
Definition
/* OKV KMIP Managed Objects */ typedef enum { OKVObjNone = 0, /* No Object Type */ OKVObjCert = 1, /* Certificate */ OKVObjSymmetric, /* Symmetric Key */ OKVObjPublic, /* Public Key */ OKVObjPrivate, /* Private Key */ OKVObjTemplate = 6, /* Template */ OKVObjSecret, /* Secret Data */ OKVObjOpaque /* Opaque Object */ } OKVObjNo; #define OKVOBJMAX 8
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.10 OKVOps
OKVOps
is the Oracle Key Vault operation
handle.
Definition
/* Oracle Key Vault KMIP Operation */ struct OKVOps { OKVOpsNo ops; OKVErr err; OKVTTLV *item; OKVTTLV *req; ub4 res; OKVTTLV *resp; OKVErr *errb; }; typedef struct OKVOps OKVOps;
OKVOps captures the request and response OKVTTLV structures for a given Oracle Key Vault KMIP operation along with the result (pass or fail) of the operation.
Parameters
Parameter | Description |
---|---|
|
KMIP operation associated with this Oracle Key Vault operation handle. |
|
Error handle for batch operations. |
item |
Batch item of this KMIP operation. |
req |
KMIP Request OKVTTLV object. |
|
Result of the KMIP operation. |
|
KMIP Response OKVTTLV object. |
|
Error handle pointer for batch operations. |
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.11 OKVOpsNo
OKVOpsNo
defines the KMIP Operations with
OKVOPSMAX
as the count of the maximum possible KMIP
operations.
Definition
/* KMIP Operations */ typedef enum { OKVOpNone = 0, /* Wrong Operation */ OKVOpCreate = 1, /* Create */ OKVOpCreateKeyPair, OKVOpRegister, /* Register */ OKVOpRekey, /* Rekey */ OKVOpDeriveKey, OKVOpCertify, OKVOpRecertify, OKVOpLocate, /* Locate */ OKVOpCheck, /* Check */ OKVOpGet, /* Get */ OKVOpGetAttributes, /* Get Attributes */ OKVOpGetAttributeList, /* Get Attribute List */ OKVOpAddAttribute, /* Add Attribute */ OKVOpModifyAttribute, /* Modify Attribute */ OKVOpDeleteAttribute, /* Delete Attribute */ OKVOpObtainLease, OKVOpGetUsageAllocation, OKVOpActivate, /* Activate */ OKVOpRevoke, /* Revoke */ OKVOpDestroy, /* Destroy */ OKVOpArchive, OKVOpRecover, OKVOpValidate, OKVOpQuery, /* Query */ OKVOpCancel, OKVOpPoll, OKVOpNotify, OKVOpPut, OKVOpRekeyKeyPair, OKVOpDiscoverVersions, /* Discover Versions */ OKVOpEncrypt, /* Encrypt */ OKVOpDecrypt, /* Decrypt */ OKVOpSign, /* Sign */ OKVOpSignVerify, /* Verify */ } OKVOpsNo; #define OKVOPSMAX 35
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.12 OKVServerInformation
OKVServerInformation
is the Oracle Key Vault specific
information that is returned by the Oracle Key Vault server for the Oracle Key Vault query
operation.
Definition
struct OKVServerInformation { oratext server_name[30]; oratext server_version[30]; }; typedef struct OKVServerInformation OKVServerInformation;
Parameters
Parameter | Description |
---|---|
|
Should be ORACLE KEYVAULT SERVER if the endpoint program is communicating with the Oracle Key Vault server. |
|
The version of the Oracle Key Vault server the endpoint program is communicating with. |
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.13 OKVTTLV
OKVTTLV
defines the Oracle Key Vault structure for a TTLV object.
Definition
/* Oracle Key Vault KMIP TTLV Structure */ struct OKVTTLV { OKVTag tag; OKVType typ; ub4 len; ub1 *val; ub4 ttlv_array_cnt; OKVTTLV **ttlv_array; }; typedef struct OKVTTLV OKVTTLV;
Parameters
Parameter | Description |
---|---|
|
The tag value of the TTLV object. |
|
The type value of the TTLV object. |
len |
The length of the value of the TTLV object. |
|
The value of the TTLV object. |
|
The count of the child TTLV objects for this TTLV object. |
|
An array of the child TTLV objects for this TTLV object. |
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.14 OKVSignResponse
OKVSignResponse
contains the sign operation response
details.
Syntax
struct OKVSignResponse { ub1 *signature_data; ub4 signature_datal; };
Parameters
Table 6-2 Parameters
Parameter | Description |
---|---|
signature_data |
Signature data value. |
signature_datal |
Signature data value length. |
Parent topic: Oracle Key Vault Structures and Enumerations
6.2.15 OKVSignVerifyResponse
OKVSignVerifyResponse
contains the signature verify
operation response details.
Syntax
struct OKVSignVerifyResponse { ub1 *recovered_data; ub4 recovered_datal; ub4 validity; };
Parameters
Table 6-3 Parameters
Parameter | Description |
---|---|
recovered_data |
Recovered data value. |
recovered_datal |
Recovered data value length. |
validity |
Validity indicator, which may take the value of
OKVDEF_VALIDITY_VALID , OKVDEF_VALIDITY_INVALID ,
or OKVDEF_VALIDITY_UNKNOWN .
|
Parent topic: Oracle Key Vault Structures and Enumerations