Debian Codegraph @

src/modules/ldap/README

raw
1 LDAP Module
2
3 Christian Schlatter
4
5 University of North Carolina
6 <[email protected]>
7
8 Copyright © 2007 University of North Carolina
9 __________________________________________________________________
10
11 Table of Contents
12
13 1. Admin Guide
14
15 1. Overview
16
17 1.1. Usage Basics
18 1.2. LDAP URLs
19
20 2. Dependencies
21
22 2.1. Kamailio Modules
23 2.2. External Libraries or Applications
24
25 3. LDAP Configuration File
26
27 3.1. Configuration File Syntax
28 3.2. LDAP Session Settings
29 3.3. Configuration File Example
30
31 4. Parameters
32
33 4.1. config_file (string)
34 4.2. connect_mode (int)
35
36 5. Functions
37
38 5.1. ldap_search(ldap_url)
39 5.2. ldap_result("ldap_attr_name/avp_spec[/avp_type]" [,
40 regex_subst])
41
42 5.3. ldap_result_check("ldap_attr_name/string_to_match" [,
43 regex_subst])
44
45 5.4. ldap_result_next()
46 5.5. ldap_filter_url_encode(string, avp_spec)
47
48 6. Installation & Running
49
50 6.1. Compiling the LDAP module
51
52 2. Developer Guide
53
54 1. Overview
55 2. API Functions
56
57 2.1. ldap_params_search
58 2.2. ldap_url_search
59 2.3. ldap_result_attr_vals
60 2.4. ldap_value_free_len
61 2.5. ldap_result_next
62 2.6. ldap_str2scope
63 2.7. ldap_rfc4515_escape
64 2.8. get_ldap_handle
65 2.9. get_last_ldap_result
66
67 3. Example Usage
68
69 Resources
70
71 List of Tables
72
73 1.1. RFC 4515 Escaping Rules
74 1.2. ldap_filter_url_encode() escaping rules
75
76 List of Examples
77
78 1.1. ldap_server_url examples
79 1.2. ldap_version example
80 1.3. ldap_bind_dn example
81 1.4. ldap_bind_password example
82 1.5. ldap_network_timeout example
83 1.6. ldap_client_bind_timeout example
84 1.7. Example LDAP Configuration File
85 1.8. config_file parameter usage
86 1.9. Set connect_mode parameter
87 1.10. Example Usage of ldap_url
88 1.11. Example Usage
89 1.12. Example Usage
90 1.13. Example Usage
91 1.14. Example Usage
92 1.15. Example Usage
93 2.1. Example code fragment to load LDAP module API
94 2.2. Example LDAP module API function call
95
96 Chapter 1. Admin Guide
97
98 Table of Contents
99
100 1. Overview
101
102 1.1. Usage Basics
103 1.2. LDAP URLs
104
105 2. Dependencies
106
107 2.1. Kamailio Modules
108 2.2. External Libraries or Applications
109
110 3. LDAP Configuration File
111
112 3.1. Configuration File Syntax
113 3.2. LDAP Session Settings
114 3.3. Configuration File Example
115
116 4. Parameters
117
118 4.1. config_file (string)
119 4.2. connect_mode (int)
120
121 5. Functions
122
123 5.1. ldap_search(ldap_url)
124 5.2. ldap_result("ldap_attr_name/avp_spec[/avp_type]" [,
125 regex_subst])
126
127 5.3. ldap_result_check("ldap_attr_name/string_to_match" [,
128 regex_subst])
129
130 5.4. ldap_result_next()
131 5.5. ldap_filter_url_encode(string, avp_spec)
132
133 6. Installation & Running
134
135 6.1. Compiling the LDAP module
136
137 1. Overview
138
139 1.1. Usage Basics
140 1.2. LDAP URLs
141
142 The LDAP module implements an LDAP search interface for Kamailio. It
143 exports script functions to perform an LDAP search operation and to
144 store the search results as Kamailio AVPs. This allows for using LDAP
145 directory data in the Kamailio SIP message routing script.
146
147 The following features are offered by the LDAP module:
148 * LDAP search function based on a LDAP URL
149 * LDAP result parsing functions to store LDAP data as AVP variables
150 * Support for accessing multiple LDAP servers
151 * LDAP SIMPLE authentication
152 * LDAP server failover and automatic reconnect
153 * Configurable LDAP connection and bind timeouts
154 * Module API for LDAP search operations that can be used by other
155 Kamailio modules
156
157 The module implementation makes use of the open source OpenLDAP library
158 available on most UNIX/Linux platforms. Besides LDAP server failover
159 and automatic reconnect, this module can handle multiple LDAP sessions
160 concurrently allowing access to data stored on different LDAP servers.
161 Each Kamailio worker process maintains one LDAP TCP connection per
162 configured LDAP server. This enables parallel execution of LDAP
163 requests and offloads LDAP concurrency control to the LDAP server(s).
164
165 An LDAP search module API is provided that can be used by other
166 Kamailio modules. A module using this API does not have to implement
167 LDAP connection management and configuration, while still having access
168 to the full OpenLDAP API for searching and result handling.
169
170 Since LDAP server implementations are optimized for fast read access
171 they are a good choice to store SIP provisioning data. Performance
172 tests have shown that this module achieves lower data access times and
173 higher call rates than other database modules like e.g. the Kamailio
174 MYSQL module.
175
176 1.1. Usage Basics
177
178 LDAP sessions is specified in an external configuration file (as
179 described in Section 3, “LDAP Configuration File”). Each of these LDAP
180 sessions includes LDAP server access parameters like server hostname or
181 connection timeouts. Normally only a single LDAP session per process
182 will be used unless there is a need to access more than one LDAP
183 server. The LDAP session name will then be used in the Kamailio
184 configuration script to refer to a specific LDAP session.
185
186 The ldap_search function (Section 5.1, “ldap_search(ldap_url)”)
187 performs an LDAP search operation. It expects an LDAP URL as input
188 which includes the LDAP session name and search parameters. The section
189 Section 1.2, “LDAP URLs” provides a quick overview on LDAP URLs.
190
191 The result of a LDAP search is stored internally and can be accessed
192 with one of the ldap_result* functions. ldap_result (Section 5.2,
193 “ldap_result("ldap_attr_name/avp_spec[/avp_type]" [, regex_subst])”)
194 stores resulting LDAP attribute values as AVPs. ldap_result_check
195 (Section 5.3, “ldap_result_check("ldap_attr_name/string_to_match" [,
196 regex_subst])”) is a convenience function to compare a string with LDAP
197 attribute values using regular expression matching. Finally,
198 ldap_result_next (Section 5.4, “ldap_result_next()”) allows using LDAP
199 search queries that return more than one LDAP entry.
200
201 All ldap_result* functions always access the LDAP result set from the
202 last ldap_search call. This should be kept in mind when calling
203 ldap_search more than once in the Kamailio configuration script.
204
205 1.2. LDAP URLs
206
207 ldap_search expects an LDAP URL as argument. This section describes the
208 format and semantics of an LDAP URL.
209
210 RFC 4516 [RFC4516] describes the format of an LDAP Uniform Resource
211 Locator (URL). An LDAP URL represents an LDAP search operation in a
212 compact format. The LDAP URL format is defined as follows (slightly
213 modified, refer to section 2 of [RFC4516] for ABNF notation):
214
215 ldap://[ldap_session_name][/dn?attrs[?scope[?filter]]]]
216
217 ldap_session_name
218 An LDAP session name as defined in the LDAP configuration file.
219
220 (RFC 4516 defines this as LDAP hostport parameter)
221
222 dn
223 Base Distinguished Name (DN) of LDAP search or target of
224 non-search operation, as defined in RFC 4514 [RFC4514]
225
226 attrs
227 Comma separated list of LDAP attributes to be returned
228
229 scope
230 Scope for LDAP search, valid values are “base”, “one”, or “sub”
231
232 filter
233 LDAP search filter definition following rules of RFC 4515
234 [RFC4515]
235
236 Note
237
238 The following table lists characters that have to be escaped in
239 LDAP search filters:
240
241 Table 1.1. RFC 4515 Escaping Rules
242
243 * \2a
244 ( \28
245 ) \29
246 \ \5c
247
248 Note
249
250 Non-URL characters in an LDAP URL have to be escaped using
251 percent-encoding (refer to section 2.1 of RFC 4516). In particular this
252 means that any "?" character in an LDAP URL component must be written
253 as "%3F", since "?" is used as a URL delimiter.
254
255 The exported function ldap_filter_url_encode (Section 5.5,
256 “ldap_filter_url_encode(string, avp_spec)”) implements RFC 4515/4516
257 LDAP search filter and URL escaping rules.
258
259 2. Dependencies
260
261 2.1. Kamailio Modules
262 2.2. External Libraries or Applications
263
264 2.1. Kamailio Modules
265
266 The module depends on the following modules (the listed modules must be
267 loaded before this module):
268 * No dependencies on other Kamailio modules.
269
270 2.2. External Libraries or Applications
271
272 The following libraries or applications must be installed before
273 running Kamailio with this module loaded:
274 * OpenLDAP library (libldap) v2.1 or greater, libldap header files
275 (libldap-dev) are needed for compilation
276 OpenSSL library if you compile your OpenLDAP library with SSL/TLS
277 support.
278
279 3. LDAP Configuration File
280
281 3.1. Configuration File Syntax
282 3.2. LDAP Session Settings
283 3.3. Configuration File Example
284
285 The module reads an external configuration file at module
286 initialization time that includes LDAP session definitions.
287
288 3.1. Configuration File Syntax
289
290 The configuration file follows the Windows INI file syntax, section
291 names are enclosed in square brackets:
292 [Section_Name]
293
294 Any section can contain zero or more configuration key assignments of
295 the form
296 key = value ; comment
297
298 Values can be given enclosed with quotes. If no quotes are present, the
299 value is understood as containing all characters between the first and
300 the last non-blank characters. Lines starting with a hash sign and
301 blank lines are treated as comments.
302
303 Each section describes one LDAP session that can be referred to in the
304 Kamailio configuration script. Using the section name as the host part
305 of an LDAP URL tells the module to use the LDAP session specified in
306 the respective section. An example LDAP session specification looks
307 like:
308 [example_ldap]
309 ldap_server_url = "ldap://ldap1.example.com, ldap://ldap2.example.com
310 "
311 ldap_bind_dn = "cn=sip_proxy,ou=accounts,dc=example,dc=com"
312 ldap_bind_password = "pwd"
313 ldap_network_timeout = 500
314 ldap_client_bind_timeout = 500
315
316 The configuration keys are explained in the following section. This
317 LDAP session can be referred to in the routing script by using an LDAP
318 URL like e.g.
319 ldap://example_ldap/cn=admin,dc=example,dc=com
320
321 3.2. LDAP Session Settings
322
323 ldap_server_url (mandatory)
324 LDAP URL including fully qualified domain name or IP address of
325 LDAP server optionally followed by a colon and TCP port to
326 connect: ldap://<FQDN/IP>[:<port>]. Failover LDAP servers can be
327 added, each separated by a comma. In the event of connection
328 errors, the module tries to connect to servers in order of
329 appearance. To connect over TLS/SSL, use ldaps://.
330
331 Default value: none, this is a mandatory setting
332
333 Example 1.1. ldap_server_url examples
334
335 ldap_server_url = "ldap://localhost"
336 ldap_server_url = "ldaps://ldap.example.com:7777"
337 ldap_server_url = "ldap://ldap1.example.com,
338 ldap://ldap2.example.com:80389"
339
340 ldap_version (optional)
341 Supported LDAP versions are 2 and 3.
342
343 Default value: 3 (LDAPv3)
344
345 Example 1.2. ldap_version example
346
347 ldap_version = 2
348
349 ldap_bind_dn (optional)
350 Authentication user DN used to bind to LDAP server (module
351 currently only supports SIMPLE_AUTH). Empty string enables
352 anonymous LDAP bind.
353
354 Default value: “” (empty string --> anonymous bind)
355
356 Example 1.3. ldap_bind_dn example
357
358 ldap_bind_dn = "cn=root,dc=example,dc=com";
359
360 ldap_bind_password (optional)
361 Authentication password used to bind to LDAP server
362 (SIMPLE_AUTH). Empty string enables anonymous bind.
363
364 Default value: “” (empty string --> anonymous bind)
365
366 Example 1.4. ldap_bind_password example
367
368 ldap_bind_password = "secret";
369
370 ldap_network_timeout (optional)
371 LDAP TCP connect timeout in milliseconds. Setting this parameter
372 to a low value enables fast failover if ldap_server_url contains
373 more than one LDAP server addresses.
374
375 Default value: 1000 (one second)
376
377 Example 1.5. ldap_network_timeout example
378
379 ldap_network_timeout = 500 ; setting TCP timeout to 500 ms
380
381 ldap_client_bind_timeout (optional)
382 LDAP bind operation timeout in milliseconds.
383
384 Default value: 1000 (one second)
385
386 Example 1.6. ldap_client_bind_timeout example
387
388 ldap_client_bind_timeout = 1000
389
390 3.3. Configuration File Example
391
392 The following configuration file example includes two LDAP session
393 definitions that could be used e.g. for accessing H.350 data and do
394 phone number to name mappings.
395
396 Example 1.7. Example LDAP Configuration File
397 # LDAP session "sipaccounts":
398 #
399 # - using LDAPv3 (default)
400 # - two redundant LDAP servers
401 #
402 [sipaccounts]
403 ldap_server_url = "ldap://h350-1.example.com, ldap://h350-2.example.com"
404 ldap_bind_dn = "cn=sip_proxy,ou=accounts,dc=example,dc=com"
405 ldap_bind_password = "pwd"
406 ldap_network_timeout = 500
407 ldap_client_bind_timeout = 500
408
409
410 # LDAP session "campus":
411 #
412 # - using LDAPv2
413 # - anonymous bind
414 #
415 [campus]
416 ldap_version = 2
417 ldap_server_url = "ldap://ldap.example.com"
418 ldap_network_timeout = 500
419 ldap_client_bind_timeout = 500
420
421 4. Parameters
422
423 4.1. config_file (string)
424 4.2. connect_mode (int)
425
426 4.1. config_file (string)
427
428 Full path to LDAP configuration file.
429
430 Default value: /usr/local/etc/kamailio/ldap.cfg
431
432 Example 1.8. config_file parameter usage
433 modparam("ldap", "config_file", "/usr/local/etc/kamailio/ldap.ini")
434
435 4.2. connect_mode (int)
436
437 Control if the module must stop loading when connecting to server fails
438 during start up. Values: 0 - stop loading; 1 - continue even if
439 connecting to database server fails..
440
441 Default value: 0
442
443 Example 1.9. Set connect_mode parameter
444 modparam("ldap", "connect_mode", 1)
445
446 5. Functions
447
448 5.1. ldap_search(ldap_url)
449 5.2. ldap_result("ldap_attr_name/avp_spec[/avp_type]" [, regex_subst])
450 5.3. ldap_result_check("ldap_attr_name/string_to_match" [,
451 regex_subst])
452
453 5.4. ldap_result_next()
454 5.5. ldap_filter_url_encode(string, avp_spec)
455
456 5.1. ldap_search(ldap_url)
457
458 Performs an LDAP search operation using given LDAP URL and stores
459 result internally for later retrieval by ldap_result* functions. If one
460 or more LDAP entries are found the function returns the number of found
461 entries which evaluates to TRUE in the Kamailio configuration script.
462 It returns -1 (FALSE) in case no LDAP entry was found, and -2 (FALSE)
463 if an internal error like e.g. an LDAP error occurred.
464
465 Function Parameters:
466
467 ldap_url
468 An LDAP URL defining the LDAP search operation (refer to
469 Section 1.2, “LDAP URLs” for a description of the LDAP URL
470 format). The hostport part must be one of the LDAP session names
471 declared in the LDAP configuration script.
472
473 Kamailio pseudo variables and AVPs included in ldap_url do get
474 substituted with their value.
475
476 Example 1.10. Example Usage of ldap_url
477
478 Search with LDAP session named sipaccounts, base
479 ou=sip,dc=example,dc=com, one level deep using search filter
480 (cn=schlatter) and returning all attributes:
481
482 ldap://sipaccounts/ou=sip,dc=example,dc=com??one?(cn=schlatter)
483
484 Subtree search with LDAP session named ldap1, base
485 dc=example,dc=com using search filter (cn=$(avp(s:name))) and
486 returning SIPIdentityUserName and SIPIdentityServiceLevel
487 attributes
488
489 ldap://ldap_1/dc=example,dc=com?
490 SIPIdentityUserName,SIPIdentityServiceLevel?sub?(cn=$(avp(s:name)))
491
492 Return Values:
493
494 n > 0 (TRUE):
495
496 + Found n matching LDAP entries
497
498 -1 (FALSE):
499
500 + No matching LDAP entries found
501
502 -2 (FALSE):
503
504 + LDAP error (e.g. LDAP server unavailable), or
505 + internal error
506
507 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
508 BRANCH_ROUTE, and ONREPLY_ROUTE.
509
510 Example 1.11. Example Usage
511 ...
512 # ldap search
513 if (!ldap_search("ldap://sipaccounts/ou=sip,dc=example,dc=com??one?(cn=$rU)"))
514 {
515 switch ($retcode)
516 {
517 case -1:
518 # no LDAP entry found
519 sl_send_reply("404", "User Not Found");
520 exit;
521 case -2:
522 # internal error
523 sl_send_reply("500", "Internal server error");
524 exit;
525 default:
526 exit;
527 }
528 }
529 xlog("L_INFO", "ldap_search: found [$retcode] entries for (cn=$rU)");
530
531 # save telephone number in $avp(s:tel_number)
532 ldap_result("telephoneNumber/$avp(s:tel_number)");
533 ...
534
535 5.2. ldap_result("ldap_attr_name/avp_spec[/avp_type]" [, regex_subst])
536
537 This function converts LDAP attribute values into AVPs for later use in
538 the message routing script. It accesses the LDAP result set fetched by
539 the last ldap_search call. ldap_attr_name specifies the LDAP attribute
540 name who's value will be stored in AVP avp_spec. Multi valued LDAP
541 attributes generate an indexed AVP. The optional regex_subst parameter
542 allows to further define what part of an attribute value should be
543 stored as AVP.
544
545 An AVP can either be of type string or integer. As default, ldap_result
546 stores LDAP attribute values as AVP of type string. The optional
547 avp_type parameter can be used to explicitly specify the type of the
548 AVP. It can be either str for string, or int for integer. If avp_type
549 is specified as int then ldap_result tries to convert the LDAP
550 attribute values to integer. In this case, the values are only stored
551 as AVP if the conversion to integer is successful.
552
553 Function Parameters:
554
555 ldap_attr_name
556 The name of the LDAP attribute who's value should be stored,
557 e.g. SIPIdentityServiceLevel or telephonenumber
558
559 avp_spec
560 Specification of destination AVP, e.g. $avp(s:service_level) or
561 $avp(i:12)
562
563 avp_type
564 Optional specification of destination AVP type, either str or
565 int. If this parameter is not specified then the LDAP attribute
566 values are stored as AVP of type string.
567
568 regex_subst
569 Regex substitution that gets applied to LDAP attribute value
570 before storing it as AVP, e.g. "/^sip:(.+)$/\1/" to strip off
571 "sip:" from the beginning of an LDAP attribute value.
572
573 Return Values:
574
575 n > 0 (TRUE)
576 LDAP attribute ldap_attr_name found in LDAP result set and n
577 LDAP attribute values stored in avp_spec
578
579 -1 (FALSE)
580 No LDAP attribute ldap_attr_name found in LDAP result set
581
582 -2 (FALSE)
583 Internal error occurred
584
585 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
586 BRANCH_ROUTE, and ONREPLY_ROUTE.
587
588 Example 1.12. Example Usage
589 ...
590
591 # ldap_search call
592 ...
593
594 # save SIPIdentityServiceLevel in $avp(s:service_level)
595 if (!ldap_result("SIPIdentityServiceLevel/$avp(s:service_level)"))
596 {
597 switch ($retcode)
598 {
599 case -1:
600 # no SIPIdentityServiceLevel found
601 sl_send_reply("403", "Forbidden");
602 exit;
603 case -2:
604 # internal error
605 sl_send_reply("500", "Internal server error");
606 exit;
607 default:
608 exit;
609 }
610 }
611
612 # save SIP URI domain in $avp(i:10)
613 ldap_result("SIPIdentitySIPURI/$avp(i:10)", "/^[^@]+@(.+)$/\1/");
614 ...
615
616 5.3. ldap_result_check("ldap_attr_name/string_to_match" [, regex_subst])
617
618 This function compares ldap_attr_name's value with string_to_match for
619 equality. It accesses the LDAP result set fetched by the last
620 ldap_search call. The optional regex_subst parameter allows to further
621 define what part of the attribute value should be used for the equality
622 match. If ldap_attr_name is multi valued, each value is checked against
623 string_to_match. If one or more of the values do match the function
624 returns 1 (TRUE).
625
626 Function Parameters:
627
628 ldap_attr_name
629 The name of the LDAP attribute who's value should be matched,
630 e.g. SIPIdentitySIPURI
631
632 string_to_match
633 String to be matched. Included AVPs and pseudo variables do get
634 expanded.
635
636 regex_subst
637 Regex substitution that gets applied to LDAP attribute value
638 before comparing it with string_to_match, e.g.
639 "/^[^@]@+(.+)$/\1/" to extract the domain part of a SIP URI
640
641 Return Values:
642
643 1 (TRUE)
644 One or more ldap_attr_name attribute values match
645 string_to_match (after regex_subst is applied)
646
647 -1 (FALSE)
648 ldap_attr_name attribute not found or attribute value doesn't
649 match string_to_match (after regex_subst is applied)
650
651 -2 (FALSE)
652 Internal error occurred
653
654 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
655 BRANCH_ROUTE, and ONREPLY_ROUTE.
656
657 Example 1.13. Example Usage
658 ...
659 # ldap_search call
660 ...
661
662 # check if 'sn' ldap attribute value equals username part of R-URI,
663 # the same could be achieved with ldap_result_check("sn/$rU")
664 if (!ldap_result_check("sn/$ru", "/^sip:([^@]).*$/\1/"))
665 {
666 switch ($retcode)
667 {
668 case -1:
669 # R-URI username doesn't match sn
670 sl_send_reply("401", "Unauthorized");
671 exit;
672 case -2:
673 # internal error
674 sl_send_reply("500", "Internal server error");
675 exit;
676 default:
677 exit;
678 }
679 }
680 ...
681
682 5.4. ldap_result_next()
683
684 An LDAP search operation can return multiple LDAP entries. This
685 function can be used to cycle through all returned LDAP entries. It
686 returns 1 (TRUE) if there is another LDAP entry present in the LDAP
687 result set and causes ldap_result* functions to work on the next LDAP
688 entry. The function returns -1 (FALSE) if there are no more LDAP
689 entries in the LDAP result set.
690
691 Return Values:
692
693 1 (TRUE)
694 Another LDAP entry is present in the LDAP result set and result
695 pointer is incremented by one
696
697 -1 (FALSE)
698 No more LDAP entries are available
699
700 -2 (FALSE)
701 Internal error
702
703 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
704 BRANCH_ROUTE, and ONREPLY_ROUTE.
705
706 Example 1.14. Example Usage
707 ...
708 # ldap_search call
709 ...
710
711 ldap_result("telephonenumber/$avp(s:tel1)");
712 if (ldap_result_next())
713 {
714 ldap_result("telephonenumber/$avp(s:tel2)");
715 }
716 if (ldap_result_next())
717 {
718 ldap_result("telephonenumber/$avp(s:tel3)");
719 }
720 if (ldap_result_next())
721 {
722 ldap_result("telephonenumber/$avp(s:tel4)");
723 }
724 ...
725
726 5.5. ldap_filter_url_encode(string, avp_spec)
727
728 This function applies the following escaping rules to string and stores
729 the result in AVP avp_spec:
730
731 Table 1.2. ldap_filter_url_encode() escaping rules
732 character in string gets replaced with defined in
733 * \2a RFC 4515
734 ( \28 RFC 4515
735 ) \29 RFC 4515
736 \ \5c RFC 4515
737 ? %3F RFC 4516
738
739 The string stored in AVP avp_spec can be safely used in an LDAP URL
740 filter string.
741
742 Function Parameters:
743
744 string
745 String to apply RFC 4515 and URL escaping rules to. AVPs and
746 pseudo variables do get expanded. Example: "cn=$avp(s:name)"
747
748 avp_spec
749 Specification of AVP to store resulting RFC 4515 and URL encoded
750 string, e.g. $avp(s:ldap_search) or $avp(i:10)
751
752 Return Values:
753
754 1 (TRUE)
755 RFC 4515 and URL encoded filter_component stored as AVP avp_name
756
757 -1 (FALSE)
758 Internal error
759
760 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
761 BRANCH_ROUTE, and ONREPLY_ROUTE.
762
763 Example 1.15. Example Usage
764 ...
765 if (!ldap_filter_url_encode("cn=$avp(s:name)", "$avp(s:name_esc)"))
766 {
767 # RFC 4515/URL encoding failed --> silently discard request
768 exit;
769 }
770
771 xlog("L_INFO", "encoded LDAP filter component: [$avp(s:name_esc)]\n");
772
773 if (ldap_search(
774 "ldap://h350/ou=commObjects,dc=example,dc=com??sub?($avp(s:name_esc))"))
775 { ... }
776 ...
777
778 6. Installation & Running
779
780 6.1. Compiling the LDAP module
781
782 6.1. Compiling the LDAP module
783
784 OpenLDAP library (libldap) and header files (libldap-dev) v2.1 or
785 greater (this module was tested with v2.1.3 and v2.3.32) are required
786 for compiling the LDAP module. The OpenLDAP source is available at
787 http://www.openldap.org/. Note that TLS support needs to be added a
788 compile time for the libraries.
789
790 The OpenLDAP library is available pre-compiled for most UNIX/Linux
791 flavors. On Debian/Ubuntu, the following packages must be installed:
792 # apt-get install libldap2 libldap2-dev
793
794 .
795
796 Chapter 2. Developer Guide
797
798 Table of Contents
799
800 1. Overview
801 2. API Functions
802
803 2.1. ldap_params_search
804 2.2. ldap_url_search
805 2.3. ldap_result_attr_vals
806 2.4. ldap_value_free_len
807 2.5. ldap_result_next
808 2.6. ldap_str2scope
809 2.7. ldap_rfc4515_escape
810 2.8. get_ldap_handle
811 2.9. get_last_ldap_result
812
813 3. Example Usage
814
815 1. Overview
816
817 The LDAP module API can be used by other Kamailio modules to implement
818 LDAP search functionality. This frees the module implementer from
819 having to care about LDAP connection management and configuration.
820
821 In order to use this API, a module has to load the API using the
822 load_ldap_api function which returns a pointer to a ldap_api structure.
823 This structure includes pointers to the API functions described below.
824 The LDAP module source file api.h includes all declarations needed to
825 load the API, it has to be included in the file that use the API.
826 Loading the API is typically done inside a module's mod_init call as
827 the following example shows:
828
829 Example 2.1. Example code fragment to load LDAP module API
830 #include "../../sr_module.h"
831 #include "../ldap/api.h"
832
833 /*
834 * global pointer to ldap api
835 */
836 extern ldap_api_t ldap_api;
837
838 ...
839
840 static int mod_init(void)
841 {
842 /*
843 * load the LDAP API
844 */
845 if (load_ldap_api(&ldap_api) != 0)
846 {
847 LM_ERR("Unable to load LDAP API - this module requires ldap module\n");
848 return -1;
849 }
850
851 ...
852 }
853
854 ...
855
856 The API functions can then be used like in the following example:
857
858 Example 2.2. Example LDAP module API function call
859 ...
860
861 rc = ldap_api.ldap_rfc4515_escape(str1, str2, 0);
862
863 ...
864
865 2. API Functions
866
867 2.1. ldap_params_search
868 2.2. ldap_url_search
869 2.3. ldap_result_attr_vals
870 2.4. ldap_value_free_len
871 2.5. ldap_result_next
872 2.6. ldap_str2scope
873 2.7. ldap_rfc4515_escape
874 2.8. get_ldap_handle
875 2.9. get_last_ldap_result
876
877 2.1. ldap_params_search
878
879 Performs an LDAP search using the parameters given as function
880 arguments.
881 typedef int (*ldap_params_search_t)(int* _ld_result_count,
882 char* _lds_name,
883 char* _dn,
884 int _scope,
885 char** _attrs,
886 char* _filter,
887 ...);
888
889 Function arguments:
890
891 int* _ld_result_count
892 The function stores the number of returned LDAP entries in
893 _ld_result_count.
894
895 char* _lds_name
896 LDAP session name as configured in the LDAP module configuration
897 file.
898
899 char* _dn
900 LDAP search DN.
901
902 int _scope
903 LDAP search scope, one of LDAP_SCOPE_ONELEVEL, LDAP_SCOPE_BASE,
904 or LDAP_SCOPE_SUBTREE, as defined in OpenLDAP's ldap.h.
905
906 char** _attrs
907 A null-terminated array of attribute types to return from
908 entries. If empty (NULL), all attribute types are returned.
909
910 char* _filter
911 LDAP search filter string according to RFC 4515. printf patterns
912 in this string do get replaced with the function arguments'
913 values following the _filter argument.
914
915 Return Values:
916
917 -1
918 Internal error.
919
920 0
921 Success, _ld_result_count includes the number of LDAP entries
922 found.
923
924 2.2. ldap_url_search
925
926 Performs an LDAP search using an LDAP URL.
927 typedef int (*ldap_url_search_t)(char* _ldap_url,
928 int* _result_count);
929
930 Function arguments:
931
932 char* _ldap_url
933 LDAP URL as described in Section 1.2, “LDAP URLs”.
934
935 int* _result_count
936 The function stores the number of returned LDAP entries in
937 _ld_result_count.
938
939 Return Values:
940
941 -1
942 Internal error.
943
944 0
945 Success, _ld_result_count includes the number of LDAP entries
946 found.
947
948 2.3. ldap_result_attr_vals
949
950 Retrieve the value(s) of a returned LDAP attribute. The function
951 accesses the LDAP result returned by the last call of
952 ldap_params_search or ldap_url_search. The berval structure is defined
953 in OpenLDAP's ldap.h, which has to be included.
954
955 This function allocates memory to store the LDAP attribute value(s).
956 This memory has to freed with the function ldap_value_free_len (see
957 next section).
958 typedef int (*ldap_result_attr_vals_t)(str* _attr_name,
959 struct berval ***_vals);
960
961 typedef struct berval {
962 ber_len_t bv_len;
963 char *bv_val;
964 } BerValue;
965
966 Function arguments:
967
968 str* _attr_name
969 str structure holding the LDAP attribute name.
970
971 struct berval ***_vals
972 A null-terminated array of the attribute's value(s).
973
974 Return Values:
975
976 -1
977 Internal error.
978
979 0
980 Success, _vals includes the attribute's value(s).
981
982 1
983 No attribute value found.
984
985 2.4. ldap_value_free_len
986
987 Function used to free memory allocated by ldap_result_attr_vals. The
988 berval structure is defined in OpenLDAP's ldap.h, which has to be
989 included.
990 typedef void (*ldap_value_free_len_t)(struct berval **_vals);
991
992 typedef struct berval {
993 ber_len_t bv_len;
994 char *bv_val;
995 } BerValue;
996
997 Function arguments:
998
999 struct berval **_vals
1000 berval array returned by ldap_result_attr_vals.
1001
1002 2.5. ldap_result_next
1003
1004 Increments the LDAP result pointer.
1005 typedef int (*ldap_result_next_t)();
1006
1007 Return Values:
1008
1009 -1
1010 No LDAP result found, probably because ldap_params_search or
1011 ldap_url_search was not called.
1012
1013 0
1014 Success, LDAP result pointer points now to next result.
1015
1016 1
1017 No more results available.
1018
1019 2.6. ldap_str2scope
1020
1021 Converts LDAP search scope string into integer value e.g. for
1022 ldap_params_search.
1023 typedef int (*ldap_str2scope_t)(char* scope_str);
1024
1025 Function arguments:
1026
1027 char* scope_str
1028 LDAP search scope string. One of "one", "onelevel", "base",
1029 "sub", or "subtree".
1030
1031 Return Values:
1032
1033 -1
1034 scope_str not recognized.
1035
1036 n >= 0
1037 LDAP search scope integer.
1038
1039 2.7. ldap_rfc4515_escape
1040
1041 Applies escaping rules described in Section 5.5,
1042 “ldap_filter_url_encode(string, avp_spec)”.
1043 typedef int (*ldap_rfc4515_escape_t)(str *sin, str *sout, int url_encode);
1044
1045 Function arguments:
1046
1047 str *sin
1048 str structure holding the string to apply the escaping rules.
1049
1050 str *sout
1051 str structure holding the escaped string. The length of this
1052 string must be at least three times the length of sin plus one.
1053
1054 int url_encode
1055 Flag that specifies if a '?' character gets escaped with '%3F'
1056 or not. If url_encode equals 0, '?' does not get escaped.
1057
1058 Return Values:
1059
1060 -1
1061 Internal error.
1062
1063 0
1064 Success, sout contains escaped string.
1065
1066 2.8. get_ldap_handle
1067
1068 Returns the OpenLDAP LDAP handle for a specific LDAP session. This
1069 allows a module implementor to use the OpenLDAP API functions directly,
1070 instead of using the API functions exported by the Kamailio LDAP
1071 module. The LDAP structure is defined in OpenLDAP's ldap.h, which has
1072 to be included.
1073 typedef int (*get_ldap_handle_t)(char* _lds_name, LDAP** _ldap_handle);
1074
1075 Function arguments:
1076
1077 char* _lds_name
1078 LDAP session name as specified in the LDAP module configuration
1079 file.
1080
1081 LDAP** _ldap_handle
1082 OpenLDAP LDAP handle returned by this function.
1083
1084 Return Values:
1085
1086 -1
1087 Internal error.
1088
1089 0
1090 Success, _ldap_handle contains the OpenLDAP LDAP handle.
1091
1092 2.9. get_last_ldap_result
1093
1094 Returns the OpenLDAP LDAP handle and OpenLDAP result handle of the last
1095 LDAP search operation. These handles can be used as input for OpenLDAP
1096 LDAP result API functions. LDAP and LDAPMessage structures are defined
1097 in OpenLDAP's ldap.h, which has to be included.
1098 typedef void (*get_last_ldap_result_t)
1099 (LDAP** _last_ldap_handle, LDAPMessage** _last_ldap_result);
1100
1101 Function arguments:
1102
1103 LDAP** _last_ldap_handle
1104 OpenLDAP LDAP handle returned by this function.
1105
1106 LDAPMessage** _last_ldap_result
1107 OpenLDAP result handle returned by this function.
1108
1109 3. Example Usage
1110
1111 The following example shows how this API can be used to perform an LDAP
1112 search operation. It is assumed that the API is loaded and available
1113 through the ldap_api pointer.
1114 ...
1115
1116 int rc, ld_result_count, scope = 0;
1117 char* sip_username = "test";
1118
1119 /*
1120 * get LDAP search scope integer
1121 */
1122 scope = ldap_api.ldap_str2scope("sub");
1123 if (scope == -1)
1124 {
1125 LM_ERR("ldap_str2scope failed\n");
1126 return -1;
1127 }
1128
1129 /*
1130 * perform LDAP search
1131 */
1132
1133 if (ldap_api.ldap_params_search(
1134 &ld_result_count,
1135 "campus",
1136 "dc=example,dc=com",
1137 scope,
1138 NULL,
1139 "(&(objectClass=SIPIdentity)(SIPIdentityUserName=%s))",
1140 sip_username)
1141 != 0)
1142 {
1143 LM_ERR("LDAP search failed\n");
1144 return -1;
1145 }
1146
1147 /*
1148 * check result count
1149 */
1150 if (ld_result_count < 1)
1151 {
1152 LM_ERR("LDAP search returned no entry\n");
1153 return 1;
1154 }
1155
1156 /*
1157 * get password attribute value
1158 */
1159
1160 struct berval **attr_vals = NULL;
1161 str ldap_pwd_attr_name = str_init("SIPIdentityPassword");
1162 str res_password;
1163
1164 rc = ldap_api.ldap_result_attr_vals(&ldap_pwd_attr_name, &attr_vals);
1165 if (rc < 0)
1166 {
1167 LM_ERR("ldap_result_attr_vals failed\n");
1168 ldap_api.ldap_value_free_len(attr_vals);
1169 return -1;
1170 }
1171 if (rc == 1)
1172 {
1173 LM_INFO("No password attribute value found for [%s]\n", sip_username);
1174 ldap_api.ldap_value_free_len(attr_vals);
1175 return 2;
1176 }
1177
1178 res_password.s = attr_vals[0]->bv_val;
1179 res_password.len = attr_vals[0]->bv_len;
1180
1181 ldap_api.ldap_value_free_len(attr_vals);
1182
1183 LM_INFO("Password for user [%s]: [%s]\n", sip_username, res_password.s);
1184
1185 ...
1186
1187 return 0;
1188
1189 Resources
1190
1191 [RFC4510] Lightweight Directory Access Protocol (LDAP): Technical
1192 Specification Road Map. June 2006. Internet Engineering Task Force.
1193
1194 [RFC4511] Lightweight Directory Access Protocol (LDAP): The Protocol.
1195 June 2006. Internet Engineering Task Force.
1196
1197 [RFC4514] Lightweight Directory Access Protocol (LDAP): String
1198 Representation of Distinguished Names. June 2006. Internet Engineering
1199 Task Force.
1200
1201 [RFC4515] Lightweight Directory Access Protocol (LDAP): String
1202 Representation of Search Filters. June 2006. Internet Engineering Task
1203 Force.
1204
1205 [RFC4516] Lightweight Directory Access Protocol (LDAP): Uniform
1206 Resource Locator. June 2006. Internet Engineering Task Force.
1207
1208 [RFC2617] HTTP Authentication: Basic and Digest Access Authentication.
1209 June 1999. Internet Engineering Task Force.
1210
1211 [RFC3261] SIP: Session Initiation Protocol. June 2002. Internet
1212 Engineering Task Force.
1213
1214 [H.350] Directory Services Architecture for Multimedia Conferencing.
1215 August 2003. ITU-T.
1216
1217 [H.350.4] Directory services architecture for SIP. August 2003. ITU-T.