IBM Support

How to change the certificates of Security Directory Integrator

Troubleshooting


Problem

Generating a New Encryption Key, Certificates, and Keystore Files for SDI 7.2.x

Symptom

**
ERROR [server] - CTGDIS210W An error has occurred on Server API initialization: com.ibm.di.api.DIException: CTGDKD004E Could not create RMI custom socket factories. Exception occurred: {0} : Invalid keystore format.
.
ERROR [server] - CTGDIS216W An error has occurred while decrypting protected property: javax.crypto.BadPaddingException: Given final block not properly padded
.
WARN [server] - CTGDIS202E Could not set up the Server keystore password info. Exception occurred: java.io.FileNotFoundException: tdiserver.jceks (The system cannot find the file specified.)
.
WARN [server] - CTGDIS222W Server security has not been initialized
**
 

Environment

Tivoli Directory Integrator 7.1.*
Security Directory Integrator 7.2.*

Diagnosing The Problem

This problem can occur when the security settings have been or need to be modified, and error messages are listed in the ibmdi.log file.

Resolving The Problem

Background

When IBM Security Directory Integrator (SDI) initializes a new solution directory, it automatically copies a baseline configuration from the installation directory (<SDI_HOME>). This includes essential files such as global.properties, keystores, and supporting files that define runtime behavior.

If you are updating configuration files or resources in an existing solution directory, replace all references to <SDI_HOME> with <SDI_SOLDIR> and replace all references to global.properties with solution.properties. This ensures that the configuration changes are applied correctly to that specific solution environment.

After validating that the new resources (for example, keystores, and configuration updates) work as expected in the solution directory, copy these updated resources into the <SDI_HOME> locations. Doing so ensures that any future solution directories created will automatically inherit these updated configurations and security resources.

Before You Begin

Before proceeding, back up all existing keystores (*.jceks, *.jks), the stash file (idisrv.sth), and configuration files such as global.properties and solution.properties. This ensures you can restore a working configuration if an error occurs or if certificate verification fails.

Agenda

This guide outlines the steps to generate new encryption keys, keystores, and SSL certificates for IBM Security Directory Integrator (SDI).
You can either:

  • Option A: Generate self-signed certificates (default)
  • Option B: Generate a Certificate Signing Request (CSR) and obtain a CA-signed certificate.

Tip: After importing the CA-signed certificates, run keytool -list -v on the keystore to verify that the complete certificate chain (root, intermediate, and end-entity) is correctly imported before restarting SDI.

 

The guide then covers:

  1. Generating new keystore files
  2. Decrypting previously encrypted property values using the existing key
  3. Copying keystores to the proper directories
  4. Updating configuration files
  5. Updating registry.txt
  6. Creating a new stash file
  7. Creating and testing a new solution directory

Step-by-Step Instructions

Step 1: Generate Keystore Files (with SAN)

When generating new keys, ensure that the Distinguished Name (DN), certificate validity, key algorithm, key size, and Subject Alternative Names (SAN) are configured according to your organization’s standards and deployment requirements. For example: CN=hostname.example.com, O=Company, C=US, with a validity period such as 3650 days, and SAN entries for all relevant hostnames or IP addresses used by SDI.

All commands in examples are executed from the temporary working directory (e.g., cd $TEMP).
Ensure the same value is used for both storepass and keypass to avoid startup errors.

Option A – Self-Signed Certificates

cd $TEMP

# Generate symmetric key for encryption
<SDI_INSTALL>/jvm/jre/bin/keytool -genseckey -alias encryptkey -keyalg AES -keysize 256 -storetype jceks -keystore tdiserver.jceks -storepass passw0rd -keypass passw0rd

# Generate server keypair with SAN
<SDI_INSTALL>/jvm/jre/bin/keytool -genkeypair -alias server -dname "CN=sdi.example.com, O=Example, C=US" -validity 7300 -keyalg RSA -keysize 2048 -storetype jceks -keystore tdiserver.jceks -storepass passw0rd -keypass passw0rd -ext SAN=dns:sdi.example.com,dns:localhost,ip:127.0.0.1

# Generate admin keypair with SAN
<SDI_INSTALL>/jvm/jre/bin/keytool -genkeypair -alias admin -dname "CN=API Admin, O=Example, C=US" -validity 7300 -keyalg RSA -keysize 2048 -storetype jceks -keystore tdiadmin.jceks -storepass passw0rd -keypass passw0rd -ext SAN=dns:sdi.example.com,dns:localhost,ip:127.0.0.1

