DL_DbCreate(3)DL_DbCreate(3)NAME
DL_DbCreate, CSSM_DL_DbCreate - Create and open new data store (CDSA)
SYNOPSIS
# include <cdsa/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 *OpenParame‐
ters, 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 AccessRe‐
quest, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, const void
*OpenParameters, CSSM_DB_HANDLE *DbHandle)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
The handle that describes the add-in data storage library module used
to perform this function. The logical name for the new data store. A
pointer to a network address directly or indirectly identifying the
location of the storage service process. If the input is NULL, the mod‐
ule 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. A pointer to a structure
describing the format/schema of each record type that will be stored in
the new data store. An indicator of the requested access mode for the
data store, such as read-only or read-write. 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 imme‐
diate 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. A
pointer to a module-specific set of parameters required to open the
data store. 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 identi‐
fies 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: 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. A value indicating whether the Subject can dele‐
gate the permissions recorded in the AuthorizationTag. (This item only
applies to public key subjects). The set of permissions that are
granted to the Subject. The start time and the stop time for which the
ACL entry is valid. 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 Direc‐
tory 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 repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_DL_DATASTORE_ALREADY_EXISTS CSS‐
MERR_DL_FIELD_SPECIFIED_MULTIPLE CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_ACCESS_REQUEST CSSMERR_DL_INVALID_DB_LOCATION CSS‐
MERR_DL_INVALID_DB_NAME CSSMERR_DL_INVALID_FIELD_NAME CSS‐
MERR_DL_INVALID_OPEN_PARAMETERS CSSMERR_DL_INVALID_PARSING_MODULE CSS‐
MERR_DL_INVALID_RECORDTYPE CSSMERR_DL_INVALID_RECORD_INDEX CSS‐
MERR_DL_UNSUPPORTED_FIELD_FORMAT CSSMERR_DL_UNSUPPORTED_INDEX_INFO CSS‐
MERR_DL_UNSUPPORTED_LOCALITY CSSMERR_DL_UNSUPPORTED_NUM_ATTRIBUTES CSS‐
MERR_DL_UNSUPPORTED_NUM_INDEXES CSSMERR_DL_UNSUPPORTED_NUM_RECORDTYPES
CSSMERR_DL_UNSUPPORTED_RECORDTYPE
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
Functions for the CSSM API:
CSSM_DL_DbOpen(3), CSSM_DL_DbClose(3), CSSM_DL_DbDelete(3)
Functions for the DL SPI:
DL_DbOpen(3), DL_DbClose(3), DL_DbDelete(3)DL_DbCreate(3)