Installing and removing custom SSL certificates for StoredIQ for Legal (VM)

StoredIQ® for Legal (VM) is already configured with self-signed certificates that are used with SSL connections. However, you can install your own certificates, either self-signed or from a certificate authority (CA), to be used instead of the preconfigured certificates.

Before you begin

You need the IP address and host name of your StoredIQ for Legal virtual machine (VM).

You need to open a Linux® command window connection (or console, for short) to the VM to run the certificate command-line tool. The VMWare vSphere client application supports opening console connections. If you choose not to use VMWare vSphere console, you must install on a remote host an application that uses the SSH protocol. You will use the SSH application to open a console connection to the VM. Some example applications are OpenSSH and PuTTY.

If you need to copy files to the VM, you must install on the remote host from which you will copy the files a secure copy application that uses the SSH protocol to securely copy files. An example application is WinSCP.

If you plan to use your own certificate, which can be either from a certificate authority (CA) or self-signed, then you must package your private key and certificate in a single password-protected keystore file and import the keystore file. Do not password-protect the private key and certificate. Password-protect only the keystore file. The supported keystore file formats include PKCS12, JCEKS, CMSKS, JKS, and PKCS11. If you use OpenSSH, it has command-line facilities and documentation that explain how to package your private key and certificate in a supported file format with a password and decrypt and strip out passwords, if necessary.

Important: Make sure you renew or remove certificates before they expire or are revoked. Otherwise, the StoredIQ for Legal commands for administering the application in the web application server will no longer work.

Procedure

To install and remove custom certificates:

In VMWare vSphere client, right-click the VM and then click Open Console.
Sign in with the root user ID and its password.
With a server-to-server copy tool that uses the SCP protocol, copy your DER encoded certificate from the web service to the path /siq/conf.
In the /siq/conf path, copy the cert_configuration_default.properties file and save it as cert_configuration.properties at the same location.
If the file with the default values is not available, contact your VM system administrator or IBM Customer Support.
Open the cert_configuration.properties file to edit it.

Tip: Use an editor that comes with the operating system, such as VI, to ensure that no characters are included that corrupt the configuration.
Required: Set the certificateAlias property to a name of your choice.

The default property setting is certificateAlias=customer certificate alias. Write down the certificateAlias setting for future reference if your certificate needs to be replaced. This value is required.

Important: Make sure you renew or remove your certificate before it expires. Otherwise, administration commands addressing the web application server will no longer work.
Uncomment the following line and add the file name of the certificate you uploaded:
```
#certificateFileName=certificate.cer
```
Optional: Complete this step only if you are creating a self-signed certificate.
1. In the section with the ### Certificate creation option ### heading, under the ## Required subheading, remove the comment character # at the start of the line for the required properties.
2. Under the ## Optional subheading, remove the comment character # at the start of the line for the optional properties that you want to include.
3. Enter values for all required fields and for any optional fields that you want to include.
4. Comment out optional fields that you are not using by leaving the # character at the front of the line.
5. Comment out all the properties in the section with the ### Certificate import option ### subheading, which are the import settings.
6. Save your changes and exit the file.
7. In the console, enter cd /siq/bin.
8. Enter ./cert_install deploy -t -p admin_password
  
  The certificate is created as a trusted certificate to the appliance.
  
  Important: Make sure you renew or remove your certificate before it expires. Otherwise, administration commands addressing the web application server will no longer work.
Optional: Complete this step only if you are importing a keystore file that contains a self-signed or CA-signed certificate.
1. In the section with the ### Certificate import option ### heading, under the ## Required subheading, remove the comment character # at the start of the line for the required properties.
2. Enter the values for all required properties.
3. Comment out all of the properties in the section with the ### Certificate creation option ### heading, which are the creation settings.
4. Save your changes and exit the file.
5. Using the secure copy application, copy your keystore file from the remote host to the /root/certs directory.
6. In the console, enter cd /siq/bin.
7. Enter ./cert_install deploy -i -t -p admin_password
  
  The certificate is imported as a trusted certificate to the appliance.
  
  Important: Make sure you renew or remove your certificate before it expires. Otherwise, administration commands addressing the web application server will no longer work.
Optional: Complete this step only if you are removing certificates.
1. Make a backup copy of the cert_configuration.properties file. Then open the original file.
2. In the section with the ### General ### heading, under the ## Required subheading, set certificateAlias to the certificate alias of the certificate that you want to remove.
3. In the console, enter cd /siq/bin.
4. Enter ./cert_install remove -t -p admin_password
  
  The certificate is removed as a trusted certificate from the appliance.

Here is a summary of the commands that you used in the previous steps.

Task	Script command
Create certificate	`./cert_install deploy -t -p admin_password`
Import certificate	`./cert_install deploy -i -t -p admin_password`
Remove certificate	`./cert_install remove -t -p admin_password`