Previous section.
Common Security: CDSA and CSSM
Copyright © 1997 The Open Group
Data Storage Library Interface
Overview
The primary purpose of a data storage library (DL) is to provide access
to persistent stores of security-related objects. The DL provides
access to these data stores by translating calls from the DLI into the
native interface of the data store. The native interface of the data
store may be that of a database management system package, a directory
service, a custom storage device, or a traditional local or remote file
system. Applications are able to obtain information about the
available DL services by using the CSSM_GetModuleInfo function to query
the CSSM registry. The information about the DL
service includes:
-
Vendor information. Information about the module vendor, a text
description of the DL and the module version number.
-
Types of supported data stores. The module may support one or more
types of persistent data stores as separate sub-services. For each
type of data store, the DL provides information on the supported query
operators and optionally provides specific information
on the accessible data stores.
The data storage library may chose to provide information about the
data stores that it has access to. Applications can obtain information
about these data stores by using the CSSM_GetModuleInfo function call.
The information about the data store includes:
-
Types of persistent security objects. The types of security objects
which may be stored include certificates, certificate revocation lists
(CRLs), keys, policy objects, and generic data objects. A single data
store can contain a single object type in one format,
a single object type in multiple formats, or multiple object types.
-
Attributes of persistent security objects. The stored security object
may have attributes which must be included by the calling application
on data insertion and which are returned by the DL on data retrieval.
-
Data store indexes. These indexes are high-performance query paths
constructed as part of data store creation and maintained by the data
store.
-
Secure Access Mechanisms. A data store may restrict a user's ability to
perform certain actions on the data store or on the data store's
contents. This structure exposes the mechanism required to
authenticate to the data store.
-
Record Integrity Capabilities. Some data stores will insure the
integrity of the data store's contents. To insure the integrity of the
data store's contents, the data store is expected to sign and verify
each record.
-
Data store location. The persistent repository can be local or remote.
To build indexes or to satisfy an application's request for record
retrieval, the data store may need to parse the stored security
objects. If the application has invoked
CSSM_DL_SetDbRecordParsingFunctions for a given security object type,
those functions will be used to parse that security object as the need
arises. If the application has not explicitly set record parsing
functions, the default add-in modules set by the data store creator
will be used for parsing.
To ensure a minimal level of interoperability among applications
and DL modules, CSSM requires that all DL modules recognize and
support two pre-defined attribute names for all record types. All
applications can use these strings as valid attribute names even
if no value is stored in association with the attribute name.
Secured access to the data store and to the data store's contents
may be enforced by the
data storage library, the data store or both. The partitioning of
authentication
responsibility is exposed via the DL and DB authentication
mechanisms available from the
CSSM registry.
Data stores may be added to a data storage library in one of three ways:
-
Using DL_DbCreate. This creates and opens a new, empty data store with
the specified schema.
-
Using DL_DbImport with information and data. If the specified data
store does not exist, a new data store is created with the specified
schema and the exported data records.
-
Using DL_DbImport with information only. In this case, the data store's
native format is the same as that managed by the DL service. Importing
its information makes it accessible via this DL service.
In all cases, it is the responsibility of the DL service to update the
CSSM registry with information about the new data store. This can be
accomplished by making use of the
CSSM_GetModuleInfo and CSSM_SetModuleInfo functions.
Categories of Operations
The data storage library SPI defines four categories of operations:
-
Data storage library operations
-
Data store operations
-
Data record operations
-
Extensibility operations
Data storage library operations are used to control access to the data
storage library. They include:
The data record operations operate on a single record of a data store.
They include:
-
Adding new data objects. A DL adds a persistent copy of data object to
an open data store. This operation may or may not include the creation
of index entries. The mechanisms used to store and retrieve persistent
data objects are private to the implementation of a DL module.
-
Deleting data objects. A DL removes single data object from the data
store.
-
Retrieving data objects. A DL provides a search mechanism for
selectively retrieving a copy of persistent security objects.
Selection is based on a selection criterion.
Data store extensibility operations include:
-
Pass-through for unique, module-specific operations. A pass-through
function is included in the data storage library interface to allow
data store libraries to expose additional services beyond what is
currently defined in the CSSM API. CSSM passes an operation identifier
and input parameters from the application to the appropriate data
storage library. Within the DL_PassThrough function in the data
storage library, the input parameters are interpreted and the
appropriate operation performed. The data storage library developer is
responsible for making known to the application the identity and
parameters of the supported pass-through operations.
Data Storage Library Operations
- CSSM_RETURN CSSMDLI DL_Authenticate()
Authenticates a user's ability to use
this DL for accessing the underlying data stores.
Data Store Operations
- CSSM_DB_HANDLE CSSMDLI DL_DbOpen()
For authorized users, this opens a data store with the specified
logical name in the requested access mode. Returns a handle to
the data store.
- CSSM_RETURN CSSMDLI DL_DbClose()
Closes a data store.
- CSSM_DB_HANDLE CSSMDLI DL_DbCreate()
Creates and opens a new, empty data store with the specified logical
name and the specified schema. As a side effect, the DL updates the
CSSM Registry to expose information about the new data store.
- CSSM_RETURN CSSMDLI DL_DbDelete()
For authorized users, this deletes all records from the specified data
store and removes current state information associated
with that data store.
- CSSM_RETURN CSSMDLI DL_DbImport()
Accepts as input a flag for what to import, a filename, a logical name,
and a schema for a data store. If information about the data store is
being imported, then the DL updates its list of accessible data stores
to include this new data store with the specified schema. If the
contents of the data store are being imported, then the file contains
an exported copy of an existing data store. The data records contained
in the file must be in the native format of a data store. The DL
imports all security objects in the file (such as certificates and
CRLs), creating a new data record for each. If the specified logical
name is that of an existing data store, the new records will be added
to the data store. Otherwise, a new data store will be created with
the specified schema to hold the new records.
- Note:
- This mechanism can
be used to copy data stores among systems or to restore a persistent
data store from a backup copy. It could also be used to import data
stores that were created and managed by other DLs, but this is not the
typical implementation and use of this interface.
- CSSM_RETURN CSSMDLI DL_DbExport()
Accepts as input the logical name of a data store and the name of a
target output file. The specified data store contains persistent data
records. A representation of the schema for the data store being
exported is written to the file along with a copy of each data record
in the data store.
- Note:
- This mechanism can be used to copy data stores
among systems or to create a backup of persistent data stores.
- CSSM_RETURN CSSMDLI DL_DbSetRecordParsingFunctions()
Sets the functions to be used for parsing the specified type of
security object.
- CSSM_DB_RECORD_PARSING_FNTABLE_PTR CSSMDLI DL_DbGetRecordParsingFunctions()
Returns the function pointers in use for parsing the specified type of
security object.
- char * CSSMDLI DL_GetDbNameFromHandle()
Retrieves the data source name corresponding to an opened database handle.
- CSSM_NAME_LIST_PTR CSSMDLI DL_GetDbNames()
Returns the names of data stores accessible via this DL module.
- CSSM_RETURN CSSMDLI DL_FreeNameList()
Frees the list of data stores returned by a call to DL_GetDbNames.
Data Record Operations
- CSSM_DB_UNIQUE_RECORD_PTR CSSMDLI DL_DataInsert()
Accepts as input a handle to a data store, the type of the security
object, the attributes of the object and the object itself. The data
object and its attributes are made persistent in the specified data
store. This may or may not include the creation of index entries, and
so on. The DL module will return to the calling application a unique
identifier for the input record which may be used to rapidly retrieve
the security object. The mechanisms used to store and retrieve
persistent security objects is private to the implementation of the
Data Storage Library.
- CSSM_RETURN CSSMDLI DL_DataDelete()
Accepts as input a handle to a data store and a unique identifier of
the security object. The object is removed from the data store. If
the object is not found in the specified data store, or if the user
does not have deletion permissions, the operation fails.
- CSSM_RETURN CSSMDLI DL_DataModify()
Accepts as input a handle to a data store, the type of the security
object, a unique record identifier, the attributes to be modified and
the data to be modified. If present, the attributes are added,
replaced, or deleted depending on the input attribute values and the
current contents of the record attributes. If present, the record data
is replaced with the input data. An indicator of the operation's
success or failure is returned. Either all or none of the requested
modifications will have occurred.
- CSSM_DATA_PTR CSSMDLI DL_DataGetFirst()
Accepts as input a handle to a data store, a query, and a list of the
attributes to be retrieved. The query is composed of the type of data
record to be retrieved, a selection predicate, and any limits or flags
on the query. Selection predicates are represented as a set of
(relational operator, attribute) pairs that are connected by a
conjunctive operator. Query limits provide a mechanism for the user to
specify upper bounds on the search time and/or the number of records
retrieved. Not all DL modules will support query limits. The
specified data store is searched for data objects of the specified type
that match the selection criteria. This function returns the first
data object matching the criteria together with the requested
attributes and a unique identifier for use in future references. If
additional objects matched, a selection handle is returned that may be
used to retrieve the subsequent objects. A data storage library may
limit the number of concurrently managed selection handles to exactly
one. The library developer must document all such
restrictions and application developers should proceed accordingly.
- CSSM_DATA_PTR CSSMDLI DL_DataGetNext()
Accepts as input a selection results handle that was returned by an
invocation of the function CSSM_DL_DataGetFirst and a list of the
attributes to be returned. If there are no more records to retrieve,
the EndOfDataStore flag is set to CSSM_TRUE and the function returns
NULL. Otherwise, a DL module returns the next data record, the
requested attributes, and a unique identifier, from the set specified
by the selection results handle. A data storage library may limit the
number of concurrently-managed selection result handles to exactly
one. The library developer must document such restrictions, and
application developers should proceed accordingly.
- CSSM_RETURN CSSMDLI DL_DataAbortQuery()
Cancels the query initiated by CSSM_DL_DataGetFirst function and resets
the selection results handle.
- CSSM_RETURN CSSMDLI DL_DataGetFromUniqueRecordId()
Accepts as input a unique record identifier and a list of the
attributes to be retrieved. The specified data store is searched for
the record corresponding to the unique record identifier. This
function returns the data object together with the requested
attributes.
- CSSM_RETURN CSSMDLI DL_FreeUniqueRecord()
Frees the memory associated with the input unique record structure.
Extensibility Functions
- void * CSSMDLI DL_PassThrough()
Accepts as input an operation ID and a set of arbitrary input
parameters. The operation ID may specify any type of operation a DL
wishes to export for use by an application or by another module. Such
operations may include queries or services that are specific to certain
types of security objects or specific types of data stores managed by a
DL module. It is the responsibility of the DL developer to make
information on the availability and usage of passthrough operations
available to application developers.
Data Storage Data Structures
CSSM_DL_HANDLE
A unique identifier for an attached module that provides data storage
library services.
typedef uint32 CSSM_DL_HANDLE /* Data Storage Library Handle */
CSSM_DB_HANDLE
A unique identifier for an open data store.
typedef uint32 CSSM_DB_HANDLE /* Data Store 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 specified 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 (data storage library handle, data store handle) pairs in
the list.
- DLDBHandle
List of (data storage library handle, data store handle) pairs.
CSSM_DB_ATTRIBUTE_NAME_FORMAT
This enumerated list defines the two formats used to represent an
attribute name. The name can be represented by a character string in
the native string encoding of the platform or the name can be
represented by an opaque OID structure that is interpreted by the DL
module.
typedef enum cssm_db_attribute_name_format {
CSSM_DB_ATTRIBUTE_NAME_AS_STRING = 0,
CSSM_DB_ATTRIBUTE_NAME_AS_OID = 1,
} CSSM_DB_ATTRIBUTE_NAME_FORMAT, *CSSM_DB_ATTRIBUTE_NAME_FORMAT_PTR;
CSSM_DB_ATTRIBUTE_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. These format indicators
can be set by application caller or by the data storage library
module. When a caller selects an format option that cannot be
supported by the library module, the module can ignore the
caller-declared format.
typedef enum cssm_db_attribute_format {
CSSM_DB_ATTRIBUTE_FORMAT_STRING = 0,
CSSM_DB_ATTRIBUTE_FORMAT_INTEGER = 1,
CSSM_DB_ATTRIBUTE_FORMAT_REAL = 2,
CSSM_DB_ATTRIBUTE_FORMAT_TIME = 3,
CSSM_DB_ATTRIBUTE_FORMAT_MONEY = 4,
CSSM_DB_ATTRIBUTE_FORMAT_BLOB = 5,
} CSSM_DB_ATTRIBUTE_FORMAT, *CSSM_DB_ATTRIBUTE_FORMAT;
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.
typedef struct cssm_db_attribute_info {
CSSM_DB_ATTRIBUTE_NAME_FORMAT AttributeNameFormat;
union cssm_db_attribute_label {
char * AttributeName; /* e.g., "record label" */
CSSM_OID AttributeID; /* e.g., CSSMOID_RECORDLABEL */
} Label;
CSSM_DB_ATTRIBUTE_FORMAT AttributeFormat;
} CSSM_DB_ATTRIBUTE_INFO, *CSSM_DB_ATTRIBUTE_INFO_PTR;
Definition
- AttributeNameFormat
Indicates which of the two formats was selected to represent"
the attribute name.
- AttributeName
A character string representation of the attribute name.
- AttributeID
A DER-encoded OID representation of the attribute name.
- AttributeFormat
Indicates the format of the attribute.The Data
Storage Library may not support more than one format, typically
CSSM_DB_ATTRIBUTE_FORMAT_STRING. In this case, the library
module can ignore any format specification provided by the
caller.
CSSM_DB_ATTRIBUTE_DATA
This data structure holds an attribute value that can be stored in an
attribute field of a persistent record. The structure contains a value
for the data item and a reference to the meta information (typing
information and schema information) associated with the attribute.
typedef struct cssm_db_attribute_data {
CSSM_DB_ATTRIBUTE_INFO Info;
CSSM_DATA Value;
} CSSM_DB_ATTRIBUTE_DATA, *CSSM_DB_ATTRIBUTE_DATA_PTR;
Definition
- Info
A reference to the meta-information/schema describing this attribute in
relationship to the data store at large.
- Value
The data-present value assigned to the attribute.
To ensure a minimal level of interoperability among applications
and DL modules, CSSM requires that all DL modules recognize and
support two pre-defined attribute names for all record types:
-
PrintName: a printable or viewable string name associated
with the record
-
Alias: an arbitrary value associated with the record.
The value can be non-printable.
Applications that create new data stores and define the
associated schema are encouraged to define these attributes as
part of the schema. If the data store creator does not define
these attributes, the DL module must add these attributes with
the following minimum storage size requirements
-
PrintName: the associated value is a string of maximum
length 16 characters
-
Alias: the associated value is an arbitrary data type of
maximum length 8 bytes
Applications are encouraged to provide values for these
attributes when creating data store records, but values are not
required. All applications can use these strings as valid
attribute names even if no value is stored in association with
this attribute name. When no value is associated with a
pre-defined attribute name, it is possible for a DL module that
encapsulates a data store schema to return one of the following:
-
A module-defined default value
-
A value selected from a database-key attribute in the data store
-
A NULL value
The CSSM_DB_ATTRIBUTE_DATA structure for the pre-defined
attribute name "PrintName" contains the following values:
{ AttributeNameFormat = CSSM_DB_ATTRIBUTE_NAME_AS_STRING
AttributeName = "PrintName"
Value = <a value in a CSSM_DATA structure> }
CSSM_DB_RECORDTYPE
This enumerated list defines the categories of persistent
security-related objects that can be managed by a data storage library
module. These categories are in one-to-one correspondence with types of
records that can be managed by a data store.
typedef enum cssm_db_recordtype {
CSSM_DL_DB_RECORD_GENERIC = 0,
CSSM_DL_DB_RECORD_CERT = 1,
CSSM_DL_DB_RECORD_CRL = 2,
CSSM_DL_DB_RECORD_KEY = 3,
CSSM_DL_DB_RECORD_POLICY = 4,
} CSSM_DB_RECORDTYPE;
CSSM_DB_CERTRECORD_SEMANTICS
These bit masks define a list of usage semantics for how certificates
may be used. It is anticipated that additional sets of bit masks will
be defined listing the usage semantics of how other record types can be
used, such as CRL record semantics, key record semantics, policy record
semantics, and so on.
#define CSSM_DB_CERT_USE_TRUSTED 0x00000001
/* application-defined as trusted */
#define CSSM_DB_CERT_USE_SYSTEM 0x00000002
/* the CSSM system cert */
#define CSSM_DB_CERT_USE_OWNER 0x00000004
/* private key owned by system user*/
#define CSSM_DB_CERT_USE_REVOKED 0x00000008
/* revoked cert - used w\ CRL APIs */
#define CSSM_DB_CERT_USE_SIGNING 0x00000010
/* use cert for signing only */
#define CSSM_DB_CERT_USE_PRIVACY 0x00000020
/* use cert for confidentiality only */
Record semantic designations are advisory only. For example, the
designation CSSM_DB_CERT_USE_OWNER suggests that the private key
associated with the public key contained
in the certificate is local to the system. This statement was
probably true when the certificate was created. Various actions
could make this assertion false. The private key could have
expired, been revoked, or be stored in a portable cryptographic
storage device that is not currently resident on the system. The
validity of the advisory designation CSSM_DB_CERT_USE_TRUSTED
should be verified using standard certificate verification
procedures. Although these designators are advisory, application
or trust policies can
choose to use this information if it is useful for their purpose.
For example, a trust policy can define how advisory designations
can be used when full policy evaluation requires connection to a
remote facility that is currently inaccessible.
Management practices for record semantic designators define the
agent and the time when a data store record can be assigned a
particular designator value. Reasonable usage is described as
follows:
Designation Value
| Assigning Time
| Assigning Agents
|
---|
CSSM_DB_CERT_USE_TRUSTED
| Local record creation time
Remote record creation time
Reset at any time
| Sys Admin App
App/Record Owner
|
---|
CSSM_DB_CERT_USE_SYSTEM
| Local record creation time
Should not be reset
| Sys Admin App
|
CSSM_DB_CERT_USE_OWNER
| Local record creation time
Reset at any time
| App/Record Owner
|
CSSM_DB_CERT_USE_REVOKED
| Set once only
| Sys Admin App
App/Record Owner
|
CSSM_DB_CERT_SIGNING
| Local record creation time
| Remote Authority
Local Authority
Record Owner
|
CSSM_DB_CERT_PRIVACY
| Local record creation time
| Remote Authority
Local Authority
Record Owner
|
CSSM_DB_RECORD_ATTRIBUTE_INFO
This structure contains the meta information or schema information
about all of the attributes in a particular record type. The
description specifies the record type, the number of attributes in the
record type, and a type information for each attribute. This
description includes the CSSM pre-defined attributes named
"PrintName" and "Alias".
typedef struct cssm_db_record_attribute_info {
CSSM_DB_RECORDTYPE DataRecordType;
uint32 NumberOfAttributes;
CSSM_DB_ATTRIBUTE_INFO_PTR AttributeInfo;
} CSSM_DB_RECORD_ATTRIBUTE_INFO, *CSSM_DB_RECORD_ATTRIBUTE_INFO_PTR;
Definition
- DataRecordType
A CSSM_DB_RECORDTYPE.
- NumberOfAttributes
The number of attributes in a record of the specified type.
- AttributeInfo
A list of pointers to the type (schema) information for each of
the attributes.
CSSM_DB_RECORD_ATTRIBUTE_DATA
This structure aggregates the actual data values for all of the
attributes in a single record.
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 certificate
records (CSSM_CERTRECORD_SEMANTICS). For all other record types, a bit
mask of zero must be used or a set of semantically meaningful masks
must be defined.
- NumberOfAttributes
The number of attributes in the record of the specified type.
- AttributeData
A list of attribute name/value pairs. If no stored value is
associated with this attribute, the attribute data pointer is
NULL.
CSSM_DB_RECORD_PARSING_FNTABLE
This structure defines the three prototypes for functions that can
parse the opaque data object stored in a record. It is used in the
CSSM_DbSetRecordParsingFunctions function to override the default
parsing module for a given record type. The DL module developer
designates the default parsing module for each record type stored in
the data store.
typedef struct cssm_db_record_parsing_fntable {
CSSM_DATA_PTR (CSSMAPI *RecordGetFirstFieldValue)
(CSSM_HANDLE Handle,
const CSSM_DATA_PTR Data,
const CSSM_OID_PTR DataField,
CSSM_HANDLE_PTR ResultsHandle,
uint32 *NumberOfMatchedFields);
CSSM_DATA_PTR (CSSMAPI *RecordGetNextFieldValue)
(CSSM_HANDLE Handle,
CSSM_HANDLE ResultsHandle);
CSSM_RETURN (CSSMAPI *RecordAbortQuery)
(CSSM_HANDLE Handle,
CSSM_HANDLE ResultsHandle);
} CSSM_DB_RECORD_PARSING_FNTABLE, *CSSM_DB_RECORD_PARSING_FNTABLE_PTR;
Definition
- *RecordGetFirstFieldValue
A function to retrieve the value of a field in the opaque object. The
field is specified by attribute name. The results handle holds the
state information required to retrieve subsequent values having the
same attribute name.
- *RecordGetNextFieldValue
A function to retrieve subsequent values having the same attribute name
from a record parsed by the first function in this table.
- *RecordAbortQuery
Stop subsequent retrieval of values having the same attribute
name from within the opaque object.
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 record 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.
CSSM_DB_INDEX_TYPE
This enumerated list defines two types of indexes: indexes with unique
values (that is, 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 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 enum.
typedef enum cssm_db_index_data_location {
CSSM_DB_INDEX_ON_UNKNOWN = 0,
CSSM_DB_INDEX_ON_ATTRIBUTE = 1,
CSSM_DB_INDEX_ON_RECORD = 2
} CSSM_DB_INDEX_DATA_LOCATION;
CSSM_DB_INDEX_INFO
This structure contains the meta information or schema description of
an index defined on an attribute. The description includes the type of
index (for example, unique key or non-unique key), the logical location of the
indexed attribute in the CSSM record (for example, an attribute or a field
within the opaque object in the record), and the meta information on
the attribute itself.
typedef struct cssm_db_index_info {
CSSM_DB_INDEX_TYPE IndexType;
CSSM_DB_INDEXED_DATA_LOCATION IndexedDataLocation;
CSSM_DB_ATTRIBUTE_INFO Info;
} CSSM_DB_INDEX_INFO, *CSSM_DB_INDEX_INFO_PTR;
Definition
- IndexType
A CSSM_DB_INDEX_TYPE.
- IndexedDataLocation
A CSSM_DB_INDEXED_DATA_LOCATION.
- Info
The meta information description of the attribute being indexed.
CSSM_DB_UNIQUE_RECORD
This structure contains an index descriptor and a module-defined
value. The index descriptor may be used by the module to enhance the
performance when locating the record. The module-defined value must
uniquely identify the record. For a DBMS, this may be the record
data. For a PKCS #11 DL, this may be an object handle. Alternately,
the DL may have a module-specific scheme for identifying data which has
been inserted or retrieved.
typedef struct cssm_db_unique_record {
CSSM_DB_INDEX_INFO RecordLocator;
CSSM_DATA RecordIdentifier;
} CSSM_DB_UNIQUE_RECORD, *CSSM_DB_UNIQUE_RECORD_PTR;
Definition
- RecordLocator
The information describing how to locate the record efficiently.
- RecordIdentifier
A module-specific identifier which will allow the DL to locate
this record.
CSSM_DB_RECORD_INDEX_INFO
This structure contains the meta information or schema description of
the set of indexes defined on a single record type. The description
includes the type of the record, the number of indexes and the meta
information describing each index.
The data store creator can specify an index over a CSSM pre-defined
attribute. When no index has been defined, the DL module has the option
to add an index over a CSSM pre-defined attribute or any other
attribute defined by the data store creator.
typedef struct cssm_db_record_index_info {
CSSM_DB_RECORDTYPE DataRecordType;
uint32 NumberOfIndexes;
CSSM_DB_INDEX_INFO_PTR IndexInfo;
} CSSM_DB_RECORD_INDEX_INFO, *CSSM_DB_RECORD_INDEX_INFO_PTR;
Definition
- DataRecordType
A CSSM_DB_RECORDTYPE.
- NumberOfIndexes
The number of indexes defined on the records of the given type.
- IndexInfo
An array containing a description of each index defined over the
specified record type.
CSSM_DB_ACCESS_TYPE
This bitmask describes a user's desired level of access to a data
store.
typedef uint32 CSSM_DB_ACCESS_TYPE, *CSSM_DB_ACCESS_TYPE_PTR;
#define CSSM_DB_ACCESS_READ 0x00001
#define CSSM_DB_ACCESS_WRITE 0x00002
#define CSSM_DB_ACCESS_PRIVILEGED 0x00004
/* versus user mode */
#define CSSM_DB_ACCESS_ASYNCHRONOUS 0x00008
/* versus synchronous */
Definition
- ReadAccess
A boolean indicating that the user requests read access.
- WriteAccess
A boolean indicating that the user requests write access.
- PrivilegedMode
A boolean indicating that the user requests privileged
operations, such as modifying data store access rights.
- Asynchronous
A boolean indicating that the user requests asynchronous access.
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 in a secure manner.
typedef struct cssm_dbinfo {
/* meta information about each record type in this data store
including meta information about record attributes and indexes */
uint32 NumberOfRecordTypes;
CSSM_DB_PARSING_MODULE_INFO_PTR DefaultParsingModules;
CSSM_DB_RECORD_ATTRIBUTE_INFO_PTR RecordAttributeNames;
CSSM_DB_RECORD_INDEX_INFO_PTR RecordIndexes;
/* access restrictions for opening this data store */
CSSM_USER_AUTHENTICATION_MECHANISM AuthenticationMechanism;
/* transparent integrity checking options for this data store */
CSSM_BOOL RecordSigningImplemented;
CSSM_DATA SigningCertificate;
CSSM_SUBSERVICE_UID SigningCspSubserviceUid;
/* additional information */
CSSM_BOOL IsLocal;
char *AccessPath; /* URL, dir path, etc. */
void *Reserved;
} CSSM_DBINFO, *CSSM_DBINFO_PTR;
Definition
- NumberOfRecordTypes
The number of distinct record types stored in this data
store.
- DefaultParsingModules
A pointer to a list of (record-type, GUID) pairs which
define the default parsing module for each record type.
- RecordAttributeNames
The meta (schema) information about the attributes
associated with each record type that can be stored in this data store.
- RecordIndexes
The meta (schema) information about the indexes that are defined
over each of the record types that can be stored in this data store.
- AuthenticationMechanism
Defines the authentication mechanism required when
accessing this data store.
- RecordSigningImplemented
A flag indicating whether or not the DL module provides
record integrity service based on digital signaturing of the data store records.
- SigningCertificate
The certificate used to sign data store records when the
transparent record integrity option is in effect.
- SigningCspSubserviceUid
The persistent service ID for the cryptographic service provider to be used to sign
data store records when the transparent record integrity option is in effect.
- IsLocal
Indicates whether the physical data store is local.
- AccessPath
A character string describing the access path to the data store, such
as an URL, a file system path name, a remote directory service name, and so on.
- Reserved
Reserved for future use.
CSSM_DB_OPERATOR
These are the logical operators which can be used when specifying a
selection predicate.
typedef enum cssm_db_operator {
CSSM_DB_EQUAL = 0,
CSSM_DB_NOT_EQUAL = 1,
CSSM_DB_APPROX_EQUAL = 2,
CSSM_DB_LESS_THAN = 3,
CSSM_DB_GREATER_THAN = 4,
CSSM_DB_EQUALS_INITIAL_SUBSTRING = 5,
CSSM_DB_EQUALS_ANY_SUBSTRING = 6,
CSSM_DB_EQUALS_FINAL_SUBSTRING = 7,
CSSM_DB_EXISTS = 8
} CSSM_DB_OPERATOR, *CSSM_DB_OPERATOR_PTR;
CSSM_DB_CONJUNCTIVE
These are the conjunctive operations which can be used when specifying
a selection criterion.
typedef enum cssm_db_conjunctive{
CSSM_DB_NONE = 0,
CSSM_DB_AND = 1,
CSSM_DB_OR = 2
} CSSM_DB_CONJUNCTIVE, *CSSM_DB_CONJUNCTIVE_PTR;
CSSM_SELECTION_PREDICATE
This structure defines the selection predicate to be used for data
store queries.
typedef struct cssm_selection_predicate {
CSSM_DB_OPERATOR DbOperator;
CSSM_DB_ATTRIBUTE_DATA Attribute;
} CSSM_SELECTION_PREDICATE, *CSSM_SELECTION_PREDICATE_PTR;
Definition
- DbOperator
The relational operator to be used when comparing a value to the
values stored in the specified attribute in the data store.
- Attribute
The meta information about the attribute to be searched and the
attribute value to be used for comparison with values in the data store.
CSSM_QUERY_LIMITS
This structure defines the time and space limits a caller can set to
control early termination of the execution of a data store query. The
constant values CSSM_QUERY_TIMELIMIT_NONE and CSM_QUERY_SIZELIMIT_NONE
should be used to specify no limit on the resources used in processing
the query. These limits are advisory. Not all data storage library
modules recognize and act upon the query limits set by a caller.
#define CSSM_QUERY_TIMELIMIT_NONE 0
#define CSSM_QUERY_SIZELIMIT_NONE 0
typedef struct cssm_query_limits {
uint32 TimeLimit; /* in seconds */
uint32 SizeLimit; /* max. number of records to return */
} CSSM_QUERY_LIMITS, *CSSM_QUERY_LIMITS_PTR;
Definition
- TimeLimit
Defines the maximum number of seconds of resource time that should be
expended performing a query operation. The constant value
CSSM_QUERY_TIMELIMIT_NONE means no time limit is specified.
- 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.
CSSM_QUERY_FLAGS
These flags may be used by the application to request query-related
operation, such as the format of the returned data.
typedef uint32 CSSM_QUERY_FLAGS
#define CSSM_QUERY_RETURN_DATA 0x1
/* On = Return the data record
Off = Return a reference to the data record */
CSSM_QUERY
This structure holds a complete specification of a query to select
records from a data store.
typedef struct cssm_query {
CSSM_DB_RECORDTYPE RecordType;
CSSM_DB_CONJUNCTIVE Conjunctive;
uint32 NumSelectionPredicates;
CSSM_SELECTION_PREDICATE_PTR SelectionPredicate;
CSSM_QUERY_LIMITS QueryLimits;
CSSM_QUERY_FLAGS QueryFlags;
} CSSM_QUERY, *CSSM_QUERY_PTR;
Definition
- RecordType
Specifies the type of record to be retrieved from the data store.
- Conjunctive
The conjunctive operator to be used in constructing the selection
predicate for the query.
- NumSelectionPredicates
The number of selection predicates to be connected by the
specified conjunctive operator to form the query.
- SelectionPredicate
The list of selection predicates to be combined by the
conjunctive operator to form the data store query.
- QueryLimits
Defines the time and space limits for processing the selection query.
The constant values CSSM_QUERY_TIMELIMIT_NONE and
CSM_QUERY_SIZELIMIT_NONE should be used to specify no limit on the
resources used in processing the query.
- QueryFlags
Query-related requests from the application.
CSSM_DLTYPE
This enumerated list defines the types of underlying data management
systems that can be used by the DL module to provide services. It is
the option of the DL module to disclose this information. It is
anticipated that other underlying data servers will be added to this
list over time.
typedef enum cssm_dltype {
CSSM_DL_UNKNOWN = 0,
CSSM_DL_CUSTOM = 1,
CSSM_DL_LDAP = 2,
CSSM_DL_ODBC = 3,
CSSM_DL_PKCS11 = 4,
CSSM_DL_FFS = 5, /* flat file system or fast file system */
CSSM_DL_MEMORY = 6,
CSSM_DL_REMOTEDIR = 7
} CSSM_DLTYPE;
CSSM_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 a PKCS#11 data store.
CSSM_DB_DATASTORES_UNKNOWN
Not all DL modules can maintain a summary of managed data stores. In
this case, the DL module reports its number of data stores as
CSSM_DB_DATASTORES_UNKNOWN. Data stores can (and probably do) exist,
but the DL module cannot provide a list of them.
#define CSSM_DB_DATASTORES_UNKNOWN (0xFFFFFFFF)
CSSM_DL_WRAPPEDPRODUCT_INFO
This structure holds product information about all backend data store
services used by the DL module. The DL module vendor is not required to
provide this information, but may choose to do so. For example, a DL
module that uses a commercial database management system can record
information about that product in this structure. Another example is a
DL module that supports certificate storage through an X.500
certificate directory server. The DL module can describe the X.500
directory service in this structure.
typedef struct cssm_dl_wrappedproductinfo {
CSSM_VERSION StandardVersion; /* Ver of standard the
product conforms to */
CSSM_STRING StandardDescription; /* Descr of standard the
product conforms to */
CSSM_VERSION ProductVersion; /* Version of wrapped
product or library */
CSSM_STRING StandardDescription; /* Desc of standard this
product conforms to */
CSSM_STRING ProductVendor; /* Vendor of wrapped product
or library */
CSSM_NET_PROTOCOL NetworkProtocol; /* The network protocol
supported by remote storage service */
uint32 ProductFlags; /* Mask of selectable DB
service features actually used by the DL */
} CSSM_DL_WRAPPEDPRODUCT_INFO, *CSSM_DL_WRAPPEDPRODUCT_INFO_PTR;
Definition
- StandardVersion
If this product conforms to an industry standard, this is the
version number of that standard.
- StandardDescription
If this product conforms to an industry standard, this is a
description of that standard.
- ProductVersion
Version number information for the actual product version used in
this version of the DL module.
- ProductDescription
A string describing the product.
- ProductVendor
The name of the product vendor.
- NetworkProtocol
The name of the network protocol.
- ProductFlags
A bit mask enumerating selectable features of the data base service
that the DL module uses in its implementation.
CSSM_NAME_LIST
The CSSM_NAME_LIST structure is used to return the logical names of the
data stores that a DL module can access.
typedef struct cssm_name_list {
uint32 NumStrings;
char** String;
} CSSM_NAME_LIST, *CSSM_NAME_LIST_PTR;
Definition
- NumStrings
Number of strings in the array pointed to by String.
- String
A pointer to an array of strings.
CSSM_DLSUBSERVICE
This structure contains the static information that describes a data
storage library sub-service. This information is securely stored in the
CSSM registry when the DL module is installed with CSSM. A data storage
library module may implement multiple types of services and organize
them as sub-services. For example, a DL module supporting two types of
remote directory services may organize its implementation into two
sub-services, one for an X.509 certificate directory and a second for
custom enterprise policy data store. Most data storage library modules
will implement exactly one sub-service.
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 (-1)
The descriptive information stored in these structures can be queried
using the function CSSM_GetModuleInfo() and specifying the data
storage library module GUID.
typedef struct cssm_dlsubservice {
uint32 SubServiceId;
CSSM_STRING Description;
CSSM_DLTYPE Type;
union cssm_dlsubservice_attributes {
CSSM_DL_CUSTOM_ATTRIBUTES CustomAttributes;
CSSM_DL_LDAP_ATTRIBUTES LdapAttributes;
CSSM_DL_ODBC_ATTRIBUTES OdbcAttributes;
CSSM_DL_PKCS11_ATTRIBUTES Pkcs11Attributes;
CSSM_DL_FFS_ATTRIBUTES FfsAttributes;
} Attributes;
CSSM_DL_WRAPPEDPRODUCT_INFO WrappedProduct;
CSSM_USER_AUTHENTICATION_MECHANISM AuthenticationMechanism;
/* meta information about the query support */
/* provided by the module */
uint32 NumberOfRelOperatorTypes;
CSSM_DB_OPERATOR_PTR RelOperatorTypes;
uint32 NumberOfConjOperatorTypes;
CSSM_DB_CONJUNCTIVE_PTR ConjOperatorTypes;
CSSM_BOOL QueryLimitsSupported;
/* meta information about the encapsulated */
/* data stores (if known) */
sint32 NumberOfDataStores;
CSSM_NAME_LIST_PTR DataStoreNames;
CSSM_DBINFO_PTR DataStoreInfo;
/* additional information */
void *Reserved;
} CSSM_DLSUBSERVICE, *CSSM_DLSUBSERVICE_PTR;
Definition
- SubServiceId
A unique, identifying number for the sub-service described in this
structure.
- Description
A string containing a description name or title for this
sub-service.
- Type
An identifier for the type of underlying data store the DL module uses to
provide persistent storage.
- Attributes
A structure containing attributes that define additional parameter
values specific to the DL module type.
- WrappedProduct
Descriptions of the backend data store services used by this
module.
- AuthenticationMechanism
Defines the authentication mechanism required when using this DL
module. This authentication mechanism is distinct from the
authentication mechanism (specified in a DBInfo structure) required to
access a specific data store.
- NumberOfRelOperatorTypes
The number of distinct relational operator the DL module accepts in
selection queries for retrieving records from its managed data stores.
- RelOperatorTypes
The list of specific relational operators that can be used to formulate
selection predicates for queries on a data store. The list contains
NumberOfRelOperatorTypes operators.
- NumberOfConjOperatorTypes
The number of distinct conjunctive operator the DL module accepts in
selection queries for retrieving records from its managed data stores.
- ConjOperatorTypes
A list of specific conjunctive operators that can be used to formulate
selection predicates for queries on a data store. The list contains
NumberOfConjOperatorTypes operators.
- QueryLimitsSupported
A boolean indicating whether query limits are effective
when the DL module executes a query.
- NumberOfDataStores
The number of data stores managed by the DL module. This information
may not be known by the DL module, in which case this value will equal
CSSM_DB_DATASTORES_UNKNOWN.
- DataStoreNames
A list of names of the data stores managed by the DL module. This
information may not be known by the DL module and hence may not be
available. The list contains NumberOfDataStores entries.
- DataStoreInfo
A list of pointers to information about each data store managed by the
DL module. This information may not be known in advance by the DL
module and hence may not be available through this structure. The list
contains NumberOfDataStores entries.
- Reserved
Reserved for future use.
Data Storage Library Operations
The manpages for
Data Storage Library Operations
can be found at the end of this chapter.
Data Store Operations
The manpages for
Data Store Operations
can be found at the end of this chapter.
Data Record Operations
The manpages for
Data Record Operations
can be found at the end of this chapter.
Extensibility Functions
The manpages for
Extensibility Functions
can be found at the end of this chapter.
Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy
of this publication.
You should also read the
legal notice explaining the terms and conditions relating to
the CDSA documentation.