Previous section.

Common Security: CDSA and CSSM, Version 2
Copyright © 1999 The Open Group

Data Storage Library Services API

Overview

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

CSSM stores and manages meta-information about a DL in the Module Directory Services (MDS). This information describes the storage and retrieval capabilities of a DL. Applications can query MDS to obtain information about the available DLs and attach to a DL that provides the needed services. Each DL service is responsible for acquiring and managing meta-data about each application-defined data store that it creates. Applications use the CSSM_DL_GetDbNames() function to obtain status information about each data store managed by the DL. The DL can store this meta-data using MDS or some other mechanism.

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

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

Data Storage Data Structures

CSSM_DL_HANDLE

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

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

CSSM_DB_HANDLE

A unique identifier for an open data store. 

typedef CSSM_MODULE_HANDLE CSSM_DB_HANDLE; /* Data storage Handle */

CSSM_DL_DB_HANDLE

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

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

DLHandle

Handle of an attached module that provides DL services.

DBHandle

Handle of an open data store that is currently under the management of the DL module specifies by the DLHandle.

CSSM_DL_DB_LIST

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

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

NumHandles

Number of DL module and data store pairing in the list.

DLDBHandle

List of data library module and data store pairs.

CSSM_DB_ATTRIBUTE_NAME_FORMAT

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


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

CSSM_DB_ATTRIBUTE_FORMAT

This enumerated list defines the formats for attribute values. Many data storage library modules manage only one attribute format, CSSM_DB_ATTRIBUTE_FORMAT_STRING.

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

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

