LDAP Browser/Editor FAQ

### Frequently Asked Questions
LDAP Browser/Editor

Question Index

General Questions

1. What is the lbe.properties file?
2. What properties can be specified in the lbe.properties file?
3. I'm getting a "NoClassFound" error trying to run the Browser. What's wrong?
4. How do I enable debugging for the Browser?
5. How do I run the Browser behind a proxy?
6. How do I modify the 'be' scripts to add the different system properties?
7. How do I run the Browser with a different Java environment?
8. What parameters can I pass to the application?

Applet Questions

1. How do I run the Browser as an applet?
2. What parameters can I pass to the applet?
3. How do I debug the Browser as an applet?

SSL Questions

1. How do I enable the SSL support in the Browser?
2. Why does initial SSL connection take a while to establish?
3. How do I turn on debugging for the SSL connection?
4. How do I specify client certificates for the SSL connection?
5. How do I fix the 'CA certificate not found' error?
6. Why does SSL connection sometimes hang the browser?

Attribute Viewers/Editors Questions

1. What are attribute viewers/editors?
2. What attribute viewers/editors are distributed with the Browser?
3. How do I set default algorithm for the Password Editor?
4. What is the ExtBinaryEditor and how can I use it?
5. What is the ExtStringViewer and how can I use it?
6. How can I configure the CertificateEditor2 to launch an external application to view the certificate?
7. How do I write a custom attribute viewer/editor?

General Questions

What is the lbe.properties file?

The lbe.properties file is a small configuration file that contains generic configuration information applicable to the Browser and any ldap session. For example, it specifies the location of the CA certificates store and its password, the location of the ldap session files, etc. The Browser during initialization will try to load this file from the '.be' directory under user's home directory. Examples:

on Unix/Linux:

    ~gawor/.lbe/lbe.properties

on Windows NT:

    c:\winnt\profiles\gawor\.lbe\lbe.properties

If the file does not exist or cannot be read, the defaults will be assumed.

The settings defined in lbe.properties file are meant to replace some of the settings previously defined in the .cf. files that were considered static and did not change throughout the different ldap sessions. Previously, the Browser obtained these properties by loading the browser.cfg file automatically. Currently, the Browser, will only load the browser.cfg file when the lbe.properties file does not exist in the user's home directory (for backwards compatibility) If the lbe.properties file does exist in the user's home directory, the Browser will not load the browser.cfg file.

What properties can be specified in the lbe.properties file?

- cacert.file

- specifies the location of the CA certificates store file. The location can be specified as an URL. If the file contains .p12 extension it will be interpreted as PKCS12 encoded file.

- cacert.pwd

- specifies the password for the CA certificates store.

- session.dir

- Specifies the local directory where the session files will be loaded from.

- base

- It sets the base location of the Browser where the templates, the help files, and the session files will be resolved from. The location can be specified as either directory or URL.

- autoloader

- specifies the name of the session file to automatically load when the Browser is started. The session file must have the 'auto connect' property set to 'yes' if the Browser should automatically connect to that server. The location of the session is resolved from the base location.

I'm getting a "NoClassFound" error trying to run the Browser. What's wrong?

This error occurs when the Browser is installed incorrectly or launched from an invalid directory. The LDAP Browser/Editor must be executed from the directory that it was installed in. The Browser must be able to locate appropriate libraries required for its operation. The libraries must be accessible and located in the lib directory of the Browser's installation directory.

How do I enable debugging for the LDAP Browser/Editor?

LDAP Browser/Editor provides dynamic debug tracing support. It is enabled by setting the lbe.debug system property. The value can be one or more of the following:

- editor

- print attribute viewers/editors debug messages

- ldap

- enable LDAP protocol message tracing

- level1

- print generic browser debug messages

- level2

- print more and more detailed debug messages

- ssl

- enable debugging for the built-in secure socket factory

- all

- enable all debugging

Example: (using the command-line option on the java command)

    java -Dlbe.debug=ldap:editor -classpath ... lbe.ui.BrowserApp

This will enable ldap tracing and debugging of the attribute viewers/editors.

For details on how to modify the 'be' scripts to enable this property see the question about this.

How do I run the Browser behind a proxy?

The LDAP Browser/Editor does not provide any special support for proxies. However, Java itself provides SOCKS 4 support.
To configure the Browser to use the proxy server add the following properties to the command line to the Java interpreter:

    -DsocksProxyPort=1080 -DsocksProxyHost=socks.mydomain.com

