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
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Miodrag Kekic">
<meta name="GENERATOR" content="Mozilla/4.61 [en] (WinNT; U) [Netscape]">
<title>Netscape LDAP Service Provider - Readme</title>
</head>
<body>
<h2>
Netscape LDAP Service Provider for JNDI (09-15-99)</h2>
The Netscape LDAP service provider for JNDI implements the JNDI DirContext
interface. It is implemented as a layer on top of the Netscape Directory
SDK for Java (ldapjdk.jar). While the ldapjdk uses the LDAP connection
as the primary abstraction enabling the access to the directory services,
the JNDI provider uses the concept of a Directory Context (the
DirContext interface) to achieve the same functionality. A DirContext as
an equivalent of a directory entry in the ldapjdk.
<p>The following sections are available in this document:
<p><a href="#Using">Using Netscape Ldap Service Provider</a>
<br><a href="#Env Props">Environment Properties</a>
<br><a href="#Controls">Working With Controls</a>
<br><a href="#Not Impl">What's Not Implemented</a>
<br>
<h3>
<a NAME="Using"></a>Using Netscape LDAP Service Provider</h3>
The current implementation is based on the JNDI 1.2 FCS. In addition
to the DirContext interface implementation, the Netscape LDAP provider
implements the new JNDI event service (<i>javax.naming.event</i> package)
and support for controls (<i>javax.naming.ldap</i> package) which were
introduced with the JNDI 1.2.
<p>To use the service provider, you'll need to:
<p>(1) Add the provider and the jars it depends on in the classpath. For
example, on Windows NT the classpath should be set as follows:
<p><tt>set classpath=%classpath%;ldapsp.jar;ldapjdk.jar;jndi.jar;</tt>
<p>Assuming that all the jars are available in the current directory. The
listed jar files are:
<br>
<table CELLSPACING=0 COLS=2 WIDTH="477" >
<tr>
<td WIDTH="100">ldapsp.jar </td>
<td WIDTH="400">Netscape LDAP Service Provider for JNDI</td>
</tr>
<tr>
<td>ldapjdk.jar</td>
<td>Netscape Directory SDK for Java 4.0</td>
</tr>
<tr>
<td>jndi.jar</td>
<td>JNDI 1.2</td>
</tr>
</table>
<p>(2) Specify the Netscape LDAP provider as the provider in the context
environment created for the initial context;
<br> <tt>Hashtable env = new Hashtable();</tt>
<br><tt> env.put(Context.INITIAL_CONTEXT_FACTORY,</tt>
<br><tt> "com.netscape.jndi.ldap.LdapContextFactory");</tt>
<br><tt> env.put(...</tt>
<br><tt> ...</tt>
<br><tt> DirContext ctx = new InitialDirContext(env);</tt>
<p>(3) For storing of Java objects in a LDAP Directory, the JNDI
java object schema must be added to the directory. To enable the JNDI schema
copy the file <i>java-object-schema.conf</i> to your <i><server-root>/slapd-<id>/config</i>
directory, and include the file into your <i><server-root>/slapd-<id>/config/ns-schema.conf</i>
schema configuration file. If you are using Netscape Directory Server 4.1,
you just need to replace the existing <i>java-object-schema.conf</i>
file.
<p>For examples of using JNDI please go to the official JNDI site.
<h3>
<a NAME="Env Props"></a>Environment Properties</h3>
The environment properties can be passed directly to the initial context
as a hash table, or specified as system properties. For compatibility reasons,
for those environment properties that are relevant to LDAP protocol but
are not defined in the JNDI, the Netscape LDAP provider is using the same
property names as the SUN LDAP service provided, if a property with the
same semantics is defined by the SUN provider.
<p>Note: If a new property is added to the context environment, or an existing
property is changed after the initial context is created, the change will
be immediately visible unless the changed property pertains to the connection.
For changes related to connection, in order to take effect you'll need
to invoke <i>LdapContext.reconnect().</i>
<p>The following table contains JNDI environment properties are relevant
for the Netscape LDAP service provider. Properties not found in this table
are silently ignored.
<br>
<table BORDER CELLSPACING=0 COLS=2 WIDTH="100%" >
<tr>
<th WIDTH="20%" BGCOLOR="#000000"><font color="#FFFFFF">Environment Property</font></th>
<th BGCOLOR="#000000"><font color="#FFFFFF">Description</font></th>
</tr>
<tr>
<td>java.naming.factory.initial</td>
<td>
<br>This environment property is used to select the LDAP provider. To select
the Netscape LDAP provider "<b>com.netscape.jndi.ldap.LdapContextFactory</b>"
should be specified.
<p><tt> env.put(Context.INITIAL_CONTEXT_FACTORY, "com.netscape.jndi.ldap.LdapContextFactory");</tt></td>
</tr>
<tr>
<td>java.naming.provider.url</td>
<td>
<br>Specifies LDAP server information. For example:
<p><tt>env.put(Context.PROVIDER_URL, "ldap://dilly.mcom.com:389");</tt>
<p>If it has not been set then the provider will attempt to access an LDAP
server at port 389 on the local host.</td>
</tr>
<tr>
<td>java.naming.ldap.version</td>
<td>
<br>Specifies the protocol version for the provider. Two values are
<br>possible:
<ul>
<li>
2 - selects LDAP Version 2 (LDAPv2)</li>
<li>
3 - selects LDAP Version 3 (LDAPv3)</li>
</ul>
For example, <tt>env.put("java.naming.ldap.version", "3");</tt>
<p>If this environment property has not been set then the provider will
<br>attempt to use LDAPv3.</td>
</tr>
<tr>
<td>java.naming.security.authentication</td>
<td>
<br>Specifies the authentication mechanism for the provider to use.
<br>The following values are permitted for this property:
<ul>
<li>
<b>none</b> - use no authentication
(anonymous)</li>
<li>
<b>simple</b> - use weak authentication (clear
text password)</li>
<li>
<i>space separated list of sasl mechanisms</i></li>
</ul>
If this environment property has not been set but the
java.naming.security.principal environment property has been
<br>set then the provider will use 'simple'. If neither have been set then
the provider will use anonymous bind.</td>
</tr>
<tr>
<td WIDTH="20%">java.naming.security.principal</td>
<td>
<br>Specifies the DN of the principal to be authenticated. For example:
<p><tt>env.put(Context.SECURITY_PRINCIPAL, "cn=Directory manager");</tt>
<p>If this environment property has not been set then the provider
<br>will use anonymous bind.</td>
</tr>
<tr>
<td>java.naming.security.credentials</td>
<td>
<br>Specifies the password of the principal to be authenticated. For example:
<p><tt>env.put(Context.SECURITY_CREDENTIALS, "secret");</tt></td>
</tr>
<tr>
<td>java.naming.security.protocol</td>
<td>
<br> Specifies the security protocol for the provider to use. One
possible value is defined: <b>ssl</b> - use Secure Socket Layer
<p><tt> env.put(Context.SECURITY_PROTOCOL, "ssl");</tt>
<p>When this environment property has been set and the
<br> <i>java.naming.ldap.factory.socket</i> property has not been
set, then the ldapjdk default socket factory <i>netscape.net.SSLSocket</i>
is used. This class is provided with Netscape Communicator 4.05 and higher.
If <i>java.naming.ldap.factory.socket</i> property has been set, the
<br>socket factory specified therein is used.</td>
</tr>
<tr>
<td>java.naming.security.sasl.authorizationId</td>
<td>
<br>Specifies which user DN to use for SASL authentication. </td>
</tr>
<tr>
<td>java.naming.security.sasl.callback</td>
<td>
<br>Specifies a callback handler for SASL mechanisms. This value of this
property must be an instance of
<br> <i>javax.security.auth.callback.CallbackHandler</i>.</td>
</tr>
<tr>
<td>
<br> java.naming.security.sasl.client.pkgs</td>
<td>
<br>Specifies a "|"-separated list of packages. These packages are used
to located factories that produce SASL mechanism drivers. </td>
</tr>
<tr>
<td>java.naming.ldap.factory.socket</td>
<td>Specifies the class name of a socket factory. This environment
<br>property is used to override the default socket factory. For example:
<p><tt>env.put("java.naming.ldap.factory.socket", "crysec.SSL.SSLSocket");</tt>
<p>If the security protocol environment property has been set but
this property has not been set, then this property's value is set to <i>netscape.net.SSLSocket</i>.
See ldapjdk documentation for more information for connecting over SSL.
<br> </td>
</tr>
<tr>
<td>java.naming.ldap.ssl.ciphers</td>
<td>Specifies the suite of ciphers used for SSL connections made through
sockets created by the factory specified with <i>java.naming.ldap.factory.socket</i>.
The value of this property is of type <i>java.lang.Object</i>. For example:
<p><tt><font size=-1>try {</font></tt>
<br><tt><font size=-1> Class c = Class.forName("crysec.SSL.SSLParams");</font></tt>
<br><tt><font size=-1> java.lang.reflect.Method m = </font></tt>
<br><tt><font size=-1>
getMethod("getCipherSuite",new Class[0]);</font></tt>
<br><tt><font size=-1> Object cipherSuite = m.invoke(null,null);</font></tt>
<br><tt><font size=-1> if (cipherSuite != null) {</font></tt>
<br><tt><font size=-1> env.put("java.naming.ldap.ssl.ciphers",
cipherSuite);</font></tt>
<br><tt><font size=-1> }</font></tt>
<br><tt><font size=-1>}</font></tt>
<br><tt><font size=-1>catch (Exception e) {}</font></tt>
<br> </td>
</tr>
<tr>
<td>java.naming.batchsize</td>
<td>Specifies that search results are to be returned in batches. A setting
of zero indicates that the provider should block until all results have
been received. If this environment property has not been set then search
results are returned in batches of one.</td>
</tr>
<tr>
<td>java.naming.ldap.maxresults</td>
<td>
<br>The default maximum number of search results to be returned for
a search request. 0 means no limit. If not specified, the ldapjdk default
is 1000. This value can be overridden per request with the parameter <i>SearchConstraints</i>
in the <i>DirContex.search()</i> method.</td>
</tr>
<tr>
<td>java.naming.ldap.timelimit</td>
<td>The default maximum number of milliseconds to wait for a search operation
to complete. If 0, which is the ldapjdk default, there is no maximum time
limit for a search operation. This value can be overridden per request
with the parameter <i>SearchConstraints</i> in the <i>DirContex.search()</i>
method.</td>
</tr>
<tr>
<td>java.naming.referral</td>
<td>
<br> Specifies how referrals shall be handled by the provider. Three
possible values are defined:
<ul>
<li>
<b> follow</b> - automatically follow any referrals</li>
<li>
<b>throw</b> - throw a ReferralException for each referral</li>
<li>
<b>ignore</b> - ignore referrals if they appear in results and treat
them like ordinary attributes if they appear in entries.</li>
</ul>
If this environment property has not been set then the LDAP provider by
default follows referrals.</td>
</tr>
<tr>
<td>java.naming.ldap.referral.limit</td>
<td>
<br>Specifies the maximum number of referrals to follow in a chain of
<br>referrals. A setting of zero indicates that there is no limit. The
default limit is 10.</td>
</tr>
<tr>
<td>java.naming.ldap.deleteRDN</td>
<td> Specifies whether the old RDN is removed during rename().
<br> If the value is "true", the old RDN is removed; otherwise,
<br> the RDN is not removed. The default value is true.</td>
</tr>
<tr>
<td>java.naming.ldap.derefAliases</td>
<td>
<br> Specifies how aliases are dereferenced during search operations.
<br> The possible values are:
<ul>
<li>
<b>always</b> always dereference
aliases</li>
<li>
<b>never</b> never dereference
aliases</li>
<li>
<b>finding</b> dereference aliases
only during name resolution</li>
<li>
<b>searching</b> dereference aliases only after name resolution</li>
</ul>
NOTE: Netscape LDAP Server 3.x and 4.x do not support aliases</td>
</tr>
<tr>
<td>java.naming.ldap.typesOnly</td>
<td>
<br> Specifies whether only attribute types are to be returned during
<br> searches and getAttributes(). Its possible values are "true"
or "false". The default is false.</td>
</tr>
<tr>
<td>java.naming.ldap.conntrol.connect</td>
<td>An array of <i>Control</i>s to be set on the LDAPConnection before
a connection attempt is made to the server. </td>
</tr>
<tr>
<td>java.naming.ldap.attributes.binary</td>
<td>Specifies attributes that have binary syntax. It extends the provider's
list of known binary attributes. Its value is a space separated list of
attribute names.
<p><tt>env.put("java.naming.ldap.attributes.binary", "mpegVideo");</tt>
<p>In contrast to ldapjdk, JNDI does not provide for reading of attribute
values as either Strings or byte arrays. All attributes are returned as
Strings unless recognized as having binary syntax. The values of attributes
that have binary syntax are returned as byte arrays instead of Strings.
<p>If this environment property has not been set then, by default, only
the following attributes are considered to have binary syntax:
<ul>
<li>
attribute names containing '<b>;binary'</b></li>
<li>
photo
(0.9.2342.19200300.100.1.7)</li>
<li>
personalSignature (0.9.2342.19200300.100.1.53)</li>
<li>
audio
(0.9.2342.19200300.100.1.55)</li>
<li>
jpegPhoto
(0.9.2342.19200300.100.1.60)</li>
<li>
javaSerializedData (1.3.6.1.4.1.42.2.27.4.1.7)</li>
<li>
thumbnailPhoto (1.3.6.1.4.1.1466.101.120.35)</li>
<li>
thumbnailLogo (1.3.6.1.4.1.1466.101.120.36)</li>
<li>
userPassword
(2.5.4.35)</li>
<li>
userCertificate (2.5.4.36)</li>
<li>
cACertificate
(2.5.4.37)</li>
<li>
authorityRevocationList (2.5.4.38)</li>
<li>
certificateRevocationList (2.5.4.39)</li>
<li>
crossCertificatePair
(2.5.4.40)</li>
<li>
x500UniqueIdentifier (2.5.4.45)</li>
</ul>
</td>
</tr>
<tr>
<td>java.naming.ldap.ref.separator</td>
<td>Specifies the character to use when encoding a RefAddr object in
<br>the javaReferenceAddress attribute. This environment property should
be used to avoid a conflict in the case where the default separator
character appears in the components of a RefAddr object.
<p> If unspecified, the default separator is the hash character '#'.</td>
</tr>
</table>
<h3>
<a NAME="Controls"></a>Working with Controls</h3>
JNDI 1.2 adds support for Controls which are fully implemented with the
Netscape LDAP provider. However, JNDI 1.2 does not define interfaces for
any of the standard controls, like for example the sort control. Instead,
the task of defining particular controls and their interfaces is left to
service providers. Therefore, if using controls, you will also need to
import the <i>com.netscape.jndi.ldap.controls</i> package in your
souce in addition to the JNDI packages.
<p>Being implemented on the top of ldapjdk, the Netscape LDAP provider
simply exposes all of the ldapjdk controls as JNDI controls. Thus, the
control APIs are exactly the same as in ldapjdk. The only difference is
that for the LDAP provider controls class names start with "Ldap"
while in ldapjdk the class names start with "LDAP". For instance, the ldapjdk
control LDAPSortControl is LdapSortControl in the Netscape LDAP provider.
<p>Here is an example of how to use the LdapSortControl. Notice that you'll
need to obtain a LdapContext object as an initial context, because controls
are not part of the directory context (DirContext). That means that instead
of calling <i>getInitialDirContext()</i> you 'll need to call <i>getInitialLdapContext()</i>.
<p><tt>import java.util.Hashtable;</tt>
<br><tt>import javax.naming.*;</tt>
<br><tt>import javax.naming.directory.*;</tt>
<br><b><tt>import javax.naming.ldap.*;</tt></b>
<br><b><tt>import com.netscape.jndi.ldap.controls.*;</tt></b>
<p><tt>public class SortReverseOrder {</tt>
<p><tt>public static void main(String[] args) {</tt>
<p><tt> Hashtable env = new Hashtable(5, 0.75f);</tt>
<br><tt> /*</tt>
<br><tt> * Specify the initial context implementation
to use.</tt>
<br><tt> */</tt>
<br><tt> env.put(Context.INITIAL_CONTEXT_FACTORY,</tt>
<br><tt> "com.netscape.jndi.ldap.LdapContextFactory");</tt>
<p><tt> /* Specify host and port to use for directory
service */</tt>
<br><tt> //env.put(Context.PROVIDER_URL, "ldap://localhost:389");</tt>
<p><tt> LdapContext ctx = null;</tt>
<br><tt> try {</tt>
<br><tt> /* get a handle to an
Initial DirContext */</tt>
<br><tt> <b>ctx = new InitialLdapContext(env,
null);</b></tt>
<p><tt> /* specify search constraints
to search subtree */</tt>
<br><tt> SearchControls cons
= new SearchControls();</tt>
<br><tt> cons.setSearchScope(SearchControls.SUBTREE_SCOPE);</tt>
<br><tt> cons.setReturningAttributes(new
String[] { "sn" });</tt>
<p><tt> // specify sort control</tt>
<br><tt> <b>ctx.setRequestControls(</b></tt>
<br><tt> <b>new
Control[] {new LdapSortControl(</b></tt>
<br><tt>
<b>new LdapSortKey[]{</b></tt>
<br><tt>
<b>new LdapSortKey("sn", true,null)},Control.CRITICAL)});</b></tt>
<p><tt> /* search for all entries
of type person */</tt>
<br><tt> NamingEnumeration results</tt>
<br><tt>
= ctx.search("o=mcom.com", "(objectclass=person)", cons);</tt>
<p><tt> /* for each entry print
out name + all attrs and values */</tt>
<br><tt> while (results != null
&& results.hasMore()) {</tt>
<br><tt>
SearchResult si = (SearchResult)results.next();</tt>
<p><tt>
Attributes attrs = si.getAttributes();</tt>
<br><tt>
/* print each attribute */</tt>
<br><tt>
for (NamingEnumeration ae = attrs.getAll(); ae.hasMoreElements();) {</tt>
<br><tt>
Attribute attr = (Attribute)ae.next();</tt>
<br><tt>
String attrId = attr.getID();</tt>
<p><tt>
/* print each value */</tt>
<br><tt>
for (NamingEnumeration vals = attr.getAll(); vals.hasMore();</tt>
<br><tt>
System.out.println(attrId + ": " + vals.next()));</tt>
<br><tt>
}</tt>
<br><tt>
System.out.println();</tt>
<br><tt> }</tt>
<br><tt> }</tt>
<br><tt> catch (NamingException e) {</tt>
<br><tt> System.err.println("Search
example failed.");</tt>
<br><tt> e.printStackTrace();</tt>
<br><tt> }</tt>
<br><tt> finally {</tt>
<br><tt> // cleanup</tt>
<br><tt> if (ctx != null) {</tt>
<br><tt> try
{ ctx.close(); } catch (Exception e) {}</tt>
<br><tt> }</tt>
<br><tt> }</tt>
<br><tt>}</tt>
<br><tt>}</tt>
<p>For full documenation on available controls and their interfaces, please
check the ldapjdk documentation.
<h3>
<a NAME="Not Impl"></a>What's Not Implemented</h3>
Currently, the following JNDI features are not implemented by the Netscape
JNDI provider:
<ul>
<li>
Support for federated names</li>
<li>
Support for the code base attribute for objects stored in LDAP directory.
Therefore, the class name specified with the <i>javaClassName</i> attribute
must be available in the local <i>CLASSPATH</i>.</li>
<li>
<i>search()</i> method for schema directory contexts. Instead, <i>Context.lookup()</i>
should be used..</li>
</ul>
</body>
</html>
|
