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:
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:
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 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 |
|---|
use_ssl | Enable explicit SSL mode, Valid options: | 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.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:
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. | |
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 passing any additional required ssl parameters 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 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. | |