5 Using SSL Communication

5.1.1 Considerations for using SSL

Normally the Oracle GoldenGate Monitor Server and agents encrypt the data sent between them. Using SSL adds the following security:

• SSL communication between the Oracle GoldenGate Monitor Server and the Oracle GoldenGate agents must be verified by credentials in the form of certificates.

• Information passed between Oracle GoldenGate Monitor Server and the Oracle GoldenGate agents on a network by using SSL is encrypted in a manner that helps to ensure the data will not be modified in transit by third parties.

You can elect to use SSL or not to use it, but you cannot do both at the same time. If your Oracle GoldenGate Monitor Server uses SSL, all the agents that communicate with it must use SSL. The option of using SSL communication for monitoring Oracle GoldenGate instances is subject to the following:

• The default is not to use SSL; you must enable SSL to use it.

• You can use SSL for monitoring Oracle GoldenGate instances on any supported Oracle GoldenGate platform except HP NonStop and IBM AS/400, which are not supported for monitoring.

• If you use SSL, the repositories it uses, called keystores, are protected by a password. This password is stored in the Oracle Wallet on all supported platforms except IBM z/OS. For z/OS all passwords are stored in the password.propterties file on the cfg subdirectory of the installation directory.

• Oracle GoldenGate Monitor supports only two-way SSL authentication and Oracle GoldenGate Monitor Server and Oracle GoldenGate agent use bidirectional communication. The Oracle GoldenGate Monitor Server and Agent will each sometimes act as the server (receiving requests) and sometimes as the client (sending requests).

• Setting up SSL involves creating the keystore and certificates using the Java Keytool. This chapter describes some of the steps to generate keys and certificates for SSL, but assumes that you have knowledge of the Java Keytool and the keystore, have read the Java Keytool documentation, and are aware of the recommended security considerations.

5.1.2 Terminology

The following terms are Java terms that are used in this chapter. Refer to the Java Keytool documentation for more extensive definitions and definitions of related terms.

Keystore

Keystores are databases used for SSL authentication. At a minimum, the keystore stores the private keys and certificates with corresponding public keys that are used to identify one client or one server. However, the truststore can be configured to merge into the keystore, adding the certification from other parties.

Certificate

A certificate is a digitally signed statement from an entity stating that the public key it references is valid because the signature can be verified to check authenticity.

Truststore

Truststores store the public keys and certificates from other parties that you will communicate with and from third party certification authorities (CAs) trusted to sign (issue) certificates for other entities. The truststore may be configured to merge into the keystore, so that all keys and certificates are in one place.

Keytool

Keytool is a Java utility for generating and managing keys and certificates.

5.2.1 Setting SSL Properties

To enable SSL, you must change a property setting for both the server and the agent .

For the Oracle GoldenGate Monitor Server:

1. Navigate to the installation directory of the Oracle GoldenGate Monitor Server.

2. Edit the monitor.properties file to set the monitor.ssl property to true.

3. Stop and restart the Oracle GoldenGate Monitor server to activate the new settings.

For each Oracle GoldenGate Monitor Agent:

1. Navigate to the installation directory of the Oracle GoldenGate instance.

2. Edit the Config.properties file for the agent to set the jagent.ssl property to true.

5.2.2 Creating the Keystore

SSL requires that you create keystores to store the certificates and key pairs. You can create these using the Keytool for Java Secure Sockets Extension (JSSE). To access the Keytool documentation for Solaris/UNIX or Windows, see "JDK Tools and Utilities" at: http://docs.oracle.com/javase/6/docs/technotes/tools

Keystore Location

The keystores for Oracle GoldenGate Monitor must be stored in the following specific directories of the server and agent installation locations:

• The keystore with certification for the agent must be stored in the dircrt subdirectory off the installation directory of the Oracle GoldenGate instance. The default name is jagentKeyStore.

• The keystore and certificate for the Monitor server must be stored in the cert subdirectory off the installation directory of the Oracle GoldenGate Monitor Server. The default name is monitorKeyStore.

