Netscape LDAP Service Provider for JNDI (09-15-99)

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.

The following sections are available in this document:

Using Netscape Ldap Service Provider
Environment Properties
Working With Controls
What's Not Implemented
 

Using Netscape LDAP Service Provider

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 (javax.naming.event package) and support for controls (javax.naming.ldap package) which were introduced with the JNDI 1.2.

To use the service provider, you'll need to:

(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:

set classpath=%classpath%;ldapsp.jar;ldapjdk.jar;jndi.jar;

Assuming that all the jars are available in the current directory. The listed jar files are:
 
ldapsp.jar  Netscape LDAP Service Provider for JNDI
ldapjdk.jar Netscape Directory SDK for Java 4.0
jndi.jar JNDI 1.2

(2) Specify the Netscape LDAP provider as the provider in the context environment created for the initial context;
       Hashtable env = new Hashtable();
   env.put(Context.INITIAL_CONTEXT_FACTORY,
          "com.netscape.jndi.ldap.LdapContextFactory");
    env.put(...
    ...
    DirContext ctx = new InitialDirContext(env);

(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 java-object-schema.conf  to your <server-root>/slapd-<id>/config directory, and include the file into your  <server-root>/slapd-<id>/config/ns-schema.conf schema configuration file. If you are using Netscape Directory Server 4.1, you just need to replace the existing  java-object-schema.conf  file.

For examples of using JNDI please go to the official JNDI site.

Environment Properties

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.

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 LdapContext.reconnect().

The following table contains JNDI environment properties are relevant for the Netscape LDAP service provider. Properties not found in this table are silently ignored.
 
Environment Property Description
java.naming.factory.initial
This environment property is used to select the LDAP provider. To select the Netscape LDAP provider "com.netscape.jndi.ldap.LdapContextFactory" should be specified.

 env.put(Context.INITIAL_CONTEXT_FACTORY, "com.netscape.jndi.ldap.LdapContextFactory");
java.naming.provider.url
Specifies LDAP server information. For example:

env.put(Context.PROVIDER_URL, "ldap://dilly.mcom.com:389");

If it has not been set then the provider will attempt to access an LDAP server at port 389 on the local host.
java.naming.ldap.version
Specifies the protocol version for the provider. Two values are
possible:
  • 2 - selects LDAP Version 2 (LDAPv2)
  • 3 - selects LDAP Version 3 (LDAPv3)
 For example,  env.put("java.naming.ldap.version", "3");

If this environment property has not been set then the provider will
attempt to use LDAPv3.
java.naming.security.authentication
Specifies the authentication mechanism for the provider to use.
The following values are permitted for this property:
  •    none     - use no authentication (anonymous)
  •    simple   - use weak authentication (clear text password)
  • space separated list of sasl mechanisms
If this environment property has not been set but the     java.naming.security.principal environment property has been
set then the provider will use 'simple'. If neither have been set then the provider will use anonymous bind.
java.naming.security.principal
Specifies the DN of the principal to be authenticated. For example:

env.put(Context.SECURITY_PRINCIPAL, "cn=Directory manager");

If this environment property has not been set then the provider
will use anonymous bind.
java.naming.security.credentials
Specifies the password of the principal to be authenticated. For example:

env.put(Context.SECURITY_CREDENTIALS, "secret");
java.naming.security.protocol
 Specifies the security protocol for the provider to use. One possible value is defined:  ssl - use Secure Socket Layer

 env.put(Context.SECURITY_PROTOCOL, "ssl");

When this environment property has been set and the
 java.naming.ldap.factory.socket property has not been set, then the ldapjdk default socket factory  netscape.net.SSLSocket is used. This class is provided with Netscape Communicator 4.05 and higher. If java.naming.ldap.factory.socket property has been set, the
socket factory specified therein is used.
java.naming.security.sasl.authorizationId
Specifies which user DN to use for SASL authentication. 
java.naming.security.sasl.callback
Specifies a callback handler for SASL mechanisms. This value of this property  must be an instance of
 javax.security.auth.callback.CallbackHandler.

  java.naming.security.sasl.client.pkgs
Specifies a "|"-separated list of packages. These packages are used to located factories that produce SASL mechanism drivers. 
java.naming.ldap.factory.socket Specifies the class name of a socket factory. This environment
property is used to override the default socket factory. For example:

env.put("java.naming.ldap.factory.socket", "crysec.SSL.SSLSocket");

If  the security protocol environment property has been set but this property has not been set, then this property's value is set to netscape.net.SSLSocket. See ldapjdk documentation for more information for connecting over SSL.
 
java.naming.ldap.ssl.ciphers Specifies the suite of ciphers used for SSL connections made through sockets created by the factory specified with java.naming.ldap.factory.socket. The value of this property is of type java.lang.Object. For example:

try {
    Class c = Class.forName("crysec.SSL.SSLParams");
    java.lang.reflect.Method m = 
         getMethod("getCipherSuite",new Class[0]);
    Object cipherSuite = m.invoke(null,null);
    if (cipherSuite != null) {
       env.put("java.naming.ldap.ssl.ciphers", cipherSuite);
    }
}
catch (Exception e) {}
 
java.naming.batchsize 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.
java.naming.ldap.maxresults
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 SearchConstraints in the DirContex.search() method.
java.naming.ldap.timelimit 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 SearchConstraints in the DirContex.search() method.
java.naming.referral
 Specifies how referrals shall be handled by the provider. Three  possible values are defined:
  •  follow - automatically follow any referrals
  •  throw  - throw a ReferralException for each referral
  •  ignore - ignore referrals if they appear in results and treat them like ordinary attributes if they appear in entries.
If this environment property has not been set then the LDAP provider by default follows referrals.
java.naming.ldap.referral.limit
Specifies the maximum number of referrals to follow in a chain of
referrals. A setting of zero indicates that there is no limit. The default limit is 10.
java.naming.ldap.deleteRDN  Specifies whether the old RDN is removed during rename().
 If the value is "true", the old RDN is removed; otherwise,
 the RDN is not removed.  The default value is true.
java.naming.ldap.derefAliases
 Specifies how aliases are dereferenced during search operations.
 The possible values are:
  • always        always dereference aliases
  • never         never dereference aliases
  • finding       dereference aliases only during name resolution
  • searching   dereference aliases only after name resolution
 NOTE: Netscape LDAP Server 3.x and 4.x do not support aliases
java.naming.ldap.typesOnly
 Specifies whether only attribute types are to be returned during
 searches and getAttributes(). Its possible values are "true" or "false". The default is false.
java.naming.ldap.conntrol.connect An array of Controls to be set on the LDAPConnection before a connection attempt is made to the server. 
java.naming.ldap.attributes.binary 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.

env.put("java.naming.ldap.attributes.binary", "mpegVideo");

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. 

If this environment property has not been set then, by default, only the following attributes are considered to have binary syntax:

  • attribute names containing ';binary'
  • photo                      (0.9.2342.19200300.100.1.7)
  • personalSignature  (0.9.2342.19200300.100.1.53)
  • audio                      (0.9.2342.19200300.100.1.55)
  • jpegPhoto               (0.9.2342.19200300.100.1.60)
  • javaSerializedData   (1.3.6.1.4.1.42.2.27.4.1.7)
  • thumbnailPhoto         (1.3.6.1.4.1.1466.101.120.35)
  • thumbnailLogo          (1.3.6.1.4.1.1466.101.120.36)
  • userPassword           (2.5.4.35)
  • userCertificate          (2.5.4.36)
  • cACertificate            (2.5.4.37)
  • authorityRevocationList    (2.5.4.38)
  • certificateRevocationList  (2.5.4.39)
  • crossCertificatePair          (2.5.4.40)
  • x500UniqueIdentifier        (2.5.4.45)
java.naming.ldap.ref.separator Specifies the character to use when encoding a RefAddr object in
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.

 If unspecified, the default separator is the hash character '#'.

Working with Controls

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  com.netscape.jndi.ldap.controls package in your souce in addition to the JNDI packages.

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.

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 getInitialDirContext() you 'll need to call getInitialLdapContext().

import java.util.Hashtable;
import javax.naming.*;
import javax.naming.directory.*;
import javax.naming.ldap.*;
import com.netscape.jndi.ldap.controls.*;

public class SortReverseOrder {

public static void main(String[] args) {

    Hashtable env = new Hashtable(5, 0.75f);
    /*
     * Specify the initial context implementation to use.
     */
    env.put(Context.INITIAL_CONTEXT_FACTORY,
        "com.netscape.jndi.ldap.LdapContextFactory");

    /* Specify host and port to use for directory service */
    //env.put(Context.PROVIDER_URL, "ldap://localhost:389");

    LdapContext ctx = null;
    try {
        /* get a handle to an Initial DirContext */
        ctx = new InitialLdapContext(env, null);

        /* specify search constraints to search subtree */
        SearchControls cons = new SearchControls();
        cons.setSearchScope(SearchControls.SUBTREE_SCOPE);
        cons.setReturningAttributes(new String[] { "sn" });

        // specify sort control
        ctx.setRequestControls(
           new Control[] {new LdapSortControl(
              new LdapSortKey[]{
                 new LdapSortKey("sn", true,null)},Control.CRITICAL)});

        /* search for all entries of type person */
        NamingEnumeration results
            = ctx.search("o=mcom.com", "(objectclass=person)", cons);

        /* for each entry print out name + all attrs and values */
        while (results != null && results.hasMore()) {
            SearchResult si = (SearchResult)results.next();

            Attributes attrs = si.getAttributes();
            /* print each attribute */
            for (NamingEnumeration ae = attrs.getAll(); ae.hasMoreElements();) {
                Attribute attr = (Attribute)ae.next();
                String attrId = attr.getID();

                    /* print each value */
                for (NamingEnumeration vals = attr.getAll(); vals.hasMore();
                    System.out.println(attrId + ": " + vals.next()));
                }
            System.out.println();
        }
    }
    catch (NamingException e) {
        System.err.println("Search example failed.");
        e.printStackTrace();
    }
    finally {
       // cleanup
       if (ctx != null) {
           try { ctx.close(); } catch (Exception e) {}
       }
    }
}
}

For full documenation on available controls and their interfaces, please check the ldapjdk documentation.

What's Not Implemented

Currently, the following JNDI features are not implemented by the Netscape JNDI provider: