From f247a5ed7f92b46341ce51bfe6ee4893d23715be Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 11 Dec 2020 12:38:37 +0100 Subject: manpages: improve wording. --- doc/interimap.1.md | 2 +- doc/pullimap.1.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index 2d2a637..5f19d66 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -420,7 +420,7 @@ Valid options are: *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`.) diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md index c9500e0..ea93ed3 100644 --- a/doc/pullimap.1.md +++ b/doc/pullimap.1.md @@ -239,7 +239,7 @@ Valid options are: *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`.) -- cgit v1.2.3 From e3b95b0da424e55682c8c7b025d9d272a4a35ffe Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 11 Dec 2020 15:09:15 +0100 Subject: libinterimap: remove default SSL_protocols value. Namely, use the system default instead of "!SSLv2 !SSLv3 !TLSv1 !TLSv1.1". As of Debian Buster (OpenSSL 1.1.1) this does not make a difference, however using the system default provides better compatibility with future libssl versions. --- doc/interimap.1.md | 11 +++++------ doc/pullimap.1.md | 11 +++++------ 2 files changed, 10 insertions(+), 12 deletions(-) (limited to 'doc') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index 5f19d66..9cfec7a 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -383,12 +383,11 @@ 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.) +: A space-separated list of SSL protocols to explicitly 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. *SSL_cipher_list* diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md index ea93ed3..84cae46 100644 --- a/doc/pullimap.1.md +++ b/doc/pullimap.1.md @@ -202,12 +202,11 @@ 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.) +: A space-separated list of SSL protocols to explicitly 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. *SSL_cipher_list* -- cgit v1.2.3 From feeb91998a29ca040f6e5dd103e09507a6355e32 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 11 Dec 2020 18:39:46 +0100 Subject: libinterimap: deprecate SSL_protocols and introduce SSL_protocol_{min,max}. Using the libssl interface simplifies our protocol black/whitelist greatly; this only allows simple min/max bounds, but holes are arguably not very useful here. Using the new settings bumps the required libssl version to 1.1.0. --- doc/interimap.1.md | 9 +++++++++ doc/pullimap.1.md | 9 +++++++++ 2 files changed, 18 insertions(+) (limited to 'doc') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index 9cfec7a..9b14a49 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -389,6 +389,15 @@ Valid options are: Enabling a protocol is a short-hand for disabling all other protocols. + *Deprecacted*: Use *SSL_protocol_min* and/or *SSL_protocol_max* + instead. + +*SSL_protocol_min*, *SSL_protocol_max* + +: Set minimum resp. maximum SSL/TLS protocol version to use for the + connection. Accepted values are `SSLv3`, `TLSv1`, `TLSv1.1`, + `TLSv1.2`, and `TLSv1.3`. + *SSL_cipher_list* : The cipher list to send to the server. Although the server diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md index 84cae46..028cbaa 100644 --- a/doc/pullimap.1.md +++ b/doc/pullimap.1.md @@ -208,6 +208,15 @@ Valid options are: Enabling a protocol is a short-hand for disabling all other protocols. + *Deprecacted*: Use *SSL_protocol_min* and/or *SSL_protocol_max* + instead. + +*SSL_protocol_min*, *SSL_protocol_max* + +: Set minimum resp. maximum SSL/TLS protocol version to use for the + connection. Accepted values are `SSLv3`, `TLSv1`, `TLSv1.1`, + `TLSv1.2`, and `TLSv1.3`. + *SSL_cipher_list* : The cipher list to send to the server. Although the server -- cgit v1.2.3 From ea120902dfe146cd7f04a289da9fa05a9e06e44c Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 11 Dec 2020 21:24:32 +0100 Subject: typofix, spelling --- doc/getting-started.md | 2 +- doc/interimap.1.md | 17 +++++++++-------- doc/pullimap.1.md | 23 ++++++++++++----------- 3 files changed, 22 insertions(+), 20 deletions(-) (limited to 'doc') 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 9b14a49..2310cb3 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,13 +383,14 @@ Valid options are: *SSL_protocols* -: A space-separated list of SSL protocols to explicitly enable or - disable (if prefixed with an exclamation mark `!`. Known protocols - are `SSLv2`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`. +: Space-separated list of SSL/TLS protocol versions to explicitly + 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. - *Deprecacted*: Use *SSL_protocol_min* and/or *SSL_protocol_max* + *DEPRECATED*: Use *SSL_protocol_min* and/or *SSL_protocol_max* instead. *SSL_protocol_min*, *SSL_protocol_max* @@ -398,7 +399,7 @@ Valid options are: connection. Accepted values are `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`. -*SSL_cipher_list* +*SSL_cipherlist* : The cipher list to send to the server. Although the server determines which cipher suite is used, it should take the first @@ -428,7 +429,7 @@ Valid options are: *SSL_verify* -: Whether to 1/ verify the server certificate chain, and 2/ 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`.) diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md index 028cbaa..cf6ec52 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,13 +202,14 @@ Valid options are: *SSL_protocols* -: A space-separated list of SSL protocols to explicitly enable or - disable (if prefixed with an exclamation mark `!`. Known protocols - are `SSLv2`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`. +: Space-separated list of SSL/TLS protocol versions to explicitly + 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. - *Deprecacted*: Use *SSL_protocol_min* and/or *SSL_protocol_max* + *DEPRECATED*: Use *SSL_protocol_min* and/or *SSL_protocol_max* instead. *SSL_protocol_min*, *SSL_protocol_max* @@ -217,7 +218,7 @@ Valid options are: connection. Accepted values are `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`. -*SSL_cipher_list* +*SSL_cipherlist* : The cipher list to send to the server. Although the server determines which cipher suite is used, it should take the first @@ -247,7 +248,7 @@ Valid options are: *SSL_verify* -: Whether to 1/ verify the server certificate chain, and 2/ 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`.) @@ -330,7 +331,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). -- cgit v1.2.3 From 8c43ed9baa905d907a6aad77de2282a852ba69a9 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sun, 13 Dec 2020 17:43:52 +0100 Subject: libinterimap: use default locations for trusted CA certificates when neither CAfile nor CApath are set. In particular, OpenSSL's default locations can be overridden by the SSL_CERT_FILE resp. SSL_CERT_DIR environment variables, see SSL_CTX_load_verify_locations(3ssl). This bumps the minimum OpenSSL version to 1.1.0 (when SSL_verify is used). --- doc/interimap.1.md | 14 ++++++++++---- doc/pullimap.1.md | 14 ++++++++++---- 2 files changed, 20 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index 2310cb3..63d5ab0 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -439,6 +439,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 @@ -446,10 +454,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 cf6ec52..05cbcaf 100644 --- a/doc/pullimap.1.md +++ b/doc/pullimap.1.md @@ -258,6 +258,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 @@ -265,10 +273,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* -- cgit v1.2.3 From ae2e4297e0a298444e94e89264e5d814a34ec61d Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sun, 13 Dec 2020 18:47:51 +0100 Subject: manual: improve wording. --- doc/interimap.1.md | 4 ++-- doc/pullimap.1.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index 63d5ab0..bcd27f9 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -424,8 +424,8 @@ 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* diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md index 05cbcaf..94fa831 100644 --- a/doc/pullimap.1.md +++ b/doc/pullimap.1.md @@ -243,8 +243,8 @@ 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* -- cgit v1.2.3 From 1a19feb7a4b3d70f44e4e1fb0f9920b063842422 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Thu, 17 Dec 2020 14:54:34 +0100 Subject: manuals: Clarify that known TLS protocol versions depend on the OpenSSL version used. --- doc/interimap.1.md | 12 +++++++----- doc/pullimap.1.md | 12 +++++++----- 2 files changed, 14 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index bcd27f9..ae6224b 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -384,9 +384,10 @@ Valid options are: *SSL_protocols* : Space-separated list of SSL/TLS protocol versions to explicitly - enable (or disable if prefixed with an exclamation mark `!`). Known - protocols are `SSLv2`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, and - `TLSv1.3`. + 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. @@ -396,8 +397,9 @@ Valid options are: *SSL_protocol_min*, *SSL_protocol_max* : Set minimum resp. maximum SSL/TLS protocol version to use for the - connection. Accepted values are `SSLv3`, `TLSv1`, `TLSv1.1`, - `TLSv1.2`, and `TLSv1.3`. + connection. Potentially recognized values are `SSLv3`, `TLSv1`, + `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL + version used. *SSL_cipherlist* diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md index 94fa831..b0bc2fd 100644 --- a/doc/pullimap.1.md +++ b/doc/pullimap.1.md @@ -203,9 +203,10 @@ Valid options are: *SSL_protocols* : Space-separated list of SSL/TLS protocol versions to explicitly - enable (or disable if prefixed with an exclamation mark `!`). Known - protocols are `SSLv2`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, and - `TLSv1.3`. + 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. @@ -215,8 +216,9 @@ Valid options are: *SSL_protocol_min*, *SSL_protocol_max* : Set minimum resp. maximum SSL/TLS protocol version to use for the - connection. Accepted values are `SSLv3`, `TLSv1`, `TLSv1.1`, - `TLSv1.2`, and `TLSv1.3`. + connection. Potentially recognized values are `SSLv3`, `TLSv1`, + `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL + version used. *SSL_cipherlist* -- cgit v1.2.3 From 57988c83bb4b3f1780f045880ac4a8f36a51c55c Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Thu, 17 Dec 2020 17:38:17 +0100 Subject: libinterimap: new option SSL_ciphersuites to set the TLSv1.3 ciphersuites. Also, clarify that SSL_cipherlist only applies to TLSv1.2 and below. See SSL_CTX_set_cipher_list(3ssl). --- doc/interimap.1.md | 12 +++++++----- doc/pullimap.1.md | 12 +++++++----- 2 files changed, 14 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/interimap.1.md b/doc/interimap.1.md index ae6224b..2d588ae 100644 --- a/doc/interimap.1.md +++ b/doc/interimap.1.md @@ -401,12 +401,14 @@ Valid options are: `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL version used. -*SSL_cipherlist* +*SSL_cipherlist*, *SSL_ciphersuites* -: 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. +: 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* diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md index b0bc2fd..89969b2 100644 --- a/doc/pullimap.1.md +++ b/doc/pullimap.1.md @@ -220,12 +220,14 @@ Valid options are: `TLSv1.1`, `TLSv1.2`, and `TLSv1.3`, depending on the OpenSSL version used. -*SSL_cipherlist* +*SSL_cipherlist*, *SSL_ciphersuites* -: 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. +: 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* -- cgit v1.2.3