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