-
-
Notifications
You must be signed in to change notification settings - Fork 3
sslerator.8
sslerator - TLS/SSL protocol wrapper
sslerator [ options ] prog arg ...
The sslerator 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. sslerator is used by the IndiMail proxy IMAP and POP3 servers.
sslerator is not usually run directly from the commandline. An application typically creates a network connection, then runs sslerator with appropriate options to encrypt the network connection with SSL/TLS.
sslerator(8) can be replaced by the dotls(1) program and in future will be deprecated.
-d certdir
Directory having certificates. Default is /etc/indimail/certs.
-n certfile
The certificate to use and is required for SSL/TLS servers. certfile
must not be world-readable. This option overrides environment variable
TLS_CERTFILE.
-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.
-c cipherfile
Use ciphers listed in cipherfile. 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 and above,
TLS_CIPHER_SUITE is used instead.
-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. The
actual protocol version used will be negotiated to the highest version
mutually supported by the client and the server. The supported protocols
are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3. Ths option must not be
used to avoid the version-specific methods as they are deprecated.
-N
Client-initiated renegotiation is disabled by default. This option
enables it.
-t timeoutdata
Timeout after timeoutdata seconds if no data is received. Default is
from the control file /etc/indimail/control/timeoutremote
-T timeoutconn
Timeout TLS/SSL accept if attempt exceeds timeoutconn seconds. Default
is 60 seconds.
-b banner
Use banner as greeting. This is overridden if -s startls stmp option
is given. This option overrides environment variable BANNER.
-e
Write ssl library errors to the network. If not provided, sslerator
will write all ssl library errors to fd 2. This mode is disabled if
environment variable TCPREMOTEIP is defined (running under
tcpserver(1)).
-s
Issue SMTP Greeting code on successful TLS/SSL negotiation. This code is
obtained from prog. prog could be something like qmail-smtpd from
qmail/indimail/notqmail/netqmail package.
-f socket
network descriptor to use for communication. This is the socket
descriptor returned by the accept(2) call or any of the descriptors
duplicated to the socket descriptor. For tcpserver(1), this will be
descriptor 0 and 1 and you can use either.
sslerator reads the following environment variables in order to configure the SSL/TLS protocol:
**TLS_CERTFILE=**filename
The certificate to use. The -n option overrides this. TLS_CERTFILE
is required for SSL/TLS servers, and is optional for SSL/TLS clients.
filename must not be world-readable.
**SSL_CIPHER=**cipherList
A set of OpenSSL cipher strings. Multiple ciphers contained in a string
should be separated by a colon. The -c option overrides this.
**BANNER=**string
Banner to issue before starting SSL/TLS negotiation.
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 sslerator choose specific bits for the RSA/DH parameters. These files are generated in @qsysconfdir@/certs. update_rmprsadh is installed to be run by cron if you have installed indimail from Open Build Service.
/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..