For example:

    java -DsocksProxyPort=1080 -DsocksProxyHost=socks.mydomain.com -classpath .....  lbe.ui.BrowserApp

For details on how to modify the 'be' scripts to enable this property see the following question.

How do I modify the 'be' scripts to add the different system properties?

On Windows:

1. Edit the lbe.bat file
2. For version 2.8.2 and greater modify the following line:

    set OPTIONS=

with the system properties, for example:

    set OPTIONS=-Dlbe.debug=ldap -DsocksProxyHost=myserver.com

For version 2.8.1 modify the following line:

    set CMD="%JAVA_HOME%\bin\java" -cp %COMMON%;%EXEC%

with the system properties, for example:

    set CMD="%JAVA_HOME%\bin\java" -Dlbe.debug=ldap -DsocksProxyHost=myserver.com -cp %COMMON%;%EXEC%

On Unix:

1. Edit the lbe.sh file
2. For version 2.8.2 and greater modify the following line:

    OPTIONS=

with the system properties, for example:

    OPTIONS="-Dlbe.debug=ldap -DsocksProxyHost=myserver.com"

For version 2.8.1 modify the following line:

    CMD="${JAVA_HOME}/bin/java -cp ${COMMON}:${EXEC}"

with the system properties, for example:

    CMD="${JAVA_HOME}/bin/java -Dlbe.debug=ldap -DsocksProxyHost=myserver.com -cp ${COMMON}:${EXEC}"

How do I run the Browser with a different Java environment?

By default the Browser will first try use the Java interpreter specified by the JAVA_HOME environment variable. If the environment variable is not set, the Browser will then try to use the Java interpreter specified in your path. You can run the browser with a different Java environment by setting the JAVA_HOME environment variable from the command line before starting the Browser. For example, to set the JAVA_HOME variable do the following:

> On Windows:

    C:\ldapbrowser>set JAVA_HOME=c:\jdk1.3

On Unix/Linux: (using tcsh)

    pitcairn: ~/ldapbrowser>setenv JAVA_HOME /sandbox/jdk1.3

Optionally, you can modify the appropriate 'be' script for your platform to set the JAVA_HOME variable. For example:

> On Windows:

1. Edit the lbe.bat file and modify (or add at the beginning) the following line:

    set JAVA_HOME=c:\jdk1.3

On Unix/Linux:

1. Edit the lbe.sh file and modify (or add at the beginning) the following line:

    JAVA_HOME=/sandbox/jdk1.3

What parameters can I pass to the Browser application?

There are two parameters that can be passes to the Browser application from the command line.

- base

- It sets the base location of the Browser where the templates, the help files, and the session files will be resolved from. The location can be specified as either directory or URL. By default, the application looks for these files in the current directory. (example: -base c:\ldapbrowser)

- config

- 2.8.2: Specifies the path of the LBE configuration file (lbe.properties) to load. By default, the Browser will try to load the configuration file from the '.be' directory under user's home directory. See What is lbe.properties file? question for details.
- 2.8.1: Specifies the name of the configuration file to load. It is resolved from the base location. If not set, the application will try to load the default configuration file called browser.cfg. (example: -config nds.cfg)

Applet Questions

How do I run the Browser as an applet?

The LDAP Browser/Editor can be run as an applet within a web browser (Netscape Navigator or Microsoft Internet Explorer) using the Java Plug-in. The Browser can be run either as a signed or unsigned applet. If the Browser is running as an unsigned applet it can only access the ldap servers on the server that the applet was downloaded from. If the Browser is running as a trusted signed applet it can access any ldap server on the network or the internet.
The HTML page that will contain the applet needs to be modified to use the Java Plug-in. A sample HTML page is included with binary distribution of the Browser in the applet directory. Please see the Java Plug-in documentation for the modification details.

To run the Browser as an unsigned applet just extract the binary distribution into some web directory (e.g. ~/public_html/ldapbrowser/) and copy the applet/applet.html file into the browser root directory (e.g. ~/public_html/ldapbrowser/). Make sure to set the right permissions to all the files and directories, and then point your browser to the applet.html file.

To run the Browser as a signed applet you can follow the same directions as above and then you must sign all the jar files (in the lib directory and the lbe.jar file) with an object signing certificate. Please see the Java Plug-in documentation for details for this step.

What parameters I can pass to the applet?

