search

duesee / imap-proxy

5 stars 0 forks source link

readme

main audit

IMAP Proxy 𓃸

A proxy that receives, Debug-prints, and forwards IMAP messages without changing their semantics (but see note below).

%%{init: {'theme': 'neutral' } }%%
flowchart LR
    imap-types --> imap-codec
    imap-codec --> imap-next
    imap-next --> imap-proxy

    style imap-codec stroke-dasharray: 10 5
    style imap-next stroke-dasharray: 10 5
    style imap-proxy stroke-width:4px

    click imap-types href "https://github.com/duesee/imap-codec/tree/main/imap-types"
    click imap-codec href "https://github.com/duesee/imap-codec"
    click imap-next href "https://github.com/duesee/imap-next"
    click imap-proxy href "https://github.com/duesee/imap-proxy"

Thanks to imap-next, the proxy takes advantage of asynchronous I/O, abstracts away literal handling, and fully supports unsolicited responses.

Quickstart

For now there is no officially released binary. You can install the proxy via cargo ...

cargo install --git https://github.com/duesee/imap-proxy

... and then run ...

imap-proxy --help

... for an overview of arguments. But we suggest to run it directly via cargo ...

cargo run -- --help

... because it allows you to tinker with the source code.

Important: You must enable tracing (logging) to see a Debug-print of exchanged messages.

To do so, set the RUST_LOG environment variable.

Use ...

RUST_LOG=proxy=trace cargo run

... to start the proxy (using the default config.toml), enabling all log messages for the "proxy" module.

You should probably experiment with the environment variable. For example, you can use ...

RUST_LOG=trace cargo run

... to enable logs from lower libraries. This way, you will get TLS events and io/{read,write}/raw events.

graph LR;
    Client -->|"â‘  parse Command"| Proxy;
    Proxy  -->|"â‘¡ change Command (currently no change)"| Proxy;
    Proxy  -->|"â‘¢ serialize Command'"| Server;
    Server -->|"â‘£ parse Response"| Proxy;
    Proxy  -->|"â‘¥ serialize Response'"| Client;
    Proxy  -->|"⑤ change Response (currently no change)"| Proxy;
Example Trace ``` $ RUST_LOG=trace cargo run # Insecure to Insecure imap://127.0.0.1:1143 (insecure) -> imap://127.0.0.1:2143 (insecure) INFO Bound to bind_addr_port="127.0.0.1:1143" INFO Accepted client client_addr=127.0.0.1:46500 INFO Connecting to server server_addr_port="127.0.0.1:2143" INFO Connected to server server_addr_port="127.0.0.1:2143" TRACE io/read/raw data="* OK Hello, World!\\r\\n" TRACE <--| role="s2p" greeting=Greeting { kind: Ok, code: None, text: Text("Hello, World!") } TRACE io/write/raw data="* OK Hello, World!\\r\\n" TRACE <--- greeting role="p2c" TRACE io/read/raw data="A LOGIN {4}\\r\\n" TRACE io/write/raw data="+ proxy: Literal accepted by proxy\\r\\n" TRACE io/read/raw data="user {4}" TRACE io/read/raw data="\\r\\n" TRACE io/write/raw data="+ proxy: Literal accepted by proxy\\r\\n" TRACE io/read/raw data="pass" TRACE io/read/raw data="\\r\\n" TRACE |--> role="c2p" command=Command { tag: Tag("A"), body: Login { username: String(Literal(Literal { data: b"user", mode: Sync })), password: String(Literal(Literal { data: b"pass", mode: Sync })) } } ```

Config

The config.toml file has pre-configured scenarios. The first scenario "Insecure to TLS" is useful for a (local) forwarding proxy and is already enabled.

You can start multiple services using TOML's array of tables syntax:

[[services]]
# ...

[[services]]
# ...

The encryption field configures transport encryption, i.e., Insecure or Tls. Insecure disables TLS encryption and SHOULD NOT be used when proxying to a remote server.

Using TLS

Create local TLS certificate(s)

You can use mkcert to create a local certificate authority (CA). The tool takes care to "register" the local CA with typical trust stores on your system.

We recommend creating a private folder before creating certificates and keys. The private folder is .gitignored, so you can't accidentally push your keys.

mkdir private
cd private

With mkcert, you should now be able to create a certificate (+ key), e.g., ...

mkcert localhost

The command creates two files, localhost.pem (certificate) and localhost-key.pem (key).

Configure to accept TLS connections

Edit your config.toml ...

[services.bind.identity]
type = "CertificateChainAndLeafKey"
certificate_chain_path = "private/localhost.pem"
leaf_key_path = "private/localhost-key.pem"

... accordingly, start the proxy, and test your connection with OpenSSL, e.g., ...

openssl s_client -verify_return_error -crlf -connect <host>:<port>

Note: openssl s_client should only really be used for testing.

Semantic changes

A few semantic changes are required to make the proxy more useful. These changes are communicated by the proxy, e.g., by emitting a warning or prefixing a text field.

Literal handling IMAP allows sending commands "piece-by-piece" using literals. However, forwarding single pieces rules out modifications that change the size of a literal. Thus, the proxy collects all pieces first and presents single messages that can be easily replaced (if so desired).

Capability stripping Capabilities can introduce fundamental protocol changes. Thus, forwarding unknown capabilities would mean we are willing to "lose track" of our session understanding. It also implies the proxy needs to forward unparsed messages and (somehow) "get on track" at some later point. Doing so requires an in-depth analysis of the problem and its implications. Thus, we prefer to strip unsupported capabilities and error out on parsing errors.

Supported authentication mechanisms

The proxy forwards authentication messages unchanged, and uses an allow-list of capabilities and authentication mechanisms to exclude everything it doesn't understand.

Some authentication mechanisms "bind" to the TLS connection ("channel binding") and will fail when proxied. These mechanisms are not proxyable by design -- at least without further ado -- and are filtered from the connection.

Authentication mechanism Support
LOGIN supported
PLAIN supported
XOAUTH2 supported
SCRAM-* supported
SCRAM-*-PLUS not supported (due to channel binding)
Others not supported (yet)

Future work

The proxy could enrich existing clients' functionality to improve compatibility, performance, and security. This could be done by fleshing out the proxy into a configurable framework.

Examples:

License

This crate is licensed under AGPL terms.

Thanks

Thanks to the NLnet Foundation for supporting the imap-codec project through NGI Assure!