By default, the keystore file is created in the directory from which the Keytool is run. Either run the Keytool from the specified locations, or move the keystore after it is created.

You can change the default names of the keystores by setting the jagent.keystore.file, jagent truststore.file, monitor.keystore.file, or monitor.truststore.file properties. If the keystore and truststore files are set to the same name, that one file will be used to store both your certificates and trusted certificates from other entities.

Keystore Password

The keystore is protected by a password created when you create the certificates that identify the Oracle GoldenGate Monitor Server or Agent. This password must also be added to the Oracle Wallet (or to the password.properties file for IBM z/OS.)

For Oracle GoldenGate Monitor Server:

• Add the keystore password by using the WebLogic Scripting Tool command updateCred(), as described in Section 2.3.1, "Changing Passwords."

• If you are using a separate truststore, also add that password, also by using the updateCred().

For each Oracle GoldenGate agent:

• Add the password for the Oracle GoldenGate agent, as explained in Section 3.3, "Updating Oracle GoldenGate Monitor Agent Passwords."

• If you are using a separate truststore, also add the truststore password by using the -truststore option of the utility.

5.3.1 Establishing a Self-signed Certificate for Monitor Server

You need to first create the self-signed certificate that identifies the Oracle GoldenGate Monitor Server and then export it into the Oracle GoldenGate Monitor Agent truststore.

Creating the Certificate to verify Monitor Server

Follow these steps to create the certificate. Refer to the Keytool for Java documentation for more detail on the commands and options.

1. Navigate to the Oracle GoldenGate Monitor Server installation directory and then to the cert subdirectory. This is the location of the Monitor Server keystore.

2. Create the certificate used by Monitor to verify itself and to encrypt the communication.

   For example:

   keytool -genkeypair -keystore monitorkeystore -keyalg rsa -alias monalias -storepass keystorepw -keypass serverpw
   

   The option -keystore identifies the name of the keystore repository. If you do not use the monitorkeystore default name, ensure that you update the monitor.properties file with the name you select.

   -keyalg identifies the encrypting algorithm, which must be rsa.

   -alias specifies an identifier for the new keystore entry that will be created; monalias in this example.

   -storepass identifies the password that protects the keystore. -keypass identifies the password that protects the private key of the generated key pair identifying the Monitor Server. If you do not provide a password for one of these, you will be prompted to enter it.

   Note:

   Record the keystore password you select so you can add it to Oracle GoldenGate Monitor Server or Agent as explained in Section 5.2.2, "Creating the Keystore."

   The program will prompt you to answer the following questions:

   What is your first and last name?
   What is the name of your organizational unit?
   What is the name of your organization?
   What is the name of your City or Locality?
   What is the name of your State or Province?
   What is the two-letter country code for this unit?
   

   After you enter your answers, the program will display them and ask you to confirm they are correct. This information becomes part of the certificate.

3. (Optional) Verify the certificate creation by listing the entry that was created using a command similar to:

   keytool -list -alias monalias -keystore monitorkeystore
   

4. Export the Oracle GoldenGate Monitor Server certificate from the monitorkeystore keystore to a file. For example:

   keytool -exportcert -alias monalias -file moncert.crt -keystore monitorkeystore storepass keystorepw
   

   The option -file identifies the file that will hold the monalias certificate after the export. -keystore identifies the repository that contains the alias that is to be exported.

   Optionally you can generate a Certificate Signing Request (CSR) with the -certreq option and send the certificate to a third party CA for signing.

5. (Optional) Print the certificate information. For example:

   keytool -printcert -file moncert.crt
   

6. Copy the Oracle GoldenGate Monitor Server certificate file created by the Keytool exportcert command (moncert.crt in the example) to the Oracle GoldenGate agent installation location/dircrt directory.

Importing the Server Certificate to the Agent Keystore

