Using the nc_httpcertimport utility

You use the nc_httpcertimport utility to make it easier to load a certificate from an HTTP server when configuring the Gateway for Message Bus to connect to IBM Operations Analytics - Log Analysis through Secure Socket Layer (SSL). This topic provides reference information related to the nc_httpcertimport utility.

NAME

nc_httpcertimport - Loads a certificate from an HTTP server

COMMAND LINE SYNTAX

nc_httpcertimport [-k keystore_file] -h host_URL
                  [-p password] [-a certificate_alias]
                  [-l] [-x] [-v] [-?]

nc_httpcertimport [--keystore keystore_file] --host host_URL
                  [--password password] [--alias certificate_alias]
                  [--list] [--accept] [--version] [--help]

OPTIONS

Option Description

-k keystore_file

--keystore keystore_file

The -k and --keystore options specify the name of the keystore file to create (if no keystore file exists) or the name of an existing keystore file in which to add certificates. The keystore file you specify for keystore_file should include the path. For example:

--keystore $OMNIHOME/java/security/
cacerts.jks

-h host_URL

--host host_URL

The -h and --host options specify the Uniform Resource Identifier (URI) of the server running the application from which to import the certificate. You must specify a port number in the URI specification. For example:

-h https://testserver1.xyzcompany.com:
9987/Unity
Note: The URI you specify should be an HTTPS URI. By default, IBM Operations Analytics - Log Analysis uses the port 9987. Note also that the URI includes the name of the application from which to import the certificate, which in the example is Unity.

-p password

--password password

The -p and --password options specify the password of the truststore file that you create using the Java keytool utility. The password of the truststore file is optional on the command line. If you do not specify a password on the command line, the nc_httpcertimport utility displays a prompt for the password.

One reason you might not want to specify the password of the truststore file on the command line is because the nc_httpcertimport utility echoes it on the display terminal screen. However, when prompted for the password, the nc_httpcertimport utility does not echo it on the display terminal screen.

Note: If you are creating a new trustore file, the nc_httpcertimport utility prompts you twice for the password. The password will not echo onto the display terminal screen.

-a certificate_alias

--alias certificate_alias

The -a and --alias options specify the alias to associate with the certificate to be added to the keystore file specified in keystore_file. For example:

--alias scala-host

-l

--list

The -l and --list options display a list of all the certificates returned by the server application specified in host_URL.

-x

--accept

The -x and --accept options accept the first server certificate from the server application specified in host_URL without prompting and adds the certificate to the keystore file specified in keystore_file. If the server application returns more than one certificate, the nc_httpcertimport utility accepts only the first certificate.

-v

--version

The -v and --version options display version information for the nc_httpcertimport utility.

-?

--help

The -? and --help options display usage information for the nc_httpcertimport utility. This usage information includes descriptions of the valid syntax for the command line options.

DESCRIPTION

The nc_httpcertimport utility loads an SSL certificate from an HTTP server and either adds it to an existing keystore file, or creates a new keystore file to which it adds the certificate. Using this utility allows you to avoid having to manually extract the SSL certificate from a web browser and to use the Java tooling to add it to a truststore file. The nc_httpcertimport utility is interactive by default and requires users to accept SSL certificates. To run the nc_httpcertimport utility with no user interaction, specify the -p (or --password) and -x (or --accept) options.

Note: The nc_httpcertimport utility generates a file to store SSL certificates. These SSL certificates can be used as a keystore file or a truststore file.

NOTES

The nc_httpcertimport utility is supported only on UNIX platforms supported by the gateway. The nc_httpcertimport utility is not supported on Windows operating systems.

EXAMPLE

$OMNIHOME/bin/nc_httpcertimport -k $OMNIHOME/java/security/cacerts.jks
-p password 
-h http://testserver1.xyzcompany.com:7789/unity
--alias scala-host

ERROR MESSAGES

The following table describes the possible error messages that the nc_httpcertimport utility can generate.

Error Message Description and Action 
Command line option option
is not recognized.

You specified an invalid command line option.

To resolve the issue, specify a valid command line option. The valid command options are described in OPTIONS. You can also specify the -? or --help option to display usage information for the nc_httpcertimport utility.

 
The certificate number that you
specified is invalid.

You were running the nc_httpcertimport utility in interactive mode and the utility requested that you enter the number of a SSL certificate you trust and want to add to the keystore file. However, the SSL certificate number you specified is invalid.

