NAME
CSSM_DL_DbCreate — Create and open new data store (CDSA)
SYNOPSIS
# include <cssm.h>
API:
CSSM_RETURN CSSMAPI CSSM_DL_DbCreate
(CSSM_DL_HANDLE DLHandle,
const char *DbName,
const CSSM_NET_ADDRESS *DbLocation,
const CSSM_DBINFO *DBInfo,
CSSM_DB_ACCESS_TYPE AccessRequest,
const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
const void *OpenParameters,
CSSM_DB_HANDLE *DbHandle)
SPI:
CSSM_RETURN CSSMDLI DL_DbCreate
(CSSM_DL_HANDLE DLHandle,
const char *DbName,
const CSSM_NET_ADDRESS *DbLocation,
const CSSM_DBINFO *DBInfo,
CSSM_DB_ACCESS_TYPE AccessRequest,
const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
const void *OpenParameters,
CSSM_DB_HANDLE *DbHandle) |
LIBRARY
Common Security Services Manager library (cdsa$incssm300_shr.exe)
PARAMETERS
| DLHandle (input) | | The handle that describes the add-in data storage
library module used to perform this function. |
| DbName (input) | | The logical name for the new data store. |
| DbLocation (input/optional) |
| | | A pointer to a network address directly or indirectly
identifying the location of the storage service process. If the
input is NULL, the module can assume a default storage service process
location. If the DbName does not distinguish
the storage service process, the service cannot be performed and
the operation fails. |
| DBInfo (input) | | A pointer to a structure describing the format/schema
of each record type that will be stored in the new data store. |
| AccessRequest (input) |
| | | An indicator of the requested access mode for the
data store, such as read-only or read-write. |
| CredAndAclEntry (input/optional) |
| | | A structure containing one or more credentials authorized
for creating a data base and the prototype ACL entry that will control
future use of the newly created key. The credentials and ACL entry
prototype can be presented as immediate values or callback functions
can be provided for use by the DL to acquire the credentials and/or
the ACL entry interactively. If the DL provides public access for
creating a data base, then the credentials can be NULL. If the DL
defines a default initial ACL entry for the new data base, then
the ACL entry prototype can be an empty list. |
| OpenParameters (input/optional) |
| | | A pointer to a module-specific set of parameters
required to open the data store. |
| DbHandle (output) |
| | | The handle to the newly created and open data store.
The value will be set to CSSM_INVALID_HANDLE if the function fails. |
DESCRIPTION
This function creates and opens a new data store. The name
of the new data store is specified by the input parameter DbName.
The record schema for the data store is specified in the DBINFO
structure. If any RecordType defined in the DBINFO
structure does not have an associated parsing module, then the ModuleSubserviceUid specified
for that record type must be zero.
The newly created data store is opened under the specified
access mode. If user authentication credentials are required, they
must be provided. Also, additional open parameters may be required
and are supplied in OpenParameters. If user authentication
credentials are required, they must be provided.
Authorization policy can restrict the set of callers who can
create a new resource. In this case, the caller must present a set
of access credentials for authorization. Upon successfully authenticating
the credentials, the template that verified the presented samples
identifies the ACL entry that will be used in the authorization computation.
If the caller is authorized, the new resource is created.
The caller must provide an initial ACL entry to be associated
with the newly created resource. This entry is used to control future
access to the new resource and (since the subject is deemed to be
the "Owner") exercise control over its associated ACL. The caller
can specify the following items for initializing an ACL entry:
| Subject | | A CSSM_LIST structure, containing the type of the
subject and a template value that can be used to verify samples
that are presented in credentials when resource access is requested. |
| Delegation flag | | A value indicating whether the Subject can delegate
the permissions recorded in the AuthorizationTag.
(This item only applies to public key subjects). |
| Authorization tag |
| | | The set of permissions that are granted to the Subject. |
| Validity period | | The start time and the stop time for which the ACL
entry is valid. |
| ACL entry tag | | A user-defined string value associated with the
ACL entry. The service provider can modify the caller-provided initial
ACL entry to conform to any innate resource-access policy that the
service provider may be required to enforce. If the initial ACL
entry provided by the caller contains values or permissions that
are not supported by the service provider, then the service provider
can modify the initial ACL appropriately or can fail the request
to create the new resource. Service providers list their supported AuthorizationTag values
in their Module Directory Services primary record. |
RETURN VALUE
A CSSM_RETURN value indicating success or specifying a particular
error condition. The value CSSM_OK indicates success. All other
values represent an error condition.
ERRORS
Errors are described in the CDSA Technical Standard.
CSSMERR_DL_DATASTORE_ALREADY_EXISTS
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_ACCESS_REQUEST
CSSMERR_DL_INVALID_DB_LOCATION
CSSMERR_DL_INVALID_DB_NAME
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_OPEN_PARAMETERS
CSSMERR_DL_INVALID_PARSING_MODULE
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_INDEX
CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT
CSSMERR_DL_UNSUPPORTED_INDEX_INFO
CSSMERR_DL_UNSUPPORTED_LOCALITY
CSSMERR_DL_UNSUPPORTED_NUM_ATTRIBUTES
CSSMERR_DL_UNSUPPORTED_NUM_INDEXES
CSSMERR_DL_UNSUPPORTED_NUM_RECORDTYPES
CSSMERR_DL_UNSUPPORTED_RECORDTYPE |
SEE ALSO
Books
Intel CDSA Application Developer's Guide
Online Help
Functions for the CSSM API:
CSSM_DL_DbOpen, CSSM_DL_DbClose, CSSM_DL_DbDelete
Functions for the DL SPI:
DL_DbOpen, DL_DbClose, DL_DbDelete
