#!/bin/cat
$Id: FAQ.Authentication_failure.txt,v 1.16 2022/08/17 09:18:17 gilles Exp gilles $

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

=======================================================================
              Imapsync authentication issues
=======================================================================

Questions answered in this FAQ are:

Q. Imapsync fails with the following error, what can I do?
Host1 failure: Error login on [imap.example.com] with user [foo] auth [LOGIN]: 2 NO [AUTHENTICATIONFAILED] Authentication failed

Q. Imapsync fails with the following error, what can I do?
   Host2 failure: Error login on [imap.example.com] with user [foo] auth [LOGIN]: 2 BAD Invalid characters in atom 

Now the questions again with their answers.


=======================================================================
Q. Imapsync fails with the following error, what can I do?
Host1 failure: Error login on [imap.example.com] with user [foo] auth [LOGIN]: 2 NO [AUTHENTICATIONFAILED] Authentication failed


R. One over four imapsync synchronizations end up quickly with the error message 
   "Authentication failed" or "NO LOGIN failed" or a similar message.
   Authentication failure is the primary failure with imapsync
   and since nothing tangible can be done without authentication, 
   this stage must succeed to go further.

Here is some advice to get you to pass this difficult stage of authentication:

  * Triple-check each credential parameter. It's not always a password problem,
    it can be the wrong host or the wrong user.
    There are three parameters on each side:
     * triple check --host1
     * triple check --user1
     * triple check --password1
     * triple check --host2
     * triple check --user2
     * triple check --password2

   * If you can authenticate successfully with another imap client software 
     like Thunderbird or Outlook or Sparrow then it is a very good sign to 
     authenticate successfully with imapsync. Examine the parameters of 
     this other imap client and copy them as is for imapsync.

   * Use option --showpasswords
     At the beginning of the output, imapsync dumps all its command
     line parameters; it's the line after "Command line used:".
     With --showpasswords, imapsync prints the passwords received 
     instead of the string MASKED. It helps with debugging quoting issues.
     Option --showpasswords shows passwords again when the IMAP dialog
     is dumped by --debugimap option. Search for a line like 
     "Sending: 2 LOGIN test1 secret1" (secret1 is the password here).

   * It is sometimes very hard to quote correctly unusual characters,
     especially on Windows (and Mac sometimes). See 
     https://imapsync.lamiral.info/FAQ.d/FAQ.Passwords_on_Windows.txt
     https://imapsync.lamiral.info/FAQ.d/FAQ.Passwords_on_Unix.txt
     https://imapsync.lamiral.info/FAQ.d/FAQ.Passwords_on_Mac.txt
     
     The quickest trick may be to change the password temporally
     with easy characters like the classical alphabet, one long
     string still ensures strong security.

   * Sometimes some servers announce they support LOGIN but it
     fails because the authentication mechanism
     working is something else like CRAM-MD5 or PLAIN. 
     So:
       * Try --authmech1 CRAM-MD5 (or --authmech2 CRAM-MD5)
       * Try --authmech1 PLAIN    (or --authmech2 PLAIN)

    * Manually test a login via ssl.
      Use either ncat or telnet-ssl or openssl commands, like in the 
      following examples with imap.gmail.com server:

  ncat --ssl -C imap.gmail.com 993
  telnet-ssl -z ssl  imap.gmail.com 993
  openssl s_client -crlf  -connect imap.gmail.com:993

Replace imap.gmail.com by your imap server.
The three commands do the same work here.

Typical dialog for an imap LOGIN command:
  
* OK Gimap ready for requests from 78.196.254.58 q1mb175739668wix
a LOGIN "gilles.lamiral@gmail.com" "secret" 
* CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE ... ESEARCH
a OK gilles.lamiral@gmail.com Gilles Lamiral authenticated (Success)
b LOGOUT
* BYE LOGOUT Requested
b OK 73 good day (Success)

The client part you have to type is 
a LOGIN ... 
b LOGOUT
while replacing ... by your credentials values,
other lines are the server responses. Letters 
a and b are identifiers of IMAP commands, you have to 
type them but you can chose any string instead of a or b.

Some other examples:

     ncat --ssl test.lamiral.info 993
     c1 LOGIN test1 "secret1"
     c2 LOGOUT

     openssl s_client -crlf  -connect test.lamiral.info:993
     c1 LOGIN test1 "secret1" 
     c2 LOGOUT

     ncat --ssl -C outlook.office365.com 993
     a LOGIN gilles.lamiral@outlook.com topsecret
     b LOGOUT

     telnet-ssl -z ssl test.lamiral.info 993
     c1 LOGIN test1 "secret1" 
     c2 LOGOUT


=======================================================================
Q. Imapsync fails with the following error, what can I do?
   Host2 failure: Error login on [imap.example.com] with user [foo] auth [LOGIN]: 2 BAD Invalid characters in atom 

R. It might be a Dovecot imap server. The password string might 
   contain special characters that Dovecot doesn't like. Change them.
 
 =======================================================================
 =======================================================================