|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. | |
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().
| 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.
| [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). |
| 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. |
| 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.
| [in] | session | Pointer to the directory session |
| [in] | common_args | Common arguments to directory operations |
| [out] | indication_p | Return result/error |
| 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.
| [in] | address | Address of directory server. |
| [out] | session_p | Pointer to receive session pointer (on success). |
| 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.
| [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 |
| 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.
| [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) |
| 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.
| [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 |
| 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.
| [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) |
| 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.
| [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 |
| 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.
| [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) |
| void DS_UnbindSync | ( | DS_Session ** | session_p | ) |
| 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).
| [in] | session_p | DS_Session to query |
| [out] | state_p | Variable to write result to |
| DS_E_NOERROR | state was returned successfully | |
| DS_E_NOBADPARAM | If session was NULL or state_p was NULL |
| 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.
| [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. |
| 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. |
| 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.
| [in] | session | DS_Session to modify |
| [in] | allow_unknown | Allow unknown attributes? (1 to allow, 0 to disallow) |
| DS_E_NOERROR | Success | |
| DS_E_BADPARAM | If session was NULL or allow_unknown was something other than 1 or 0. |
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.
| [in] | session | DS_Session to modify |
| [out] | allow_unknown_p | Variable to write result to |
| DS_E_NOERROR | Value was read successfully | |
| DS_E_NOBADPARAM | If session was NULL or allow_unknown_p was NULL |