To resolve the issue, enter a valid number of a SSL certificate you trust and want to add to the keystore file. Or, you can specify q to quit the nc_httpcertimport utility.

 
Failed to access the system console.
Not able to run in interactive mode.
Specify the --help option for details
on how to run the utility in
non-interactive mode.

The nc_httpcertimport utility was unable to access the system console. The most likely reason is that you attempted to run nc_httpcertimport without user interaction (non-interactive mode) and specified invalid options.

To run the nc_httpcertimport utility without user interaction (non-interactive mode), specify the -p (or --password) and -x (or --accept) options.

You can also specify the -? or --help option to display usage information for the nc_httpcertimport utility.

 
You specified an http URI for the host.
An https URI is required.

You specified either the -h or --host option and followed it with the URI of the server application from which to import the SSL certificate. However, the URI you specified started with http://.

To resolve the issue, the URI you specify should be an HTTPS URI. Thus, the URI should start with https://.

 
The required keystore file keystore_file
was not found. Verify that the install
is not corrupted.

You specified either the -k or --keystore option and followed it with the path and name of the required keystore file. However, the nc_httpcertimport utility was unable to find the specified keystore file.

To resolve the issue ensure that the keystore file that you specify with the -k or --keystore option exists.

 
Failed to connect to the host due to IO
exception. exception

The nc_httpcertimport utility called an internal method to create an SSL socket connection. This error indicates that the attempt to create the SSL socket connection to the host specified in host_URL failed because the server is not running, a firewall is in the way, or you incorrectly specified the URI in the host_URL. The I/O exception specified in exception generally provides information about the specific reason for the failure to connect to the server.

To resolve the issue, use the information in exception to identify the specific cause of the error.

 
Failed to open keystore file due to IO
exception exception

The nc_httpcertimport utility called an internal method to open the keystore file that you specified with the -k or --keystore option. However, the internal method failed to open the specified keystore file due to the I/O exception specified in exception.

One reason this error can occur is that you are running the nc_httpcertimport utility against an existing keystore file and the user ID that the utility is running under does not have access to the keystore file. Another possible reason for this error to occur is that you are creating a new keystore file and the nc_httpcertimport utility does not have access to the directory where the keystore file resides.

To resolve the issue, use the information in exception to identify the specific cause of the error.

 
The --list and --accept parameters
cannot be specified at the same time.

You invoked the nc_httpcertimport utility with the --list and --accept (or -l and -x) options. This is an invalid combination of options because the --list and -l options display a list of all the SSL certificates returned by the server application specified in host_URL. The --accept and -x options accept the first server certificate from the server application specified in host_URL without prompting and instruct nc_httpcertimport to add the SSL certificate to the keystore file specified in keystore_file.

To resolve the issue, specify either the option to display a list of all the certificates or the option to accept the first server certificate.

 
Argument arg_name requires a value.
Please use the --help option to check
the valid syntax of the command line
arguments. There is a missing value.

You invoked the nc_httpcertimport utility with the command line option arg_name. The arg_name command line option requires that you specify a valid value.

Or, you invoked the nc_httpcertimport utility with the command line option arg_name and specified a value that starts with -. Command line option values cannot start with a -.

To resolve the issue, use the -? or --help option to check the valid syntax of the command line options. You can also review the command line option descriptions in OPTIONS. Also, ensure that you do not specify values with -.

 
This utility requires that you set the
the NCHOME environment variable.

The nc_httpcertimport utility was performing operations on the keystore file that you specified with the -k or --keystore option. However, nc_httpcertimport determined that the NCHOME environment variable was not set.

To correct the issue, set the NCHOME environment variable.

 
Internal error retrieving the server
certificate chain.

The nc_httpcertimport utility called an internal method to obtain the trust manager chain from the Java Secure Socket Extension (JSSE) trust manager. This error indicates that the internal method discovered that the trust manager chain is null and therefore the currently running Java virtual machine (JVM) was terminated.

If this error occurs contact IBM technical support.

 
Unable to find a default X509 trust
manager for the JVM.

The nc_httpcertimport utility called an internal method to obtain an instance of a default X509 trust manager from the current keystore file. (X509 trust managers manage X509 certificates.) This error indicates that the internal method was unable to find a default X509 trust manager for the currently running Java virtual machine (JVM). As a result, the internal method creates an X509 trust manager.

