Data Storage Library Interface

Overview

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

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

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

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_SPI_DL_FUNCS

typedef struct cssm_spi_dl_funcs {
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *DbClose)
        (CSSM_DL_DB_HANDLE DLDBHandle);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *DbDelete)
        (CSSM_DL_HANDLE DLHandle,
        const char *DbName,
        const CSSM_NET_ADDRESS *DbLocation,
        const CSSM_ACCESS_CREDENTIALS *AccessCred);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *DestroyRelation)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        CSSM_DB_RECORDTYPE RelationID);
    CSSM_RETURN (CSSMAPI *Authenticate)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        CSSM_DB_ACCESS_TYPE AccessRequest,
        const CSSM_ACCESS_CREDENTIALS *AccessCred);
    CSSM_RETURN (CSSMAPI *GetDbAcl)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        const CSSM_STRING *SelectionTag,
        uint32 *NumberOfAclInfos,
        CSSM_ACL_ENTRY_INFO_PTR *AclInfos);
    CSSM_RETURN (CSSMAPI *ChangeDbAcl)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const CSSM_ACL_EDIT *AclEdit);
    CSSM_RETURN (CSSMAPI *GetDbOwner)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        CSSM_ACL_OWNER_PROTOTYPE_PTR Owner);
    CSSM_RETURN (CSSMAPI *ChangeDbOwner)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const CSSM_ACL_OWNER_PROTOTYPE *NewOwner);
    CSSM_RETURN (CSSMAPI *GetDbNames)
        (CSSM_DL_HANDLE DLHandle,
        CSSM_NAME_LIST_PTR *NameList);
    CSSM_RETURN (CSSMAPI *GetDbNameFromHandle)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        char **DbName);
    CSSM_RETURN (CSSMAPI *FreeNameList)
        (CSSM_DL_HANDLE DLHandle,
        CSSM_NAME_LIST_PTR NameList);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *DataDelete)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        const CSSM_DB_UNIQUE_RECORD *UniqueRecordIdentifier);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *DataGetNext)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        CSSM_HANDLE ResultsHandle,
        C
        CSSM_DATA_PTR Data,
        CSSM_DB_UNIQUE_RECORD_PTR *UniqueId);
    CSSM_RETURN (CSSMAPI *DataAbortQuery)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        CSSM_HANDLE ResultsHandle);
    CSSM_RETURN (CSSMAPI *DataGetFromUniqueRecordId)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        const CSSM_DB_UNIQUE_RECORD *UniqueRecord,
        CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
        CSSM_DATA_PTR Data);
    CSSM_RETURN (CSSMAPI *FreeUniqueRecord)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord);
    CSSM_RETURN (CSSMAPI *PassThrough)
        (CSSM_DL_DB_HANDLE DLDBHandle,
        uint32 PassThroughId,
        const void * InputParams,
        void **OutputParams);
}CSSM_SPI_DL_FUNCS, *CSSM_SPI_DL_FUNCS_PTR;

Data Storage Library Operations

NAME

DL_Authenticate

SYNOPSIS

CSSM_RETURN CSSMDLI DL_Authenticate
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const 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 corresponding function call definition in Part 2 of this document.

NAME

DL_GetDbAcl

SYNOPSIS

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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_ChangeDbAcl()

NAME

DL_ChangeDbAcl

SYNOPSIS

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 Subject 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 dat a base. The new ACL entry is created from the prototype ACL entry contained in f2NewEntry. 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 th e specified data base. The existing ACL is replaced based on the ACL entry proto type 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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_GetDbAcl()

NAME

DL_GetDbOwner

SYNOPSIS

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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_ChangeDbOwner()

NAME

DL_ChangeDbOwner

SYNOPSIS

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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_GetDbOwner()

Data Store Operations

NAME

DL_DbOpen

SYNOPSIS

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 no DbName is provided, the default data store will be opened. 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 and a default cannot be assumed, 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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DbClose()

NAME

DL_DbClose

SYNOPSIS

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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DbOpen()

NAME

DL_DbCreate

SYNOPSIS

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 Authorization tag . (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 Authorization tag 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 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 and a default cannot be assumed, 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 key 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 CSP to acquire the credentials and/or the ACL entry interactively. If the CSP provides public access for creating a key, then the credentials can be NULL. If the CSP defines a default initial ACL entry for the new key, 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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DbOpen()
DL_DbClose()
DL_DbDelete()

NAME

DL_DbDelete

SYNOPSIS

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 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 and a default cannot be assumed, 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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DbCreate()

NAME

DL_CreateRelation

SYNOPSIS

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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DestroyRelation()

NAME

DL_DestroyRelation

SYNOPSIS

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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_CreateRelation()

NAME

DL_GetDbNames

SYNOPSIS

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

See the corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_GetDbNameFromHandle()
DL_FreeNameList()

NAME

DL_GetDbNameFromHandle

SYNOPSIS

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

DESCRIPTION

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

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module used to perform this function and the open data store whose name is being requested.

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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_GetDbNames()

NAME

DL_FreeNameList

SYNOPSIS

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

See the corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_GetDbNames()

Data Record Operations

NAME

DL_DataInsert

SYNOPSIS

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 modules can assume default values for any unspecified attribute values or can return an error condition when DLM-required attributes 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 (concatenation of all unique indexes in the relation) exists, the DLM will maintain its uniqueness. If the new record's primary key duplicates the primary key of an existing record in the current relation, the existing record will be updated with the new record's data and attributes. If an attribute or the opaque data object is not specified, then either the existing value is overwritten with a default value, or the an error condition is returned.

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. 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.) The DL module can assume default values for those attributes that are not assigned values by the caller, or may 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_POINTER 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, using this DLDBHandle pairing. The pointer will be set to NULL if the function fails. The 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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DataDelete()