typedef struct cssm_db_attribute_info {
    CSSM_DB_ATTRIBUTE_NAME_FORMAT AttributeNameFormat;
    union cssm_db_attribute_label {
        char * AttributeName;         /* e.g., "record label" */
        CSSM_OID 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.

AttributeFormat

Indicates the format of the attribute.The Data Storage Library may not support more than one format, typically CSSM_DB_ATTRIBUTE_FORMAT_STRING. In this case, the library module can ignore any format specification provided by the caller.

CSSM_DB_ATTRIBUTE_DATA

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

typedef struct cssm_db_attribute_data {
    CSSM_DB_ATTRIBUTE_INFO Info;
    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

These constants partition the space of record type names into three primary groups:

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 + 94)


/* 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 + 6)


/* 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
CSSM_DL_DB_SCHEMA_RELATIONS is a relation containing one record for each relation defined for the database. All fields are searchable. RecordType is the primary database key for this relation.

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

  Field Name Field Data Type Comment
* RelationID UINT32 A unique integer value identifying a relation.
  RelationName STRING The relation name in ASCII text.

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.

  Field Name Field Data Type Comment
* RelationID UINT32 A unique integer value identifying a relation.
* AttributeID UINT32 A number identifying an attribute in the relation identified by (RelationId)
  AttributeNameFormat UINT32 Format of AttributeName
  AttributeName STRING Name of attribute
  AttributeNameID BLOB Name of attribute expressed as an infinite precision number (aka OID).
  AttributeFormat UINT32 Data type of values associated with the attribute

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.

  Field Name Field Data Type Comment
* RelationID UINT32 A unique integer value identifying a relation.
* IndexID UINT32 A number uniquely identifying an index. Unique indexes will use the same IndexID for each attribute (AttributeID) comprising the concatenated key of the unique index.
* AttributeID UINT32 An integer value uniquely identifying an attribute within the relation identified by RelationID.
  IndexType UINT32 Type of index (part of the unique index or a non-unique index).
  IndexedDataLocation UINT32 Source of the information used to create the index

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.

  Field Name Field Data Type Comment
* RelationID UINT32 A unique integer value identifying a relation.
* AttributeID UINT32 Attribute to which the parsing module is associated.
  ModuleID BLOB GUID of the module used to parse the data object
  AddinVersion STRING Version of the module used to parse the data object
  SSID UINT32 SubserviceID of the subservice used to parse the data object
  SubserviceType UINT32 Type of module used to parse the data object

Definitions for Open Group Application Record Types
The meaning of each record types is defined as follows:

Record Type CSSM Type Comment
CSSM_DL_DB_RECORD_CERT CSSM_DATA An opaque structure whose format is defined by the type of certificate stored in the structure.
CSSM_DL_DB_RECORD_CRL CSSM_DATA An opaque structure whose format is defined by the type of CRL stored in the structure.
CSSM_DL_DB_RECORD_POLICY CSSM_DATA An opaque structure whose format is defined by the type of policy stored in the structure.
CSSM_DL_DB_RECORD_GENERIC CSSM_DATA An opaque structure whose format is defined by agreement between the application and the service provider module
CSSM_DL_DB_RECORD_PUBLIC_KEY CSSM_KEY A CSSM_KEY structure with an instantiated CSSM_KEY_HEADER describing the attributes of the key.
CSSM_DL_DB_RECORD_PRIVATE_KEY CSSM_KEY A CSSM_KEY structure with an instantiated CSSM_KEY_HEADER describing the attributes of the key.
CSSM_DL_DB_RECORD_SYMMETRIC_KEY CSSM_KEY A CSSM_KEY structure with an instantiated CSSM_KEY_HEADER describing the attributes of the key.
CSSM_DL_DB_RECORD_ALL_KEYS CSSM_KEY A CSSM_KEY structure with an instantiated CSSM_KEY_HEADER describing the attributes of the key.

Schema for DL Records of Type CSSM_DL_DB_RECORD_CERT
The following schema defines the set of attributes for DL records of type CSSM_DL_DB_RECORD_CERT.

Attribute Name Attribute Type Attribute Description
CertType CSSM_CERT_TYPE One of the values defined for CSSM_CERT_TYPE.
CertEncoding CSSM_CERT_ENCODING One of the values defined for CSSM_CERT_ENCODING.
PrintName CSSM_Data
(max length 16 characters) 		The PrintName attribute required in all DL-stored records.
Alias CSSM_Data
(max length 8 bytes) 		The Alias attribute required in all DL-stored records.

Schema for DL Records of Type CSSM_DL_DB_RECORD_CRL
The following schema defines the set of attributes for DL records of type CSSM_DL_DB_RECORD_CRL.

Attribute Name Attribute Type Attribute Description
CrlType CSSM_CRL_TYPE One of the values defined for CSSM_CRL_TYPE.
CrlEncoding CSSM_CRL_ENCODING One of the values defined for CSSM_CRL_ENCODING.
PrintName CSSM_Data
(max length 16 characters) 		The PrintName attribute required in all DL-stored records.
Alias CSSM_Data
(max length 8 bytes) 		The Alias attribute required in all DL-stored records.


Schema for DL Records of Type CSSM_DL_DB_RECORD_POLICY
The following schema defines the set of attributes for DL records of type CSSM_DL_DB_RECORD_POLICY.

Attribute Name Attribute Type Attribute Description
PolicyName CSSM_OID One of the values defined by the policy domain.
PrintName CSSM_Data
(max length 16 characters) 		The PrintName attribute required in all DL-stored records.
Alias CSSM_Data
(max length 8 bytes) 		The Alias attribute required in all DL-stored records.

Schema for DL Records of Type CSSM_DL_DB_RECORD_GENERIC
The following schema defines the set of attributes for DL records of type CSSM_DL_DB_RECORD_GENERIC.

Attribute Name Attribute Type Attribute Description
PrintName CSSM_Data
(max length 16 characters) 		The PrintName attribute required in all DL-stored records.
Alias CSSM_Data
(max length 8 bytes) 		The Alias attribute required in all DL-stored records.

Schema for DL Records of Type KEY
The following schema defines the set of attributes for DL records of type CSSM_DL_DB_RECORD_PUBLIC_KEY, CSSM_DL_DB_RECORD_PRIVATE_KEY, and CSSM_DL_DB_RECORD_SYMMETRIC_KEY.

Attribute Name Attribute Type Attribute Description
KeyClass CSSM_DB_RECORDTYPE One of the following values:
CSSM_DL_DB_RECORD_PUBLIC_KEY,
CSSM_DL_DB_RECORD_PRIVATE_KEY,
CSSM_DL_DB_RECORD_SYMMETRIC_KEY
PrintName CSSM_Data
(max length 16 characters) 		The PrintName attribute required in all DL-stored records. This attribute could be replaced by the value of Label attribute.
Alias CSSM_Data
(max length 8 bytes) 		The Alias attribute required in all DL-stored records. This attribute could be replaced by the value of ApplicationTag attribute.
Permanent CSSM_BOOL Indicates whether the key is stored permanently or temporarily in the device.
Private CSSM_BOOL Indicates whether user authentication is required to access the key.
Modifiable CSSM_BOOL Attributes describing the key can be modified
Label CSSM_DATA User-defined label assigned by the user who created the key.
ApplicationTag CSSM_DATA Application-defined string assigned by the application creating the key.
KeyCreator CSSM_GUID GUID of the CSP that created the key. This could be a virtual attribute for a multi-service provider with CSP and DL in one module.
KeyType CSSM_ALGORITHMS Algorithm Identifier for a key type
KeySizeInBits uint32 Size of the key in bits
EffectiveKeySize uint32 Effective size of the key. This could be a virtual attribute that is computed on demand.
StartDate CSSM_DATE Starting validity date
EndDate CSSM_DATE Ending validity date
Sensitive CSSM_BOOL Key can not be revealed outside of the device in an unwrapped state
AlwaysSensitive CSSM_BOOL The Sensitive attribute has always been CSSM_TRUE, and the key was generated by the CSP.
Extractable CSSM_BOOL Key can be removed from the token in wrapped or unwrapped form
NeverExtractable CSSM_BOOL The Extractable attribute has never been CSSM_TRUE
Encrypt CSSM_BOOL Key is usable for encryption
Decrypt CSSM_BOOL Key is usable for decryption
Derive CSSM_BOOL Key is usable for derivation
Sign CSSM_BOOL Key is usable for signature or MAC generation
Verify CSSM_BOOL Key is usable for signature verification
SignRecover CSSM_BOOL Key is usable to generate signatures with message recovery (private key encrypt)
VerifyRecover CSSM_BOOL Key is usable to verify signatures with message recovery (public key decrypt)
Wrap CSSM_BOOL Key can be used to wrap other keys
Unwrap CSSM_BOOL Key can be used to unwrap other keys

CSSM_DB_CERTRECORD_SEMANTICS

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

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

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

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

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

CSSM_DB_RECORD_ATTRIBUTE_INFO

This structure contains the meta information or schema information about all of the attributes in a particular record type. The description specifies the record type, the number of attributes in the record type, and a type information for each attribute. 

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

DataRecordType

A CSSM_DB_RECORDTYPE.

NumberOfAttributes

The number of attributes in a record of the specified type.

AttributeInfo

A list of pointers to the type (schema) information for each of the attributes.

CSSM_DB_RECORD_ATTRIBUTE_DATA

This structure aggregates the actual data values for all of the attributes in a single record. The structure includes the record type, optional semantic information on how the record can and cannot be used, the number of attributes in the records, and the actual data value for each attribute. 

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

DataRecordType

A CSSM_DB_RECORDTYPE.

SemanticInformation

A bit mask of type CSSM_XXXRECORD_SEMANTICS defining how the record can be used. Currently these bit masks are defined only for CSSM_CERTRECORD_SEMANTICS. For all other records types, a bit masks of zero must be used or a set of semantically meaning masks must be defined.

NumberOfAttributes

The number of attributes in a record of the specified type.

AttributeData

A list of pointers to data values, one per attribute. If no stored value is associated with this attribute, the attribute data pointer is NULL.

CSSM_DB_PARSING_MODULE_INFO

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

typedef 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

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

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

CSSM_DB_INDEXED_DATA_LOCATION

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

typedef enum cssm_db_indexed_data_location {
    CSSM_DB_INDEX_ON_UNKNOWN = 0,
    CSSM_DB_INDEX_ON_ATTRIBUTE = 1,
    CSSM_DB_INDEX_ON_RECORD = 2
} CSSM_DB_INDEXED_DATA_LOCATION;

CSSM_DB_INDEX_INFO

This structure contains the meta information or schema description of an index defined on an attribute. The description includes the type of index (for example, unique key or non-unique key), the logical location of the indexed attribute in the CSSM record (for example, an attribute or a field within the opaque object in the record), and the meta information on the attribute itself. The primary key is formed by concatenating the attributes specifying the unique indexes. Non-unique indexes can only be on multiple single attributes. 

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

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

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

RecordLocator

The information describing how to locate the record efficiently.

RecordIdentifier

A module-specific identifier which will allow the DL to locate this record.

CSSM_DB_RECORD_INDEX_INFO

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

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

DataRecordType

A CSSM_DB_RECORDTYPE.

NumberOfIndexes

The number of indexes defined on the record of the given type.

IndexInfo

An array containing a description of each index defined over the specified record type.

CSSM_DB_ACCESS_TYPE

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

typedef uint32 CSSM_DB_ACCESS_TYPE, *CSSM_DB_ACCESS_TYPE_PTR;

#define CSSM_DB_ACCESS_READ (0x00001)
#define CSSM_DB_ACCESS_WRITE (0x00002)
#define CSSM_DB_ACCESS_PRIVILEGED (0x00004) /* versus user mode */

CSSM_DB_MODIFY_MODE

Constants of this type define the types of modifications that can be performed on record attributes using the function CSSM_DL_DataModify(). 

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

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

typedef struct cssm_dbinfo {
      /* meta information about each record type stored in this
      data store including meta information about record
      attributes and indexes */
    uint32 NumberOfRecordTypes;
    CSSM_DB_PARSING_MODULE_INFO_PTR DefaultParsingModules;
    CSSM_DB_RECORD_ATTRIBUTE_INFO_PTR RecordAttributeNames;
    CSSM_DB_RECORD_INDEX_INFO_PTR RecordIndexes;
               /* access restrictions for opening this data store */
    CSSM_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

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

typedef enum cssm_db_operator {
    CSSM_DB_EQUAL = 0,
    CSSM_DB_NOT_EQUAL = 1,
    CSSM_DB_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.

Operator Description CSSM_DB_
ATTRIBUTE_FORMAT
CSSM_DB_EQUAL Is the predicate equal to the attribute All
CSSM_DB_NOT_EQUAL Is the predicate not equal to the attribute All
CSSM_DB_LESS_THAN Is the predicate less than the attribute All, except Multi-Uint32, Blob, and Complex
CSSM_DB_GREATER_THAN Is the predicate greater than the attribute All, except Multi-Uint32, Blob, and Complex
CSSM_DB_CONTAINS Is the predicate contained in the attribute String, Blob, Multi-Uint32
CSSM_DB_CONTAINS_INITIAL_SUBSTRING Is the start of the attribute equal to the predicate String, Blob, Multi-Uint32
CSSM_DB_CONTAINS_FINAL_SUBSTRING Is the end of the attribute equal to the predicate String, Blob, Multi-Uint32

CSSM_DB_CONJUNCTIVE

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

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

CSSM_SELECTION_PREDICATE

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

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

DbOperator

The relational operator to be used when comparing a value to the values stored in the specified attribute in the data store.

Attribute

The meta information about the attribute to be searched and the attribute value to be used for comparison with values in the data store.

CSSM_QUERY_LIMITS

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

#define CSSM_QUERY_TIMELIMIT_NONE 0
#define CSSM_QUERY_SIZELIMIT_NONE 0

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

TimeLimit

Defines the maximum number of seconds of resource time that should be expended performing a query operation. The constant value CSSM_QUERY_TIMELIMIT_NONE means no time limit is specified. All specific time values must be greater than zero, as any query requires greater than zero time to execute.

SizeLimit

Defines the maximum number of records that should be retrieved in response to a single query. The constant value CSSM_QUERY_SIZELIMIT_NONE means no space limit is specified. All specific space values must be greater than zero, as any query requires greater than zero space in which to execute.

CSSM_QUERY_FLAGS

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

typedef uint32 CSSM_QUERY_FLAGS;

#define CSSM_QUERY_RETURN_DATA (0x01)

Flag Identifier Meaning
CSSM_QUERY_RETURN_DATA Valid for key records only. If this flag is set, the DL will attempt to return a CSSM_KEY structure with the actual key material as plaintext. If it is not set, then the DL will return a CSSM_KEY structure with a key reference.

CSSM_QUERY

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

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

RecordType

Specifies the type of record to be retrieved from the data store.

Conjunctive

The conjunctive operator to be used in constructing the selection predicate for the query.

NumSelectionPredicates

The number of selection predicates to be connected by the specified conjunctive operator to form the query.

SelectionPredicate

The list of selection predicates to be combined by the conjunctive operator to form the data store query.

QueryLimits

Defines the time and space limits for processing the selection query. The constant values CSSM_QUERY_TIMELIMIT_NONE and CSM_QUERY_SIZELIMIT_NONE should be used to specify no limit on the resources used in processing the query.

QueryFlags

Query-related requests from the application.

CSSM_DLTYPE

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

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

CSSM_DL_PKCS11_ATTRIBUTES

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

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

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

DeviceAccessFlags

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

CSSM_DB_DATASTORES_UNKNOWN

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

#define CSSM_DB_DATASTORES_UNKNOWN (0xFFFFFFFF)

CSSM_NAME_LIST

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

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

NumStrings

Number of strings in the array pointed to by String.

String

A pointer to an array of strings.

CSSM_DB_RETRIEVAL_MODES

This defines the retrieval modes for CSSM_DL_DataGetFirst() operations. The data storage module supports one of two retrieval models: 

#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

This section defines Error Values that can be returned by DL operations.

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)

DL Error Values Derived from ACL-based Error Codes

This section lists DL error values derived from convertible ACL-based error codes. 

#define CSSM_DL_OPERATION_AUTH_DENIED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OPERATION_AUTH_DENIED)	
#define CSSM_DL_OBJECT_USE_AUTH_DENIED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OBJECT_USE_AUTH_DENIED)
#define CSSM_DL_OBJECT_MANIP_AUTH_DENIED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OBJECT_MANIP_AUTH_DENIED)
#define CSSM_DL_OBJECT_ACL_NOT_SUPPORTED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OBJECT_ACL_NOT_SUPPORTED)
#define CSSM_DL_OBJECT_ACL_REQUIRED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OBJECT_ACL_REQUIRED)
#define CSSM_DL_INVALID_ACCESS_CREDENTIALS \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACCESS_CREDENTIALS)
#define CSSM_DL_INVALID_ACL_BASE_CERTS \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_BASE_CERTS)
#define CSSM_DL_ACL_BASE_CERTS_NOT_SUPPORTED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_BASE_CERTS_NOT_SUPPORTED)
#define CSSM_DL_INVALID_SAMPLE_VALUE \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_SAMPLE_VALUE)
#define CSSM_DL_SAMPLE_VALUE_NOT_SUPPORTED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_SAMPLE_VALUE_NOT_SUPPORTED)
#define CSSM_DL_INVALID_ACL_SUBJECT_VALUE \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_SUBJECT_VALUE)
#define CSSM_DL_ACL_SUBJECT_TYPE_NOT_SUPPORTED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_SUBJECT_TYPE_NOT_SUPPORTED)
#define CSSM_DL_INVALID_ACL_CHALLENGE_CALLBACK \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_CHALLENGE_CALLBACK)
#define CSSM_DL_ACL_CHALLENGE_CALLBACK_FAILED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_CHALLENGE_CALLBACK_FAILED)
#define CSSM_DL_INVALID_ACL_ENTRY_TAG \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_ENTRY_TAG)
#define CSSM_DL_ACL_ENTRY_TAG_NOT_FOUND \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_ENTRY_TAG_NOT_FOUND)
#define CSSM_DL_INVALID_ACL_EDIT_MODE \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_EDIT_MODE)
#define CSSM_DL_ACL_CHANGE_FAILED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_CHANGE_FAILED)
#define CSSM_DL_INVALID_NEW_ACL_ENTRY \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_NEW_ACL_ENTRY)
#define CSSM_DL_INVALID_NEW_ACL_OWNER \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_NEW_ACL_OWNER)
#define CSSM_ DL_ACL_DELETE_FAILED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_DELETE_FAILED)
#define CSSM_ DL_ACL_REPLACE_FAILED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_REPLACE_FAILED)
#define CSSM_ DL_ACL_ADD_FAILED \
    (CSSM_DL_BASE_ERROR+CSSM_ERRCODE_ACL_ADD_FAILED)

DL Error Values for Specific Data Types

This section lists DL error values derived from Common Error Codes 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)

General DL Error Values

These values can be returned from any DL function. 


#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)
The database file or other data form is corrupt

DL Specific Error Values 


#define CSSMERR_DL_INVALID_RECORD_INDEX	(CSSM_DL_BASE_DL_ERROR+8)
A record index in the DbInfo structure is invalid 


#define CSSMERR_DL_INVALID_RECORDTYPE (CSSM_DL_BASE_DL_ERROR+9)
Record types from DbInfo's arrays do not match 


#define CSSMERR_DL_INVALID_FIELD_NAME (CSSM_DL_BASE_DL_ERROR+10)
Attribute or index name is an illegal name 


#define CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT (CSSM_DL_BASE_DL_ERROR+11)
A field's format (data type) is not supported 


#define CSSMERR_DL_UNSUPPORTED_INDEX_INFO (CSSM_DL_BASE_DL_ERROR+12)
Requested IndexInfo struct is not supported 


#define CSSMERR_DL_UNSUPPORTED_LOCALITY	(CSSM_DL_BASE_DL_ERROR+13)
The value of DbInfo->IsLocal is not supported 


#define CSSMERR_DL_UNSUPPORTED_NUM_ATTRIBUTES (CSSM_DL_BASE_DL_ERROR+14)
Unsupported number of attributes specified 


#define CSSMERR_DL_UNSUPPORTED_NUM_INDEXES (CSSM_DL_BASE_DL_ERROR+15)
Unsupported number of indexes 


#define CSSMERR_DL_UNSUPPORTED_NUM_RECORDTYPES (CSSM_DL_BASE_DL_ERROR+16)
Unsupported number of record types 


#define CSSMERR_DL_UNSUPPORTED_RECORDTYPE (CSSM_DL_BASE_DL_ERROR+17)
Requested record type is not supported 


#define CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE (CSSM_DL_BASE_DL_ERROR+18)
A record attribute or index was specified multiple times with differing information 


#define CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT (CSSM_DL_BASE_DL_ERROR+19)
The field format for an index from an attribute is different from the field format of that attribute 


#define CSSMERR_DL_INVALID_PARSING_MODULE (CSSM_DL_BASE_DL_ERROR+20)
A parsing module in the DB Info is invalid 


#define CSSMERR_DL_INVALID_DB_NAME (CSSM_DL_BASE_DL_ERROR+22)
The Database name is invalid. 


#define CSSMERR_DL_DATASTORE_DOESNOT_EXIST (CSSM_DL_BASE_DL_ERROR+23)
The specified datastore does not exists 


#define CSSMERR_DL_DATASTORE_ALREADY_EXISTS (CSSM_DL_BASE_DL_ERROR+24)
The specified datastore already exists 


#define CSSMERR_DL_DB_LOCKED (CSSM_DL_BASE_DL_ERROR+25)
Database is currently locked for exclusive update 


#define CSSMERR_DL_DATASTORE_IS_OPEN (CSSM_DL_BASE_DL_ERROR+26)
The database is currently open 


#define CSSMERR_DL_RECORD_NOT_FOUND (CSSM_DL_BASE_DL_ERROR+27)
The record does not exist 


#define CSSMERR_DL_MISSING_VALUE (CSSM_DL_BASE_DL_ERROR+28)
Missing needed attribute or data value 


#define CSSMERR_DL_UNSUPPORTED_QUERY (CSSM_DL_BASE_DL_ERROR+29)
An unsupported query was specified 


#define CSSMERR_DL_UNSUPPORTED_QUERY_LIMITS (CSSM_DL_BASE_DL_ERROR+30)
The requested query limits are not supported 


#define CSSMERR_DL_UNSUPPORTED_NUM_SELECTION_PREDS \
    (CSSM_DL_BASE_DL_ERROR+31)
The number of selection predicates is not supported 


#define CSSMERR_DL_UNSUPPORTED_OPERATOR	(CSSM_DL_BASE_DL_ERROR+33)
An unsupported operator was requested 


#define CSSMERR_DL_INVALID_RESULTS_HANDLE (CSSM_DL_BASE_DL_ERROR+34)
Invalid results handle 


#define CSSMERR_DL_INVALID_DB_LOCATION (CSSM_DL_BASE_DL_ERROR+35)
The Database Location is not valid 


#define CSSMERR_DL_INVALID_ACCESS_REQUEST (CSSM_DL_BASE_DL_ERROR+36)
Unrecognized access type 


#define CSSMERR_DL_INVALID_INDEX_INFO (CSSM_DL_BASE_DL_ERROR+37)
Invalid index information passed 


#define CSSMERR_DL_INVALID_SELECTION_TAG (CSSM_DL_BASE_DL_ERROR+38)
Invalid selection tag 


#define CSSMERR_DL_INVALID_NEW_OWNER (CSSM_DL_BASE_DL_ERROR+39)
Owner definition is invalid 


#define CSSMERR_DL_INVALID_RECORD_UID (CSSM_DL_BASE_DL_ERROR+40)
The data inside the unique record identifier is not valid 


#define CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA (CSSM_DL_BASE_DL_ERROR+41)
The modification would have caused the new primary key to have a value that is already in use 


#define CSSMERR_DL_INVALID_MODIFY_MODE (CSSM_DL_BASE_DL_ERROR+42)
The specified modification mode is undefined or could not be applied to the record attributes identified for modification. 


#define CSSMERR_DL_INVALID_OPEN_PARAMETERS (CSSM_DL_BASE_DL_ERROR+43)
The open parameters are not valid 


#define CSSMERR_DL_EXISTING_RECORD_UPDATED (CSSM_DL_BASE_DL_ERROR+44)
The value of the new record's primary key was found in another record, that record was updated successfully. 


#define CSSMERR_DL_ENDOFDATA (CSSM_DL_BASE_DL_ERROR+45)
There are no more records satisfying the query.

Data Storage Functions

The man-page definitions for Data Storage functions are presented in this section.
Previous section.

Click here to return to the publication details.

NAME

CSSM_DL_DbOpen

SYNOPSIS


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)

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

CSSM_DL_DbClose()
Previous section.

NAME

CSSM_DL_DbClose

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE

SEE ALSO


CSSM_DL_DbOpen()
Previous section.

NAME

CSSM_DL_DbCreate

SYNOPSIS


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)

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:

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 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 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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_DATASTORE_ALREADY_EXISTS
CSSMERR_DL_INVALID_ACCESS_REQUEST
CSSMERR_DL_INVALID_DB_LOCATION
CSSMERR_DL_INVALID_DB_NAME
CSSMERR_DL_INVALID_OPEN_PARAMETERS
CSSMERR_DL_INVALID_RECORD_INDEX
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_FIELD_NAME
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
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_PARSING_MODULE

