Merge tag 'v0.5.4' into debian/latest

Release version 0.5.4

4 files changed, 51 insertions, 25 deletions

diff --git a/doc/build.md b/doc/build.md
index 4a4f80d..b9291f7 100644
--- a/doc/build.md
+++ b/doc/build.md
@@ -1,7 +1,7 @@
 % Build instructions
 % [Guilhem Moulin](mailto:guilhem@fripost.org)
 
-On Debian 9 (codename *Stretch*) and later, installing [`interimap`(1)]
+On Debian 10 (codename *Buster*) and later, installing [`interimap`(1)]
 is a single command away:
 
     $ sudo apt install interimap
@@ -24,7 +24,7 @@ following Perl modules:
   * [`Getopt::Long`](https://perldoc.perl.org/Getopt/Long.html) (*core module*)
   * [`MIME::Base64`](https://perldoc.perl.org/MIME/Base64.html) (*core module*) — if authentication is required
   * [`List::Util`](https://perldoc.perl.org/List/Util.html) (*core module*)
-  * [`Net::SSLeay`](https://metacpan.org/pod/Net::SSLeay) ≥1.73
+  * [`Net::SSLeay`](https://metacpan.org/pod/Net::SSLeay) ≥1.83
   * [`POSIX`](https://perldoc.perl.org/POSIX.html) (*core module*)
   * [`Socket`](https://perldoc.perl.org/Socket.html) (*core module*)
   * [`Time::HiRes`](https://perldoc.perl.org/Time/HiRes.html) (*core module*) — if `logfile` is set
@@ -84,12 +84,12 @@ Debian GNU/Linux users can also use [`gbp`(1)] from
 [`git-buildpackage`](https://tracker.debian.org/pkg/git-buildpackage) in
 order to build their own packages:
 
-    $ git checkout debian
+    $ git checkout debian/latest
     $ gbp buildpackage
 
 Alternatively, for the development version:
 
-    $ git checkout debian
+    $ git checkout debian/latest
     $ git merge master
     $ gbp buildpackage --git-force-create --git-upstream-tree=BRANCH
 
diff --git a/doc/getting-started.md b/doc/getting-started.md
index 1d059b4..83d3ba9 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -198,7 +198,7 @@ for the sake of clarity we start from an empty file here.
     shell process doesn't linger around during the IMAP session.)
 
  3. And finally append a `[remote]` section with your account
-    information at `imap.example.org` (adapt the values accordingly):
+    information at `imap.example.net` (adapt the values accordingly):
 
         $ cat >>${XDG_CONFIG_HOME:-~/.config}/interimap/config <<-EOF
 
diff --git a/doc/interimap.1.md b/doc/interimap.1.md
index 7df0100..2d2a637 100644
--- a/doc/interimap.1.md
+++ b/doc/interimap.1.md
@@ -317,7 +317,9 @@ Valid options are:
 
 *host*
 
-:   Server hostname, for `type=imap` and `type=imaps`.
+:   Server hostname or IP address, for `type=imap` and `type=imaps`.
+    The value can optionally be enclosed in square brackets to force its
+    interpretation as an IP literal (hence skip name resolution).
     (Default: `localhost`.)
 
 *port*
@@ -327,8 +329,8 @@ Valid options are:
 
 *proxy*
 
-:   An optional SOCKS proxy to use for TCP connections to the IMAP
-    server (`type=imap` and `type=imaps` only), formatted as
+:   Optional SOCKS proxy to use for TCP connections to the IMAP server
+    (`type=imap` and `type=imaps` only), formatted as
     `PROTOCOL://[USER:PASSWORD@]PROXYHOST[:PROXYPORT]`.
     If `PROXYPORT` is omitted, it is assumed at port 1080.
     Only [SOCKSv5][RFC 1928] is supported (with optional
@@ -418,15 +420,19 @@ Valid options are:
 
 *SSL_verify*
 
-:   Whether to verify the server certificate chain.
+:   Whether to verify the server certificate chain, and match its
+    Subject Alternative Name (SAN) or Subject CommonName (CN) against
+    the value of the *host* option.
+    (Default: `YES`.)
+
     Note that using *SSL_fingerprint* to specify the fingerprint of the
     server certificate provides an independent server authentication
-    measure as it ignores the CA chain.
-    (Default: `YES`.)
+    measure as it pins directly its key material and ignore its chain of
+    trust.
 
 *SSL_CApath*
 
-:   Directory to use for server certificate verification if
+:   Directory to use for server certificate verification when
     `SSL_verify=YES`.
     This directory must be in “hash format”, see [`verify`(1ssl)] for
     more information.
@@ -434,7 +440,14 @@ Valid options are:
 *SSL_CAfile*
 
 :   File containing trusted certificates to use during server
-    certificate verification if `SSL_verify=YES`.
+    certificate verification when `SSL_verify=YES`.
+
+*SSL_hostname*
+
+:   Name to use for the TLS SNI (Server Name Indication) extension.  The
+    default value is taken from the *host* option when it is a hostname,
+    and to the empty string when it is an IP literal.
+    Setting *SSL_hostname* to the empty string explicitly disables SNI.
 
 Supported extensions  {#supported-extensions}
 ====================
@@ -568,6 +581,6 @@ A _getting started_ guide is available [there](getting-started.html).
 
 [INI file]: https://en.wikipedia.org/wiki/INI_file
 [PCRE]: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions
-[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html
-[`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/verify.html
+[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html
+[`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-verify.html
 [`doveadm-deduplicate`(1)]: https://wiki.dovecot.org/Tools/Doveadm/Deduplicate
diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md
index 98ec2ef..c9500e0 100644
--- a/doc/pullimap.1.md
+++ b/doc/pullimap.1.md
@@ -139,7 +139,9 @@ Valid options are:
 
 *host*
 
-:   Server hostname, for `type=imap` and `type=imaps`.
+:   Server hostname or IP address, for `type=imap` and `type=imaps`.
+    The value can optionally be enclosed in square brackets to force its
+    interpretation as an IP literal (hence skip name resolution).
     (Default: `localhost`.)
 
 *port*
@@ -149,8 +151,8 @@ Valid options are:
 
 *proxy*
 
-:   An optional SOCKS proxy to use for TCP connections to the IMAP
-    server (`type=imap` and `type=imaps` only), formatted as
+:   Optional SOCKS proxy to use for TCP connections to the IMAP server
+    (`type=imap` and `type=imaps` only), formatted as
     `PROTOCOL://[USER:PASSWORD@]PROXYHOST[:PROXYPORT]`.
     If `PROXYPORT` is omitted, it is assumed at port 1080.
     Only [SOCKSv5][RFC 1928] is supported (with optional
@@ -237,15 +239,19 @@ Valid options are:
 
 *SSL_verify*
 
-:   Whether to verify the server certificate chain.
+:   Whether to verify the server certificate chain, and match its
+    Subject Alternative Name (SAN) or Subject CommonName (CN) against
+    the value of the *host* option.
+    (Default: `YES`.)
+
     Note that using *SSL_fingerprint* to specify the fingerprint of the
     server certificate provides an independent server authentication
-    measure as it ignores the CA chain.
-    (Default: `YES`.)
+    measure as it pins directly its key material and ignore its chain of
+    trust.
 
 *SSL_CApath*
 
-:   Directory to use for server certificate verification if
+:   Directory to use for server certificate verification when
     `SSL_verify=YES`.
     This directory must be in “hash format”, see [`verify`(1ssl)] for
     more information.
@@ -253,7 +259,14 @@ Valid options are:
 *SSL_CAfile*
 
 :   File containing trusted certificates to use during server
-    certificate verification if `SSL_verify=YES`.
+    certificate verification when `SSL_verify=YES`.
+
+*SSL_hostname*
+
+:   Name to use for the TLS SNI (Server Name Indication) extension.  The
+    default value is taken from the *host* option when it is a hostname,
+    and to the empty string when it is an IP literal.
+    Setting *SSL_hostname* to the empty string explicitly disables SNI.
 
 Control flow  {#control-flow}
 ============
@@ -378,5 +391,5 @@ Standards
 [`fetchmail`(1)]: https://www.fetchmail.info/
 [`getmail`(1)]: http://pyropus.ca/software/getmail/
 [`write`(2)]: https://man7.org/linux/man-pages/man2/write.2.html
-[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html
-[`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/verify.html
+[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html
+[`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-verify.html