Enabling SSL for host factory (external certificate)

Enable SSL for host factory by using a properly chained certificate from a trusted certificate authority (CA). SSL communication between the host factory server and client enables secure access for the host factory RESTful APIs.

About this task

SSL communication for host factory follows your SSL setting for RESTful web servers, which is enabled during installation by default. If you disabled SSL for web server communication during installation, SSL for host factory is also disabled.

Important: Ensure that you use the same SSL setting (either enabled or disabled) for the cluster management console, RESTful web servers, and host factory. You cannot enable SSL for one and disable SSL for others; without a uniform configuration, errors occur. When SSL is uniformly enabled, you can use different certificates and keys as required.

When SSL is enabled for your production environment, you must use a properly chained certificate that is issued or signed by a trusted certificate authority (CA). You can use your own self-signed certificate or an external certificate. When you have a valid certificate (either self-signed or external), follow these steps to import your certificate for use with host factory. (For testing on Linux® hosts, you can use the built-in self-signed certificate at $EGO_TOP/wlp/usr/shared/resources/security/; see Enabling SSL for host factory (default certificate)).

Note: For Windows hosts (both in testing and production environments), you must generate your own PKCS certificate; use the OpenSSL utility or other methods to generate your PKCS certificate. Ensure that you use a certificate in .p12 format and that the certificate contains the server-side certificate and the private key. Windows 2012 and higher versions do not support .p12 certificate files without a password; ensure that you set an export password for the file. For example:

openssl pkcs12 -export -in cert.pem -out cert.p12 -inkey prvtkey.pem

For more information on generating certificates with OpenSSL, refer to OpenSSL documentation.

Procedure

Follow these steps to enable SSL for host factory with an external certificate from a trusted CA.

Stop the HostFactory service:
```
egosh service stop HostFactory
```
Specify your certificate file and private key in the hostfactoryconf.json file at:
- $HF_TOP/$HF_VERSION/ on Linux.
- %HF_TOP%\%HF_VERSION%\ on Windows.
You can define this configuration at the cluster level and retrieve it for host factory, or define it exclusively for host factory.
- To retrieve cluster-level SSL configuration from the ego.conf file on a management host that runs the HostFactory service:
  1. In hostfactoryconf.json, set the HF_REST_TRANSPORT_ARG parameter to an environment variable. For example:
    - On Linux:
```
"HF_REST_TRANSPORT_ARG": "$EGO_DEFAULT_TS_PARAMS"
```
    - On Windows:
```
"HF_REST_TRANSPORT_ARG": "$EGO_DEFAULT_TS_PARAMS_WIN"
```
  2. In ego.conf, set the CERTIFICATE and PRIVATE_KEY subparameters for the EGO_DEFAULT_TS_PARAMS parameter on Linux and EGO_DEFAULT_TS_PARAMS_WIN_P12 on Windows to the certificate file and private key. Optionally, you can also define the CIPHER, CAFILE, and SERVER_AUTH subparameters. For example:
    - On Linux:
```
EGO_DEFAULT_TS_PARAMS: "SSL[CERTIFICATE=/opt/cert.pem,PRIVATE_KEY=/opt/cert.key,CIPHER=ECDHE-ECDSA-AES256-GCM-SHA384,
CAFILE=/opt/cacert.pem,SERVER_AUTH={}]"
```
    - On Windows:
```
EGO_DEFAULT_TS_PARAMS_WIN_P12: "SSL[CERTIFICATE=C:\cert.p12,PRIVATE_KEY=p12_export_password,
CIPHER=ECDHE-ECDSA-AES256-GCM-SHA384,CAFILE=C:\cacert.pem,SERVER_AUTH={}]"
```
- To define SSL parameters separately for host factory, set HF_REST_TRANSPORT_ARG in hostfactoryconf.json to specify the certificate file and its private key as subparameters in the following format:
```
"HF_REST_TRANSPORT_ARG": "SSL[subparameter, ...]" 
```
  where the subparameters are:
  - CERTIFICATE: Path to the certificate file. For Windows hosts, the certificate file must be in P12 format.
  - PRIVATE_KEY: Path to the private key file.
  The HF_REST_TRANSPORT_ARG parameter uses the same subparameters as the EGO_DEFAULT_TS_PARAMS parameter in ego.conf. Optionally, you can also define the CIPHER, CAFILE, and SERVER_AUTH subparameters.
  For example:
  - On Linux:
```
"HF_REST_TRANSPORT_ARG": "SSL[CERTIFICATE=/opt/user.pem,PRIVATE_KEY=/opt/user.key,
CIPHER=ECDHE-ECDSA-AES256-GCM-SHA384,CAFILE=/opt/cacert.pem,SERVER_AUTH={}]"
```
  - On Windows:
```
"HF_REST_TRANSPORT_ARG": "SSL[CERTIFICATE=C:\\user.p12,PRIVATE_KEY=p12.user.key,
CIPHER=ECDHE-ECDSA-AES256-GCM-SHA384,CAFILE=C:\\cacert.pem,SERVER_AUTH={}]"
```
    Ensure that you use double-backslashes (\\) in JSON files on Windows.
Optional: Set the HF_REST_LISTEN_PORT parameter in hostfactoryconf.json to specify the listening port for host factory client requests. Valid value is either 0 or a port number in the range 1024 - 65535. The default SSL port is 9443. If you specify 0 or if the parameter is not defined, a random port is assigned.
For example:
```
"HF_REST_LISTEN_PORT": 9443
```
Save your changes to hostfactoryconf.json.
Import the host factory CA certificate to the default server keystore (serverKeyStore.jks) on the primary host. If high availability is enabled, ensure that you import the host factory CA certificate also on each primary-candidate host.
- If you are using your own self-signed certificate, use the keytool -importcert command to import your certificate as described in Enabling SSL for the RESTful APIs using a self-signed certificate.
- If you are using an external certificate, use the keytool -importcert command to import your certificate as described in Enabling SSL for the RESTful APIs using an external certificate.
Start the HostFactory service:
```
egosh service start HostFactory
```

Results

You can now access the host factory APIs over SSL with your own self-signed or production certificate.