# Working with SSL

## SSL Overview

Secure-Sockets Layer (SSL) is a communications facility that encrypts all communications between a client and a target system. The DStore communications protocol in RSE supports SSL.

SSL achieves its security by using certificates to authenticate each side of a connection made between two parties. The certificates allow for the certain identification of those parties and for the negotiation of an encrypted channel for communication. The certificates themselves are files whose alteration can be easily detected and whose origin is verified by a trusted certificate authority.

Web browsers use SSL and request SSL certificates from their servers to communicate with on-line stores, banks, and other service providers. These are the same kind of certificates, but are used for a different purpose. A web browser will typically be verifying the identity of the server and will be contacting a certificate authority to do so. RSE users, on the other hand, will typically trust the target system to provide certificates to client systems so that the communications can be encrypted.

## Using SSL

Certificates are usually manufactured by a service provider (such as a target system) in concert with a certificate authority. The authority can be any entity that the target system trusts including itself. Certificates are delivered to a client system by the target system when the two are negotiating an SSL connection. When starting a connection to a server, DStore first attempts an SSL connection and then falls back to non-SSL if the SSL one fails. As a client, you don't need to be concerned with the handling of certificates at all, but you can use the RSE SSL preferences page to manage all your certificates that you have received from the target systems you have connected to in the past.

You reach the RSE preferences page by opening the `Preferences` for the workbench, expanding the `Remote Systems` category and selecting the `SSL` subcategory. There you will see operations that allow you to add certificates, rename them to make them easier to manage, remove them once they have expired, and view their contents. You would typically see one certificate for each target system that you have connected to using SSL.

## Setting Up The Server

You set up the DStore server to use SSL by editing the `ssl.properties` file in the server location. This server names the keystore and its password used for holding certificates generated using the `keytool` utility from the Java SDK. These certificates are then given to the client during SSL startup so that communications can be encrypted.

The keystore file referenced by `ssl.properties` can contain several entries but only one is used when a client connects. The entries in the keystore may themselves have passwords, but dstore assumes that these are all the same as the keystore password. It makes sense, therefore, to maintain only one keystore for the dstore server, that it have only one entry, and that it exist in the same directory as the dstore server. That entry can be a self-signed certificate.

The following command will create a keystore and add a single self-signed certificate to it.

    keytool -genkey -keystore keystore_file -alias entry_name -storepass d98kMn50sV
       -dname "CN=dstore server, OU=division, O=company, L=city, ST=state, C=country"

The command would be entered on a single line. It appears here on multiple lines for readability.

After entering this command you will be prompted to supply a password for the entry itself. You should press enter to take the default which is the keystore password.

One would then edit the ssl.properties file to use this as follows:

    daemon_keystore_file=keystore_file
    daemon_keystore_password=d98kMn50sV