doc/index.texi

   1 \input texinfo
   2 @documentencoding UTF-8
   3 @settitle tofuproxy
   4
   5 @copying
   6 Copyright @copyright{} 2021 @email{stargrave@@stargrave.org, Sergey Matveev}
   7 @end copying
   8
   9 @node Top
  10 @top tofuproxy
  11
  12 @image{logs,,,Example logs,.webp}
  13
  14 @itemize
  15
  16 @item I am tired that various HTTPS clients (like browsers and feed
  17 aggregators) use various TLS libraries with different features. NSS,
  18 GnuTLS, OpenSSL... All of them sucks, comparing to Go's @code{crypto/tls}.
  19
  20 @item I tired that everyone provides very limited certificates trust
  21 management capabilities, like either certificate or SPKI
  22 @url{https://en.wikipedia.org/wiki/Certificate_pinning, pinning} with
  23 @url{https://en.wikipedia.org/wiki/Trust_on_first_use, TOFU}. Even my
  24 beloved @url{https://en.wikipedia.org/wiki/Xombrero, Xombrero} browser
  25 still pins only the whole certificate, but its public key would be much
  26 more sufficient and convenient to work with.
  27
  28 @item I am tired that many clients provides very few information about
  29 certificates and connections at all.
  30
  31 @item I hate that hardly anyone can control (no automatic silent
  32 transparent following) HTTP redirections. Although Firefox had proper
  33 extensions for that.
  34
  35 @item I am sick of tiny control on URLs. The best you can is to use some
  36 kind of @url{https://en.wikipedia.org/wiki/Privoxy, Privoxy}, but it is
  37 not friendly with TLS connections, obviously.
  38
  39 @item Hardly anyone does
  40 @url{https://en.wikipedia.org/wiki/DNS-based_Authentication_of_Named_Entities, DANE}
  41 checks.
  42
  43 @item And there is insanity of downloading fonts.
  44 Why the hell people just do not send PostScript documents instead!?
  45
  46 @item And wonderful @url{http://jpegxl.info/, JPEG XL} image format is
  47 not supported by most browsers. Even pretty old WebP is not supported
  48 everywhere.
  49
  50 @end itemize
  51
  52 That is why I wrote @command{tofuproxy} -- pure Go HTTP proxy, MitMing
  53 all HTTPS connections on the fly. It is written for my personal needs
  54 exclusively, so many features are just directly hard-coded, instead of
  55 creating some kind of complex configuration framework.
  56
  57 @itemize
  58
  59 @item Effective responses proxying, without storing them in the memory first.
  60
  61 @item TLS connection between client and @command{tofuproxy} has the
  62     proper hostname set in ephemeral on-the-fly generated certificate.
  63
  64 @item @code{HEAD} method is forbidden, because of damned Xombrero loving
  65     making it so much. Can live without it.
  66
  67 @item @code{www.reddit.com} is redirected to @code{old.reddit.com}.
  68
  69 @item @url{https://habr.com/ru/all/, Хабр}'s resolution reduced images
  70     are redirected to their full size variants.
  71
  72 @item Various spying domains (advertisement, tracking counters) are
  73     responded with 404 error.
  74
  75 @item Web fonts downloads are replaced with 404 errors.
  76
  77 @item All HTTP redirects are replaced with HTML page with the link.
  78     However temporary redirects are passed as is for @code{newsboat}
  79     User-Agent.
  80
  81 @item WebP (except if User-Agent is Xombrero browser) and JPEG XL images
  82     are transparently transcoded to PNG.
  83
  84 @item Default Go's checks are applied to all certificates. If they pass,
  85     then certificate chain is saved on the disk. Future connections are
  86     compared against it, warning you about SPKI change and waiting for
  87     your decision either to accept new chain (possibly once per
  88     session), or reject it.
  89
  90 @item Even when native Go's checks are failed, you can still make a
  91     decision to forcefully trust the domain.
  92
  93 @item Optionally DANE-EE check is also made for each domain you visit.
  94
  95 @item TLS session resumption is also supported.
  96
  97 @item And Go itself tries also to act as a
  98 @url{https://http2.github.io/, HTTP/2} client too.
  99
 100 @end itemize
 101
 102 @image{dialog,,,Example dialog,.webp}
 103
 104 @node Usage
 105 @unnumbered Usage
 106
 107 @itemize
 108
 109 @item Build @command{tofuproxy}:
 110
 111 @example
 112 $ git clone git://git.stargrave.org/tofuproxy.git
 113 $ cd tofuproxy
 114 $ go build
 115 @end example
 116
 117 @item
 118 Generate CA-capable certificate for the proxy, that will issue ephemeral
 119 certificate to proxied domains:
 120
 121 @example
 122 $ redo cert.pem
 123 @end example
 124
 125 @item
 126 Create directory with output FIFOs and directory for stored certificate chains:
 127
 128 @example
 129 $ ./mkfifos.sh
 130 $ mkdir certs
 131 @end example
 132
 133 @item
 134 Run @command{tofuproxy} itself. By default it will bind to
 135 @code{[::1]:8080}, use @code{[::1]:53} DNS server for DANE requests
 136 (set to an empty string to disable DANE lookups):
 137
 138 @example
 139 $ ./tofuproxy
 140 main.go:316: listening: [::1]:8080
 141 @end example
 142
 143 @item Trust your newly generated CA:
 144
 145 @example
 146 # cat /path/to/tofuproxy/cert.pem >> /etc/ssl/cert.pem
 147 @end example
 148
 149 @item Point you HTTP/HTTPS clients to @code{http://localhost:8080}.
 150
 151 @item Watch logs with @url{https://github.com/halturin/multitail, multitail}:
 152
 153 @example
 154 $ ./multitail.sh
 155 @end example
 156
 157 @end itemize
 158
 159 When you encounter something requiring your attention and decision, you
 160 will be shown Tk-dialog through the @command{wish} invocation. GnuTLS'es
 161 @command{certtool} is used for certificate information printing.
 162
 163 @node TODO
 164 @unnumbered TODO
 165
 166 What I am planning possibly to do? Just brainstorming:
 167
 168 @itemize
 169
 170 @item HTTP authorization dialog.
 171
 172 @item TLS client certificates usage capability.
 173
 174 @end itemize