# Export and import certificates
<SDI_INSTALL>/jvm/jre/bin/keytool -exportcert -alias server -file tdiserver.der -storetype jceks -keystore tdiserver.jceks -storepass passw0rd

<SDI_INSTALL>/jvm/jre/bin/keytool -exportcert -alias admin -file tdiadmin.der -storetype jceks -keystore tdiadmin.jceks -storepass passw0rd

<SDI_INSTALL>/jvm/jre/bin/keytool -importcert -alias server -file tdiserver.der -storetype jceks -keystore tdiadmin.jceks -storepass passw0rd

<SDI_INSTALL>/jvm/jre/bin/keytool -importcert -alias admin -file tdiadmin.der -storetype jceks -keystore tdiserver.jceks -storepass passw0rd

Option B – Using a CA-Signed Certificate

If you prefer to use a trusted CA-signed certificate:

1. Generate the private key and CSR

cd $TEMP

# Create a new keystore and generate a CSR
<SDI_INSTALL>/jvm/jre/bin/keytool -genkeypair -alias server -dname "CN=sdi.example.com, O=Example, C=US" -validity 7300 -keyalg RSA -keysize 2048 -storetype jceks -keystore tdiserver.jceks -storepass passw0rd -keypass passw0rd -ext SAN=dns:sdi.example.com,dns:localhost,ip:127.0.0.1

# Generate the CSR
<SDI_INSTALL>/jvm/jre/bin/keytool -certreq -alias server -file server.csr -storetype jceks -keystore tdiserver.jceks -storepass passw0rd

2. Submit CSR to CA

Send server.csr to your preferred Certificate Authority (CA) — either an internal enterprise CA or a trusted third-party CA — following your organization's certificate issuance process.

You’ll receive:

  • A signed certificate (server.crt)
  • Intermediate CA certificate(s)
  • Root CA certificate (optional)

3. Import the CA chain into the keystore

cd $TEMP

# Import root CA (if applicable)
<SDI_INSTALL>/jvm/jre/bin/keytool -importcert -trustcacerts -alias rootCA -file rootCA.crt -keystore tdiserver.jceks -storetype jceks -storepass passw0rd

# Import intermediate CA(s)
<SDI_INSTALL>/jvm/jre/bin/keytool -importcert -trustcacerts -alias intermediateCA -file intermediateCA.crt -keystore tdiserver.jceks -storetype jceks -storepass passw0rd

# Import your signed certificate
<SDI_INSTALL>/jvm/jre/bin/keytool -importcert -alias server -file server.crt -storetype jceks -keystore tdiserver.jceks -storepass passw0rd

# Verify imported certificates and chain
<SDI_INSTALL>/jvm/jre/bin/keytool -list -v -keystore tdiserver.jceks -storetype jceks -storepass passw0rd

4. (Optional) For the admin keystore, repeat the process:

To mirror the default client and server certificates supplied with the product, generate another CSR with alias admin, use the file name tdiadmin.jceks, and submit it to your CA. Import the returned certificate(s) into the keystore. Share the public certificates (admin and server) between tdiadmin.jceks and tdiserver.jceks to ensure mutual trust between the client and server.

cd $TEMP

# Export and import certificates
<SDI_INSTALL>/jvm/jre/bin/keytool -exportcert -alias server -file tdiserver.der -storetype jceks -keystore tdiserver.jceks -storepass passw0rd

<SDI_INSTALL>/jvm/jre/bin/keytool -exportcert -alias admin -file tdiadmin.der -storetype jceks -keystore tdiadmin.jceks -storepass passw0rd

<SDI_INSTALL>/jvm/jre/bin/keytool -importcert -alias server -file tdiserver.der -storetype jceks -keystore tdiadmin.jceks -storepass passw0rd

<SDI_INSTALL>/jvm/jre/bin/keytool -importcert -alias admin -file tdiadmin.der -storetype jceks -keystore tdiserver.jceks -storepass passw0rd

Step 2: Decrypt Protected Values

Before creating new keys, you must decrypt any previously encrypted values using the existing encryption key and keystore. This ensures compatibility and allows SDI to re-encrypt the values later with the new key.

# Backup the original properties file
cp <SDI_HOME>/etc/global.properties <SDI_HOME>/etc/global.properties.bak

# Decrypt using the existing keystore (e.g., old tdiserver.jceks)
<SDI_HOME>/serverapi/cryptoutils.sh -input <SDI_HOME>/etc/global.properties -output <SDI_HOME>/etc/global.properties_plain -mode decrypt_props -keystore <SDI_HOME>/old_tdiserver.jceks -storepass oldpassword -alias server

