Merge tag 'v0.5.5' into debian/latest

Release version 0.5.5

3 files changed, 82 insertions, 44 deletions

diff --git a/doc/getting-started.md b/doc/getting-started.md
index 83d3ba9..74fc8da 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -20,7 +20,7 @@ format][mbox]).  Local mail clients usually access it directly.  They
 also often maintain their own cache in order to speed up message header
 listing and searches.
 
-While most bidirectional synchronisation software (such as [OfflineIMAP])
+While most bidirectional synchronization software (such as [OfflineIMAP])
 are able to handle a mail storage in Maildir format, *InterIMAP is
 not*.  Instead, InterIMAP needs an [IMAP4rev1] server on *both* peers
 to synchronize.  This may sound like a severe limitation at first, but by
diff --git a/doc/interimap.1.md b/doc/interimap.1.md
index 2d2a637..2d588ae 100644
--- a/doc/interimap.1.md
+++ b/doc/interimap.1.md
@@ -249,7 +249,7 @@ Valid options are:
     Two wildcards are available, and passed verbatim to the IMAP server:
     a ‘\*’ character matches zero or more characters, while a ‘%’
     character matches zero or more characters up to the hierarchy
-    delimiter.  Hardcoding the hierarchy delimiter in this setting is
+    delimiter.  Hard-coding the hierarchy delimiter in this setting is
     not advised because the server might silently change it at some
     point. A null character should be used instead.  For instance, if
     *list-mailbox* is set `"foo\x00bar"` then, assuming the hierarchy
@@ -309,7 +309,7 @@ Valid options are:
     `type=imap` and `type=imaps` are respectively used for IMAP and IMAP
     over SSL/TLS connections over an INET socket.
     `type=tunnel` causes `interimap` to create an unnamed pair of
-    connected sockets for interprocess communication with a *command*
+    connected sockets for inter-process communication with a *command*
     instead of opening a network socket.
     Note that specifying `type=tunnel` in the `[remote]` section makes
     the default *database* to be `localhost.db`.
@@ -383,19 +383,32 @@ Valid options are:
 
 *SSL_protocols*
 
