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