Description:
------------
This relates to https://bugs.php.net/bug.php?id=76928

I'm repurposing that issue as a documentation issue for a couple of reasons:

1. ext-imap is listed as unmaintained (https://wiki.php.net/todo/extensions) and I assume that's why no one has officially replied

2. The documentation for both /tls and /ssl options does not mirror how libc-client actually works

3. I don't believe it's actually a bug (see below)

Skip to the end if you want to see what I propose as changes...

--

For background, the below references libc-client source code which is available at the mirror site:
http://ftp.ntua.gr/pub/net/mail/imap/

So let’s look at how imap_open uses the /ssl and /tls options. There’s other code that sets some flags based on these options but ultimately we end up here:

./osdep/unix/ssl_unix.c:706

if (!(stream->context = SSL_CTX_new (start_tls ?
                                       TLSv1_server_method () :
                                       SSLv23_server_method ())))

Associated function definitions: https://man.openbsd.org/SSL_CTX_new.3#DESCRIPTION

The /tls option sets start_tls and hence uses TLSv1 (1.0). This is hardcoded and not possible to change.

The /ssl option uses SSLv23 which is flexible and supports the highest protocol version available. The following context options are set:

#define SSLCIPHERLIST "ALL:!LOW"
SSL_CTX_set_options (stream->context,SSL_OP_ALL);
/* set cipher list */
if (!SSL_CTX_set_cipher_list (stream->context,SSLCIPHERLIST))
      syslog (LOG_ALERT,"Unable to set cipher list %.80s, host=%.80s",
              SSLCIPHERLIST,tcp_clienthost ());

SSL_OP_ALL is a list of bug workarounds for maximum compatibility: 
https://www.openssl.org/docs/man1.1.0/man3/SSL_CTX_clear_options.html

SSLCIPHERLIST is set to allow anything except eNULL and LOW:
https://www.openssl.org/docs/man1.0.2/man1/ciphers.html

--

In the previous issue issue aurelien dot grimal at tech-tips dot fr commented:

> The problem is only concerning IMAP with StartTLS (port 143) and
> not direct SSL on IMAPS (port 993). So IMAP with StartTLS can't
> use further than TLS1.0, and IMAP on SSL can use TLS1.2.

I've verified that the /tls option on a secure/non-secure port uses TLSv1 while /ssl on secure port uses TLS 1.2

--

With all this in mind, I propose the following changes:

/tls option:
 * should strictly only be used in combination with insecure ports (STARTTLS will upgrade the connection). If you’re using on a secure port then /ssl is the better option
 * Should advise against use as it will ALWAYS use TLSv1

/ssl option:
 * should be used on implicit secure ports (e.g. 993/995)
* should be clear that the highest available protocol version will be used (SSL or TLS). Note: this could mean an insecure protocol is used e.g. when using outdated openssl