NAME
   DL_ChangeDbAcl, CSSM_DL_ChangeDbAcl - Edit stored ACL (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_DL_ChangeDbAcl
        (CSSM_DL_DB_HANDLE DLDBHandle,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const CSSM_ACL_EDIT *AclEdit)
    SPI:
        CSSM_RETURN CSSMDLI DL_ChangeDbAcl
        (CSSM_DL_DB_HANDLE DLDBHandle,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const CSSM_ACL_EDIT *AclEdit)

 LIBRARY
   Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

 PARAMETERS
   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.OldEntryHandle
           ______________________________________________________________
           CSSM_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.

 DESCRIPTION
   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 TypedSubject 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.

 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.

        CSSMERR_DL_INVALID_DB_HANDLE

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_DL_GetDbAcl

   Functions for the DL SPI:

       DL_GetDbAcl