CSSM_ChangeKeyAcl(3)CSSM_ChangeKeyAcl(3)NAMECSSM_ChangeKeyAcl - Edit a stored ACL associated with the target key
(CDSA)
SYNOPSIS
# include <cdsa/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 (libcssm.so)
PARAMETERS
The module handle that identifies the cryptographic service provider to
perform this operation 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 sam‐
ples. 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. A structure containing
information that defines the edit operation. Valid operations include:
adding, replacing, and deleting entries in an ACL managed by the ser‐
vice provider. The AclEdit can contain information for a new ACL entry
and a handle uniquely identifying an existing ACL entry. The informa‐
tion 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: A CSSM_LIST structure containing a typed Subject. The
Subject identifies the entity authorized by this ACL entry. A
CSSM_BOOL value indicating whether the subject can delegate the
permissions recorded in the authorization array. A CSSM_AUTHO‐
RIZATIONGROUP structure defining the set of operations for which
permission is granted to the Subject. A CSSM_ACL_VALID‐
ITY_PERIOD structure containing two elements, the start time and
the stop time for which the ACL entry is valid. A CSSM_STRING
containing a user-defined value associated with the ACL entry.
A pointer to the target key whose associated ACL is being modi‐
fied.
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 authen‐
tication 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 com‐
plete 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 repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3).
None specific to this call.
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
Functions: CSSM_GetKeyAcl(3)CSSM_ChangeKeyAcl(3)
