SSL Certificate PINsafe Appliance How to Guide

From Swivel Knowledgebase Wiki

Contents 1 Overview 2 Prerequisites 2.1 Considerations 2.1.1 HA Appliances using VIP 2.1.2 Appliance Webmin 2.1.3 Keystore and Connector Ports 2.1.4 Key format 2.1.5 VeriSign Certificates 3 Certificate Management CMI menu option 4 Procedure Summary 4.1 1. Create a local certificate 4.2 2. Generate a CSR 4.3 3. Apply for the Certificate 4.4 4. Import the Certificate 4.5 5. Check that the certificate is valid 4.6 6. Delete the old selfsigned alias if it exists 4.7 7. Restart Tomcat 5 Exporting certificate from Primary to Standby Server 6 Moving from one appliance to another 7 Importing certificates generated on other appliances and servers 8 Certificates using a CSR from a different appliance or servers 9 Known Issues 9.1 Keysize 10 Troubleshooting 10.1 Error Messages

Overview

PINsafe appliances ship with a self-signed certificate which prompts users to accept a security warning when the Turing image is presented within a web browser. When a PINsafe system goes into production a signed certificate can be installed onto the appliance. This article describes how to install a valid certificate using the PINsafe appliance CMI menu.

If you do not have an appliance, but instead a software only installation of PINsafe, please see our Generate CSR for Tomcat How to Guide.

Prerequisites

• PINsafe appliance version 2.x with Console Management Interface (CMI)

• Configuration of the PINsafe appliance for basic settings

• Certificate Authority to sign a certificate signing request

• Please read and understand these instructions before attempting to install a certificate

Considerations

HA Appliances using VIP

For HA appliances, if a VIP (Virtual IP) is being is used then the certificate must to be bound to a hostname that is used on both PINsafe servers. When you've setup a signed-certificate on one appliance then the keystore can be copied to the other appliance.

Appliance Webmin

The other appliance web based interface, Webmin, uses a separate certificate for SSL communications. Since this is rarely used and then only for administrative purposes by trained administrators, the built-in self-signed certificate is utilised.

Keystore and Connector Ports

