X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=doc%2Findex.texi;h=b6704a6fe981f68487e7433539c540317540af16;hb=HEAD;hp=40806995a656fc712e768b81f2a905af6a3c0c2c;hpb=df5111054e401374c77d69e7b04f1f119dd464d5;p=tofuproxy.git diff --git a/doc/index.texi b/doc/index.texi index 4080699..de9d845 100644 --- a/doc/index.texi +++ b/doc/index.texi @@ -1,166 +1,110 @@ \input texinfo -@documentencoding UTF-8 @settitle tofuproxy @copying -Copyright @copyright{} 2021 @email{stargrave@@stargrave.org, Sergey Matveev} +Copyright @copyright{} 2021-2024 @email{stargrave@@stargrave.org, Sergey Matveev} @end copying @node Top @top tofuproxy -@image{logs,,,Example logs,.webp} +@command{tofuproxy} is +@url{https://www.gnu.org/philosophy/free-sw.html, free software} +flexible HTTP/HTTPS proxy server, TLS terminator, X.509 TOFU manager, +@url{https://en.wikipedia.org/wiki/Web_ARChive, WARC} and +@url{https://en.wikipedia.org/wiki/Gemini_(protocol), geminispace} +browser, written on @url{https://go.dev/, Go} with following +capabilities: @itemize -@item I am tired that various HTTPS clients (like browsers and feed -aggregators) use various TLS libraries with different features. NSS, -GnuTLS, OpenSSL... All of them sucks, comparing to Go's @code{crypto/tls}. - -@item I tired that everyone provides very limited certificates trust -management capabilities, like either certificate or SPKI -@url{https://en.wikipedia.org/wiki/Certificate_pinning, pinning} with -@url{https://en.wikipedia.org/wiki/Trust_on_first_use, TOFU}. Even my -beloved @url{https://en.wikipedia.org/wiki/Xombrero, Xombrero} browser -still pins only the whole certificate, but its public key would be much -more sufficient and convenient to work with. - -@item I am tired that many clients provides very few information about -certificates and connections at all. - -@item I hate that hardly anyone can control (no automatic silent -transparent following) HTTP redirections. Although Firefox had proper -extensions for that. - -@item I am sick of tiny control on URLs. The best you can is to use some -kind of @url{https://en.wikipedia.org/wiki/Privoxy, Privoxy}, but it is -not friendly with TLS connections, obviously. - -@item Hardly anyone does -@url{https://en.wikipedia.org/wiki/DNS-based_Authentication_of_Named_Entities, DANE} -checks. - -@item And there is insanity of downloading fonts. -Why the hell people just do not send PostScript documents instead!? - -@item And wonderful @url{http://jpegxl.info/, JPEG XL} image format is -not supported by most browsers. Even pretty old WebP is not supported -everywhere. - -@end itemize - -That is why I wrote @command{tofuproxy} -- pure Go HTTP proxy, MitMing -all HTTPS connections on the fly. It is written for my personal needs -exclusively, so many features are just directly hard-coded, instead of -creating some kind of complex configuration framework. - -@itemize - -@item Effective responses proxying, without storing them in the memory first. +@item +Full TLS connection termination between Web-servers and +@command{tofuproxy} itself. TLS 1.3, session resumption, GOST +cryptography (if built with @url{http://www.gostls13.cypherpunks.ru/, +gostls13}) support. Connection between @command{tofuproxy} and browser +itself uses ephemeral on-the-fly generated certificates with proper +domain name. -@item TLS connection between client and @command{tofuproxy} has the - proper hostname set in ephemeral on-the-fly generated certificate. +@item +@url{https://http2.github.io/, HTTP/2} (if negotiated with ALPN) and +HTTP keep-alives are supported. -@item @code{HEAD} method is forbidden, because of damned Xombrero loving - making it so much. Can live without it. +@item +Default Go's @code{crypto/x509} checks are applied to all certificates. +If they pass, then certificate chain is saved on the disk (TOFU, +trust-on-first-use). Future connections are compared against it, warning +you about SPKI change (SPKI pinning) and waiting for your decision +either to accept new chain (possibly once per session), or reject it. +Even if native Go's checks are failed (for example domain still does not +use @code{SubjectAltName} extension), you can still make a decision to +forcefully trust the domain. -@item @code{www.reddit.com} is redirected to @code{old.reddit.com}. +@item +CAs can have restrictions on what domains they are allowed to be served. -@item Various spying domains (advertisement, tracking counters) are - responded with 404 error. +@item +Optional @url{https://en.wikipedia.org/wiki/DNS-based_Authentication_of_Named_Entities, DANE-EE} check. -@item Web fonts downloads are replaced with 404 errors. +@item +TLS client certificates are supported too. -@item All HTTP redirects are replaced with HTML page with the link. - However temporary redirects are passed as is for @code{newsboat} - User-Agent. +@item +HTTP-based authorization requests are intercepted and user/password +input dialogue is shown. It automatically loads initial form values from +@file{.netrc}. -@item WebP (except if User-Agent is Xombrero browser) and JPEG XL images - are transparently transcoded to PNG. +@item +Permanent HTTP redirects are replaces with non-refreshing HTML page with +the link, to make you explicitly allow that step. Temporary redirects +are followed if it is neither @url{https://newsboat.org/, Newsboat} +nor @url{https://www.feeder.stargrave.org/, go.stargrave.org/feeder} +user-agent, not image paths. -@item Default Go's checks are applied to all certificates. If they pass, - then certificate chain is saved on the disk. Future connections are - compared against it, warning you about SPKI change and waiting for - your decision either to accept new chain (possibly once per - session), or reject it. +@item +JPEG XL, AVIF and WebP images are transparently transcoded to PNG, +giving it back to the browser, not requiring it to support modern +effective image formats. -@item Even when native Go's checks are failed, you can still make a - decision to forcefully trust the domain. +@item +Ability to load, index and browse WARC web archives, that are possibly +multi-segment/frame compressed with @command{gzip}/@command{zstd}. -@item Optionally DANE-EE check is also made for each domain you visit. +@item +Ability to browse geminispace, transparently converting gemfiles to +HTMLs with URL rewriting. @end itemize -@image{dialog,,,Example dialog,.webp} - -@node Usage -@unnumbered Usage +And additional personal preferences: @itemize -@item Build @command{tofuproxy}: - -@example -$ git clone git://git.stargrave.org/tofuproxy.git -$ cd tofuproxy -$ go build -@end example - @item -Generate CA-capable certificate for the proxy, that will issue ephemeral -certificate to proxied domains: - -@example -$ redo cert.pem -@end example +Various spying domains (advertisement, tracking counters) are denied. @item -Create directory with output FIFOs and directory for stored certificate chains: - -@example -$ ./mkfifos.sh -$ mkdir certs -@end example +@code{www.reddit.com} is redirected to @code{old.reddit.com} (because it +works without JavaScript and looks nicer). @item -Run @command{tofuproxy} itself. By default it will bind to -@code{[::1]:8080}, use @code{[::1]:53} DNS server for DANE requests -(set to an empty string to disable DANE lookups): - -@example -$ ./tofuproxy -main.go:316: listening: [::1]:8080 -@end example - -@item Trust your newly generated CA: - -@example -# cat /path/to/tofuproxy/cert.pem >> /etc/ssl/cert.pem -@end example - -@item Point you HTTP/HTTPS clients to @code{http://localhost:8080}. +@url{https://habr.com/ru/all/, Хабр}'s resolution reduced images are +redirected to their full size variants. -@item Watch logs with @url{https://github.com/halturin/multitail, multitail}: - -@example -$ ./multitail.sh -@end example +@item +Web fonts downloads are forbidden. @end itemize -When you encounter something requiring your attention and decision, you -will be shown Tk-dialog through the @command{wish} invocation. GnuTLS'es -@command{certtool} is used for certificate information printing. - -@node TODO -@unnumbered TODO - -What I am planning possibly to do? Just brainstorming: - -@itemize - -@item HTTP authorization dialog. - -@item TLS client certificates usage capability. - -@end itemize +@insertcopying + +@include why.texi +@include install.texi +@include usage.texi +@include spies.texi +@include certs.texi +@include tlsauth.texi +@include restricted.texi +@include httpauth.texi +@include warcs.texi +@include gemini.texi