aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorGuilhem Moulin <guilhem@debian.org>2021-01-01 12:44:17 +0100
committerGuilhem Moulin <guilhem@debian.org>2021-01-01 12:44:17 +0100
commitd782c12d603fcbcc8bcf7b18860e9a16a27f4b1b (patch)
tree789fa2c3e7d08b08e82b6e5fa999ac7584fe3416 /doc
parent2ce885e19f4a5f18da30c35dc7da7a204e2ceb58 (diff)
parent3d818bf7e24f0757bcd13f30118d229e5a6b5448 (diff)
Merge tag 'debian/0.5.5-1' into debian/buster-backports
interimap Debian release 0.5.5-1
Diffstat (limited to 'doc')
-rw-r--r--doc/getting-started.md2
-rw-r--r--doc/interimap.1.md59
-rw-r--r--doc/pullimap.1.md65
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).