Data Storage Library Services

Introduction

A DL module is responsible for the creation and accessibility of one or more data stores. The DL provides access to these data stores by translating calls from the DL interface (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.

The implementation of DL operations should be semantically free. For example, a DL operation which inserts a trusted X.509 certificate into a data store should not be responsible for verifying the trust on that certificate. The semantic interpretation of security objects should be implemented in TP services, layered services, and applications. A single DL module can be tightly tied to a Certificate library (CL) and/or Trust Policy (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.

A pass-through function is defined in the DL API. This mechanism allows each DL to provide additional functions to store and retrieve certificates, CRLs and other security-related objects. Pass-through functions may be used to increase functionality or enhance performance.

CSSM API

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 CL module can be used to parse the opaque certificate object. The DL module defines a default set of parsing functions.

DL SPI

Add-In Module

A CDSA add-in module is a dynamically-linkable library, composed of functions that implement some or all of the CSSM Module Interfaces. Add-in module functionality is partitioned into two areas:

• The provision of security services to applications

• Module administration

Add-in modules provide one or more categories of security services to applications, in this case the Data Storage Library (DL) services. Each security service contains one or more implementation instances, called sub-services. For a DL service provider, a sub-service would represent a type of persistent storage. These sub-services each support the module interface for their respective service categories.

Each module, regardless of the security services it offers, has the same set of administrative responsibilities. Every module must expose functions that allow CSSM to indicate events such as module attach and detach. In addition, as part of the attach operation, every module must be able to verify its own integrity, verify the integrity of CSSM, and register with CSSM. Detailed information about add-in module structure, administration, and interfaces can be found in Part 14 of this Technical Standard.

Operation

• 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 should provide information about the data stores that it has access to. Applications can obtain information about these data stores by using the CSSM_GetDbInfo() function. 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. The default add-in modules set by the data store creator are used for parsing.

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.

Interoperability

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. Data store access can be protected by a passphrase, which can be changed by the owner of the old passphrase. 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 Data Structures

CSSM_DL_HANDLE

typedef CSSM_MODULE_HANDLE CSSM_DL_HANDLE; /* data storage library Handle */

CSSM_DB_HANDLE

typedef CSSM_MODULE_HANDLE CSSM_DB_HANDLE; /* Data storage Handle */

CSSM_DL_DB_HANDLE

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

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

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_AS_INTEGER = 2,
} CSSM_DB_ATTRIBUTE_NAME_FORMAT, *CSSM_DB_ATTRIBUTE_NAME_FORMAT_PTR;

CSSM_DB_ATTRIBUTE_FORMAT

It is important to note that the value returned from a database might not have the same binary value as the value inserted into the database. The value returned is only guaranteed to have the same value in the context of its attribute format. For instance, strings may acquire or loose NULL termination or the size of integers may change.

typedef enum cssm_db_attribute_format {
    CSSM_DB_ATTRIBUTE_FORMAT_STRING = 0,
    CSSM_DB_ATTRIBUTE_FORMAT_SINT32 = 1,
    CSSM_DB_ATTRIBUTE_FORMAT_UINT32 = 2,
    CSSM_DB_ATTRIBUTE_FORMAT_BIG_NUM = 3,
    CSSM_DB_ATTRIBUTE_FORMAT_REAL = 4,
    CSSM_DB_ATTRIBUTE_FORMAT_TIME_DATE = 5,
    CSSM_DB_ATTRIBUTE_FORMAT_BLOB = 6,
    CSSM_DB_ATTRIBUTE_FORMAT_MULTI_UINT32 = 7,
    CSSM_DB_ATTRIBUTE_FORMAT_COMPLEX = 8
} CSSM_DB_ATTRIBUTE_FORMAT, *CSSM_DB_ATTRIBUTE_FORMAT_PTR;

Definitions

STRING

A string containing only printable characters, NULL terminator is optional. Greater than and less than operations are performed by comparing the binary value of each character (strcmp). The character format is platform specific.

SINT32

A signed, 32-bit integer. Endian-ness is platform specific. 8-bit and 16-bit integers are converted to 32-bit integers with sign extension. All other sized integers are invalid.

UINT32

An unsigned, 32-bit integer. Endian-ness is platform specific. 8-bit and 16-bit integers are converted to 32-bit integers without sign extension. All other sized integers are invalid.

BIG_NUM

This is a sign-magnitude little-endian integer of arbitrary size. The first bit represents the sign of the number (0 == positive, 1 == negative, zero is non-deterministic), all other bits represent the magnitude. Padding zeros are allowed.

REAL

A double precision IEEE floating point number (size = 8 bytes). Single precision IEEE floating point numbers (size = 4 bytes) are interpolated to doubles. Not a number (NaN) is not a valid input.

TIME_DATE

A representation of generalized time: A NULL terminated ASCII string representation of Zulu Time and Data of size 16 character and following the format: "YYYYMMDDhhmmssZ"

BLOB

An opaque block of data. Greater than and less than operations are preformed by comparing the binary value of each byte.

MULTI_UINT32

An array of uint32s. The length of this structure must be a multiple of four. Greater than and less than operations are performed by comparing the binary value of each uint32.

COMPLEX

A non-standard or complex structure. The type is further defined by the attribute's name. (for example, if AttributeName = APP_DOMAIN_STRUCTURED_NAME, then the implied type is a application-defined structure containing a name). Use of this type is not recommended.

CSSM_DB_ATTRIBUTE_INFO

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 AttributeOID;        /* e.g., CSSMOID_RECORDLABEL */
        uint32 AttributeID;
    } Label;
    CSSM_DB_ATTRIBUTE_FORMAT AttributeFormat;
} CSSM_DB_ATTRIBUTE_INFO, *CSSM_DB_ATTRIBUTE_INFO_PTR;

Definition

AttributeNameFormat

Indicates which of the defined formats was selected to represent the attribute name.

Label

A character string representation of the attribute name. or an OID representation of the attribute name as indicated by the value of AttributeNameFormat.

• 
  A character string representation of the attribute name.

• 
  An OID representation of the attribute name.

• 
  An integer 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

