Common Security: CDSA and CSSM - Data Storage Library Interface

Common Security: CDSA and CSSM
Copyright © 1997 The Open Group

Data Storage Library Interface

Overview

The primary purpose of a data storage library (DL) is to provide access to persistent stores of security-related objects. The DL provides access to these data stores by translating calls from the DLI into the native interface of the data store. The native interface of the data store may be that of a database management system package, a directory service, a custom storage device, or a traditional local or remote file system. Applications are able to obtain information about the available DL services by using the CSSM_GetModuleInfo function to query the CSSM registry. The information about the DL service includes:

Vendor information. Information about the module vendor, a text description of the DL and the module version number.
Types of supported data stores. The module may support one or more types of persistent data stores as separate sub-services. For each type of data store, the DL provides information on the supported query operators and optionally provides specific information on the accessible data stores.

The data storage library may chose to provide information about the data stores that it has access to. Applications can obtain information about these data stores by using the CSSM_GetModuleInfo function call. The information about the data store includes:

Types of persistent security objects. The types of security objects which may be stored include certificates, certificate revocation lists (CRLs), keys, policy objects, and generic data objects. A single data store can contain a single object type in one format, a single object type in multiple formats, or multiple object types.
Attributes of persistent security objects. The stored security object may have attributes which must be included by the calling application on data insertion and which are returned by the DL on data retrieval.
Data store indexes. These indexes are high-performance query paths constructed as part of data store creation and maintained by the data store.
Secure Access Mechanisms. A data store may restrict a user's ability to perform certain actions on the data store or on the data store's contents. This structure exposes the mechanism required to authenticate to the data store.
Record Integrity Capabilities. Some data stores will insure the integrity of the data store's contents. To insure the integrity of the data store's contents, the data store is expected to sign and verify each record.
Data store location. The persistent repository can be local or remote.

To build indexes or to satisfy an application's request for record retrieval, the data store may need to parse the stored security objects. If the application has invoked CSSM_DL_SetDbRecordParsingFunctions for a given security object type, those functions will be used to parse that security object as the need arises. If the application has not explicitly set record parsing functions, the default add-in modules set by the data store creator will be used for parsing.

To ensure a minimal level of interoperability among applications and DL modules, CSSM requires that all DL modules recognize and support two pre-defined attribute names for all record types. All applications can use these strings as valid attribute names even if no value is stored in association with the attribute name.

Secured access to the data store and to the data store's contents may be enforced by the data storage library, the data store or both. The partitioning of authentication responsibility is exposed via the DL and DB authentication mechanisms available from the CSSM registry.

Data stores may be added to a data storage library in one of three ways:

Using DL_DbCreate. This creates and opens a new, empty data store with the specified schema.
Using DL_DbImport with information and data. If the specified data store does not exist, a new data store is created with the specified schema and the exported data records.
Using DL_DbImport with information only. In this case, the data store's native format is the same as that managed by the DL service. Importing its information makes it accessible via this DL service.

In all cases, it is the responsibility of the DL service to update the CSSM registry with information about the new data store. This can be accomplished by making use of the CSSM_GetModuleInfo and CSSM_SetModuleInfo functions.

Categories of Operations

The data storage library SPI defines four categories of operations:

Data storage library operations
Data store operations
Data record operations
Extensibility operations

Data storage library operations are used to control access to the data storage library. They include:

Authentication to the DL Module. A user may be required to present valid credentials to the data storage library prior to accessing any of the data stores embedded in the DL module. The DL module will be responsible for insuring that the user does not exceed his/her access privileges.
The data store functions operate on a data store as a single unit. These operations include:
Opening and closing data stores. A DL service manages the mapping of logical data store names to the storage mechanisms it uses to provide persistence. The caller uses logical names to reference persistent data stores. The open operation prepares an existing data store for future access by the caller. The close operation terminates current access to the data store by the caller.
Creating and deleting data stores. A DL creates a new, empty data store and opens it for future access by the caller. An existing data store may be deleted. Deletion discards all data contained in the data store.
Importing and exporting data stores. Occasionally a data store must be moved from one system to another or a DL service may need to provide access to an existing data store. The import and export operations may be used in conjunction to support the transfer of an entire data store. The export operation prepares a snapshot of a data store. (Export does not delete the data store it snapshots.) The import operation accepts a snapshot (generated by the export operation) and includes it in a new or existing data store managed by a DL. Alternately, the import operation may be used independently to register an existing data store with a DL.

The data record operations operate on a single record of a data store. They include:

Adding new data objects. A DL adds a persistent copy of data object to an open data store. This operation may or may not include the creation of index entries. The mechanisms used to store and retrieve persistent data objects are private to the implementation of a DL module.
Deleting data objects. A DL removes single data object from the data store.
Retrieving data objects. A DL provides a search mechanism for selectively retrieving a copy of persistent security objects. Selection is based on a selection criterion.

Data store extensibility operations include:

Pass-through for unique, module-specific operations. A pass-through function is included in the data storage library interface to allow data store libraries to expose additional services beyond what is currently defined in the CSSM API. CSSM passes an operation identifier and input parameters from the application to the appropriate data storage library. Within the DL_PassThrough function in the data storage library, the input parameters are interpreted and the appropriate operation performed. The data storage library developer is responsible for making known to the application the identity and parameters of the supported pass-through operations.

Data Storage Library Operations

CSSM_RETURN CSSMDLI DL_Authenticate(): Authenticates a user's ability to use this DL for accessing the underlying data stores.

Data Store Operations

CSSM_DB_HANDLE CSSMDLI DL_DbOpen()

For authorized users, this opens a data store with the specified logical name in the requested access mode. Returns a handle to the data store.

CSSM_RETURN CSSMDLI DL_DbClose()

Closes a data store.

CSSM_DB_HANDLE CSSMDLI DL_DbCreate()

Creates and opens a new, empty data store with the specified logical name and the specified schema. As a side effect, the DL updates the CSSM Registry to expose information about the new data store.

CSSM_RETURN CSSMDLI DL_DbDelete()

For authorized users, this deletes all records from the specified data store and removes current state information associated with that data store.

CSSM_RETURN CSSMDLI DL_DbImport()

Accepts as input a flag for what to import, a filename, a logical name, and a schema for a data store. If information about the data store is being imported, then the DL updates its list of accessible data stores to include this new data store with the specified schema. If the contents of the data store are being imported, then the file contains an exported copy of an existing data store. The data records contained in the file must be in the native format of a data store. The DL imports all security objects in the file (such as certificates and CRLs), creating a new data record for each. If the specified logical name is that of an existing data store, the new records will be added to the data store. Otherwise, a new data store will be created with the specified schema to hold the new records.

Note:: This mechanism can be used to copy data stores among systems or to restore a persistent data store from a backup copy. It could also be used to import data stores that were created and managed by other DLs, but this is not the typical implementation and use of this interface.

CSSM_RETURN CSSMDLI DL_DbExport()

Accepts as input the logical name of a data store and the name of a target output file. The specified data store contains persistent data records. A representation of the schema for the data store being exported is written to the file along with a copy of each data record in the data store.

Note:: This mechanism can be used to copy data stores among systems or to create a backup of persistent data stores.

CSSM_RETURN CSSMDLI DL_DbSetRecordParsingFunctions()

Sets the functions to be used for parsing the specified type of security object.

CSSM_DB_RECORD_PARSING_FNTABLE_PTR CSSMDLI DL_DbGetRecordParsingFunctions()

Returns the function pointers in use for parsing the specified type of security object.

char * CSSMDLI DL_GetDbNameFromHandle()

Retrieves the data source name corresponding to an opened database handle.

CSSM_NAME_LIST_PTR CSSMDLI DL_GetDbNames()

Returns the names of data stores accessible via this DL module.

CSSM_RETURN CSSMDLI DL_FreeNameList()

Frees the list of data stores returned by a call to DL_GetDbNames.

Data Record Operations

CSSM_DB_UNIQUE_RECORD_PTR CSSMDLI DL_DataInsert(): Accepts as input a handle to a data store, the type of the security object, the attributes of the object and the object itself. The data object and its attributes are made persistent in the specified data store. This may or may not include the creation of index entries, and so on. The DL module will return to the calling application a unique identifier for the input record which may be used to rapidly retrieve the security object. The mechanisms used to store and retrieve persistent security objects is private to the implementation of the Data Storage Library.
CSSM_RETURN CSSMDLI DL_DataDelete(): Accepts as input a handle to a data store and a unique identifier of the security object. The object is removed from the data store. If the object is not found in the specified data store, or if the user does not have deletion permissions, the operation fails.
CSSM_RETURN CSSMDLI DL_DataModify(): Accepts as input a handle to a data store, the type of the security object, a unique record identifier, the attributes to be modified and the data to be modified. If present, the attributes are added, replaced, or deleted depending on the input attribute values and the current contents of the record attributes. If present, the record data is replaced with the input data. An indicator of the operation's success or failure is returned. Either all or none of the requested modifications will have occurred.
CSSM_DATA_PTR CSSMDLI DL_DataGetFirst(): Accepts as input a handle to a data store, a query, and a list of the attributes to be retrieved. The query is composed of the type of data record to be retrieved, a selection predicate, and any limits or flags on the query. Selection predicates are represented as a set of (relational operator, attribute) pairs that are connected by a conjunctive operator. Query limits provide a mechanism for the user to specify upper bounds on the search time and/or the number of records retrieved. Not all DL modules will support query limits. The specified data store is searched for data objects of the specified type that match the selection criteria. This function returns the first data object matching the criteria together with the requested attributes and a unique identifier for use in future references. If additional objects matched, a selection handle is returned that may be used to retrieve the subsequent objects. A data storage library may limit the number of concurrently managed selection handles to exactly one. The library developer must document all such restrictions and application developers should proceed accordingly.
CSSM_DATA_PTR CSSMDLI DL_DataGetNext(): Accepts as input a selection results handle that was returned by an invocation of the function CSSM_DL_DataGetFirst and a list of the attributes to be returned. If there are no more records to retrieve, the EndOfDataStore flag is set to CSSM_TRUE and the function returns NULL. Otherwise, a DL module returns the next data record, the requested attributes, and a unique identifier, from the set specified by the selection results handle. A data storage library may limit the number of concurrently-managed selection result handles to exactly one. The library developer must document such restrictions, and application developers should proceed accordingly.
CSSM_RETURN CSSMDLI DL_DataAbortQuery(): Cancels the query initiated by CSSM_DL_DataGetFirst function and resets the selection results handle.
CSSM_RETURN CSSMDLI DL_DataGetFromUniqueRecordId(): Accepts as input a unique record identifier and a list of the attributes to be retrieved. The specified data store is searched for the record corresponding to the unique record identifier. This function returns the data object together with the requested attributes.
CSSM_RETURN CSSMDLI DL_FreeUniqueRecord(): Frees the memory associated with the input unique record structure.

Extensibility Functions

void * CSSMDLI DL_PassThrough(): Accepts as input an operation ID and a set of arbitrary input parameters. The operation ID may specify any type of operation a DL wishes to export for use by an application or by another module. Such operations may include queries or services that are specific to certain types of security objects or specific types of data stores managed by a DL module. It is the responsibility of the DL developer to make information on the availability and usage of passthrough operations available to application developers.

