-- Leo's gemini proxy
-- Connecting to git.thebackupbox.net:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/gemini
repo: gemini-site action: commit revision: path_from: revision_from: c58af6fe7f86e6f0f1364bf439f158ebd1a3ef57: path_to: revision_to:
commit c58af6fe7f86e6f0f1364bf439f158ebd1a3ef57
Author: Solderpunk <solderpunk@sdf.org>
Date: Tue May 26 20:52:06 2020 +0000
Rearrange spec sections without any semantic change.
diff --git a/docs/spec-spec.txt b/docs/spec-spec.txt
--- a/docs/spec-spec.txt +++ b/docs/spec-spec.txt @@ -21,7 +21,7 @@ solderpunk@sdf.org. ----------------------------- -1. Overview +1 Overview Gemini is a client-server protocol featuring request-response transactions, broadly similar to gopher or HTTP. Connections are @@ -40,16 +40,16 @@ follows: C: Opens connection S: Accepts connection -C/S: Complete TLS handshake (see 1.4) -C: Validates server certificate (see 1.4.2) -C: Sends request (one CRLF terminated line) (see 1.2) +C/S: Complete TLS handshake (see section 4) +C: Validates server certificate (see 4.2) +C: Sends request (one CRLF terminated line) (see section 2) S: Sends response header (one CRLF terminated line), closes connection - under non-success conditions (see 1.3.1, 1.3.2) -S: Sends response body (text or binary data) (see 1.3.3) + under non-success conditions (see 3.1 and 3.2) +S: Sends response body (text or binary data) (see 3.3) S: Closes connection -C: Handles response (see 1.3.4) +C: Handles response (see 3.4) -1.2 Gemini requests +2 Gemini requests Gemini requests are a single CRLF-terminated line with the following structure: @@ -70,19 +70,19 @@ resources over Gemini. Proxying is optional and the vast majority of servers are expected to only respond to requests for resources at their own domain(s). -1.3 Responses +3 Gemini responses Gemini response consist of a single CRLF-terminated header line, optionally followed by a response body. -1.3.1 Response headers +3.1 Response headers Gemini response headers look like this: <STATUS><SPACE><META><CR><LF> <STATUS> is a two-digit numeric status code, as described below in -1.3.2 and in Appendix 1. +3.2 and in Appendix 1. <META> is a UTF-8 encoded string of maximum length 1024 bytes, whose meaning is <STATUS> dependent. @@ -98,7 +98,7 @@ If a server sends a <STATUS> which is not a two-digit number or a connection and disregard the response header, informing the user of an error. -1.3.2 Status codes +3.2 Status codes Gemini uses two-digit numeric status codes. Related status codes share the same first digit. Importantly, the first digit of Gemini status @@ -194,7 +194,7 @@ increased power (and correspondingly increased complexity) of the second digits is entirely "opt-in" on the part of both servers and clients. -1.3.3 Response bodies +3.3 Response bodies Response bodies are just raw content, text or binary, ala gopher. There is no support for compression, chunking or any other kind of @@ -226,13 +226,14 @@ they cannot decode SHOULD gracefully inform the user what happened instead of displaying garbage. If <META> is an empty string, the MIME type MUST default to -"text/gemini; charset=utf-8". +"text/gemini; charset=utf-8". The text/gemini media type is defined +in section 5. -1.3.4 Response body handling +3.4 Response body handling Response handling by clients should be informed by the provided MIME type information. Gemini defines one MIME type of its own -(text/gemini) whose handling is discussed below in 1.3.5. In all +(text/gemini) whose handling is discussed below in section 5. In all other cases, clients should do "something sensible" based on the MIME type. Minimalistic clients might adopt a strategy of printing all other text/* responses to the screen without formatting and saving @@ -240,9 +241,100 @@ all non-text responses to the disk. Clients for unix systems may consult /etc/mailcap to find installed programs for handling non-text types. -1.3.5 text/gemini responses +4 TLS -1.3.5.1 Overview +Use of TLS for Gemini transactions is mandatory. + +Use of the Server Name Indication (SNI) extension to TLS is also +mandatory, to facilitate name-based virtual hosting. + +4.1 Version requirements + +Servers MUST use TLS version 1.2 or higher and SHOULD use TLS version +1.3 or higher. TLS 1.2 is reluctantly permitted for now to avoid +drastically reducing the range of available implementation libraries. +Hopefully TLS 1.3 or higher can be specced in the near future. +Clients who wish to be "ahead of the curve MAY refuse to connect to +servers using TLS version 1.2 or lower. + +4.2 Server certificate validation + +Clients can validate TLS connections however they like (including not +at all) but the strongly RECOMMENDED approach is to implement a +lightweight "TOFU" certificate-pinning system which treats self-signed +certificates as first- class citizens. This greatly reduces TLS +overhead on the network (only one cert needs to be sent, not a whole +chain) and lowers the barrier to entry for setting up a Gemini site +(no need to pay a CA or setup a Let's Encrypt cron job, just make a +cert and go). + +TOFU stands for "Trust On First Use" and is public-key security model +similar to that used by OpenSSH. The first time a Gemini client +connects to a server, it accepts whatever certificate it is presented. +That certificate's fingerprint and expiry date are saved in a +persistent database (like the .known_hosts file for SSH), associated +with the server's hostname. On all subsequent connections to that +hostname, the received certificate's fingerprint is computed and +compared to the one in the database. If the certificate is not the +one previously received, but the previous certificate's expiry date +has not passed, the user is shown a warning, analogous to the one web +browser users are shown when receiving a certificate without a +signature chain leading to a trusted CA. + +This model is by no means perfect, but it is not awful and is vastly +superior to just accepting self-signed certificates unconditionally. + +4.3 Transient client certificate sessions + +Self-signed client certificates can optionally be used by Gemini +clients to permit servers to recognise subsequent requests from the +same client as belonging to a single "session". This facilitates +maintaining state in server-side applications. The functionality is +very similar to HTTP cookies, but with important differences. + +Whereas HTTP cookies are originally created by a webserver and given +to a client via a response header, client certificates are created by +the client and given to the server as part of the TLS handshake: +Client certificates are fundamentally a client-centric means of +identification. Further, whereas HTTP cookies can be "resurrected" by +webservers after a client deletes them if the server recognises the +client by means of browser finger-printing or some other tracking +technology (leading to unkillable "super cookies"), if a client +deletes a client certificate and also the accompanying private key +(which the server has never seen), then the session ID can never be +recreated. Thus clients not only need to opt in to a certificate +session, but once they have done so they retain a guaranteed ability +to opt out of it at any point and the server cannot defeat this +ability. + +Gemini requests typically will be made without a client certificate +being sent to the server. If a requested resource is part of a +server-side application which requires persistent state, a Gemini +server can return a status code of 61 (see Appendix 1 below) to +request that the client repeat the request with a "transient +certificate" to initiate a client certificate section. + +Interactive clients for human users MUST inform users that such a +session has been requested and require the user to approve generation +of such a certificate. Transient certificates MUST NOT be generated +automatically. + +Transient certificates are limited in scope to a particular domain. +Transient certificates MUST NOT be reused across different domains. + +Transient certificates MUST be permanently deleted when the matching +server issues a response with a status code of 21 (see Appendix 1 +below). + +Transient certificates MUST be permanently deleted when the client +process terminates. + +Transient certificates SHOULD be permanently deleted after not having +been used for more than 24 hours. + +5 The text/gemini media type + +5.1 Overview In the same sense that HTML is the "native" response format of HTTP and plain text is the native response format of gopher, Gemini defines @@ -264,7 +356,7 @@ simple clients can function correctly while ignoring the second digit, the text/gemini format has been designed so that simple clients can ignore the more advanced features and still remain very usable. -1.3.5.2 Line-orientation +5.2 Line-orientation As mentioned, the text/gemini format is line-oriented. Each line of a text/gemini document has a single "line type". It is possible to @@ -277,16 +369,16 @@ in scope to that individual line. There are 6 different line types in total. However, a fully functional and specification compliant Gemini client need only recognise and handle 4 of them - these are the "core line types", -(see 1.3.5.3). Advanced clients can also handle the additional -"advanced line types" (see 1.3.5.4). Simple clients can treat all +(see 5.3). Advanced clients can also handle the additional +"advanced line types" (see 5.4). Simple clients can treat all advanced line types as one of the core line types and still offer an adequate user experience. -1.3.5.3 Core line types +5.3 Core line types The four core line types are: -1.3.5.3.1 Text lines +5.3.1 Text lines Text lines are the most fundamenal line type - any line which does not match the definition of another line type defined below defaults @@ -306,7 +398,7 @@ background colour, etc. Authors should not expect to exercise any control over the precise rendering of their text lines, only of their actual textual content. Content such as ASCII art, computer source code, etc. which may appear incorrectly when treated as such should -be enclosed beween preformatting toggle lines (see 1.3.5.3.3). +be enclosed beween preformatting toggle lines (see 5.3.3). Blank lines are instances of text lines and have no special meaning. They should be rendered individually as vertical blank space each @@ -338,7 +430,7 @@ the content will display neatly on clients whose display device is as wide as the hard-wrapped length or wider, but will appear with irregular line widths on narrower clients. -1.3.5.3.2 Link lines +5.3.2 Link lines Lines beginning with the two characters "=>" are link lines, which have the following syntax: @@ -371,7 +463,7 @@ non-gopher content via a non-standard adaptation of the `h` item-type. Clients can present links to users in whatever fashion the client author wishes. -1.3.5.3.3 Preformatting toggle lines +5.3.3 Preformatting toggle lines Any line whose first three characters are "```" (i.e. three consecutive back ticks with no leading whitespace) are preformatted @@ -382,12 +474,12 @@ should be "off" at the beginning of a document. The current status of preformatted mode is the only internal state a parser is required to maintain. When preformatted mode is "on", the usual rules for identifying line types are suspended, and all lines should be -identified as preformatted text lines (see 1.3.5.3.4). +identified as preformatted text lines (see 5.3.4). Preformatting toggle lines can be thought of as analogous to <pre> and </pre> tags in HTML. -1.3.5.3.4 Preformatted text lines +5.3.4 Preformatted text lines Preformatted text lines should be presented to the user in a "neutral", monowidth font without any alteration to whitespace or stylistic @@ -400,13 +492,13 @@ significant whitespace (e.g. Python) should be able to be copied and pasted from the client into a file and interpreted/compiled without any problems arising from the client's manner of displaying them. -1.3.5.4 Advanced line types +5.4 Advanced line types The following advanced line types MAY be recognised by advanced clients. Simple clients may treat them all as text lines as per -1.3.5.3.1 without any loss of essential function. +5.3.1 without any loss of essential function. -1.3.5.4.1 Heading lines +5.4.1 Heading lines Lines beginning with "#" are heading lines. Heading lines consist of one, two or three consecutive "#" characters, followed by optional @@ -428,7 +520,7 @@ scrolling. CMS-style tools automatically generating menus or Atom/RSS feeds for a directory of text/gemini files can use first heading in the file as a human-friendly title. -1.3.5.4.2 Unordered list items +5.4.2 Unordered list items Lines beginning with a * are unordered list items. This line type exists purely for stylistic reasons. The * may be replaced in @@ -439,103 +531,15 @@ can take the space of the bullet symbol into account when wrapping long list items to ensure that all lines of text corresponding to the item are offset an equal distance from the left of the screen. -1.4 TLS - -Use of TLS for Gemini transactions is mandatory. - -Use of the Server Name Indication (SNI) extension to TLS is also -mandatory, to facilitate name-based virtual hosting. - -1.4.1 Version requirements - -Servers MUST use TLS version 1.2 or higher and SHOULD use TLS version -1.3 or higher. Clients MAY refuse to connect to servers using TLS -version 1.2 or lower. - -1.4.2 Server certificate validation - -Clients can validate TLS connections however they like (including not -at all) but the strongly RECOMMENDED approach is to implement a -lightweight "TOFU" certificate-pinning system which treats self-signed -certificates as first- class citizens. This greatly reduces TLS -overhead on the network (only one cert needs to be sent, not a whole -chain) and lowers the barrier to entry for setting up a Gemini site -(no need to pay a CA or setup a Let's Encrypt cron job, just make a -cert and go). - -TOFU stands for "Trust On First Use" and is public-key security model -similar to that used by OpenSSH. The first time a Gemini client -connects to a server, it accepts whatever certificate it is presented. -That certificate's fingerprint and expiry date are saved in a -persistent database (like the .known_hosts file for SSH), associated -with the server's hostname. On all subsequent connections to that -hostname, the received certificate's fingerprint is computed and -compared to the one in the database. If the certificate is not the -one previously received, but the previous certificate's expiry date -has not passed, the user is shown a warning, analogous to the one web -browser users are shown when receiving a certificate without a -signature chain leading to a trusted CA. - -This model is by no means perfect, but it is not awful and is vastly -superior to just accepting self-signed certificates unconditionally. - -1.4.3 Transient client certificate sessions - -Self-signed client certificates can optionally be used by Gemini -clients to permit servers to recognise subsequent requests from the -same client as belonging to a single "session". This facilitates -maintaining state in server-side applications. The functionality is -very similar to HTTP cookies, but with important differences. - -Whereas HTTP cookies are originally created by a webserver and given -to a client via a response header, client certificates are created by -the client and given to the server as part of the TLS handshake: -Client certificates are fundamentally a client-centric means of -identification. Further, whereas HTTP cookies can be "resurrected" by -webservers after a client deletes them if the server recognises the -client by means of browser finger-printing or some other tracking -technology (leading to unkillable "super cookies"), if a client -deletes a client certificate and also the accompanying private key -(which the server has never seen), then the session ID can never be -recreated. Thus clients not only need to opt in to a certificate -session, but once they have done so they retain a guaranteed ability -to opt out of it at any point and the server cannot defeat this -ability. - -Gemini requests typically will be made without a client certificate -being sent to the server. If a requested resource is part of a -server-side application which requires persistent state, a Gemini -server can return a status code of 61 (see Appendix 1 below) to -request that the client repeat the request with a "transient -certificate" to initiate a client certificate section. - -Interactive clients for human users MUST inform users that such a -session has been requested and require the user to approve generation -of such a certificate. Transient certificates MUST NOT be generated -automatically. - -Transient certificates are limited in scope to a particular domain. -Transient certificates MUST NOT be reused across different domains. - -Transient certificates MUST be permanently deleted when the matching -server issues a response with a status code of 21 (see Appendix 1 -below). - -Transient certificates MUST be permanently deleted when the client -process terminates. - -Transient certificates SHOULD be permanently deleted after not having -been used for more than 24 hours. - Appendix 1. Full two digit status codes 10 INPUT - As per definition of single-digit code 1 in 1.3.2. + As per definition of single-digit code 1 in 3.2. 20 SUCCESS - As per definition of single-digit code 2 in 1.3.2. + As per definition of single-digit code 2 in 3.2. 21 SUCCESS - END OF CLIENT CERTIFICATE SESSION @@ -550,7 +554,7 @@ Appendix 1. Full two digit status codes 30 REDIRECT - TEMPORARY - As per definition of single-digit code 3 in 1.3.2. + As per definition of single-digit code 3 in 3.2. 31 REDIRECT - PERMANENT @@ -568,7 +572,7 @@ Appendix 1. Full two digit status codes 40 TEMPORARY FAILURE - As per definition of single-digit code 4 in 1.3.2. + As per definition of single-digit code 4 in 3.2. 41 SERVER UNAVAILABLE @@ -595,7 +599,7 @@ Appendix 1. Full two digit status codes 50 PERMANENT FAILURE - As per definition of single-digit code 5 in 1.3.2. + As per definition of single-digit code 5 in 3.2. 51 NOT FOUND @@ -627,12 +631,12 @@ Appendix 1. Full two digit status codes 60 CLIENT CERTIFICATE REQUIRED - As per definition of single-digit code 6 in 1.3.2. + As per definition of single-digit code 6 in 3.2. 61 TRANSIENT CERTIFICATE REQUESTED The server is requesting the initiation of a transient client - certificate session, as described in 1.4.3. The client should + certificate session, as described in 4.3. The client should ask the user if they want to accept this and, if so, generate a disposable key/cert pair and re-request the resource using it. The key/cert pair should be destroyed when the client quits,
-----END OF PAGE-----
-- Response ended
-- Page fetched on Sun Jun 2 17:38:29 2024