1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<!- $Id: Protocols.LDAP-doc.html,v 1.2 1999/03/29 12:44:34 hop Exp $ ->
<HTML>
<HEAD>
<TITLE>LDAP Pike objects</TITLE>
</HEAD>
<BODY bgcolor="#ffffff" link="#ff0000" vlink="#000099" alink="#009900" text="#000000">
<H1 align=center>LDAP Pike objects</H1>
<P><BR>
This document discusses the following topics:
<UL>
<LI> <A href="#description">Description</A>
<LI> <A href="#connection">Initial connection</A>
<LI> <A href="#binding">Binding</A>
<LI> <A href="#delop">Delete operation</A>
<LI> <A href="#compop">Compare operation</A>
<LI> <A href="#searchop">Search operation</A>
<LI> <A href="#addop">Add operation</A>
<LI> Modify operation
<LI> <A href="#error">Error values</A>
<LI> <A href="#options">Session options</A>
<LI> <A href="#results">Obtaining results</A>
</UL>
<P><RIGHT><FONT size=-2>
© <A href="mailto:hop@unibase.cz">Honza Petrous</A>, v1.3
</FONT></RIGHT>
<HR>
<P><BR>
<A name="description"></A>
<TABLE align=center width="100%">
<TR>
<td bgcolor=#ffdead align=center><H3>Description</H3></td>
</TR>
</TABLE>
<P>
<TABLE width="100%">
<TR>
<TD width=50></td>
<TD > This module allows Pike programmers to access and manipulate
an LDAP based Directory. Module enables two new objects
<I>Protocols.LDAP.client</I> and <I>Protocols.LDAP.client.result</I>
for using it in LDAP-related calculatings.
<P>
Current version 1.5 supports the main subset of client operations
version 2 LDAP protocol with one exception in search filter -
parser don't understand escaped characters. This will be corrected
in the next version.
<P>
<P><BR></TD>
</TR>
</TABLE>
<A name="connection"></A>
<TABLE align=center width="100%">
<TR>
<td bgcolor=#ffdead align=center><H3>Initial conection</H3></td>
</TR>
</TABLE>
<P>
<TABLE width="100%">
<TR>
<TD width=50></td>
<TD > All connection to the LDAP server are started by creating a new
object in the <I>Protocols.LDAP.client</I> class. This can be done
quite easily by the following type of statement:
<PRE>
> object ld = Protocols.LDAP.client("ldap.company.com");
</PRE>
Where argument is the name of your LDAP server. If you are not
using the standard LDAP port (389), you will also need to suply
the portnumber:
<PRE>
> object ld = Protocols.LDAP.client("ldap.company.com:9999");
</PRE>
<P><BR></TD>
</TR>
</TABLE>
<A name="binding"></A>
<TABLE align=center width="100%">
<TR>
<td bgcolor=#ffdead align=center><H3>Binding</H3></td>
</TR>
</TABLE>
<P>
<TABLE width="100%">
<TR>
<TD width=50></td>
<TD > After creating a connection to the LDAP server, you will always
need to bind to the server<SUP>(1)</SUP> prior to performing any
LDAP related operations. This can be done with the <B>bind</B>
method.
<P>As anonymous bind can be performed without arguments:
<PRE>
> int status = ld->bind();
</PRE>
A simple bind can be performed by specifying the distingished name (DN)
and password of the user you are authenticating as:
<PRE>
> status = ld->bind("cn=Directory Admin, o=UniBASE Ltd., c=CZ", "password");
</PRE>
Note that if "password" above was "", you would be doing a reference
bind, which would return success even if the password in the directory
was not empty. Thus if you were using the bind to check a password
entered with one in the directory, you should first check to see if
password was null.
<BLOCKQUOTE>
<P><B>SECURITY ALERT:</B>
Current version supported only simple bind operation with clear text
password.
</BLOCKQUOTE>
<SUP>(1)</SUP> - This is true for version 2 LDAP protocol.
<P></TR>
</TABLE>
<A name="delop"></A>
<TABLE align=center width="100%">
<TR>
<td bgcolor=#ffdead align=center><H3>Delete operation</H2></TD>
</TR>
</TABLE>
<P>
<TABLE width="100%">
<TR>
<TD width=50></td>
<TD > The <B>delete</B> operation is used to delete DN.
<PRE>
> status = ld->delete("cn=Honza Petrous, o=UniBASE Ltd., c=CZ");
</PRE>
<P><BR></TD>
</TR>
</TABLE>
<A name="compop"></A>
<TABLE align=center width="100%">
<TR>
<td bgcolor=#ffdead align=center><H3>Compare operation<H3></td>
</TR>
</TABLE>
<P>
<TABLE width="100%">
<TR>
<TD width=50></td>
<TD > The <B>compare</B> operation is used to compare single attribute
value for DN.
<PRE>
> status = ld->compare("cn=Honza Petrous, o=UniBASE Ltd., c=CZ",
({"mail", "hop@unibase.cz"}));
</PRE>
Status value returned by this method is LDAP_COMPARE_TRUE (5) or
LDAP_COMPARE_FALSE (6).
<P><BR></TD>
</TR>
</TABLE>
<A name="searchop"></A>
<TABLE align=center width="100%">
<TR>
<td bgcolor=#ffdead align=center><H3>Search operation</H3></td>
</TR>
</TABLE>
<P>
<TABLE width="100%">
<TR>
<TD width=50></td>
<TD > The <B>search</B> operation is used for retrieving attribute
and its values for entries specified in search filter.
<PRE>
> object rv = ld->search("(|(objectclass=person)(mail))");
</PRE>
Statesment above performs LDAP search. Returns an object, if operations
ended successfully otherwise negative integer value. Argument is
a string containing an LDAP search filter.
<BR>You can restrict attributes returned by search:
<PRE>
> rv = ld->search("(|(objectclass=person)(mail))",
({"mail", "telephonenumber", "sn"}));
</PRE>
Second argument is array of attribute names you need.
<BR>You also can restrict returned attributes name only:
<PRE>
> rv = ld->search("(|(objectclass=person)(mail))",
({"mail", "telephonenumber", "sn"}), 1);
</PRE>
Third argument can be '1' if you can returned attributes name only.
<P><BR></TD>
</TR>
</TABLE>
<A name="addop"></A>
<TABLE align=center width="100%">
<TR>
<td bgcolor=#ffdead align=center><H3>Add operation</H3></td>
</TR>
</TABLE>
<P>
<TABLE width="100%">
<TR>
<TD width=50></td>
<TD > The <B>add</B> operation is used to insert new entry to the
LDAP server.
<PRE>
> status = ld->add("cn=Akos Varga, o=UniBASE Ltd., c=CZ",
(["objectclass":({"top", "person"}),
"mail":({"Akos.Varga@unibase.cz"})]);
</PRE>
First argument is DN of new entry. Second argument is an attribute
values of entry. This is mapping(string:array(string)) object.
<P>Note that in most cases, you will need to be bound to the LDAP
server as an administrator in order to add entries.
<P><BR></TD>
</TR>
</TABLE>
<A name="error"></A>
<TABLE align=center width="100%">
<TR>
<td bgcolor=#ffdead align=center><H3>Error values</H3></td>
</TR>
</TABLE>
<P>
<TABLE width="100%">
<TR>
<TD width=50></td>
<TD > Most methods returns integer value as status of operation.
There are three groups of values:
<OL>
<LI> <I>greater or equal to 0</I>
<BR> This values are regular LDAP code errors. You can access
error code and its aproppriate string representations
anytime you want by the following methods:
<PRE>
> status = ld->error_code();
> string strstat = ld->error_string();
</PRE>
<LI> <I>less then 0</I>
<BR> This codes are returned on internal error.
</OL>
<P></TR>
</TABLE>
<A name="options"></A>
<TABLE align=center width="100%">
<TR>
<td bgcolor=#ffdead align=center><H3>Session options</H3></td>
</TR>
</TABLE>
<P>
<TABLE width="100%">
<TR>
<TD width=50></td>
<TD> The methods <B>get_option</B> and <B>set_option</B> can be used
to get and set LDAP session options.
<P>The following LDAP options can be set or gotten whith these methods:
<PRE>
LDAP_OPT_DEREF (1) - Dereference
LDAP_OPT_SIZELIMIT (2) - Maximum number of entries to return
LDAP_OPT_TIMELIMIT (3) - Timeout for LDAP operations
LDAP_OPT_REFERRALS (4) - Follow referrals <B>(unimplemented)</B>
</PRE>
For both get and set operations, the first argument is the relevant
option. In set, the second argument is the value at which to set
this option.
Examples:
<PRE>
> status = ld->set_option(LDAP_OPT_SIZELIMIT, 20);
> int size = ld->get_option(LDAP_OPT_SIZELIMIT);
</PRE>
<P><BR></TD>
</TR>
</TABLE>
<A name="results"></A>
<TABLE align=center width="100%">
<TR>
<td bgcolor=#ffdead align=center><H3>Obtaining results</H3></td>
</TR>
</TABLE>
<P>
<TABLE width="100%">
<TR>
<TD width=50></td>
<TD > Search operation returns object of type <I>Protocols.LDAP.client.result</I>
if successful. This object contains all LDAP messages returned from
LDAP server (i.e. entries and result). All entries in object are
linked to the chain. You can access entries sequencelly or directly.
<P>Example:
<P>Walking through all entries sequencelly:
<PRE>
object rv = search("(objectclass=person)");
do {
print(sprintf("%d. %s <%s>\n", rv->num_entries() - rv->count_entries(),
rv->fetch()["dn"][0],
rv->fetch()["mail"][0]));
} while (rv->next());
</PRE>
The same but with direct access:
<PRE>
object rv = search("(objectclass=person)");
for(int ix=1; ix<rv->num_entries(); ix++) {
print(sprintf("%d. %s <%s>\n", ix,
rv->fetch(ix)["dn"][0],
rv->fetch(ix)["mail"][0]));
}
</PRE>
As you can see, method <B>fetch</B> is used for getting entry.
This method returns mapping(string:array(string)) for entry.
<P><BR></TD>
</TR>
</TABLE>
</BODY>
</HTML>
|