SEE ALSO


CSSM_DL_DbOpen()
CSSM_DL_DbClose()
CSSM_DL_DbDelete()
Previous section.

NAME

CSSM_DL_DbDelete

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_DATASTORE_IS_OPEN
CSSMERR_DL_INVALID_DB_LOCATION
CSSMERR_DL_INVALID_DB_NAME
CSSMERR_DL_DATASTORE_DOESNOT_EXIST

SEE ALSO


CSSM_DL_DbCreate()
CSSM_DL_DbOpen()
CSSM_DL_DbClose()
Previous section.

NAME

CSSM_DL_CreateRelation

SYNOPSIS


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)

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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_INDEX_INFO
CSSMERR_DL_INVALID_ATTRIBUTE_INFO

SEE ALSO

CSSM_DL_DestroyRelation()
Previous section.

NAME

CSSM_DL_DestroyRelation

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RECORDTYPE

SEE ALSO

CSSM_DL_CreateRelation()
Previous section.

NAME

CSSM_DL_Authenticate

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_INVALID_ACCESS_REQUEST
CSSMERR_DL_INVALID_DB_HANDLE

Previous section.

NAME

CSSM_DL_GetDbAcl

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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:

The public ACL entry information returned by this function includes:

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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE

SEE ALSO

CSSM_DL_ChangeDbAcl()
Previous section.