typedef struct cssm_db_attribute_data {
    CSSM_DB_ATTRIBUTE_INFO Info;
    uint32 NumberOfValues;
    CSSM_DATA_PTR 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.

NumberOfValues

An integer value indicating the number of individual values contained in Value. If Value is a multi-valued attribute, this value can be greater than one. For single-valued attributes, this integer must be 1.

Value

The data-present value(s) assigned to the attribute.

CSSM_DB_RECORDTYPE

• Record types for schema management

• Record types recognized and documented in this specification for application use

• Record types defined independently by the industry at large for application use

All record types defined in this specification are defined in the Schema Management name space and the Open Group name space.

typedef uint32 CSSM_DB_RECORDTYPE;

/* Schema Management Name Space Range Definition*/
#define CSSM_DB_RECORDTYPE_SCHEMA_START          (0x00000000)
#define CSSM_DB_RECORDTYPE_SCHEMA_END
(CSSM_DB_RECORDTYPE_SCHEMA_START + 4)

/* Open Group Application Name Space Range Definition*/
#define CSSM_DB_RECORDTYPE_OPEN_GROUP_START      (0x0000000A)
#define CSSM_DB_RECORDTYPE_OPEN_GROUP_END
(CSSM_DB_RECORDTYPE_OPEN_GROUP_START + 8)

/* Industry At Large Application Name Space Range Definition */
#define CSSM_DB_RECORDTYPE_APP_DEFINED_START     (0x80000000)
#define CSSM_DB_RECORDTYPE_APP_DEFINED_END       (0xffffffff)

/* Record Types defined in the Schema Management Name Space */
#define CSSM_DL_DB_SCHEMA_INFO
(CSSM_DB_RECORDTYPE_SCHEMA_START + 0)
#define CSSM_DL_DB_SCHEMA_INDEXES
(CSSM_DB_RECORDTYPE_SCHEMA_START + 1)
#define CSSM_DL_DB_SCHEMA_ATTRIBUTES
(CSSM_DB_RECORDTYPE_SCHEMA_START + 2)
#define CSSM_DL_DB_SCHEMA_PARSING_MODULE
(CSSM_DB_RECORDTYPE_SCHEMA_START + 3)

/* Record Types defined in the Open Group Application Name Space */
#define CSSM_DL_DB_RECORD_ANY
        (CSSM_DB_RECORDTYPE_OPEN_GROUP_START + 0)
#define CSSM_DL_DB_RECORD_CERT
        (CSSM_DB_RECORDTYPE_OPEN_GROUP_START + 1)
#define CSSM_DL_DB_RECORD_CRL
        (CSSM_DB_RECORDTYPE_OPEN_GROUP_START + 2)
#define CSSM_DL_DB_RECORD_POLICY
        (CSSM_DB_RECORDTYPE_OPEN_GROUP_START + 3)
#define CSSM_DL_DB_RECORD_GENERIC
        (CSSM_DB_RECORDTYPE_OPEN_GROUP_START +4)
#define CSSM_DL_DB_RECORD_PUBLIC_KEY
        (CSSM_DB_RECORDTYPE_OPEN_GROUP_START + 5)
#define CSSM_DL_DB_RECORD_PRIVATE_KEY
        (CSSM_DB_RECORDTYPE_OPEN_GROUP_START + 6)
#define CSSM_DL_DB_RECORD_SYMMETRIC_KEY
        (CSSM_DB_RECORDTYPE_OPEN_GROUP_START + 7)
#define CSSM_DL_DB_RECORD_ALL_KEYS
        (CSSM_DB_RECORDTYPE_OPEN_GROUP_START + 8)

Definitions for Schema Management Record Types

The schema relations can be queried by users and applications, but cannot be modified by users or applications.

CSSM_DL_DB_SCHEMA_ATTRIBUTES is a relation containing one record for each attribute defined for the database. All fields are searchable. The starred(*) fields form the primary database key for this relation.

CSSM_DL_DB_SCHEMA_INDEXES is a relation containing one record for each index defined for the database. All fields are searchable. The starred(*) fields form the primary database key for this relation.

CSSM_DL_DB_SCHEMA_PARSING_MODULE is a relation containing one record for each attribute in a relation in the database for attributes using parsing modules. All fields are searchable. The starred(*) fields form the primary database key for this relation. If no parsing modules are defined for an attribute, then no entry will be found in the table.

Definitions for Open Group Application Record Types

Schema for DL Records of Type CSSM_DL_DB_RECORD_CERT

Schema for DL Records of Type CSSM_DL_DB_RECORD_CRL

Schema for DL Records of Type CSSM_DL_DB_RECORD_POLICY

Schema for DL Records of Type CSSM_DL_DB_RECORD_GENERIC

Schema for DL Records of Type KEY

CSSM_DB_CERTRECORD_SEMANTICS

#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:

CSSM_DB_RECORD_ATTRIBUTE_INFO

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

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_PARSING_MODULE_INFO

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. If no parsing module is specified for this RecordType, then the ModuleSubserviceUid must be zero.

CSSM_DB_INDEX_TYPE

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

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

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 set of one or more attributes that form the index.

CSSM_DB_UNIQUE_RECORD

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

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

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

CSSM_DB_MODIFY_MODE

typedef uint32 CSSM_DB_MODIFY_MODE;

#define CSSM_DB_MODIFY_ATTRIBUTE_NONE (0)
#define CSSM_DB_MODIFY_ATTRIBUTE_ADD
    (CSSM_DB_MODIFY_ATTRIBUTE_NONE + 1) 
#define CSSM_DB_MODIFY_ATTRIBUTE_DELETE
    (CSSM_DB_MODIFY_ATTRIBUTE_NONE + 2)  
#define CSSM_DB_MODIFY_ATTRIBUTE_REPLACE
    (CSSM_DB_MODIFY_ATTRIBUTE_NONE + 3)

CSSM_DBINFO

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

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

typedef enum cssm_db_operator {
    CSSM_DB_EQUAL = 0,
    CSSM_DB_NOT_EQUAL = 1,
    CSSM_DB_LESS_THAN = 2,
    CSSM_DB_GREATER_THAN = 3,
    CSSM_DB_CONTAINS = 4,
    CSSM_DB_CONTAINS_INITIAL_SUBSTRING = 5,
    CSSM_DB_CONTAINS_FINAL_SUBSTRING = 6
} CSSM_DB_OPERATOR, *CSSM_DB_OPERATOR_PTR;

Some logical operator can only be applied to selected attribute types. The table below defines the valid attribute types for each logical operator.

CSSM_DB_CONJUNCTIVE

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

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

#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

typedef uint32 CSSM_QUERY_FLAGS;

#define CSSM_QUERY_RETURN_DATA (0x01)

CSSM_QUERY

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

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 */
    CSSM_DL_MEMORY = 6,
    CSSM_DL_REMOTEDIR = 7
} CSSM_DLTYPE, *CSSM_DLTYPE_PTR;

CSSM_DL_PKCS11_ATTRIBUTES

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

#define CSSM_DB_DATASTORES_UNKNOWN (0xFFFFFFFF)

CSSM_NAME_LIST

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_DB_RETRIEVAL_MODES

• Transactional
  All query results are determined at initial query evaluation. Results do not change during an incremental retrieval process.

• File System Scan
  Query results are selected during the incremental retrieval process. Records matching the query may be added to or deleted from the underlying data store during the iterative retrieval. The caller may receive the new matching records and not receive the deleted records.

typedef uint32 CSSM_DB_RETRIEVAL_MODES;

#define CSSM_DB_TRANSACTIONAL_MODE (0)
#define CSSM_DB_FILESYSTEMSCAN_MODE (1)

CSSM_DB_SCHEMA_ATTRIBUTE_INFO

typedef struct cssm_db_schema_attribute_info {
    uint32 AttributeId;
    char *AttributeName;
    CSSM_OID AttributeNameID; 
    CSSM_DB_ATTRIBUTE_FORMAT DataType;
} CSSM_DB_SCHEMA_ATTRIBUTE_INFO, *CSSM_DB_SCHEMA_ATTRIBUTE_INFO_PTR;

CSSM_DB_SCHEMA_INDEX_INFO

typedef struct cssm_db_schema_index_info {
    uint32 AttributeId;
    uint32 IndexId;
    CSSM_DB_INDEX_TYPE IndexType;
    CSSM_DB_INDEXED_DATA_LOCATION IndexedDataLocation;
} CSSM_DB_SCHEMA_INDEX_INFO, *CSSM_DB_SCHEMA_INDEX_INFO_PTR; 

Error Codes and Error Values

The Error Values that can be returned by DL functions can be either derived from the Common Error Codes defined in CSSM Error Handling, or from a Common set that more than one DL function can return, or they are specific to the DL function.

The DL functions defined in this section list all the DL Error Values in the Common set, plus any Error Values that are specific to the function.

DL Error Values Derived from Common Error Codes

#define CSSMERR_DL_INTERNAL_ERROR \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INTERNAL_ERROR)		
#define CSSMERR_DL_MEMORY_ERROR  \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_MEMORY_ERROR)			
#define CSSMERR_DL_MDS_ERROR  \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_MDS_ERROR)			
#define CSSMERR_DL_INVALID_POINTER  \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_POINTER)			
#define CSSMERR_DL_INVALID_INPUT_POINTER  \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_INPUT_POINTER)			
#define CSSMERR_DL_INVALID_OUTPUT_POINTER  \ 
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_OUTPUT_POINTER)
#define CSSMERR_DL_FUNCTION_NOT_IMPLEMENTED  \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_FUNCTION_NOT_IMPLEMENTED)
#define CSSMERR_DL_SELF_CHECK_FAILED  \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_SELF_CHECK_FAILED)			
#define CSSMERR_DL_OS_ACCESS_DENIED  \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OS_ACCESS_DENIED)			
#define CSSMERR_DL_FUNCTION_FAILED  \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_FUNCTION_FAILED)
#define CSSMERR_DL_INVALID_DL_HANDLE \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_DL_HANDLE)

DL Error Values Derived from ACL-based Error Codes

#define CSSMERR_DL_OPERATION_AUTH_DENIED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OPERATION_AUTH_DENIED)	
#define CSSMERR_DL_OBJECT_USE_AUTH_DENIED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OBJECT_USE_AUTH_DENIED)
#define CSSMERR_DL_OBJECT_MANIP_AUTH_DENIED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OBJECT_MANIP_AUTH_DENIED)
#define CSSMERR_DL_OBJECT_ACL_NOT_SUPPORTED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OBJECT_ACL_NOT_SUPPORTED)
#define CSSMERR_DL_OBJECT_ACL_REQUIRED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OBJECT_ACL_REQUIRED)
#define CSSMERR_DL_INVALID_ACCESS_CREDENTIALS \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACCESS_CREDENTIALS)
#define CSSMERR_DL_INVALID_ACL_BASE_CERTS \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_BASE_CERTS)
#define CSSMERR_DL_ACL_BASE_CERTS_NOT_SUPPORTED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_BASE_CERTS_NOT_SUPPORTED)
#define CSSMERR_DL_INVALID_SAMPLE_VALUE \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_SAMPLE_VALUE)
#define CSSMERR_DL_SAMPLE_VALUE_NOT_SUPPORTED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_SAMPLE_VALUE_NOT_SUPPORTED)
#define CSSMERR_DL_INVALID_ACL_SUBJECT_VALUE \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_SUBJECT_VALUE)
#define CSSMERR_DL_ACL_SUBJECT_TYPE_NOT_SUPPORTED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_SUBJECT_TYPE_NOT_SUPPORTED)
#define CSSMERR_DL_INVALID_ACL_CHALLENGE_CALLBACK \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_CHALLENGE_CALLBACK)
#define CSSMERR_DL_ACL_CHALLENGE_CALLBACK_FAILED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_CHALLENGE_CALLBACK_FAILED)
#define CSSMERR_DL_INVALID_ACL_ENTRY_TAG \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_ENTRY_TAG)
#define CSSMERR_DL_ACL_ENTRY_TAG_NOT_FOUND \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_ENTRY_TAG_NOT_FOUND)
#define CSSMERR_DL_INVALID_ACL_EDIT_MODE \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_EDIT_MODE)
#define CSSMERR_DL_ACL_CHANGE_FAILED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_CHANGE_FAILED)
#define CSSMERR_DL_INVALID_NEW_ACL_ENTRY \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_NEW_ACL_ENTRY)
#define CSSMERR_DL_INVALID_NEW_ACL_OWNER \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_NEW_ACL_OWNER)
#define CSSMERR_DL_ACL_DELETE_FAILED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_DELETE_FAILED)
#define CSSMERR_DL_ACL_REPLACE_FAILED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_REPLACE_FAILED)
#define CSSMERR_DL_ACL_ADD_FAILED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_ADD_FAILED)

