How to Migrate SSL Keys and Certificates

CA SiteMinder® Federation Standalone Guide › SSL Administration for Federation System › How to Migrate SSL Keys and Certificates

How to Migrate SSL Keys and Certificates

For CA SiteMinder® Federation Standalone 12.52 SP1, the SSL key and certificate files for the embedded Apache and Tomcat servers are encrypted. For releases 12.0 and 12.0 SP1, these files are not encrypted. To avoid purchasing a new key/certificate pair for an encrypted file, migrate existing key or certificate files from r12.0/r12.0 SP1 to 12.52 SP1. You can also export these files for backup purposes without migrating them.

Important! For federation systems before r12.1, the embedded Tomcat server uses a self-signed certificate. You cannot use this self-signed certificate for a migration to 12.52 SP1. Purchase a signed certificate and upgrade the Tomcat SSL configuration with the signed certificate.

For Apache, you can migrate files for the SSL connections beginning at r12.0. For Tomcat, you can migrate files only from r12.1 forward because at release12.0, a self-signed certificate secured the Tomcat key store. Beginning with r12.1, the federation system requires that a Certificate Authority signs the certificate.

Migrating SSL keys and certificate files is useful in the following situations:

To move to a different version of CA SiteMinder® Federation Standalone on a new system instead of upgrading an existing system. Migrate the SSL keys or certificates from the existing system to the new system.
To migrate SSL keys and certificates from one system in a cluster to another. Migrating lets you reuse the keys and certificates. For example, if a load balancer passes SSL requests to the federation systems in a cluster, each system must use the same keys and certificates. Therefore, you would migrate keys and certificates from one system to the other.

Note: If you upgrade a federation 12.0 system to 12.52 SP1, the installer automatically upgrades Apache and Tomcat SSL key and certificate files to encrypted files. This automatic does not apply to migrations.

The certificate and private key files are as follows:

Apache

The server.key file contains a private key.
The server.cert file contains a server certificate.

Tomcat

For r12.0, the tomcat.keystore file contains a self-signed certificate. For r12.1x, the tomcat.keystore file contains a CA-signed certificate and private key pair.

To migrate or export these files, use the CA SiteMinder® Federation Standalone SSL utility named migratessl. The migration utility is included with the product as a batch file for Windows systems and a shell script for UNIX systems. The utility is installed in the federation_install_dir/bin folder.

The process to migrate SSL files is as follows:

Copy the key and certificate files from the existing r12 federation system to any location on the 12.52 SP1 federation system.
Copy the migratessl tool to the location where you copied the key and certificate files.
If you migrate signed certificates, export the Certificate Authority certificate that signed the SSL certificate. Before you continue with the migration, import the CA certificate.

Copy Key and Certificate Files from the r12 System

To use the SSL migration tool, first gather the key and certificate files for the CA SiteMinder® Federation Standalone system from which you plan to migrate or export then copy them.

To copy the SSL key and certificate files

Locate the files on the existing CA SiteMinder® Federation Standalone system.
The Apache SSL key and certificate files are in the following locations:
- federation_install_dir/secure-proxy/SSL/keys/server.key
- federation_install_dir/secure-proxy/SSL/certs/server.crt
The Tomcat SSL key store file is in the following location:
- federation_install_dir/secure-proxy/SSL/keys/tomcat.keystore
Copy the key and certificate files to any location on the new CA SiteMinder® Federation Standalone machine.

Copy the SSL Migration Tool to Same Folder as the Key/Certificate Files

The SSL migration tool requires software that is deployed with CA SiteMinder® Federation Standalone 12.1 SP3. Run the tool on the machine where the CA SiteMinder® Federation Standalone 12.1 SP3 product has been installed. Specifically, the tool has to reside in the same folder where you copied the files to be migrated.

To copy the SSL utility tool

Navigate to federation_install_dir/bin on the 12.52 SP1 system.
Copy the migratessl file (.bat or .sh) to the location on the 12.52 SP1 system where you copied the key and certificate files.

Migrate or Export SSL Keys and Certificates

Complete the SSL key or certificate file migration by running the migratessl utility.

Follow these steps:

Import the Certificate Authority certificate that originally signed the SSL certificate you are migrating.
1. On the system from which you are migrating, export the CA certificate using the Administrative UI.
2. On the new system to which you are migrating, import the CA certificate using the Administrative UI.
Open a command window on the new system where you copied the existing key or certificate files.
Navigate to the folder where you copied the components.

Specify the migratessl command with the necessary command arguments. Refer to the list of migration tool command arguments for all the options.

Examples

To migrate the SSL server.key for Apache SSL connections, enter:

migratessl.bat -op migrate -keytype Apache 
-sourcefile server.key -certfile server.crt
-sourcever 12.0 -sourceos Windows -oldpwd admin1
-newpwd admin2 -issueralias trustedca

To migrate a key/cert file for Tomcat SSL connections, enter:

migratessl.sh -op migrate -keytype Tomcat
-sourcefile tomcat.keystore -sourcever 12.1
-sourceos UNIX -issueralias trustedca 
-oldpwd admin1 -newpwd admin2

To export a key/cert file for Tomcat SSL connections, enter:

migratessl.sh -op export -keytype Tomcat
-sourcefile tomcat.keystore -sourcever 12.1
-sourceos UNIX  -dest ca/federationmgr/secure-proxy/
SSL/keys/ -oldpwd admin1 -newpwd admin2

If you are migrating SSL keys and certificates as part of an entire configuration migration, complete the migration process by reactivating partnerships.

SSL Migration Tool Command Arguments

The migratessl tool is invoked at the command line. When entering a command:

Follow each command agrument (except for Help flags) by only one value.
Enclose values that have spaces, such as directory paths in double quotes.

Command Argument	Meaning
-op	Migrate or Export Default: Migrate When exporting for Apache, the tool exports a server.key file and a server.crt file, if you specify the -certfile argument. For Tomcat, the tool exports a tomcat.p12 file, which is a PKCS#12 key/cert file.
-keytype	Apache or Tomcat Default: Apache
-sourcefile	Name of the file containing the SSL key (Apache) or the key store containing the key and certificate (Tomcat).
-certfile	Name of the file containing the Apache SSL server certificate (Apache only).
-sourcever	CA SiteMinder® Federation Standalone version the key or certificate comes from, such as 12.0, 12.1. Default: 12.0
-sourceos	Operating system of the environment the key comes from, Windows or UNIX. Note: There is no Linux option because Linux support was introduced in r12.1 SP3. Default: The OS of the machine where the tool is being run.
-dest	Path to the folder for output files. This option is ignored for migration. Default for Export: Current folder Important! If you do not specify a destination folder, the files that you are migrating are overwritten.
-issueralias	The alias of the CA certificate that signed the certificate you are migrating. Import the CA certificate under this alias to the destination CA SiteMinder® Federation Standalone system. (Used only for Migrate; ignored for Export.)
-oldpwd	The CA SiteMinder® Federation Standalone administrative password of the system that is the source of the key.
-newpwd	The CA SiteMinder® Federation Standalone administrative password of the system to which the key is being moved.
-h	Displays these usage instructions.
-help	Displays these usage instructions.
-?	Displays these usage instructions.