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, de‐
79              liver, 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 en‐
111              cryption 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  ex‐
120                  plained  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              operation.  NewSupDN  is  the  new  parent that the RDN shall be
258              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 dereference aliases, treat aliases as entries.
303
304       derefAlways() -> dereference()
305
306              Always dereference aliases.
307
308       derefInSearching() -> dereference()
309
310              Dereference aliases only when searching.
311
312       derefFindingBaseObj() -> dereference()
313
314              Dereference 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  attri‐
385              bute  sn  and matches with the value "Bar". The default value of
386              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       paged_result_control(PageSize) ->  {control,  "1.2.840.113556.1.4.319",
413       true, binary()}
414
415              Types:
416
417                 PageSize = positive_integer()
418
419              Paged  results is an extension to the LDAP protocol specified by
420              RFC2696
421
422              This function creates a control with the specified page size for
423              use in search/3, for example:
424
425              Control = eldap:paged_result_control(50),
426              {ok, SearchResults} = search(Handle, [{base, "dc=example, dc=com"}], [Control]),
427
428
429       paged_result_control(PageSize,        Cookie)        ->       {control,
430       "1.2.840.113556.1.4.319", true, binary()}
431
432              Types:
433
434                 PageSize = positive_integer()
435                 Cookie = binary()
436
437              Paged results is an extension to the LDAP protocol specified  by
438              RFC2696
439
440              This function creates a control with the specified page size and
441              cookie for use in search/3 to retrieve the next results page.
442
443              For example:
444
445              PageSize = 50,
446              Control1 = eldap:paged_result_control(PageSize),
447              {ok, SearchResults1} = search(Handle, [{base, "dc=example, dc=com"}], [Control1]),
448              %% retrieve the returned cookie from the search results
449              {ok, Cookie1} = eldap:paged_result_cookie(SearchResults1),
450              Control2 = eldap:paged_result_control(PageSize, Cookie1),
451              {ok, SearchResults2} = eldap:search(Handle, [{base, "dc=example,dc=com"}], [Control2]),
452              %% etc
453
454
455       paged_result_cookie(SearchResult) -> binary()
456
457              Types:
458
459                 SearchResult = #eldap_search_result{}
460
461              Paged results is an extension to the LDAP protocol specified  by
462              RFC2696.
463
464              This  function extracts the cookie returned from the server as a
465              result of a paged search result.
466
467              If the returned cookie is the empty string "", then these search
468              results represent the last in the series.
469
470       info(Handle) -> connection_info()
471
472              Types:
473
474                 connection_info()  = #{socket := Socket, socket_type := tcp |
475                 ssl}
476                 Socket = ssl:sslsocket() | gen_tcp:socket()
477
478              Currently available  information  reveals  the  socket  and  the
479              transport  protocol,  TCP or TLS (SSL), used by the LDAP connec‐
480              tion.
481
482
483
484Ericsson AB                      eldap 1.2.11                         eldap(3)
Impressum