ITM Certificate Authentication Configuration Guide for ITM 6.2.2 and newer releases

This page has not been liked. Updated 4/25/13, 11:30 AM by NikolaVoukTags: None

 

 

ITM Certificate Authentication

Configuration Guide for ITM 6.2.2 and ITM 6.2.3

 

Version 3.0

 

Note: See the attachment for detailed examples and pictures associated with this text.

 

Download Attachment for Pictures and Examples

 

 

Introduction

 

 

 

ITM 6.2.2 supports the optional configuration of client and server certificate validation to allow customers the ability to restrict the set of clients that may connect to the Warehouse Proxy Agent, TEMS, TEMS soap interface or the service console on any ITM component. The most common scenario is described below:

 

The customer would like to use custom certificates and signing certificates as a way of restricting access based on issuing a limited set of certificates.

 

Authentication is achieved through the verification that the digital signature on the presented certificate was signed by a trusted certificate authority. There is no further authentication of the certificate contents or extensions.

 

There are two independent modes of certificate validation that may be enabled: Server Certificate Authentication and Client Certificate Authentication. They each have an implication on the certificates required for access.

 

Certificate authentication requires the use of a custom root or intermediate certificate authority to create public key certificates for each TEMS, TEPS and Agent (TEMA). The limited distribution of certificates acts as a means of restricting which nodes have authority to connect to the managed system. This technique has its limitations as any Certificate signed by the root authority would be accepted without question. On the other hand, any certificate not signed by the certificate authority would not be accepted. Careful control of what signing certificates are present on all hosts is required.

 

Table 1 ITM Connections

 

Client

Server

Certificate Authentication Capable

ITM Agent (TEMA)

IP.SPIPE HUB or Remote TEMS (3660)

YES

IP.SPIPE HUB or Remote TEMS (3660)

IP.SPIPE HUB or Remote TEMS (3660)

YES

IP.SPIPE HUB TEMS (3660)

IP.SPIPE Hot Standby HUB TEMS

YES

TEMA

IP.SPIPE Warehouse Proxy Agent (WPA – 3660)

YES

TEMS

IP.SPIPE Warehouse Proxy Agent (WPA - 3660)

YES

Browser

HTTPS Service Console (TEMS, Agents, TEPS, WPA, etc) (3661 + x*1920)

YES

Browser

HTTPS TEMS SOAP Server (3661)

YES

TEP Server

IP.SPIPE TEMS (3660)

YES

Browser

HTTPS Service Index (3661)

YES

TEP Client

TEP Server

NO

TEP Browser Java Client

TEP Server eWAS Management Console

NO

TEP Desktop Java Client

TEP Server eWAS Management Console

NO

TEP Desktop Java Client

TEP Server eWAS Management Console

NO

TEP Server

Customer Information Control System Connector Endpoints (CICS)

NO

TEMS Server

TEC Server (EIF)

NO

TEMS Server

Omnibus (EIF)

NO

TIP Server

TEP Server

NO

TEP Server

LDAP Server

NO

TEMS Server

LDAP Server

NO

TEP Server

DB2/Oracle/MSSQL TEPS DB and Warehouse DB

NO

TEMA

SMNP Server

NO

FIPS 140-2 Mode Component

FIPS 140-2 Mode Component

YES

Non-FIPS 140-2 Component

FIPS 140-2 Mode Component

YES

Non-FIPS 140-2 Component

Non-FIPS 140-2 Component

YES

Firewall Gateway Agent Reverse-Proxy Server

Firewall Gateway Agent (behind Firewall)

YES

 

 

Table 1 enumerates the set of connections between ITM components and whether the server and the client have the option to enable symmetric certificate authentication. The components that do not have symmetric certificate authentication use a username and password to authenticate themselves to the remote component (e.g.: TEP Server).

 

Enabling certificate validation requires creating certificate databases for each agent installation and configuring their respective configuration files. It is best to pre-create the certificates and distribute them through manual certificate distribution or your own PKI solution.

 

z/OS Omegamon users use z/OS SystemSSL/TLS and ICSF to implement TLS and encryption, respectively. z/OS users may control certificate authentication through the system configuration facilities provided by z/OS for SystemSSL/TLS and ICSF.

 

Client Validates Server Certificate Configuration

 

Server certificate authentication enables the client to be assured that the server it is communicating with is trusted by the certificate authority and by extension trusted by the client.

 

Enabling server certificate authentication means that any connection any ITM component opens to a server, ITM or otherwise, would require the server to present a valid signed certificate or the connection will not complete.

 

