USER MANUALS

Obtaining and Installing an SSL/TLS Certificate

Before enabling SSL/TLS in the Denodo Platform servers and clients, you need to create a keystore with a key pair (a public key and associated private key) and a certificate. To do this, follow one of these options:

  1. If you do not have an SSL private key, you can create a keystore with a self-signed private key.

  2. If you do not have an SSL private key, you can send a request to a certificate authority (CA) and create a keystore with the certificate reply.

  3. If you have a PFX file with the private key, create a keystore with its content.

  4. If you already have a keystore file (usually, this file has the extension “p12” or “jks”), jump to the next section.

To use the options one, two or three, we are going to use the tool keytool. The keytool documentation for Windows and Linux provides more details about the parameters of this tool.

Create a Keystore with a Self-Signed Certificate

This section explains how to generate a key pair (a public key and associated private key) and its self-signed certificate (an X.509 v3 self-signed certificate).

In the host where the Denodo servers will run, open a command line and run these commands.

Step #1. Generate the key pair.

Execute the following command (on Linux, change \ with /), replacing the sample hostname.example.com with the FQDN where the Denodo servers will run.

cd <DENODO_HOME>
.\jre\bin\keytool -genkeypair -alias denodo-server-self-signed -keyalg RSA -keysize 2048 -keystore denodo_server_key_store.p12 -storetype pkcs12 -validity 365 -dname "cn=hostname.example.com" -ext san=dns:hostname.example.com,dns:localhost,ip:127.0.0.1

To use a JKS keystore change the file extension from .p12 to .jks and the -storetype parameter to jks.

Note

Note that Subject Alternative Names (SAN) are not required for JDBC or ODBC connections, but they are required by the browser when accessing the web tools of the Denodo Platform. If the web tools will be used, ensure that all the hostnames and IP addresses used to access the Denodo Platform are added into the SAN entry following the format shown above. If this is not necessary, everything including and after -ext can be removed.

Samples of valid SAN attributes:

SAN=IP:123.456.789.101,DNS:hostname.example.com,DNS:hostname SAN=DNS:hostname.example.com

Enter and re-enter the password of the new keystore. Write down this password, you will need it later in the configuration and if lost, it cannot be retrieved.

Step #2. Export the self-signed public key to a file.

Execute this (on Linux, replace \ with /):

.\jre\bin\keytool -exportcert -alias denodo-server-self-signed -keystore denodo_server_key_store.p12 -file denodo_server_public_key.cer

Enter the password you entered in “step #1”.

This command exports the certificate to the file denodo_server_public_key.cer.

Step #3. Import the certificate into the truststore of the Denodo servers.

Execute this (on Linux, replace \ with /):

.\jre\bin\keytool -importcert -alias denodo-server-self-signed -file denodo_server_public_key.cer -cacerts -storepass "changeit" -noprompt

Step #4. Copy the public key to the Virtual DataPort administration tools that will connect to this Denodo server.

Copy the file “cacerts” of this server (located in the directory “<DENODO_HOME>/jre/lib/security”), to all the computers that have a Virtual DataPort administration tool that will connect to this server. In these computers, replace the file <DENODO_HOME>/jre/lib/security/cacerts with the cacerts you just copied.

The cacerts file only contains public keys and not private ones so it can be shared freely and does not pose any security risk.


Alternatively, instead of copying the “cacerts” file, you can import just the public key. To do this, copy the file denodo_server_public_key.cer from the Denodo server to the directory <DENODO_HOME> of the client, open a command line in this client and execute this:

cd <DENODO_HOME>
.\jre\bin\keytool -importcert -alias denodo-server-self-signed -file denodo_server_public_key.cer -cacerts -storepass "changeit" -noprompt

With the parameter -importcert you are importing the self-signed certificate into the truststore of the Java Runtime Environment included in the Denodo Platform. “changeit” is the default password of the cacerts file included in any Java Runtime Environment.


Step #5. Import the public key into JDBC clients.

  1. Copy the file denodo_server_public_key.cer from the Server to the computer of the client application.

  2. Locate the Java Runtime Environment (JRE) the JDBC client uses.

  3. Open a command line in this computer and execute this:

keytool -importcert -alias denodo-server-self-signed -file denodo_server_public_key.cer -cacerts -storepass "changeit" -noprompt

You do not have to import the public key into clients that to connect to Denodo using ODBC.


You need to import the certificate into the truststore of the clients (the “cacerts” file) because this certificate is self-signed and not signed by a public certificate authority (CA). Therefore, by default, external clients do not trust this certificate and they will refuse to establish SSL connections to the Denodo servers.


Now that you have the certificate in place, go to the next section to enable SSL on the Denodo servers and its clients.

Send a Certificate Request to a Certificate Authority (CA) and Create a Keystore with the Reply

This section explains how to send a “Certificate Signing Request” (CSR) so you can use a certificate that is signed by a public certification authority (CA); and how to create a keystore with the reply.

