diff options
Diffstat (limited to 'doc/interimap.1.md')
| -rw-r--r-- | doc/interimap.1.md | 107 |
1 files changed, 73 insertions, 34 deletions
diff --git a/doc/interimap.1.md b/doc/interimap.1.md index f10ced6..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,58 +378,95 @@ 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. The following command can be used to compute the SHA-256 digest of a certificate's Subject Public Key Info: - openssl x509 -in /path/to/server/certificate.pem -pubkey \ - | openssl pkey -pubin -outform DER \ - | openssl dgst -sha256 + $ openssl x509 -in /path/to/server/certificate.pem -pubkey \ + | 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} ==================== @@ -469,7 +508,7 @@ Known bugs and limitations * Because the [IMAP protocol][RFC 3501] doesn't provide a way for clients to determine whether a disappeared mailbox was deleted or renamed, `interimap` aborts when a known mailbox disappeared from one - server but not the other. The `--delete` (resp. `rename`) command + server but not the other. The `--delete` (resp. `--rename`) command should be used instead to delete (resp. rename) the mailbox on both servers as well as within `interimap`'s internal database. @@ -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 |