IBM Tivoli Storage Manager, Version 7.1

Configuring Tivoli Storage Manager client/server communication with Secure Sockets Layer

Secure Sockets Layer (SSL) allows industry standard SSL-based secure communications between the Tivoli® Storage Manager client and server.

The following client components support SSL:

Command-line client
Administrative command-line client
Client GUI
Client API

Only outgoing client/server connections support SSL. Incoming connections (for example, CAD, server-initiated schedule connections) do not support SSL. Client-to-client communications and web GUI do not support SSL.

Each Tivoli Storage Manager server that is enabled for SSL must have a unique certificate. The certificate can be one of the following types:

A certificate that is self-signed by Tivoli Storage Manager.
A certificate that is issued by a certificate authority (CA). The CA can be from a company such as VeriSign or Thawte, or an internal CA, maintained within your company.

Follow these steps to enable SSL communication with a self-signed certificate:

Obtain the Tivoli Storage Manager server self-signed certificate (cert256.arm) Use the cert.arm certificate file when the server is not setup to use Transport Layer Security (TLS) 1.2; otherwise, use the cert256.arm file. The client certificate file must be the same as the certificate file that the server uses.
Configure the clients. To use SSL, each client must import the self-signed server certificate.
Use the GSKit command-line utility (gsk8capicmd for 32-bit clients or gsk8capicmd_64 for 64-bit clients) to import the certificate.

Use the GSKit command-line utility, gsk8capicmd_64 to import the certificate.
For a disaster recovery of the Tivoli Storage Manager server, if the certificate has been lost, a new one is automatically generated by the server. Each client must obtain and import the new certificate.

Follow these steps to enable SSL communication with a CA-signed certificate:

Obtain the CA root certificate.
Configure the clients. To use SSL, each client must import the self-signed server certificate.
Use the GSKit command-line utility (gsk8capicmd for 32-bit clients or gsk8capicmd_64 for 64-bit clients) to import the certificate.

Use the GSKit command-line utility, gsk8capicmd_64 to import the certificate.

Tip: After you complete this step, if the server gets a new certificate that is signed by the same CA, the client does not need to import the root certificate again.
If you are recovering the Tivoli Storage Manager as part of disaster recovery, you must install the SSL certificate on the server again. If the certificate was lost, you must get a new one. You do not need to reconfigure the client if the new certificate has been signed by a CA.

The gsk8capicmd and gsk8capicmd_64 commands are provided by Global Security Kit (GSKit). Tivoli Storage Manager automatically installs GSKit in \Program Files\IBM\gsk8. However, if GSKit is installed before Tivoli Storage Manager is installed, it is possible that it is in some other location. You can obtain the GSKit location from the following registry key:

HKey_Local_Machine\SOFTWARE\IBM\gsk8\CurrentVersion\InstallPath

Before you set up the server certificate on the client, follow these steps:

Open a command window and change the directory to your Tivoli Storage Manager client directory, for example: cd "c:\Program Files\Tivoli\TSM\baclient"
Add the GSKit binary path and library path to the PATH environment variable, for example:
```
set PATH=C:\Program Files\IBM\gsk8\bin;
  C:\Program Files\IBM\gsk8\lib;%PATH%
```

If you are configuring SSL on the Tivoli Storage Manager client for the first time, you must create the client local key database, dsmcert.kdb. To create the client local key database, run the following command from the DSM_DIR directory:

   gsk8capicmd_64 -keydb -create -populate
     -db dsmcert.kdb -pw password -stash

   gsk8capicmd_64 -keydb -create -populate
     -db dsmcert.kdb -pw password -stash

After you create the local key database, you must import the server certificate, or the CA root certificate.

If you use a self-signed certificate

