Common Security: CDSA and CSSM - Data Storage Library Services API

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

Data Storage Library Services API

Overview

The primary purpose of a data storage library (DL) module is to provide persistent storage of security-related objects including certificates, certificate revocation lists (CRLs), keys, and policy objects. A DL module is responsible for the creation and accessibility of one or more data stores. A single DL module can be tightly tied to a CL and/or TP module, or can be independent of all other module types. A single data store can contain a single object type in one format, a single object type in multiple formats, or multiple object types. The persistent repository can be local or remote.

CSSM stores and manages meta-information about a DL in the CSSM registry. This information describes the storage and retrieval capabilities of a DL. Applications can query the CSSM registry to obtain information about the available DLs and attach to a DL that provides the needed services. Some DL services can acquire and store meta-information about each of the data stores it manages. When this information is available it is stored in the CSSM registry. Not all DL service providers can supply this information.

The DL APIs define a data storage model that can be implemented using a custom storage device, a traditional local or remote file system service, a database management system package, or a complete (local or remote) information management system. The abstract data model defined by the DL APIs partitions all values stored in a data record into two categories: one or more mutable attributes and one opaque data object. The attribute values can be directly manipulated by the application and the DL module. Values stored within the opaque data object must be accessed using parsing functions. A DL module that stores certificates can, but should not, interpret the format of those certificates. A set of parsing functions such as those defined in a certificate library module can be used to parse the opaque certificate object. The DL module defines a default set of parsing functions. An application can define a CSSM module to be used for parsing or can define its own set of parsing functions to be used during a data storage session.

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 this attribute name.

Data Storage Data Structures

CSSM_DL_HANDLE

A unique identifier for an attached module that provide 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 storage 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 specifies 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 DL module and data store pairing in the list.
DLDBHandle: List of data library module and data store 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_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. The attribute name is of one of two formats, not both.

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 format was selected to represent the attribute name.
AttributeName: A character string representation of the attribute name.
AttributeID: An 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 System Administrator App
Application/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	System Administrator App Application/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. The structure includes the record type, optional semantic information on how the record can and cannot be used, the number of attributes in the records, and the actual data value for each attribute.

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 CSSM_CERTRECORD_SEMANTICS. For all other records types, a bit masks of zero must be used or a set of semantically meaning masks must be defined.
NumberOfAttributes: The number of attributes in a record of the specified type.
AttributeData: A list of pointers to data values, one per attribute. 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 object stored in a record. The functions can parse the opaque objects in some or all of the distinct record types stored in the data store. Record types not supported by the data store need not be supported by the parsing functions. The DL module must designate a default parsing module for each record type stored in the data store. The default parsing module can parse multiple record types. The function CSSM_DbSetRecordParsingFunctions must be used to override the default parsing module each applicable record type.

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 a value from 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 retrievals of values having the same attribute name from within an opaque object in a CSSM record.

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 records types. The same ID would be repeated with each record type parsed by the module.

typedef 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 (such as, 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 CSSM 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 enumeration.

typedef enum cssm_db_indexed_data_location {
    CSSM_DB_INDEX_ON_UNKNOWN = 0,
    CSSM_DB_INDEX_ON_ATTRIBUTE = 1,
    CSSM_DB_INDEX_ON_RECORD = 2
} CSSM_DB_INDEXED_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 record 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 */

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.

typedef struct cssm_dbinfo {
      /* meta information about each record type stored 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 GUID-record-type pairs, defining the default parsing module for each record type.
RecordAttributeNames: The meta (schema) information about the attributes in each of the record types 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 subservice 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. All specific time values must be greater than zero, as any query requires greater than zero time to execute.
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. All specific space values must be greater than zero, as any query requires greater than zero space in which to execute.

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_DLTYPE_PTR;

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 the 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 base services used by the DL module. The DL module vendor is not required to provide this information, but may choose to do so.

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 ProductDescription; /* Description of wrapped
                                        product or library */
    CSSM_STRING ProductVendor; /* Vendor of wrapped product or
                                        library */
    CSSM_NET_PROTOCOL NetworkProtocol; /* The network protocol
                         supported by a 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 supported by a remote storage service.
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 stored in the CSSM registry when the DL module is installed with CSSM. CSSM checks the integrity of the DL module description before using the information. A data storage library module may implement multiple types of services and organize them as sub-services.

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_WRAPPEDPRODUCTINFO 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 server 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 operators 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 and hence may not be available.
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 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 Functions

The manpages for Data Storage Functions 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