NAME

CSSM_DL_ChangeDbAcl

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE

SEE ALSO

CSSM_DL_GetDbAcl()
Previous section.

NAME

CSSM_DL_GetDbOwner

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE

SEE ALSO

CSSM_DL_ChangeDbOwner()
Previous section.

NAME

CSSM_DL_ChangeDbOwner

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_NEW_OWNER

SEE ALSO

CSSM_DL_GetDbOwner()
Previous section.

NAME

CSSM_DL_GetDbNames

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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


CSSM_DL_GetDbNameFromHandle()
CSSM_DL_FreeNameList()
Previous section.

NAME

CSSM_DL_GetDbNameFromHandle

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_DL_INVALID_DB_HANDLE

SEE ALSO


CSSM_DL_GetDbNames()
Previous section.

NAME

CSSM_DL_FreeNameList

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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


CSSM_DL_GetDbNames()

Data Record Operations

The man-page definitions for Data Record operations are presented in this section.
Previous section.

NAME

CSSM_DL_DataInsert

SYNOPSIS


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)

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 (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_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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_EXISTING_RECORD_UPDATED
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_PARSING_MODULE
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_MISSING_VALUE
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_FIELD_NAME

SEE ALSO


CSSM_DL_DataDelete()
Previous section.

NAME

CSSM_DL_DataDelete

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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.

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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_RECORD_NOT_FOUND
CSSMERR_DL_INVALID_RECORD_UID

SEE ALSO


CSSM_DL_DataInsert()
Previous section.

NAME

CSSM_DL_DataModify

SYNOPSIS


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)

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 representation 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, specified 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 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 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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA
CSSMERR_DL_INVALID_MODIFY_MODE
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_FIELD_NAME

