1eldap(3)                   Erlang Module Definition                   eldap(3)
2
3
4

NAME

6       eldap - LDAP Client
7

DESCRIPTION

9       This  module  provides a client api to the Lightweight Directory Access
10       Protocol (LDAP).
11
12       References:
13
14         * RFC 4510 - RFC 4519
15
16         * RFC 2830
17
18       The above publications can be found at IETF.
19

DATA TYPES

21       Type definitions that are used more than once in this module:
22
23         handle():
24           Connection handle
25
26         attribute() =:
27           {Type = string(), Values=[string()]}
28
29         modify_op():
30           See mod_add/2, mod_delete/2, mod_replace/2
31
32         scope():
33           See baseObject/0, singleLevel/0, wholeSubtree/0
34
35         dereference():
36           See neverDerefAliases/0, derefInSearching/0, derefFindingBaseObj/0,
37           derefAlways/0
38
39         filter():
40           See  present/1,  substrings/2,  equalityMatch/2,  greaterOrEqual/2,
41           lessOrEqual/2, approxMatch/2, extensibleMatch/2,  'and'/1,  'or'/1,
42           'not'/1
43
44         return_value() = :
45           ok | {ok, {referral,referrals()}} | {error,Error}
46
47         referrals() =:
48           [Address = string()] The contents of Address is server dependent.
49

EXPORTS