DL Error Values for Specific Data Types

#define CSSMERR_DL_INVALID_DB_HANDLE \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_DB_HANDLE)
#define CSSMERR_DL_INVALID_PASSTHROUGH_ID \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_PASSTHROUGH_ID)
#define CSSMERR_DL_INVALID_NETWORK_ADDR \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_NETWORK_ADDR)

General DL Error Values

#define CSSM_DL_BASE_DL_ERROR \
    (CSSM_DL_BASE_ERROR+CSSM_ERRORCODE_COMMON_EXTENT)

#define CSSMERR_DL_DATABASE_CORRUPT (CSSM_DL_BASE_DL_ERROR+1)

DL Specific Error Values

#define CSSMERR_DL_INVALID_RECORD_INDEX	(CSSM_DL_BASE_DL_ERROR+8)

#define CSSMERR_DL_INVALID_RECORDTYPE (CSSM_DL_BASE_DL_ERROR+9)

#define CSSMERR_DL_INVALID_FIELD_NAME (CSSM_DL_BASE_DL_ERROR+10)

#define CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT (CSSM_DL_BASE_DL_ERROR+11)

#define CSSMERR_DL_UNSUPPORTED_INDEX_INFO (CSSM_DL_BASE_DL_ERROR+12)

#define CSSMERR_DL_UNSUPPORTED_LOCALITY	(CSSM_DL_BASE_DL_ERROR+13)

#define CSSMERR_DL_UNSUPPORTED_NUM_ATTRIBUTES (CSSM_DL_BASE_DL_ERROR+14)

#define CSSMERR_DL_UNSUPPORTED_NUM_INDEXES (CSSM_DL_BASE_DL_ERROR+15)

#define CSSMERR_DL_UNSUPPORTED_NUM_RECORDTYPES (CSSM_DL_BASE_DL_ERROR+16)

#define CSSMERR_DL_UNSUPPORTED_RECORDTYPE (CSSM_DL_BASE_DL_ERROR+17)

#define CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE (CSSM_DL_BASE_DL_ERROR+18)

#define CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT (CSSM_DL_BASE_DL_ERROR+19)

#define CSSMERR_DL_INVALID_PARSING_MODULE (CSSM_DL_BASE_DL_ERROR+20)

#define CSSMERR_DL_INVALID_DB_NAME (CSSM_DL_BASE_DL_ERROR+22)

#define CSSMERR_DL_DATASTORE_DOESNOT_EXIST (CSSM_DL_BASE_DL_ERROR+23)

#define CSSMERR_DL_DATASTORE_ALREADY_EXISTS (CSSM_DL_BASE_DL_ERROR+24)

#define CSSMERR_DL_DB_LOCKED (CSSM_DL_BASE_DL_ERROR+25)

#define CSSMERR_DL_DATASTORE_IS_OPEN (CSSM_DL_BASE_DL_ERROR+26)

#define CSSMERR_DL_RECORD_NOT_FOUND (CSSM_DL_BASE_DL_ERROR+27)

#define CSSMERR_DL_MISSING_VALUE (CSSM_DL_BASE_DL_ERROR+28)

#define CSSMERR_DL_UNSUPPORTED_QUERY (CSSM_DL_BASE_DL_ERROR+29)

#define CSSMERR_DL_UNSUPPORTED_QUERY_LIMITS (CSSM_DL_BASE_DL_ERROR+30)

#define CSSMERR_DL_UNSUPPORTED_NUM_SELECTION_PREDS \
    (CSSM_DL_BASE_DL_ERROR+31)

#define CSSMERR_DL_UNSUPPORTED_OPERATOR	(CSSM_DL_BASE_DL_ERROR+33)

#define CSSMERR_DL_INVALID_RESULTS_HANDLE (CSSM_DL_BASE_DL_ERROR+34)

#define CSSMERR_DL_INVALID_DB_LOCATION (CSSM_DL_BASE_DL_ERROR+35)

#define CSSMERR_DL_INVALID_ACCESS_REQUEST (CSSM_DL_BASE_DL_ERROR+36)

#define CSSMERR_DL_INVALID_INDEX_INFO (CSSM_DL_BASE_DL_ERROR+37)

#define CSSMERR_DL_INVALID_SELECTION_TAG (CSSM_DL_BASE_DL_ERROR+38)

#define CSSMERR_DL_INVALID_NEW_OWNER (CSSM_DL_BASE_DL_ERROR+39)

#define CSSMERR_DL_INVALID_RECORD_UID (CSSM_DL_BASE_DL_ERROR+40)

#define CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA (CSSM_DL_BASE_DL_ERROR+41)

#define CSSMERR_DL_INVALID_MODIFY_MODE (CSSM_DL_BASE_DL_ERROR+42)

#define CSSMERR_DL_INVALID_OPEN_PARAMETERS (CSSM_DL_BASE_DL_ERROR+43)

#define CSSMERR_DL_RECORD_MODIFIED (CSSM_DL_BASE_DL_ERROR+44)

#define CSSMERR_DL_ENDOFDATA (CSSM_DL_BASE_DL_ERROR+45)

#define CSSMERR_DL_INVALID_QUERY (CSSM_DL_BASE_DL_ERROR+46)

#define CSSMERR_DL_INVALID_VALUE (CSSM_DL_BASE_DL_ERROR+47)

#define CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED (CSSM_DL_BASE_DL_ERROR+48)

#define CSSMERR_DL_STALE_UNIQUE_RECORD (CSSM_DL_BASE_DL_ERROR+49)

Data Storage Library Operations

NAME

CSSM_DL_Authenticate, for the CSSM API
DL_Authenticate, for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_Authenticate
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_ACCESS_TYPE AccessRequest,
    const CSSM_ACCESS_CREDENTIALS *AccessCred)

SPI:
CSSM_RETURN CSSMDLI DL_Authenticate
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_ACCESS_TYPE AccessRequest,
    const CSSM_ACCESS_CREDENTIALS *AccessCred)

DESCRIPTION

This function allows the caller to provide authentication credentials to the DL module at a time other than data store creation, deletion, open, import, and export. AccessRequest defines the type of access to be associated with the caller. If the authentication credential applies to access and use of a DL module in general, then the data store handle specified in the DLDBHandle must be NULL. When the authorization credential is to apply to a specific data store, the handle for that data store must be specified in the DLDBHandle pair.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module used to perform this function and the data store to which access is being requested. If the form of authentication being requested is authentication to the DL module in general, then the data store handle must be NULL.

AccessRequest (input)

An indicator of the requested access mode for the data store or DL module in general.

AccessCred (input)

A pointer to the set of one or more credentials being presented for authentication by the caller. The credentials can apply to the DL module in general or to a particular data store managed by this service module. The credentials required for creating new data stores is defined by the DL and recorded in a record in the MDS Primary DL relation. The required set of credentials to access a particular data store is defined by the DbInfo record containing meta-data for the specified data store.

The credentials structure can contain multiple types of credentials, as required for multi-factor authentication. The credential data can be an immediate value, such as a passphrase, PIN, certificate, or template of user-specific data, or the caller can specify a callback function the DL can use to obtain one or more credentials.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_ACCESS_REQUEST
CSSMERR_DL_INVALID_DB_HANDLE

NAME

CSSM_DL_GetDbAcl for the CSSM API
DL_GetDbAcl for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_GetDbAcl
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_STRING *SelectionTag,
    uint32 *NumberOfAclInfos,
    CSSM_ACL_ENTRY_INFO_PTR *AclInfos)

SPI:
CSSM_RETURN CSSMDLI DL_GetDbAcl
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_STRING *SelectionTag,
    uint32 *NumberOfAclInfos,
    CSSM_ACL_ENTRY_INFO_PTR *AclInfos)

DESCRIPTION

This function returns a description of zero or more ACL entries managed by the data storage service provider module and associated with the target database identified by DLDBHandle.DBHandle. The optional input SelectionTag restricts the returned descriptions to those ACL entries with a matching EntryTag value. If a SelectionTag value is specified and no matches are found, zero descriptions are returned. If no SelectionTag is specified, a description of all ACL entries associated with the target data base are returned by this function.

Each AclInfo structure contains:

• Public contents of an ACL entry

• ACL EntryHandle, which is a unique value defined and managed by the service provider

The public ACL entry information returned by this function includes:

