CSSM_ChangeKeyAcl

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