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

HTTP uses one way TLS by default, as the verify_peer and verify_host parameters are set to true.

To use two-way mTLS, you can provide an ssl parameter can be passed as a table of values:

-- add parameters to ssl table 
local ssl_info = {
   cert= iguana.workingDir()..'configurations/web/cert.pem',
   key= iguana.workingDir()..'configurations/web/key.pem'
}
 
-- pass ssl_info to the net.http ssl parameter    
local r, c, h = net.http.post{
   url='http://localhost:6544/demo', 
   body=Data,
   ssl=ssl_info,
   live=true
}

Below is the full list of available ssl table parameters. See the built-in help documentation in the Translator for additional details:

Parameter	Description	Default
cert	The name of your certificate file.
cert_type	Your certificate's type: PEM 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 uses one way TLS by default, as the use_ssl parameter is set to 'try' (meaning optional), along with verify_peer and verify_host parameters set to true.

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

local r, c, h = net.ftp.init{
      server='ftp://speedtest.tele2.net',
      username='anonymous',
      certificate_file=iguana.workingDir()..'configurations/web/cert.pem',
      private_key_file=iguana.workingDir()..'configurations/web/key.pem',
      live=true
}

Below is the full list of available ssl parameters. See the built-in help documentation in the Translator for additional details:

Parameter	Description	Default
use_ssl	Enable explicit SSL mode, Valid options: 'all' (always enable) 'try' (optional) 'control' (control connection)	`try`
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	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.

FTPS - net.ftps

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

FTP uses one way TSL by default, as the use_ssl parameter is set to 'try' (meaning optional) as default.

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

local r, c, h = net.ftp.init{
      server='ftp://speedtest.tele2.net',
      username='anonymous',
      certificate_file=iguana.workingDir()..'configurations/web/cert.pem',
      private_key_file=iguana.workingDir()..'configurations/web/key.pem',
      live=true
}

Below is the full list of available ssl parameters. See the built-in help documentation in the Translator for additional details:

Parameter	Description	Default
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	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.
ssl_auth	Use 'ssl' to try AUTH SSL before AUTH TLS, or 'tls' to try AUTH TLS first then AUTH SSL.
force_ssl	Normally 'yes', but can be changed to 'control' to require SSL on the control connection, or 'no' to allow insecure (non-SSL) connections entirely.	`yes`
use_ccc	Clear control channel: shutdown SSL/TLS on the control connection after authentication. If set to 'active' we will initiate the shutdown; use 'passive' to allow the server to start the shutdown.

LLP over TLS - net.tcp

Also see Enable SSL for the HL7 Server.

SMTP - net.smtp

SMTP does not have TLS enabled by default. The parameter use_ssl (yes, no, try) must be set to yes or try along with additional ssl parameters individually to the net.smtp client APIs:

-- load custom field configurations
local Configs = component.fields()

local r, c, h = net.smtp.send{
      server = Configs.emailServer,
      username = Configs.username,
      password = Configs.password,
      to = {Configs.recipients},
      from = Configs.sender,
      header = {Subject = 'Email Subject'},
      body = Data,
      use_ssl = 'yes', 
      certificate_file = iguana.workingDir()..'configurations/web/cert.pem',
      private_key_file = iguana.workingDir()..'configurations/web/key.pem',
      live=true
}

Below is the full list of available ssl parameters. See the built-in help documentation in the Translator for additional details:

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.