Peya/docs/proxies.md

# Proxy usage in the Monero ecosystem
The CLI/RPC wallets and daemon both support proxies and use the same parameters
to configure them. Currently socks 4, 4a, and 5 are supported and can be
selected with command-line options.

## Wallet
The CLI and RPC wallets support proxies via the `--proxy` option. The format
for usage is `[socks5://[user:pass]]host:port`. The square brackets indicate
an optional portion. This option can only be specified once. Examples:

```
--proxy 192.168.0.10:1050
--proxy socks5://192.168.0.10:1050
--proxy socks5://username:password@192.168.0.10:1050
--proxy [::1]:1050
--proxy socks5://[::1]:1050
--proxy socks5://username:password@[::1]:1050
```

The first connects to `192.168.0.10` on port `1050` using socks 4a. The second
connects to the same location using socks 5. The third uses socks 5 at the same
location and sends user authentication if prompted by the proxy server. The
last three are identical to the first 3, except an IPv6 address is used
instead. While IPv6 connections are invalid for Socks 4 and 4a, the proxy
server itself can be connected using IPv6.

The username and password fields both support "percent-encoding" for special
character support. As an example, `%40` gets converted to `@`, such that
`username:p%40ssword` gets converted to `username:p@ssword`. This allows that
specific character to be used; specifying the character directly will
incorrectly change the specification of the hostname.

> NOTE: The username+password will show up in the process list and can be read
> by other programs. It is recommended that `--config-file` be used to store
> username+password options. The format for a config file is `option=value`,
> so in this example the file would contain:
> `proxy=socks5://username:password@192.168.0.10:1080`.

The CLI and RPC wallets currently reject hosts that do **NOT** end in`.onion`
or `.i2p` **unless** `--daemon-ssl-ca-certificates`,
`--daemon-ssl-allow-any-cert`, or `--daemon-ssl-allowed-fingerprints` is used.
If an onion or i2p address is used, the hostname contains the certificate
verification, providing decent security against man-in-the-middle (MitM)
attacks. The two `--daemon-ssl-*` options support specifying exact
certificates, also preventing MitM attacks.

> Perhaps the wallets should be relaxed to allow system-CA checks, but for now
> certificates must be strictly provided.

## Daemon
The daemon has two options for proxies `--proxy` and `--tx-proxy` which can be
used in isolation or together. The `--proxy` option controls how
IPv4/IPv6/hostname connections are performed, whereas `--tx-proxy` controls
how local transactions are relayed. Both options support Socks 4, 4a, and 5.

### `--proxy`
This option should be used when outbound connections to IPv4/IPv6 addresses and
hostnames  (other than `.onion` `.i2p`) need to be proxied. Common examples
include using Tor exit nodes or a VPN to conceal your local IP. This option
will **not** use Tor or I2P hidden services for P2P connections; this is
primarily used for proxying standard IPv4 or IPv6 connections to some remote
host. Hidden services are not used because this is designed to be more general
purpose (i.e. a standard socks VPN can be used). 

> An additional option for hidden services (separate from `--tx-proxy`) could
> arguably be added, which could optionally turn off IPv4/IPv6 connections for
> P2P.