Data Storage Data Structures

CSSM_DL_HANDLE

A unique identifier for an attached module that provides data storage library services.

typedef uint32 CSSM_DL_HANDLE  /* Data Storage Library Handle */

CSSM_DB_HANDLE

A unique identifier for an open data store.

typedef uint32 CSSM_DB_HANDLE    /* Data Store Handle */

CSSM_DL_DB_HANDLE

This data structure holds a pair of handles, one for a data storage library and another for a data store opened and being managed by the data storage library.

typedef struct cssm_dl_db_handle {
    CSSM_DL_HANDLE DLHandle;
    CSSM_DB_HANDLE DBHandle;
} CSSM_DL_DB_HANDLE, *CSSM_DL_DB_HANDLE_PTR;

Definition

DLHandle: Handle of an attached module that provides DL services.
DBHandle: Handle of an open data store that is currently under the management of the DL module specified by the DLHandle.

CSSM_DL_DB_LIST

This data structure defines a list of handle pairs of (data storage library handle, data store handle).

typedef struct cssm_dl_db_list {
    uint32 NumHandles;
    CSSM_DL_DB_HANDLE_PTR DLDBHandle;
} CSSM_DL_DB_LIST, *CSSM_DL_DB_LIST_PTR;

Definition

NumHandles: Number of (data storage library handle, data store handle) pairs in the list.
DLDBHandle: List of (data storage library handle, data store handle) pairs.

CSSM_DB_ATTRIBUTE_NAME_FORMAT

This enumerated list defines the two formats used to represent an attribute name. The name can be represented by a character string in the native string encoding of the platform or the name can be represented by an opaque OID structure that is interpreted by the DL module.

typedef enum cssm_db_attribute_name_format {
    CSSM_DB_ATTRIBUTE_NAME_AS_STRING = 0,
    CSSM_DB_ATTRIBUTE_NAME_AS_OID = 1,
} CSSM_DB_ATTRIBUTE_NAME_FORMAT, *CSSM_DB_ATTRIBUTE_NAME_FORMAT_PTR;

CSSM_DB_ATTRIBUTE_FORMAT

This enumerated list defines the formats for attribute values. Many data storage library modules manage only one attribute format, CSSM_DB_ATTRIBUTE_FORMAT_STRING. These format indicators can be set by application caller or by the data storage library module. When a caller selects an format option that cannot be supported by the library module, the module can ignore the caller-declared format.

typedef enum cssm_db_attribute_format {
    CSSM_DB_ATTRIBUTE_FORMAT_STRING = 0,
    CSSM_DB_ATTRIBUTE_FORMAT_INTEGER = 1,
    CSSM_DB_ATTRIBUTE_FORMAT_REAL = 2,
    CSSM_DB_ATTRIBUTE_FORMAT_TIME = 3,
    CSSM_DB_ATTRIBUTE_FORMAT_MONEY = 4,
    CSSM_DB_ATTRIBUTE_FORMAT_BLOB = 5,
} CSSM_DB_ATTRIBUTE_FORMAT, *CSSM_DB_ATTRIBUTE_FORMAT;

CSSM_DB_ATTRIBUTE_INFO

This data structure describes an attribute of a persistent record. The description is part of the schema information describing the structure of records in a data store. The description includes the format of the attribute name and the attribute name itself. The attribute name implies the underlying data type of a value that may be assigned to that attribute.

typedef struct cssm_db_attribute_info {
    CSSM_DB_ATTRIBUTE_NAME_FORMAT AttributeNameFormat;
    union cssm_db_attribute_label {
        char * AttributeName;  /* e.g., "record label" */
        CSSM_OID AttributeID;  /* e.g., CSSMOID_RECORDLABEL */
    } Label;
    CSSM_DB_ATTRIBUTE_FORMAT AttributeFormat;
} CSSM_DB_ATTRIBUTE_INFO, *CSSM_DB_ATTRIBUTE_INFO_PTR;

Definition

AttributeNameFormat: Indicates which of the two formats was selected to represent" the attribute name.
AttributeName: A character string representation of the attribute name.
AttributeID: A DER-encoded OID representation of the attribute name.
AttributeFormat: Indicates the format of the attribute.The Data Storage Library may not support more than one format, typically CSSM_DB_ATTRIBUTE_FORMAT_STRING. In this case, the library module can ignore any format specification provided by the caller.

CSSM_DB_ATTRIBUTE_DATA

This data structure holds an attribute value that can be stored in an attribute field of a persistent record. The structure contains a value for the data item and a reference to the meta information (typing information and schema information) associated with the attribute.

typedef struct cssm_db_attribute_data {
    CSSM_DB_ATTRIBUTE_INFO Info;
    CSSM_DATA Value;
} CSSM_DB_ATTRIBUTE_DATA, *CSSM_DB_ATTRIBUTE_DATA_PTR;

Definition

Info: A reference to the meta-information/schema describing this attribute in relationship to the data store at large.
Value: The data-present value assigned to the attribute.

To ensure a minimal level of interoperability among applications and DL modules, CSSM requires that all DL modules recognize and support two pre-defined attribute names for all record types:

PrintName: a printable or viewable string name associated with the record
Alias: an arbitrary value associated with the record. The value can be non-printable.

Applications that create new data stores and define the associated schema are encouraged to define these attributes as part of the schema. If the data store creator does not define these attributes, the DL module must add these attributes with the following minimum storage size requirements

PrintName: the associated value is a string of maximum length 16 characters
Alias: the associated value is an arbitrary data type of maximum length 8 bytes

