mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
238 lines
8.8 KiB
Groff
238 lines
8.8 KiB
Groff
.TH LDAP_BIND 3 "RELEASEDATE" "OpenLDAP LDVERSION"
|
|
.\" $OpenLDAP$
|
|
.\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved.
|
|
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
|
.SH NAME
|
|
ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines
|
|
.SH LIBRARY
|
|
OpenLDAP LDAP (libldap, -lldap)
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <ldap.h>
|
|
.LP
|
|
.BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred ","
|
|
.RS
|
|
.BI "int " method ");"
|
|
.RE
|
|
.LP
|
|
.BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred ","
|
|
.RS
|
|
.BI "int " method ");"
|
|
.RE
|
|
.LP
|
|
.BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");"
|
|
.LP
|
|
.BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");"
|
|
.LP
|
|
.BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism ","
|
|
.RS
|
|
.BI "struct berval *" cred ", LDAPControl *" sctrls "[],"
|
|
.BI "LDAPControl *" cctrls "[], int *" msgidp ");"
|
|
.RE
|
|
.LP
|
|
.BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism ","
|
|
.RS
|
|
.BI "struct berval *" cred ", LDAPControl *" sctrls "[],"
|
|
.BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");"
|
|
.RE
|
|
.LP
|
|
.BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res ","
|
|
.RS
|
|
.BI "struct berval **" servercredp ", int " freeit ");"
|
|
.RE
|
|
.LP
|
|
.BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn ","
|
|
.RS
|
|
.BI "const char *" mechs ","
|
|
.BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[],"
|
|
.BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact ","
|
|
.BI "void *" defaults ");"
|
|
.RE
|
|
.LP
|
|
.BI "int ldap_unbind(LDAP *" ld ");"
|
|
.LP
|
|
.BI "int ldap_unbind_s(LDAP *" ld ");"
|
|
.\" .LP
|
|
.\" .ft B
|
|
.\" void ldap_set_rebind_proc( ld, rebindproc )
|
|
.\" .ft
|
|
.\" LDAP *ld;
|
|
.\" int (*rebindproc)();
|
|
.LP
|
|
.BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[],"
|
|
.RS
|
|
.BI LDAPControl *" cctrls "[]);"
|
|
.RE
|
|
.LP
|
|
.BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[],"
|
|
.RS
|
|
.BI LDAPControl *" cctrls "[]);"
|
|
.RE
|
|
.LP
|
|
.BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params);"
|
|
.SH DESCRIPTION
|
|
.LP
|
|
These routines provide various interfaces to the LDAP bind operation.
|
|
After an association with an LDAP server is made using
|
|
.BR ldap_init (3),
|
|
an LDAP bind operation should be performed before other operations are
|
|
attempted over the connection. An LDAP bind is required when using
|
|
Version 2 of the LDAP protocol; it is optional for Version 3 but is
|
|
usually needed due to security considerations.
|
|
.LP
|
|
There are three types of bind calls, ones providing simple authentication,
|
|
ones providing SASL authentication, and general routines capable of doing
|
|
either simple or SASL authentication.
|
|
.LP
|
|
.B SASL
|
|
(Simple Authentication and Security Layer)
|
|
that can negotiate one of many different kinds of authentication.
|
|
Both synchronous and asynchronous versions of each variant of the bind
|
|
call are provided. All routines
|
|
take \fIld\fP as their first parameter, as returned from
|
|
.BR ldap_init (3).
|
|
.SH SIMPLE AUTHENTICATION
|
|
The simplest form of the bind call is
|
|
.BR ldap_simple_bind_s() .
|
|
It takes the DN to bind as in \fIwho\fP, and the userPassword associated
|
|
with the entry in \fIpasswd\fP. It returns an LDAP error indication
|
|
(see
|
|
.BR ldap_error (3)).
|
|
The
|
|
.B ldap_simple_bind()
|
|
call is asynchronous,
|
|
taking the same parameters but only initiating the bind operation and
|
|
returning the message id of the request it sent. The result of the
|
|
operation can be obtained by a subsequent call to
|
|
.BR ldap_result (3).
|
|
.SH GENERAL AUTHENTICATION
|
|
The
|
|
.B ldap_bind()
|
|
and
|
|
.B ldap_bind_s()
|
|
routines can be used when the
|
|
authentication method to use needs to be selected at runtime. They
|
|
both take an extra \fImethod\fP parameter selecting the authentication
|
|
method to use. It should be set to LDAP_AUTH_SIMPLE
|
|
to select simple authentication.
|
|
.B ldap_bind()
|
|
returns the message id of the request it initiates.
|
|
.B ldap_bind_s()
|
|
returns an LDAP error indication.
|
|
.SH SASL AUTHENTICATION
|
|
Description still under construction...
|
|
.SH REBINDING
|
|
.LP
|
|
The
|
|
.B ldap_set_rebind_proc
|
|
function() sets the process to use for binding when an operation returns a
|
|
referral. This function is used when an application needs to bind to another server
|
|
in order to follow a referral or search continuation reference.
|
|
.LP
|
|
The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP,
|
|
the arbitrary data like state information which the client might need to properly rebind.
|
|
The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries
|
|
to use the rebind function. Use the
|
|
.BR ldap_set_option
|
|
function to set the value.
|
|
.LP
|
|
The rebind function has the following syntax.
|
|
.B int rebind_function (LDAP *ld, const char *url,int request,ber_int_t msgid);
|
|
.LP
|
|
The \fIld\fP parameter must be used by the application when binding to the
|
|
referred server if the application wants the libraries to follow the referral.
|
|
.LP
|
|
The \fIurl\fP parameter points to the URL referral string received from the LDAP server.
|
|
The LDAP application can use the
|
|
.BR ldap_url_parse()
|
|
.LP
|
|
The \fIrequest\fP parameter specifies the request operation that generated the referral.
|
|
function to parse the string into its components.
|
|
.LP
|
|
The \fImsgid\fP parameter specifies the message ID of the request generating the referral.
|
|
.LP
|
|
The LDAP libraries set all the parameters when they call the rebind function. The application
|
|
should not attempt to free either the ld or the url structures in the rebind function.
|
|
.LP
|
|
The application must supply to the rebind function the required authentication information such as,
|
|
user name, password, and certificates. The rebind function must use a synchronous bind method.
|
|
.SH UNBINDING
|
|
The
|
|
.B ldap_unbind()
|
|
call is used to unbind from the directory,
|
|
terminate the current association, and free the resources contained
|
|
in the \fIld\fP structure. Once it is called, the connection to
|
|
the LDAP server is closed, and the \fIld\fP structure is invalid.
|
|
The
|
|
.B ldap_unbind_s()
|
|
call is just another name for
|
|
.BR ldap_unbind() ;
|
|
both of these calls are synchronous in nature.
|
|
.\" .SH RE-BINDING WHILE FOLLOWING REFERRALS
|
|
.\" The
|
|
.\" .B ldap_set_rebind_proc()
|
|
.\" call is used to set a routine that will be called back to obtain bind
|
|
.\" credentials used when a new server is contacted during the following of
|
|
.\" an LDAP referral. Note that this function is only available when the
|
|
.\" LDAP libraries are compiled with LDAP_REFERRALS defined and is only
|
|
.\" used when the ld_options field in the LDAP structure has
|
|
.\" LDAP_OPT_REFERRALS set (this is the default). If
|
|
.\" .B ldap_set_rebind_proc()
|
|
.\" is never called, or if it is called with a NULL \fIrebindproc\fP
|
|
.\" parameter, an unauthenticated simple LDAP bind will always be done
|
|
.\" when chasing referrals.
|
|
.\" .LP
|
|
.\" \fIrebindproc\fP should be a function that is declared like this:
|
|
.\" .LP
|
|
.\" .nf
|
|
.\" int rebindproc( LDAP *ld, char **whop, char **credp,
|
|
.\" int *methodp, int freeit );
|
|
.\" .fi
|
|
.\" .LP
|
|
.\" The LDAP library will first call the rebindproc to obtain the
|
|
.\" referral bind credentials, and the \fIfreeit\fP parameter will be
|
|
.\" zero. The \fIwhop\fP, \fIcredp\fP, and \fImethodp\fP should be
|
|
.\" set as appropriate. If the rebindproc returns LDAP_SUCCESS, referral
|
|
.\" processing continues, and the rebindproc will be called a second
|
|
.\" time with \fIfreeit\fP non-zero to give your application a chance to
|
|
.\" free any memory allocated in the previous call.
|
|
.\" .LP
|
|
.\" If anything but LDAP_SUCCESS is returned by the first call to
|
|
.\" the rebindproc, then referral processing is stopped and that error code
|
|
.\" is returned for the original LDAP operation.
|
|
.LP
|
|
The
|
|
.B ldap_unbind_ext()
|
|
and
|
|
.B ldap_unbind_ext_s()
|
|
allows the operations to sepicify controls.
|
|
.SH ERRORS
|
|
Asynchronous routines will return -1 in case of error, setting the
|
|
\fIld_errno\fP parameter of the \fIld\fP structure. Synchronous
|
|
routines return whatever \fIld_errno\fP is set to. See
|
|
.BR ldap_error (3)
|
|
for more information.
|
|
.SH NOTES
|
|
If an anonymous bind is sufficient for the application,the rebind process
|
|
need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option
|
|
set to ON (default value) will automatically follow referrals using an anonymous bind.
|
|
.LP
|
|
If the application needs stronger authentication than an anonymous bind,
|
|
you need to provide a rebind process for that authentication method.
|
|
The bind method must be synchronous.
|
|
.SH SEE ALSO
|
|
.BR ldap (3),
|
|
.BR ldap_error (3),
|
|
.BR ldap_open (3),
|
|
.BR ldap_set_option (3),
|
|
.BR ldap_url_parse (3)
|
|
.B RFC 4422
|
|
(http://www.rfc-editor.org),
|
|
.B Cyrus SASL
|
|
(http://asg.web.cmu.edu/sasl/)
|
|
.SH ACKNOWLEDGEMENTS
|
|
.B OpenLDAP
|
|
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
|
|
.B OpenLDAP
|
|
is derived from University of Michigan LDAP 3.3 Release.
|