NAME
   CSSM_ChangeKeyAcl - Edit a stored ACL associated with the target
                       key (CDSA)

 SYNOPSIS
   # include <cssm.h>

        CSSM_RETURN CSSMAPI CSSM_ChangeKeyAcl
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const CSSM_ACL_EDIT *AclEdit,
        const CSSM_KEY *Key)

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

 PARAMETERS
   CSPHandle (input)
           The module handle that identifies the cryptographic service
           provider to perform this operation

   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 key. 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 an ACL managed by the service provider.
           The AclEdit can contain information for a new ACL entry and a
           handle uniquely 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 Key. The new ACL
                                        entry is created from the ACL
                                        entry prototype contained in
                                        NewEntry.  OldEntryHandle is
                                        ignored for this edit mode.

           CSSM_ACL_EDIT_MODE_DELETE    Deletes the ACL entry identified
                                        by OldEntryHandle and associated
                                        with the specified Key.  NewEntry
                                        is ignored for this edit mode.

           CSSM_ACL_EDIT_MODE_REPLACE   Replaces the ACL entry identified
                                        by OldEntryHandle and associated
                                        with the specified Key. The
                                        existing ACL is replaced based on
                                        the ACL entry prototype contained
                                        in the 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.

   Key (input)
           A pointer to the target key whose associated ACL is being
           modified.

 DESCRIPTION
   This function edits the stored ACL associated with the target key.
   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 key. 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 Subject 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.

   None specific to this call.

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions: CSSM_GetKeyAcl