go-gemini/README.md

87 lines
2.7 KiB
Markdown
Raw Normal View History

2020-09-21 13:48:42 -06:00
# go-gemini
2020-09-21 16:28:34 -06:00
[![GoDoc](https://godoc.org/git.sr.ht/~adnano/go-gemini?status.svg)](https://godoc.org/git.sr.ht/~adnano/go-gemini)
2020-09-21 20:09:50 -06:00
`go-gemini` implements the [Gemini protocol](https://gemini.circumlunar.space)
in Go.
2020-09-21 13:48:42 -06:00
2020-09-21 15:23:51 -06:00
It aims to provide an API similar to that of `net/http` to make it easy to
develop Gemini clients and servers.
2020-09-21 13:48:42 -06:00
2020-09-21 15:23:51 -06:00
## Examples
2020-09-21 13:48:42 -06:00
2020-09-27 15:44:49 -06:00
There are a few examples provided in the `examples` directory.
Some examples might require you to generate TLS certificates.
2020-09-21 13:48:42 -06:00
2020-09-21 15:23:51 -06:00
To run the examples:
2020-09-21 13:48:42 -06:00
2020-09-21 16:25:31 -06:00
go run -tags=example ./examples/server
2020-09-24 18:13:59 -06:00
## Overview
A quick overview of the Gemini protocol:
1. Client opens connection
2. Server accepts connection
3. Client and server complete a TLS handshake
4. Client validates server certificate
5. Client sends request
6. Server sends response header
7. Server sends response body (only for successful responses)
8. Server closes connection
9. Client handles response
The way this is implemented in this package is like so:
2020-09-25 16:53:20 -06:00
1. Client makes a request with `NewRequest`. The client then sends the request
2020-09-25 21:06:54 -06:00
with `(*Client).Send(*Request) (*Response, error)`. The client then determines whether
2020-09-27 15:44:49 -06:00
to trust the certificate (see [Trust On First Use](#trust-on-first-use)).
2020-09-24 18:13:59 -06:00
2. Server recieves the request and constructs a response.
The server calls the `Serve(*ResponseWriter, *Request)` method on the
`Handler` field. The handler writes the response. The server then closes
the connection.
2020-09-25 17:53:50 -06:00
3. Client recieves the response as a `*Response`. The client then handles the
response.
2020-09-25 21:06:54 -06:00
2020-09-27 15:44:49 -06:00
## Trust On First Use
2020-09-25 21:06:54 -06:00
2020-09-26 11:59:24 -06:00
`go-gemini` makes it easy to implement Trust On First Use in your clients.
2020-09-27 14:21:56 -06:00
The default client loads known hosts from `$XDG_DATA_HOME/gemini/known_hosts`.
If that is all you need, you can simply use the top-level `Send` function:
```go
2020-09-27 14:31:41 -06:00
// Send uses the default client, which will load the default list of known hosts.
2020-09-27 19:40:51 -06:00
req := gmi.NewRequest("gemini://example.com")
gmi.Send(req)
2020-09-27 14:21:56 -06:00
```
Clients can also load their own list of known hosts:
2020-09-25 21:06:54 -06:00
```go
2020-09-27 18:20:59 -06:00
client := &gmi.Client{}
2020-09-27 14:21:56 -06:00
if err := client.KnownHosts.LoadFrom("path/to/my/known_hosts"); err != nil {
2020-09-26 11:59:24 -06:00
log.Fatal(err)
2020-09-25 21:06:54 -06:00
}
```
2020-09-26 11:59:24 -06:00
Clients can then specify how to trust certificates in the `TrustCertificate`
field:
```go
2020-09-27 18:20:59 -06:00
client.TrustCertificate = func(hostname string, cert *x509.Certificate, knownHosts *gmi.KnownHosts) error {
2020-09-26 11:59:24 -06:00
// If the certificate is in the known hosts list, allow the connection
2020-09-27 14:21:56 -06:00
return knownHosts.Lookup(hostname, cert)
2020-09-26 11:59:24 -06:00
}
```
2020-09-27 17:45:48 -06:00
Advanced clients can prompt the user for what to do when encountering an unknown
certificate. See `examples/client` for an example.
2020-09-27 15:44:49 -06:00
## Client Authentication
Gemini takes advantage of client certificates for authentication.
See `examples/auth` for an example server which authenticates its users with a
username and password, and uses their client certificate to remember sessions.