NAME

DL_DataDelete

SYNOPSIS

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

DESCRIPTION

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

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.

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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DataInsert()

NAME

DL_DataModify

SYNOPSIS

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_ADD	For single-valued attributes, the current value is replaced with the new value. For multi-valued attributes, the new value is added to the set of current values; previously existing values are retained.
CSSM_DB_MODIFY_ATTRIBUTE_DELETE	For single-valued attributes, the current value is set to the NULL representatio n appropriate for the attribute type. For multi-valued attributes, the specified set values will be deleted from the current set values. If no current set values are specified then the current value is set to the empty-set.
CSSM_DB_MODIFY_ATTRIBUTE_REPLACE	For single-valued attributes, the current value is replaced with the new value. For multi-valued attributes, the current set value is replaced with the new, spe cified set value.

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.

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 the data record resides.

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 containing the names of the attributes to be modified and their new values. For each attribute in the Attributes list, the attribute is added if does not exist, or replaced if it does exist. If the AttributesToBeModified->AttributeData[i].Value (where i is the index of the current attribute to be modified) is NULL and ModifyMode is equal to CSSM_DB_MODIFY_ATTRIBUTE_DELETE or CSSM_DB_MODIFY_ATTRIBUTE_REPLACE, the attribute is deleted. If the AttributesToBeModified->AttributeData[i].Value is NULL and ModifyMode is equal to CSSM_DB_MODIFY_ATTRIBUTE_ADD the error CSSM_DL_INVALID_MODIFY_MODE is returned. 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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DataInsert()
DL_DataDelete()

NAME

DL_DataGetFirst

SYNOPSIS

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 returns the first record satisfying the query in 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 records satisfied the query and, if so, a results handle to be used when retrieving subsequent records satisfying the query.

Additional matching records are iteratively retrieved using the function 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 specifies time or space limits for executing the query, those limits also apply to 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. The CSSM pre-defined attribute names "PrintName" and "Alias" are valid in any query, regardless of the stored value for those attributes. If no query is specified, the DL module can return the first record in the data store (that is, perform 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).

ResultsHandle (output)

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

Attributes (optional-input/output)

On input, a CSSM_DB_RECORD_ATTRIBUTE structure referencing pre-allocated memory. Data values contained in the referenced memory are ignored during processing and are overwritten with retrieved attribute values. On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing a list of attribute values (and corresponding meta information) from the retrieved record.

Data (optional-input/output)

On input, a CSSM_DATA structure referencing pre-allocated memory. 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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DataGetNext()
DL_DataAbortQuery()

NAME

DL_DataGetNext

SYNOPSIS

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. A flag indicates whether additional records satisfying the original query remain to be retrieved. 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, as long as the query is still running. 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 DataGetFirst function.

Attributes (optional-input/output)

On input, a CSSM_DB_RECORD_ATTRIBUTE structure referencing pre-allocated memory. The attribute structure can specify the names of the attributes to be retrieved. Data values contained in the referenced memory are ignored during processing and are overwritten with all or the requested subset of attribute values retrieved by this function. On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing a list of all or the requested attribute value subset (and corresponding meta information) from the retrieved record. If the Attributes structure pointer is NULL, no values are returned.

Data (optional-input/output)

On input, a CSSM_DATA structure referencing pre-allocated memory. 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_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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DataGetFirst()
DL_DataAbortQuery()

NAME

DL_DataAbortQuery

SYNOPSIS

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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DataGetFirst()
DL_DataGetNext()

NAME

DL_DataGetFromUniqueRecordId

SYNOPSIS

CSSM_RETURN CSSMDLI DL_DataGetFromUniqueRecordId
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_DB_UNIQUE_RECORD *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.

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)

On input, a CSSM_DB_RECORD_ATTRIBUTE structure referencing pre-allocated memory. The attribute structure can specify the names of the attributes to be retrieved. Data values contained in the referenced memory are ignored during processing and are overwritten with all or the requested subset of attribute values retrieved by this function. On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing a list of all or the requested attribute value subset (and corresponding meta information) from the retrieved record. If the Attributes structure pointer is NULL, no values are returned.

Data (optional-input/output)

On input, a CSSM_DATA structure referencing pre-allocated memory. 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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DataInsert()
DL_DataGetFirst()
DL_DataGetNext()

NAME

DL_FreeUniqueRecord

SYNOPSIS

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 corresponding function call definition in Part 2 of this document.

SEE ALSO

DL_DataInsert()
DL_DataGetFirst()
DL_DataGetNext()

Extensibility Functions

NAME

DL_PassThrough

SYNOPSIS

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

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/optional)

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 corresponding function call definition in Part 2 of this document.