2.9 KiB
2.9 KiB
go-gemini
go-gemini
implements the Gemini protocol
in Go.
It aims to provide an API similar to that of net/http
to make it easy to
develop Gemini clients and servers.
Examples
See examples/client
and examples/server
for an example client and server.
To run the examples:
go run -tags=example ./examples/server
Overview
A quick overview of the Gemini protocol:
- Client opens connection
- Server accepts connection
- Client and server complete a TLS handshake
- Client validates server certificate
- Client sends request
- Server sends response header
- Server sends response body (only for successful responses)
- Server closes connection
- Client handles response
The way this is implemented in this package is like so:
- Client makes a request with
NewRequest
. The client then sends the request with(*Client).Send(*Request) (*Response, error)
. The client then determines whether to trust the certificate inTrustCertificte(*x509.Certificate, *KnownHosts) bool
. (See TOFU). - Server recieves the request and constructs a response.
The server calls the
Serve(*ResponseWriter, *Request)
method on theHandler
field. The handler writes the response. The server then closes the connection. - Client recieves the response as a
*Response
. The client then handles the response.
TOFU
This package provides an easy way to implement Trust On First Use in your clients. Here is a simple client using TOFU to authenticate certificates:
client := &gemini.Client{
KnownHosts: gemini.LoadKnownHosts(".local/share/gemini/known_hosts"),
TrustCertificate: func(cert *x509.Certificate, knownHosts *gemini.KnownHosts) error {
// If the certificate is in the known hosts list, allow the connection
if err := knownHosts.Lookup(cert); {
return true
}
// Prompt the user
if userTrustsCertificateTemporarily() {
// Temporarily trust the certificate
return true
} else if userTrustsCertificatePermanently() {
// Add the certificate to the known hosts file
knownHosts.Add(cert)
return true
}
// User does not trust the certificate
return false
},
}
client := &gemini.Client{
TrustCertificate: func(cert *x509.Certificate, knownHosts *gemini.KnownHosts) error {
err := knownHosts.Lookup(cert)
if err != nil {
switch err {
case gemini.ErrCertificateNotTrusted:
// Alert the user that the certificate is not trusted
alertUser()
case gemini.ErrCertificateUnknown:
// Prompt the user to trust the certificate
if userTrustsCertificateTemporarily() {
// Temporarily trust the certificate
return nil
} else if user.TrustsCertificatePermanently() {
// Add the certificate to the known hosts file
knownHosts.Add(cert)
return nil
}
}
}
return err
},
}