Summary: Isode provides a number of APIs which allow integrators and product developers to build components that allow client programs to connect to, query and modify data in the directory.

Modules

 Bind parameters
 
 SASL security properties
 
 Identities
 

Functions

DS_Status DS_Session_New (const char *address, int force_tls, DS_Session **session_p)
 Create an unbound directory session, validating the specified address. More...
 
DS_Status DS_BindAnonymousSync (DS_Session *session, DS_CommonArgs *common_args, DS_Indication **indication_p)
 Perform an anonymous synchronous directory bind. More...
 
DS_Status DS_BindSync_Anonymous (const char *address, DS_Session **session_p) DSAPI_DEPRECATED
 Perform an anonymous synchronous directory bind. More...
 
DS_Status DS_BindSimpleSync (DS_Session *session, const DS_DN *dn, const char *password, DS_CommonArgs *common_args, DS_Indication **indication_p)
 Perform a synchronous directory bind using simple credentials. More...
 
DS_Status DS_BindSync_Simple (const char *address, const DS_DN *dn, const char *password, DS_Session **session_p) DSAPI_DEPRECATED
 Perform a synchronous directory bind using simple credentials. More...
 
DS_Status DS_BindStrongSync (DS_Session *session, const DS_DN *dsa_dn, const DS_DN *dn, const char *password, DS_CommonArgs *common_args, DS_Indication **indication_p)
 Perform a synchronous directory bind using strong credentials. More...
 
DS_Status DS_BindSync_Strong (const char *address, const DS_DN *dsa_dn, const DS_DN *dn, const char *password, DS_Session **session_p) DSAPI_DEPRECATED
 Perform a synchronous directory bind using strong credentials. More...
 
const char ** DS_SaslMechList (void)
 Perform a synchronous directory bind using SASL. More...
 
DS_Status DS_BindSASLSync (DS_Session *session, const char *mechanism, const char *userid, const char *secret, DS_CommonArgs *common_args, DS_Indication **indication_p)
 
DS_Status DS_BindSync_SASL (const char *address, const char *mechanism, const char *userid, const char *secret, DS_Session **session_p) DSAPI_DEPRECATED
 Perform a synchronous directory bind using SASL. More...
 
DS_Status DS_BindWithParameters (DS_Session *session, const DS_BindParams *bind_params, DS_CommonArgs *common_args, DS_Indication **indication_p)
 Bind using a set of bind parameters. More...
 
void DS_UnbindSync (DS_Session **session_p)
 Perform a synchronous directory unbind. More...
 
DS_Status DS_GetSessionState (const DS_Session *session_p, DSSessionState *state_p)
 Get the current session state. More...
 
DS_Status DS_GetSessionCertificates (const DS_Session *session_p, DS_AttrValList **av_list_p, int *identity_check_result)
 Get and/or verify certificates that were sent by a server during a strong bind operation. More...
 
DS_Status DS_AllowUnknownAttrs (DS_Session *session, int allow_unknown)
 Turn on or off the flag that allows unknown attributes to be read over LDAP. More...
 
DS_Status DS_GetAllowUnknownAttrs (DS_Session *session, int *allow_unknown_p)
 Get the values of the flag that allows unknown attributes to be read over LDAP. More...
 

Detailed Description

Methods used to create, authenticate, and delete a directory session.

The normal procedure is to create a session using DS_Session_New(), then bind using DS_BindAnonymousSync(), DS_BindSimpleSync(), DS_BindSASLSync() or DS_BindStrongSync(), perform other operations against the directory server, and then finally unbind and delete the session with DS_UnbindSync().

Function Documentation

DS_Status DS_Session_New ( const char *  address,
int  force_tls,
DS_Session **  session_p 
)

Create an unbound directory session, validating the specified address.

If address is a presentation address (RFC 1278 format) then a DAP session will be created. If address is an LDAP URL (RFC 2255 format) or an LDAPS URL then an LDAPv3 session will be created.

Note that a connection to the directory server is not established until one of the bind functions is called.

