.TH eldap 3erl "eldap 1.2.8" "Ericsson AB" "Erlang Module Definition"
.SH NAME
eldap \- LDAP Client
.SH DESCRIPTION
.LP
This module provides a client api to the Lightweight Directory Access Protocol (LDAP)\&.
.LP
References:
.RS 2
.TP 2
*
RFC 4510 - RFC 4519
.LP
.TP 2
*
RFC 2830
.LP
.RE

.LP
The above publications can be found at IETF\&.
.SH "DATA TYPES"

.LP
Type definitions that are used more than once in this module:
.RS 2
.TP 2
.B
\fIhandle()\fR\&:
Connection handle
.TP 2
.B
\fIattribute() =\fR\&:
\fI{Type = string(), Values=[string()]}\fR\&
.TP 2
.B
\fImodify_op()\fR\&:
See mod_add/2, mod_delete/2, mod_replace/2 
.TP 2
.B
\fIscope()\fR\&:
See baseObject/0, singleLevel/0, wholeSubtree/0 
.TP 2
.B
\fIdereference()\fR\&:
See neverDerefAliases/0, derefInSearching/0, derefFindingBaseObj/0, derefAlways/0 
.TP 2
.B
\fIfilter()\fR\&:
See present/1, substrings/2, equalityMatch/2, greaterOrEqual/2, lessOrEqual/2, approxMatch/2, extensibleMatch/2, \&'and\&'/1, \&'or\&'/1, \&'not\&'/1 
.TP 2
.B
\fIreturn_value() = \fR\&:
\fIok | {ok, {referral,referrals()}} | {error,Error}\fR\& 
.TP 2
.B
\fIreferrals() =\fR\&:
\fI[Address = string()]\fR\& The contents of \fIAddress\fR\& is server dependent\&.
.RE
.SH EXPORTS
.LP
.B
open([Host]) -> {ok, Handle} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Handle = handle()
.br
.RE
.RE
.RS
.LP
Setup a connection to an LDAP server, the \fIHOST\fR\&\&'s are tried in order\&.
.RE

.LP
.B
open([Host], [Option]) -> {ok, Handle} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Handle = handle()
.br
Option = {port, integer()} | {log, function()} | {timeout, integer()} | {ssl, boolean()} | {sslopts, list()} | {tcpopts, list()}
.br
.RE
.RE
.RS
.LP
Setup a connection to an LDAP server, the \fIHOST\fR\&\&'s are tried in order\&.
.LP
The log function takes three arguments, \fIfun(Level, FormatString, [FormatArg]) end\fR\&\&.
.LP
Timeout set the maximum time in milliseconds that each server request may take\&.
.LP
All TCP socket options are accepted except \fIactive\fR\&, \fIbinary\fR\&, \fIdeliver\fR\&, \fIlist\fR\&, \fImode\fR\& and \fIpacket\fR\& 
.RE

.LP
.B
close(Handle) -> ok
.br
.RS
.LP
Types:

.RS 3
Handle = handle()
.br
.RE
.RE
.RS
.LP
Shutdown the connection after sending an unbindRequest to the server\&. If the connection is tls the connection will be closed with \fIssl:close/1\fR\&, otherwise with \fIgen_tcp:close/1\fR\&\&.
.RE

.LP
.B
start_tls(Handle, Options) -> return_value()
.br
.RS
.LP
Same as start_tls(Handle, Options, infinity)
.RE

.LP
.B
start_tls(Handle, Options, Timeout) -> return_value()
.br
.RS
.LP
Types:

.RS 3
Handle = handle()
.br
Options = ssl:ssl_options()
.br
Timeout = infinity | positive_integer()
.br
.RE
.RE
.RS
.LP
Upgrade the connection associated with \fIHandle\fR\& to a tls connection if possible\&.
.LP
The upgrade is done in two phases: first the server is asked for permission to upgrade\&. Second, if the request is acknowledged, the upgrade to tls is performed\&.
.LP
Error responses from phase one will not affect the current encryption state of the connection\&. Those responses are:
.RS 2
.TP 2
.B
\fItls_already_started\fR\&:
The connection is already encrypted\&. The connection is not affected\&.
.TP 2
.B
\fI{response,ResponseFromServer}\fR\&:
The upgrade was refused by the LDAP server\&. The \fIResponseFromServer\fR\& is an atom delivered byt the LDAP server explained in section 2\&.3 of rfc 2830\&. The connection is not affected, so it is still un-encrypted\&.
.RE
.LP
Errors in the second phase will however end the connection:
.RS 2
.TP 2
.B
\fIError\fR\&:
Any error responded from ssl:connect/3
.RE
.LP
The \fITimeout\fR\& parameter is for the actual tls upgrade (phase 2) while the timeout in eldap:open/2 is used for the initial negotiation about upgrade (phase 1)\&.
.RE