Perform the following steps to import the Oracle GoldenGate Monitor Server certificate to the agent truststore.

1. Navigate to the location of the Oracle GoldenGate agent keystore (installation location/dircrt).

2. Import the certificate to the Oracle GoldenGate agent keystore. For example:

   keytool -importcert -alias agentalias -file moncert.crt -keystore jagentkeystore storepass agentkeystorepw
   

   This reads the certificate from the moncert.crt file and stores it in the jagentkeystore.

   Optionally, you can use the -trustcerts option to import additional certificates for the chain of trust from a system-wide keystore of CA certificates. For example, the following command will trigger Keytool to attempt to establish a trust path from the moncert.crt up to a self-signed certificate.

   keytool -importcert -trustcacerts -alias agentalias -file moncert.crt -keystore jagentkeystore -storepass agentkeystorepw
   

3. (Optional) List the certificates that have been created in the keystore to verify the import. For example:

   keytool -list -keystore jagentkeystore storepass agentkeystorepw
   

5.3.2 Establishing a Self-signed Certificate for the Agent

You need to create a self-signed certificate to verify the Oracle GoldenGate Monitor Agent and import the certificate to the Oracle GoldenGate Monitor Server.

5.4.1 Generating a Certificate Signing Request

Follow these steps to generate a Certificate Signing Request (CSR). In this example we are using different names for the keystores to avoid limiting the example to either the Oracle GoldenGate Monitor Server side or the Agent side.

1. Generate the CSR using a Keytool command similar to the following.

   keytool -certreq -v -alias certalias -file cert.csr -keypass keypassword -storepass keystorepw -keystore keystore.jks 
   

   This command will create a file named cert.csr as specified in the -file option. The -v option signifies verbose mode, which will output more information.

2. Submit the CSR cert.csr to the third party that is to sign the certificate.

5.4.2 Importing the Certificate

Once you get the signed certificate back from the third party CA, import both the signed certificate and the certificate of the CA that signed it into your keystore.

1. Convert the CA certificates and the signed certificate into PEM format and store them in the directory of the keystore. Each certificate, including those in a chain, must be stored individually.

2. Import the top (or root) certificate in the chain, which must be the self-signed certificate of the CA, using a command similar to the following:

   keytool -importcert -v -noprompt -trustcacerts -alias rootCA -file rootCA.pem -keystore keystore.jks -storepass keystorepw
   

   In this example, rootCA is the alias of the certificate and rootCA.pem is the file that contains the top certificate in the chain.

   If the import is successful, Keytool will display the message Certificate was added to keystore.

   Note:

   For some third party Certification Authorities, there may be two CA certificates in the chain: the root certificate and an intermediate CA certificate. In this case, the intermediate certificate should be imported directly after the root certificate.

3. Repeat the import for each of the certificates (.pem files) in the chain. Create a different alias for each one.

4. After all of the certificates have been successfully imported, import the signed reply certificate using a command similar to the following:

   -keytool -importcert -v-alias certalias -file cert.pem -keystore keystore.jks -keypass keypass -storepass keystorepw
   

   Use the same alias that you used when generating the certificate and the CSR.

   If the import was successful, Keytool will display the message Certificate reply was installed in the keystore.

5. List all of the CA certificates that were imported.

   keytool -list -keystore keystore.jks -storepass keystorepw
   

6. Export the public certificate using a command similar to the following, which will create the file cert.cer.

   keytool -exportcert -alias certalias -file cert.cer -keystore keystore.jks -storepass keystorepw
   

   Repeat the export for each of the certificates.

7. To import a certificate and its CA certificates to the keystore, first store all of the certificates in separate files in .pem format. Then import all of the certificates, starting with the top or root certificate, giving each one a different alias. For example to import the root certificate:

   keytool -importcert -v -noprompt -trustcacerts -alias IDrootCA -file IDrootCA.pem -keystore keystore.jks -storepass storepasspw
   

   Repeat the import for each of the certificates.