Each Tivoli Storage Manager server generates its own certificate. The certificate has a fixed file name of either cert.arm or cert256.arm. The certificate file is stored on the server workstation in the server instance directory, for example, /opt/tivoli/tsm/server/bin/cert256.arm. If the certificate file does not exist and you specify the SSLTCPPORT or SSLTCPADMINPORT server option, the certificate file is created when you restart the server with these options set. Tivoli Storage Manager V6.3 servers (and newer versions) generate files named cert256.arm and cert.arm. Tivoli Storage Manager servers older than V6.3 generate only certificate files named cert.arm. You must choose the certificate that is set as the default on the server.

Each Tivoli Storage Manager server generates its own certificate. The certificate has a fixed file name of either cert.arm or cert256.arm. The certificate file is stored on the server workstation in the server instance directory, for example, c:\Program Files\tivoli\tsm\server1\cert256.arm. If the certificate file does not exist and you specify the SSLTCPPORT or SSLTCPADMINPORT server option, the certificate file is created when you restart the server with these options set. Tivoli Storage Manager V6.3 servers (and newer versions) generate files named cert256.arm and cert.arm. Tivoli Storage Manager servers older than V6.3 generate only certificate files named cert.arm. You must choose the certificate that is set as the default on the server.

Follow these steps to set up the SSL connection to a server:

Obtain the certificate from the server administrator.

Import the certificate into the client key database by using the following command:

gsk8capicmd_64 -cert -add -db dsmcert.kdb -stashed 
  -label "TSM server <servername> self-signed key" 
  -file <path_to_cert256.arm> -format ascii

If you use a certificate from a certificate authority

If the certificate was issued by a certificate authority (CA) such as VeriSign or Thawte, the client is ready for SSL and you can skip the following steps.

For the list of preinstalled root certificates from external certificate authorities, see Certificate Authorities root certificates.

If the certificate was not issued by one of the well-known certificate authorities, follow these steps:

Obtain the root certificate of the signing CA.

Import the certificate into the client key database by using the following command:

gsk8capicmd_64 -cert -add -db dsmcert.kdb -stashed 
  -label "XYZ Certificate Authority" -file <path to CA root certificate> 
  -format ascii

Important:

An arbitrary password, provided by you, is used to encrypt the key database. The password is automatically stored encrypted in the stash file (dsmcert.sth). The stash file is used by the Tivoli Storage Manager client to retrieve the key database password.
More than one server certificate can be added to the client key database file so that the client can connect to different servers. Different certificates must have different labels. The label names are not important, but use meaningful names. Also, more than one CA root certificate can be added to the client key database.
If you do not run the preceding commands from the DSM_DIR directory, you must copy dsmcert.kdb and dsmcert.sth into that directory.
By default, local key database files have root ownership and permissions and cannot be read by other users. If you plan to run the Tivoli Storage Manager client as a non-root user, you must update the permissions. For example, to grant read access to all users and groups, run the following command:
```
# chmod go+r dsmcert.*
```
If you do not run the preceding commands from the Tivoli Storage Manager client directory, you must copy dsmcert.kdb and dsmcert.sth into that directory.
For performance reasons, use SSL only for sessions where it is needed. Consider adding more processor resources on the Tivoli Storage Manager server system to manage the increased requirements.
In order for a client to connect to a server that is using Transport Layer Security (TLS) Version 1.2, the certificate's signature algorithm must be SHA-1 or stronger. If you are using a self-signed certificate, you must use the cert256.arm certificate. Your Tivoli Storage Manager administrator might need to change the default certificate on the Tivoli Storage Manager server. See the SSLTLS12 server option topic for details.

After the server certificate is added to the client key database, add the ssl yes option to the client options file, and update the value of the tcpport option. It is important to understand that the server is normally set up for SSL connections on a different port. In other words, two ports are opened on the server:

One port accepts regular non-SSL client connections
Another port accepts SSL connections only

You cannot connect to a non-SSL port with an SSL-enabled client, and vice versa.

If the value of tcpport is incorrect, the client cannot connect to the server. Specify the correct port number on the tcpport option.

Feedback