Page Comparison

DRAFT

Protocols like HTTP, FTP, LLP(S), and SMTP may use TLS to encrypt communication. When using the various Network Client APIs in the Translator, TLS can be used. Please see the built-in help for full details on how to implement each API. .

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, use if you need to specify the path to a custom CA File for peer verification.
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.

Translator Net API-Specific Configuration:

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

Expand

title	HTTPS - net.http

By HTTP uses one-way TLS by default, the net.http.* client APIs are set to verify as the verify_peer and verify_host parameters are set to true. ssl parameters

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

Code Block

language	lua

-- 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.* client APIs.

 net.http ssl parameter    
local r, c, h = net.http.post{
   url='https://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 (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.

Expand

title	FTP and FTPS - net.ftp and net.ftps

FTP and FTPS use uses one-way TSLTLS by default.

net.ftp.*

, as the use_ssl parameter is set to 'try' (meaning optional)

as default.

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

, along with the verify_peer and verify_host parameters set to true.

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

Code Block

language	lua

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 related 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.

Expand

title	FTPS - net.ftps.init

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

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

Expand

title	LLP over TLS - net.tcp

Also see Enable SSL for the HL7 Server

Code Block

language	lua

local r, c, h = net.ftps.init{
      server='ftps://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 related 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.

Expand

title	SMTP - net.smtp

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

Code Block

language	lua

-- 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 related 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.

...

Versions Compared

Old Version 1

New Version Current

Key

General TLS configurations:

Translator Net API-Specific Configuration: