Creating the Truststore and Keystore

Creating the Truststore and Keystore

The SSL configuration works through two separate files that define the server and client side of the encryption configuration. Because individual hosts within a Tungsten Replicator configuration are both servers (when acting as a master, or when providing status information), and clients (when reading remote THL and managing nodes remotely), both the server and client side of the configuration must be configured. Configuration for all systems relies on two files, the truststore, which contains the server certificate information (the certificates it will accept from clients), and the keystore , which manages the client certificate information (the certificates that will be provided to servers). The truststore and keystore hold SSL certificate information, and are password protected.
The keystore and truststore operate by holding one or more certificates that will be used for encrypting communication. The following certificate options are available:

• Create your own server and client certificates
• Create your own server certificates, get the server certificate signed by a Certificate Authority (CA), and use a corresponding signed client certificate
• Use a server and client certificate already signed by a CA. Care should be taken with these certificates, as they are associated with specific domains and/or hosts, and may cause problems in a dynamic environment.

In a multi-node environment such as Tungsten Replicator, all the hosts in the dataservice can use the same keystore and truststore certificates. The tpm command will distribute these files along with the configuration when a new installation is deployed, or when updating an existing deployment.

2.18.1.1. Creating Your Own Client and Server Certificates

Because the client and server components of the Tungsten Replicator configuration are the same, the same certificate can be used and add to both the keystore and truststore files.
The process is as follows:

1. Create the keystore and generate a certificate
2. Export the certificate
3. Import the certificate to the truststore

To start, use the supplied keytool to create a keystore and populate it with a certificate. The process asks for certain information. The alias is the name to use for the server and can be any identifier. When asked for the first and last name, use localhost, as this is used as the server identifier for the certificate. The other information should be entered accordingly.
Keystores (and truststores) also have their own passwords that are used to protect the store from updating the certificates. The password must be known as it is required in the configuration so that Tungsten Replicator can open the keystore and read the contents.
keytool -genkey -alias replserver -keyalg RSA -keystore keystore.jks The above process has created the truststore and the 'server' certificate, stored in the file keystore.jks.
Alternatively, you can create a new certificate in a keystore non-interactively by specifying the passwords and certificate contents on the command-line:
keytool -genkey -alias replserver \ -keyalg RSA -keystore keystore.jks \ -dname "cn=localhost, ou=IT, o=Continuent, c=US" \ -storepass password -keypass password Now you need to export the certificate so that it can be added to the truststore as the trusted certificate:
keytool -export -alias replserver -file client.cer -keystore keystore.jks This has created a certificate file in client.cer that can now be used to populate your truststore. When added the certificate to the truststore, it must be identified as a trusted certificate to be valid. The password for the truststore must be provided. It can be the same, or different, to the one for the keystore, but must be known so that it can be added to the Tungsten Replicator configuration.
keytool -import -v -trustcacerts -alias replserver -file client.cer -keystore truststore.ts This has created the truststore file, truststore.ts.
A non-interactive version is available by using the -noprompt option and supplying the truststore name:
keytool -import -trustcacerts -alias replserver -file client.cer \ -keystore truststore.ts -storepass password -noprompt The two files, the keystore (keystore.jks), and truststore (truststore.ts), along with their corresponding passwords can be now be used .

2.18.1.2. Creating a Custom Certificate and Getting it Signed

You can create your own certificate and get it signed by an authority such as VeriSign or Thawte. To do this, the certificate must be created first, then you create a certificate signing request, send this to your signing authority, and then import the signed certificate and the certificate authority certificate into your keystore and truststore.
Create the certificate:
keytool -genkey -alias replserver -keyalg RSA -keystore keystore.jks Create a new signing request the certificate:
keytool -certreq -alias replserver -file certrequest.pem \ -keypass password -keystore keystore.jks -storepass password This creates a certificate request, certrequest.pem. This must be sent the to the signing authority to be signed.

• Official Signing
  Send the certificate file to your signing authority. They will send a signed certificate back, and also include a root CA and/or intermediary CA certificate. Both these and the signed certificate must be included in the keystore and truststore files.
  First, import the returned signed certificate:
  keytool -import -alias replserver -file signedcert.pem -keypass password \ -keystore keystore.jks -storepass password Now install the root CA certificate:
  keytool -import -alias careplserver -file cacert.pem -keypass password \ -keystore keystore.jks -storepass password

  Note

  If the import of your certificate with keytool fails, it may be due to an incompatibility with some versions of OpenSSL, which fail to create suitable certificates for third-party tools. In this case, see Section 2.18.1.4, “Converting SSL Certificates for keytool” for more information.
  
  And an intermediary certificate if you were sent one:
  keytool -import -alias interreplserver -file intercert.pem -keypass password \ -keystore keystore.jks -storepass password Now export the signed certificate so that it can be added to the truststore. Although you can import the certificate supplied, by exporting the certificate in your keystore for inclusion into your truststore you can ensure that the two certificates will match:
  keytool -export -alias replserver -file client.cer -keystore keystore.jks The exported certificate and CA root and/or intermediary certificates must now be imported to the truststore:
  keytool -import -trustcacerts -alias replserver -file client.cer \ -keystore truststore.ts -storepass password -nopromptkeytool -import -trustcacerts -alias careplserver -file cacert.pem \ -keystore truststore.ts -storepass password -nopromptkeytool -import -trustcacerts -alias interreplserver -file intercert.pem \ -keystore truststore.ts -storepass password -noprompt
