Configure SSL for CGE

How to configure SSL as part of implementing CGE security

SSL provides three types of protection for data and users. The first protection it affords is assurance that the user is interacting with a web UI that is, in fact, the web UI for your CGE instance. By providing an SSL certificate that is correctly signed, your web UI tells users (and their browsers) that they are talking to the right web UI. To the user, that means that it is safe to present a username and password to the web UI, that the user can safely present sensitive information to the web UI without concern that an impostor web UI will steal it, and that any data coming from the web UI is trustworthy, since it comes from a verified web UI. This means that the user can trust the data for decision making and trust the database with new data. The second protection SSL affords is encryption of authentication secrets so that the user can present a username and password without fear of these secrets being intercepted in-flight to the web UI. The third protection SSL affords is encryption of query and update data so that the user can query and update the database without fear of sensitive query results or sensitive update data being either intercepted or modified in flight to and from the web UI.

There are two kinds of SSL certificates that may be used to provide SSL protection of the web UI:

Verified - A verified SSL certificate is purchased from a third party Certificate Authority (CA). The CA provides a secure verification service. Certificates from that authority can be verified securely by any web browser or SSL enabled application with no user intervention.
Self-signed - A self-signed certificate is one that the owner of the web UI can generate for themselves, but which has no third-party verification. Users are prompted by their browsers to accept or reject self-signed certificates, and are usually advised not to accept them. In some cases, where users know for sure what your certificate looks like and that you are trustworthy, they might be willing to accept a self-signed certificate. In general, self-signed certificates are used for prototyping and debugging of web UI deployments. When it comes time to go live with data, it is a good idea to obtain a verified certificate and replace the self-signed certificate with it. CGE provides the cge-cli generate keystore command to help with creation and importation of SSL certificates.

Using a Verified SSL Certificate - Obtaining a verified SSL certificate is outside the scope of this discussion, but once you have an SSL Certificate downloaded to your site and want to install it, installation is simple. The following command will import the certificate into your keystore for you to use:
```
$ cge-cli generate keystore --import your.cer --keystore ~/.cge/keystore
```
This will produce a file named keystore in the .cge directory in the home directory. This is the default place that CGE looks for CGE configuration files. The keys in the keystore file will be found by CGE by default by looking in this file. If a different directory is used (or, for example, a directory on HDFS) for CGE's configuration, it is possible to choose the path or URL of that directory as the argument to the --keystore option. The SSL certificate will be imported from the file user.cer which is the verified certificate downloaded from the certificate authority.
CAUTION: In order for the imported certificate to be usable it must contain the private key as well as the Digital signature from the certificate authority. Without the private key a certificate cannot be used for SSL
Using a Self-Signed SSL Certificate - To use a self-signed certificate, execute the following command:
```
$ cge-cli generate keystore --self-signed --keystore ~/.cge/keystore
```
The system will be prompt for a bunch of information about the self-signed certificate and then it will be created in the .cge directory in the home directory. This is the default place that CGE looks for CGE configuration files. The keys in the keystore file will be found by CGE by default by looking in this file. If using a different directory (or, for example, a directory on HDFS) for CGE's configuration, it is possible to choose the path or URL of that directory as the argument to the --keystore option
Giving Your Web-UI Access to Your SSL Keystore - In addition to file protections, both the SSL keystore and certificates can be password protected. In this case, cge-cli fe needs to know these passwords to access the certificate. These passwords need to be stored in the CGE properties file (by default $HOME/.cge/cge.properties) as follows:
```
cge.cli.server.ssl.password = MyKeyStorePassword
cge.cli.server.ssl.key-password = MyCertificatePassword
```
By default these passwords are stored in clear text. If you want them stored in an obfuscated (one-way hashed) form, you can use the following command to set up these passwords:
```
$ cge-cli generate properties --ssl-passwords
```
The system will prompt for these two passwords, obfuscate them, and add them to the cge.properties file.
Securing Your SSL Certificate - The SSL certificate contains sensitive information and should be properly secured. With it, it is possible for an impostor to impersonate the SSL protected web-site. While the information in the SSL keystore is somewhat obfuscated, it is best not to treat it as secured simply by those means. Using Linux file permissions you can further secure the keystore to help prevent unauthorized use. If a user needs to run the Web-UI (i.e. invoking the cge-cli fe command) the user can simply make the file mode readable only by themself. For example:
```
$ ls -l keystore
-rw-r--r-- 1 erl criemp 2222 Sep 26 10:56 keystore
$ chmod 600 keystore
$ ls -l keystore
-rw------- 1 erl criemp 2222 Sep 26 10:56 keystore
```
Take similar steps to protect the cge.properties file and any verified certificate files, since these contain similarly sensitive data.