GopherProxy

	add explanation of TLS support for Gopher and learning material - gopher-tutori…
	git clone git://bitreich.org/gopher-tutorials/ git://enlrupgkhuxnvlhsf6lc3fziv5…
	Log
	Files
	Refs
	Tags
	---
	commit 16560bfbb1105980eebf8c2b9ca8966fb0004444
	parent ab101ec3855175a8a0f42abf6df2f40d5e886af8
	Author: Josuah Demangeon <[email protected]>
	Date: Fri, 12 Mar 2021 23:17:49 +0100

	add explanation of TLS support for Gopher and learning material

	Signed-off-by: Christoph Lohmann <[email protected]>

	Diffstat:
	A gopher-tls.txt \| 94 +++++++++++++++++++++++++++++…

	1 file changed, 94 insertions(+), 0 deletions(-)
	---
	diff --git a/gopher-tls.txt b/gopher-tls.txt
	@@ -0,0 +1,94 @@
	+Adding TLS to Gopher
	+====================
	+The changes are minimal, do not break compatibility, and the support
	+for clients like hurl, curl or servers like geomyidae is already there.
	+
	+Context and challenge
	+---------------------
	+Traditionnal clients use port 70 without encryption, for which we want
	+compatibility.
	+
	+The gophermap syntax, with gopher links, write down only one port
	+(usually 70), so bringing Gopher+TLS on a different port would require
	+changing the gophermap standard for everyone, and breaking compatibility,
	+and also asking everyone to change their content.
	+
	+The best compromise would be using port 70 for both plaintext and
	+encrypted gopher to preserve gophermaps, with no change for the plaintext
	+version to keep compatibility.
	+
	+It happen to be possible and not difficult to implement using only
	+standard (POSIX.1) features.
	+
	+If the client use raw TCP, the server communicate in raw TCP.
	+
	+If the client uses TLS, the server communicates in TLS right away.
	+
	+Without TLS
	+-----------
	+ [ Client open TCP to Server on port :70 ]
	+ C: /page\r\n
	+ S: Hello world!
	+
	+The client sends usual selector directly over TCP, in which case the
	+content is served over plain TCP (non-encrypted).
	+
	+With TLS
	+--------
	+ [ Client opens TCP to Server on port :70 ]
	+ [ Client negotiate TLS with server ]
	+ C: /page\r\n
	+ S: Hello world!
	+
	+The client open TLS on the port 70. The server notices that the
	+first byte is 0x16, as always in TLS, and pursue with negotiation.
	+
	+How to implement
	+----------------
	+The only thing needed for negotiation is reading the first byte and check
	+if it is 0x16.
	+
	+In order to read without messing up the data stream from the client,
	+POSIX provides at least two ways to peek at the data without shifting
	+the read position, such as pread(2) and recv(2).
	+
	+Using recv(2):
	+
	+ if (recv(sockfd, buf, 1, MSG_PEEK) < 1)
	+ err("could not peek at first byte");
	+ if (buf[0] == 0x16)
	+ istls = 1;
	+
	+> The MSG_PEEK flag causes the receive operation to return data from the
	+> beginning of the receive queue without removing that data from the queue.
	+> Thus, a subsequent receive call will return the same data. -- recv(2)
	+
	+[7\|man page search:\|/man.dcgi\|perso.pw\|70]
	+
	+Then we can pursue with plain TCP or with TLS right away without
	+negtciating anything nor breaking existing clients that only handle TCP.
	+Graceful fallback does not change anything for the client.
	+
	+Known implementations
	+---------------------
	+Here are not listed generic tools that can add a layer of TLS encryption
	+which can also work for Gopher.
	+
	+### Geomyidae (server)
	+
	+[1\|project home page\|/scm/geomyidae/files.gph\|bitreich.org\|70]
	+[1\|commit 07240d76\|/scm/geomyidae/commit/07240d76fd8e1d0a67c49bf7e123bb508613e…
	+
	+### Hurl (client)
	+
	+Use gophers:// to explicitely use gopher on top of TLS.
	+
	+[1\|project home page\|/git/hurl/files.gph\|git.codemadness.org\|70]
	+[1\|commit 9546c0f1\|/git/hurl/commit/9546c0f17665658befbc25876245acaa9db4b08f.g…
	+
	+### Curl (client)
	+
	+Use gophers:// to explicitely use gopher on top of TLS.
	+
	+[h\|project home page\|URL:https://curl.haxx.se/\|\|]
	+[h\|commit a1f06f32\|URL:https://github.com/curl/curl/commit/a1f06f32b8603427535…