# Replace the original file with the decrypted version
cp <SDI_HOME>/etc/global.properties_plain <SDI_HOME>/etc/global.properties

Note: Retain a secure copy of the old keystore and its password for rollback or audit purposes. Do not delete it until the new SSL configuration is verified. Depending on your environment, you may need to update solution.properties instead of global.properties if you are modifying an existing solution directory.

Step 3: Copy Keystore Files

cd $TEMP

cp tdiadmin.jceks <SDI_HOME>/serverapi/
cp tdiserver.jceks <SDI_HOME>/

Step 4: Update global.properties

Update <SDI_HOME>/etc/global.properties with:

# Server authentication
javax.net.ssl.trustStore=serverapi/tdiadmin.jceks
{protect}-javax.net.ssl.trustStorePassword=passw0rd
javax.net.ssl.trustStoreType=jceks

# Client authentication
javax.net.ssl.keyStore=serverapi/tdiadmin.jceks
{protect}-javax.net.ssl.keyStorePassword=passw0rd
javax.net.ssl.keyStoreType=jceks

# API keystore settings
api.keystore.type=jceks
api.keystore=tdiserver.jceks
api.key.alias=server
{protect}-api.keystore.password=passw0rd
{protect}-api.key.password=passw0rd

# Encryption key settings
com.ibm.di.server.encryption.keystore=tdiserver.jceks
com.ibm.di.server.encryption.key.alias=encryptkey
com.ibm.di.server.encryption.keystoretype=jceks
com.ibm.di.server.encryption.transformation=AES

# API truststore settings
api.truststore.type=jceks
api.truststore=tdiserver.jceks
{protect}-api.truststore.pass=passw0rd

# Server API client settings
api.client.ssl.custom.properties.on=true
api.client.keystore=serverapi/tdiadmin.jceks
{protect}-api.client.keystore.pass=passw0rd
api.client.keystore.type=jceks
{protect}-api.client.key.pass=passw0rd
api.client.truststore=serverapi/tdiadmin.jceks
{protect}-api.client.truststore.pass=passw0rd
api.client.truststore.type=jceks

Note: The {protect} prefix indicates that SDI will encrypt these values at runtime. 

Step 5: Update registry.txt

This DN corresponds to the alias admin created in Step 1 and must be added or updated in this file. The registry.txt lists all authorized clients allowed to connect to SDI using credentials stored in serverapi/tdiadmin.jceks.

[USER]
[ID]:CN=API Admin, O=Example, C=US
[ROLE]:admin
[ENDUSER]

Step 6: Create the Stash File

The idisrv.sth stash file is generated in the directory from which the createstash.bat or createstash.sh command is executed. Execute this command from the target directory where you want the stash file to reside. For consistency and system compatibility, use the exact same password specified during the key creation process in Step 1 for tdiserver.jceks when generating this stash file.

cd <SDI_HOME>
<SDI_HOME>/bin/createstash.sh passw0rd passw0rd

Step 7: Verify Configuration

  1. Start the SDI server.
  2. Confirm that no SSL errors occur in the ibmdi.log 
  3. Verify that previously protected values are re-encrypted with the new key.
  4. Use an SSL inspection tool or browser to confirm the CA certificate chain is trusted (if using a CA-signed cert).

Result:
Your SDI server now supports secure SSL connections using either:

  • Self-signed certificates (quick setup), or
  • CA-signed certificates (trusted production setup).

AS-IS Example script:
##############
SDI - Bash script to generate new keypair, and change password for testserver.jks and testadmin.jks
###################################################################
# Script Name:  generateSDIcertificates
# Description:  The script will
#                   (1)change the password for testadmin.jks, testadmin.jks, and idisrv.sth
#                   (2)generate new certificates for both store files
#                   (3)update solution.properties with the new passwords
#
# INFO: Run as user, which owns SDI Install Directory and Solution Directory
###################################################################
 

[{"Line of Business":{"code":"LOB24","label":"Security Software"},"Business Unit":{"code":"BU008","label":"Security"},"Product":{"code":"SSCQGF","label":"Tivoli Directory Integrator"},"ARM Category":[{"code":"a8m0z0000001hYOAAY","label":"SSL \/ Certificates"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"7.1.1;7.2.0"}]

Document Information

Modified date:
31 October 2025

UID

ibm11103787

Page Feedback