There is a number of parameters that can be passed to the applet:

- width

- It sets the width of the Browser window. Defaults to 600 if not set. Example:

    <PARAM NAME=width VALUE=600>

- height

- It sets the height of the Browser window. Defaults to 370 if not set. Example:

    <PARAM NAME=height VALUE=400>

- base

- It sets the base location of the Browser where the templates, the help files, and the session files will be resolved from. Must be in form of URL. If the base location is not set, the location where the browser was loaded from will be used. The applet must have access to the specified base url. Example:

    <PARAM NAME=BASE VALUE="http://myserver.com/ldapbrowser">

- config

- 2.8.2: Specifies the location of the LBE configuration file (lbe.properties) to load. By default, the Browser will try to load the configuration file from the '.be' directory under user's home directory. See What is lbe.properties file? question for details. Example:

    <PARAM NAME=config VALUE="lbe.properties">

- 2.8.1: Specifies the name of the configuration file to load. It is resolved from the base location. If not set, the applet will try to load the default configuration file called browser.cfg. Example:

    <PARAM NAME=config VALUE="nds.cfg">

- dir

- Specifies the local directory where the session files will be loaded from. The applet must have access to the specified directory. Example:

    <PARAM NAME=dir VALUE="C:\ldapbrowser">

- window

- Specifies if the Browser should run in a panel within the web browser or in an external window. By default, the Browser runs within the web browser window. If set to 'frame' the Browser will run in an external window. If set to 'both', the user will be able to switch the Browser dynamically between the web browser and an external window. Example:

    <PARAM NAME=window VALUE="both">

- debug

- It enables the debug level of the Browser. This parameter takes exactly the same values as described in this question. Example:

    <PARAM NAME=debug VALUE="ldap:ssl">

How do I debug the Browser as an applet?

To debug the Browser as an applet first make sure to enable the Java Plug-in Console. It can be enabled through the Java Plug-in Control Panel. Once the console is enabled, you will see the console window appear when Java Plug-in is used in the browser. In addition you can also enable the Browser applet debugging by setting the debug parameter as described in the above question.

Attribute Viewers/Editor Questions

What are attribute viewers/editors?

The attribute viewer/editor is a means of displaying and/or editing the contents of an attribute. Each attribute can contain a different value that needs to be represented differently. For example, a 'jpegphoto' attribute contains an image and an 'audio' attribute contains a sound and a 'name' attribute contains some string. These three need to have different visual representations. In the case of the image, the actual image might be displayed. In the case of the sound, the sound might be played automatically or when a play button is pressed. In the case of the name attribute a textbox with the string might be displayed. The LDAP Browser/Editor allows users to customize the viewers/editors for any attribute.

What attribute viewers/editors are distributed with the Browser?

The following editors are currently distributed with the browser:

- ImageEditor

- allows the display of image files such as JPEG and GIF.

- CertificateEditor2

- allows the display of X.509 certificates.

- Password Editor

- allows for generating and verifying MD5, SHA, and Unix Crypt passwords.

- ControlViewer

- allows for displaying friendly names of the LDAP controls contained in the Root DSE.

- ExtBinaryEditor (experimental in 2.8.1)

- allows for executing external applications to view the contents of an attribute.

- ExtStringEditor (experimental in 2.8.1)

- allows for executing external applications to view the contents of an attribute.

- SoundEditor

- allows the playing of sound files such as AIFF, AU, WAV, TYPE 0 MIDI, TYPE 1 MIDI and RMF.

How do I set default algorithm for the Password Editor?

By default the Password Editor will generate a new password using the same algorithm as the algorithm used in the existing password. To force the editor to always generate a specific type of password edit the attributes.config file and add following arguments to the Password Editor line:

    -algorithm [algorithmType] -force

where algorithmType is one of following: Crypt, MD5 or SHA. For example, an entry for userpassword in my config file looks like following:

    userpassword=binary,lbe.editor.PasswordEditor -algorithm crypt -force

Also, make sure that your server is configured to accept the algorithm specified.

What is the ExtBinaryEditor and how can I use it?

The ExtBinaryEditor is a generic editor for binary attributes that allows for launching external applications to view the contents of the attribute. You can configure the ExtBinaryEditor to launch an external application to view the certificate by adding the following arguments to the ExtBinaryEditor line in the attributes.config file:

    -ext -extcmd "command {0}"