Applications are encouraged to provide values for these attributes when creating data store records, but values are not required. All applications can use these strings as valid attribute names even if no value is stored in association with this attribute name. When no value is associated with a pre-defined attribute name, it is possible for a DL module that encapsulates a data store schema to return one of the following:

A module-defined default value
A value selected from a database-key attribute in the data store
A NULL value

The CSSM_DB_ATTRIBUTE_DATA structure for the pre-defined attribute name "PrintName" contains the following values:

  {  AttributeNameFormat = CSSM_DB_ATTRIBUTE_NAME_AS_STRING
     AttributeName = "PrintName"
     Value = <a value in a CSSM_DATA structure>  }

CSSM_DB_RECORDTYPE

This enumerated list defines the categories of persistent security-related objects that can be managed by a data storage library module. These categories are in one-to-one correspondence with types of records that can be managed by a data store.

typedef enum cssm_db_recordtype {
    CSSM_DL_DB_RECORD_GENERIC = 0,
    CSSM_DL_DB_RECORD_CERT = 1,
    CSSM_DL_DB_RECORD_CRL = 2,
    CSSM_DL_DB_RECORD_KEY = 3,
    CSSM_DL_DB_RECORD_POLICY = 4,
} CSSM_DB_RECORDTYPE;

CSSM_DB_CERTRECORD_SEMANTICS

These bit masks define a list of usage semantics for how certificates may be used. It is anticipated that additional sets of bit masks will be defined listing the usage semantics of how other record types can be used, such as CRL record semantics, key record semantics, policy record semantics, and so on.

#define CSSM_DB_CERT_USE_TRUSTED 0x00000001
                         /* application-defined as trusted */
#define CSSM_DB_CERT_USE_SYSTEM  0x00000002
                         /* the CSSM system cert */
#define CSSM_DB_CERT_USE_OWNER   0x00000004
                         /* private key owned by system user*/
#define CSSM_DB_CERT_USE_REVOKED 0x00000008
                         /* revoked cert - used w\ CRL APIs */
#define CSSM_DB_CERT_USE_SIGNING 0x00000010
                         /* use cert for signing only */
#define CSSM_DB_CERT_USE_PRIVACY 0x00000020
                         /* use cert for confidentiality only */

Record semantic designations are advisory only. For example, the designation CSSM_DB_CERT_USE_OWNER suggests that the private key associated with the public key contained in the certificate is local to the system. This statement was probably true when the certificate was created. Various actions could make this assertion false. The private key could have expired, been revoked, or be stored in a portable cryptographic storage device that is not currently resident on the system. The validity of the advisory designation CSSM_DB_CERT_USE_TRUSTED should be verified using standard certificate verification procedures. Although these designators are advisory, application or trust policies can choose to use this information if it is useful for their purpose. For example, a trust policy can define how advisory designations can be used when full policy evaluation requires connection to a remote facility that is currently inaccessible.

Management practices for record semantic designators define the agent and the time when a data store record can be assigned a particular designator value. Reasonable usage is described as follows:

Designation Value Assigning Time Assigning Agents
CSSM_DB_CERT_USE_TRUSTED Local record creation time
Remote record creation time
Reset at any time Sys Admin App
App/Record Owner
CSSM_DB_CERT_USE_SYSTEM Local record creation time
Should not be reset Sys Admin App
CSSM_DB_CERT_USE_OWNER Local record creation time
Reset at any time App/Record Owner
CSSM_DB_CERT_USE_REVOKED Set once only Sys Admin App
App/Record Owner
CSSM_DB_CERT_SIGNING Local record creation time Remote Authority
Local Authority
Record Owner
CSSM_DB_CERT_PRIVACY Local record creation time Remote Authority
Local Authority
Record Owner

Designation Value	Assigning Time	Assigning Agents
CSSM_DB_CERT_USE_TRUSTED	Local record creation time Remote record creation time Reset at any time	Sys Admin App App/Record Owner
CSSM_DB_CERT_USE_SYSTEM	Local record creation time Should not be reset	Sys Admin App
CSSM_DB_CERT_USE_OWNER	Local record creation time Reset at any time	App/Record Owner
CSSM_DB_CERT_USE_REVOKED	Set once only	Sys Admin App App/Record Owner
CSSM_DB_CERT_SIGNING	Local record creation time	Remote Authority Local Authority Record Owner
CSSM_DB_CERT_PRIVACY	Local record creation time	Remote Authority Local Authority Record Owner

CSSM_DB_RECORD_ATTRIBUTE_INFO

This structure contains the meta information or schema information about all of the attributes in a particular record type. The description specifies the record type, the number of attributes in the record type, and a type information for each attribute. This description includes the CSSM pre-defined attributes named "PrintName" and "Alias".

typedef struct cssm_db_record_attribute_info {
    CSSM_DB_RECORDTYPE DataRecordType;
    uint32 NumberOfAttributes;
    CSSM_DB_ATTRIBUTE_INFO_PTR AttributeInfo;
} CSSM_DB_RECORD_ATTRIBUTE_INFO, *CSSM_DB_RECORD_ATTRIBUTE_INFO_PTR;

Definition

DataRecordType: A CSSM_DB_RECORDTYPE.
NumberOfAttributes: The number of attributes in a record of the specified type.
AttributeInfo: A list of pointers to the type (schema) information for each of the attributes.

CSSM_DB_RECORD_ATTRIBUTE_DATA

This structure aggregates the actual data values for all of the attributes in a single record.

typedef struct cssm_db_record_attribute_data {
    CSSM_DB_RECORDTYPE DataRecordType;
    uint32 SemanticInformation;
    uint32 NumberOfAttributes;
    CSSM_DB_ATTRIBUTE_DATA_PTR AttributeData;
} CSSM_DB_RECORD_ATTRIBUTE_DATA, *CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR;

Definition

DataRecordType: A CSSM_DB_RECORDTYPE.
SemanticInformation: A bit mask of type CSSM_XXXRECORD_SEMANTICS defining how the record can be used. Currently these bit masks are defined only for certificate records (CSSM_CERTRECORD_SEMANTICS). For all other record types, a bit mask of zero must be used or a set of semantically meaningful masks must be defined.
NumberOfAttributes: The number of attributes in the record of the specified type.
AttributeData: A list of attribute name/value pairs. If no stored value is associated with this attribute, the attribute data pointer is NULL.

CSSM_DB_RECORD_PARSING_FNTABLE

This structure defines the three prototypes for functions that can parse the opaque data object stored in a record. It is used in the CSSM_DbSetRecordParsingFunctions function to override the default parsing module for a given record type. The DL module developer designates the default parsing module for each record type stored in the data store.

typedef struct cssm_db_record_parsing_fntable {
    CSSM_DATA_PTR (CSSMAPI *RecordGetFirstFieldValue)
        (CSSM_HANDLE Handle,
        const CSSM_DATA_PTR Data,
        const CSSM_OID_PTR DataField,
        CSSM_HANDLE_PTR ResultsHandle,
        uint32 *NumberOfMatchedFields);
    CSSM_DATA_PTR (CSSMAPI *RecordGetNextFieldValue)
        (CSSM_HANDLE Handle,
        CSSM_HANDLE ResultsHandle);
    CSSM_RETURN (CSSMAPI *RecordAbortQuery)
        (CSSM_HANDLE Handle,
        CSSM_HANDLE ResultsHandle);
} CSSM_DB_RECORD_PARSING_FNTABLE, *CSSM_DB_RECORD_PARSING_FNTABLE_PTR;

Definition

*RecordGetFirstFieldValue: A function to retrieve the value of a field in the opaque object. The field is specified by attribute name. The results handle holds the state information required to retrieve subsequent values having the same attribute name.
*RecordGetNextFieldValue: A function to retrieve subsequent values having the same attribute name from a record parsed by the first function in this table.
*RecordAbortQuery: Stop subsequent retrieval of values having the same attribute name from within the opaque object.

CSSM_DB_PARSING_MODULE_INFO

This structure aggregates the persistent subservice ID of a default parsing module with the record type that it parses. A parsing module can parse multiple record types. The same ID would be repeated with each record type parsed by the module.

typedef struct cssm_db_parsing_module_info {
    CSSM_DB_RECORDTYPE  RecordType;
    CSSM_SUBSERVICE_UID   ModuleSubserviceUid;
} CSSM_DB_PARSING_MODULE_INFO, *CSSM_DB_PARSING_MODULE_INFO_PTR;

Definition

RecordType: The type of record parsed by the module specified by GUID.
ModuleSubserviceUid: A persistent subservice ID identifying the default parsing module for the specified record type.

CSSM_DB_INDEX_TYPE

This enumerated list defines two types of indexes: indexes with unique values (that is, primary database keys) and indexes with non-unique values. These values are used when creating a new data store and defining the schema for that data store.

typedef enum cssm_db_index_type {
    CSSM_DB_INDEX_UNIQUE = 0,
    CSSM_DB_INDEX_NONUNIQUE = 1
} CSSM_DB_INDEX_TYPE;

CSSM_DB_INDEXED_DATA_LOCATION

This enumerated list defines where within a record the indexed data values reside. Indexes can be constructed on attributes or on fields within the opaque object in the record. However, the logical location of the index value between these two categories may be unknown by the user of this enum.

typedef enum cssm_db_index_data_location {
    CSSM_DB_INDEX_ON_UNKNOWN = 0,
    CSSM_DB_INDEX_ON_ATTRIBUTE = 1,
    CSSM_DB_INDEX_ON_RECORD = 2
} CSSM_DB_INDEX_DATA_LOCATION;

CSSM_DB_INDEX_INFO

This structure contains the meta information or schema description of an index defined on an attribute. The description includes the type of index (for example, unique key or non-unique key), the logical location of the indexed attribute in the CSSM record (for example, an attribute or a field within the opaque object in the record), and the meta information on the attribute itself.

typedef struct cssm_db_index_info {
    CSSM_DB_INDEX_TYPE IndexType;
    CSSM_DB_INDEXED_DATA_LOCATION IndexedDataLocation;
    CSSM_DB_ATTRIBUTE_INFO Info;
} CSSM_DB_INDEX_INFO, *CSSM_DB_INDEX_INFO_PTR;

Definition

IndexType: A CSSM_DB_INDEX_TYPE.
IndexedDataLocation: A CSSM_DB_INDEXED_DATA_LOCATION.
Info: The meta information description of the attribute being indexed.

CSSM_DB_UNIQUE_RECORD

This structure contains an index descriptor and a module-defined value. The index descriptor may be used by the module to enhance the performance when locating the record. The module-defined value must uniquely identify the record. For a DBMS, this may be the record data. For a PKCS #11 DL, this may be an object handle. Alternately, the DL may have a module-specific scheme for identifying data which has been inserted or retrieved.

typedef struct cssm_db_unique_record {
    CSSM_DB_INDEX_INFO RecordLocator;
    CSSM_DATA RecordIdentifier;
} CSSM_DB_UNIQUE_RECORD, *CSSM_DB_UNIQUE_RECORD_PTR;

Definition

RecordLocator: The information describing how to locate the record efficiently.
RecordIdentifier: A module-specific identifier which will allow the DL to locate this record.

