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 am 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 am tired 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 tired that you have got small control on URLs. The best you
  36 can is to use some kind of @url{https://en.wikipedia.org/wiki/Privoxy,
  37 Privoxy}, but it is 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 @end itemize
  47
  48 That is why I wrote @command{tofuproxy} -- pure Go HTTP proxy, MitMing
  49 all HTTPS connections on the fly. It is written for my personal needs
  50 exclusively, so many features are just directly hard-coded, instead of
  51 creating some kind of complex configuration framework.
  52
  53 @itemize
  54
  55 @item Effective responses proxying, without storing them in the memory first.
  56
  57 @item TLS connection between client and @command{tofuproxy} has the
  58     proper hostname set in ephemeral on-the-fly generated certificate.
  59
  60 @item @code{HEAD} method is forbidden, because of damned Xombrero loving
  61     making it so much. Can live without it.
  62
  63 @item @code{www.reddit.com} is redirected to @code{old.reddit.com}.
  64
  65 @item Various spying domains (advertisement, tracking counters) are
  66     responded with 404 error.
  67
  68 @item All HTTP redirects are replaced with HTML page with the link.
  69     However temporary redirects are passed as is for @code{newsboat}
  70     User-Agent.
  71
  72 @item Default Go's checks are applied to all certificates. If they pass,
  73     then certificate chain is saved on the disk. Future connections are
  74     compared against it, warning you about SPKI change and waiting for
  75     your decision either to accept new chain (possibly once per
  76     session), or reject it.
  77
  78 @item Even when native Go's checks are failed, you can still make a
  79     decision to forcefully trust the domain.
  80
  81 @item Optionally DANE-EE check is also made for each domain you visit.
  82
  83 @end itemize
  84
  85 @image{dialog,,,Example dialog,.webp}
  86
  87 @node Usage
  88 @unnumbered Usage
  89
  90 @itemize
  91
  92 @item Build @command{tofuproxy}:
  93
  94 @example
  95 $ git clone git://git.stargrave.org/tofuproxy.git
  96 $ cd tofuproxy
  97 $ go build
  98 @end example
  99
 100 @item
 101 Generate CA-capable certificate for the proxy, that will issue ephemeral
 102 certificate to proxied domains:
 103
 104 @example
 105 $ redo cert.pem
 106 @end example
 107
 108 @item
 109 Create directory with output FIFOs and directory for stored certificate chains:
 110
 111 @example
 112 $ ./mkfifos.sh
 113 $ mkdir certs
 114 @end example
 115
 116 @item
 117 Run @command{tofuproxy} itself. By default it will bind to
 118 @code{[::1]:8080}, use @code{[::1]:53} DNS server for DANE requests
 119 (set to an empty string to disable DANE lookups):
 120
 121 @example
 122 $ ./tofuproxy
 123 main.go:316: listening: [::1]:8080
 124 @end example
 125
 126 @item Trust your newly generated CA:
 127
 128 @example
 129 # cat /path/to/tofuproxy/cert.pem >> /etc/ssl/cert.pem
 130 @end example
 131
 132 @item Point you HTTP/HTTPS clients to @code{http://localhost:8080}.
 133
 134 @item Watch logs with @url{https://github.com/halturin/multitail, multitail}:
 135
 136 @example
 137 $ ./multitail.sh
 138 @end example
 139
 140 @end itemize
 141
 142 When you encounter something requiring your attention and decision, you
 143 will be shown Tk-dialog through the @command{wish} invocation. GnuTLS'es
 144 @command{certtool} is used for certificate information printing.
 145
 146 @node TODO
 147 @unnumbered TODO
 148
 149 What I am planning possibly to do? Just brainstorming:
 150
 151 @itemize
 152
 153 @item JPEG-XL/WebP transparent converter to JPEG/PNG.
 154
 155 @item HTTP authorization dialog.
 156
 157 @item TLS client certificates usage capability.
 158
 159 @end itemize