Typically, this error would only occur if your environment has an issue with the JVM. The gateway should be picking up the X509 trust manager that delivers with it.

If this error occurs contact IBM technical support.

 
This utility requires you specify the
URI of the server running the
application from which you want to add
certificates.

You invoked the nc_httpcertimport utility with the -h or --host option, but did not supply a URI to the host_URL argument.

To resolve the issue, you must specify the URI of the server running the application from which to import the SSL certificate. You can also specify the -? or --help option to check the valid syntax of the -h or --host options or see OPTIONS for additional information.

 
Specify either a keystore filename or
a list of all certificates returned by
the server.

You invoked the nc_httpcertimport utility without specifying one of the following command line options:

  • -l or --list - To display a list of all the certificates returned by the server application specified in host_URL.
  • -k or --keystore keystore_file - To specify the specify the name of the keystore file

To resolve the issue, you need to specify one of the previously described options.

You can also use the -? or --help option to check the valid syntax of the command line options. You can also review the command line option description for the previously described options in OPTIONS.

 
The passwords that you specified do
not match.

You invoked the nc_httpcertimport utility without specifying the -p or --password options. Thus, the nc_httpcertimport utility requests that you enter and then reenter the password for the truststore file. In this case, the passwords that you specified do not match.

To resolve the issue, invoke the nc_httpcertimport utility without specifying the -p or --password options. Then make sure you specify identical passwords to the password prompts that the nc_httpcertimport utility displays.

 
The host server URI does not contain
a port number.

You invoked the nc_httpcertimport utility with the -h or --host option and specified a URI for the host_URL argument. However, the URI you specified did not contain a port number for the server application from which to import the SSL certificate.

To resolve the issue, invoke the nc_httpcertimport utility with the -h or --host option and this time specify a URI that contains a port number.

You can also use the -? or --help option to check the valid syntax of the command line options. You can also review the command line option description for the previously described options in OPTIONS.

 
The SSL connection to the host failed
with an SSLException exception.

The nc_httpcertimport utility called an internal method to create an SSL socket connection. This error indicates that the attempt to create the SSL socket connection to the host specified in host_URL failed because of the reason specified in exception.

This error indicates that the attempt to create the SSL socket connection to the host specified in host_URL failed because the server is not running, a firewall is in the way, or you incorrectly specified the URI in the host_URL. The SSL exception specified in exception generally provides information about the specific reason for the failure to connect to the server.

To resolve the issue, use the information in exception to identify the specific cause of the error.

 
The SSL Handshake failed with the
following error error.

The nc_httpcertimport utility called an internal method to create an SSL socket. This error indicates that the SSL handshake operation failed because of the reason specified in error.

This error indicates that the attempt to create the SSL socket connection to the host specified in host_URL failed because the server is not running, a firewall is in the way, or you incorrectly specified the URI in the host_URL. The error specified in error generally provides information about the specific reason for the failure to connect to the server.

To resolve the issue, use the information in error to identify the specific cause of the error.

 
The SSL Handshake failed with the
following error error.
Verify that the keystore file
contains certificates.

The nc_httpcertimport utility called an internal method to create an SSL socket. This error indicates that the SSL handshake operation failed because of the reason specified in error.

To resolve the issue, ensure that the keystore file that you specified with the -k or --keystore option contains one or more valid SSL certificates. Also, use the information in error to identify the specific cause of the error.

 
Error unable to parse URI: uri.

You invoked the nc_httpcertimport utility with the -h or --host option and specified a host_URL. When the nc_httpcertimport utility attempts to create an SSL certificate import instance it checks the specified host_URL. In this case, nc_httpcertimport could not parse the host_URL you specified.

To resolve the issue, enter a valid host_URL. Use the -? or --help option to check the valid syntax of the command line options. You can also review the command line option description for the -h and --host options in OPTIONS.

 
Error error reading user response from
the standard input.

You were running the nc_httpcertimport utility in interactive mode and the utility requested that you enter the number of an SSL certificate you trust and want to add to the keystore file. However, the nc_httpcertimport utility detected an error in reading the SSL certificate you specified.

To resolve the issue, enter a valid number of an SSL certificate you trust and want to add to the keystore file. Or, you can specify q to quit the nc_httpcertimport utility.