SEE ALSO


CSSM_DL_DataInsert()
CSSM_DL_DataDelete()
Previous section.

NAME

CSSM_DL_DataGetFirst

SYNOPSIS


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)

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

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 or 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).

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 also the Error Codes and Error Values section earlier in this Chapter.


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

SEE ALSO


CSSM_DL_DataGetNext()
CSSM_DL_DataAbortQuery()
Previous section.

NAME

CSSM_DL_DataGetNext

SYNOPSIS


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)

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. Pre-allocated buffers must be of sufficient size to hold the retrieved attributes and data. 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. 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)

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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RESULTS_HANDLE
CSSMERR_DL_ENDOFDATA
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_FIELD_NAME

SEE ALSO


CSSM_DL_DataGetFirst()
CSSM_DL_DataAbortQuery()
Previous section.

NAME

CSSM_DL_DataAbortQuery

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RESULTS_HANDLE

SEE ALSO


CSSM_DL_DataGetFirst()
CSSM_DL_DataGetNext()
Previous section.

NAME

CSSM_DL_DataGetFromUniqueRecordId

SYNOPSIS


CSSM_RETURN CSSMAPI 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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_FIELD_NAME

SEE ALSO


CSSM_DL_DataInsert()
CSSM_DL_DataGetFirst()
CSSM_DL_DataGetNext()
Previous section.

NAME

CSSM_DL_FreeUniqueRecord

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RECORD_UID

SEE ALSO


CSSM_DL_DataInsert()
CSSM_DL_DataGetFirst()
CSSM_DL_DataGetNext()

Extensibility Functions

The man-page defining the CSSM_DL_PassThrough() extensibility function is presented in this section.
Previous section.

NAME

CSSM_DL_PassThrough

SYNOPSIS


CSSM_RETURN CSSMAPI 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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_PASSTHROUGH_ID

Contents Next section Index