CSSM_DB_RECORD_INDEX_INFO

This structure contains the meta information or schema description of the set of indexes defined on a single record type. The description includes the type of the record, the number of indexes and the meta information describing each index. The data store creator can specify an index over a CSSM pre-defined attribute. When no index has been defined, the DL module has the option to add an index over a CSSM pre-defined attribute or any other attribute defined by the data store creator.

typedef struct cssm_db_record_index_info {
    CSSM_DB_RECORDTYPE DataRecordType;
    uint32 NumberOfIndexes;
    CSSM_DB_INDEX_INFO_PTR IndexInfo;
} CSSM_DB_RECORD_INDEX_INFO, *CSSM_DB_RECORD_INDEX_INFO_PTR;

Definition

DataRecordType: A CSSM_DB_RECORDTYPE.
NumberOfIndexes: The number of indexes defined on the records of the given type.
IndexInfo: An array containing a description of each index defined over the specified record type.

CSSM_DB_ACCESS_TYPE

This bitmask describes a user's desired level of access to a data store.

typedef uint32 CSSM_DB_ACCESS_TYPE, *CSSM_DB_ACCESS_TYPE_PTR;

#define CSSM_DB_ACCESS_READ         0x00001
#define CSSM_DB_ACCESS_WRITE        0x00002
#define CSSM_DB_ACCESS_PRIVILEGED   0x00004
                                        /* versus user mode */
#define CSSM_DB_ACCESS_ASYNCHRONOUS 0x00008
                                        /* versus synchronous */

Definition

ReadAccess: A boolean indicating that the user requests read access.
WriteAccess: A boolean indicating that the user requests write access.
PrivilegedMode: A boolean indicating that the user requests privileged operations, such as modifying data store access rights.
Asynchronous: A boolean indicating that the user requests asynchronous access.

CSSM_DBINFO

This structure contains the meta-information about an entire data store. The description includes the types of records stored in the data store, the attribute schema for each record type, the index schema for all indexes over records in the data store, the type of authentication mechanism used to gain access to the data store, and other miscellaneous information used by the DL module to manage the data store in a secure manner.

typedef struct cssm_dbinfo {
/* meta information about each record type in this data store
including meta information about record attributes and indexes */
    uint32 NumberOfRecordTypes;
    CSSM_DB_PARSING_MODULE_INFO_PTR DefaultParsingModules;
    CSSM_DB_RECORD_ATTRIBUTE_INFO_PTR RecordAttributeNames;
    CSSM_DB_RECORD_INDEX_INFO_PTR RecordIndexes;

  /* access restrictions for opening this data store */
    CSSM_USER_AUTHENTICATION_MECHANISM AuthenticationMechanism;

  /* transparent integrity checking options for this data store */
    CSSM_BOOL RecordSigningImplemented;
    CSSM_DATA SigningCertificate;
    CSSM_SUBSERVICE_UID SigningCspSubserviceUid;

    /* additional information */
    CSSM_BOOL IsLocal;
    char *AccessPath;           /* URL, dir path, etc. */
    void *Reserved;
} CSSM_DBINFO, *CSSM_DBINFO_PTR;

Definition

NumberOfRecordTypes: The number of distinct record types stored in this data store.
DefaultParsingModules: A pointer to a list of (record-type, GUID) pairs which define the default parsing module for each record type.
RecordAttributeNames: The meta (schema) information about the attributes associated with each record type that can be stored in this data store.
RecordIndexes: The meta (schema) information about the indexes that are defined over each of the record types that can be stored in this data store.
AuthenticationMechanism: Defines the authentication mechanism required when accessing this data store.
RecordSigningImplemented: A flag indicating whether or not the DL module provides record integrity service based on digital signaturing of the data store records.
SigningCertificate: The certificate used to sign data store records when the transparent record integrity option is in effect.
SigningCspSubserviceUid: The persistent service ID for the cryptographic service provider to be used to sign data store records when the transparent record integrity option is in effect.
IsLocal: Indicates whether the physical data store is local.
AccessPath: A character string describing the access path to the data store, such as an URL, a file system path name, a remote directory service name, and so on.
Reserved: Reserved for future use.

CSSM_DB_OPERATOR

These are the logical operators which can be used when specifying a selection predicate.

typedef enum cssm_db_operator {
    CSSM_DB_EQUAL = 0,
    CSSM_DB_NOT_EQUAL = 1,
    CSSM_DB_APPROX_EQUAL = 2,
    CSSM_DB_LESS_THAN = 3,
    CSSM_DB_GREATER_THAN = 4,
    CSSM_DB_EQUALS_INITIAL_SUBSTRING = 5,
    CSSM_DB_EQUALS_ANY_SUBSTRING = 6,
    CSSM_DB_EQUALS_FINAL_SUBSTRING = 7,
    CSSM_DB_EXISTS = 8
} CSSM_DB_OPERATOR, *CSSM_DB_OPERATOR_PTR;

CSSM_DB_CONJUNCTIVE

These are the conjunctive operations which can be used when specifying a selection criterion.

typedef enum cssm_db_conjunctive{
    CSSM_DB_NONE = 0,
    CSSM_DB_AND = 1,
    CSSM_DB_OR = 2
} CSSM_DB_CONJUNCTIVE, *CSSM_DB_CONJUNCTIVE_PTR;

CSSM_SELECTION_PREDICATE

This structure defines the selection predicate to be used for data store queries.

typedef struct cssm_selection_predicate {
    CSSM_DB_OPERATOR DbOperator;
    CSSM_DB_ATTRIBUTE_DATA Attribute;
} CSSM_SELECTION_PREDICATE, *CSSM_SELECTION_PREDICATE_PTR;

