DL_ChangeDbAcl

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 1:...

API Functions

DL_Authenticate

DL_ChangeDbOwner

DL_ChangeDbAcl

Library
Description
Errors

Parameters
Return Value
See Also

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.

CSSMERR_DL_INVALID_DB_HANDLE