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.
None specific to this call.
SEE ALSO
Books
Intel CDSA Application Developer's Guide
Online Help
Functions: CSSM_GetKeyAcl