Set the following settings in order to enable server certificate authentication:

 

Configuration File

Setting

ITM product specific INI/ENV/custom environment file

ITM_AUTHENTICATE_SERVER_CERTIFICATE=Y

 

 



 

Server Validates Client Certificate Configuration

 

Configuration File

Setting

ITM product specific INI file or ENV file

ITM_AUTHENTICATE_CLIENT_CERTIFICATE=Y

 

 

 

Certificate Files

 

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

 

Platform

Directory

Windows

$ITMHOME\keyfiles

Unix/Linux

$ITMHOME/keyfiles

 

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.

 

Limitations (OCSP/CRL)

 

Before addressing how to create certificates, it’s important to understand what the current implementation of ITM does not support.

 

  1. No Certificate Revocation List (CRL) support

Certificate Revocation Lists, whether through HTTP, LDAP or local file are currently not enabled.

  1. No Online Certificate Status Protocol (OCSP) support

OCSP responders are currently not supported. There is no mechanism to check for a revoked

  1. No verification of the Certificate fields or Extensions

 

The net result is that certificates are used to generate session keys through TLS but only the signatures are verified to have been signed by one of the trusted certificate authorities in the local key database file.

 

Creating Certificates

 

 

 

 

 

 

 

Create a Custom Root Certificate Authority

 

The easiest tool to generate your certificates is to us the gsk7ikm/gsk7ikm_64 graphical utility to generate the certificate authority.

 

# Create Certificate Authorities

# 0. Create a random password for the database for best security

# We recommend using random to generate a random password

# The password will be saved as part of the stash file for the keystore.

# You may adjust the length as needed. The escaped version is useful so the shell

# doesn't balk at shell-specific characters when used as a parameter

gsk7capicmd -random -create -length 32 -strong -fips > CApassword.txt

cat CApassword.txt | perl -pi -e "s/([()\\ \~\?\;|&\!<>\`\'\*\"\\$])/\\\\\1/g" > CAescapedPassword.txt

export CAPASSWORD=`cat escapedPassword.txt`



 

# 1. Make the ITM Certificate Authority



 

gsk7capicmd -keydb -create -db ITMRoot.kdb -pw $CAPASSWORD -expire 3650 -fips



 

# 2. Clean out the trusted CA certificates



 

gsk7capicmd -cert -list -db ./ITMRoot.kdb -pw $CAPASSWORD -fips



 

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Thawte Personal Premium CA" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Thawte Personal Freemail CA" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Thawte Personal Basic CA" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Thawte Premium Server CA" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Thawte Server CA" -fips



 

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 3 Secure Server CA" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign International Server CA - Class 3" -fips

-fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 4 Public Primary Certification Authority - G3" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 3 Public Primary Certification Authority - G3" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 2 Public Primary Certification Authority - G3" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 1 Public Primary Certification Authority - G3" -fips

-fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 4 Public Primary Certification Authority - G2" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 3 Public Primary Certification Authority - G2" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 2 Public Primary Certification Authority - G2" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 1 Public Primary Certification Authority - G2" -fips

-fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 3 Public Primary Certification Authority" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 2 Public Primary Certification Authority" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "VeriSign Class 1 Public Primary Certification Authority" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Entrust.net Global Secure Server Certification Authority" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Entrust.net Global Client Certification Authority" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Entrust.net Client Certification Authority" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Entrust.net Certification Authority (2048)" -fips

gsk7capicmd -cert -delete -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Entrust.net Secure Server Certification Authority" -fips



 

# 3. Create the Root CA for ITM. The details of the parameters may be changed to suit the environment



 

gsk7capicmd -cert -create -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Tivoli ITM Certificate Authority" -size 2048 -dn "cn=itmca.raleigh.ibm.com,o=IBM,OU=ITM,L=Durham,ST=NC,C=USA" -default_cert yes -expire 3695 -ca true -sigalg sha512 -fips



 

# display the certificate authority details

gsk7capicmd -cert -details -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Tivoli ITM Certificate Authority" -fips



 

# 4 Make the CA Cert the default

gsk7capicmd -cert -setdefault -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Tivoli ITM Certificate Authority" -fips



 

gsk7capicmd -cert -list -db ./ITMRoot.kdb -pw $CAPASSWORD -fips



 

# 5. Export the CA Certificate so the consumers may import it for validation



 

gsk7capicmd -cert -extract -target ITMRoot.arm -db ./ITMRoot.kdb -pw $CAPASSWORD -label "Tivoli ITM Certificate Authority" -fips

 

 