where command is an application to execute and {0} is an argument to the application. The argument is a filename that contains the data of the selected attribute.
Example:

    certificateRevocationList=binary,lbe.editor.ExtBinaryEditor -ext -extcmd "rundll32.exe cryptext.dll,CryptExtOpenCRL {0}"

The above example will allow to pass the data of the certificateRevocationList attribute to Windows default CRL viewer. (This assumes all the necessary software is installed)

What is the ExtStringViewer and how can I use it?

The ExtStringViewer is a generic viewer for the regular attributes that allows for passing the attribute value to an external application. For example, it could be used to pass an email address to mail application. It is used and configured the same as the ExtBinaryEditor where the only difference is that the {0} argument is the actual value of the selected attribute. Please see the question about the ExtBinaryEditor for details.
The following example will pass the email address stored in the mail attribute to Outlook Express on Windows. (This assumes all the necessary software is installed)

    mail=string,lbe.editor.ExtStringViewer -ext -extcmd "C:\\Program Files\\Outlook Express\\msimn.exe /mailurl:mailto:{0}"

How can I configure the CertificateEditor2 to launch an external application to view the certificate?

You can configure the CertificateEditor2 to launch an external application to view the certificate in the same way as you configure the ExtBinaryEditor. Please see the question about the ExtBinaryEditor for details.
The following example will pass the certificate to Windows certificate wizard: (This assumes all the necessary software is installed)

    usercertificate=binary,lbe.editor.CertificateEditor2 -ext -extcmd "rundll32.exe cryptext.dll,CryptExtOpenCER {0}"

How do I write a custom attribute viewer/editor?

Two things:

> 1. Extend some JComponent (from SwingSet) e.g. JPanel, JTextField, JTable.
> 2. Implement the AttributeEditor interface.

> or

> 1. Extend BinaryEditor (for binary values) or DefaultEditor (for string values) or any other built-in editor.
> 2. Override needed methods.

SSL Questions

How do I enable the SSL support in the Browser?

The Browser is closely integrated with the JSSE library from Sun. It is a free pure Java SSL library.
To enable the SSL support in the Browser do the following:

1. Download JSSE from: http://java.sun.com/products/jsse.
2. Install the JSSE package:

- either by following the general installation instructions, or by
- copying the jnet.jar, jsse.jar, jcert.jar files from the lib/ directory of the JSSE package to the lib/ directory of the Browser.

And that's all. To connect using SSL just make sure to select the SSL box in the connect window and specify the right port number.

Why does initial SSL connection take a while to establish?

The very first time a secure connection is established Java must create a secure seed required for the SSL connection. This is a very computationally expensive process and may take up to a few seconds on certain platforms. However, the seed only needs to be computed once per session.

How do I turn on debugging for the SSL connection?

To enable debug mode for secure connections use

    -Djavax.net.debug=all

option on the command line to the Java interpreter. For example:

    java -Djavax.net.debug=all -classpath .....  lbe.ui.BrowserApp

For details on how to modify the 'be' scripts to enable this property see the question about this.

How do I specify client certificates for the SSL connection?

To specify the client certificates you must create a Java keystore (using keytool) with your certificates and then add the path to the keystore and the password of the keystore to the session file.
For example:

       keystore   = .keystore
       passphrase = abcdef

Please note, that these settings will only work with the default secure socket factory that is built-in with the browser. If different socket factory is used, it might have another way of specifying these options.

If the passphrase is not specified in the session file, the Browser will prompt the user for it as needed.

Note: The passphrase of the keystore must match the password of the private key (keypass)

How do I fix the 'CA certificate not found' error?

This error occurs during SSL handshaking when the server does not send the CA certificate along with its certificates and the client cannot verify the server certificates because it also does not have the CA certificate. To fix this problem, you must obtain the server CA certificate and add it manually to the Browser's CA certificate store.
By default, the Browser maintains all the CA certificates in the lbecacerts file. The default password for the file is 'changeit'
Once you obtain the server CA certificate, you can add it to the lbecacerts file by using the keytool program, e.g.:

    keytool -import -alias myldap -file CAcert.cer -keystore lbecacerts -storepass changeit

See the Java documentation for more information about the keytool program.

Why does an SSL connection sometimes hang the browser?

Most likely this occurs when the ldap port number specified in the connection windows was not a SSL port. If non-secure socket is used to connect to a server's SSL socket, then the application using the non-secure socket will hang. This is a characteristic of the SSL protocol.