Generating and Installing new Self-Signed Certificates

Introduction:

ITM generates a self-signed certificate during installation but that contains generic information not specific to your particular system environment. It is better to have a certificate authority and issue signed certificates, as described in ITM Certificate Authentication Configuration Guide for ITM 6.2.2 and newer releases, but if that is not possible, then regenerating and distributing new self-signed certificate is acceptable to meet basic security requirements for TLS communication.

 

You may have arrived on this page because a network scanner has told you the certificate generated by ITM has weak message digest /hash algorithm or is too small. This product-provided certificate is generated at install time and is suggested to be replaced by the customer with a valid certificate either generated from a central authority or re-generated for your own installation. 

 

This script will allow you to generate a new self-signed certificate that you may drop into place on top of your existing certificate store in ITM for the purposes of bypassing the scanner warning.

A full solution requires generating proper certificates for all your components signed by a trusted authority.

Download the Script

Use the below (and attached) script to generate a self signed certificate. Copy the resulting keyfiles directory contents to the remote server into the ITM home/keyfiles directory. Restart the agent and the new certificate will be in use. The script will generate a 2048-bit RSA self-signed certificate signed with SHA-512 digital signature digest.

 

Certificate Files

 

ITM stores its secret keys and certificates in the following places:

 

Platform

Directory

Windows

$ITMHOME\keyfiles

Unix/Linux

$ITMHOME/keyfiles

z/OS RACF Manages the certificate
i5/OS Configuring the i5OS Agent using IP.SPIPE

 

The specific files in the directory are important to understand what has to be replaced:

 

File

Purpose

Keyfiles.kdb

Default Key database for ITM agents. One is shared by all ITM components. The IBM_Tivoli_Monitoring_Certificate is used for certificate negotiation by default.

Keyfiles.sth

Stash file that holds the obfuscated password for the key database. Ensure this file’s permissions are locked down to agent user ids and administrators

Keyfile.crl

Legacy file for storing certification revocation lists. No longer used.

Keyfile.rdb

 

KAES256.ser

256-bit AES Key used to encrypt locally encrypted configuration data or decrypting credentials passed through remote deploy functions. This key is not used for communication encryption.

 

ITM components access their certificate through environment variables that must be set or SSL/TLS communication won’t work. These values

 

Variable

Default Value

Purpose

KEYFILE_DIR

$ITMHOME\keyfiles

The keyfile directory where the key database is stored

KDEBE_KEYRING_FILE

$ITMHOME/keyfiles

The specific key database file with the agent’s certificates

KDEBE_KEYRING_STASH

$ITMHOME/keyfiles/keyfiles.sth

The path to the stash file containing the obfuscated key database password

KDEBE_KEY_LABEL

IBM_Tivoli_Monitoring_Certificate

The label of the specific certificate to use for authentication. A certificate must be present even when no validation is enabled.

 

Prerequisites/Guidelines:

1) Make sure you have an ITM installation on the box you are generating your scripts from

2) The script is written for a UNIX/Linux system with bash installed. It may be easily adapted for other shells or even batch

3) You can use this script to generate a new self-signed certificate for each one of your machines. The script allows for easy automation by pip

Usage:

Usage for Utility Script

 

usage ./gentSSCert.sh [ITMHOME PATH] [Directory where to output] [Hostname of Target Machine] [Organization Name] [Company name]

Keyfiles stored in a directory [OUTPUTFOLDER]/[HOSTNAME]/keyfiles/

for convenient replacement on remote systems

The Distinguished name in the certificate will be cn=[HOSTNAME],o=[Organization Name],c=[Company Name]

Sample Usage

./gentSSCert.sh /opt/IBM/ITM ./certificates itm.tivoli.ibm.com Tivoli IBM

 

 

Example:

 

Example usage

[root@itm~]# hostname

itm

[root@tameaix5 ~]# nslookup itm

Server: ns1.ibm.com

Address: 10.1.1.1

 

Name: itm.tivoli.ibm.com

Address: 10.1.22.1

bash# ./gentSSCert.sh /opt/IBM/ITM ./certificates itm.tivoli.ibm.com Tivoli IBM

 

bash-2.05a# ./genSSCert.sh /opt/IBM/ITM ./certificates itm.tivoli.ibm.com Tivoli IBM
 
Generating Self-Signed RSA Certificate for hostname itm.tivoli.ibm.com
Certificate Size: 2048
Certificate Signature Algorithm: SHA-512
Certificate Keystore: /home/root/certmanage/ss/certificates/itm.tivoli.ibm.com/keyfiles/keyfile.kdb
Certificate Keystore Password: Xl94R3RUIjdbbH
Certificate Label: IBM_Tivoli_Monitoring_Certificate
 
 
Certificates found:
* default, - has private key, ! trusted
-!      IBM_Tivoli_Monitoring_Certificate
Label        : IBM_Tivoli_Monitoring_Certificate
Key Size     : 2048
Version      : X509 V3
Serial Number: 6619c819d8b1dbfb
Issuer       : cn=itm.tivoli.ibm.com
Subject      : cn=itm.tivoli.ibm.com
Valid From   : Sunday, 12 May 2013 16:01:53 PM
To           : Sunday, 25 June 2023 16:01:53 PM
Finger Print : 0xb6caab35e50748043d871ef848706e24d85ba065
Extensions   : Present
Signature Algorithm: 1.2.840.113549.1.1.13
Trusted      : enabled
bash-2.05a#
bash-2.05a# ls
certificates  genSSCert.sh
bash-2.05a# cd certificates/
bash-2.05a# ls
itm.tivoli.ibm.com
bash-2.05a# cd
bash-2.05a# find .
.
./itm.tivoli.ibm.com
./itm.tivoli.ibm.com/keyfiles
./itm.tivoli.ibm.com/keyfiles/keyfile.kdb
./itm.tivoli.ibm.com/keyfiles/keyfile.rdb
./itm.tivoli.ibm.com/keyfiles/keyfile.crl
./itm.tivoli.ibm.com/keyfiles/keyfile.sth
 

 