Parameters
[in]addressAddress of directory server.
[in]force_tlsSet to 1 to force plain LDAP connections to use TLS (ignored for DAP connections and LDAPS connections).
[out]session_pPointer to receive session pointer (on success).
Return values
DS_E_NOERRORthe session was created
DS_E_BADADDRthe value specified in address is invalid
DS_E_BADPARAMEither address or session_p was NULL.
Since
DSAPI_VERSION 2026
Examples:
add.c, anonymous.c, async.c, delete.c, modify.c, read.c, and simple.c.
DS_Status DS_BindAnonymousSync ( DS_Session session,
DS_CommonArgs common_args,
DS_Indication **  indication_p 
)

Perform an anonymous synchronous directory bind.

Perform an anonymous bind on a directory session created by DS_Session_New(). Optionally, pass in any common arguments - a common use for this is to request password policy information.

Returns an indication of the bind success or failure.

Parameters
[in]sessionPointer to the directory session
[in]common_argsCommon arguments to directory operations
[out]indication_pReturn result/error
Returns
DSAPI function status code.
Since
DSAPI_VERSION 2026
Examples:
anonymous.c, async.c, and read.c.
DS_Status DS_BindSync_Anonymous ( const char *  address,
DS_Session **  session_p 
)

Perform an anonymous synchronous directory bind.

If address is a presentation address (RFC 1278 format) then a DAP session will be created. If address is an LDAP URL (RFC 2255 format) or an LDAPS URL then an LDAPv3 session will be created.

Parameters
[in]addressAddress of directory server.
[out]session_pPointer to receive session pointer (on success).
Returns
DSAPI function status code.
Deprecated:
Use DS_BindAnonymousSync() instead.
DS_Status DS_BindSimpleSync ( DS_Session session,
const DS_DN dn,
const char *  password,
DS_CommonArgs common_args,
DS_Indication **  indication_p 
)

Perform a synchronous directory bind using simple credentials.

Perform a simple bind on a directory session created by DS_Session_New(). Optionally, pass in any common arguments - a common use for this is to request password policy information.

Parameters
[in]sessionPointer to the directory session
[in]dnDN of user to connect as (NULL signifies anonymous)
[in]passwordPassword of user to connects as (NULL signifies none)
[in]common_argsCommon arguments to directory operations
[out]indication_pReturn result/error
Returns
DSAPI function status code.
Since
DSAPI_VERSION 2026
Examples:
add.c, delete.c, modify.c, and simple.c.
DS_Status DS_BindSync_Simple ( const char *  address,
const DS_DN dn,
const char *  password,
DS_Session **  session_p 
)

Perform a synchronous directory bind using simple credentials.

If address is a presentation address (RFC 1278 format) then a DAP session will be created. If address is an LDAP URL (RFC 2255 format) or an LDAPS URL then an LDAPv3 session will be created.

Parameters
[in]addressAddress of directory server
[in]dnDN of user to connect as (NULL signifies anonymous)
[in]passwordPassword of user to connects as (NULL signifies none)
[out]session_pPointer to receive session pointer (on success)
Returns
DSAPI function status code.
Deprecated:
Use DS_BindSimpleSync() instead.
DS_Status DS_BindStrongSync ( DS_Session session,
const DS_DN dsa_dn,
const DS_DN dn,
const char *  password,
DS_CommonArgs common_args,
DS_Indication **  indication_p 
)

Perform a synchronous directory bind using strong credentials.

Perform a strong bind on a directory session created by DS_Session_New(). Optionally, pass in any common arguments - a common use for this is to request password policy information.

If dn is not NULL, an identity must exist with the same subject name. If dn is NULL, a default identity will be used.

Parameters
[in]sessionPointer to the directory session
[in]dsa_dnDN of DSA to bind to
[in]dnDN of user to connect as (can be NULL)
[in]passwordPassword used to decrypt the user's identity
[in]common_argsCommon arguments to directory operations
[out]indication_pReturn result/error
Returns
DSAPI function status code.
Since
DSAPI_VERSION 2026
DS_Status DS_BindSync_Strong ( const char *  address,
const DS_DN dsa_dn,
const DS_DN dn,
const char *  password,
DS_Session **  session_p 
)

