Previous Next JavaScript must be enabled to correctly display this content

## Guidelines for Generating Self-Signed Certificate and Private Key using OpenSSL

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

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 self-signed certificate 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. Use one of the following OpenSSL command to generate the self-signed certificate and private key. When prompted, provide a secure password of your choice for the certificate file.

   Note:

   All prompt password will use `123456` in this example.

       openssl req -x509 -days 365 -newkey rsa:4096 -keyout key.pem -out certificate.pem
        -subj "/C=US/ST=CA/L=San/CN=*.example.com/emailAddress=localhost@oracle.com"
       or
       openssl req -x509 -days 365 -newkey rsa:4096 -keyout key.pem -out certificate.pem
        -subj "/C=US/ST=CA/L=San/CN=proxy-nosql.example.com/emailAddress=localhost@oracle.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 -x509 -days 365 -newkey rsa:4096 -sha256   \
           -keyout key.pem  -out certificate.pem -extensions san -config \
           <(echo "[req]";
             echo distinguished_name=req;
             echo "[san]";
             echo subjectAltName=DNS:proxy-nosql,IP:10.0.0.9
             ) \
           -subj "/C=US/ST=CA/L=San/CN=proxy-nosql.example.com/emailAddress=localhost@example.com"

3. 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 files are generated in the directory:

- `key.pem` is the private key.
- `key-pkcs8.pem` is the private key in `PKCS#8` format.
- `certificate.pem` is the SSL certificate file in pem format.

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

Additionally, a `driver.trust` file is also required if you are using the Java driver. This `driver.trust` file is not required for other language drivers. To generate the `driver.trust` file, import the certificate to the Java keystore. When prompted, provide the keystore password.

    keytool -import -alias example -keystore driver.trust -file certificate.pem