bash# cp ./certificates/itm.tivoli.ibm.com/keyfiles/* /opt/IBM/ITM/keyfiles/

bash# cd /opt/IBM/ITM/bin

bash# ./itmcmd agent stop ux

bash# ./itmcmd agent start ux

 

Verification:

You may verify the quality of the script by following the instructions on 'Setting and Verifying ITM SSL/TLS Cipher Security'.

 

Full Script:

Generate Self-Signed Certificate

 

 
#!/bin/bash
 
export ITMHOME=$1
 
export OUTPUTFOLDER=$2
 
export HOSTNAME=$3
 
export ORGNAME=$4
 
export COMPANYNAME=$5
 
export STOREROOTNAME=keyfile
 
export LABEL_NAME=IBM_Tivoli_Monitoring_Certificate
 
if [ -z $COMPANYNAME ]; then
echo usage $0 [ITMHOME PATH] [Directory where to output] [Hostname of Target Machine] [Organization Name] [Company name]
 
echo Keyfiles stored in a directory [OUTPUTFOLDER]/[HOSTNAME]/keyfiles/
echo for convenient replacement on remote systems
echo The Distinguished name in the certificate will be cn=[HOSTNAME],o=[Organization Name],c=[Company Name]
 
echo Sample Usage
echo $0 /opt/IBM/ITM ./certificates itm.tivoli.ibm.com Tivoli IBM
 
else
 
 
if [ ! -d $OUTPUTFOLDER ]; then
mkdir $OUTPUTFOLDER
fi
cd $OUTPUTFOLDER
 
export CDIR=${PWD}
 
export OUTPUTFOLDER=${CDIR}/${HOSTNAME}/keyfiles
 
mkdir -p ${OUTPUTFOLDER}
 
# the easiest way to get proper paths is to use the
# the environment of the agents. Choose the proper any agent
# code in your environment
 
export GSK7BIN=`find ${ITMHOME} -name gsk7capicmd_64`
export GSK7BINFILE=${GSK7BIN##*/}
 
export GSK7LIBS=`find ${ITMHOME} -name lib64`
export GSK7LIBFILE=${GSK7LIBS##*/}
 
 
export GSK7BINPATH=${GSK7BIN%$GSK7BINFILE}
 
#export GSK7LIBPATH=${GSK7LIBS%$GSK7LIBFILE}
 
export GSK7LIBPATH=`find ${ITMHOME} -name lib64`
 
export LIBPATH=$GSK7LIBPATH:$PATH
export LD_LIBRARY_PATH=$GSK7LIBPATH:$PATH
export PATH=$GSK7BINPATH:$PATH
 
 
# echo $LIBPATH
# echo $PATH
 
 
# fixed passwords are not a good idea
 
# export CAPASSWORD=ABCDEFG
 
# change this password to something better and more random
export CAPASSWORD=`${GSK7BIN} -random -create -length 14 -strong -fips |perl -MMIME::Base64 -ne 'print encode_base64($_)' | cut -c1-14`
 
cd ${OUTPUTFOLDER}
/bin/rm -f ./${STOREROOTNAME}.*
 
${GSK7BIN} -keydb -create -db ${OUTPUTFOLDER}/${STOREROOTNAME}.kdb -pw ${CAPASSWORD} -expire 3650 -fips -stash
 
 
# newline is array delimiter
IFS=$'\n'
 
CERTLIST=(`${GSK7BIN} -cert -list -db ${OUTPUTFOLDER}/${STOREROOTNAME}.kdb -pw ${CAPASSWORD} -fips |grep "^\!" |perl -pi -e 's/!\t//'`)
 
element_count=${#CERTLIST[*]}
#echo "There are $element_count elements in the array"
 
# Clean out the trusted CA certificates
i="0"
while [ $i -lt $element_count ]
do
#echo $i \> Deleting ${CERTLIST[$i]}
${GSK7BIN} -cert -delete -db ${OUTPUTFOLDER}/${STOREROOTNAME}.kdb -stashed -label "${CERTLIST[$i]}" -fips
# step by 1
i=$[$i+1]
done
 
 
echo Generating Self-Signed RSA Certificate for hostname $HOSTNAME
echo Certificate Size: 2048
echo Certificate Signature Algorithm: SHA-512
echo Certificate Keystore: ${OUTPUTFOLDER}/${STOREROOTNAME}.kdb
echo Certificate Keystore Password: $CAPASSWORD
echo Certificate Label: ${LABEL_NAME}
 
${GSK7BIN} -cert -create -db ${OUTPUTFOLDER}/${STOREROOTNAME}.kdb -stashed -label ${LABEL_NAME} -size 2048 -dn "cn=$HOSTNAME,o=,C=" -default_cert -expire 3695 -ca true -sigalg sha512 -fips -stash
 
${GSK7BIN} -cert -list -db ${OUTPUTFOLDER}/${STOREROOTNAME}.kdb -stashed -fips
 
# display the certificate authority details
${GSK7BIN} -cert -details -db ${OUTPUTFOLDER}/${STOREROOTNAME}.kdb -stashed -label ${LABEL_NAME} -fips
 
fi