Verify TLS certificates using different network perspectives
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

63 lines
3.1 KiB

3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
  1. # Trust Seeker
  2. _Verify TLS certificates using different network perspectives._
  3. Trust Seeker is a certificate pinning program that can be run privately, on the command line, or publicly, as a server-side CGI script. Each public trust seeker can be asked what certificate it sees for a certain host. Client software can query multiple trust seekers, to check for consensus.
  4. It aims to bring as much relevant information as possible to bear on any trust decision. This includes the TLS version and cipher suite, to help defend against downgrade attacks.
  5. Example:
  6. ```
  7. trust-seeker --ask https://example.org/cgi/trust-seeker \
  8. --verify gemini.circumlunar.space:1965 \
  9. --fingerprint sha256:1234567890123456789012345678901234567890123456789012345678901234
  10. # Response:
  11. status=mismatch
  12. fingerprint=sha256:1a03a15619200db4496494ec90381c1fe8bd9e0142260f6d8a3d962ed3cfc72f
  13. fingerprint_base64=sha256:GgOhVhkgDbRJZJTskDgcH+i9ngFCJg9tij2WLtPPxy8=
  14. expires=1759488637
  15. tls_version=1.3
  16. cipher_suite=TLS_AES_256_GCM_SHA384
  17. first_seen=1617463930
  18. last_seen=1618133995
  19. seen_count=2
  20. ```
  21. Trust Seeker mixes ideas from:
  22. * Moxie Marlinspike's [Convergence](https://youtu.be/UawS3_iuHoA?t=2100) project
  23. * Recommendations made in ["Public Key Pinning for TLS Using a Trust on First Use Model"](https://homepages.staff.os3.nl/~delaat/rp/2012-2013/p56/report.pdf) (Gabor X Toth & Tjebbe Vlieg, 2013)
  24. It can verify TLS certificates on any host and port, regardless of the protocol underneath: HTTP, DNS (DoT and DoH), e-mail (SMTP, IMAP, POP3), IRC, FTP, Gemini, [Gopher](https://github.com/curl/curl/commit/a1f06f32b8603427535fc21183a84ce92a9b96f7), etc.
  25. SSH and STARTTLS support are on the roadmap.
  26. Trust Seeker can be used with command line tools that support public key pinning, such as [curl](https://curl.se/libcurl/c/CURLOPT_PINNEDPUBLICKEY.html) and wget, to protect every connection they make. For instance, this is how it can be used with curl to verify a self-signed certificate based on example.org's network perspective:
  27. ```
  28. # ask example.org about self-signed.badssl.com
  29. response=$(trust-seeker --ask https://example.org/cgi/trust-seeker \
  30. self-signed.badssl.com:443)
  31. # get certificate's public key (SubjectPublicKeyInfo)
  32. spki=$(echo "$response" | grep 'fingerprint_base64=sha256:' | cut -d ':' -f 2)
  33. # get minimum TLS version
  34. tlsv=$(echo "$response" | grep 'tls_version=' | cut -d '=' -f 2)
  35. # run curl with key pinning instead of CA validation
  36. curl -k --pinnedpubkey "sha256//$spki" "--tlsv$tlsv" https://self-signed.badssl.com/
  37. ```
  38. The holy grail is to enable this kind of dynamic key pinning for e-mail server-to-server communication, which generally relies on opportunistic encryption.
  39. ## Current status
  40. The code is in an early exploratory stage. You can experiment with it, but big changes are planned and there is no regard for backward compatibility at this point.
  41. ## Contributing
  42. The project is hosted at [https://tildegit.org/nervuri/trust-seeker](https://tildegit.org/nervuri/trust-seeker). Just [shoot me an email](https://nervuri.net/contact) if you don't want to [make a tildegit account](https://tildegit.org/user/sign_up).