Encrypting SSL Files

Use the esp_encrypt executable to encrypt secure sockets layer (SSL) files (server.key and server.crt) for new nodes, or to re-encrypt existing files.

During installation, ESP encrypts SSL files and references them in <node-name>.xml. To indicate that they are encrypted, the files gain the .enc extension, becoming server.key.enc and server.crt.enc. Encrypt SSL files only when you configure a new node or cluster (before you start it), or when you need to re-encrypt SSL files using a new key file. By default, ESP looks for encrypted and unencrypted SSL files in ESP_HOME/cluster/keys/<cluster-name>.

The ESP installer provides only encrypted SSL files. To configure SSL files for a new cluster, either:

Use OpenSSL or a similar toolkit to generate your own server.key and server.crt in privacy enhanced mail (PEM) format, or;
Copy existing SSL files to the new cluster, then use a new cluster key file to re-encrypt the files.

Shut down all nodes in the cluster.
Use a text editor to open the cluster node configuration file:
ESP_HOME/cluster/nodes/<node-name>/<node-name>.xml
Note the value in the Cipher element. This is the cluster key file required to encrypt SSL files. If the Cipher element does not exist:
1. Create a cluster key. From a command line, navigate to ESP_HOME/bin and launch the esp_encrypt executable using the --create-key option:
```
esp_encrypt --create-key cluster.key
```
  The command writes a new key to the file cluster.key.
2. Add the Cipher element to <node-name>.xml using the following format:
```
<Security>
      .
      .
      . 
      <Cipher>  
            <File>ESP_HOME/cluster/keys/<cluster-name>/cluster.key</File> 
      </Cipher> 
      .
      .
      .
</Security> 
               
```
Although each cluster key can encrypt a specific file multiple times, it encrypts the file the same way every time. Since ESP encrypts files during installation, create a new key file to re-encrypt SSL files for a new cluster.
From a command line, navigate to ESP_HOME/bin and launch the esp_encrypt executable. Do one of the following to encrypt either the server.key file or the server.crt file:
1. To encrypt an SSL file for the first time within <node-name>.xml, use the --encrypt option with the cluster key file:
```
esp_encrypt --encrypt <key-file> --file <server.key>
```
2. To re-encrypt an SSL file within <node-name>.xml, create a new cluster.key file (see step 3). Then, use the --re-encrypt option with the cluster key file:
```
esp_encrypt --re-encrypt <old-key-file> <new-key-file> --file <server.key.enc>
```
  Note: esp_encrypt works on a file with any name, allowing you to keep multiple copies of your SSL files. At runtime, however, ESP looks for SSL files with these names:
  - server.key
  - server.crt
  - server.key.enc
  - server.crt.enc
  The setting of the ssl-key-file-encrypted property (see step 5) determines whether ESP looks for SSL files with or without the .enc extension.
The SSL files gain the .enc extension, marking them as encrypted.
In Controller|ApplicationTypes in <node-name>.xml, ensure that the ssl-key-file-encrypted property in project and ha_project ApplicationType elements is set to true.
This attribute ensures that the server recognizes the file as encrypted and decrypts it at runtime. If the attribute is not set to true, the server does not recognize the file as encrypted and tries to process the file without decrypting it, resulting in errors.
Ensure that the ssl-key-file property points to the location of the encrypted SSL files:
ESP_HOME/cluster/keys/<cluster-name>
Save and close the cluster node configuration file.