Create a new certificate for each TEPS/TEMS/Agent

 

Each ITM component will need to have a new certificate created for it.

 

# Create a certificate keystore for each ITM agent, TEMS, TEPS

# the agent for this example is ITMAgent1



 

# 1. We recommend using random to generate a random password

# for each Agent. The password will be saved as part of

# the stash file for each new keystore.

# you may adjust the length as needed. The escaped version is useful so the shell

# doesn't balk at shell-specific characters when used as a parameter

gsk7capicmd -random -create -length 32 -strong -fips > password.txt

cat password.txt | perl -pi -e "s/([()\\ \~\?\;|&\!<>\`\'\*\"\\$])/\\\\\1/g" > escapedPassword.txt

export PASSWORD=`cat escapedPassword.txt`



 

# 2. Create the agent's key database

gsk7capicmd -keydb -create -db ./ITMAgent1.kdb -pw $PASSWORD -expire 365 -fips -stash



 

# 6. up the old CAs



 

gsk7capicmd -cert -list -db ./ITMAgent1.kdb -pw $PASSWORD -fips



 

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "Thawte Personal Premium CA" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "Thawte Personal Freemail CA" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "Thawte Personal Basic CA" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "Thawte Premium Server CA" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "Thawte Server CA" -fips



 

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 3 Secure Server CA" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign International Server CA - Class 3" -fips

-fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 4 Public Primary Certification Authority - G3" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 3 Public Primary Certification Authority - G3" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 2 Public Primary Certification Authority - G3" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 1 Public Primary Certification Authority - G3" -fips

-fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 4 Public Primary Certification Authority - G2" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 3 Public Primary Certification Authority - G2" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 2 Public Primary Certification Authority - G2" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 1 Public Primary Certification Authority - G2" -fips

-fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 3 Public Primary Certification Authority" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 2 Public Primary Certification Authority" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "VeriSign Class 1 Public Primary Certification Authority" -fips



 

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "Entrust.net Global Secure Server Certification Authority" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "Entrust.net Global Client Certification Authority" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "Entrust.net Client Certification Authority" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "Entrust.net Certification Authority (2048)" -fips

gsk7capicmd -cert -delete -db ./ITMAgent1.kdb -pw $PASSWORD -label "Entrust.net Secure Server Certification Authority" -fips



 

gsk7capicmd -cert -list -db ./ITMAgent1.kdb -pw $PASSWORD -fips



 



 

# 7. Create a new certificate request for this agent to be signed by the CA



 



 

gsk7capicmd -certreq -create -db ./ITMAgent1.kdb -pw $PASSWORD -label "IBM_Tivoli_Monitoring_Certificate" -size 2048 -file ITMAgent1Req.arm -dn "CN=tameaix5.tivlab.raleigh.ibm.com,OU=tameaix5:KUX,O=IBM,L=RTP,ST=NC,C=US" -fips



 



 

# 8. Send the certificate to the CA to be signed



 

gsk7capicmd -cert -sign -db ITMRoot.kdb -pw $CAPASSWORD -expiry 365 -label "Tivoli ITM Certificate Authority" -file ITMAgent1Req.arm -target ./ITMAgent1Signed.arm



 

# 9. Import the CA Cert into the agent's key database so the signer is recognized when the agent cert is imported



 

gsk7capicmd -cert -add -file ./ITMRoot.arm -trust enable -label "Tivoli ITM Certificate Authority" -db ./ITMAgent1.kdb -pw $PASSWORD -fips



 

# 10. Receive the now signed certificate



 

gsk7capicmd -cert -receive -file ./ITMAgent1Signed.arm -db ./ITMAgent1.kdb -pw $PASSWORD -fips



 

# make the new imported signed certificate the default certificate in the database using the

# established ITM key name

gsk7capicmd -cert -setdefault -db ./ITMAgent1.kdb -pw $PASSWORD -label "IBM_Tivoli_Monitoring_Certificate" -fips

 

Repeat this exercise for every agent. It should be fairly easy to automate this process through scripting.

 

 

Creating a Java JKS keystore

 

For java clients, the JKS (Java Key Store) format is used. Use the gsk7ikm (Gskit iKey Manager) utility to generate the agent JKS keystores, though there isn't a way to automate gsk7ikm from the CLI. gsk7ikm is provided in the ITM installation on Windows and Linux/UNIX platforms.

 

 

Some common consumers of JKS keystores are WebSphere and Omnibus.

 

 

 

 

 

 

 

 