• The subject type - A CSSM_LIST structure containing one element identifying the type of subject stored in the ACL entry.

• Delegation flag - A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded in Authorization

• Authorization array - A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which permission is granted to the Subject.

• Validity period - A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid.

• ACL entry tag - A CSSM_STRING containing a user-defined value associated with the ACL entry.

PARAMETERS

DLDBHandle (input)

The handle pair that identifies the Data Storage service provider to perform this operation and the target data store whose associated ACL entries are scanned and returned.

SelectionTag (input/optional)

A CSSM_STRING value matching the user-defined tag value associated with one or more ACL entries for the target data base. To retrieve a description of all ACL entries for the target data base, this parameter must be NULL.

NumberOfAclInfos (output)

The number of entries in the AclInfos array. If no ACL entry descriptions are returned, this value is zero.

AclInfos (output)

An array of CSSM_ACL_ENTRY_INFO structures. The unique handle contained in each structure can be used during the current attach session to reference the ACL entry for editing. The structure is allocated by the service provider and must be released by the caller when the structure is no longer needed. If no ACL entry descriptions are returned, this value is NULL.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE

SEE ALSO

For the CSSM API: CSSM_DL_ChangeDbAcl()

For the DL SPI: DL_ChangeDbAcl()

NAME

CSSM_DL_ChangeDbAcl for the CSSM API
DL_ChangeDbAcl for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_ChangeDbAcl
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const CSSM_ACL_EDIT *AclEdit)

SPI:
CSSM_RETURN CSSMDLI DL_ChangeDbAcl
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const CSSM_ACL_EDIT *AclEdit)

DESCRIPTION

This function edits the stored ACL associated with the target data base identified by DLDBHandle.DBHandle. The ACL is modified according to the edit mode and information provided in AclEdit.

The caller must be authorized to modify the target ACL. Caller authentication and authorization to edit the ACL is determined based on the caller-provided AccessCred.

The caller must be authorized to add, delete or replace the ACL entries associated with the target data base. When adding or replacing an ACL entry, the service provider must reject the creation of duplicate ACL entries.

When adding a new ACL entry to an ACL, the caller must provide a complete ACL entry prototype. All ACL entry items, except the ACL entry TypedSubject must be provided as an immediate value in AclEdit->NewEntry. The ACL entry Subject can be provided as an immediate value, from a verifier with a protected data path, from an external authentication or authorization service, or through a callback function specified in AclEdit->NewEntry->Callback.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the data storage library module to be used to perform this function, and the open data store whose associated ACL entries are to be updated.

AccessCred (input)

A pointer to the set of one or more credentials used to authenticate and validate the caller's authorization to modify the ACL associated with the target data base. Required credentials can include zero or more certificates, zero or more caller names, and one or more samples. If certificates and/or caller names are provided as input these must be provided as immediate values in this structure. The samples can be provided as immediate values or can be obtained through a callback function included in the AccessCred structure.

AclEdit (input)

A structure containing information that defines the edit operation. Valid operations include adding, replacing and deleting entries in the set of ACL entries managed by the service provider. The AclEdit can contain information for a new ACL entry and a unique handle identifying an existing ACL entry. The information controls the edit operation as follows:

Value of AclEdit.EditMode	Use of AclEdit.NewEntry and AclEdit.OldEntryHandle
CSSM_ACL_EDIT_MODE_ADD	Adds a new ACL entry to the set of ACL entries associated with the specified data base. The new ACL entry is created from the prototype ACL entry contained in NewEntry. OldEntryHandle is ignored for this EditMode.
CSSM_ACL_EDIT_MODE_DELETE	Deletes the ACL entry identified by OldEntryHandle and associated with the specified data base. NewEntry is ignored for this EditMode.
CSSM_ACL_EDIT_MODE_REPLACE	Replaces the ACL entry identified by OldEntryHandle and associated with the specified data base. The existing ACL is replaced based on the ACL entry prototype contained in NewEntry.

When replacing an existing ACL entry, the caller must replace all of the items in an ACL entry. The replacement prototype includes:

• Subject type and value - A CSSM_LIST structure containing a typed Subject. The Subject identifies the entity authorized by this ACL entry.

• Delegation flag - A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded in the authorization array.

• Authorization array - A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which permission is granted to the Subject.

• Validity period - A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid.

• ACL entry tag - A CSSM_STRING containing a user-defined value associated with the ACL entry.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE

SEE ALSO

For the CSSM API: CSSM_DL_GetDbAcl()

For the DL SPI: DL_GetDbAcl()

NAME

CSSM_DL_GetDbOwner for the CSSM API
DL_GetDbOwner for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_GetDbOwner
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_ACL_OWNER_PROTOTYPE_PTR Owner)

SPI:
CSSM_RETURN CSSMDLI DL_GetDbOwner
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_ACL_OWNER_PROTOTYPE_PTR Owner)

DESCRIPTION

This function returns a CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Data Base.

PARAMETER

DLDBHandle (input)

The handle pair that describes the data storage library module to be used to perform this function, and the open data store whose associated Owner is to be retrieved.

Owner (output)

A CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Data Base.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE

SEE ALSO

For the CSSM API: CSSM_DL_ChangeDbOwner()

For the DL SPI: DL_ChangeDbOwner()

NAME

CSSM_DL_ChangeDbOwner for the CSSM API
DL_ChangeDbOwner for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_ChangeDbOwner
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const CSSM_ACL_OWNER_PROTOTYPE *NewOwner)

SPI:
CSSM_RETURN CSSMDLI DL_ChangeDbOwner
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const CSSM_ACL_OWNER_PROTOTYPE *NewOwner)

DESCRIPTION

This function takes a CSSM_ACL_OWNER_PROTOTYPE defining the new Owner of the Data Base.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the data storage library module to be used to perform this function, and the open data store whose associated Owner is to be updated.

AccessCred (input)

A pointer to the set of one or more credentials used to prove the caller is the current Owner of the Data Base. Required credentials can include zero or more certificates, zero or more caller names, and one or more samples. If certificates and/or caller names are provided as input these must be provided as immediate values in this structure. The samples can be provided as immediate values or can be obtained through a callback function included in the AccessCred structure.

NewOwner (Input)

A CSSM_ACL_OWNER_PROTOTYPE defining the new Owner of the Data Base.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_NEW_OWNER

SEE ALSO

For the CSSM API: CSSM_DL_GetDbOwner()

For the DL SPI: DL_GetDbOwner()

Data Storage Operations

NAME

CSSM_DL_DbOpen for the CSSM API
DL_DbOpen for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DbOpen
    (CSSM_DL_HANDLE DLHandle,
    const char *DbName,
    const CSSM_NET_ADDRESS *DbLocation,
    CSSM_DB_ACCESS_TYPE AccessRequest,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const void *OpenParameters,
    CSSM_DB_HANDLE *DbHandle)

SPI:
CSSM_RETURN CSSMDLI DL_DbOpen
    (CSSM_DL_HANDLE DLHandle,
    const char *DbName,
    const CSSM_NET_ADDRESS *DbLocation,
    CSSM_DB_ACCESS_TYPE AccessRequest,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const void *OpenParameters,
    CSSM_DB_HANDLE *DbHandle)

DESCRIPTION

This function opens the data store with the specified logical name under the specified access mode. If user authentication credentials are required, they must be provided. Also, additional open parameters may be required to open a given data store, and are supplied in the OpenParameters.

PARAMETERS

DLHandle (input)

The handle that describes the add-in data storage library module to be used to perform this function.

DbName (input)

A pointer to the string containing the logical name of the data store.

DbLocation (input/optional)

A pointer to a network address directly or indirectly identifying the location of the storage service process. If the input is NULL, the module can determine a storage service process and its location based on the DbName (for existing data stores) or can assume a default storage service process location. If the DbName does not distinguish the storage service process, the service cannot be performed and the operation fails.

AccessRequest (input)

An indicator of the requested access mode for the data store, such as read-only or read-write.

AccessCred (input/optional)

A pointer to the set of one or more credentials being presented for authentication by the caller. These credentials are required to obtain access to the specified data store. The credentials structure can contain multiple types of credentials, as required for multi-factor authentication. The credential data can be an immediate value, such as a passphrase, PIN, certificate, or template of user-specific data, or the caller can specify a callback function the DL can use to obtain one or more credentials. The required set of credentials to access a particular data store is defined by the DbInfo record containing meta-data for the specified data store. If credentials are not required to access the specified data store, then this field can be NULL.

OpenParameters (input/optional)

A pointer to a module-specific set of parameters required to open the data store.

DbHandle (output)

The handle to the opened data store. The value will be set to CSSM_INVALID_HANDLE if the function fails.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_DB_LOCKED
CSSMERR_DL_INVALID_ACCESS_REQUEST
CSSMERR_DL_INVALID_DB_LOCATION
CSSMERR_DL_INVALID_DB_NAME
CSSMERR_DL_DATASTORE_DOESNOT_EXIST
CSSMERR_DL_INVALID_PARSING_MODULE
CSSMERR_DL_INVALID_OPEN_PARAMETERS

