Data types in Network Identity Manager

Network Identity Manager's Credentials Database supports several useful data types. In addition, plug-ins can define custom data types. Only a few operations are expected of these data types since the core KCDB delegates fine grained operations to other entities that understand the underlying format.

A field in a credential can have any one of these data types, but it must have some data type. Each value can be at most KCDB_TYPE_MAXCB bytes in length regardless of the data type.

Some data types have a fixed size (such as Int32), while others are variable size. The required memory for each field in a credential is allocated as needed.

Data types

Descriptions of individual data types are below.

Individual data types

Void

Type identifier : KCDB_TYPE_VOID

The Void data type is used to indicate that the associated object does not contain any data.

String

Type identifier : KCDB_TYPE_STRING

A unicode string that is terminated with a unicode NULL (L'\0'). By default, the type has the following flags:

KCDB_TYPE_FLAG_CB_AUTO

This is because, as long as the string is terminated with a unicode NULL, the length of the string, and therefore it's size in bytes, can be inferred from the data itself.

Date

Type identifier : KCDB_TYPE_DATE

Dates and times in Network Identity Manager are stored in FILETIME structures. Utility functions are provided for converting from other formats such as time_t.

Interval

Type identifier : KCDB_TYPE_INTERVAL

Stores an interval of time. Stored as a 64-bit signed integer. The string representation of this data type is different from the Date data type and designates an interval of time.

The special value _I64_MAX (which is defined in limits.h as 0x7fffffffffffffff, or in other words, the largest positive value that can be stored in a 64-bit signed integer) is used to represent an interval of unknown length.

The string representations of a data value of Interval type are defined as follows for English (US):

Int32

Type identifier : KCDB_TYPE_INT32

A signed 32-bit integer.

Int64

Type identifier : KCDB_TYPE_INT64

A signed 64-bit integer.

Data

Type identifier : KCDB_TYPE_DATA

Raw data. Can contain a byte stream. This data type can be used by plug-ins to associate raw data with a credential. However, there is no built-in string representation for this data type. As such, this is not meant to be used for storing anything that has to be displayed to the user verbatim.

Custom data types

Custom data type call backs

Custom data types in the Network Identity Manager Credentials Database are defined using kcdb_type structures that must include several callback functions. The expected behavior of these callback functions is documented below.

toString

      khm_int32   toString(
        const void * data,
        khm_int32 cb_data,
        wchar_t *buffer,
        khm_int32 *pcb_buffer,
        khm_int32 flags);

Produce the localized string representation of the object pointed to by data. The size of the data block is specified by the cb_data parameter. If the data type specified the KCDB_TYPE_FLAG_CB_AUTO flag then cb_data can be KCDB_CBSIZE_AUTO, in which case the size of the data block is to be inferred.

toString should assume that the block of data pointed to by data is valid for this data type.

The pcb_buffer parameter is always a valid pointer to an khm_int32 variable.

The buffer parameter is a pointer to a wchar_t buffer which is to receive the unicode string representing the object. buffer may be NULL, in which case the required size of the buffer should be returned in pcb_buffer. In this case, the function should return KHM_ERROR_TOO_LONG.

If the buffer parameter is not NULL and the pcb_buffer specifies that the buffer is large enough to hold the string representation, the function should copy the string representation to the buffer, set the pcb_buffer to the number of bytes that were copied including the terminating NULL, and return KHM_ERROR_SUCCESS.

If the buffer parameter is not NULL and the pcb_buffer specifies a buffer that is not large enough, the function should set pcb_buffer to the required size (including the terminating NULL) and then return KHM_ERROR_TOO_LONG.

comp

      khm_int32 comp(
        const void * data1,
        khm_int32 cb_data1,
        const void * data2,
        khm_int32 cb_d2);

Compares two objects and returns a value indicating the relative ordering.

Since the KCDB does not interpret any data type, it relies on a loose definition of what a relative ordering is. It is left up to each data type callback to interpret what 'ascending' and 'descending' mean.

The return value r should be as follows:

r < 0 : if data1 < data2

r > 0 : if data1 > data2

r = 0 : if data1 = data2 or no relative ordering can be determined for the two objects data1 and data2.

The function should assume that both objects are valid for this data type.

The size specifiers cb_data1 and cb_data2 can (either or both) be KCDB_CBSIZE_AUTO if the data type specified KCDB_TYPE_FLAG_CB_AUTO flag.

dup

      khm_int32 dup(
        const void * d_src,
        khm_int32 cb_src,
        void * d_dst,
        khm_int32 * pcb_dst);

Duplicate an object. The object pointed to by d_src is to be copied to the buffer pointed to by d_dst. The function is to assume that d_src object is valid. The size specifier cb_src may be KCDB_CBSIZE_AUTO if KCDB_TYPE_FLAG_CB_AUTO was specified for the data type.

If d_dst pointer is NULL, then the required buffer size should be returned in pcb_dst. In this case, the function itself should return KHM_ERROR_TOO_LONG. The same behavior should occur if d_dst is non NULL and pcb_dst indicates that the buffer is not sufficient.

If d_dst is not NULL and pcb_dst indicates that the buffer is sufficient, then a copy of the object in d_src should be placed in d_dst. The function shold return KHM_ERROR_SUCCESS and set pcb_dst to the number of bytes that were copied.

This callback will only be called when the credentials database is retrieving objects from the outside. Once it receives an object it may be copied or moved as required. Hence the object should not assume to reside in a specific location of memory. Also, dup is not intended to perform such functions as reference counting which require knowledge of a precise number of instances of an object, as the credentials database may copy the object simply by copying the block of memory.

Note that whenever pcb_dst is to be set, it MUST be set to a valid byte count. It can not be assigned KCDB_CBSIZE_AUTO even if the data type supports it. The pcb_dst parameter is used internally to allocate memory for the object.

isValid

      khm_boolean isValid(
        const void * data,
        khm_int32 cb_data);

Checks if the object pointed to by the data pointer is a valid object for this data type. If the data type specified the KCDB_TYPE_CB_AUTO flag, then the cb_data parameter may be KCDB_CBSIZE_AUTO, in which the size of the object should be inferred from the data.

The function should be able to determine the validity of the object and return TRUE if it is valid. Return FALSE if it isn't, or if the size of the object can not be inferred from the given data, or if the inferred size exceeds KCDB_TYPE_MAXCB.


Generated on Fri Aug 3 08:27:13 2007 for Network Identity Manager by Doxygen 1.5.2
© 2004-2007 Massachusetts Institute of Technology.
© 2005-2007 Secure Endpoints Inc.
Contact khimaira@mit.edu