Perform a synchronous directory bind using strong credentials.

If address is a presentation address (RFC 1278 format) then a DAP session will be created. If address is an LDAP URL (RFC 2255 format) or an LDAPS URL then an LDAPv3 session will be created.

If dn is not NULL, an identity must exist with the same subject name. If dn is NULL, a default identity will be used.

Parameters
[in]addressAddress of directory server
[in]dsa_dnDN of DSA to bind to
[in]dnDN of user to connect as (can be NULL)
[in]passwordPassword used to decrypt the user's identity
[out]session_pPointer to receive session pointer (on success)
Returns
DSAPI function status code.
Since
DSAPI_VERSION 2000
Deprecated:
Use DS_BindStrongSync() instead.
const char** DS_SaslMechList ( void  )

Perform a synchronous directory bind using SASL.

Perform a SASL bind on a directory session created by DS_Session_New(). Optionally, pass in any common arguments - a common use for this is to request password policy information.

Currently SASL is not supported for DAP sessions.

Parameters
[in]sessionPointer to the directory session
[in]mechanismSASL mechanism to use (e.g. "DIGEST-MD5"), or NULL to allow the mechanism to be negotiated
[in]useridSASL userid to authenticate with (e.g. "user@example.com")
[in]secretSASL secret, or NULL if one is not required for the selected mechanism
[in]common_argsCommon arguments to directory operations
[out]indication_pReturn result/error
Returns
DSAPI function status code.
Since
DSAPI_VERSION 2026

Retrieve a list of the supported SASL mechanisms.

Returns a null-terminated array of strings that lists all mechanisms that are loaded by either the client or server side of the library.

Returns
Returns a pointer to the array on success. NULL on failure (SASL library uninitialised)
Since
DSAPI_VERSION 2045
DS_Status DS_BindSync_SASL ( const char *  address,
const char *  mechanism,
const char *  userid,
const char *  secret,
DS_Session **  session_p 
)

Perform a synchronous directory bind using SASL.

If address is an LDAP URL (RFC 2255 format) or an LDAPS URL then an LDAPv3 session will be created. Currently SASL is not supported for DAP sessions.

Parameters
[in]addressAddress of directory server
[in]mechanismSASL mechanism to use (e.g. "DIGEST-MD5"), or NULL to allow the mechanism to be negotiated
[in]useridSASL userid to authenticate with (e.g. "user@example.com")
[in]secretSASL secret, or NULL if one is not required for the selected mechanism
[out]session_pPointer to receive session pointer (on success)
Returns
DSAPI function status code.
Since
DSAPI_VERSION 2022
Deprecated:
Use DS_BindSASLSync() instead.
DS_Status DS_BindWithParameters ( DS_Session session,
const DS_BindParams bind_params,
DS_CommonArgs common_args,
DS_Indication **  indication_p 
)

Bind using a set of bind parameters.

The type of bind (anonymous/simple/strong etc.) is determined by whether the caller has used DS_BindParams_SetSimple or DS_BindParams_SetStrong. If neither of those has been used, then an anonymous bind will be attempted.

Parameters
[in]sessionPointer to the directory session
[in]bind_paramsbind parameters to use for the bind.
[in]common_argsCommon arguments to directory operations
[out]indication_pReturn result/error
Returns
DSAPI function status code.
void DS_UnbindSync ( DS_Session **  session_p)

Perform a synchronous directory unbind.

Parameters
[in]session_pPointer to an open directory session (contents are freed)
Examples:
add.c, anonymous.c, async.c, delete.c, modify.c, read.c, and simple.c.
DS_Status DS_GetSessionState ( const DS_Session session_p,
DSSessionState state_p 
)

Get the current session state.

This function returns the state (see DSSessionState) of the session so far as the library is concerned, based on the result of the most recent operation.

Note the state DSConnectionLost is not detected by the library until an operation is attempted over a connection which has been lost. In other words, should a network error of this type occur, the, the session's state as returned by this function will not be DSConnectionLost until another operation is attempted and the error is detected (the operation in this case will fail with DS_E_CONNECTIONLOST).