• Self-Signing
  If you have setup your own certificate authority, you can self-sign the request using openssl:
  openssl ca -in certrequest.pem -out certificate.pem Convert the certificate to a plain PEM certificate:
  openssl x509 -in certificate.pem -out certificate.pem -outform PEM Finally, for a self-signed certificate, you must combine the signed certificate with the CA certificate:
  cat certificate.pem cacert.pem > certfull.pem This certificate can be imported into your keystore and truststore.
  To import your signed certificate into your keystore:
  keytool -import -alias replserver -file certfull.pem -keypass password \ -keystore keystore.jks -storepass password Then export the certificate for use in your truststore:
  keytool -export -alias replserver -file client.cer -keystore keystore.jks The same certificate must also be exported and added to the truststore:
  keytool -import -trustcacerts -alias replserver -file client.cer \ -keystore truststore.ts -storepass password -noprompt

This completes the setup of your truststore and keystore. The files created can be used in your tpm configuration. See Section 2.18.3, “Configuring the Secure Service through tpm”.

2.18.1.3. Using an existing Certificate

If you have an existing certificate (for example with your MySQL, HTTP server or other configuration) that you want to use, you can import that certificate into your truststore and keystore. When using this method, you must import the signed certificate, and the certificate for the signing authority.
When importing the certificate into your keystore and truststore, the certificate supplied by the certificate authority can be used directly, but must be imported alongside the certificate authorities root and/or intermediary certificates. All the certificates must be imported for the SSL configuration to work.
The certificate should be in the PEM format if it is not already. You can convert to the PEM format by using the openssl tool:
openssl x509 -in signedcert.crt -out certificate.pem -outform PEM First, import the returned signed certificate:
keytool -import -file certificate.pem -keypass password \ -keystore keystore.jks -storepass password

Note

If the import of your certificate with keytool fails, it may be due to an incompatibility with some versions of OpenSSL, which fail to create suitable certificates for third-party tools. In this case, see Section 2.18.1.4, “Converting SSL Certificates for keytool” for more information.

Now install the root CA certificate:
keytool -import -file cacert.pem -keypass password \ -keystore keystore.jks -storepass password And an intermediary certificate if you were sent one:
keytool -import -file intercert.pem -keypass password \ -keystore keystore.jks -storepass password Now export the signed certificate so that it can be added to the truststore:
keytool -export -alias replserver -file client.cer -keystore keystore.jks The exported certificate and CA root and/or intermediary certificates must now be imported to the truststore:
keytool -import -trustcacerts -alias replserver -file client.cer \ -keystore truststore.ts -storepass password -nopromptkeytool -import -trustcacerts -alias replserver -file cacert.pem \ -keystore truststore.ts -storepass password -nopromptkeytool -import -trustcacerts -alias replserver -file intercert.pem \ -keystore truststore.ts -storepass password -noprompt

2.18.1.4. Converting SSL Certificates for keytool

Some versions of the openssl toolkit generate certificates which are incompatible with the certificate mechanisms of third-party tools, even though the certificates themselves work fine with OpenSSL tools and libraries. This is due to a bug which affected certain releases of openssl 1.0.0 and later and the X.509 certificates that are created.
This problem only affects self-generated and/or self-signed certificates generated using the openssl command. Officially signed certificates from Thawte, VeriSign, or others should be compatible with keytool without conversion.
To get round this issue, the keys can be converted to a different format, and then imported into a keystore and truststore for use with Tungsten Replicator.
To convert a certificate, use openssl to convert the X.509 into PKCS12 format. You will be prompted to enter a password for the generated file which is required in the next step:
openssl pkcs12 -export -in client-cert.pem -inkey client-key.pem >client.p12 To import the converted certificate into a keystore, specifying the destination keystore name, as well as the source PKCS12 password used in the previous step:
keytool -importkeystore -srckeystore client.p12 -destkeystore keystore.jks -srcstoretype pkcs12 The same process can be used to import server certificates into truststore, by converting the server certificate and private key:
openssl pkcs12 -export -in server-cert.pem -inkey server-key.pem >server.p12 Then importing that into a truststore
keytool -importkeystore -srckeystore server.p12 -destkeystore truststore.ts -srcstoretype pkcs12 For official CA certificates, the generated certificate information should be valid for importing using keytool, and this file should not need conversion.