The keystore used by each port is defined as a Connector element within the Tomcat server.xml file. You can view this file from Webmin (https://<pinsafe_server>:10000). Go to Servers -> PINsafe and select "Edit Tomcat config file". There should be 3 "<Connector ..." entries, one each for ports 8080, 8443 and 8181 (the last is for internal use only). The entries for port="8080" and "8443" should both have the same value for keystoreFile, which should be "/home/swivel/.keystore". If one of these is different, it needs to be changed.

Key format

Keystores are by default JKS on the PINsafe appliance. Keys are by default generated in DER and expecting X.509 formatted responses. However you can import PKCS12 keystores as long as you can obtain the password from the certificate authority to be able to convert/import it into a JKS.

VeriSign Certificates

VeriSign certificates generally require to import the Primary and Secondary intermediates (instead of root and intermediate) and remove the existing root and intermediate before importing the response onto the private key

Certificate Management CMI menu option

You can find the Certificate Management menu on the PINsafe appliance, by initiating an SSH connection. For information on how to do this, see our PuTTY How To Guide.

Once you've logged into the CMI, you can find the Certificate Management menu under the Tomcat menu and the screen should look something like this (screen shot taken from a PINsafe Primary HA appliance):

Procedure Summary

The normal procedure in getting a commercially signed certificate for a PINsafe appliance is to:

• Create a self-signed private/public key pair;
• Generate a CSR (Certificate Signing Request) from the self-signed certificate you created;
• Import the root or intermediate certificates from the CA (Certificate Authority);
• Import the response from the CA to replace the public key.

The following article sections detail how this is done via the Certificate Management CMI menu option.

1. Create a local certificate

From the Certificate Management menu, select the Create a local Certificate option.

Note: With a certificate renewal you just need to Generate a CSR on the existing cert, without creating a new cert. You will need to enter the alias of the existing keypair when selecting the cert to generate a csr for. Usually this is 'swivel'.

Here is a screen shot of the first screen you encounter when selecting the Create a local Certificate option. At the time of writing this article, most CAs (Certificate Authorities) require at least 2048 bit key size.

You are next prompted to provide information on the site-name (URL of the PINsafe Turing image that the certificate will be securing), company name and location information.

Once all of the information has been entered (including correct country code) you will be presented with the information for review and confirmation that the certificate has been created.

Now you have created a local Certificate, you can generate a CSR (Certificate Signing Request) from it.

2. Generate a CSR

Before performing this step, please ensure you have successfully created a local certificate, as detailed in the previous section.

To generate a CSR (Certificate Signing Request) from the new local certificate, select the Generate CSR menu option from the Certificate Management menu screen. You will be presented with the following screen.

You need to enter the alias swivel as shown in the next screen shot, as this is the alias used by the Certificate Management software when you create a local certificate.

You now need to copy the certificate signing request file you just generated, from the appliance, so that you may send it to your Certificate Signing Authority. For more information on how to copy files to and from the PINsafe appliance, see the Copying appliance files How to Guide.

The CSR is created under /backups/upload as <certificate alias>.csr where <certificate alias> in this case would be swivel, e.g. swivel.csr

3. Apply for the Certificate

Request the certificate from the certificate provider via their website. You should receive an email response once the certificate has been signed. You need to look for "Tomcat" or "Java" keystore compatible formats. This is fairly crucial, otherwise you will create further complications translating the certificate to the correct format and this may require command line work.

4. Import the Certificate

Copy your certificate, and any intermediate certificates you require, to the appliance, under /backups/upload. See Copying appliance files How to Guide

Next, on the Certificate Management menu of the appliance, import the intermediate certificates. Ensure they are given aliases that do not already exist in the keystore.

Now import the new certificate, making sure you use the alias that was used to generate the CSR, i.e. "swivel".

Note: If you get an error at this point, such as a warning that the original alias must be deleted first, DO NOT delete the old alias. If the alias has been deleted see trustedCertEntry in Troubleshooting below.

This will likely be caused by a known bug in some CMI versions, check the CMI certificate software version.

The workaround to this bug is to login the the command line via the Advanced Options menu and enter the following command:

keytool -importcert -keystore /home/swivel/.keystore -alias swivel -file /backups/upload/response.txt -trustcacerts

Where:

• "swivel" is the alias you were attempting to import the response onto, but failed due to the known bug - note that this is the default alias for a local certificate;

• "/backups/upload/response.txt" is the location of the response file you are trying to import. Replace this with the actual filename of your response file.

5. Check that the certificate is valid

Check the certificate using the View keystore option. The length of the certificate chain should equal the number of certificates you have installed (including intermediates) plus one (for the root certificate). Also, the certificate type should be "privateKeyEntry", not "trustedCertEntry".

6. Delete the old selfsigned alias if it exists

If there is still an alias "selfsigned" in the keystore, delete it, or PINsafe may use that instead of the new certificate. Use the delete certificate option for this. Do not delete the local certificate created in step 1.

7. Restart Tomcat

Restart Tomcat to register the new certificate. Check access to the PINsafe administration console, and that there is no certificate error.

Exporting certificate from Primary to Standby Server

This is useful where a VIP is used, and the certificate can be bound to the hostname. The procedure actually involves copying the keystore file to the Standby appliance, not exporting the keypair.

The keystore file location should be listed within your /usr/local/tomcat/conf/server.xml file, but the default keystore file location is:

/home/swivel/.keystore

(it's a hidden file with the '.' prefix)

The method would involve:

- Take a backup of the existing /home/swivel/.keystore file on the Primary

- Make a note of the permissions assigned to the file, by default they are swivel:swivel 600

- Copy in the Primary .keystore file to the same location on the Standby. See Copying appliance files How to Guide

- Run the following commands to ensure the permissions are set to their

defaults:

chmod 600 /home/swivel/.keystore

chown swivel:swivel /home/swivel/.keystore

- Restart Tomcat

Moving from one appliance to another

You can't import the response on an appliance that doesn't have the private key corresponding to the original request. However, you can simply copy the entire keystore from the working appliance to the other one, see the instructions above for Exporting certificate from Primary to Standby Server.

Importing certificates generated on other appliances and servers

It is possible to import a certificate that was generated from another server, but only if the private key is imported as well. This requires the certificate to be exported from the other server complete with the private key, normally as a .pfx file. This is, however, a much more complicated procedure. See SSL Solutions.

Certificates using a CSR from a different appliance or servers

If the CSR was generated from a different appliance or server, and not from the PINsafe appliance, then things get complicated. The simplest solution is to request a new certificate from the certificate authority, using a CSR generated as above, it is possible to export the private key from the server that you generated the original request from, but this is more complicated.

Known Issues

Keysize

The CMI Certs version 0.7 and earlier does not contain keysize options. This is available in 0.8 onwards. Upgrade the CMI or issue the keysize through the command line.

keytool -genkey -keysize 2048 -alias <YourAlias> -keyalg RSA -keystore /home/swivel/.keystore

Where <YourAlias> is whatever you would like the alias to be called e.g. swivel

When prompted for the First and Last Name, use the FQDN.

Troubleshooting

New Certificate not working

Has Tomcat been restarted after installing the certificate? The certificate file is only read when Tomcat starts.

If Importing Server Certificates from Another Machine, ensure that the private key as well as the public key is imported

Verify the certificates on your appliance from the appliance console. Log on via SSH or on the console. Go to the Tomcat option, then Certificate Management, then View Keystore. This will show a list of installed certificates. Select the required certificate, and check the details. In particular, check the Entry Type. If it is "trustedCertEntry", then only the public key has been imported. If there is an alias of "swivel" or "selfsigned" that is not one that you have installed, this may need to be deleted. If the type of this certificate is PrivateKeyEntry, it may be used in preference to one imported, in this case, you should delete all PrivateKeyEntry certificates except the one you imported.

Appliance and certificate management version

Which appliance version and certificate management software is running, check the versions screen within the CMI menu?

Certificate Alias

If the CSR was generated by the PINsafe appliance, but it is still not treated as a private key entry, then you may not have imported it with the same alias as the original self-signed certificate. If this is the case, try re-importing the certificate using the same alias as you used to request the certificate. Otherwise, we recommend starting again, using a self-signed certificate generated from the PINsafe keystore.

trustedCertEntry

The certificate alias "swivel" is showing as a trustedCertEntry. That means it doesn't have an associated private key.

There are two possible reasons for this:

a. The CSR for this certificate was not generated from the PINsafe appliance

b. The original local certificate was deleted before installing the new certificate

The CMI makes backups of the keystore before it makes any changes, allowing a roll back to an earlier keystore. This requires the command line to do it.

cd /home/swivel

ls -al

This lists the folder contents, most of which will be backups of the keystore (starting with .keystore). Identify the correct one from the date and time, or the file size (the file immediately after the correct one will be slightly smaller, as the certificate has been deleted). To confirm the contents of a keystore, use the following command:

keytool -list -keystore <filename>

The keystore password can be obtained from SwivelSecure Support.

Look for a store that contains the alias "swivel" and has the type "PrivateKeyEntry".

Once the correct keystore has been located, make a copy of it:

cp <existing_filename> <new_filename>

Import the certificate response into the keystore as follows:

keytool -importcert -alias swivel -keystore <keystore_filename> -file <response_filename>

If this is successful, rename the file .keystore:

mv .keystore .keystore.saved

And then rename the modified keystore to .keystore:

mv <keystore_name> .keystore

Restart Tomcat in order to register the new keystore and check the certificates by connecting to the PINsafe Administration Console.

Webmin still uses a self signed certificate

Importing the certificate does not affect webmin, only Tomcat.

Certificate not working for port 8443

If the certificate is not working for port 8443, it may be that you haven't imported it properly, or it may be a self-signed certificate that is being used instead.

Error Messages

keytool -importcert -keystore /home/swivel/.keystore -alias swivel -file /backups/upload/swivel.txt -trustcacerts Enter keystore password: keytool error: java.lang.Exception: Failed to establish chain from reply

The certificate has been imported without the required intermediate certificate. Import the intermediate bundle or individual intermediate certificates first (primary and secondary intermediates may be required), before importing the certificate response. Import the intermediate(s)/root e.g. intermediate or root depending on what you're importing (example below).

  keytool -importcert -keystore /home/swivel/.keystore -alias intermediate -file intermediate.txt -trustcacerts

Once the intermediates/root certificate has been imported you can then attempt to import the response again and you should get a success message.

bash: keytool: command not found

This error is seen when keytool cannot be found in the users path. This will be part of the Java path, and will depend upon the Java Version, Example: /usr/java/jre1.6.0_18/bin/keytool