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
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.
typedef CSSM_MODULE_HANDLE CSSM_DL_HANDLE; /* data storage library Handle */
typedef CSSM_MODULE_HANDLE CSSM_DB_HANDLE; /* Data storage Handle */
typedef struct cssm_dl_db_handle {
CSSM_DL_HANDLE DLHandle;
CSSM_DB_HANDLE DBHandle;
} CSSM_DL_DB_HANDLE, *CSSM_DL_DB_HANDLE_PTR;
typedef struct cssm_dl_db_list {
uint32 NumHandles;
CSSM_DL_DB_HANDLE_PTR DLDBHandle;
} CSSM_DL_DB_LIST, *CSSM_DL_DB_LIST_PTR;
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;
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;
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;
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;
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)
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 |
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. |
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. |
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. |
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. |
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. |
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 |
#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 |
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;
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;
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;
typedef enum cssm_db_index_type {
CSSM_DB_INDEX_UNIQUE = 0,
CSSM_DB_INDEX_NONUNIQUE = 1
} CSSM_DB_INDEX_TYPE;
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;
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;
typedef struct cssm_db_unique_record {
CSSM_DB_INDEX_INFO RecordLocator;
CSSM_DATA RecordIdentifier;
} CSSM_DB_UNIQUE_RECORD, *CSSM_DB_UNIQUE_RECORD_PTR;
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;
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 */
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)
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;
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 |
typedef enum cssm_db_conjunctive{
CSSM_DB_NONE = 0,
CSSM_DB_AND = 1,
CSSM_DB_OR = 2
} CSSM_DB_CONJUNCTIVE, *CSSM_DB_CONJUNCTIVE_PTR;
typedef struct cssm_selection_predicate {
CSSM_DB_OPERATOR DbOperator;
CSSM_DB_ATTRIBUTE_DATA Attribute;
} CSSM_SELECTION_PREDICATE, *CSSM_SELECTION_PREDICATE_PTR;
#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;
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. |
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;
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;
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;
#define CSSM_DB_DATASTORES_UNKNOWN (0xFFFFFFFF)
typedef struct cssm_name_list {
uint32 NumStrings;
char** String;
} CSSM_NAME_LIST, *CSSM_NAME_LIST_PTR;
#define CSSM_DB_TRANSACTIONAL_MODE (0)
#define CSSM_DB_FILESYSTEMSCAN_MODE (1)
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;
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;
The Error Values that
can be returned by DL functions can be either derived from
the Common Error Codes defined in
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.
#define CSSMERR_DL_INTERNAL_ERROR \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INTERNAL_ERROR)
#define CSSMERR_DL_MEMORY_ERROR \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_MEMORY_ERROR)
#define CSSMERR_DL_MDS_ERROR \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_MDS_ERROR)
#define CSSMERR_DL_INVALID_POINTER \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_POINTER)
#define CSSMERR_DL_INVALID_INPUT_POINTER \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_INPUT_POINTER)
#define CSSMERR_DL_INVALID_OUTPUT_POINTER \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_OUTPUT_POINTER)
#define CSSMERR_DL_FUNCTION_NOT_IMPLEMENTED \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_FUNCTION_NOT_IMPLEMENTED)
#define CSSMERR_DL_SELF_CHECK_FAILED \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_SELF_CHECK_FAILED)
#define CSSMERR_DL_OS_ACCESS_DENIED \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_OS_ACCESS_DENIED)
#define CSSMERR_DL_FUNCTION_FAILED \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_FUNCTION_FAILED)
#define 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)
#define CSSMERR_DL_INVALID_DB_HANDLE \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_DB_HANDLE)
#define CSSMERR_DL_INVALID_PASSTHROUGH_ID \
(CSSM_DL_BASE_ERROR+CSSM_ERRCODE_INVALID_PASSTHROUGH_ID)
#define CSSM_DL_BASE_DL_ERROR \
(CSSM_DL_BASE_ERROR+CSSM_ERRORCODE_COMMON_EXTENT)
#define CSSMERR_DL_DATABASE_CORRUPT (CSSM_DL_BASE_DL_ERROR+1)
#define CSSMERR_DL_INVALID_RECORD_INDEX (CSSM_DL_BASE_DL_ERROR+8)
#define CSSMERR_DL_INVALID_RECORDTYPE (CSSM_DL_BASE_DL_ERROR+9)
#define CSSMERR_DL_INVALID_FIELD_NAME (CSSM_DL_BASE_DL_ERROR+10)
#define CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT (CSSM_DL_BASE_DL_ERROR+11)
#define CSSMERR_DL_UNSUPPORTED_INDEX_INFO (CSSM_DL_BASE_DL_ERROR+12)
#define CSSMERR_DL_UNSUPPORTED_LOCALITY (CSSM_DL_BASE_DL_ERROR+13)
#define CSSMERR_DL_UNSUPPORTED_NUM_ATTRIBUTES (CSSM_DL_BASE_DL_ERROR+14)
#define CSSMERR_DL_UNSUPPORTED_NUM_INDEXES (CSSM_DL_BASE_DL_ERROR+15)
#define CSSMERR_DL_UNSUPPORTED_NUM_RECORDTYPES (CSSM_DL_BASE_DL_ERROR+16)
#define CSSMERR_DL_UNSUPPORTED_RECORDTYPE (CSSM_DL_BASE_DL_ERROR+17)
#define CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE (CSSM_DL_BASE_DL_ERROR+18)
#define CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT (CSSM_DL_BASE_DL_ERROR+19)
#define CSSMERR_DL_INVALID_PARSING_MODULE (CSSM_DL_BASE_DL_ERROR+20)
#define CSSMERR_DL_INVALID_DB_NAME (CSSM_DL_BASE_DL_ERROR+22)
#define CSSMERR_DL_DATASTORE_DOESNOT_EXIST (CSSM_DL_BASE_DL_ERROR+23)
#define CSSMERR_DL_DATASTORE_ALREADY_EXISTS (CSSM_DL_BASE_DL_ERROR+24)
#define CSSMERR_DL_DB_LOCKED (CSSM_DL_BASE_DL_ERROR+25)
#define CSSMERR_DL_DATASTORE_IS_OPEN (CSSM_DL_BASE_DL_ERROR+26)
#define CSSMERR_DL_RECORD_NOT_FOUND (CSSM_DL_BASE_DL_ERROR+27)
#define CSSMERR_DL_MISSING_VALUE (CSSM_DL_BASE_DL_ERROR+28)
#define CSSMERR_DL_UNSUPPORTED_QUERY (CSSM_DL_BASE_DL_ERROR+29)
#define CSSMERR_DL_UNSUPPORTED_QUERY_LIMITS (CSSM_DL_BASE_DL_ERROR+30)
#define CSSMERR_DL_UNSUPPORTED_NUM_SELECTION_PREDS \
(CSSM_DL_BASE_DL_ERROR+31)
#define CSSMERR_DL_UNSUPPORTED_OPERATOR (CSSM_DL_BASE_DL_ERROR+33)
#define CSSMERR_DL_INVALID_RESULTS_HANDLE (CSSM_DL_BASE_DL_ERROR+34)
#define CSSMERR_DL_INVALID_DB_LOCATION (CSSM_DL_BASE_DL_ERROR+35)
#define CSSMERR_DL_INVALID_ACCESS_REQUEST (CSSM_DL_BASE_DL_ERROR+36)
#define CSSMERR_DL_INVALID_INDEX_INFO (CSSM_DL_BASE_DL_ERROR+37)
#define CSSMERR_DL_INVALID_SELECTION_TAG (CSSM_DL_BASE_DL_ERROR+38)
#define CSSMERR_DL_INVALID_NEW_OWNER (CSSM_DL_BASE_DL_ERROR+39)
#define CSSMERR_DL_INVALID_RECORD_UID (CSSM_DL_BASE_DL_ERROR+40)
#define CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA (CSSM_DL_BASE_DL_ERROR+41)
#define CSSMERR_DL_INVALID_MODIFY_MODE (CSSM_DL_BASE_DL_ERROR+42)
#define CSSMERR_DL_INVALID_OPEN_PARAMETERS (CSSM_DL_BASE_DL_ERROR+43)
#define CSSMERR_DL_EXISTING_RECORD_UPDATED (CSSM_DL_BASE_DL_ERROR+44)
#define CSSMERR_DL_ENDOFDATA (CSSM_DL_BASE_DL_ERROR+45)
CSSM_DL_DbOpen
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)
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.
- 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.
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.
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
CSSM_DL_DbClose()
CSSM_DL_DbClose
CSSM_RETURN CSSMAPI CSSM_DL_DbClose (CSSM_DL_DB_HANDLE DLDBHandle)
This function closes an open data store.
- 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.
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.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_DL_INVALID_DB_HANDLE
CSSM_DL_DbOpen()
CSSM_DL_DbCreate
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)
This function creates and opens a new data store. The name of the new data store is specified by the input parameter DbName. The record schema for the data store is specified in the DBINFO structure. If any RecordType defined in the DBINFO structure does not have an associated parsing module, then the ModuleSubserviceUid specified for that record type must be zero.The newly created data store is opened under the specified access mode. If user authentication credentials are required, they must be provided. Also, additional open parameters may be required and are supplied in OpenParameters. If user authentication credentials are required, they must be provided.
Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must present a set of access credentials for authorization. Upon successfully authenticating the credentials, the template that verified the presented samples identifies the ACL entry that will be used in the authorization computation. If the caller is authorized, the new resource is created.
The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise control over its associated ACL. The caller can specify the following items for initializing an ACL entry:
- Subject - A CSSM_LIST structure, containing the type of the subject and a template value that can be used to verify samples that are presented in credentials when resource access is requested.
- Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the AuthorizationTag. (This item only applies to public key subjects).
- Authorization tag - The set of permissions that are granted to the Subject.
- Validity period - The start time and the stop time for which the ACL entry is valid.
- ACL entry tag - A user-defined string value associated with the ACL entry.
The service provider can modify the caller-provided initial ACL entry to conform to any innate resource-access policy that the service provider may be required to enforce. If the initial ACL entry provided by the caller contains values or permissions that are not supported by the service provider, then the service provider can modify the initial ACL appropriately or can fail the request to create the new resource. Service providers list their supported AuthorizationTag values in their Module Directory Services primary record.
- 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.
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.
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
CSSM_DL_DbOpen()
CSSM_DL_DbClose()
CSSM_DL_DbDelete()
CSSM_DL_DbDelete
CSSM_RETURN CSSMAPI CSSM_DL_DbDelete (CSSM_DL_HANDLE DLHandle, const char *DbName, const CSSM_NET_ADDRESS *DbLocation, const CSSM_ACCESS_CREDENTIALS *AccessCred)
This function deletes all records from the specified data store and removes all state information associated with that data store.
- 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.
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.
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
CSSM_DL_DbCreate()
CSSM_DL_DbOpen()
CSSM_DL_DbClose()
CSSM_DL_CreateRelation
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)
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.
- 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.
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.
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
CSSM_DL_DestroyRelation()
CSSM_DL_DestroyRelation
CSSM_RETURN CSSMAPI CSSM_DL_DestroyRelation (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_RECORDTYPE RelationID)
This function destroys an existing relation of the specified type by removing its entry from the specified data store.
- 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.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RECORDTYPE
CSSM_DL_CreateRelation()
CSSM_DL_Authenticate
CSSM_RETURN CSSMAPI CSSM_DL_Authenticate (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_ACCESS_TYPE AccessRequest, const CSSM_ACCESS_CREDENTIALS *AccessCred)
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.
- 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.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_DL_INVALID_ACCESS_REQUEST
CSSMERR_DL_INVALID_DB_HANDLE
CSSM_DL_GetDbAcl
CSSM_RETURN CSSMAPI CSSM_DL_GetDbAcl (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_STRING *SelectionTag, uint32 *NumberOfAclInfos, CSSM_ACL_ENTRY_INFO_PTR *AclInfos)
This function returns a description of zero or more ACL entries managed by the data storage service provider module and associated with the target database identified by DLDBHandle.DBHandle. The optional input SelectionTag restricts the returned descriptions to those ACL entries with a matching EntryTag value. If a SelectionTag value is specified and no matches are found, zero descriptions are returned. If no SelectionTag is specified, a description of all ACL entries associated with the target data base are returned by this function.Each AclInfo structure contains:
- Public contents of an ACL entry
- ACL EntryHandle, which is a unique value defined and managed by the service provider
The public ACL entry information returned by this function includes:
- The subject type - A CSSM_LIST structure containing one element identifying the type of subject stored in the ACL entry.
- Delegation flag - A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded in Authorization
- Authorization array - A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which permission is granted to the Subject.
- Validity period - A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid.
- ACL entry tag - A CSSM_STRING containing a user-defined value associated with the ACL entry.
- 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.
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.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_DL_INVALID_DB_HANDLE
CSSM_DL_ChangeDbAcl()
CSSM_DL_ChangeDbAcl
CSSM_RETURN CSSMAPI CSSM_DL_ChangeDbAcl (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_EDIT *AclEdit)
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.
- 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.OldEntryHandleCSSM_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.
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.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_DL_INVALID_DB_HANDLE
CSSM_DL_GetDbAcl()
CSSM_DL_GetDbOwner
CSSM_RETURN CSSMAPI CSSM_DL_GetDbOwner (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_ACL_OWNER_PROTOTYPE_PTR Owner)
This function returns a CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Data Base.
- 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.
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.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_DL_INVALID_DB_HANDLE
CSSM_DL_ChangeDbOwner()
CSSM_DL_ChangeDbOwner
CSSM_RETURN CSSMAPI CSSM_DL_ChangeDbOwner (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_OWNER_PROTOTYPE *NewOwner)
This function takes a CSSM_ACL_OWNER_PROTOTYPE defining the new Owner of the Data Base.
- 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.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_NEW_OWNER
CSSM_DL_GetDbOwner()
CSSM_DL_GetDbNames
CSSM_RETURN CSSMAPI CSSM_DL_GetDbNames (CSSM_DL_HANDLE DLHandle, CSSM_NAME_LIST_PTR *NameList)
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.
- 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.
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.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_DL_GetDbNameFromHandle()
CSSM_DL_FreeNameList()
CSSM_DL_GetDbNameFromHandle
CSSM_RETURN CSSMAPI CSSM_DL_GetDbNameFromHandle (CSSM_DL_DB_HANDLE DLDBHandle, char **DbName)
This function retrieves the data source name corresponding to an opened data store handle.
- 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.
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.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_DL_INVALID_DB_HANDLE
CSSM_DL_GetDbNames()
CSSM_DL_FreeNameList
CSSM_RETURN CSSMAPI CSSM_DL_FreeNameList (CSSM_DL_HANDLE DLHandle, CSSM_NAME_LIST_PTR NameList)
This function frees the list of the logical data store names that was returned by CSSM_DL_GetDbNames.
- 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.
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.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_DL_GetDbNames()
CSSM_DL_DataInsert
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)
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.
- 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. TheCSSM_DL_FreeUniqueRecord() function must be used to deallocate this structure.
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.
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
CSSM_DL_DataDelete()
CSSM_DL_DataDelete
CSSM_RETURN CSSMAPI CSSM_DL_DataDelete (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_DB_UNIQUE_RECORD *UniqueRecordIdentifier)
This function removes the data record specified by the unique record identifier from the specified data store.
- 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.
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.
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
CSSM_DL_DataInsert()
CSSM_DL_DataModify
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)
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.
- 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.
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.
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
CSSM_DL_DataInsert()
CSSM_DL_DataDelete()
CSSM_DL_DataGetFirst
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)
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:
- Transactional - all query results are determined at initial query evaluation. Results do not change during an incremental retrieval process.
- File System Scan - query results are selected during the incremental retrieval process. Records matching the query may be added to or deleted from the underlying data store during the iterative retrieval. The caller may receive the new matching records and not received the deleted records.
The caller can determine which retrieval model is supported by examining the encapsulated product description for this data storage module.
If the query selection criteria also specifies time for space limits 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 callCSSM_DataAbortQuery() for releasing resources that CSSM uses. If all records satisfying the query have been retrieved, then query is automatically terminated.
- 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 andCSSM_DL_DataGetFirst() must return CSSM_DL_ENDOFDATA; in this case a normal termination condition has occurred. TheCSSM_DL_FreeUniqueRecord() must be used to de-allocate this structure.
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.
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
CSSM_DL_DataGetNext()
CSSM_DL_DataAbortQuery()
CSSM_DL_DataGetNext
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)
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 callCSSM_DataAbortQuery() for releasing resources that CSSM uses. If all records satisfying the query have been retrieved, then query is automatically terminated.
- 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 theCSSM_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 andCSSM_DL_DataGetFirst() must return CSSM_DL_ENDOFDATA; in this case a normal termination condition has occurred. TheCSSM_DL_FreeUniqueRecord() must be used to de-allocate this structure.
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.
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
CSSM_DL_DataGetFirst()
CSSM_DL_DataAbortQuery()
CSSM_DL_DataAbortQuery
CSSM_RETURN CSSMAPI CSSM_DL_DataAbortQuery (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_HANDLE ResultsHandle)
This function terminates the query initiated byDL_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 callCSSM_DL_DataAbortQuery() at the termination.
- 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.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RESULTS_HANDLE
CSSM_DL_DataGetFirst()
CSSM_DL_DataGetNext()
CSSM_DL_DataGetFromUniqueRecordId
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)
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.
- 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.
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.
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
CSSM_DL_DataInsert()
CSSM_DL_DataGetFirst()
CSSM_DL_DataGetNext()
CSSM_DL_FreeUniqueRecord
CSSM_RETURN CSSMAPI CSSM_DL_FreeUniqueRecord (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord)
This function frees the memory associated with the data store unique record structure.
- 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.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_RECORD_UID
CSSM_DL_DataInsert()
CSSM_DL_DataGetFirst()
CSSM_DL_DataGetNext()
CSSM_DL_PassThrough
CSSM_RETURN CSSMAPI DL_PassThrough (CSSM_DL_DB_HANDLE DLDBHandle, uint32 PassThroughId, const void *InputParams, void **OutputParams)
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.
- 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.
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.
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 |