#!/bin/cat
$Id: FAQ.SSL_errors.txt,v 1.9 2019/12/11 15:38:37 gilles Exp gilles $

This document is also available online at
https://imapsync.lamiral.info/FAQ.d/
https://imapsync.lamiral.info/FAQ.d/FAQ.SSL_errors.txt


=======================================================================
               Imapsync SSL errors
=======================================================================

Questions answered in this FAQ are:

Q. What are the errors
  DEBUG: .../IO/Socket/SSL.pm:1165: local error: SSL write error
  or
  DEBUG: .../IO/Socket/SSL.pm:1088: local error: SSL read error

Q. What can I do to avoid those "SSL read/write errors"?

Q. SSL connect attempt failed SSL 
   routines:SSL23_GET_SERVER_HELLO:sslv3 alert handshake failure


Now the questions again with their answers.

=======================================================================
Q. What are the errors
  DEBUG: .../IO/Socket/SSL.pm:1165: local error: SSL write error
  or
  DEBUG: .../IO/Socket/SSL.pm:1088: local error: SSL read error


R1.Like they claim, those errors are SSL errors. SSL is not directly
   done by imapsync but by an underlying Perl module called
   IO::Socket::SSL. Those errors arise sometimes and sometimes
   they form a serie that ends with imapsync auto-abortion.
   Those errors happen with some hosts but not with others,
   it's often Exchange or Office365. I don't know what exactly happens.
   Those errors happen more often on Windows than on Linux.


=======================================================================
Q. What can I do to avoid those "SSL read/write errors"?

R0. Windows users: upgrade to imapsync.exe release 1.836 (or next ones)
    Those errors don't appear with recent releases, post 1.836

R1. Remove all ssl/tls encryption

  imapsync ...   --nossl1 --notls1 --nossl2 --notls2

R2. If you don't want to quit encryption, rerun imapsync until the 
    complete sync is over. Those errors are not at the same place 
    each time, so imapsync will sync remaining messages at each run
    until none remains.

R3. Run imapsync on a Linux machine, a VM is ok, there are less
    SSL errors on Unix.
    
R4. Use https://imapsync.lamiral.info/X/
    It's a Linux host so response R3 applies there.

R5. Set up a ssltunnel proxy to the host.
    Read the file FAQ.Security.txt for an example to set up
    a ssltunnel proxy.

=======================================================================
Q. SSL connect attempt failed SSL 
   routines:SSL23_GET_SERVER_HELLO:sslv3 alert handshake failure

R1. Use: 

   imapsync ... --sslargs1 'SSL_cipher_list=DEFAULT' 
   or    
   imapsync ... --sslargs2 'SSL_cipher_list=DEFAULT' 

   depending on where the error occurs, host1 or host2 or both.

R2. If it doesn't work, I let you try other things, 
    I quote the "SSL_version" section of
    https://metacpan.org/pod/IO::Socket::SSL (Module version: 2.066)

    imapsync ...  --sslargs1 SSL_version=SSLv2
    imapsync ...  --sslargs1 SSL_version=TLSv1_2
    
    SSLv2 and TLSv12 are just examples depending on your context
    (--ssl1 or --tls1, and also the imap server encryption scheme)
    
Feedback on what worked for you (and possibly hy) is welcome!

https://metacpan.org/pod/IO::Socket::SSL
...
SSL_version

Sets the version of the SSL protocol used to transmit data.
'SSLv23' uses a handshake compatible with SSL2.0, SSL3.0 and TLS1.x, 
while 'SSLv2', 'SSLv3', 'TLSv1', 'TLSv1_1', 'TLSv1_2', or 'TLSv1_3' 
restrict handshake and protocol to the specified version. 
All values are case-insensitive. Instead of 'TLSv1_1', 'TLSv1_2', and 'TLSv1_3' 
one can also use 'TLSv11', 'TLSv12', and 'TLSv13'.

Support for 'TLSv1_1', 'TLSv1_2', and 'TLSv1_3' 
requires recent versions of Net::SSLeay and openssl.

Independent from the handshake format you can limit to set of 
accepted SSL versions by adding !version separated by ':'.
The default SSL_version is 'SSLv23:!SSLv3:!SSLv2' which means, 
that the handshake format is compatible to SSL2.0 and higher, 
but that the successful handshake is limited to TLS1.0 and higher, 
that is no SSL2.0 or SSL3.0 because both of these versions have
serious security issues and should not be used anymore.

You can also use !TLSv1_1 and !TLSv1_2 to 
disable TLS versions 1.1 and 1.2 while still allowing TLS version 1.0.

Setting the version instead to 'TLSv1' might break interaction 
with older clients, which need and SSL2.0 compatible handshake.

On the other side some clients just close the connection 
when they receive a TLS version 1.1 request. 
In this case setting the version 
to 'SSLv23:!SSLv2:!SSLv3:!TLSv1_1:!TLSv1_2' might help.


=======================================================================
=======================================================================