Session Management
[Invoking Directory Operations]


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.
DS_Status	DS_BindAnonymousSync (DS_Session session, DS_CommonArgs common_args, DS_Indication **indication_p)
	Perform an anonymous synchronous directory bind.
DS_Status	DS_BindSync_Anonymous (const char address, DS_Session *session_p) DSAPI_DEPRECATED
	Perform an anonymous synchronous directory bind.
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.
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.
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.
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.
DS_Status	DS_BindSASLSync (DS_Session session, const char mechanism, const char userid, const char secret, DS_CommonArgs common_args, DS_Indication *indication_p)
	Perform a synchronous directory bind using SASL.
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.
void	DS_UnbindSync (DS_Session **session_p)
	Perform a synchronous directory unbind.
DS_Status	DS_GetSessionState (const DS_Session session_p, DSSessionState state_p)
	Get the current session state.
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.
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.
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.

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]`	address	Address of directory server.
`[in]`	force_tls	Set to 1 to force plain LDAP connections to use TLS (ignored for DAP connections and LDAPS connections).
`[out]`	session_p	Pointer to receive session pointer (on success).

Return values:

	DS_E_NOERROR	the session was created
	DS_E_BADADDR	the value specified in address is invalid
	DS_E_BADPARAM	Either 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]`	session	Pointer to the directory session
`[in]`	common_args	Common arguments to directory operations
`[out]`	indication_p	Return 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]`	address	Address of directory server.
`[out]`	session_p	Pointer 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]`	session	Pointer to the directory session
`[in]`	dn	DN of user to connect as (NULL signifies anonymous)
`[in]`	password	Password of user to connects as (NULL signifies none)
`[in]`	common_args	Common arguments to directory operations
`[out]`	indication_p	Return 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]`	address	Address of directory server
`[in]`	dn	DN of user to connect as (NULL signifies anonymous)
`[in]`	password	Password of user to connects as (NULL signifies none)
`[out]`	session_p	Pointer 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]`	session	Pointer to the directory session
`[in]`	dsa_dn	DN of DSA to bind to
`[in]`	dn	DN of user to connect as (can be NULL)
`[in]`	password	Password used to decrypt the user's identity
`[in]`	common_args	Common arguments to directory operations
`[out]`	indication_p	Return 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]`	address	Address of directory server
`[in]`	dsa_dn	DN of DSA to bind to
`[in]`	dn	DN of user to connect as (can be NULL)
`[in]`	password	Password used to decrypt the user's identity
`[out]`	session_p	Pointer to receive session pointer (on success)

Returns:: DSAPI function status code.

Since:: DSAPI_VERSION 2000

Deprecated:: Use DS_BindStrongSync() instead.

DS_Status DS_BindSASLSync	(	DS_Session *	session,
		const char *	mechanism,
		const char *	userid,
		const char *	secret,
		DS_CommonArgs *	common_args,
		DS_Indication **	indication_p
	)

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]`	session	Pointer to the directory session
`[in]`	mechanism	SASL mechanism to use (e.g. "DIGEST-MD5"), or NULL to allow the mechanism to be negotiated
`[in]`	userid	SASL userid to authenticate with (e.g. "user@example.com")
`[in]`	secret	SASL secret, or NULL if one is not required for the selected mechanism
`[in]`	common_args	Common arguments to directory operations
`[out]`	indication_p	Return result/error

Returns:: DSAPI function status code.

Since:: DSAPI_VERSION 2026

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]`	address	Address of directory server
`[in]`	mechanism	SASL mechanism to use (e.g. "DIGEST-MD5"), or NULL to allow the mechanism to be negotiated
`[in]`	userid	SASL userid to authenticate with (e.g. "user@example.com")
`[in]`	secret	SASL secret, or NULL if one is not required for the selected mechanism
`[out]`	session_p	Pointer to receive session pointer (on success)

Returns:: DSAPI function status code.

Since:: DSAPI_VERSION 2022

Deprecated:: Use DS_BindSASLSync() instead.

void DS_UnbindSync ( DS_Session ** session_p )

Perform a synchronous directory unbind.

Parameters:

[in] session_p Pointer 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_p	DS_Session to query
`[out]`	state_p	Variable to write result to

Return values:

	DS_E_NOERROR	state was returned successfully
	DS_E_NOBADPARAM	If 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_p	DS_Session to query
`[out]`	av_list_p	pointer 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_result	the pointer to a variable which will be set to non-zero if a server-identity-check succeeds, or zero otherwise.

Return values:

	DS_E_NOERROR	information was returned successfully
	DS_E_NOMEMORY	if a memory allocation failed
	DS_E_INTERNAL	an internal error occurred.
	DS_E_OPFAILED	if session_p refers to a session which is not using LDAP with TLS/SSL.
	DS_E_NOBADPARAM	If 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]`	session	DS_Session to modify
`[in]`	allow_unknown	Allow unknown attributes? (1 to allow, 0 to disallow)

Return values:

	DS_E_NOERROR	Success
	DS_E_BADPARAM	If 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]`	session	DS_Session to modify
`[out]`	allow_unknown_p	Variable to write result to

Return values:

	DS_E_NOERROR	Value was read successfully
	DS_E_NOBADPARAM	If session was NULL or allow_unknown_p was NULL

Since:: DSAPI_VERSION 2018

Section Contents

Documentation

Isode Simple Directory API

Session Management
[Invoking Directory Operations]

Functions

Detailed Description

Function Documentation

Section Contents

Documentation

Isode Simple Directory API

Session Management [Invoking Directory Operations]

Functions

Detailed Description

Function Documentation

Session Management
[Invoking Directory Operations]