.LP
.B
simple_bind(Handle, Dn, Password) -> return_value()
.br
.RS
.LP
Types:

.RS 3
Handle = handle()
.br
Dn = string()
.br
Password = string()
.br
.RE
.RE
.RS
.LP
Authenticate the connection using simple authentication\&.
.RE

.LP
.B
add(Handle, Dn, [Attribute]) -> return_value()
.br
.RS
.LP
Types:

.RS 3
Handle = handle()
.br
Dn = string()
.br
Attribute = attribute()
.br
.RE
.RE
.RS
.LP
Add an entry\&. The entry must not exist\&.
.LP
.nf

  add(Handle,
      "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com",
       [{"objectclass", ["person"]},
        {"cn", ["Bill Valentine"]},
        {"sn", ["Valentine"]},
        {"telephoneNumber", ["545 555 00"]}]
     )
	
.fi
.RE

.LP
.B
delete(Handle, Dn) -> return_value()
.br
.RS
.LP
Types:

.RS 3
Dn = string()
.br
.RE
.RE
.RS
.LP
Delete an entry\&.
.LP
.nf

  delete(Handle, "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com")
	
.fi
.RE

.LP
.B
mod_add(Type, [Value]) -> modify_op()
.br
.RS
.LP
Types:

.RS 3
Type = string()
.br
Value = string()
.br
.RE
.RE
.RS
.LP
Create an add modification operation\&.
.RE

.LP
.B
mod_delete(Type, [Value]) -> modify_op()
.br
.RS
.LP
Types:

.RS 3
Type = string()
.br
Value = string()
.br
.RE
.RE
.RS
.LP
Create a delete modification operation\&.
.RE

.LP
.B
mod_replace(Type, [Value]) -> modify_op()
.br
.RS
.LP
Types:

.RS 3
Type = string()
.br
Value = string()
.br
.RE
.RE
.RS
.LP
Create a replace modification operation\&.
.RE

.LP
.B
modify(Handle, Dn, [ModifyOp]) -> return_value()
.br
.RS
.LP
Types:

.RS 3
Dn = string()
.br
ModifyOp = modify_op()
.br
.RE
.RE
.RS
.LP
Modify an entry\&.
.LP
.nf

  modify(Handle, "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com",
         [eldap:mod_replace("telephoneNumber", ["555 555 00"]),
	  eldap:mod_add("description", ["LDAP Hacker"]) ])
	
.fi
.RE

.LP
.B
modify_password(Handle, Dn, NewPasswd) -> return_value() | {ok, GenPasswd}
.br
.RS
.LP
Types:

.RS 3
Dn = string()
.br
NewPasswd = string()
.br
.RE
.RE
.RS
.LP
Modify the password of a user\&. See modify_password/4\&.
.RE

.LP
.B
modify_password(Handle, Dn, NewPasswd, OldPasswd) -> return_value() | {ok, GenPasswd}
.br
.RS
.LP
Types:

.RS 3
Dn = string()
.br
NewPasswd = string()
.br
OldPasswd = string()
.br
GenPasswd = string()
.br
.RE
.RE
.RS
.LP
Modify the password of a user\&.
.RS 2
.TP 2
*
\fIDn\fR\&\&. The user to modify\&. Should be "" if the modify request is for the user of the LDAP session\&.
.LP
.TP 2
*
\fINewPasswd\fR\&\&. The new password to set\&. Should be "" if the server is to generate the password\&. In this case, the result will be \fI{ok, GenPasswd}\fR\&\&.
.LP
.TP 2
*
\fIOldPasswd\fR\&\&. Sometimes required by server policy for a user to change their password\&. If not required, use modify_password/3\&.
.LP
.RE

.RE

.LP
.B
modify_dn(Handle, Dn, NewRDN, DeleteOldRDN, NewSupDN) -> return_value()
.br
.RS
.LP
Types:

.RS 3
Dn = string()
.br
NewRDN = string()
.br
DeleteOldRDN = boolean()
.br
NewSupDN = string()
.br
.RE
.RE
.RS
.LP
Modify the DN of an entry\&. \fIDeleteOldRDN\fR\& indicates whether the current RDN should be removed from the attribute list after the operation\&. \fINewSupDN\fR\& is the new parent that the RDN shall be moved to\&. If the old parent should remain as parent, \fINewSupDN\fR\& shall be ""\&.
.LP
.nf

  modify_dn(Handle, "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com ",
            "cn=Bill Jr Valentine", true, "")
	
.fi
.RE