-:   A space-separated list of SSL protocols to enable or disable (if
-    prefixed with an exclamation mark `!`.  Known protocols are `SSLv2`,
-    `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`.  Enabling a
-    protocol is a short-hand for disabling all other protocols.
-    (Default: `!SSLv2 !SSLv3 !TLSv1 !TLSv1.1`, i.e., only enable TLSv1.2
-    and above.)
+:   Space-separated list of SSL/TLS protocol versions to explicitly
+    enable (or disable if prefixed with an exclamation mark `!`).
+    Potentially known protocols are `SSLv2`, `SSLv3`, `TLSv1`,
+    `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL
+    version used.
+    Enabling a protocol is a short-hand for disabling all other
+    protocols.
 
-*SSL_cipher_list*
+    *DEPRECATED*: Use *SSL_protocol_min* and/or *SSL_protocol_max*
+    instead.
 
-:   The cipher list to send to the server.  Although the server
-    determines which cipher suite is used, it should take the first
-    supported cipher in the list sent by the client.  See
-    [`ciphers`(1ssl)] for more information.
+*SSL_protocol_min*, *SSL_protocol_max*
+
+:   Set minimum resp. maximum SSL/TLS protocol version to use for the
+    connection.  Potentially recognized values are `SSLv3`, `TLSv1`,
+    `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL
+    version used.
+
+*SSL_cipherlist*, *SSL_ciphersuites*
+
+:   Sets the TLSv1.2 and below cipher list resp. TLSv1.3 cipher suites.
+    The combination of these lists is sent to the server, which then
+    determines which cipher to use (normally the first supported one
+    from the list sent by the client).  The default suites depend on the
+    OpenSSL version and its configuration, see [`ciphers`(1ssl)] for
+    more information.
 
 *SSL_fingerprint*
 
@@ -415,12 +428,12 @@ Valid options are:
 
     Specifying multiple digest values can be useful in key rollover
     scenarios and/or when the server supports certificates of different
-    types (for instance RSA+ECDSA).  In that case the connection is
-    aborted when none of the specified digests matches.
+    types (for instance a dual-cert RSA/ECDSA setup).  In that case the
+    connection is aborted when none of the specified digests matches.
 
 *SSL_verify*
 
-:   Whether to verify the server certificate chain, and match its
+:   Whether to 1/ verify the server certificate chain; and 2/ match its
     Subject Alternative Name (SAN) or Subject CommonName (CN) against
     the value of the *host* option.
     (Default: `YES`.)
@@ -430,6 +443,14 @@ Valid options are:
     measure as it pins directly its key material and ignore its chain of
     trust.
 
+*SSL_CAfile*
+
+:   File containing trusted certificates to use during server
+    certificate verification when `SSL_verify=YES`.
+
+    Trusted CA certificates are loaded from the default system locations
+    unless one (or both) of *SSL_CAfile* or *SSL_CApath* is set.
+
 *SSL_CApath*
 
 :   Directory to use for server certificate verification when
@@ -437,10 +458,8 @@ Valid options are:
     This directory must be in “hash format”, see [`verify`(1ssl)] for
     more information.
 
-*SSL_CAfile*
-
-:   File containing trusted certificates to use during server
-    certificate verification when `SSL_verify=YES`.
+    Trusted CA certificates are loaded from the default system locations
+    unless one (or both) of *SSL_CAfile* or *SSL_CApath* is set.
 
 *SSL_hostname*
 
diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md
index c9500e0..89969b2 100644
--- a/doc/pullimap.1.md
+++ b/doc/pullimap.1.md
@@ -106,14 +106,14 @@ Valid options are:
 
 *deliver-ehlo*
 
-:   Hostname to use in `EHLO` or `LHLO` commands.
+:   Name to use in `EHLO` or `LHLO` commands.
     (Default: `localhost.localdomain`.)
 
 *deliver-rcpt*
 
 :   Message recipient.  Note that the local part needs to quoted if it
     contains special characters; see [RFC 5321] for details.
-    (Default: the username associated with the effective uid of the
+    (Default: the username associated with the effective user ID of the
     `pullimap` process.)
 
 *purge-after*
@@ -123,7 +123,7 @@ Valid options are:
     `SEARCH` criterion ignoring time and timezone.)
     If *purge-after* is set to `0` then messages are deleted immediately
     after delivery.  Otherwise `pullimap` issues an IMAP `SEARCH` (or
-    extended `SEARCH` on servers advertizing the [`ESEARCH`][RFC 4731]
+    extended `SEARCH` on servers advertising the [`ESEARCH`][RFC 4731]
     capability) command to list old messages; if `--idle` is set then
     the `SEARCH` command is issued again every 12 hours.
 
@@ -133,7 +133,7 @@ Valid options are:
     `type=imap` and `type=imaps` are respectively used for IMAP and IMAP
     over SSL/TLS connections over an INET socket.
     `type=tunnel` causes `pullimap` to create an unnamed pair of
-    connected sockets for interprocess communication with a *command*
+    connected sockets for inter-process communication with a *command*
     instead of opening a network socket.
     (Default: `imaps`.)
 
@@ -202,19 +202,32 @@ Valid options are:
 
 *SSL_protocols*
 
-:   A space-separated list of SSL protocols to enable or disable (if
-    prefixed with an exclamation mark `!`.  Known protocols are `SSLv2`,
-    `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`.  Enabling a
-    protocol is a short-hand for disabling all other protocols.
-    (Default: `!SSLv2 !SSLv3 !TLSv1 !TLSv1.1`, i.e., only enable TLSv1.2
-    and above.)
+:   Space-separated list of SSL/TLS protocol versions to explicitly
+    enable (or disable if prefixed with an exclamation mark `!`).
+    Potentially known protocols are `SSLv2`, `SSLv3`, `TLSv1`,
+    `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL
+    version used.
+    Enabling a protocol is a short-hand for disabling all other
+    protocols.
 
-*SSL_cipher_list*
+    *DEPRECATED*: Use *SSL_protocol_min* and/or *SSL_protocol_max*
+    instead.
 
-:   The cipher list to send to the server.  Although the server
-    determines which cipher suite is used, it should take the first
-    supported cipher in the list sent by the client.  See
-    [`ciphers`(1ssl)] for more information.
+*SSL_protocol_min*, *SSL_protocol_max*
+
+:   Set minimum resp. maximum SSL/TLS protocol version to use for the
+    connection.  Potentially recognized values are `SSLv3`, `TLSv1`,
+    `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL
+    version used.
+
+*SSL_cipherlist*, *SSL_ciphersuites*
+
+:   Sets the TLSv1.2 and below cipher list resp. TLSv1.3 cipher suites.
+    The combination of these lists is sent to the server, which then
+    determines which cipher to use (normally the first supported one
+    from the list sent by the client).  The default suites depend on the
+    OpenSSL version and its configuration, see [`ciphers`(1ssl)] for
+    more information.
 
 *SSL_fingerprint*
 
@@ -234,12 +247,12 @@ Valid options are:
 
     Specifying multiple digest values can be useful in key rollover
     scenarios and/or when the server supports certificates of different
-    types (for instance RSA+ECDSA).  In that case the connection is
-    aborted when none of the specified digests matches.
+    types (for instance a dual-cert RSA/ECDSA setup).  In that case the
+    connection is aborted when none of the specified digests matches.
 
 *SSL_verify*
 
-:   Whether to verify the server certificate chain, and match its
+:   Whether to 1/ verify the server certificate chain; and 2/ match its
     Subject Alternative Name (SAN) or Subject CommonName (CN) against
     the value of the *host* option.
     (Default: `YES`.)
@@ -249,6 +262,14 @@ Valid options are:
     measure as it pins directly its key material and ignore its chain of
     trust.
 
+*SSL_CAfile*
+
+:   File containing trusted certificates to use during server
+    certificate verification when `SSL_verify=YES`.
+
+    Trusted CA certificates are loaded from the default system locations
+    unless one (or both) of *SSL_CAfile* or *SSL_CApath* is set.
+
 *SSL_CApath*
 
 :   Directory to use for server certificate verification when
@@ -256,10 +277,8 @@ Valid options are:
     This directory must be in “hash format”, see [`verify`(1ssl)] for
     more information.
 
-*SSL_CAfile*
-
-:   File containing trusted certificates to use during server
-    certificate verification when `SSL_verify=YES`.
+    Trusted CA certificates are loaded from the default system locations
+    unless one (or both) of *SSL_CAfile* or *SSL_CApath* is set.
 
 *SSL_hostname*
 
@@ -322,7 +341,7 @@ In more details, `pullimap` works as follows:
     to terminate it gracefully.
 
  3. Issue a `UID STORE` command to mark all retrieved messages (and
-    stalled UIDs found in the *statefile* after the eigth byte) as
+    stalled UIDs found in the *statefile* after the eighth byte) as
     `\Seen`.
 
  4. Update the *statefile* with the new UIDNEXT value (bytes 5-8).