aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--.gitignore1
-rw-r--r--Changelog109
-rw-r--r--Makefile23
-rw-r--r--README93
-rw-r--r--doc/build.md8
-rw-r--r--doc/getting-started.md4
-rw-r--r--doc/interimap.1.md99
-rw-r--r--doc/pullimap.1.md102
-rw-r--r--doc/template.html2
-rwxr-xr-xinterimap8
-rw-r--r--interimap.sample8
-rw-r--r--lib/Net/IMAP/InterIMAP.pm289
-rwxr-xr-xpullimap14
-rw-r--r--pullimap.sample4
-rw-r--r--tests/certs/.gitignore4
-rwxr-xr-xtests/certs/generate44
-rw-r--r--tests/config/dovecot/dhparams.pem (renamed from tests/snippets/dovecot/dhparams.pem)0
-rw-r--r--tests/config/dovecot/imapd.conf (renamed from tests/snippets/dovecot/imapd.conf)0
-rw-r--r--tests/config/dovecot/interimap-required-capabilities.conf (renamed from tests/snippets/dovecot/interimap-required-capabilities.conf)0
-rw-r--r--tests/config/dovecot/lmtpd.conf (renamed from tests/snippets/dovecot/lmtpd.conf)0
-rw-r--r--tests/config/dovecot/ssl.conf5
-rw-r--r--tests/list3
-rwxr-xr-xtests/preauth-plaintext/imapd4
-rw-r--r--tests/preauth-plaintext/t2
-rwxr-xr-xtests/run11
-rw-r--r--tests/snippets/dovecot/dovecot.key5
-rw-r--r--tests/snippets/dovecot/dovecot.pem11
-rw-r--r--tests/snippets/dovecot/ssl.conf4
-rwxr-xr-xtests/starttls-injection/imapd24
-rw-r--r--tests/starttls/t9
l---------tests/tls-ciphers/interimap.remote1
l---------tests/tls-ciphers/remote.conf1
-rw-r--r--tests/tls-ciphers/t31
-rw-r--r--tests/tls-pin-fingerprint/t50
-rw-r--r--tests/tls-protocols/openssl.cnf14
-rw-r--r--tests/tls-protocols/t76
l---------tests/tls-rsa+ecdsa/interimap.remote1
-rw-r--r--tests/tls-rsa+ecdsa/remote.conf5
-rw-r--r--tests/tls-rsa+ecdsa/t56
-rw-r--r--tests/tls-sni/interimap.remote3
-rw-r--r--tests/tls-sni/remote.conf7
-rw-r--r--tests/tls-sni/t66
-rw-r--r--tests/tls-verify-peer/interimap.remote1
-rw-r--r--tests/tls-verify-peer/t103
-rw-r--r--tests/tls/t9
45 files changed, 1002 insertions, 312 deletions
diff --git a/.gitignore b/.gitignore
index 9dae7e6..2267ea4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
*~
+*.bak
/doc/*.1
/doc/*.html
!/doc/template.html
diff --git a/Changelog b/Changelog
index 6ee44fc..f82f68b 100644
--- a/Changelog
+++ b/Changelog
@@ -1,3 +1,102 @@
+interimap (0.5.6) upstream;
+
+ - Bump required Net::SSLeay version to 1.86_06 as it's when get_version()
+ was introduced.
+ - doc/template.html: remove type attribute from <style/> element.
+
+ -- Guilhem Moulin <guilhem@fripost.org> Fri, 01 Jan 2021 16:05:53 +0100
+
+interimap (0.5.5) upstream;
+
+ * libinterimap: remove default SSL_protocols value "!SSLv2 !SSLv3
+ !TLSv1 !TLSv1.1" and use the system default instead. 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.
+ * libinterimap: deprecate SSL_protocols, obsoleted by new settings
+ 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.
+ * 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).
+ * libinterimap: _start_ssl() now fails immediately with OpenSSL <1.1.0.
+ It could in principle still work with earlier versions if the new
+ settings SSL_protocol_{min,max} are not used, however it's cumbersome
+ to do individual checks for specific settings, let alone maintain
+ test coverage with multiple OpenSSL versions.
+ * 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).
+ + `make release`: also bump libinterimap version and pin it in 'use'
+ declarations.
+ + Make error messages more uniform and consistent.
+ - libinterimap: use Net::SSLeay::get_version() to get the protocol
+ version string.
+ - test suite: `mv tests/snippets tests/config`
+ - tests/tls-protocols: use custom OpenSSL configuration file with
+ MinProtocol=None so we can test TLSv1 as well, not just TLSv1.2 and
+ later.
+ - test suite: explicitly set ssl_min_protocol=TLSv1 in the Dovecot
+ configuration file (the default as of 2.3.11.3), hence running TLS
+ tests now require Dovecot 2.3 or later.
+ - documentation: simplify SSL options in the sample configuration files.
+ - README: suggest 'restrict,command="/usr/bin/doveadm exec imap"' as
+ authorized_keys(5) options.
+ - README: suggest ControlPath=$XDG_RUNTIME_DIR/ssh-imap-%C for the SSH
+ transport (note that variable expansion is only available in OpenSSH
+ 8.4 and later).
+ - test suite: ensure we haven't started speaking IMAP when the SSL/TLS
+ handshake is aborted (unless STARTTLS is used to upgrade to
+ connection).
+ - documentation: clarify that known TLS protocol versions depend on the
+ OpenSSL version used.
+
+ -- Guilhem Moulin <guilhem@fripost.org> Sat, 26 Dec 2020 23:11:10 +0100
+
+interimap (0.5.4) upstream;
+
+ * libinterimap: make SSL_verify also checks that the certificate
+ Subject Alternative Name (SAN) or Subject CommonName (CN) matches the
+ hostname or IP literal specified by the 'host' option. Previously it
+ was only checking the chain of trust. This bumps the minimum
+ Net::SSLeay version to 1.83 and OpenSSL version to 1.0.2 (when
+ SSL_verify is used).
+ * libinterimap: add support for the TLS SNI (Server Name Indication)
+ extension, controlled by the new 'SSL_hostname' option. The default
+ value of that option is the value of the 'host' option when it is
+ hostname, and the empty string (which disables SNI) when it is an IP
+ literal.
+ + libinterimap: show the matching pinned SPKI in --debug mode.
+ + test suite: always generate new certificates on `make test`.
+ + test suite: sign all test certificates with the same root CA.
+ + libinterimap: factor out hostname/IP parsing.
+ + document that enclosing 'host' value in square brackets forces its
+ interpretation as an IP literal (hence skips name resolution).
+ + Makefile: new 'release' target; also, change the tag format from
+ upstream/$VERSION to v$VERSION.
+ - documentation: replace example.org with example.net for consistency.
+ - rename 'debian' branch to 'debian/latest' for DEP-14 compliance.
+
+ -- Guilhem Moulin <guilhem@fripost.org> Fri, 11 Dec 2020 11:21:17 +0100
+
+interimap (0.5.3) upstream;
+
+ * libinterimap: SSL_fingerprint now supports a space-separated list of
+ digests to pin, and succeeds if, and only if, the peer certificate
+ SPKI matches one of the pinned digest values. Specifying multiple
+ digest values can key useful in key rollover scenarios and/or when
+ the server supports certificates of different types (for instance
+ RSA+ECDSA).
+ - libinterimap: 'null-stderr' is now ignored when the 'debug' flag is
+ set (the standard error is never sent to /dev/null).
+ - test suite: use a RSA certificate rather than ECDSA.
+ - test suite: new test with a server offering both RSA+ECDSA
+ certificates. This test requires dovecot-imapd 2.2.31 or later.
+
+ -- Guilhem Moulin <guilhem@fripost.org> Wed, 09 Dec 2020 15:32:01 +0100
+
interimap (0.5.2) upstream;
- Makefile: remove 'smart' extension from pandoc call to generate
@@ -33,7 +132,7 @@ interimap (0.5) upstream;
(regardless of the hierarchy delimiter in use).
Other changes:
- * interimap: the space-speparated list of names and/or patterns in
+ * interimap: the space-separated list of names and/or patterns in
'list-mailbox' can now contain C-style escape sequences (backslash
and hexadecimal escape).
* interimap: fail when two non-INBOX LIST replies return different
@@ -41,7 +140,7 @@ interimap (0.5) upstream;
happen if mailboxes from different namespaces are being listed. The
workaround here is to run a new interimap instance for each
namespace.
- * libinterimap: in tunnel mode, use a socketpair rather than two pipes
+ * libinterimap: in tunnel mode, use a socket pair rather than two pipes
for IPC between the interimap and the IMAP server. Also, use
SOCK_CLOEXEC to save an fcntl() call when setting the close-on-exec
flag on the socket.
@@ -104,7 +203,7 @@ interimap (0.5) upstream;
- libinterimap: use directories relative to $HOME for the XDG
environment variables default values. Previously getpwuid() was
called to determine the user's home directory, while the XDG
- specification explicitely mentions $HOME. Conveniently our docs
+ specification explicitly mentions $HOME. Conveniently our docs
always mentioned ~/, which on POSIX-compliant systems expands to the
value of the variable HOME. (Cf. Shell and Utilities volume of
POSIX.1-2017, sec. 2.6.1.)
@@ -118,7 +217,7 @@ interimap (0.5) upstream;
- libinterimap: push_flag_updates(): ignore UIDs for which no untagged
FETCH response was received.
- libinterimap: push_flag_updates(): don't ignores received updates (by
- another client) to a superset of the desigred flag list.
+ another client) to a superset of the desired flag list.
- libinterimap: avoid sending large UID EXPUNGE|FETCH|STORE commands as
they might exceed the server's max acceptable command size; these
commands are now split into multiple (sequential) commands when their
@@ -128,7 +227,7 @@ interimap (0.5) upstream;
This is a also a workaround for a bug in Dovecot 2.3.4:
https://dovecot.org/pipermail/dovecot/2019-November/117522.html
- interimap: for the reason explained above, limit number of messages
- to 128 per APPEND command (only on servers advertizing MULTIAPPEND,
+ to 128 per APPEND command (only on servers advertising MULTIAPPEND,
for other servers the number remains 1).
- interimap: gracefully ignore messages with a NIL RFC822 attribute.
- pullimap: treat messages with a NIL RFC822 attribute as empty.
diff --git a/Makefile b/Makefile
index 3d60dfb..9f4702d 100644
--- a/Makefile
+++ b/Makefile
@@ -16,7 +16,26 @@ $(MANUAL_FILES): $(BUILD_DOCDIR)/%: ./doc/%.md
pandoc -f markdown -t json -- "$<" | ./pandoc2man.jq | pandoc -s -f json -t man -o "$@"
test:
- @./tests/run-all
+ ./tests/certs/generate
+ ./tests/run-all
+
+release:
+ @if ! git diff HEAD --quiet -- ./Changelog ./interimap ./pullimap ./lib/Net/IMAP/InterIMAP.pm; then \
+ echo "Dirty state, refusing to release!" >&2; \
+ exit 1; \
+ fi
+ VERS=$$(dpkg-parsechangelog -l Changelog -SVersion 2>/dev/null) && \
+ if git rev-parse -q --verify "refs/tags/v$$VERS" >/dev/null; then echo "tag exists" 2>/dev/null; exit 1; fi && \
+ sed -ri "0,/^( -- .*) .*/ s//\\1 $(shell date -R)/" ./Changelog && \
+ sed -ri "0,/^(our\\s+\\\$$VERSION\\s*=\\s*)'[0-9.]+'\\s*;/ s//\\1'$$VERS';/" \
+ -- ./interimap ./pullimap && \
+ sed -ri "0,/^(package\\s+Net::IMAP::InterIMAP\\s+)v[0-9.]+\\s*;/ s//\\1v$$VERS;/" \
+ -- ./lib/Net/IMAP/InterIMAP.pm && \
+ sed -ri "0,/^(use\\s+Net::IMAP::InterIMAP\\s+)[0-9.]+(\\s|\\$$)/ s//\\1$$VERS\\2/" \
+ -- ./interimap ./pullimap && \
+ git commit -m "Prepare new release v$$VERS." \
+ -- ./Changelog ./interimap ./pullimap ./lib/Net/IMAP/InterIMAP.pm && \
+ git tag -sm "Release version $$VERS" "v$$VERS"
## make html CSS="https://guilhem.org/static/css/bootstrap.min.css" BUILD_DOCDIR="$XDG_RUNTIME_DIR/Downloads"
$(HTML_FILES): $(BUILD_DOCDIR)/%.html: ./doc/%.md $(HTML_TEMPLATE)
@@ -58,4 +77,4 @@ uninstall:
clean:
rm -vf -- $(MANUAL_FILES) $(HTML_FILES)
-.PHONY: all manual html doc test install uninstall clean
+.PHONY: all manual html doc test release install uninstall clean
diff --git a/README b/README
index fbc4ed7..c241486 100644
--- a/README
+++ b/README
@@ -1,54 +1,51 @@
InterIMAP is a fast bidirectional synchronization program for QRESYNC-capable
IMAP4rev1 servers. PullIMAP retrieves messages a remote IMAP mailbox and
-deliver them to an SMTP session. Visit https://guilhem.org/interimap
-for more information.
+deliver them to an SMTP session. Visit https://guilhem.org/interimap for more
+information.
-_______________________________________________________________________
+______________________________________________________________________________
-Compared to IMAP-to-Maildir synchronization solutions like OfflineIMAP,
-adding an IMAP server between the Maildir storage and the MUA saves
-loads of readdir(2) system calls and other File System quirks; moreover
-the abstraction layer offered by the IMAP server makes the MUA and
-synchronization program agnostic to the storage backend (Maildir, mbox,
-dbox,...) in use.
+Compared to IMAP-to-Maildir synchronization solutions like OfflineIMAP, adding
+an IMAP server between the Maildir storage and the MUA saves loads of
+readdir(2) system calls and other File System quirks; moreover the abstraction
+layer offered by the IMAP server makes the MUA and synchronization program
+agnostic to the storage backend (Maildir, mbox, dbox,...) in use.
IMAP synchronization of a mailbox is usually two-folds: 1/ detect and
-propagate changes (flag updates and message deletions) to existing
-messages, then 2/ copy the new messages. The naive way to perform the
-first step is to issue a FETCH command to list all messages in the
-mailbox along with their flags and UIDs, causing heavy network usage.
-Instead, InterIMAP takes advantage of the QRESYNC extension from
-[RFC7162] to perform stateful synchronization: querying changes since
-the last synchronization only gives a phenomenal performance boost and
-drastically reduces the network traffic.
+propagate changes (flag updates and message deletions) to existing messages,
+then 2/ copy the new messages. The naive way to perform the first step is to
+issue a FETCH command to list all messages in the mailbox along with their
+flags and UIDs, causing heavy network usage. Instead, InterIMAP takes
+advantage of the QRESYNC extension from [RFC7162] to perform stateful
+synchronization: querying changes since the last synchronization only gives a
+phenomenal performance boost and drastically reduces the network traffic.
-For convenience reasons servers must also support LIST-EXTENDED
-[RFC5258], LIST-STATUS [RFC5819] and UIDPLUS [RFC4315]. Other supported
-extensions are:
- * LITERAL+ [RFC2088] non-synchronizing literals (recommended),
- * MULTIAPPEND [RFC3502] (recommended),
- * COMPRESS=DEFLATE [RFC4978] (recommended),
- * SASL-IR [RFC4959] SASL Initial Client Response, and
+For convenience reasons servers must also support LIST-EXTENDED [RFC5258],
+LIST-STATUS [RFC5819] and UIDPLUS [RFC4315]. Other supported extensions are:
+
+ * LITERAL+ [RFC2088] non-synchronizing literals (recommended);
+ * MULTIAPPEND [RFC3502] (recommended);
+ * COMPRESS=DEFLATE [RFC4978] (recommended);
+ * SASL-IR [RFC4959] SASL Initial Client Response; and
* UNSELECT [RFC3691].
-_______________________________________________________________________
+______________________________________________________________________________
-IMAP traffic is mostly text (beside message bodies perhaps) hence
-compresses pretty well: enabling compression can save a great amount of
-network resources.
+IMAP traffic is mostly text (beside message bodies perhaps) hence compresses
+pretty well: enabling compression can save a great amount of network
+resources.
However establishing an SSL/TLS connection (type=imaps, or type=imap and
STARTTLS=YES) yields a small overhead due to the SSL/TLS handshake.
On the other hand if SSH access is allowed on the remote server, one can
-tunnel the IMAP traffic through SSH and use OpenSSH's ControlPersist
-feature to save most of the cryptographic overhead (at the expense of a
-local 'ssh' process and a remote 'imap' process). Moreover if the IMAP
-user is a valid UNIX user it is possible to use pre-authentication on
-the remote server as well, which saves the extra round trip caused by
-the AUTHENTICATE command. For instance the following configuration
-snippet saves bandwidth and brings a significant speed gain compared to
-type=imaps.
+tunnel the IMAP traffic through SSH and use OpenSSH's ControlPersist feature
+to save most of the cryptographic overhead (at the expense of a local 'ssh'
+process and a remote 'imap' process). Moreover if the IMAP user is a valid
+UNIX user it is possible to use pre-authentication on the remote server as
+well, which saves the extra round trip caused by the AUTHENTICATE command.
+For instance the following configuration snippet saves bandwidth and brings a
+significant speed gain compared to type=imaps.
local: $XDG_CONFIG_HOME/interimap/config:
[remote]
@@ -59,7 +56,7 @@ type=imaps.
Host imap.example.net
IdentityFile ~/.ssh/id-interimap
IdentitiesOnly yes
- ControlPath /run/shm/%u@%n
+ ControlPath ${XDG_RUNTIME_DIR}/ssh-imap-%C
ControlMaster auto
ControlPersist 10m
StrictHostKeyChecking yes
@@ -69,17 +66,17 @@ type=imaps.
Compression yes
remote: ~user/.ssh/authorized_keys:
- command="/usr/lib/dovecot/imap",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-... id-interimap
+ restrict,command="/usr/bin/doveadm exec imap" ssh-[…] id-interimap
-However for long-lived connections (using the --watch command-line
-option), the TLS overhead becomes negligible hence the advantage offered
-by the OpenSSH ControlPersist feature is not obvious. Furthermore if
-the remote server supports the IMAP COMPRESS extension [RFC4978], adding
-compress=DEFLATE to the configuration can also greatly reduce bandwidth
-usage with regular INET sockets (type=imaps or type=imap).
+However for long-lived connections (using the --watch command-line option),
+the TLS overhead becomes negligible hence the advantage offered by the OpenSSH
+ControlPersist feature is not obvious. Furthermore if the remote server
+supports the IMAP COMPRESS extension [RFC4978], adding compress=DEFLATE to the
+configuration can also greatly reduce bandwidth usage with regular INET
+sockets (type=imaps or type=imap).
-_______________________________________________________________________
+______________________________________________________________________________
-InterIMAP is Copyright© 2015-2018 Guilhem Moulin ⟨guilhem@fripost.org⟩,
-and licensed for use under the GNU General Public License version 3 or
-later. See ‘COPYING’ for specific terms and distribution information.
+InterIMAP is Copyright© 2015-2020 Guilhem Moulin ⟨guilhem@fripost.org⟩, and
+licensed for use under the GNU General Public License version 3 or later. See
+‘COPYING’ for specific terms and distribution information.
diff --git a/doc/build.md b/doc/build.md
index 4a4f80d..2e4e511 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.86_06
* [`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..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
@@ -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 5370d79..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`.
@@ -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
@@ -376,29 +378,44 @@ Valid options are:
*null-stderr*
: Whether to redirect *command*'s standard error to `/dev/null` for
- `type=tunnel`. (Default: `NO`.)
+ `type=tunnel`. This option is ignored when the `--debug` flag is
+ set. (Default: `NO`.)
*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*
-: Fingerprint of the server certificate's Subject Public Key Info, in
- the form `[ALGO$]DIGEST_HEX` where `ALGO` is the used algorithm (by
- default `sha256`).
+: Space-separated list of acceptable fingerprints for the server
+ certificate's Subject Public Key Info, in the form
+ `[ALGO$]DIGEST_HEX` where `ALGO` is the digest algorithm (by default
+ `sha256`).
Attempting to connect to a server with a non-matching certificate
SPKI fingerprint causes `interimap` to abort the connection during
the SSL/TLS handshake.
@@ -409,25 +426,47 @@ Valid options are:
| openssl pkey -pubin -outform DER \
| openssl dgst -sha256
+ Specifying multiple digest values can be useful in key rollover
+ scenarios and/or when the server supports certificates of different
+ 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.
- Note that using *SSL_fingerprint* to specify the fingerprint of the
- server certificate is an orthogonal authentication measure as it
- ignores the CA chain.
+: 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`.)
+ Note that using *SSL_fingerprint* to specify the fingerprint of the
+ server certificate provides an independent server authentication
+ 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 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.
-*SSL_CAfile*
+ Trusted CA certificates are loaded from the default system locations
+ unless one (or both) of *SSL_CAfile* or *SSL_CApath* is set.
-: File containing trusted certificates to use during server
- certificate authentication if `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}
====================
@@ -561,6 +600,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 0055675..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 deli