Enabling security for host factory (default certificate)

Enable security for host factory by using a default self-signed certificate on Linux® hosts for testing purposes. TLS communication between the host factory server and client enables secure access for the host factory RESTful APIs.

About this task

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

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

With security for web servers enabled during installation, security for host factory is also enabled; on Linux hosts, the host factory client automatically uses a built-in self-signed certificate for its TLS sessions. If you disabled security for web servers during installation and want to enable TLS for host factory for the first time on Linux hosts, you can use the default self-signed certificate purely for testing purposes. The self-signed certificate is available at $EGO_TOP/wlp/usr/shared/resources/security/. For testing on Windows hosts, you must generate your own PKCS certificate; use the OpenSSL utility or other methods to generate your certificate in .p12 format. See Enabling security for host factory (external certificate).

Procedure

Follow these steps to enable TLS for host factory with the default self-signed certificate on Linux hosts.

Stop the HostFactory service:
```
egosh service stop HostFactory
```
Edit the hostfactoryconf.json file at $HF_TOP/$HF_VERSION/ to specify the path to the default self-signed certificate file and private key in the HF_REST_TRANSPORT_ARG parameter. 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 TLS 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:
```
"HF_REST_TRANSPORT_ARG": "$EGO_DEFAULT_TS_PARAMS"
```
  2. In ego.conf, set the CERTIFICATE and PRIVATE_KEY subparameters for the EGO_DEFAULT_TS_PARAMS parameter to the default certificate file and private key. Optionally, you can also define the CIPHER, CAFILE, and SERVER_AUTH subparameters. For example:
```
EGO_DEFAULT_TS_PARAMS: "SSL[CERTIFICATE=/opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/user.pem,
PRIVATE_KEY=/opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/user.key,CIPHER=ECDHE-ECDSA-AES256-GCM-SHA384,
CAFILE=/opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/cacert.pem,SERVER_AUTH={}]"
```
- To define security parameters separately for host factory, in hostfactoryconf.json, set the HF_REST_TRANSPORT_ARG parameter to the default certificate file and private key as subparameters in the following format:
```
"HF_REST_TRANSPORT_ARG": "SSL[subparameter, ...]" 
```
  where the subparameters are:
  - CERTIFICATE: Path to the user.pem certificate file, which is at $EGO_TOP/wlp/usr/shared/resources/security/.
  - PRIVATE_KEY: Path to the user.key private key file, which is at $EGO_TOP/wlp/usr/shared/resources/security/.
  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 parameters.
  For example:
```
"HF_REST_TRANSPORT_ARG": "SSL[CERTIFICATE=/opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/user.pem,
PRIVATE_KEY=/opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/user.key,CIPHER=ECDHE-ECDSA-AES256-GCM-SHA384,
CAFILE=/opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/cacert.pem,SERVER_AUTH={}]"
```
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 TLS 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.
Start the HostFactory service:
```
egosh service start HostFactory
```

Results

You can now access the host factory APIs over TLS with the default self-signed certificate.