aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/build.md8
-rw-r--r--doc/getting-started.md2
-rw-r--r--doc/interimap.1.md33
-rw-r--r--doc/pullimap.1.md33
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
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-11 03:40:36 +0000