In the host where the Denodo servers will run, open a command line and run these commands.

Step #1. Create a keystore and a private key.

Execute this (on Linux, replace \ with /):

cd <DENODO_HOME>
.\jre\bin\keytool -genkeypair -alias denodo-server -keyalg RSA -keysize 2048 -keystore denodo_server_key_store.p12 -deststoretype PKCS12 -v -ext san=dns:hostname.example.com,dns:localhost,ip:127.0.0.1

Enter and re-enter the password of the new keystore. Write down this password, you will need it later in the configuration and if lost, it cannot be retrieved.

Entering the attributes of the certificate

After entering the password, provide the attributes of the certificate. If any of these attributes has an &, @, or any other symbol using the shift key, spell out the symbol or omit it to enroll. For example, if “Oil & Gas Corporation”, enter “Oil and Gas Corporation”.

Note

Note that Subject Alternative Names (SAN) are not required for JDBC or ODBC connections, but they are required by the browser when accessing the web tools of the Denodo Platform. If the web tools will be used, ensure that all the hostnames and IP addresses used to access the Denodo Platform are added into the SAN entry following the format shown above. If this is not necessary, the -ext option can be removed completely.

Step #2. Generate the Certificate Signing Request (CSR)

Execute this:

.\jre\bin\keytool -certreq -alias denodo-server -file denodo_certificate_signing_request.csr -keystore denodo_server_key_store.p12 -sigalg SHA1withRSA -v

You will have to enter the password of the keystore you entered on step #1.

The file denodo_certificate_signing_request.csr contains the certificate request; send it to your Certification Authority (CA).

Step #3. Import the certificate response into the keystore.

Once you got the certificate response, import it into the keystore. The steps depend on if you have a PCKS#7 certificate or a X.509 one.

  1. An X.509 certificate usually has the extension cer and it is a text file that starts with -----BEGIN CERTIFICATE-----. If you have this type of certificate, you have to do two steps:

    1. Probably (depends on the CA), you need to obtain the intermediate certificate of the CA. After obtaining it, execute this:

    .\jre\bin\keytool -import -trustcacerts -alias intermediate_ca -keystore denodo_server_key_store.p12 -file <INTERMEDIATE CERTIFICATE FILENAME.cer>

    1. Import the certificate:

    .\jre\bin\keytool -import -trustcacerts -alias denodo-server -keystore denodo_server_key_store.p12 -file <YOUR CERTIFICATE FILENAME.cer>

    Note

    The parameter alias has to match the alias you indicated in the previous step (when you executed keytool -certreq).

  2. A PKCS#7 certificate usually has the extension p7b. Execute this to import it into the keystore:

    .\jre\bin\keytool -import -trustcacerts -alias denodo-server -keystore denodo_server_key_store.p12 -file <YOUR CERTIFICATE FILENAME.p7b>

    Note

    The parameters alias and keystore have to match what you indicated in the previous step (when you executed keytool -certreq).

Step #4. Check the contents of the keystore.

Check that the keystore contains the appropriate certificate. To do it, execute this from the command line:

.\jre\bin\keytool -list -v -keystore denodo_server_key_store.p12

You should see something like the following:

Alias name: denodo-server...
Creation date: Nov 15, 2017
Entry type: PrivateKeyEntry
Certificate chain length:
...
...

The value of “Entry Type” has to be PrivateKeyEntry or KeyEntry.

In some scenarios, this command will return several entries. In this case, in one and only one of the entries, the value of “Entry Type” has to be PrivateKeyEntry or KeyEntry. The keystore has several entries when the certification authority (CA) from which you obtained the private key is not widely recognized. Therefore, when importing the private key, “keytool” also imports the public certificate of the CA.

Step #5. Import the certificate of the CA (and intermediate CAs) into the truststore of the Denodo servers.

Note

This step is necessary only if your certificate has been signed by a Certificate Authority (CA) that is not trusted by default (i.e. its certificate is not included in the default truststore, located in <DENODO_HOME>/jre/lib/security/cacerts). This will happen when your certificate is signed by the CA of your organization or by lesser known CA.

  1. If you do not have individual .cer files for the CA and intermediate CA’s public certificates, export them from the keystore. To do this, execute these commands:

    Start by checking the contents of the keystore:

    cd <DENODO_HOME>
.\jre\bin\keytool -list -v -keystore denodo_server_key_store.p12

    You should see the aliases for the CA and intermediate CA’s certificates (or maybe only for the CA, in case an intermediate CA is not required). Now, export these certificates (use the appropriate aliases):

    .\jre\bin\keytool -exportcert -alias "my_ca" -keystore denodo_server_key_store.p12 -file my_ca.cer
