logo

drewdevault.com

[mirror] blog and personal website of Drew DeVault git clone https://hacktivis.me/git/mirror/drewdevault.com.git

Gemini-TOFU.md (4114B)

    

  1. ---
  2. title: TOFU recommendations for Gemini
  3. date: 2020-09-21
  4. outputs: [html, gemtext]
  5. ---
  7. I will have more to say about [Gemini][0] in the future, but for now, I wanted to
  8. write up some details about one thing in particular: the trust-on-first-use
  9. algorithm I implemented for my client, [gmni][1]. I think you should implement
  10. this algorithm, too!
  12. [0]: https://gemini.circumlunar.space/
  13. [1]: https://sr.ht/~sircmpwn/gmni
  15. First of all, it's important to note that the Gemini specification explicitly
  16. mentions TOFU and the role of self-signed certificates: they are the norm in
  17. Geminiland, and if your client does not support them then you're going to be
  18. unable to browse many sites. However, the exact details are left up to the
  19. implementation. Here's what mine does:
  21. First, on startup, it finds the known_hosts file. For my client, this is
  22. `~/.local/share/gmni/known_hosts` (the exact path is adjusted as necessary per
  23. the XDG basedirs specification). Each line of this file represents a known host,
  24. and each host has four fields separated by spaces, in this order:
  26. - Hostname (e.g. gemini.circumlunar.space)
  27. - Fingerprint algorithm (e.g. SHA-512)
  28. - Fingerprint, in hexadecimal, with ':' between each octet (e.g. 55:01:D8...)
  29. - Unix timestamp of the certificate's notAfter date
  31. If a known_hosts entry is encountered with a hashing algorithm you don't
  32. understand, it is disregarded.
  34. Then, when processing a request and deciding whether or not to trust its
  35. certificate, take the following steps:
  37. 1. Verify that the certificate makes sense. Check the notBefore and notAfter
  38.    dates against the current time, and check that the hostname is correct
  39.    (including wildcards). Apply any other scrutiny you want, like enforcing a
  40.    good hash algorithm or an upper limit on the expiration date. If these checks
  41.    do not pass, the trust state is INVALID, GOTO 5.
  42. 2. Compute the certificate's fingerprint. Use the entire certificate (in OpenSSL
  43.    terms, `X509_digest` will do this), not just the public key.[^1]
  44. 3. Look up the known_hosts record for this hostname. If one is found, but the
  45.    record is expired, disregard it. If one is found, and the fingerprint does
  46.    not match, the trust state is UNTRUSTED, GOTO 5. Otherwise, the trust state
  47.    is TRUSTED. GOTO 7.
  48. 4. The trust state is UNKNOWN. GOTO 5.
  49. 5. Display information about the certficate and its trust state to the user, and
  50.    prompt them to choose an action, from the following options:
  51.    - If INVALID, the user's choices are ABORT or TRUST_TEMPORARY.
  52.    - If UNKNOWN, the user's choices are ABORT, TRUST_TEMPORARY, or TRUST_ALWAYS.
  53.    - If UNTRUSTED, abort the request and display a diagnostic message. The user
  54.      must manually edit the known_hosts file to correct the issue.
  55. 6. Complete the requested action:
  56.    - If ABORT, terminate the request.
  57.    - If TRUST_TEMPORARY, update the session's list of known hosts.
  58.    - If TRUST_ALWAYS, append a record to the known_hosts file and update the
  59.      session's list of known hosts.
  60. 7. Allow the request to proceed.
  62. If the trust state is UNKNOWN, instead of requring user input to proceed, the
  63. implementation MAY proceed with the request IF the UI displays that a new
  64. certificate was trusted and provides a means to review the certificate and
  65. revoke that trust.
  67. Note that being signed by a certificate authority in the system trust store is
  68. not considered meaningful to this algorithm. Such a cert is TOFU'd all the same.
  70. [^1]: Rationale: this fingerprint matches the output of `openssl x509 -sha512 -fingerprint`.
  72. That's it! If you have feedback on this approach, please [send me an
  73. email](mailto:sir@cmpwn.com).
  75. My implementation doesn't *entirely* match this behavior, but it's close and
  76. I'll finish it up before 1.0. If you want to read the code, [here it is][2].
  78. [2]: https://git.sr.ht/~sircmpwn/gmni/tree/master/src/tofu.c
  80. Bonus recommendation for servers: you **should** use a self-signed certificate,
  81. and you **should not** use a certificate signed by one of the mainstream
  82. certificate authorities. We don't need to carry along the legacy CA cabal into
  83. our brave new Gemini future.