From: Sergey Matveev <stargrave@stargrave.org>
Date: Sun, 5 Sep 2021 14:03:46 +0000 (+0300)
Subject: Small documentation
X-Git-Tag: v0.1.0~92
X-Git-Url: http://www.git.stargrave.org/?p=tofuproxy.git;a=commitdiff_plain;h=f62068a89b1c2bc079491913dfb44689e9a018a0

Small documentation
---

diff --git a/README b/README
new file mode 100644
index 0000000..c62d94d
--- /dev/null
+++ b/README
@@ -0,0 +1,2 @@
+tofuproxy -- HTTP proxy, MitMing all HTTPS connections, taking all
+TLS-related certificates trust management.
diff --git a/doc/dialog.webp b/doc/dialog.webp
new file mode 100644
index 0000000..bff3268
Binary files /dev/null and b/doc/dialog.webp differ
diff --git a/doc/index.texi b/doc/index.texi
new file mode 100644
index 0000000..1989a45
--- /dev/null
+++ b/doc/index.texi
@@ -0,0 +1,158 @@
+\input texinfo
+@documentencoding UTF-8
+@settitle tofuproxy
+
+@copying
+Copyright @copyright{} 2021 @email{stargrave@@stargrave.org, Sergey Matveev}
+@end copying
+
+@node Top
+@top tofuproxy
+
+@image{logs,,,Example logs,.webp}
+
+@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 am 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 am tired that hardly anyone can control (no automatic silent
+transparent following) HTTP redirections. Although Firefox had proper
+extensions for that.
+
+@item I am tired that you have got small 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.
+
+@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 TLS connection between client and @command{tofuproxy} has the
+    proper hostname set in ephemeral on-the-fly generated certificate.
+
+@item @code{HEAD} method is forbidden, because of damned Xombrero loving
+    making it so much. Can live without it.
+
+@item @code{www.reddit.com} is redirected to @code{old.reddit.com}.
+
+@item Various spying domains (advertisement, tracking counters) are
+    responded with 404 error.
+
+@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 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 Even when native Go's checks are failed, you can still make a
+    decision to forcefully trust the domain.
+
+@item Optionally DANE-EE check is also made for each domain you visit.
+
+@end itemize
+
+@image{dialog,,,Example dialog,.webp}
+
+@node Usage
+@unnumbered Usage
+
+@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
+
+@item
+Create directory with output FIFOs and directory for stored certificate chains:
+
+@example
+$ ./mkfifos.sh
+$ mkdir certs
+@end example
+
+@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}.
+
+@item Watch logs with @url{https://github.com/halturin/multitail, multitail}:
+
+@example
+$ ./multitail.sh
+@end example
+
+@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 JPEG-XL/WebP transparent converter to JPEG/PNG.
+
+@item HTTP authorization dialog.
+
+@item TLS client certificates usage capability.
+
+@item Web fonts download restriction.
+
+@end itemize
diff --git a/doc/logs.webp b/doc/logs.webp
new file mode 100644
index 0000000..0d3bba6
Binary files /dev/null and b/doc/logs.webp differ
diff --git a/doc/style.css b/doc/style.css
new file mode 100644
index 0000000..0d2e65b
--- /dev/null
+++ b/doc/style.css
@@ -0,0 +1,9 @@
+body {
+    margin: auto;
+    width: 80em;
+    background-color: #AEBECE;
+}
+h1, h2, h3, h4 { text-align: center }
+h1, h2, h3, h4, strong { color: #900090 }
+pre { background-color: #CCCCCC }
+table, th, td { border: 1px solid black ; border-collapse: collapse }
diff --git a/doc/www.do b/doc/www.do
new file mode 100644
index 0000000..0f70f33
--- /dev/null
+++ b/doc/www.do
@@ -0,0 +1,16 @@
+redo-ifchange *.texi
+html=tofuproxy.html
+rm -f $html/*.html
+${MAKEINFO:=makeinfo} --html \
+    --css-include style.css \
+    --set-customization-variable SECTION_NAME_IN_TITLE=1 \
+    --set-customization-variable TREE_TRANSFORMATIONS=complete_tree_nodes_menus \
+    --set-customization-variable FORMAT_MENU=menu \
+    --set-customization-variable SHOW_TITLE=0 \
+    --set-customization-variable DATE_IN_HEADER=1 \
+    --set-customization-variable CLOSE_QUOTE_SYMBOL=\" \
+    --set-customization-variable OPEN_QUOTE_SYMBOL=\" \
+    -o $html index.texi
+cp -a *.webp $html/
+find $html -type d -exec chmod 755 {} +
+find $html -type f -exec chmod 644 {} +
diff --git a/mkfifos.sh b/mkfifos.sh
new file mode 100755
index 0000000..c822253
--- /dev/null
+++ b/mkfifos.sh
@@ -0,0 +1,6 @@
+#!/bin/sh
+
+mkdir fifos
+for f in cert err ok other redir req tls ; do
+    mkfifo fifos/$f
+done
diff --git a/verify.go b/verify.go
index 05fa9e9..6c1ed9e 100644
--- a/verify.go
+++ b/verify.go
@@ -21,7 +21,6 @@ import (
 	"crypto/x509"
 	"encoding/pem"
 	"fmt"
-	"io/ioutil"
 	"log"
 	"os"
 	"os/exec"
@@ -31,8 +30,13 @@ import (
 	"go.cypherpunks.ru/ucspi"
 )
 
+var (
+	CmdCerttool = "certtool"
+	CmdWish     = "wish8.7"
+)
+
 func certInfo(certRaw []byte) string {
-	cmd := exec.Command("certtool", "--certificate-info", "--inder")
+	cmd := exec.Command(CmdCerttool, "--certificate-info", "--inder")
 	cmd.Stdin = bytes.NewReader(certRaw)
 	out, err := cmd.Output()
 	if err != nil {
@@ -156,8 +160,8 @@ grid rowconfigure . 0 -weight 1
 grid columnconfigure . 0 -weight 1
 `)
 
-		cmd := exec.Command("wish8.7")
-		ioutil.WriteFile("/tmp/w.tcl", b.Bytes(), 0666)
+		cmd := exec.Command(CmdWish)
+		// ioutil.WriteFile("/tmp/w.tcl", b.Bytes(), 0666)
 		cmd.Stdin = &b
 		err = cmd.Run()
 		exitError, ok := err.(*exec.ExitError)