SEE ALSO

For the CSSM API: CSSM_DL_DbClose()

For the DL SPI: DL_DbClose()

NAME

CSSM_DL_DbClose for the CSSM API
DL_DbClose for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DbClose
    (CSSM_DL_DB_HANDLE DLDBHandle)

SPI:
CSSM_RETURN CSSMDLI DL_DbClose
    (CSSM_DL_DB_HANDLE DLDBHandle)

DESCRIPTION

This function closes an open data store.

PARAMETERS

DLDBHandle (input)

A handle structure containing the DL handle for the attached DL module and the DB handle for an open data store managed by the DL. This specifies the open data store to be closed.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE

SEE ALSO

For the CSSM API:
CSSM_DL_DbOpen()

For the DL SPI:
DL_DbOpen()

NAME

CSSM_DL_DbCreate for the CSSM API
DL_DbCreate for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DbCreate
    (CSSM_DL_HANDLE DLHandle,
    const char *DbName,
    const CSSM_NET_ADDRESS *DbLocation,
    const CSSM_DBINFO *DBInfo,
    CSSM_DB_ACCESS_TYPE AccessRequest,
    const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
    const void *OpenParameters,
    CSSM_DB_HANDLE *DbHandle)

SPI:
CSSM_RETURN CSSMDLI DL_DbCreate
    (CSSM_DL_HANDLE DLHandle,
    const char *DbName,
    const CSSM_NET_ADDRESS *DbLocation,
    const CSSM_DBINFO *DBInfo,
    CSSM_DB_ACCESS_TYPE AccessRequest,
    const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
    const void *OpenParameters,
    CSSM_DB_HANDLE *DbHandle)

DESCRIPTION

This function creates and opens a new data store. The name of the new data store is specified by the input parameter DbName. The record schema for the data store is specified in the DBINFO structure. If any RecordType defined in the DBINFO structure does not have an associated parsing module, then the ModuleSubserviceUid specified for that record type must be zero.

The newly created data store is opened under the specified access mode. If user authentication credentials are required, they must be provided. Also, additional open parameters may be required and are supplied in OpenParameters. If user authentication credentials are required, they must be provided.

Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must present a set of access credentials for authorization. Upon successfully authenticating the credentials, the template that verified the presented samples identifies the ACL entry that will be used in the authorization computation. If the caller is authorized, the new resource is created.

The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise control over its associated ACL. The caller can specify the following items for initializing an ACL entry:

• Subject - A CSSM_LIST structure, containing the type of the subject and a template value that can be used to verify samples that are presented in credentials when resource access is requested.

• Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the AuthorizationTag. (This item only applies to public key subjects).

• Authorization tag - The set of permissions that are granted to the Subject.

• Validity period - The start time and the stop time for which the ACL entry is valid.

• ACL entry tag - A user-defined string value associated with the ACL entry.

The service provider can modify the caller-provided initial ACL entry to conform to any innate resource-access policy that the service provider may be required to enforce. If the initial ACL entry provided by the caller contains values or permissions that are not supported by the service provider, then the service provider can modify the initial ACL appropriately or can fail the request to create the new resource. Service providers list their supported AuthorizationTag values in their Module Directory Services primary record.

PARAMETERS

DLHandle (input)

The handle that describes the add-in data storage library module used to perform this function.

DbName (input)

The logical name for the new data store.

DbLocation (input/optional)

A pointer to a network address directly or indirectly identifying the location of the storage service process. If the input is NULL, the module can assume a default storage service process location. If the DbName does not distinguish the storage service process, the service cannot be performed and the operation fails.

DBInfo (input)

A pointer to a structure describing the format/schema of each record type that will be stored in the new data store.

AccessRequest (input)

An indicator of the requested access mode for the data store, such as read-only or read-write.

CredAndAclEntry (input/optional)

A structure containing one or more credentials authorized for creating a data base and the prototype ACL entry that will control future use of the newly created key. The credentials and ACL entry prototype can be presented as immediate values or callback functions can be provided for use by the DL to acquire the credentials and/or the ACL entry interactively. If the DL provides public access for creating a data base, then the credentials can be NULL. If the DL defines a default initial ACL entry for the new data base, then the ACL entry prototype can be an empty list.

OpenParameters (input/optional)

A pointer to a module-specific set of parameters required to open the data store.

DbHandle (output)

The handle to the newly created and open data store. The value will be set to CSSM_INVALID_HANDLE if the function fails.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_DATASTORE_ALREADY_EXISTS
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_ACCESS_REQUEST
CSSMERR_DL_INVALID_DB_LOCATION
CSSMERR_DL_INVALID_DB_NAME
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_OPEN_PARAMETERS
CSSMERR_DL_INVALID_PARSING_MODULE
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_INDEX
CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT
CSSMERR_DL_UNSUPPORTED_INDEX_INFO
CSSMERR_DL_UNSUPPORTED_LOCALITY
CSSMERR_DL_UNSUPPORTED_NUM_ATTRIBUTES
CSSMERR_DL_UNSUPPORTED_NUM_INDEXES
CSSMERR_DL_UNSUPPORTED_NUM_RECORDTYPES
CSSMERR_DL_UNSUPPORTED_RECORDTYPE

SEE ALSO

For the CSSM API:
CSSM_DL_DbOpen()
CSSM_DL_DbClose()
CSSM_DL_DbDelete()

For the DL SPI:
DL_DbOpen()
DL_DbClose()
DL_DbDelete()

NAME

CSSM_DL_DbDelete for the CSSM API
DL_DbDelete for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DbDelete
    (CSSM_DL_HANDLE DLHandle,
    const char *DbName,
    const CSSM_NET_ADDRESS *DbLocation,
    const CSSM_ACCESS_CREDENTIALS *AccessCred)

SPI:
CSSM_RETURN CSSMDLI DL_DbDelete
    (CSSM_DL_HANDLE DLHandle,
    const char *DbName,
    const CSSM_NET_ADDRESS *DbLocation,
    const CSSM_ACCESS_CREDENTIALS *AccessCred)

DESCRIPTION

This function deletes all records from the specified data store and removes all state information associated with that data store.

PARAMETERS

DLHandle (input)

The handle that describes the add-in data storage library module to be used to perform this function.

DbName (input)

A pointer to the string containing the logical name of the data store.

DbLocation (input/optional)

A pointer to a network address directly or indirectly identifying the location of the storage service process. If the input is NULL, the module can assume a default storage service process location. If the DbName does not distinguish the storage service process, the service cannot be performed and the operation fails.

AccessCred (input/optional)

A pointer to the set of one or more credentials being presented for authentication by the caller. These credentials are required to obtain access to the specified data store. The credentials structure can contain multiple types of credentials, as required for multi-factor authentication. The credential data can be an immediate value, such as a passphrase, PIN, certificate, or template of user-specific data, or the caller can specify a callback function the DL can use to obtain one or more credentials. The required set of credentials to access a particular data store is defined by the DbInfo record containing meta-data for the specified data store. If credentials are not required to access the specified data store, then this field can be NULL.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_DATASTORE_DOESNOT_EXIST
CSSMERR_DL_DATASTORE_IS_OPEN
CSSMERR_DL_INVALID_DB_LOCATION
CSSMERR_DL_INVALID_DB_NAME

SEE ALSO

For the CSSM API:
CSSM_DL_DbCreate()
CSSM_DL_DbOpen()
CSSM_DL_DbClose()

For the DL SPI:
DL_DbCreate()
DL_DbOpen()
DL_DbClose()

NAME

CSSM_DL_CreateRelation for the CSSM API
DL_CreateRelation for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_CreateRelation
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_RECORDTYPE RelationID,
    const char *RelationName,
    uint32 NumberOfAttributes,
    const CSSM_DB_SCHEMA_ATTRIBUTE_INFO *pAttributeInfo,
    uint32 NumberOfIndexes,
    const CSSM_DB_SCHEMA_INDEX_INFO *pIndexInfo)

SPI:
CSSM_RETURN CSSMDLI DL_CreateRelation
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_RECORDTYPE RelationID,
    const char *RelationName,
    uint32 NumberOfAttributes,
    const CSSM_DB_SCHEMA_ATTRIBUTE_INFO *pAttributeInfo,
    uint32 NumberOfIndexes,
    const CSSM_DB_SCHEMA_INDEX_INFO *pIndexInfo)

DESCRIPTION

This function creates a new persistent relation of the specified type by inserting it into the specified data store. The pAttributeInfo and pIndexInfo specify the values contained in the new relation record.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store in which to insert the new relation record. The database should be opened in administrative mode using the CSSM_DB_ACCESS_PRIVILEGED flag.

RelationID (input)

Indicates the type of relation record being added to the data store.

RelationName (input)

Indicates the name of the relation being added to the data store.

NumberOfAttributes (input)

Indicates the number of attributes specified in pAttributeInfo.

pAttributeInfo (input)

A list of structures containing the meta information (schema) describing the attributes for the relation being added to the specified data store. The list contains at most one entry per attribute in the specified record type.

NumberOfIndexes (input)

