How To
Summary
These instructions assume that you have a working AIX LDAP client that is not currently using SSL, and you want to enable it. They can also be used if you need to modify an existing SSL-enabled setup by rebuilding the SSL key database file and adding a new certificate.
Steps
First, it is best to ensure that your idsldap and associated IBM Global Security Kit (GSKit) file sets are matching and up-to-date.
Obtain the latest idsldap and IBM Global Security Kit (GSKit) packages from the most recent AIX media. The idsldap filesets should be on AIX base media, and the IBM GSKit filesets should be on the AIX Expansion Pack. At the time of this writing (3Q 2024), the most recent idsldap version available to AIX customers is 10.0.0.1, but a newer version should be available soon.
Follow the instructions here to install both packages -
The instructions (at the time of this writing) mention the path /opt/IBM/ldap/V6.4/bin. Since you will be installing the most recent filesets, the V6.4 portion will need to be changed to V10.0, V10.0.1, V10.0.2, etc depending on what you've actually installed.
Make sure to install the 'max_crypto' filesets mentioned in that link, since they are essential to enable SSL/TLS, and may not have been previously installed when LDAP was initially configured.
In addition to installing the packages, this link describes how to accept the license with 'idsLicense' and link the libraries into place with 'idslink'. That link suggests the following idslink command:
./idslink -g -i -l 32 -f
I would suggest adding the '-l 64' flag also. Although it is not needed for secldapclntd operation, this ensures that the correct libraries are linked in place for any 64-bit applications you are using that interact with LDAP:
./idslink -g -i -l 32 -l 64 -f
To enable SSL, your LDAP server team should provide you an exported SSL certificate that can be used for SSL communication with the server. The certificate file can be in binary or ASCII format.
Once you've got that, the commands used to create the client SSL key database would be as follows. The command we will be using is gsk8capicmd (or gsk8capicmd_64), which exists as a link seen here:
# ls -l /usr/bin/gsk8capicmd
lrwxrwxrwx 1 root system 33 Feb 25 12:46 /usr/bin/gsk8capicmd -> /usr/opt/ibm/gsk8/bin/gsk8capicmd
Create the key database file:
gsk8capicmd -keydb -create -db /etc/security/ldap/client.kdb -pw <password>
That assumes you want to call the database '/etc/security/ldap/client.kdb', but you can choose any location and file name to use, as long as you have the .kdb extension.
Next, you need to import the SSL certificate into this key database. Do this with:
gsk8capicmd -cert -add -db /etc/security/ldap/client.kdb -pw <password> -label <label of cert> -file <file containing exported cert>
If you do not know the label of the certificate, you can leave that argument out. This causes it to import all certificates that are provided in the file. This would also be useful if there are multiple certificates that you are wanting to import from the same file:
gsk8capicmd -cert -add -db /etc/security/ldap/client.kdb -pw <password> -file <file containing exported cert>
Run the following to get a list of labels of the certificates that exist in the key database:
gsk8capicmd -cert -list -db /etc/security/ldap/client.kdb -pw <password>
gsk8capicmd -cert -details -label <cert label> -db /etc/security/ldap/client.kdb -pw <password>
You can run the 'validate' command to check for any errors, such as missing a part of the certificate chain, an expired ticket, or any other errors. This command will validate a single certificate specified by it's label:
gsk8capicmd -cert -validate -db /etc/security/ldap/client.kdb -pw <password> -label "<cert label>"
By leaving out the 'label' option, this command will check every certificate that is in the key database:
gsk8capicmd -cert -validate -db /etc/security/ldap/client.kdb -pw <password>
Now that you've got a key database created and certificates added to it, adding SSL capability to /etc/security/ldap/ldap.cfg would involve adding these lines:
useSSL:yes
ldapsslkeyf:/etc/security/ldap/client.kdb
ldapsslkeypwd:<encrypted password>
Be sure that you remove/comment out any existing useSSL, ldapsslkeyf, or ldapsslkeypwd entries.
Note that 'useSSL:SSL' is equivalent to 'useSSL:yes', and they both enable the usage of the SSL/TLS family of protocols - SSLv3, TLS1.0, TLS1.1, TLS1.2, and TLS1.3 on the most recent idsldap filesets. This option defaults to using port 636 to communicate with the LDAP server. The 'useSSL:TLS' setting is something different - it signifies that you want to use StartTLS, which starts the connection in an insecure manner on port 389 before upgrading the connection to use TLS. There is nothing wrong with using 'useSSL:TLS' as long as you know that is what you want; be aware some LDAP servers may be configured to reject connection attempts on port 389, however.
To get the encrypted version of your password, do the following. Make sure you have single apostrophes around your actual password, and back ticks before and after the secldapclntd command:
SSLPWD=`secldapclntd -e 'secret'`
echo $SSLPWD
You can then copy/paste that encrypted result into the ldapsslkeypwd entry of ldap.cfg.
When that is done, do a 'restart-secldapclntd' and verify if LDAP is working.
You may decide that you do not want to deal with a password for your SSL key database. In that case, you can create a stash file for your password.
Create the key database like this:
gsk8capicmd -keydb -create -db /etc/security/ldap/client.kdb -pw <pwd> -stash
This takes the password that you give and create a .sth file along with the .kdb key database file; it is your password stash file.
When performing operations on the kdb file, instead of using the '-pw <pwd>' argument, use '-stashed':
gsk8capicmd -cert -list -db /etc/security/ldap/client.kdb -stashed
This looks for an .sth file with the same name as the .kdb file - /etc/security/ldap/client.sth, in this example. If the stash file is valid, it allows the operation on the key database.
If you are using a stash file, there is no need to populate the 'ldapsslkeypwd' setting in ldap.cfg. Likewise, if you were to run an ldapsearch command, you would not need the '-P <key_pw>' argument.
Related Information
Document Location
Worldwide
[{"Line of Business":{"code":"LOB08","label":"Cognitive Systems"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG10","label":"AIX"},"ARM Category":[{"code":"a8m0z000000cvzjAAA","label":"Security-\u003ELDAP\/LDAPA\/GSKIT"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Version(s)"}]
Was this topic helpful?
Document Information
Modified date:
28 February 2025
UID
ibm16396206