.\jre\bin\keytool -exportcert -alias "my_intermediate_ca" -keystore denodo_server_key_store.p12 -file my_intermediate_ca.cer

  2. Execute these commands to import these certificates (the .cer files) into the Denodo server’s truststore. These commands are to import the .cer files obtained in the step above or the .cer files provided by your security team.

    .\jre\bin\keytool -importcert -alias "my_ca" -file my_ca.cer -cacerts -storepass "changeit" -noprompt
.\jre\bin\keytool -importcert -alias "my_intermediate_ca" -file my_intermediate_ca.cer -cacerts -storepass "changeit" -noprompt

Now that the certificates are in place, go to the next section to enable SSL on the Denodo servers and its clients.

Create a Keystore from a PFX File (PKCS#12)

A PKCS #12 bundle contains a private key and its X.509 certificate. These bundles usually have the file extension .pfx or .p12.

To create a keystore from a PKCS bundle, you can use the Denodo SSL/TLS configurator script or open a command line and follow these steps:

Step #1. List the certificates in the PCKS #12 file.

cd <DENODO_HOME>
.\jre\bin\keytool -list -keystore <PFX file name> -storetype pkcs12 -v

This command lists the certificates included in this file. You will see something like this:

Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 1 entry

Alias name: 91fd6b6a-5e7e-4e32-b963-6faf6439aaae
...
...
...

Copy the value of the attribute “Alias name”.

Step #2. Import the key into the keystore.

.\jre\bin\keytool -importkeystore -trustcacerts --srckeystore "<PFX certificate file name>" -srcalias "<ALIAS OF THE KEY TO IMPORT>" -destkeystore denodo_server_key_store.p12 -destalias "denodo_server" -srcstoretype PKCS12 -deststoretype PKCS12

Replace <ALIAS OF THE KEY TO IMPORT> with the “Alias name” obtained in the previous step.

You have to provide the password of the PFX bundle and the password of the new keystore. When prompted for the password for the key (when in the command line you see (RETURN if same as keystore password)), press Enter so the key has the same password as the keystore. The key and the keystore need to have the same password.

Step #3. Check the contents of the keystore.

Execute the command below to check that the keystore contains the appropriate certificate.

.\jre\bin\keytool -list -v -keystore denodo_server_key_store.p12

You should see something like the following:

Alias name: denodo-server...
Creation date: Jul 1, 2016
Entry type: PrivateKeyEntry
Certificate chain length:
...
...

The value of “Entry Type” has to be PrivateKeyEntry or KeyEntry.

In some scenarios, this command will return several entries. In this case, in one and only one of the entries, the value of “Entry Type” has to be PrivateKeyEntry or KeyEntry. The keystore has several entries when the certification authority (CA) from which you obtained the private key is not widely recognized. Therefore, when importing the private key, “keytool” also imports the public certificate of the CA.

Step #4. Import the certificate into the truststore of the Denodo servers.

Note

This step is necessary only if your certificate is self-signed.

.\jre\bin\keytool -exportcert -alias "denodo_server" -keystore denodo_server_key_store.p12 -file denodo_server_public_key.cer

Enter the password you entered in “step #2” for the new keystore.

Now, import the certificate into the truststore of the Denodo servers. Execute this (on Linux, replace \ with /):

.\jre\bin\keytool -importcert -alias "denodo_server" -file denodo_server_public_key.cer -cacerts -storepass "changeit" -noprompt

This command imports the certificate into the truststore of the Java Runtime Environment included in the Denodo Platform.

Step #5. Import the CA and intermediate CA certificates into the truststore of the Denodo servers.

Note

This step is necessary only if your certificate has been signed by an authority which is not trusted by default (i.e. its certificate is not included in the default truststore, located in <DENODO_HOME>/jre/lib/security/cacerts). This will happen when your certificate has been signed by a corporate CA or by a newer or lesser known Certificate Authority.

If you do not have individual .cer files for the CA and intermediate CA’s public certificates, first you will need to export them from the keystore. Start by checking the contents of the keystore:

.\jre\bin\keytool -list -v -keystore denodo_server_key_store.p12

You should see the aliases for the CA and intermediate CA’s certificates (or maybe only for the CA, in case an intermediate CA is not required). Now, export these certificates (use the appropriate aliases):

.\jre\bin\keytool -exportcert -alias "my_ca" -keystore denodo_server_key_store.p12 -file my_ca.cer
.\jre\bin\keytool -exportcert -alias "my_intermediate_ca" -keystore denodo_server_key_store.p12 -file my_intermediate_ca.cer

Finally, import these certificates into the Denodo server’s truststore:

.\jre\bin\keytool -importcert -alias "my_ca" -file my_ca.cer -cacerts -storepass "changeit" -noprompt
.\jre\bin\keytool -importcert -alias "my_intermediate_ca" -file my_intermediate_ca.cer -cacerts -storepass "changeit" -noprompt

Now that you have the certificates in place, go to the next section to enable SSL on the Denodo servers and its clients.

Add feedback