Indicates the number of indexes specified in pIndexInfo.

pIndexInfo (input)

A list of structures containing the meta information (schema) describing the indexes for the relation being added to the specified data store. The list contains at most one entry per index in the specified record type.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INVALID_ATTRIBUTE_INFO
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_INDEX_INFO
CSSMERR_DL_INVALID_RECORDTYPE

SEE ALSO

For the CSSM API: CSSM_DL_DestroyRelation()

For the DL SPI: DL_DestroyRelation()

NAME

CSSM_DL_DestroyRelation for the CSSM API
DL_DestroyRelation for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DestroyRelation 
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_RECORDTYPE RelationID)

SPI:
CSSM_RETURN CSSMDLI DL_DestroyRelation 
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_RECORDTYPE RelationID)

DESCRIPTION

This function destroys an existing relation of the specified type by removing its entry from the specified data store.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store from which to delete the relation record.

RelationID (input)

Indicates the type of relation record being deleted from the data store.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RECORDTYPE

SEE ALSO

For the CSSM API: CSSM_DL_CreateRelation()

For the DL SPI: DL_CreateRelation()

NAME

CSSM_DL_GetDbNames for the CSSM API
DL_GetDbNames for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_GetDbNames
    (CSSM_DL_HANDLE DLHandle,
    CSSM_NAME_LIST_PTR *NameList)

SPI:
CSSM_RETURN CSSMDLI DL_GetDbNames
    (CSSM_DL_HANDLE DLHandle,
    CSSM_NAME_LIST_PTR *NameList)

DESCRIPTION

This function returns the list of logical data store names for all data stores that are known by and accessible to the specified DL module. This list also includes the number of data store names in the return list.

The CSSM_DL_FreeNameList() function must be called to de-allocate memory containing the list.

PARAMETERS

DLHandle (input)

The handle that describes the add-in data storage library module to be used to perform this function.

NameList (output)

Returns a list of data store names in a CSSM_NAME_LIST_PTR structure.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO

For the CSSM API:
CSSM_DL_GetDbNameFromHandle()
CSSM_DL_FreeNameList()

For the DL SPI:
DL_GetDbNameFromHandle()
DL_FreeNameList()

NAME

CSSM_DL_GetDbNameFromHandle for the CSSM API
DL_GetDbNameFromHandle for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_GetDbNameFromHandle
    (CSSM_DL_DB_HANDLE DLDBHandle,
    char **DbName)

SPI:
CSSM_RETURN CSSMDLI DL_GetDbNameFromHandle
    (CSSM_DL_DB_HANDLE DLDBHandle,
    char **DbName)

DESCRIPTION

This function retrieves the data source name corresponding to an opened data store handle.

PARAMETERS

DLDBHandle (input)

The handle pair that identifies the add-in data storage library module and the open data store whose name should be retrieved.

DbName (output)

Returns a zero terminated string which contains a data store name. The memory is allocated by the service provider and must be de-allocated by the application.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE

SEE ALSO

For the CSSM API:
CSSM_DL_GetDbNames()

For the DL SPI:
DL_GetDbNames()

NAME

CSSM_DL_FreeNameList for the CSSM API
DL_FreeNameList for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_FreeNameList
    (CSSM_DL_HANDLE DLHandle,
    CSSM_NAME_LIST_PTR NameList)

SPI:
CSSM_RETURN CSSMDLI DL_FreeNameList
    (CSSM_DL_HANDLE DLHandle,
    CSSM_NAME_LIST_PTR NameList)

DESCRIPTION

This function frees the list of the logical data store names that was returned by CSSM_DL_GetDbNames.

PARAMETERS

DLHandle (input)

The handle that describes the add-in data storage library module to be used to perform this function.

NameList (input)

A pointer to the CSSM_NAME_LIST.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO

For the CSSM API:
CSSM_DL_GetDbNames()

For the DL SPI:
DL_GetDbNames()

Data Record Operations

NAME

CSSM_DL_DataInsert for the CSSM API
DL_DataInsert for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DataInsert
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_RECORDTYPE RecordType,
    const CSSM_DB_RECORD_ATTRIBUTE_DATA *Attributes,
    const CSSM_DATA *Data,
    CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)

SPI:
CSSM_RETURN CSSMDLI DL_DataInsert
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_RECORDTYPE RecordType,
    const CSSM_DB_RECORD_ATTRIBUTE_DATA *Attributes,
    const CSSM_DATA *Data,
    CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)

DESCRIPTION

This function creates a new persistent data record of the specified type by inserting it into the specified data store. The values contained in the new data record are specified by the Attributes and the Data. The attribute value list contains zero or more attribute values. The Attributes parameter also specifies a record type. This type must be the same as the type specified by the RecordType input parameter. The DL module may require initial values for the CSSM pre-defined attributes. The DL module can assume default values for any unspecified attribute values or can return an error condition when DLM-required attribute values are not specified by the caller. The Data is an opaque object to be stored in the new data record.

If a primary key (concatination of all unique indexes in the relation) exists, the error CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA is returned. The client should call CSSM_DL_DataGetFirst() followed by CSSM_DL_DataModify() to change an existing record.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store in which to insert the new data record.

RecordType (input)

Indicates the type of data record being added to the data store

Attributes (input/optional)

A list of structures containing the attribute values to be stored in that attribute, and the meta information (schema) describing those attributes. The list contains at most one entry per attribute in the specified record type. The specified AttributeFormat for each attribute must match that of the database schema, otherwise the error CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT is returned. If an attribute is of type CSSM_DB_ATTRIBUTE_FORMAT_STRING and the value specified for that string includes a null-terminator, then the length count in the CSSM_DATA structure containing the input string should include the terminating character. (If null-terminators are used, they should be used consistently when storing, searching, and retrieving the string value, otherwise selection predicates will not locate expected matches.) For those attributes that are not assigned values by the caller, the DL module may assume the values to be the empty set, or assume default values, or return an error. If the specified record type does not contain any attributes, this parameter must be NULL.

Data (input/optional)

A pointer to the CSSM_DATA structure which contains the opaque data object to be stored in the new data record. If the specified record type does not contain an opaque data object, this parameter must be NULL.

UniqueId (output)

A pointer to a CSSM_DB_UNIQUE_RECORD_PTR containing a unique identifier associated with the new record. This unique identifier structure can be used in future references to this record during the current open data base session. The pointer will be set to NULL if the function fails. The CSSM_DL_FreeUniqueRecord() function must be used to deallocate this structure.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_PARSING_MODULE
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA
CSSMERR_DL_INVALID_VALUE
CSSMERR_DL_MISSING_VALUE

SEE ALSO

For the CSSM API:
CSSM_DL_DataDelete()

For the DL SPI:
DL_DataDelete()

NAME

CSSM_DL_DataDelete for the CSSM API
DL_DataDelete for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DataDelete
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_DB_UNIQUE_RECORD *UniqueRecordIdentifier)

SPI:
CSSM_RETURN CSSMDLI DL_DataDelete
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_DB_UNIQUE_RECORD *UniqueRecordIdentifier)

DESCRIPTION

This function removes the data record specified by the unique record identifier from the specified data store.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store from which to delete the specified data record.

UniqueRecordIdentifier (input)

A pointer to a CSSM_DB_UNIQUE_RECORD identifier containing unique identification of the data record to be deleted from the data store. Once the associated record has been deleted, this unique record identifier cannot be used in future references, except as an argument to DL_FreeUniqueRecord(), which must still be called.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_RECORD_NOT_FOUND

SEE ALSO

For the CSSM API:
CSSM_DL_DataInsert()

For the DL SPI:
DL_DataInsert()

NAME

CSSM_DL_DataModify for the CSSM API
DL_DataModify for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DataModify
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_RECORDTYPE RecordType,
    CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier,
    const CSSM_DB_RECORD_ATTRIBUTE_DATA *AttributesToBeModified,
    const CSSM_DATA *DataToBeModified,
    CSSM_DB_MODIFY_MODE ModifyMode)

SPI:
CSSM_RETURN CSSMDLI DL_DataModify
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_RECORDTYPE RecordType,
    CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier,
    const CSSM_DB_RECORD_ATTRIBUTE_DATA *AttributesToBeModified,
    const CSSM_DATA *DataToBeModified,
    CSSM_DB_MODIFY_MODE ModifyMode)

DESCRIPTION

This function modifies the persistent data record identified by the UniqueRecordIdentifier. The modifications are specified by the Attributes and Data parameters. The ModifyMode indicates how the attributes are to be updated. The ModifyMode has no affect on updating the data blob contained in the record. If the data blob is the only record attribute being updated by this function call, then the modification mode must be 0. The current modification modes behave as follows:

