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