| Note |
|---|
|
Before using this information and the product it supports, read the general information under Appendix A, 8.0 Notices. |
This file contains a description of the IBM(R) Directory Server Client SDK Version 4.1. This Software Developer's Kit (SDK) provides LDAP application development support for the following operating systems:
3.0 Important considerations for secure LDAP (using SSL)
5.0 Installing the IBM Directory Server clients
6.0 IBM Directory Server client SDK description
The IBM Directory Server Client SDK consists of the following components for developing C applications:
The following component is provided for developing Java(TM) applications that use Sun Microsystems's Java Naming and Directory Server Interface (JNDI) (7). This permits Java applications to access Lightweight Directory Server Access Protocol (LDAP) compliant directory servers:
The LDAP libraries (C and JNDI) enable the programmer to develop applications that can access an LDAP-compliant Directory Server, including, but not limited to the following:
The LDAP API provides typical Directory Server functions such as read, write and search. The client can authenticate itself to the Directory Server using a password and Distinguished Name (DN) (simple) or one of the Simple Authentication and Security Layer (SASL) mechanisms (CRAM-MD5, GSSAPI or EXTERNAL).
The client SDK includes tools to build your own LDAP application (LDAP Version 2 or LDAP Version 3). Note that the client SDK for C also provides support for Secure Sockets Layer (SSL), which provides data confidentiality (encryption) on connections protected by SSL. SSL support is enabled when the IBM Global Security Kit, Version 5.0.4.X (GSKit) is installed. GSKit is optional software that is included with the IBM Directory Server package.
The client SDK also provides support for Java applications. The Java client SDK is an implementation of Sun's JNDI.
In addition to the Readmes, on-line documents including the Release Notes, the Administration Guide, the Programming Reference are provided in pdf and html format. The Directory Server Management Tool online helps are provided in html format.
The IBM Directory Server Version 4.1 uses the JNDI client from Sun Microsystems. For information about the JNDI client, go to the Sun Microsystems Web site at http://java.sun.com/products/jndi/1.2/javadoc/index.html
For Windows systems:
For AIX systems:
For Solaris systems:
For Linux systems:
For HP-UX systems:
Further information is available on the Web. Find the IBM Directory Server page at http://www-306.ibm.com/software/network/directory/ for general information and announcements.
The LDAP libraries and utilities provided with the client SDK utilize the SSL libraries, if present. The SSL libraries are provided as part of IBM's GSKit 5.0.4.X. If GSKit has been installed, the LDAP library will dynamically load the SSL libraries and use them to enable support for SSL. If GSKit has not been installed, and the SSL libraries are not available, the LDAP library is fully functional, with the exception of SSL support.
GSKit includes tools for managing the SSL key database file. The mkkf utility used with older versions of the LDAP client SDK has been replaced by the following program:
gsk5ikm a Java GUI application for managing the keyring database and
generating certificate requests.
The gsk5ikm utility is used to manage keys and certificates in files with a new format. The gsk5ikm utility can be used to migrate a pre-existing keyring file, as created with mkkf, to the new format used by gsk5ikm. The gsk5ikm utility can also be used to create a key.class file for use with JNDI applications. This permits JNDI applications to implement server authentication and server-client authentication when connecting to an LDAP server when using SSL to create secure connections.
See the SSL sections in the on-line, html-based LDAP Programming Reference for more information about using gsk5ikm.
By using SSL with server authentication, the LDAP application can use simple LDAP authentication (USERID and password) over a secure, encrypted communication connection. SSL thus provides for the establishment of a secure connection between the LDAP client application and the LDAP server. In addition, SSL provides data confidentiality (encryption) on connections protected by SSL. Authentication of servers to the clients is accomplished with X.509 certificates.
The gsk5ikm korn shell script on AIX is trying to find a file '$JAVA_HOME/sh/jre' that no longer exists. To use this java utility you must issue the following commands:
ln -s /usr/ldap/java/bin/java /usr/ldap/java/bin/jre
The Directory Management Tool is intended for use with IBM Directory Server on AIX, Windows systems, Solaris, Linux, and AS/400(R) operating systems. It might work with some other LDAP directories, but such use is not supported. The Directory Management Tool for the latest IBM Directory Server release (4.1) works with, and is supported for earlier SecureWay 3.x releases. However, the converse is not true. Use the latest Directory Management Tool when communicating with the latest level of the IBM Directory Server.
The IBM Directory Server Directory Management Tool provides a Java Virtual Machine-based graphical user interface that enables you to manage information stored in LDAP directory servers. You can use this tool to:
For more information on using and configuring Directory Management Tool, see the Directory Management Tool on-line documentation (load dparent.htm with your preferred web browser).
To start Directory Management Tool, simply type dmt.
To automatically run the Directory Management Tool with its default configuration file, start it in the ldaphome\bin subdirectory.
On the SuSE Linux 7.2 version of the Linux operating system, the Directory Management Tool panels are displayed in English, even if you have set your locale variable to a language other than English. This is a known problem. The SuSE Linux 7.2 version of the Linux operating system is not officially supported by Java 1.3, which is included in the IBM Directory Server Version 4.1 release.
At the present time the Directory Management Tool, depending on the resources available, has a performance limitation of 100,000 entries. Using the tool with directories having greater than 100,000 entries might lessen the performance of the tool.
Syntax length is not a mandatory field. It defaults to 240 bytes for a string and 256 bytes for a binary. A string can range from a minimum of 1byte to a maximum of 32700 bytes. The maximum for a binary is 2 GB.
On the Solaris 8 operating system with the default Traditional Chinese locale (zh_TW.Big5) if you are running the Directory Management Tool, you need to add the following to your profile:
export LANG=zh_TW export LC_ALL=zh_TW
Use this procedure to install the Windows clients. You can also use the InstallShield GUI to install the UNIX-based clients, except for the Linux S/390(R), TurboLinux 6.5 and HP-UX clients. They must be installed using the appropriate system utilities.
InstallShield GUI has two installation options: Typical and Custom. If you want to accept the default settings, select Typical during installation. If you are an experienced user and want to customize your installation, select Custom.
Typical installation uses default settings and is recommended for new users.
To begin installing IBM Directory Server 4.1:
Select the Client SDK 4.1. You can also select DMT 4.1 and Java 1.3, if you want to install the Directory Management Tool on your client.
Custom installation is for experienced users who want to customize their installation.
The components that are not yet installed are preselected. You can choose to reinstall the Server or the Client, if they were previously installed.
This panel also indicates the amount of disk space required and available on the selected drive.
Click Back to change any of your selections. Click Next to begin installation.
You can use InstallShield (the preferred installation method) or either smit or installp from a command prompt to install the IBM Directory Server. If you use the InstallShield to install, you must use the installShield to uninstall.
For more detailed information on AIX installation procedures and commands, see the IBM Directory Server Version 4.1 Installation and Configuration Guide for Multiplatforms.
The following instructions assume that you are installing from a CD-ROM with the device name /dev/cd0.
To install IBM Directory Server using smit:
http://www-306.ibm.com/software/network/directory/downloads/
smit install
and press the Enter key. The Software Installation and Maintenance window is displayed.
For this example the non-SSL package is used. If you select the list option, you see:
> ldap.client ALL
4.1.0.0 IBM Directory Client DMT
4.1.0.0 IBM Directory Client Java
4.1.0.0 IBM Directory Client Runtime (No SSL)
4.1.0.0 IBM Directory Client SDK
> ldap.html.en_US ALL
4.1.0 IBM Directory Server HTML Install/Config Guide - U.S. Engli
4.1.0 IBM Directory Server HTML man Pages - U.S. English
> ldap.server ALL
4.1.0 IBM Directory Server Administrative Interface
4.1.0 IBM Directory Server Framework
4.1.0 IBM Directory Server Runtime (No SSL)
When you finish selecting filesets, click OK.
lslpp -L | grep ldap
The output displayed lists all the filesets starting with ldap. This includes the client, html, and message filesets. For example:
ldap.client.adt 4.1.0.0 C IBM Directory Client SDK
ldap.client.dmt 4.1.0.0 C IBM Directory Client DMT
ldap.client.java 4.1.0.0 C IBM Directory Client Java
ldap.client.rte 4.1.0.0 C IBM Directory Client
ldap.html.en_US.config 4.1.0.0 C IBM Directory HTML
ldap.html.en_US.man 4.1.0.0 C IBM Directory HTML man
ldap.msg.en_US 4.1.0.0 C IBM Directory Messages
To install IBM Directory Server from a command prompt:
http://www-306.ibm.com/software/network/directory/downloads/
installp -ld /dev/cd0 | grep ldapA list all of the installable IBM Directory Server packages is displayed.
Some examples of United States English-specific packages are:
ldap.html.en_US.man ldap.msg.en_US
installp -acgXd /dev/cd0 <packages>
where :
Examples:
To install only the IBM Directory Server client files, type:
installp -acgXd /dev/cd0 ldap.client
To install all of the IBM Directory Server filesets (including every language translation of messages), type:
installp -acgXd /dev/cd0 ldap
lslpp -L | grep ldap
The output displayed lists all the filesets starting with ldap. This includes the client, html, and message filesets. For example:
ldap.client.adt 4.1.0.0 C IBM Directory SDK
ldap.client.dmt 4.1.0.0 C IBM Directory Client DMT
ldap.client.java 4.1.0.0 C IBM Directory Client Java
ldap.client.rte 4.1.0.0 C IBM Directory Client Runtime
ldap.html.en_US.config 4.1.0.0 C IBM Directory Install/Config
ldap.html.en_US.man 4.1.0.0 C IBM Directory Man Pages -U.S.
ldap.msg.en_US 4.1.0.0 C IBM Directory Messages -U.S.
You can use InstallShield (the preferred installation method) or either the admintool utility or pkgadd from a command prompt to install IBM Directory Server. If you use the InstallShield to install, you must use the installShield to uninstall.
The following two IBM Directory Server packages are available for installation. Because of package dependencies, the order of installation is significant. Install the packages in the following order:
Because of package dependencies, the order of installation is significant. Install the packages in the following order:
If the client package is not installed first, the installation fails.
During the installation of the client on Solaris Operating Environment Software Version 8, you might encounter the following message:
A non-IBM version of LDAP has been located on your system. In order to usethe command line version of the IBM supplied files, the existing files (ldapadd,ldapdelete, ldaplist, ldapmodify, ldapmodrdn, ldapsearch) must be relocated. Specify the new directory in which to move the files (/usr/bin/ldapsparc) [?,q]
Press Enter to accept the default directory (/usr/bin/ldapsparc), or type a new path name and press Enter, or type q and press Enter to quit.
After relocating the files, you might see these additional messages:
## Processing system information. WARNING: /usr/bin/ldapadd <no longer a linked file> WARNING: /usr/bin/ldapdelete <no longer a regular file> WARNING: /usr/bin/ldapmodify <no longer a regular file> WARNING: /usr/bin/ldapmodrdn <no longer a regular file> WARNING: /usr/bin/ldapsearch <no longer a regular file> ## Verifying package dependencies. ## Verifying disk space requirements. ## Checking for conflicts with packages already installed. The following files are already installed on the system and are being used by another package: /usr/bin/ldapadd /usr/bin/ldapdelete /usr/bin/ldapmodify /usr/bin/ldapmodrdn /usr/bin/ldapsearch Do you want to install these conflicting files [y,n,?,q]
Type y and press Enter to continue the installation. The existing files are moved to the directory previously specified and the IBM Directory Server files are installed in the /usr/bin directory.
To install IBM Directory Server using the admintool utility:
admintool&
The Users window is displayed.
/cdrom/cdrom0/
IBM Directory Client IBM Direcotry DMT and Java IBM Directory Documentation (for all languages) IBM Directory Messages (for all languages)
Remember that you must install the IBMldapc package first.
This package contains scripts which will be executed with super-user permission during the process of installing the package.
These scripts create the IBM Directory Server user ID. Type y to continue.
To install IBM Directory Server from a command prompt:
pkgadd -d /cdrom/cdrom0/<subdirectory>
where <subdirectory> contains the IBM Directory Server packages. The following packages are available:
1 IBMldapc IBM Directory Client
(sparc)4.1.0.0
2 IBMldapdj IBM Directory DMT and Java
(sparc)4.1.0.0
3 IBMldixxx IBM Directory Server documentation (where xxx is
language dependent)
(sparc)4.1.0.0
4 IBMldm xxx IBM Directory messages
(sparc)4.1.0.0
Attention: Do not use the system default of all. The system does not sequence the packages correctly and the installation fails. The order in which the packages are listed is crucial. If package dependencies are not met, the installation fails.
pkgadd -d /cdrom/cdrom0/<subdirectory> IBMldapc
pkgadd -d /cdrom/cdrom0/<subdirectory> IBMldapc IBMldixxx
One method to determine if you have a previously installed version of LDAP is to issue the following command to query the installed packages:
rpm -qa | grep -i ldap
This command finds any installed applications containing the name ldap. This method works only if you have a version of LDAP that contains the string ldap in its application names.
You can use the InstallShield on all Linux platforms except Linux S/390 and TurboLinux 6.5.
The IBM Directory Server client for Linux operating systems is shipped in the following packages:
rpm --nodeps -hiv ldap-client-4.1-1.i386.rpmSpecifying --nodeps bypasses dependency checking. It allows the code to be installed.
To install the IBM Directory Server client with no-SSL, you must:
rpm -hiv ldap-client-4.1-1.i386.rpm
rpm -hiv ldap-javadmt-4.1-1.i386.rpm
rpm -qa | grep ldap
If the product has been successfully installed, the following is displayed:
ldap-client-4.1-1 ldap-javadmt-4.1-1
rpm -hiv ldap-msg-xxx -4.1-1.i386.rpm rpm -hiv ldap-html-xxx -4.1-1.i386.rpm
After installing the messages, you need to set the following environment variables:
export NLSPATH=/usr/share/i18n/msg/%L/%N export LANG=xxx LC_ALL=xxx
where xxx is the language. For example, en_US for English.
To install the IBM Directory Server client with encryption, you must:
rpm -hiv ldap-cliendt-4.1-1.i386.rpm
rpm -hiv ldap-javadmtd-4.1-1.i386.rpm
rpm -qa | grep ldap
If the product has been successfully installed, the following is displayed:
ldap-clientd-4.1-1 ldap-javadmtd-4.1-1
rpm -hiv ldap-msg-xxx -4.1-1.i386.rpm rpm -hiv ldap-html-xxx -4.1-1.i386.rpm
After installing the messages, you need to set the following environment variables:
export NLSPATH=/usr/share/i18n/msg/%L/%N export LANG=xxx LC_ALL=xxx
where xxx is the language. For example, en_US for English.
To install the HP-UX client, perform the following steps:
Selecting LDAPClient_noSSL installs the client with SSL disabled.
SHLIB_PATH=/usr/lib
For example, at a command prompt type:
export SHLIB_PATH=/usr/lib;$SHLIB_PATH
The IBM Directory Server Client SDK provides the tools required to develop LDAP applications, including the following:
ldapmodrdn.exe LDAP modify relative distinguished name
ldapdelete.exe LDAP delete
ldapmodify.exe LDAP modify
ldapsearch.exe LDAP search
ldapadd.exe LDAP add (a renamed version of ldapmodify)
path = c:\Program Files\IBM\LDAP
This is the default, depending on install target.
Sample C-client programs are provided in the following locations:
Included with the samples is a makefile for use with the sample programs, as well as a sample LDIF file.
This information was developed for products and services offered in the U.S.A. IBM might not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of LicensingFor license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation LicensingThe following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
IBM CorporationSuch information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBM's suggested retail prices, are current and are subject to change without notice. Dealer prices may vary.
The following terms are trademarks of International Business Machines Corporation in the United States, or other countries, or both:
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
Microsoft(R), Windows, and Windows NT are registered trademarks of Microsoft Corporation.
Intel is a registered trademark of Intel Corporation in the United States, other countries, or both. (For a complete list of Intel trademarks, see http://www.intel.com/sites/corporate/tradmarx.htm.)
UNIX is a registered trademark of the Open group.
Other company, product, and service names may be trademarks or service marks of others.