Browse Source

add examples to README.md

master
nervuri 2 months ago
parent
commit
d6af13e8e4
  1. 51
      README.md

51
README.md

@ -1,21 +1,58 @@
# Trust Seeker
Verify TLS certificates using different network perspectives.
_Verify TLS certificates using different network perspectives._
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.
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.
Example:
```
trust-seeker --ask https://example.org/cgi/trust-seeker \
--verify gemini.circumlunar.space:1965 \
--fingerprint sha256:1234567890123456789012345678901234567890123456789012345678901234
# Response:
status=mismatch
fingerprint=sha256:1a03a15619200db4496494ec90381c1fe8bd9e0142260f6d8a3d962ed3cfc72f
fingerprint_base64=sha256:GgOhVhkgDbRJZJTskDgcH+i9ngFCJg9tij2WLtPPxy8=
expires=1759488637
tls_version=1.3
cipher_suite=TLS_AES_256_GCM_SHA384
first_seen=1617463930
last_seen=1618133995
seen_count=2
```
Trust Seeker mixes ideas from:
* Moxie Marlinspike's [Convergence](https://youtu.be/UawS3_iuHoA?t=2100) project
* Recommendations made in ["Public Key Pinning for TLS Using a Trust on First Use Model"](https://rp.delaat.net/2012-2013/p56/report.pdf) (Gabor X Toth & Tjebbe Vlieg, 2013)
* 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)
It is a certificate pinning program that can be run either 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.
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.
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.
SSH and STARTTLS support are on the roadmap.
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.
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 using example.org's network perspective:
```
# ask example.org's trust seeker about self-signed.badssl.com
response=$(trust-seeker --ask https://example.org/cgi/trust-seeker \
self-signed.badssl.com:443)
# get certificate's public key (SubjectPublicKeyInfo)
spki=$(echo "$response" | grep 'fingerprint_base64=sha256:' | cut -d ':' -f 2)
# get minimum TLS version
tlsv=$(echo "$response" | grep 'tls_version=' | cut -d '=' -f 2)
SSH support is on the roadmap.
# run curl with key pinning instead of CA validation
curl -k --pinnedpubkey "sha256//$spki" "--tlsv$tlsv" https://self-signed.badssl.com/
```
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. The holy grail is to enable this kind of dynamic key pinning for e-mail server-to-server communication, which currently relies on opportunistic encryption.
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.
## Current status

Loading…
Cancel
Save