Ophiculus

Gemini client in Python

Notes on spec v0.14.2 / 2020-07-02

One, single-request, transaction type.
  C: connect
  S: accept
  <TLS handshake>
  C: Validate server cert
  C: send request
  S: send response header, close connection here for failures
  S: send response body
  S: close connection
  C: handle response

URI scheme: RFC3986, authority required but userinfo disallowed, host required, port defaults to 1965
spaces as %20 not +

THE REQUEST: <URL><CR><LF>
URL in utf-8, 1024 bytes, always absolute, gemini:// scheme optional

RESPONSE HEADER: <STATUS><SPACE><META><CR><LF>
STATUS: 2 digits
META: UTF-8, 1024 bytes

STATUS CODES
1x INPUT
Server is requesting a query parameter. Show META to the user as the prompt, request again as a query parameter.
2x SUCCESS
Response body to follow. META is mime type
3x REDIRECT
Temporary redirect to META
4x TEMPORARY FAILURE
META probably contains more information, show it
5x PERMANENT FAILURE
META probably contains more information, show it. Do not repeat this exact request.
6x CLIENT CERTIFICATE REQUIRED
Your certificate was not accepted or you forgot it. Try again with a different one. META may be useful.

RESPONSE BODIES
Only for 2x statuses, META is MIME type per RFC 2046. Default to "text/gemini; charset=utf-8"; assume UTF-8 if not specified for text/. LF is allowed instead of CRLF to end lines in text/.

TLS
TLS 1.2+ is required, TLS 1.3 is SHOULD.
Trust On First Use is recommended, cache self-signed certs.
some requests will require client certs - on-demand or longer-lived. server caches the hash but client controls when it can be deleted
client certs are scoped to that hostname, and that path & below. example.com/foo -> example.com/foo/bar but not the top level?

text/gemini MIME type:
  has charset, default UTF-8
  has lang parameter, values RFC4646, do not assume a default
  line oriented
CORE LINE TYPES
  text: default case, use as you will. do not collapse blank lines. SHOULD wrap to fit, MUST NOT combine
  link: => URL FRIENDLY-LINK-NAME. any amount of whitespace. MUST NOT automatically make network connections
  preformating toggle: ```. further text to be interpreted as alt text, e.g. for caption or screen reader or syntax highlighting
  preformatted lines (between preformat toggles)
ADVANCED LINE TYPES
  headings: #, ##, ###.
  unordered list: "* ". style only, basically.
  quotes: ">".

EXTENSION STATUS CODES
10 INPUT
11 SENSITIVE INPUT (e.g. passwords), client should hide input field
20 SUCCESS
30 TEMPORARY REDIRECT
31 PERMANENT REDIRECT
40 TEMPORARY FAILURE
41 SERVER UNAVAILABLE
42 CGI ERROR (dynamic content failed)
43 PROXY ERROR
44 SLOW DOWN (rate limited for META seconds)
50 PERMANENT FAILURE
51 NOT FOUND
52 GONE
53 PROXY REQUREST REFUSED (wrong domain)
59 BAD REQUEST
60 CLIENT CERTIFICATE REQUIRED
61 CERTIFICATE NOT AUTHORIZED (for this resource, at least)
62 CERTIFICATE NOT VALID (your problem)




CLIENT RECOMMENDATIONS
- follow no more than 5 redirects in a row
- handle cross protocol redirects
- TLS 1.2 ciphers: only DGE ECDHE for key agreement, AES or ChaCha20 for bulk cipers, SHA2/SHA3 hashes