Index Index for
Section 3
Index Alphabetical
listing for D
Bottom of page Bottom of
page		 

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 *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 (libcssm.so)


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.	See CDSA_intro(3).

       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 (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)

Index Index for
Section 3
Index Alphabetical
listing for D
Top of page Top of
page