Definition

DbOperator: The relational operator to be used when comparing a value to the values stored in the specified attribute in the data store.
Attribute: The meta information about the attribute to be searched and the attribute value to be used for comparison with values in the data store.

CSSM_QUERY_LIMITS

This structure defines the time and space limits a caller can set to control early termination of the execution of a data store query. The constant values CSSM_QUERY_TIMELIMIT_NONE and CSM_QUERY_SIZELIMIT_NONE should be used to specify no limit on the resources used in processing the query. These limits are advisory. Not all data storage library modules recognize and act upon the query limits set by a caller.

#define CSSM_QUERY_TIMELIMIT_NONE 0
#define CSSM_QUERY_SIZELIMIT_NONE 0

typedef struct cssm_query_limits {
    uint32 TimeLimit;     /* in seconds */
    uint32 SizeLimit;     /* max. number of records to return */
} CSSM_QUERY_LIMITS, *CSSM_QUERY_LIMITS_PTR;

Definition

TimeLimit: Defines the maximum number of seconds of resource time that should be expended performing a query operation. The constant value CSSM_QUERY_TIMELIMIT_NONE means no time limit is specified.
SizeLimit: Defines the maximum number of records that should be retrieved in response to a single query. The constant value CSSM_QUERY_SIZELIMIT_NONE means no space limit is specified.

CSSM_QUERY_FLAGS

These flags may be used by the application to request query-related operation, such as the format of the returned data.

typedef uint32 CSSM_QUERY_FLAGS

#define CSSM_QUERY_RETURN_DATA  0x1
                   /* On  = Return the data record
                   Off = Return a reference to the data record */

CSSM_QUERY

This structure holds a complete specification of a query to select records from a data store.

typedef struct cssm_query {
    CSSM_DB_RECORDTYPE RecordType;
    CSSM_DB_CONJUNCTIVE Conjunctive;
    uint32 NumSelectionPredicates;
    CSSM_SELECTION_PREDICATE_PTR SelectionPredicate;
    CSSM_QUERY_LIMITS QueryLimits;
    CSSM_QUERY_FLAGS QueryFlags;
} CSSM_QUERY, *CSSM_QUERY_PTR;

Definition

RecordType: Specifies the type of record to be retrieved from the data store.
Conjunctive: The conjunctive operator to be used in constructing the selection predicate for the query.
NumSelectionPredicates: The number of selection predicates to be connected by the specified conjunctive operator to form the query.
SelectionPredicate: The list of selection predicates to be combined by the conjunctive operator to form the data store query.
QueryLimits: Defines the time and space limits for processing the selection query. The constant values CSSM_QUERY_TIMELIMIT_NONE and CSM_QUERY_SIZELIMIT_NONE should be used to specify no limit on the resources used in processing the query.
QueryFlags: Query-related requests from the application.

CSSM_DLTYPE

This enumerated list defines the types of underlying data management systems that can be used by the DL module to provide services. It is the option of the DL module to disclose this information. It is anticipated that other underlying data servers will be added to this list over time.

typedef enum cssm_dltype {
    CSSM_DL_UNKNOWN = 0,
    CSSM_DL_CUSTOM = 1,
    CSSM_DL_LDAP = 2,
    CSSM_DL_ODBC = 3,
    CSSM_DL_PKCS11 = 4,
    CSSM_DL_FFS = 5, /* flat file system  or fast file system */
    CSSM_DL_MEMORY = 6,
    CSSM_DL_REMOTEDIR = 7
} CSSM_DLTYPE;

CSSM_DL_PKCS11_ATTRIBUTES

Each type of DL module can define it own set of type-specific attributes. This structure contains the attributes that are specific to a PKCS#11 compliant data storage device.

typedef void *CSSM_DL_CUSTOM_ATTRIBUTES;
typedef void *CSSM_DL_LDAP_ATTRIBUTES;
typedef void *CSSM_DL_ODBC_ATTRIBUTES;
typedef void *CSSM_DL_FFS_ATTRIBUTES;

typedef struct cssm_dl_pkcs11_attributes {
    uint32 DeviceAccessFlags;
} *CSSM_DL_PKCS11_ATTRIBUTE, *CSSM_DL_PKCS11_ATTRIBUTE_PTR;

Definition

DeviceAccessFlags: Specifies the PKCS#11-specific access modes applicable for accessing persistent objects in a PKCS#11 data store.

CSSM_DB_DATASTORES_UNKNOWN

Not all DL modules can maintain a summary of managed data stores. In this case, the DL module reports its number of data stores as CSSM_DB_DATASTORES_UNKNOWN. Data stores can (and probably do) exist, but the DL module cannot provide a list of them.

#define CSSM_DB_DATASTORES_UNKNOWN (0xFFFFFFFF)

CSSM_DL_WRAPPEDPRODUCT_INFO

This structure holds product information about all backend data store services used by the DL module. The DL module vendor is not required to provide this information, but may choose to do so. For example, a DL module that uses a commercial database management system can record information about that product in this structure. Another example is a DL module that supports certificate storage through an X.500 certificate directory server. The DL module can describe the X.500 directory service in this structure.

typedef struct cssm_dl_wrappedproductinfo {
    CSSM_VERSION StandardVersion;    /* Ver of standard the
                                        product conforms to */
    CSSM_STRING StandardDescription; /* Descr of standard the
                                        product conforms to */
    CSSM_VERSION ProductVersion;     /* Version of wrapped
                                        product or library */
    CSSM_STRING StandardDescription; /* Desc of standard this
                                        product conforms to */
    CSSM_STRING ProductVendor;       /* Vendor of wrapped product
                                        or library */
    CSSM_NET_PROTOCOL NetworkProtocol;  /* The network protocol
                           supported by remote storage service */
    uint32 ProductFlags;             /* Mask of selectable DB
                      service features actually used by the DL */
} CSSM_DL_WRAPPEDPRODUCT_INFO, *CSSM_DL_WRAPPEDPRODUCT_INFO_PTR;

