Access Control API Changes in ES 4.0

1, ACL_LDAPDatabaseHandle()

This function always logs an error message and returns LAS_EVAL_FAIL.  Changes were made in ES 4.0 to support a pool of LDAP connections to each LDAP database defined in dbswitch.conf.  This function could not be implemented under the new model, but two new functions, ACL_LDAPSessionAllocate() and ACL_LDAPSessionFree(), have been added to the Access Control API in ES 4.0.  These are described below.

2. ACL_LDAPSessionAllocate()

This is a new function in ES 4.0, intended to provide the same functionality previously obtained from ACL_LDAPDatabaseHandle().  It allocates an LDAP connection to the specified LDAP database, returning a (LDAP *) handle for the connection, which can be used in calls to LDAP SDK functions.  The caller is responsible for calling ACL_LDAPSessionFree() to return the connection to the pool of LDAP connections managed by the server.  Upon a successful return, the returned LDAP connection is bound to the binddn specified in dbswitch.conf, if any, or anonymously bound otherwise.  The caller may rebind the connection, if desired.
 
Syntax:

#include <aclapi.h>

NSAPI_PUBLIC
int ACL_LDAPSessionAllocate(NSErr_t *errp, const char *dbname,
                             LDAP **ld, const char **basedn)

Parameters:

This function has the following parameters:

errp

Pointer to the header for a list of error frames.
dbname
Name of the LDAP database. If this argument is NULL, the default database is used.
ld
Pointer to the returned connection handle to the LDAP server. If you are performing LDAP operations through LDAP API function calls, you need to pass this handle as an argument to the functions you call.  This parameter must not be NULL.
basedn
Pointer to the returned distinguished name (DN) of the root object in the LDAP directory (for example, o=Ace Industry,c=US).  Note that unlike ACL_LDAPDatabaseHandle(), the returned value is a (const char *), which need not be freed by the caller, and which is valid until ACL_LDAPSessionFree() is called.  This parameter may be NULL if the base DN is not needed.
Returns:

LAS_EVAL_TRUE if successful, or LAS_EVAL_FAIL if an error occurs.

Example:

See lasemail.c.

3. ACL_LDAPSessionFree()

This function is used to free an LDAP connection obtained from ACL_LDAPSessionAllocate() back to the LDAP connection pool from which it was allocated.  Since LDAP connections are shared among all threads in the server, it is important to free a connection when there is no immediate use for it.
 
Syntax:
#include <aclapi.h>

void ACL_LDAPSessionFree(LDAP *ld)

Parameters:

ld

This is the handle for the LDAP connection that was previously returned by ACL_LDAPSessionAllocate().
Returns:

No value is returned.

Example:

See lasemail.c.

4. Handling of LAS_EVAL_FAIL

When an LAS plugin returns LAS_EVAL_FAIL in ES 4.0, this is taken to be indicative of a server configuration error, and "Server Error" is the response given to the client.  It may be necessary to return LAS_EVAL_FALSE instead of LAS_EVAL_FAIL in some cases, to achieve the desired behavior.