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.

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.

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 with OKVATTRMAX as the count of the KMIP attributes.
• 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 with OKVOBJMAX 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 with OKVOPSMAX 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.

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;

  /* 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;

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,
  OKVAttrCompromiseOccurenceDate,
  OKVAttrCompromiseDate,
  OKVAttrRevocationReason,
  OKVAttrArchiveDate,
  OKVAttrObjectGroup,
  OKVAttrFresh,
  OKVAttrLink,
  OKVAttrAppSpecificInfo,
  OKVAttrContactInfo,
  OKVAttrLastChangeDate,
  OKVAttrInvalid = 255
} OKVAttrNo;
#define OKVATTRMAX  33

6.2.3 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
conn_spi	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.
mem_spi	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.
parse_spi	Stores the context for parse management. Since the serialization of OKVTTLV objects is internal to Oracle Key Vault Client SDK, parse_spi is set and unset internally only. KMIP v1.1 can have a regular TTLV packing or XML style packing. In the first version of Oracle Key Vault Client SDK, TTLV packing is supported.
flag	Controls the operational behavior of the Oracle Key Vault client SDK program. Most of the flags are self explanatory.
request_obj	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 request_obj.
result_obj	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 result_obj.
err	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.
trc_ctx	Stores the handle for trace management.
batch_cnt	This is the count of batch operations.
batch	This is the array of batch operations along with the place holders for results.
batch_err_ctx_cnt	This is the count of batch error context.
batch_err_ctx	Batch error context will hold the information such as Oracle Key Vault operation name and errors related to that operation if any.

6.2.4 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.

6.2.5 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.
okvMalloc	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.
okvFree	Pointer to the endpoint program defined function to free the memory allocated using okvMalloc or okvRealloc. The pointer should be set to NULL after freeing it.

6.2.6 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

6.2.7 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
ops	KMIP operation associated with this Oracle Key Vault operation handle.
err	Error handle for batch operations.
item	Batch item of this KMIP operation.
req	KMIP Request OKVTTLV object.
res	Result of the KMIP operation.
resp	KMIP Response OKVTTLV object.
errb	Error handle pointer for batch operations.

6.2.8 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 */
} OKVOpsNo;
#define OKVOPSMAX                  30

6.2.9 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
server_name	Should be ORACLE KEYVAULT SERVER if the endpoint program is communicating with the Oracle Key Vault server.
server_version	The version of the Oracle Key Vault server the endpoint program is communicating with.

6.2.10 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
tag	The tag value of the TTLV object.
typ	The type value of the TTLV object.
len	The length of the value of the TTLV object.
val	The value of the TTLV object.
ttlv_array_cnt	The count of the child TTLV objects for this TTLV object.
ttlv_array	An array of the child TTLV objects for this TTLV object.