ModifyMode Value	Function Behavior
CSSM_DB_MODIFY_ATTRIBUTE_NONE	No Attributes are being updated.
CSSM_DB_MODIFY_ATTRIBUTE_ADD	The specified values are added to the set of current values for each attribute. If 0 values are specified then the error CSSMERR_DL_INVALID_MODIFY_MODE is returned. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED is returned.
CSSM_DB_MODIFY_ATTRIBUTE_DELETE	The specified values are removed from the set of current values for each attribute. If 0 values are specified then all values are deleted or the attributes value is replaced with the default for this attribute. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED is returned.
CSSM_DB_MODIFY_ATTRIBUTE_REPLACE	The values for each attribute are replaced with the specified set of values for each attribute. If no values are specified then all values are deleted or the attributes value is replaced with the default for this attribute. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED is returned when more than 1 value is specified.

If the attribute lists specifies an attribute that is not defined in the database's meta-information, an error condition is returned. For each attribute-value pair, the value replaces the corresponding attribute value in the record. If a data value is specified, the record's data value is replaced with the specified value. A record's data value or attribute values can be set to NULL or zero to represent deletion or the lack of a known value.

If the record referenced by UniqueRecordIdentifier has been modified since the last time it was updated, the error CSSMERR_DL_STALE_UNIQUE_RECORD is returned and no modification takes place.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store to search for records satisfying the query.

RecordType (input)

Indicates the type of data record being modified.

UniqueRecordIdentifier (input/output)

A pointer to a CSSM_DB_UNIQUE_RECORD containing a unique identifier associated with the record to modify. If the modification succeeds, the UniqueRecordIdentifier points to a CSSM_DB_UNIQUE_RECORD containing a unique identifier associated with the updated record. If the modification fails, the UniqueRecordIdentifier is not modified.

AttributesToBeModified (input/optional)

A list of structures containing the attribute values to be stored in that attribute and the meta information (schema) describing those attributes. The list contains at most one entry per attribute in the specified record type. The specified AttributeFormat for each attribute must match that of the database schema, otherwise the error CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT is returned. If an attribute is of type CSSM_DB_ATTRIBUTE_FORMAT_STRING and the value specified for that string includes a null-terminator, then the length count in the CSSM_DATA structure containing the input string should include the terminating character. (If null-terminators are used, they should be used consistently when storing, searching, and retrieving the string value, otherwise selection predicates will not locate expected matches.) Each attribute specified is modified according to the value of ModifyMode (see table in the DESCRIPTION section of this definition). Those attributes that are not specified as part of this parameter remain unchanged. If the AttributesToBeModified parameter is NULL, no attribute modification occurs.

DataToBeModified (input/optional)

A pointer to the CSSM_DATA structure which contains the opaque data object to be stored in the data record. If this parameter is NULL, no Data modification occurs.

ModifyMode (input)

A CSSM_DB_MODIFY_MODE value indicating the type of modification to be performed on the record attributes identified by AttributesToBeModified. If no attributes are specified, then this value must be CSSM_DB_MODIFY_ATTRIBUTE_NONE.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_MODIFY_MODE
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA
CSSMERR_DL_INVALID_VALUE
CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED
CSSMERR_DL_STALE_UNIQUE_RECORD

SEE ALSO

For the CSSM API:
CSSM_DL_DataInsert()
CSSM_DL_DataDelete()

For the DL SPI:
DL_DataInsert()
DL_DataDelete()

NAME

CSSM_DL_DataGetFirst for the CSSM API
DL_DataGetFirst for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DataGetFirst
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_QUERY *Query,
    CSSM_HANDLE_PTR ResultsHandle,
    CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
    CSSM_DATA_PTR Data,
    CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)

SPI:
CSSM_RETURN CSSMDLI DL_DataGetFirst
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_QUERY *Query,
    CSSM_HANDLE_PTR ResultsHandle,
    CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
    CSSM_DATA_PTR Data,
    CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)

DESCRIPTION

This function retrieves the first data record in the data store that matches the selection criteria. The selection criteria (including selection predicate and comparison values) is specified in the Query structure. If the Query specifies an attribute that is not defined in the database's meta-information, an error condition is returned. The DL module can use internally-managed indexing structures to enhance the performance of the retrieval operation. This function selects the first record satisfying the query based on the list of Attributes and the opaque Data object. The output buffers for the retrieved record are allocated by this function using the memory management functions provided during the module attach operation. This function also returns a results handle to be used when retrieving subsequent records satisfying the query.

Additional matching records are iteratively retrieved using the function CSSM_DL_DataGetNext(). The data storage module supports one of two retrieval models:

• Transactional - all query results are determined at initial query evaluation. Results do not change during an incremental retrieval process.

• File System Scan - query results are selected during the incremental retrieval process. Records matching the query may be added to or deleted from the underlying data store during the iterative retrieval. The caller may receive the new matching records and not received the deleted records.

The caller can determine which retrieval model is supported by examining the encapsulated product description for this data storage module.

If the query selection criteria also specifies time for space limits for executing the query, those limits also apply ro retrieval of the additional selected data records retrieved using the CSSM_DL_DataGetNext() function. Finally, this function returns a unique record identifier associated with the retrieved record. This structure can be used in future references to the retrieved data record. Once a user has finished using a certain query, it must call CSSM_DataAbortQuery() for releasing resources that CSSM uses. If all records satisfying the query have been retrieved, then query is automatically terminated.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store to search for records satisfying the query.

Query (input/optional)

The query structure specifying the selection predicate(s) used to query the data store. The structure contains meta information about the search fields and the relational and conjunctive operators forming the selection predicate. The comparison values to be used in the search are specified in the Attributes field of this Query structure. If a search attribute is of type CSSM_DB_ATTRIBUTE_FORMAT_STRING and the search value specified for that string includes a null-terminator, then the length count for that string should include the terminating character. (If null-terminators are used they should be used consistently, storing the terminator as part of the string in the data store, otherwise selection predicates will not locate expected matches.) The Query structure attributes also identify the particular attributes to be searched by this query. If no query is specified, the DL module can return the first record in the data store, performing sequential retrieval, or return an error. If no selection predicates are specified, the DL module can return the first record in the data store, performing sequential retrieval, or return an error (CSSM_DL_UNSUPPORTED_NUM_SELECTION_PREDS). When selection predicates are specified, the NumberOfValues of the Attribute of each selection predicate must be 1. If any selection predicate does not satisfy this requirement, the error CSSMERR_DL_INVALID_QUERY is returned.

ResultsHandle (output)

This handle should be used to retrieve subsequent records that satisfied this query.

Attributes (optional-input/output)

If the Attributes structure pointer is NULL, no values are returned.

Otherwise, the DataRecordType, NumberOfAttributes and AttributeData fields are read. AttributeData must be an array of NumberOfAttributes CSSM_DB_RECORD_ATTRIBUTE elements. Only the Info field of each element is used on input. The AttributeFormat field of the Info field is ignored on input.

On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing a list of all or the requested attribute values (subset) from the retrieved record. The SemanticInformation field is set. For each CSSM_DB_ATTRIBUTE_DATA contained in the AttributeData array, the NumberOfValues field is set to reflect the size of the Value array which is allocated by the DL using the application specified allocators. Each CSSM_DATA in the Value array will have it's Data field as a pointer to data allocated using the application specified allocators containing the attributes value, and have it's Length set to the length of the value.

All values for an attribute are returned (this could be 0). All fields in the Info field of the CSSM_DB_ATTRIBUTE_DATA are left unchanged except for the AttributeFormat field, which is set to reflect the schema.

Data (optional-input/output)

Data values contained in the referenced memory are ignored during processing and are overwritten with the retrieved opaque object. On output, a CSSM_DATA structure containing the opaque object stored in the retrieved record.

UniqueId (output)

If successful and (at least) a record satisfying the query has been found, then this parameter returns a pointer to a CSSM_UNIQUE_RECORD_PTR structure containing a unique identifier associated with the retrieved record. This unique identifier structure can be used in future references to this record using this DLDBHandle pairing. It may not be valid for other DLHandles targeted to this DL module or to other DBHandles targeted to this data store. If there are no records satisfying the query, then this pointer is NULL and CSSM_DL_DataGetFirst() must return CSSM_DL_ENDOFDATA; in this case a normal termination condition has occurred. The CSSM_DL_FreeUniqueRecord() must be used to de-allocate this structure.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_ENDOFDATA
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_PARSING_MODULE
CSSMERR_DL_INVALID_QUERY
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT
CSSMERR_DL_UNSUPPORTED_NUM_SELECTION_PREDS
CSSMERR_DL_UNSUPPORTED_OPERATOR
CSSMERR_DL_UNSUPPORTED_QUERY
CSSMERR_DL_UNSUPPORTED_QUERY_LIMITS

SEE ALSO

For the CSSM API:
CSSM_DL_DataGetNext()
CSSM_DL_DataAbortQuery()

For the DL SPI:
DL_DataGetNext()
DL_DataAbortQuery()

NAME

CSSM_DL_DataGetNext for the CSSM API
DL_DataGetNext for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DataGetNext
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_HANDLE ResultsHandle,
    CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
    CSSM_DATA_PTR Data,
    CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)

SPI:
CSSM_RETURN CSSMDLI DL_DataGetNext
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_HANDLE ResultsHandle,
    CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
    CSSM_DATA_PTR Data,
    CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)

DESCRIPTION