.LP
.B
search(Handle, SearchOptions) -> {ok, #eldap_search_result{}} | {ok, {referral,referrals()}} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
SearchOptions = #eldap_search{} | [SearchOption]
.br
SearchOption = {base, string()} | {filter, filter()} | {scope, scope()} | {attributes, [string()]} | {deref, dereference()} | | {types_only, boolean()} | {timeout, integer()} 
.br
.RE
.RE
.RS
.LP
Search the directory with the supplied the SearchOptions\&. The base and filter options must be supplied\&. Default values: scope is \fIwholeSubtree()\fR\&, deref is \fIderefAlways()\fR\&, types_only is \fIfalse\fR\& and timeout is \fI0\fR\& (meaning infinity)\&.
.LP
.nf

  Filter = eldap:substrings("cn", [{any,"V"}]),
  search(Handle, [{base, "dc=example, dc=com"}, {filter, Filter}, {attributes, ["cn"]}]),
	
.fi
.LP
The \fItimeout\fR\& option in the \fISearchOptions\fR\& is for the ldap server, while the timeout in eldap:open/2 is used for each individual request in the search operation\&.
.RE

.LP
.B
baseObject() -> scope()
.br
.RS
.LP
Search baseobject only\&.
.RE

.LP
.B
singleLevel() -> scope()
.br
.RS
.LP
Search the specified level only, i\&.e\&. do not recurse\&.
.RE

.LP
.B
wholeSubtree() -> scope()
.br
.RS
.LP
Search the entire subtree\&.
.RE

.LP
.B
neverDerefAliases() -> dereference()
.br
.RS
.LP
Never derefrence aliases, treat aliases as entries\&.
.RE

.LP
.B
derefAlways() -> dereference()
.br
.RS
.LP
Always derefrence aliases\&.
.RE

.LP
.B
derefInSearching() -> dereference()
.br
.RS
.LP
Derefrence aliases only when searching\&.
.RE

.LP
.B
derefFindingBaseObj() -> dereference()
.br
.RS
.LP
Derefrence aliases only in finding the base\&.
.RE

.LP
.B
present(Type) -> filter()
.br
.RS
.LP
Types:

.RS 3
Type = string()
.br
.RE
.RE
.RS
.LP
Create a filter which filters on attribute type presence\&.
.RE

.LP
.B
substrings(Type, [SubString]) -> filter()
.br
.RS
.LP
Types:

.RS 3
Type = string()
.br
SubString = {StringPart, string()}
.br
StringPart = initial | any | final
.br
.RE
.RE
.RS
.LP
Create a filter which filters on substrings\&.
.RE

.LP
.B
equalityMatch(Type, Value) -> filter()
.br
.RS
.LP
Types:

.RS 3
Type = string()
.br
Value = string()
.br
.RE
.RE
.RS
.LP
Create a equality filter\&.
.RE

.LP
.B
greaterOrEqual(Type, Value) -> filter()
.br
.RS
.LP
Types:

.RS 3
Type = string()
.br
Value = string()
.br
.RE
.RE
.RS
.LP
Create a greater or equal filter\&.
.RE

.LP
.B
lessOrEqual(Type, Value) -> filter()
.br
.RS
.LP
Types:

.RS 3
Type = string()
.br
Value = string()
.br
.RE
.RE
.RS
.LP
Create a less or equal filter\&.
.RE

.LP
.B
approxMatch(Type, Value) -> filter()
.br
.RS
.LP
Types:

.RS 3
Type = string()
.br
Value = string()
.br
.RE
.RE
.RS
.LP
Create a approximation match filter\&.
.RE

.LP
.B
extensibleMatch(MatchValue, OptionalAttrs) -> filter()
.br
.RS
.LP
Types:

.RS 3
MatchValue = string()
.br
OptionalAttrs = [Attr]
.br
Attr = {matchingRule,string()} | {type,string()} | {dnAttributes,boolean()}
.br
.RE
.RE
.RS
.LP
Creates an extensible match filter\&. For example,
.LP
.nf

  eldap:extensibleMatch("Bar", [{type,"sn"}, {matchingRule,"caseExactMatch"}]))
      
.fi
.LP
creates a filter which performs a \fIcaseExactMatch\fR\& on the attribute \fIsn\fR\& and matches with the value \fI"Bar"\fR\&\&. The default value of \fIdnAttributes\fR\& is \fIfalse\fR\&\&.
.RE

.LP
.B
\&'and\&'([Filter]) -> filter()
.br
.RS
.LP
Types:

.RS 3
Filter = filter()
.br
.RE
.RE
.RS
.LP
Creates a filter where all \fIFilter\fR\& must be true\&.
.RE

.LP
.B
\&'or\&'([Filter]) -> filter()
.br
.RS
.LP
Types:

.RS 3
Filter = filter()
.br
.RE
.RE
.RS
.LP
Create a filter where at least one of the \fIFilter\fR\& must be true\&.
.RE

.LP
.B
\&'not\&'(Filter) -> filter()
.br
.RS
.LP
Types:

.RS 3
Filter = filter()
.br
.RE
.RE
.RS
.LP
Negate a filter\&.
.RE