Definition

StandardVersion: If this product conforms to an industry standard, this is the version number of that standard.
StandardDescription: If this product conforms to an industry standard, this is a description of that standard.
ProductVersion: Version number information for the actual product version used in this version of the DL module.
ProductDescription: A string describing the product.
ProductVendor: The name of the product vendor.
NetworkProtocol: The name of the network protocol.
ProductFlags: A bit mask enumerating selectable features of the data base service that the DL module uses in its implementation.

CSSM_NAME_LIST

The CSSM_NAME_LIST structure is used to return the logical names of the data stores that a DL module can access.

typedef struct cssm_name_list {
    uint32 NumStrings;
    char** String;
} CSSM_NAME_LIST, *CSSM_NAME_LIST_PTR;

Definition

NumStrings: Number of strings in the array pointed to by String.
String: A pointer to an array of strings.

CSSM_DLSUBSERVICE

This structure contains the static information that describes a data storage library sub-service. This information is securely stored in the CSSM registry when the DL module is installed with CSSM. A data storage library module may implement multiple types of services and organize them as sub-services. For example, a DL module supporting two types of remote directory services may organize its implementation into two sub-services, one for an X.509 certificate directory and a second for custom enterprise policy data store. Most data storage library modules will implement exactly one sub-service.

#define CSSM_DB_DATASTORES_UNKNOWN (-1)

The descriptive information stored in these structures can be queried using the function CSSM_GetModuleInfo() and specifying the data storage library module GUID.

typedef struct cssm_dlsubservice {
    uint32 SubServiceId;
    CSSM_STRING Description;
    CSSM_DLTYPE Type;
    union cssm_dlsubservice_attributes {
        CSSM_DL_CUSTOM_ATTRIBUTES CustomAttributes;
        CSSM_DL_LDAP_ATTRIBUTES LdapAttributes;
        CSSM_DL_ODBC_ATTRIBUTES OdbcAttributes;
        CSSM_DL_PKCS11_ATTRIBUTES Pkcs11Attributes;
        CSSM_DL_FFS_ATTRIBUTES FfsAttributes;
    } Attributes;
    CSSM_DL_WRAPPEDPRODUCT_INFO WrappedProduct;
    CSSM_USER_AUTHENTICATION_MECHANISM AuthenticationMechanism;

    /* meta information about the query support */
    /* provided by the module */
    uint32 NumberOfRelOperatorTypes;
    CSSM_DB_OPERATOR_PTR RelOperatorTypes;
    uint32 NumberOfConjOperatorTypes;
    CSSM_DB_CONJUNCTIVE_PTR ConjOperatorTypes;
    CSSM_BOOL QueryLimitsSupported;

    /* meta information about the encapsulated */
    /* data stores (if known) */
    sint32 NumberOfDataStores;
    CSSM_NAME_LIST_PTR DataStoreNames;
    CSSM_DBINFO_PTR DataStoreInfo;

    /* additional information */
    void *Reserved;
} CSSM_DLSUBSERVICE, *CSSM_DLSUBSERVICE_PTR;

Definition

SubServiceId: A unique, identifying number for the sub-service described in this structure.
Description: A string containing a description name or title for this sub-service.
Type: An identifier for the type of underlying data store the DL module uses to provide persistent storage.
Attributes: A structure containing attributes that define additional parameter values specific to the DL module type.
WrappedProduct: Descriptions of the backend data store services used by this module.
AuthenticationMechanism: Defines the authentication mechanism required when using this DL module. This authentication mechanism is distinct from the authentication mechanism (specified in a DBInfo structure) required to access a specific data store.
NumberOfRelOperatorTypes: The number of distinct relational operator the DL module accepts in selection queries for retrieving records from its managed data stores.
RelOperatorTypes: The list of specific relational operators that can be used to formulate selection predicates for queries on a data store. The list contains NumberOfRelOperatorTypes operators.
NumberOfConjOperatorTypes: The number of distinct conjunctive operator the DL module accepts in selection queries for retrieving records from its managed data stores.
ConjOperatorTypes: A list of specific conjunctive operators that can be used to formulate selection predicates for queries on a data store. The list contains NumberOfConjOperatorTypes operators.
QueryLimitsSupported: A boolean indicating whether query limits are effective when the DL module executes a query.
NumberOfDataStores: The number of data stores managed by the DL module. This information may not be known by the DL module, in which case this value will equal CSSM_DB_DATASTORES_UNKNOWN.
DataStoreNames: A list of names of the data stores managed by the DL module. This information may not be known by the DL module and hence may not be available. The list contains NumberOfDataStores entries.
DataStoreInfo: A list of pointers to information about each data store managed by the DL module. This information may not be known in advance by the DL module and hence may not be available through this structure. The list contains NumberOfDataStores entries.
Reserved: Reserved for future use.

Data Storage Library Operations

The manpages for Data Storage Library Operations can be found at the end of this chapter.

Data Store Operations

The manpages for Data Store Operations can be found at the end of this chapter.

Data Record Operations

The manpages for Data Record Operations can be found at the end of this chapter.

Extensibility Functions

The manpages for Extensibility Functions can be found at the end of this chapter.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.
You should also read the legal notice explaining the terms and conditions relating to the CDSA documentation.

Contents

Next section

Index