-
-
Notifications
You must be signed in to change notification settings - Fork 2
dotls.1
dotls - Generic TLS/SSL protocol wrapper for non-TLS programs
dotls [-nNdcLftDMCTz ] [-s smtp|pop3] prog arg ...
The dotls program is used by applications to encrypt a network connection using SSL/TLS, without having the application deal with the gory details of SSL/TLS.
dotls is not usually run directly from the command line. An application typically creates a network connection, then runs dotls with appropriate options to encrypt the network connection with SSL/TLS. dotls can also do opportunistic SSL/TLS (or delayed encryption) for SMTP or POP3 in server mode.
dotls can be run under tcpserver(1) to provide SSL/TLS or opportunistic TLS for qmail-smtpd, qmail-pop3d. This is known as server mode.
dotls can be run under tcpclient(1) to connect to any SSL/TLS enabled server. This is known is client mode. This gets enabled when you use -T or the -C options.
If the environment variable BANNER is set, and -s option has not been specified, dotls can print the value of BANNER environment variable, on the network to the client, before starting a SSL/TLS session.
dotls will directly execute prog if NOTLS environment variable is set. This can be set using the tcpserver(1) rules file to bypass SSL/TLS for hosts that don't work if STARTTLS or TLS is enabled.
dotls is not needed by indimail-mta, as all features offered by dotls are built-in tcpserver(1) and tcpclient(1), provided by ucspi-tcp package from indimail-mta git repo at, https://github.com/indimail/indimail-mta/tree/master/ucspi-tcp-x
dotls intercepts client commands for the EHLO, CAPA, STARTTLS, STLS, QUIT requests. For the EHLO and CAPA requests, it offers STARTTLS and STLS capability on behalf of prog. All other commands are passed unaltered to prog.
dotls sets the environment variable TLS_PROVIDER with details of the TLS connnection if the -z option is passed.
-q
Quiet. Do not print error messages.
-Q
(Default.) Print error messages.
-v
Verbose. Print error messages and status messages.
-d certdir
Directory having certificates. Default is /etc/indimail/certs.
-n certfile
Use certfile as the certificate The certificate to use and is required
for SSL/TLS servers. certfile must not be world-readable. This option
overrides environment variable TLS_CERTFILE. If this is not provided,
the file /etc/indimail/certs/clientcert.pem will be used.
-c cafile
Specify cafile as the file containing CA certificates. Sometimes,
special CA certificates are needed if an intermediate certificate used
by your issuing CA expires. Note that the file given with -c is passed
to SSL_CTX_load_verify_locations and thus may contain several CA
certificates, which will be used during SSL connection negotiation to
close any gap in the certificate chain. If this is not provided, the
file /etc/indimail/certs/clientca.pem will be used.
-L crlfile
A list of Certificate Revocation Lists (CRLs). If present it should
contain the CRLs of the CAs in cafile and client certs that will be
checked for revocation. If this is not provided, the file
/etc/indimail/certs/clientcrl.pem will be used.
-f cipher_list
Use ciphers listed in cipher_list. Without this dotls uses
TLS_CIPHER_LIST environment variable if set (or system configured
PROFILE=SYSTEM ciphers for TLSv1.2 and below). For TLSv1.3 the
environment variable TLS_CIPHER_SUITE is used instead. See
openssl-ciphers(1ossl).
-M tls_method
Use tls_method to set client/server method / protocol. This will be
one of SSLv23, SSLv3, TLSv1, TLSv1_1, TLSv1_2, TLSv1_3 values. Without
this option, the actual protocol version used will be negotiated to the
highest version mutually supported by the client and the server. The
supported protocols at this moment are TLSv1.2 and TLSv1.3. Older
protocols have been deprecated and removed. It is best not to use this
option to let dotls chose the highest protocol supported.
-N
Client-initiated renegotiation is disabled by default. This option
enables it.
-z
Set TLS_PROVIDER environment variables with details of the TLS/SSL
connection. This environment variable will be available for prog when
using TLS/SSL.
-D timeoutdata
Quit if read or write to/from program or application exceeds
timeoutdata seconds.
-t timeoutconn
Timeout on TLS/SSL connect in client mode or TLS/SSL accept in server
mode if attempt exceeds timeoutconn seconds.
-s startlsType
Specify smtp or pop3 for starttlsType. In this mode, dotls will
offer STARTTLS extension. It will initiate SSL/TLS negotation only when
it receives STARTTLS command from client. Currently, smtp and
pop3 are supported. If this is not provided, dotls will directly
initiate a TLS session.
-T
tcpclient mode. In this mode, dotls acts as a tls client,
expecting tcpclient be connected to a port where data is being
encrypted with TLS/SSL. prog will be run reading descriptor 0 for
input and descriptor 1 for output.
-C
tcpclient mode. In this mode, dotls acts as a tls client,
expecting tcpclient be connected to a port where data is being
encrypted with TLS/SSL. prog will be run reading descriptor 6 for
input and descriptor 7 for output. Use this if prog has been
specifically written for the original tcpclient by djb.
dotls reads the following environment variables in order to configure the SSL/TLS protocol:
CERTDIR
Directory having servercert.pem. This can be overriden by the -d option.
Default is /etc/indimail/certs.
TLS_CERTFILE
client/server ssl certificate. This can be overriden by the -n option.
Default is /etc/indimail/certs/servercert.pem in server mode and
/etc/indimail/certs/clientcert.pem in client mode.
CLIENTCA
CA certificate. This can be overriden by the -c option. Default is
/etc/indimail/certs/clientca.pem
CLIENTCRL
Certificate Revocation Lists. Default is
/etc/indimail/certs/clientcrl.pem
TLS_CIPHER_LIST
A set of OpenSSL cipher strings. Multiple ciphers contained in a string
should be separated by a colon. This can be overriden by the -f option.
1. Add STARTTLS extension for qmail-smtpd
tcpserver 0 25 /usr/bin/dotls -s smtp /var/qmail/bin/qmail-smtpd
2. Provide SMTPS service on port 465 for qmail-smtpd
tcpserver 0 465 /usr/bin/dotls /var/qmail/bin/qmail-smtpd
3. Add STLS extension for qmail-pop3d
tcpserver 0 110 /usr/bin/dotls -s pop3 qmail-popup host \
checkpassword qmail-pop3d Maildir
4. Provide POP3S service on port 993 for qmail-pop3d
tcpserver 0 993 /usr/bin/dotls qmail-popup host checkpassword \
qmail-pop3d Maildir
5. Run a script under tcpclient that connects to a SSL server on port 5555
read from descriptor 0 reads from network & write to descriptor 1 writes
to network
tcpclient 0 5555 /usr/bin/dotls -T /usr/bin/myscript
6. Run a script under tcpclient that connects to a SSL server on port 5555
read from descriptor 6 reads from network & write to descriptor 7 writes
to network
tcpclient 0 5555 /usr/bin/dotls -CT /usr/bin/myscript
This NOTE is valid only when dotls(1) is acting as a server.
A script update_tmprsadh in cron uses the following openssl commands to pre-generate 2048 bites RSA and DH parameters. You can pass --maxbits argument to update_tmprsadh to generate these with higher bits. You can set the environment variable SSL_BITS to make tcpclient choose specific bits for the RSA/DH parameters. These files are generated in /etc/indimail/certs. update_rmprsadh is installed to be run by cron if you have installed indimail from Open Build Service.
cd /etc/indimail/certs
/usr/bin/openssl genrsa -out rsa2048.pem 2048
/usr/bin/openssl dhparam -out -2 dh2048.pem 2048
Some ciphersuites may use ephemeral Diffie-Hellman (DH) key exchange. In these cases, the session data is negotiated using the ephemeral/temporary DH key and the key supplied and certified by the certificate chain is only used for signing. Anonymous ciphers (without a permanent server key) also use ephemeral DH keys.
Using ephemeral DH key exchange yields forward secrecy as the connection can only be decrypted when the DH key is known. By generating a temporary DH key inside the server application that is lost when the application is left, it becomes impossible for an attacker to decrypt past sessions, even if they get hold of the normal (certified) key, as this key was only used for signing.
In order to perform a DH key exchange the server must use a DH group (DH parameters) and generate a DH key. The server will always generate a new DH key during the negotiation.
As generating DH parameters is extremely time consuming, an application should not generate the parameters on the fly. DH parameters can be reused, as the actual key is newly generated during the negotiation.
Typically applications should use well known DH parameters that have built-in support in OpenSSL. The macro SSL_set_dh_auto(3ossl) configures OpenSSL to use the default built-in DH parameters for the SSL object. Passing a value of 1 in the onoff parameter switches the feature on, and passing a value of 0 switches it off. The default setting is off.
If "auto" DH parameters are switched on then the parameters will be selected to be consistent with the size of the key associated with the server's certificate. If there is no certificate (e.g. for PSK ciphersuites), then it it will be consistent with the size of the negotiated symmetric cipher key.
Applications may supply their own DH parameters instead of using the built-in values. This approach is discouraged and applications should in preference use the built-in parameter support described above. Applications wishing to supply their own DH parameters should call SSL_set0_tmp_dh_pkey(3ossl) to supply the parameters for SSL. The parameters should be supplied in the dhpkey argument as an EVP_PKEY containg DH parameters. Ownership of the dhpkey value is passed to the SSL_CTX or SSL object as a result of this call, and so the caller should not free it if the function call is succesful..
tcpclient(1), tcpserver(1), qmail-smtpd(8), qmail-pop3d(8) openssl-ciphers(1ossl).