The format for `--proxy` usage: `[socks5://[user:pass]]@127.0.0.1`. The square
bracket indicate optional portion. See [wallet](#wallet) section above for
examples and other information on the format. The option can only be specified
once. The restrictions for MitM attacks apply only to the wallet usage, and not
to the daemon.

> When using `--proxy`, inbound connections will be impossible unless the
> proxy server is somehow setup to forward connections. This setup is a
> difficult because each outgoing socks connections can have a unique binding
> port. Such a setup is currently out-of-scope for this document.

### `--tx-proxy`
This option should be used to specify a proxy that can resolve hidden service
hostnames, so that local transactions can be forwarded over a privacy
preserving network. Currently only Tor or I2P hidden services are supported.
This option be specified multiple times, but only once per network (see below).

The format for `--tx-proxy` is
`network,[socks5://[user:pass@]]ip:port[,max_connections][,disable_noise]`.
Examples:

```
--tx-proxy tor,127.0.0.1:1050
--tx-proxy tor,127.0.0.1:1050,100
--tx-proxy tor,127.0.0.1:1050,disable_noise
--tx-proxy tor,127.0.0.1:1050,100,disable_noise
--tx-proxy tor,socks5://127.0.0.1:1050
--tx-proxy tor,socks5://127.0.0.1:1050,100
--tx-proxy tor,socks5://127.0.0.1:1050,disable_noise
--tx-proxy tor,socks5://127.0.0.1:1050,100,disable_noise
--tx-proxy tor,socks5://username:password@127.0.0.1:1050
--tx-proxy tor,socks5://username:password@127.0.0.1:1050,100
--tx-proxy tor,socks5://username:password@127.0.0.1:1050,disable_noise
--tx-proxy tor,socks5://username:password@127.0.0.1:1050,100,disable_noise
--tx-proxy tor,[::1]:1050
--tx-proxy tor,[::1]:1050,100
--tx-proxy tor,[::1]:1050,disable_noise
--tx-proxy tor,[::1]:1050,100,disable_noise
--tx-proxy tor,socks5://[::1]:1050
--tx-proxy tor,socks5://[::1]:1050,100
--tx-proxy tor,socks5://[::1]:1050,disable_noise
--tx-proxy tor,socks5://[::1]:1050,100,disable_noise
--tx-proxy tor,socks5://username:password@[::1]:1050
--tx-proxy tor,socks5://username:password@[::1]:1050,100
--tx-proxy tor,socks5://username:password@[::1]:1050,disable_noise
--tx-proxy tor,socks5://username:password@[::1]:1050,100,disable_noise
--tx-proxy i2p,127.0.0.1:1050
--tx-proxy i2p,127.0.0.1:1050,100
--tx-proxy i2p,127.0.0.1:1050,disable_noise
--tx-proxy i2p,127.0.0.1:1050,100,disable_noise
--tx-proxy i2p,socks5://127.0.0.1:1050
--tx-proxy i2p,socks5://127.0.0.1:1050,100
--tx-proxy i2p,socks5://127.0.0.1:1050,disable_noise
--tx-proxy i2p,socks5://127.0.0.1:1050,100,disable_noise
--tx-proxy i2p,socks5://username:password@127.0.0.1:1050
--tx-proxy i2p,socks5://username:password@127.0.0.1:1050,100
--tx-proxy i2p,socks5://username:password@127.0.0.1:1050,disable_noise
--tx-proxy i2p,socks5://username:password@127.0.0.1:1050,100,disable_noise
--tx-proxy i2p,[::1]:1050
--tx-proxy i2p,[::1]:1050,100
--tx-proxy i2p,[::1]:1050,disable_noise
--tx-proxy i2p,[::1]:1050,100,disable_noise
--tx-proxy i2p,socks5://[::1]:1050
--tx-proxy i2p,socks5://[::1]:1050,100
--tx-proxy i2p,socks5://[::1]:1050,disable_noise
--tx-proxy i2p,socks5://[::1]:1050,100,disable_noise
--tx-proxy i2p,socks5://username:password@[::1]:1050
--tx-proxy i2p,socks5://username:password@[::1]:1050,100
--tx-proxy i2p,socks5://username:password@[::1]:1050,disable_noise
--tx-proxy i2p,socks5://username:password@[::1]:1050,100,disable_noise
```

The above examples are fairly exhaustive of all the possible option scenarios
that will be incurred by the typical user. 

#### The `network` portion of the option
The first section (before the first `,`) indicates the network - only `tor` or
`i2p` are valid here.

This portion of the option tells `--add-node`, `--add-priority-node`, and
`--add-exclusive-node` options to use the specified proxy for those nodes. In
other words, command-line specified hidden services are forwarded to their
corresponding `--tx-proxy` server. Hidden services do **NOT** have to be
specified on the command-line, there are built-in seed nodes for each network.

#### The `ip:port` portion of the option
The second portion of the option (after the first `,` and _optionally_ ending
in the next `,`) indicates the location of the socks server. The location
**must** include an IPv4/IPv6 AND port. The location can optionally include the
socks version  - `socks4`, `socks4a`, and `socks5` are all valid here. If
the socks version is not specified, `socks4a` is assumed.

An optional username and password can also be included. These fields support
percent-encoding, see [wallet](#wallet) section for more information.

#### The last portion of the option
After the ip:port section two options can be specified: the number of max
connections and `disable_noise`. They can be specified in either order, but
must be after the ip:port section.

The max connections does exactly as advertised, it limits the number of
outgoing connections to the proxy. The `disable_noise` feature lowers the
bandwidth requirements, and decreases the tx-relay time. When **NOT**
specified, dummy P2P packets are sent periodically to connections (via the
proxy) to conceal when a transaction is forwarded over the connection. When
the option is specified, P2P links only send data for peerlist information and
local outgoing transactions.

### `--anonymous-inbound`
Currently the daemon cannot configure incoming hidden services connections.
Instead, the user must manually configure Tor or I2P to accept inbound
connections. Then, `--anonymous-inbound` must be used to tell the daemon where
to listen for incoming connections, and the incoming hidden service address.
The option can be specified once for each network type. The format for usage
is: `hidden-service-address,[bind-ip:]port[,max_connections]`. Examples:

```
--anonymous-inbound rveahdfho7wo4b2m.onion:18083,18083
--anonymous-inbound rveahdfho7wo4b2m.onion:18083,18083,100
--anonymous-inbound rveahdfho7wo4b2m.onion:18083,127.0.0.1:18083
--anonymous-inbound rveahdfho7wo4b2m.onion:18083,127.0.0.1:18083,100
--anonymous-inbound udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p,18083
--anonymous-inbound udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p,18083,100
--anonymous-inbound udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p,127.0.0.1:18083
--anonymous-inbound udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p,127.0.0.1:18083,100
```

Everything before the first `,` is the hidden service hostname. This must be
a valid Tor or I2P address. This tells the daemon the **inbound** hidden
service as configured for the local Tor or I2P daemons.

Everything between `,`s specify the bind ip and bind port. The IP address is
optional, and defaults to `127.0.0.1`. The Tor and I2P daemons must be
configured to forward incoming hidden service connections to this IP/Port pair.

Everything after the second `,` is used to specify the number of max inbound
connections. The field is optional.