Enable TLS/SSL with the Network Client APIs

Protocols like HTTP, FTP(S), 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:

  1. One-way TLS - Only the client verifies the server’s certificate.

  2. 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:

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='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

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 uses one-way TLS by default, as the use_ssl parameter is set to 'try' (meaning optional), 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:

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

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 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:

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

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.

 

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

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

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.

 

Â