IBM Support

Configuring NHttpd for SSL

Question/Answer


Question

nco_http : How do you enable SSL connectivity?

Cause

The service [server] requires an SSL certificate created from a Master CA for NHttpd.SSLEnable to work.

Answer

In order to use the SSL feature available for nco_http the server needs to be allocated a valid SSL certificate.

The default location for the keystore used by Netcool/OMNIbus is $NCHOME/etc/security/keys/omni.kdb. In order to create valid certificates a Master CA keystore needs to be created on one of the Netcool/OMNIbus installations. This can then be used to validate SSL certificates.

The following step by step instructions are also illustrated in the $NCHOME/bin/create_example_keys.sh script that is shipped with a Netcool/OMNIbus installation.

Example for creating the Master CA keystore [MASTER_CA.kdb]:

In this example we create a Master CA certificate from the keystore MASTER_CA.kdb, with a password 'netcool' using the label and common name 'MASTER_CA'. (Note: The simple password 'netcool' is not FIPS compliant. It is recommended that a stronger password is used for a production system.) The password is usually stored in a stash file which saves the effort of having to enter it every time the keystore is accessed.

Create the MASTER_CA keystore 
cd $NCHOME/etc/security/keys/
$NCHOME/bin/nc_gskcmd -keydb -create -db "$NCHOME/etc/security/keys/MASTER_CA.kdb" -pw netcool
ls -l
-rw-r--r-- MASTER_CA.rdb
-rw-r--r-- MASTER_CA.kdb

Save the password to the keystore in a stash file
$NCHOME/bin/nc_gskcmd -keydb -stashpw -db "$NCHOME/etc/security/keys/MASTER_CA.kdb" -pw netcool
ls -l
-rw-r--r-- MASTER_CA.rdb
-rw-r--r-- MASTER_CA.sth
-rw-r--r-- MASTER_CA.kdb

Create the MASTER_CA certificate
$NCHOME/bin/nc_gskcmd -cert -create -db "$NCHOME/etc/security/keys/MASTER_CA.kdb" -stashed \
-label "MASTER_CA" -size 1024 -ca true \
-dn "CN=MASTER_CA,O=IBM,OU=Support,L=SouthBank,ST=London,C=GB" \
-expire 1825 -x509version 3

List the certificates in the MASTER_CA keystore
$NCHOME/bin/nc_gskcmd -cert -list -db "$NCHOME/etc/security/keys/MASTER_CA.kdb" -pw netcool

Certificates in MASTER_CA.kdb are listed as:
MASTER_CA

Extract the MASTER_CA certificate to a file for usage
$NCHOME/bin/nc_gskcmd -cert -extract -db "$NCHOME/etc/security/keys/MASTER_CA.kdb" -stashed \
-label "MASTER_CA" \
-target "$NCHOME/etc/security/keys/MASTER_CA_CERT.arm"


Example for enabling NHttpd SSL at the Object Server:

In this example the Master CA is used to create a valid SSL certificate for the Object Server NHTTPS. The common name in the certificate should be the fully qualified domain name (FQDN) of the hostname that the ObjectServer is running on. For the certificate label we use ' NHTTPS'. The two keystores exist in the same directory for simplicity. The same password, ' netcool', is used for both.

Create a valid keystore for the Netcool/OMNIbus installation:
$NCHOME/bin/nc_gskcmd -keydb -create -db "$NCHOME/etc/security/keys/ omni.kdb" -pw netcool
$NCHOME/bin/nc_gskcmd -keydb -stashpw -db "$NCHOME/etc/security/keys/ omni.kdb" -pw netcool
ls -l
-rw-r--r-- omni.rdb
-rw-r--r-- omni.sth
-rw-r--r-- omni.kdb


Add MASTER_CA certificate to keystore
$NCHOME/bin/nc_gskcmd -cert -add -db "$NCHOME/etc/security/keys/ omni.kdb" -pw netcool \
-file "$NCHOME/etc/security/keys/ MASTER_CA_CERT.arm" -label " MASTER_CA"
$NCHOME/bin/nc_gskcmd -cert -list -db $NCHOME/etc/security/keys/ omni.kdb -stashed

Certificates found in omni.kdb are listed as:
MASTER_CA

Create the Object Server's certificate request:
$NCHOME/bin/nc_gskcmd -certreq -create -db "$NCHOME/etc/security/keys/ omni.kdb" -stashed \
-label " NHTTPS" \
-size 1024 \
-dn "CN= host.example.com,O=IBM,OU=Support,L=SouthBank,ST=London,C=GB" \
-file "$NCHOME/etc/security/keys/ NHTTPS_req.arm"

Sign the ObjectServer certificate in the Master CA keystore with the Master CA certificate:
$NCHOME/bin/nc_gskcmd -cert -sign -db "$NCHOME/etc/security/keys/ MASTER_CA.kdb" -stashed  \
-label " MASTER_CA" \
-file "$NCHOME/etc/security/keys/ NHTTPS_req.arm" \
-expire 1825 \
-target "$NCHOME/etc/security/keys/ NHTTPS_signed.arm"

Receive the signed certificate back in omni.kdb:
$NCHOME/bin/nc_gskcmd -cert -receive -db "$NCHOME/etc/security/keys/ omni.kdb" -stashed  \
-file "$NCHOME/etc/security/keys/ NHTTPS_signed.arm"

Check the contents of the keystore:
$NCHOME/bin/nc_gskcmd -cert -list -db $NCHOME/etc/security/keys/omni.kdb -stashed
$NCHOME/bin/nc_gskcmd -certreq -list -db $NCHOME/etc/security/keys/omni.kdb -stashed

Cleanup intermediate files
At this point we can get rid of all the intermediate *.arm files that were created in the steps above.

Update the NHTTP Object Server's property file with the SSL certificates label and keystore password, and check the other settings are correct:
#$NCHOME/etc/security/keys/README.txt
NHttpd.SSLCertificate: ' NHTTPS'
NHttpd.SSLCertificatePwd: ' netcool'  # This property was deprecated in 8.1 fixpack 15

NRestOS.Enable: TRUE
NRestOS.OSLCRDFMsgFormat: 'STANDARD'
NHttpd.ListeningHostname: ' <IP OR FQDN>'
NHttpd.AuthenticationDomain: 'omnibus'

NHttpd.DocumentRoot: '$OMNIHOME/etc/restos/docroot'
NHttpd.EnableFileServing: FALSE

NHttpd.EnableHTTP: TRUE
NHttpd.ListeningPort: 8080

NHttpd.SSLEnable: TRUE
NHttpd.SSLListeningPort: 9090

NHttpd.ExpireTimeout: 15
NHttpd.NumWorkThreads: 5

Enable SSL for the nco_http command:
vi nco_http.props
# ENABLE HTTPS
NHttpd.SSLEnable: TRUE
NHttpd.SSLCertificatePwd: ' netcool' # This property was deprecated in 8.1 fixpack 15
#EOF

(Re)start the NHTTP Object Server and test the connection:
nco_http -username root -password '' -uri https : / / <IP OR FQDN> : 9090 / objectserver / sysinfo

Tip: The ObjectServer must always be restarted after the certificate is created or changed.

Example for enabling NHttpd SSL at the Probe:

In this example the probe common name and label are 'ProbeServer001' and is created on the same installation as the Object Server example.

Create the certificate:
Note: The CN must be a fully qualified domain name (fqdn)
$NCHOME/bin/nc_gskcmd -certreq -create -db "$NCHOME/etc/security/keys/ omni.kdb" -pw netcool \
-label " ProbeServer001" \
-size 1024 \
-dn "CN= host.example.com,O=IBM,OU=Support,L=SouthBank,ST=London,C=GB" \
-file "$NCHOME/etc/security/keys/ ProbeServer001_req.arm"

Sign the certificate:
$NCHOME/bin/nc_gskcmd -cert -sign -db "$NCHOME/etc/security/keys/ MASTER_CA.kdb" -pw netcool \
-label " MASTER_CA" \
-target "$NCHOME/etc/security/keys/ ProbeServer001_signed.arm" \
-expire 1825 \
-file "$NCHOME/etc/security/keys/ ProbeServer001_req.arm"

Receive the signed certificate:
$NCHOME/bin/nc_gskcmd -cert -receive -db "$NCHOME/etc/security/keys/ omni.kdb" -pw netcool \
-file "$NCHOME/etc/security/keys/ ProbeServer001_signed.arm"

Check the contents of the keystore:
$NCHOME/bin/nc_gskcmd -cert -list -db $NCHOME/etc/security/keys/ omni.kdb -stashed
$NCHOME/bin/nc_gskcmd -certreq -list -db $NCHOME/etc/security/keys/ omni.kdb -stashed


Example Probe properties:

NHttpd.AccessLog : '$OMNIHOME/log/ ProbeServer001_access.log'
NHttpd.AuthenticationDomain : 'omnibus'
NHttpd.ListeningHostname : ' <IP OR FQDN>'
NHttpd.EnableHTTP : TRUE
NHttpd.ListeningPort : 8081
NHttpd.SSLEnable : TRUE
NHttpd.SSLListeningPort : 9091
NHttpd.SSLCertificate : ' ProbeServer001'
NHttpd.SSLCertificatePwd : ' netcool' # Deprecated in OMNIbus 8.1 fixpack 15
#EOF

Start the probe and then test the connectivity using nco_http :
The nco_http.props is already enabled for HTTPS, see the earlier example.

nco_http -uri [https] : / / <IP OR FQDN> : 9091 / probe / common

*(omit the '[ ]' in your usage)

Document information

More support for: Tivoli Netcool/OMNIbus

Component: Not Applicable

Software version: 8.1.0

Operating system(s): AIX, HP-UX, Linux, Solaris

Reference #: 1669288

Modified date: 03 May 2019