This function returns the next data record referenced by the ResultsHandle. The ResultsHandle references a set of records selected by an invocation of the DataGetFirst function. The Attributes parameter can specify a subset of the attributes to be returned. If Attributes specifies an attribute that is not defined in the database's meta-information, an error condition is returned. The record values are returned in the Attributes and Data parameters. The output buffers for the retrieved record are allocated by this function using the memory management functions provided during the module attach operation. The function also returns a unique record identifier for the return record.

The data storage module supports one of two retrieval models: transactional or file system scan. The transactional model freezes the set of records to be retrieved at query initiation. The file system scan model selects from a potentially changing set of records during the retrieval process. The EndOfDataStore() indicates when all matching records have been retrieved. The caller can determine which retrieval model is supported by examining the encapsulated product description for this data storage module. Once a user has finished using a certain query, it must call CSSM_DataAbortQuery() for releasing resources that CSSM uses. If all records satisfying the query have been retrieved, then query is automatically terminated.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function, and the open data store from which records were selected by the initiating query.

ResultsHandle (input)

The handle identifying a set of records retrieved by a query executed by the CSSM_DL_DataGetFirst() function.

Attributes (optional-input/output)

If the Attributes structure pointer is NULL, no values are returned.

Otherwise, the DataRecordType, NumberOfAttributes and AttributeData fields are read. AttributeData must be an array of NumberOfAttributes CSSM_DB_RECORD_ATTRIBUTE elements. Only the Info field of each element is used on input. The AttributeFormat field of the Info field is ignored on input.

On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing a list of all or the requested attribute values (subset) from the retrieved record. The SemanticInformation field is set. For each CSSM_DB_ATTRIBUTE_DATA contained in the AttributeData array, the NumberOfValues field is set to reflect the size of the Value array which is allocated by the DL using the application specified allocators. Each CSSM_DATA in the Value array will have it's Data field as a pointer to data allocated using the application specified allocators containing the attributes value, and have it's Length set to the length of the value.

All values for an attribute are returned (this could be 0). All fields in the Info field of the CSSM_DB_ATTRIBUTE_DATA are left unchanged except for the AttributeFormat field, which is set to reflect the schema.

Data (optional-input/output)

Data values contained in the referenced memory are ignored during processing and are overwritten with the retrieved opaque object. On output, a CSSM_DATA structure containing the opaque object stored in the retrieved record. If the pointer is data structure pointer is NULL, the opaque object is not returned.

UniqueId (output)

If successful and (at least) a record satisfying the query has been found, then this parameter returns a pointer to a CSSM_UNIQUE_RECORD_PTR structure containing a unique identifier associated with the retrieved record. This unique identifier structure can be used in future references to this record using this DLDBHandle pairing. It may not be valid for other DLHandles targeted to this DL module or to other DBHandles targeted to this data store. If there are no more records satisfying the query, then this pointer is NULL and CSSM_DL_DataGetNext() must return CSSM_DL_ENDOFDATA; in this case a normal termination condition has occurred. The CSSM_DL_FreeUniqueRecord() must be used to de-allocate this structure.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_ENDOFDATA
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_INVALID_RESULTS_HANDLE

SEE ALSO

For the CSSM API:
CSSM_DL_DataGetFirst()
CSSM_DL_DataAbortQuery()

For the DL SPI:
DL_DataGetFirst()
DL_DataAbortQuery()

NAME

CSSM_DL_DataAbortQuery for the CSSM API
DL_DataAbortQuery for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DataAbortQuery
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_HANDLE ResultsHandle)

SPI:
CSSM_RETURN CSSMDLI DL_DataAbortQuery
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_HANDLE ResultsHandle)

DESCRIPTION

This function terminates the query initiated by DL_DataGetFirst(), and allows a DL to release all intermediate state information associated with the query, and release any locks on the resource. The user/application must call CSSM_DL_DataAbortQuery() at the termination.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store from which records were selected by the initiating query.

ResultsHandle (input)

The selection handle returned from the initial query function.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RESULTS_HANDLE

SEE ALSO

For the CSSM API:
CSSM_DL_DataGetFirst()
CSSM_DL_DataGetNext()

For the DL SPI:
DL_DataGetFirst()
dL_DataGetNext()

NAME

CSSM_DL_DataGetFromUniqueRecordId for the CSSM API
DL_DataGetFromUniqueRecordId for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_DataGetFromUniqueRecordId
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord,
    CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
    CSSM_DATA_PTR Data)

SPI:
CSSM_RETURN CSSMDLI DL_DataGetFromUniqueRecordId
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord,
    CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
    CSSM_DATA_PTR Data)

DESCRIPTION

This function retrieves the data record and attributes associated with this unique record identifier. The Attributes parameter can specify a subset of the attributes to be returned. If Attributes specifies an attribute that is not defined in the database's meta-information, an error condition is returned. The output buffers for the retrieved record are allocated by this function using the memory management functions provided during the module attach operation. The DL module can use an indexing structure identified in the UniqueRecordId to enhance the performance of the retrieval operation.

The DL should assume that the value of CSSM_QUERY_FLAGS is 0 when performing this operation. In particular this means that if the data of a key record is being retrieved, the DL will return a CSSM_KEY structure with a key reference.

If the record referenced by UniqueRecordIdentifier has been modified since the last time it was retrieved, the error (warning) CSSMERR_DL_RECORD_MODIFIED is returned but the requested attributes and data of the new record is returned. The caller should be advised that other attributes (or the data) might have changed that were not fetched from the DL with this call.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store to search for the data record.

UniqueRecord (input)

The pointer to a unique record structure returned from a DL_DataInsert, DL_DataGetFirst, or DL_DataGetNext operation.

Attributes (optional-input/output)

If the Attributes structure pointer is NULL, no values are returned.

Otherwise, the DataRecordType, NumberOfAttributes and AttributeData fields are read. AttributeData must be an array of NumberOfAttributes CSSM_DB_RECORD_ATTRIBUTE elements. Only the Info field of each element is used on input. The AttributeFormat field of the Info field is ignored on input.

On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing a list of all or the requested attribute values (subset) from the retrieved record. The SemanticInformation field is set. For each CSSM_DB_ATTRIBUTE_DATA contained in the AttributeData array, the NumberOfValues field is set to reflect the size of the Value array which is allocated by the DL using the application specified allocators. Each CSSM_DATA in the Value array will have it's Data field as a pointer to data allocated using the application specified allocators containing the attributes value, and have it's Length set to the length of the value.

All values for an attribute are returned (this could be 0). All fields in the Info field of the CSSM_DB_ATTRIBUTE_DATA are left unchanged except for the AttributeFormat field, which is set to reflect the schema.

Data (optional-input/output)

Data values contained in the referenced memory are ignored during processing and are overwritten with the retrieved opaque object. On output, a CSSM_DATA structure containing the opaque object stored in the retrieved record. If the pointer is data structure pointer is NULL, the opaque object is not returned.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID

SEE ALSO

For the CSSM API:
CSSM_DL_DataInsert()
CSSM_DL_DataGetFirst()
CSSM_DL_DataGetNext()

For the DL SPI:
CSSM_DL_DataInsert()
CSSM_DL_DataGetFirst()
CSSM_DL_DataGetNext()

NAME

CSSM_DL_FreeUniqueRecord for the CSSM API
DL_FreeUniqueRecord for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_FreeUniqueRecord
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord)

SPI:
CSSM_RETURN CSSMDLI DL_FreeUniqueRecord
    (CSSM_DL_DB_HANDLE DLDBHandle,
    CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord)

DESCRIPTION

This function frees the memory associated with the data store unique record structure.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store from which the UniqueRecord identifier was assigned.

UniqueRecord(input)

The pointer to the memory that describes the data store unique record structure.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RECORD_UID

SEE ALSO

For the CSSM API:
CSSM_DL_DataInsert()
CSSM_DL_DataGetFirst()
CSSM_DL_DataGetNext()

For the DL SPI:
DL_DataInsert()
DL_DataGetFirst()
DL_DataGetNext()

Extensibility Operations

NAME

CSSM_DL_PassThrough for the CSSM API
DL_PassThrough for the DL SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_DL_PassThrough
    (CSSM_DL_DB_HANDLE DLDBHandle,
    uint32 PassThroughId,
    const void *InputParams,
    void **OutputParams)

SPI:
CSSM_RETURN CSSMDLI DL_PassThrough
    (CSSM_DL_DB_HANDLE DLDBHandle,
    uint32 PassThroughId,
    const void *InputParams,
    void **OutputParams)

DESCRIPTION

This function allows applications to call data storage library module-specific operations that have been exported. Such operations may include queries or services that are specific to the domain represented by a DL module.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store upon which the function is to be performed.

PassThroughId (input)

An identifier assigned by a DL module to indicate the exported function to be performed.

InputParams (input)

A pointer to a module implementation-specific structure containing parameters to be interpreted in a function-specific manner by the requested DL module.

OutputParams (output)

A pointer to a module, implementation-specific structure containing the output data. The service provider will allocate the memory for this structure. The application should free the memory for the structure.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_PASSTHROUGH_ID