7.11 Using Secure Sockets Layer (SSL) Connections

Table of Contents Previous Next


7 Common Operations : 7.11 Using Secure Sockets Layer (SSL) Connections

Note: SSL connections are not used from the xDB Replication Console or the xDB Replication Server Command Line Interface. The xDB user interfaces communicate with the publication server and subscription server, which in turn connect to the publication/subscription databases or master nodes.
Note: The Migration Toolkit connection using SSL occurs within the context of the publication server and subscription server SSL connections. Therefore, there are no separate steps that you need to perform for the Migration Toolkit SSL connection.
The Java truststore is the file containing the Certificate Authority (CA) certificates with which the Java client (the publication server and subscription server) uses to verify the authenticity of the server to which it is initiating an SSL connection.
The Java keystore is the file containing private and public keys and their corresponding certificates. The keystore is required for client authentication to the server, which is used for xDB Replication Server SSL connections.
Step 1: Create the certificate signing request (CSR).
In the following example the generated certificate signing request file is server.csr. The private key is generated as file server.key.
Note: When creating the certificate, the value specified for the common name field (designated as CN=enterprisedb in this example) must be the database user name that is specified in the User field of the Add Database or Update Database dialog box used when defining the publication database (see Section 5.2.2), subscription database (see Section 5.3.2), or master nodes (see sections 6.2.2 and 6.3).
Alternatively, user name maps can be used as defined in the pg_ident.conf file to permit more flexibility for the common name and database user name. Steps 8 and 9 describe the use of user name maps.
Step 2: Generate the self-signed certificate.
The following generates a self-signed certificate to file server.crt using the certificate signing request file, server.csr, and the private key, server.key, as input.
Step 3: Make a copy of the server certificate (server.crt) to be used as the root Certificate Authority (CA) file (root.crt).
Step 4: Delete the now redundant certificate signing request (server.csr).
Step 5: Move or copy the certificate and private key files to the Postgres database server data directory, POSTGRES_INSTALL_HOME/data.
Step 6: Set the file ownership and permissions on the certificate files and private key file.
Set the ownership to the operating system account that owns the data subdirectory of the Postgres database server, which is either enterprisedb or postgres depending upon the chosen installation mode (Oracle compatible or PostgreSQL compatible) when you installed your Postgres database server.
Step 7: In the postgresql.conf file, make the following modifications.
Step 8: Modify the pg_hba.conf file to enable SSL usage on the desired publication, subscription, or master node databases.
In the pg_hba.conf file, the hostssl type indicates the entry is used to validate SSL connection attempts from the client (the publication server and the subscription server).
The authentication method is set to cert with the option clientcert=1 in order to require an SSL certificate from the client against which authentication is performed using the common name of the certificate (enterprisedb in this example).
The map=sslusers option specifies that a mapping named sslusers defined in the pg_ident.conf file is to be used for authentication. This mapping allows a connection to the database if the common name from the certificate and the database user name attempting the connection match the SYSTEM-USERNAME/PG-USERNAME pair listed in the pg_ident.conf file.
The following is an example of the settings in the pg_hba.conf file if the publication and subscription databases (edb and subnode) must use SSL connections.
Step 9: The following shows the user name maps in the pg_ident.conf file related to the pg_hba.conf file by the map=sslusers option. These user name maps permit you to specify database user names pubuser, subuser, mmruser, or enterprisedb in the User field of the Add Database or Update Database dialog box when adding the publication, subscription, or master node databases in the xDB Replication Console.
Step 10: Restart the Postgres database server after you have made the changes to the Postgres configuration files.
Step 1: Using files server.crt and server.key located under the Postgres database server data subdirectory, create copies of these files and move them to the host where the publication server and subscription server are running.
For this example, assume file xdb.crt is a copy of server.crt and xdb.key is a copy of server.key.
Step 2: Create a copy of xdb.crt.
Step 3: Create a Distinguished Encoding Rules (DER) format of file xdb_root.crt. The generated DER format of this file is xdb_root.crt.der. The DER format of the file is required for the keytool program in the next step.
Step 4: Use the keytool program to create a keystore file (xdb.keystore) using xdb_root.crt.der as the input. This process adds the certificate of the Postgres database server to the keystore file.
The keytool program can be found under the bin subdirectory of the Java Runtime Environment installation.
Step 5: Generate the encrypted form of the new password specified in the preceding step.
The encrypted password must be specified with the sslTrustStorePassword configuration option of the publication server configuration file for publication server SSL connections and the subscription server configuration file for subscription server SSL connections. (See Section 10.4.1 for information on the publication server and subscription server configuration files.)
Encrypt the password using the xDB Replication Server CLI encrypt command. The following example shows this process encrypting the password contained in file infile.
Step 6: Create a PKCS #12 format of the keystore file (xdb_pkcs.p12) using files xdb.crt and xdb.key as input.
Step 7: Generate the encrypted form of the new password specified in the preceding step,
The encrypted password must be specified with the sslKeyStorePassword configuration option of the publication server configuration file for publication server SSL connections and the subscription server configuration file for subscription server SSL connections.
Step 8: Copy files xdb.keystore and xdb_pkcs.p12 to a directory location where they are to be accessed by the publication server and subscription server.
Step 9: In the publication server and subscription server configuration files, set the location of file xdb.keystore with the sslTrustStore option and the location of file xdb_pkcs.p12 with the sslKeyStore option.
The encrypted sslTrustStorePassword is obtained from Step 5 after being specified for the keytool program in Step 4.
The encrypted sslKeyStorePassword is obtained from Step 7 after being specified for the openssl pkcs12 program in Step 6.
Section 7.11.4 contains a summary of the publication server and subscription server configuration options for SSL connections.
Step 10: Restart the publication and subscription servers.
pubserver_add_database_dialog_box_ssl
Note: If you no longer wish to use an SSL connection to an xDB Replication Server database, you must completely delete the ssl=true text from the URL Options field of the Add Database or Update Database dialog box. Simply changing true to false does not have the effect of disabling the SSL option.
The sslTrustStoreType option specifies the truststore format. Set this option to the Java truststore format of the client.
sslTrustStoreType=truststore_format
The default value for truststore_format is jks for the JKS truststore file format.
The typical default location of the truststore is in directory JAVA_HOME/jre/lib/security or JAVA_HOME/lib/security in a file named cacerts. (JAVA_HOME is the Java installation directory.)
sslTrustStore=truststore_file
Encrypt the password for the Java system truststore using the xDB Replication Server CLI encrypt command (see Section 8.3.4) and specify the encrypted password with the sslTrustStorePassword option.
sslTrustStorePassword=encrypted_password
The sslKeyStoreType option specifies the keystore format. Set this option to the Java keystore format of the client.
sslKeyStoreType=keystore_format
The default value for keystore_format is pkcs12 for the PKCS #12 keystore file format.
sslKeyStore=keystore_file
Encrypt the password for the Java system keystore using the xDB Replication Server CLI encrypt command (see Section 8.3.4) and specify the encrypted password with the sslKeyStorePassword option.
sslKeyStorePassword=encrypted_password

7 Common Operations : 7.11 Using Secure Sockets Layer (SSL) Connections

Table of Contents Previous Next