Parameters
[in]session_pDS_Session to query
[out]state_pVariable to write result to
Return values
DS_E_NOERRORstate was returned successfully
DS_E_NOBADPARAMIf session was NULL or state_p was NULL
Since
DSAPI_VERSION 2029
DS_Status DS_GetSessionCertificates ( const DS_Session session_p,
DS_AttrValList **  av_list_p,
int *  identity_check_result 
)

Get and/or verify certificates that were sent by a server during a strong bind operation.

A directory server may use certificates to authenticate itself to the client when a strong bind is performed (for LDAP, these certificates are provided as part of the TLS negotiation, and so may be available for LDAPS binds or LDAP binds that subsequently perform a startTLS).

Clients may perform checks on the server certificates in order to decide they trust the server enough to proceed.

This function allows a caller to obtain the certificates that were presented, and so provides the option for a DSAPI user to abandon a session for a server that does not present acceptable certificates.

If any certificates are presented by the server, they will be returned as a series of BER values in a DS_AttrValList structure. Note that the order of values is significant: the first being the "peer" certificate, followed by progressively "higher" level CA certificates.

If no certificates were available, then the returned DS_AttrValList will be NULL, and a status of DS_E_NOERROR will be returned.

When certificates are present, this function will perform a "server identity check". For a DAP connection, this check confirms that the subject DN in the server's certificate matches the DSA's DN.

In the case of LDAP, the check performed is described in RFC4513 section 3.1.3. This allows clients to guard against man-in-the-middle attacks.

The identity_check_result parameter will be set to non-zero in the case that the server has presented a certificate which passes the server identity check. The server identity check will fail if no certificates are available.

Passing NULL as the av_list_p parameter is permissible if the caller wishes to find the result of the server identity check, but is not interested in having the certificate list returned.

Parameters
[in]session_pDS_Session to query
[out]av_list_ppointer to a newly created DS_AttrValList structure which will contain an attribute value for each certificate presented. This value may be NULL if the caller does not want the certificate values. If no certificates are returned, a NULL value will be returned. The caller must free any returned value using DS_AttrValList_Delete.
[out]identity_check_resultthe pointer to a variable which will be set to non-zero if a server-identity-check succeeds, or zero otherwise.
Return values
DS_E_NOERRORinformation was returned successfully
DS_E_NOMEMORYif a memory allocation failed
DS_E_INTERNALan internal error occurred.
DS_E_OPFAILEDif session_p refers to a session which is not using LDAP with TLS/SSL.
DS_E_NOBADPARAMIf session_p or identity_check_result was NULL.
Since
DSAPI_VERSION 2032
DS_Status DS_AllowUnknownAttrs ( DS_Session session,
int  allow_unknown 
)

Turn on or off the flag that allows unknown attributes to be read over LDAP.

Parameters
[in]sessionDS_Session to modify
[in]allow_unknownAllow unknown attributes? (1 to allow, 0 to disallow)
Return values
DS_E_NOERRORSuccess
DS_E_BADPARAMIf session was NULL or allow_unknown was something other than 1 or 0.
Since
DSAPI_VERSION 2018

By default, LDAP operations which return unknown attribute types (according to the local schema) will result in DS_E_BADATTRTYPE errors.

The "allow_unknown" flag may be used to override this behaviour: if set, then any such attributes will be returned as "unknown attributes", and will have a syntax of "octetstring".

Unknown attributes may be written to LDIF files, or used in subsequent LDAP operations to write data to the directory.

Unknown attributes will never be returned from a DAP session, and may not be written to a directory server over DAP.

DS_Status DS_GetAllowUnknownAttrs ( DS_Session session,
int *  allow_unknown_p 
)

Get the values of the flag that allows unknown attributes to be read over LDAP.

Parameters
[in]sessionDS_Session to modify
[out]allow_unknown_pVariable to write result to
Return values
DS_E_NOERRORValue was read successfully
DS_E_NOBADPARAMIf session was NULL or allow_unknown_p was NULL
Since
DSAPI_VERSION 2018