Previous Next JavaScript must be enabled to correctly display this content

## Guidelines for Generating Certificate Chain and Private Key using OpenSSL

Certificate chains can be used to securely connect to the Oracle NoSQL Database Proxy. This section provides the steps to generate certificate chains and other required files for a secure connection using OpenSSL.

A certificate chain is provided by a Certificate Authority (CA). There are many CAs. Each CA has a different registration process to generate a certificate chain. Follow the steps provided by your CA for the process to obtain a certificate chain from them.

As a pre-requisite, download and install OpenSSL on the host machine. See OpenSSL.

Note:

In the examples below, the OpenSSL command has been used in Oracle Linux Version 8 (OL8). The syntax of `openssl` can be different in other Oracle Linux versions.

Before generating your certificate, list all the different hostnames, domains, sub-domains, and IP addresses that need to be secured. Understanding how the application connects to the Oracle NoSQL Database Proxy, allows you to understand the needs of SSL/TLS certificates. First you need to determine how many hostnames, domains and sub-domains need to be secured. This will help in determining the right SSL/TLS certificate or a certificate mix that is needed to encrypt the traffic between the applications and the Oracle NoSQL Database Proxy.

To generate a certificate chain and private key using the OpenSSL, complete the following steps:

1. On the configuration host, navigate to the directory where the certificate file is required to be placed.
2. Create a 2048 bit server private key.

       openssl genrsa -out key.pem 2048

   The following output is displayed.

       Generating RSA private key, 2048 bit long modulus
       ..................+++
       ...................+++
       e is 65537 (0x10001)

3. This step is required only when your server private key is not in PKCS#8 format. Convert the private key to PKCS#8 format. When prompted, provide a secure password of your choice for the encryption.

       openssl pkcs8 -topk8 \
       -inform PEM -outform PEM \
       -in key.pem -out key-pkcs8.pem

   The following output is displayed.

       Enter Encryption Password:
       Verifying - Enter Encryption Password:

   Note:

   The below conversion should be done if your key is encrypted with the `PKCS#5 v2.0` algorithm. Otherwise, you might encounter `IllegalArgumentException` exception that indicates the file does not contain a valid private key due to the unsupported algorithm. The encryption algorithm can be converted via OpenSSL `pkcs8` utility by specifying `PKCS#5 v1.5` or `PKCS#12` algorithms with `-v1` flag. The following command converts the encryption algorithm of a key to `PBE-SHA1-3DES`.

       openssl pkcs8 -topk8 -in <PKCS#5v2.0_key_file> -out <new_key_file> -v1 PBE-SHA1-3DES

4. Create a Certificate Signing Request (CSR).

       openssl req -new  -key key.pem -out request.csr \
       -subj "/C=US/ST=CA/L=San/CN=proxy-nosql.example.com"

   where, `CN` in the `subj` should map to either the NoSQL Database proxy server hostname or the NoSQL Database proxy domain name.
   Using CN and optionally SAN while generating a self-signed certificate:
   - Common Name (CN) is used to specify the NoSQL Database proxy server hostname or NoSQL Database proxy server domain name.
   - When a client tries to connect to the Oracle NoSQL Database Proxy it will get the SSL certificate and compare the NoSQL Database proxy server hostname or NoSQL Database proxy server domain name it wants to connect, with the CN provided in the SSL certificate. If they are exactly the same it will use the SSL certificate to encrypt the connection, otherwise, the connection fails.
   - The standard X509 defines that single SSL certificate can only use a single CN. This means an SSL certificate can be used only for a single NoSQL Database proxy server hostname or NoSQL Database proxy server domain name.
   - To solve this limitation, Subject Alternative Name(SAN) is created. SAN is used to define multi-name or many CNs in SSL certificates.
   - SAN is shown as a separate attribute in SSL Certificates. Here is an example of a SAN.

         openssl req  -new  \
         -key key.pem  -out request.csr -config \
         <(echo "[req]";
         echo distinguished_name=req;
         echo req_extensions=req_ext
         echo "[req_ext]";
         echo subjectAltName=@alt_names
         echo "[alt_names]";
         echo DNS.1=proxy-nosql.example.com
         echo DNS.2=proxy-nosql
         echo DNS.3=localhost
         echo IP.1=10.0.0.9
         )  \
         -subj "/C=US/ST=CA/L=San/CN=proxy-nosql.example.com"

5. Send Certificate Signing Request (CSR) data file to CA. CA will use CSR data to issue a SSL certificate.
6. CA returns a signed certificate `certificate.pem`. If it is not yet chained up with CA's certificate (`ca-chain.cert.pem`), you need to manually chain up.

       cat intermediateCA.crt > ca-chain.cert.pem
       cat rootCA.crt > ca-chain.cert.pem
       cat ca-chain.cert.pem >> certificate.pem

The following files are generated in the directory:

- `key.pem` is the server private key.
- `key-pkcs8.pem` is the server private key in PKCS#8 format.
- `certificate.pem` is the certificate chain file in pem format. It includes the server certificates issued by CA.
- `request.csr` is the server certificate request file.
- `rootCA.crt` is the root certificate provided by the CA.
- `intermediateCA.crt` is the intermediate certificate(s) provided by CA.

Additionally, a `driver.trust` file is also required if you are using the Java driver, and if the `rootCA.crt` is not listed in Java default trust store `JAVA_HOME/jre/lib/security/cacerts`. This `driver.trust` file is not required for other language drivers. To generate the `driver.trust` file, import the `rootCA.crt` certificate to the Java keystore. When prompted, provide the keystore password.

    keytool -import -alias example -keystore driver.trust -file rootCA.crt

For the Python driver, if your selected CA is not trusted by default, you need to get the `rootCA.crt` or the entire chain of certificates from CA and set the system environment variable accordingly:

Example:

    REQUESTS_CA_BUNDLE=PATH_OF_CA_FILE/rootCA.crt