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.

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:

On the configuration host, navigate to the directory where the certificate file is required to be placed.

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)

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
```
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"
```
Send Certificate Signing Request (CSR) data file to CA. CA will use CSR data to issue a SSL certificate.
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