Enable TLS/SSL with the Network Client APIs

Protocols like HTTP, FTP, LLP, and SMTP may use TLS to encrypt communication. When using the various Network Client APIs in the Translator, TLS can be used.

General TLS configurations:

One-way TLS - Only the client verifies the server’s certificate.
Two-way Mutual TLS (mTLS) - Both the client and the server authenticate each other’s certificates.

There are a few key parameters used to enable these TLS configurations:

verify_peer - Ensures that the server's certificate is valid and trusted by verifying it against a Certificate Authority (CA).
verify_host - Ensures that the server's certificate is specifically intended for the hostname you are connecting to.
ca_file - Optional, if you need to specify the path to a custom CA File.
cert - For mTLS, the client is required to provide a certificate to be verified by the server.
key - For mTLS, the client is required to use a private key to provide a signature proving that the client has the private key associated with the public certificate it presents.

API-specific Configuration:

The Network Client APIs have slightly different configuration parameters, choose the dropdown below to view the specific configurations and an example with each client API:

HTTPS - net.http

By default, the net.http.* client APIs are set to verify peer and verify host

ssl parameters can be passed as a table to the net.http.* client APIs.

Parameter	Description	Default
cert	The name of your certificate file.
cert_type	Your certificate's type: PEM (default) or DER.	`PEM`
key	The name of your private key file.
key_pass	The password to access your private key.
key_type	Your private key's type: PEM, DER, or ENG.	`PEM`
ssl_engine	The engine to use with 'key_type' ENG.
verify_peer	Ensures that the server's certificate is valid and trusted by verifying it against a CA.	`true`
verify_host	Ensures that the server's certificate is specifically intended for the hostname you are connecting to.	`true`
ca_file	The certificate(s) file to use for peer verification.
issuer_cert	The PEM certificate file to validate the issuer of the peer's certificate during peer validation.
crl_file	The name of the certificate revocation list to use during peer validation.
ssl_version	Use a particular SSL version(s). Possible values for ssl_version are tls-v1, tls-v1.1, tls-v1.2, tls-v1.3. See Overriding TLS Defaults.	Tries `tls-v1.3` and then `tls-v1.2`.
cipher_list	Provide a list of ciphers in OpenSSL format to use. See Overriding TLS Defaults.
cipher_suite_list	Provide a list of TLSv1.3 cipher suites in OpenSSL format to use. See Overriding TLS Defaults.

FTP - net.ftp

FTP use one way TSL by default.

The use_ssl parameter is set to 'try' (meaning optional) as default.

To use two-way mTLS, you can provide the following parameters:

FTPS - net.ftps

net.ftps.init used to initialize the connection. By default, the force_ssl parameter is true to use TLS.

LLP over TLS - net.tcp

Also see Enable SSL for the HL7 Server.

SMTP - net.smtp

use_ssl (yes, no, try) and pass the rest of the ssl parameters individually to the net.smtp client APIs:

Parameter	Description	Default
use_ssl	Options include: yes - SSL will be used or an error will occur no - SSL will not be used try - SSL will be used if possible	`no`
certificate_file	The name of your certificate file
certificate_type	Your certificate's type: PEM or DER	`PEM`
private_key_file	The name of your private key file
private_key_pass	The password to access your private key
private_key_type	Your private key's type: PEM, DER, or ENG	`PEM`
ssl_engine	The engine to use with 'key_type' ENG
verify_peer	Verify peer certificate	`true`
verify_host	Verify host certificate matches URL	`true`
ca_file	The certificate(s) file to use for peer verification
issuer_cert	The PEM certificate file to validate the issuer of the peer's certificate during peer validation
crl_file	The name of the certificate revocation list to use during peer validation
ssl_version	Use a particular SSL version(s). Possible values for ssl_version are tls-v1, tls-v1.1, tls-v1.2, tls-v1.3. See Overriding TLS Defaults.	Tries `tls-v1.3` and then `tls-v1.2`.
cipher_list	Provide a list of ciphers in OpenSSL format to use. See Overriding TLS Defaults.
cipher_suite_list	Provide a list of TLSv1.3 cipher suites in OpenSSL format to use. See Overriding TLS Defaults.