51       open([Host]) -> {ok, Handle} | {error, Reason}
52
53              Types:
54
55                 Handle = handle()
56
57              Setup  a  connection  to an LDAP server, the HOST's are tried in
58              order.
59
60       open([Host], [Option]) -> {ok, Handle} | {error, Reason}
61
62              Types:
63
64                 Handle = handle()
65                 Option = {port, integer()} | {log,  function()}  |  {timeout,
66                 integer()} | {ssl, boolean()} | {sslopts, list()} | {tcpopts,
67                 list()}
68
69              Setup a connection to an LDAP server, the HOST's  are  tried  in
70              order.
71
72              The log function takes three arguments, fun(Level, FormatString,
73              [FormatArg]) end.
74
75              Timeout set the maximum time in milliseconds  that  each  server
76              request may take.
77
78              All  TCP  socket  options  are  accepted  except active, binary,
79              deliver, list, mode and packet
80
81       close(Handle) -> ok
82
83              Types:
84
85                 Handle = handle()
86
87              Shutdown the connection after sending an  unbindRequest  to  the
88              server.  If  the connection is tls the connection will be closed
89              with ssl:close/1, otherwise with gen_tcp:close/1.
90
91       start_tls(Handle, Options) -> return_value()
92
93              Same as start_tls(Handle, Options, infinity)
94
95       start_tls(Handle, Options, Timeout) -> return_value()
96
97              Types:
98
99                 Handle = handle()
100                 Options = ssl:ssl_options()
101                 Timeout = infinity | positive_integer()
102
103              Upgrade the connection associated with Handle to a  tls  connec‐
104              tion if possible.
105
106              The upgrade is done in two phases: first the server is asked for
107              permission to upgrade. Second, if the request  is  acknowledged,
108              the upgrade to tls is performed.
109
110              Error  responses  from  phase  one  will  not affect the current
111              encryption state of the connection. Those responses are:
112
113                tls_already_started:
114                  The connection is already encrypted. The connection  is  not
115                  affected.
116
117                {response,ResponseFromServer}:
118                  The  upgrade  was  refused by the LDAP server. The Response‐
119                  FromServer  is  an  atom  delivered  byt  the  LDAP   server
120                  explained  in section 2.3 of rfc 2830. The connection is not
121                  affected, so it is still un-encrypted.
122
123              Errors in the second phase will however end the connection:
124
125                Error:
126                  Any error responded from ssl:connect/3
127
128              The Timeout parameter is for the actual tls  upgrade  (phase  2)
129              while  the timeout in eldap:open/2 is used for the initial nego‐
130              tiation about upgrade (phase 1).
131
132       simple_bind(Handle, Dn, Password) -> return_value()
133
134              Types:
135
136                 Handle = handle()
137                 Dn = string()
138                 Password = string()
139
140              Authenticate the connection using simple authentication.
141
142       add(Handle, Dn, [Attribute]) -> return_value()
143
144              Types:
145
146                 Handle = handle()
147                 Dn = string()
148                 Attribute = attribute()
149
150              Add an entry. The entry must not exist.
151
152                add(Handle,
153                    "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com",
154                     [{"objectclass", ["person"]},
155                      {"cn", ["Bill Valentine"]},
156                      {"sn", ["Valentine"]},
157                      {"telephoneNumber", ["545 555 00"]}]
158                   )
159
160
161       delete(Handle, Dn) -> return_value()
162
163              Types:
164
165                 Dn = string()
166
167              Delete an entry.
168
169                delete(Handle, "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com")
170
171
172       mod_add(Type, [Value]) -> modify_op()
173
174              Types:
175
176                 Type = string()
177                 Value = string()
178
179              Create an add modification operation.
180
181       mod_delete(Type, [Value]) -> modify_op()
182
183              Types:
184
185                 Type = string()
186                 Value = string()
187
188              Create a delete modification operation.
189
190       mod_replace(Type, [Value]) -> modify_op()
191
192              Types:
193
194                 Type = string()
195                 Value = string()
196
197              Create a replace modification operation.
198
199       modify(Handle, Dn, [ModifyOp]) -> return_value()
200
201              Types:
202
203                 Dn = string()
204                 ModifyOp = modify_op()
205
206              Modify an entry.
207
208                modify(Handle, "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com",
209                       [eldap:mod_replace("telephoneNumber", ["555 555 00"]),
210                     eldap:mod_add("description", ["LDAP Hacker"]) ])
211
212
213       modify_password(Handle, Dn, NewPasswd) -> return_value()  |  {ok,  Gen‐
214       Passwd}
215
216              Types:
217
218                 Dn = string()
219                 NewPasswd = string()
220
221              Modify the password of a user. See modify_password/4.
222
223       modify_password(Handle,  Dn,  NewPasswd, OldPasswd) -> return_value() |
224       {ok, GenPasswd}
225
226              Types:
227
228                 Dn = string()
229                 NewPasswd = string()
230                 OldPasswd = string()
231                 GenPasswd = string()
232
233              Modify the password of a user.
234
235                * Dn. The user to modify. Should be "" if the  modify  request
236                  is for the user of the LDAP session.
237
238                * NewPasswd.  The  new  password  to  set. Should be "" if the
239                  server is to generate the password. In this case, the result
240                  will be {ok, GenPasswd}.
241
242                * OldPasswd. Sometimes required by server policy for a user to
243                  change their password. If  not  required,  use  modify_pass‐
244                  word/3.
245
246       modify_dn(Handle, Dn, NewRDN, DeleteOldRDN, NewSupDN) -> return_value()
247
248              Types:
249
250                 Dn = string()
251                 NewRDN = string()
252                 DeleteOldRDN = boolean()
253                 NewSupDN = string()
254
255              Modify  the  DN  of an entry. DeleteOldRDN indicates whether the
256              current RDN should be removed from the attribute list after  the
257              after  operation.  NewSupDN is the new parent that the RDN shall
258              be moved to. If the old parent should remain as parent, NewSupDN
259              shall be "".
260
261                modify_dn(Handle, "cn=Bill Valentine, ou=people, o=Example Org, dc=example, dc=com ",
262                          "cn=Bill Jr Valentine", true, "")
263
264
265       search(Handle,  SearchOptions)  ->  {ok, #eldap_search_result{}} | {ok,
266       {referral,referrals()}} | {error, Reason}
267
268              Types:
269
270                 SearchOptions = #eldap_search{} | [SearchOption]
271                 SearchOption  =  {base,  string()}  |  {filter,  filter()}  |
272                 {scope,  scope()} | {attributes, [string()]} | {deref, deref‐
273                 erence()} | | {types_only, boolean()} | {timeout, integer()}
274
275              Search the directory with the supplied  the  SearchOptions.  The
276              base  and filter options must be supplied. Default values: scope
277              is wholeSubtree(), deref is derefAlways(), types_only  is  false
278              and timeout is 0 (meaning infinity).
279
280                Filter = eldap:substrings("cn", [{any,"V"}]),
281                search(Handle, [{base, "dc=example, dc=com"}, {filter, Filter}, {attributes, ["cn"]}]),
282
283
284              The  timeout option in the SearchOptions is for the ldap server,
285              while the timeout in eldap:open/2 is used  for  each  individual
286              request in the search operation.
287
288       baseObject() -> scope()
289
290              Search baseobject only.
291
292       singleLevel() -> scope()
293
294              Search the specified level only, i.e. do not recurse.
295
296       wholeSubtree() -> scope()
297
298              Search the entire subtree.
299
300       neverDerefAliases() -> dereference()
301
302              Never derefrence aliases, treat aliases as entries.
303
304       derefAlways() -> dereference()
305
306              Always derefrence aliases.
307
308       derefInSearching() -> dereference()
309
310              Derefrence aliases only when searching.
311
312       derefFindingBaseObj() -> dereference()
313
314              Derefrence aliases only in finding the base.
315
316       present(Type) -> filter()
317
318              Types:
319
320                 Type = string()
321
322              Create a filter which filters on attribute type presence.
323
324       substrings(Type, [SubString]) -> filter()
325
326              Types:
327
328                 Type = string()
329                 SubString = {StringPart, string()}
330                 StringPart = initial | any | final
331
332              Create a filter which filters on substrings.
333
334       equalityMatch(Type, Value) -> filter()
335
336              Types:
337
338                 Type = string()
339                 Value = string()
340
341              Create a equality filter.
342
343       greaterOrEqual(Type, Value) -> filter()
344
345              Types:
346
347                 Type = string()
348                 Value = string()
349
350              Create a greater or equal filter.
351
352       lessOrEqual(Type, Value) -> filter()
353
354              Types:
355
356                 Type = string()
357                 Value = string()
358
359              Create a less or equal filter.
360
361       approxMatch(Type, Value) -> filter()
362
363              Types:
364
365                 Type = string()
366                 Value = string()
367
368              Create a approximation match filter.
369
370       extensibleMatch(MatchValue, OptionalAttrs) -> filter()
371
372              Types:
373
374                 MatchValue = string()
375                 OptionalAttrs = [Attr]
376                 Attr  =  {matchingRule,string()}  |  {type,string()} | {dnAt‐
377                 tributes,boolean()}
378
379              Creates an extensible match filter. For example,
380
381                eldap:extensibleMatch("Bar", [{type,"sn"}, {matchingRule,"caseExactMatch"}]))
382
383
384              creates  a  filter  which  performs  a  caseExactMatch  on   the
385              attribute sn and matches with the value "Bar". The default value
386              of dnAttributes is false.
387
388       'and'([Filter]) -> filter()
389
390              Types:
391
392                 Filter = filter()
393
394              Creates a filter where all Filter must be true.
395
396       'or'([Filter]) -> filter()
397
398              Types:
399
400                 Filter = filter()
401
402              Create a filter where at least one of the Filter must be true.
403
404       'not'(Filter) -> filter()
405
406              Types:
407
408                 Filter = filter()
409
410              Negate a filter.
411
412
413
414Ericsson AB                       eldap 1.2.7                         eldap(3)
Impressum