# 1. Create the new Key store using gsk7ikm. It is located in all ITM installations.

 

 

 

 

2. Remove the Default Signer Certificates.

 

 

 

 

# 3. Create a new certificate request that will be signed by your certificate authority.

 

 

 

 

# 4. Import the CA Certificate inot the key database so the signer is recognized when the agent certificate is imported.

 

 

 

 

 

 

# Set the Label to:



# "Tivoli Omnibus Certificate Authority" - This value may be changed appropriately for the organization.



 

 



 

# 9. Sign the certificate request with the Omnibus CA



 

gsk7capicmd -cert -sign -db OmniBusCA.kdb -pw $OMCAPASSWORD -expiry 365 -label "Tivoli Omnibus Certificate Authority" -file OmniBusServer1Req.arm -target ./OmniBusServer1Signed.arm



 

# 10. Receive the now signed certificate

 



 

 

 

 

 

 

Replace existing Key store

 

Each new key store created with the preceding steps must be placed into the keyfiles directory of each new agent.

 

 

 

 

mv ITMAgent1.kdb keyfiles.kdb

mv ITMAgent1.rdb keyfiles.rdb

mv ITMAgent1.crl keyfiles.crl

mv ITMAgent1.sth keyfiles.sth

 

Replace the files on the target system in the keyfiles subdirectory of the ITM home directory.

 

 

 

 

On UNIX/Linux platforms, the names are also the same.

 

 

 

 

Cross-Certifying two authorities for a single keystore

 

 

 

 

 

 

There are cases where a particular end-point may need to trust multiple Certificate authorities so that it may communicate securely across different products. Cross-certifying should be limited to only those systems which truly need cross-product communiction as too wide of a distribution breaks the chain of trust and possibly allowing untrusted programs to communicate with your trusted network.

 

 

 

 

 

 

  1. Create two independent certificate authorities following the steps above

  2. Create two sets of independent agents from each respective certificate authority.

 

 

For a two components to trust each other, the signing authority public key of each respective component's certificate authority must be in each other's certificate store.

 

# 1. import the CA cert of the ITM Root CA into the Omnibus agent jks through gsk7ikm

 

# Now the Omnibus Server1 trusts the Tivoli ITM Certificate Authority in addition to its own Omnibus Authority.



 

 



 

# 2. import the CA cert of the Ombinus Root CA into the OmnibusAgent1 CMS keystore



 

gsk7capicmd -cert -add -file ./OmniBusCA.arm -trust enable -label "Tivoli OmniBus Certificate Authority" -db ./ITMAgent1.kdb -pw RANDOMPWD -fips



 

gsk7capicmd -cert -list -db ./ITMAgent1.kdb -pw RANDOMPWD -fips



 

# now the ITM agent and the Omnibus server will validate (assuming authentication is enabled) each other's certificate and the connection will complete.

 

 

Automation:



 

The steps outlined above would be tedious to perform for large deployments or even modest small deployments.

 

The steps are easily automatable.

 

Each of the steps above are already in a format that is shell script compatible, so they can easily be copied and pasted into a script for CA creation, and one for agent creation.

 

In ITM, the easy way to deploy agent key stores is through the putfile facility in 6.2.2 and 6.2.3.

 

 

 

 

Again, scripting this by querying the available systems, generating the

 

 

References

 

The following documents provide excellent reference on certificate management and policy with GS Kit.

 

“GSKCapiCmd User’s Guide: GSKit Version 7”, March 12th, 2007

ftp://ftp.software.ibm.com/software/webserver/appserv/library/v61/ihs/GSK7c_CapiCmd_UserGuide.pdf

 

“IBM Global Security Kit Secure Sockets Layer Introduction and iKeyMan User’s Guide”

ftp://ftp.software.ibm.com/software/webserver/appserv/library/v61/ihs/GSK7c_SSL/TLS_Ikm_Guide.pdf

Errors

 

Improper configuration may cause several errors. The following may help to resolve common configuration issues.

 

GSK_ERROR_BAD_CERT

This error may occur if a certificate authority public certificate is missing from the certificate database of the TEPS, TEMS or TEMA. Ensure the signing authority’s public key is installed in the certificate database for each component and a proper certificate is issued by the client or server issuing the certificate.

 



 

GSK_ERROR_BAD_KEYFILE_PASSWORD

 

On Windows, the keyfiles.kdb file and associated stash file may have been created without inheriting the permissions from the parent directory. Adjust the permissions of the files to allow for the user-id necessary to read and/or write.