Update KnownHosts documentation

cert.go

@@ -28,7 +28,7 @@ type CertificateStore struct {
 
 // Add adds a certificate for the given scope to the store.
 // It tries to parse the certificate if it is not already parsed.
-func (c *CertificateStore) Add(scope string, cert tls.Certificate) error {
+func (c *CertificateStore) Add(scope string, cert tls.Certificate) {
 	if c.store == nil {
 		c.store = map[string]tls.Certificate{}
 	}
@@ -39,15 +39,18 @@ func (c *CertificateStore) Add(scope string, cert tls.Certificate) error {
 			cert.Leaf = parsed
 		}
 	}
+	c.store[scope] = cert
+}
+
+// Write writes the provided certificate to the certificate directory.
+func (c *CertificateStore) Write(scope string, cert tls.Certificate) error {
 	if c.dir {
-		// Write certificates
 		certPath := filepath.Join(c.path, scope+".crt")
 		keyPath := filepath.Join(c.path, scope+".key")
 		if err := WriteCertificate(cert, certPath, keyPath); err != nil {
 			return err
 		}
 	}
-	c.store[scope] = cert
 	return nil
 }
 
@@ -82,6 +85,12 @@ func (c *CertificateStore) Load(path string) error {
 	return nil
 }
 
+// SetOutput sets the directory that new certificates will be written to.
+func (c *CertificateStore) SetOutput(path string) {
+	c.dir = true
+	c.path = path
+}
+
 // CertificateOptions configures the creation of a certificate.
 type CertificateOptions struct {
 	// Subject Alternate Name values.

client.go

@@ -47,7 +47,7 @@ type Client struct {
 	// the request of a server.
 	// If CreateCertificate is nil or the returned error is not nil,
 	// the request will not be sent again and the response will be returned.
-	CreateCertificate func(hostname, path string) (tls.Certificate, error)
+	CreateCertificate func(scope, path string) (tls.Certificate, error)
 
 	// TrustCertificate is called to determine whether the client
 	// should trust a certificate it has not seen before.
@@ -108,6 +108,7 @@ func (c *Client) do(req *Request, via []*Request) (*Response, error) {
 	if err := resp.read(conn); err != nil {
 		return nil, err
 	}
+	resp.Request = req
 	// Store connection state
 	resp.TLS = conn.ConnectionState()
 
@@ -151,11 +152,7 @@ func (c *Client) do(req *Request, via []*Request) (*Response, error) {
 		if err != nil {
 			return resp, err
 		}
-
 		target = req.URL.ResolveReference(target)
-		if target.Scheme != "" && target.Scheme != "gemini" {
-			return resp, nil
-		}
 
 		redirect := NewRequestFromURL(target)
 		if c.CheckRedirect != nil {
@@ -166,7 +163,6 @@ func (c *Client) do(req *Request, via []*Request) (*Response, error) {
 		}
 	}
 
-	resp.Request = req
 	return resp, nil
 }
 
@@ -221,17 +217,20 @@ func (c *Client) verifyConnection(req *Request, cs tls.ConnectionState) error {
 		if c.TrustCertificate != nil {
 			switch c.TrustCertificate(hostname, cert) {
 			case TrustOnce:
-				c.KnownHosts.AddTemporary(hostname, cert)
+				fingerprint := NewFingerprint(cert.Raw, cert.NotAfter)
+				c.KnownHosts.Add(hostname, fingerprint)
 				return nil
 			case TrustAlways:
-				c.KnownHosts.Add(hostname, cert)
+				fingerprint := NewFingerprint(cert.Raw, cert.NotAfter)
+				c.KnownHosts.Add(hostname, fingerprint)
+				c.KnownHosts.Write(hostname, fingerprint)
 				return nil
 			}
 		}
 		return errors.New("gemini: certificate not trusted")
 	}
 
-	fingerprint := NewFingerprint(cert)
+	fingerprint := NewFingerprint(cert.Raw, cert.NotAfter)
 	if knownHost.Hex == fingerprint.Hex {
 		return nil
 	}

doc.go

@@ -1,55 +0,0 @@
-/*
-Package gemini implements the Gemini protocol.
-
-Get makes a Gemini request:
-
-	resp, err := gemini.Get("gemini://example.com")
-	if err != nil {
-		// handle error
-	}
-	defer resp.Body.Close()
-	// ...
-
-For control over client behavior, create a Client:
-
-	client := &gemini.Client{}
-	resp, err := client.Get("gemini://example.com")
-	if err != nil {
-		// handle error
-	}
-	// ...
-
-Server is a Gemini server.
-
-	server := &gemini.Server{
-		ReadTimeout:    10 * time.Second,
-		WriteTimeout:   10 * time.Second,
-	}
-
-Servers should be configured with certificates:
-
-	err := server.Certificates.Load("/var/lib/gemini/certs")
-	if err != nil {
-		// handle error
-	}
-
-Servers can accept requests for multiple hosts and schemes:
-
-	server.RegisterFunc("example.com", func(w *gemini.ResponseWriter, r *gemini.Request) {
-		fmt.Fprint(w, "Welcome to example.com")
-	})
-	server.RegisterFunc("example.org", func(w *gemini.ResponseWriter, r *gemini.Request) {
-		fmt.Fprint(w, "Welcome to example.org")
-	})
-	server.RegisterFunc("http://example.net", func(w *gemini.ResponseWriter, r *gemini.Request) {
-		fmt.Fprint(w, "Proxied content from http://example.net")
-	})
-
-To start the server, call ListenAndServe:
-
-	err := server.ListenAndServe()
-	if err != nil {
-		// handle error
-	}
-*/
-package gemini

examples/auth.go

@@ -64,7 +64,7 @@ func main() {
 }
 
 func getSession(cert *x509.Certificate) (*session, bool) {
-	fingerprint := gemini.NewFingerprint(cert)
+	fingerprint := gemini.NewFingerprint(cert.Raw, cert.NotAfter)
 	session, ok := sessions[fingerprint.Hex]
 	return session, ok
 }
@@ -79,7 +79,8 @@ func login(w *gemini.ResponseWriter, r *gemini.Request) {
 		w.WriteHeader(gemini.StatusInput, "Username")
 		return
 	}
-	fingerprint := gemini.NewFingerprint(r.Certificate.Leaf)
+	cert := r.Certificate.Leaf
+	fingerprint := gemini.NewFingerprint(cert.Raw, cert.NotAfter)
 	sessions[fingerprint.Hex] = &session{
 		username: username,
 	}
@@ -116,7 +117,8 @@ func logout(w *gemini.ResponseWriter, r *gemini.Request) {
 		w.WriteStatus(gemini.StatusCertificateRequired)
 		return
 	}
-	fingerprint := gemini.NewFingerprint(r.Certificate.Leaf)
+	cert := r.Certificate.Leaf
+	fingerprint := gemini.NewFingerprint(cert.Raw, cert.NotAfter)
 	delete(sessions, fingerprint.Hex)
 	fmt.Fprintln(w, "Successfully logged out.")
 	fmt.Fprintln(w, "=> / Index")

examples/client.go

@@ -10,9 +10,11 @@ import (
 	"io/ioutil"
 	"log"
 	"os"
+	"path/filepath"
 	"time"
 
 	"git.sr.ht/~adnano/go-gemini"
+	"git.sr.ht/~adnano/go-xdg"
 )
 
 const trustPrompt = `The certificate offered by %s is of unknown trust. Its fingerprint is:
@@ -31,9 +33,9 @@ var (
 
 func init() {
 	client.Timeout = 30 * time.Second
-	client.KnownHosts.LoadDefault()
+	client.KnownHosts.Load(filepath.Join(xdg.DataHome(), "gemini", "known_hosts"))
 	client.TrustCertificate = func(hostname string, cert *x509.Certificate) gemini.Trust {
-		fingerprint := gemini.NewFingerprint(cert)
+		fingerprint := gemini.NewFingerprint(cert.Raw, cert.NotAfter)
 		fmt.Printf(trustPrompt, hostname, fingerprint.Hex)
 		scanner.Scan()
 		switch scanner.Text() {
@@ -80,9 +82,9 @@ func main() {
 		fmt.Println(err)
 		os.Exit(1)
 	}
-	defer resp.Body.Close()
 
 	if resp.Status.Class() == gemini.StatusClassSuccess {
+		defer resp.Body.Close()
 		body, err := ioutil.ReadAll(resp.Body)
 		if err != nil {
 			log.Fatal(err)

fs.go

@@ -33,7 +33,7 @@ func (fsh fsHandler) Respond(w *ResponseWriter, r *Request) {
 	// Detect mimetype
 	ext := path.Ext(p)
 	mimetype := mime.TypeByExtension(ext)
-	w.SetMimetype(mimetype)
+	w.SetMediaType(mimetype)
 	// Copy file to response writer
 	io.Copy(w, f)
 }
@@ -72,7 +72,7 @@ func ServeFile(w *ResponseWriter, fs FS, name string) {
 	// Detect mimetype
 	ext := path.Ext(name)
 	mimetype := mime.TypeByExtension(ext)
-	w.SetMimetype(mimetype)
+	w.SetMediaType(mimetype)
 	// Copy file to response writer
 	io.Copy(w, f)
 }

gemini.go

@@ -1,8 +1,56 @@
+/*
+Package gemini implements the Gemini protocol.
+
+Client is a Gemini client.
+
+	client := &gemini.Client{}
+	resp, err := client.Get("gemini://example.com")
+	if err != nil {
+		// handle error
+	}
+	if resp.Status.Class() == gemini.StatusClassSucess {
+		defer resp.Body.Close()
+		// ...
+	}
+	// ...
+
+Server is a Gemini server.
+
+	server := &gemini.Server{
+		ReadTimeout:    10 * time.Second,
+		WriteTimeout:   10 * time.Second,
+	}
+
+Servers should be configured with certificates:
+
+	err := server.Certificates.Load("/var/lib/gemini/certs")
+	if err != nil {
+		// handle error
+	}
+
+Servers can accept requests for multiple hosts and schemes:
+
+	server.RegisterFunc("example.com", func(w *gemini.ResponseWriter, r *gemini.Request) {
+		fmt.Fprint(w, "Welcome to example.com")
+	})
+	server.RegisterFunc("example.org", func(w *gemini.ResponseWriter, r *gemini.Request) {
+		fmt.Fprint(w, "Welcome to example.org")
+	})
+	server.RegisterFunc("http://example.net", func(w *gemini.ResponseWriter, r *gemini.Request) {
+		fmt.Fprint(w, "Proxied content from http://example.net")
+	})
+
+To start the server, call ListenAndServe:
+
+	err := server.ListenAndServe()
+	if err != nil {
+		// handle error
+	}
+*/
 package gemini
 
 import (
 	"errors"
-	"sync"
 )
 
 var crlf = []byte("\r\n")
@@ -13,26 +61,3 @@ var (
 	ErrInvalidResponse = errors.New("gemini: invalid response")
 	ErrBodyNotAllowed  = errors.New("gemini: response body not allowed")
 )
-
-// defaultClient is the default client. It is used by Get and Do.
-var defaultClient Client
-
-// Get performs a Gemini request for the given url.
-func Get(url string) (*Response, error) {
-	setupDefaultClientOnce()
-	return defaultClient.Get(url)
-}
-
-// Do performs a Gemini request and returns a Gemini response.
-func Do(req *Request) (*Response, error) {
-	setupDefaultClientOnce()
-	return defaultClient.Do(req)
-}
-
-var defaultClientOnce sync.Once
-
-func setupDefaultClientOnce() {
-	defaultClientOnce.Do(func() {
-		defaultClient.KnownHosts.LoadDefault()
-	})
-}

response.go

@@ -2,10 +2,8 @@ package gemini
 
 import (
 	"bufio"
-	"bytes"
 	"crypto/tls"
 	"io"
-	"io/ioutil"
 	"strconv"
 )
 
@@ -21,7 +19,6 @@ type Response struct {
 	Meta string
 
 	// Body contains the response body for successful responses.
-	// Body is guaranteed to be non-nil.
 	Body io.ReadCloser
 
 	// Request is the request that was sent to obtain this response.
@@ -86,8 +83,6 @@ func (resp *Response) read(rc io.ReadCloser) error {
 
 	if resp.Status.Class() == StatusClassSuccess {
 		resp.Body = newReadCloserBody(br, rc)
-	} else {
-		resp.Body = ioutil.NopCloser(bytes.NewReader([]byte{}))
 	}
 	return nil
 }

server.go

@@ -160,8 +160,9 @@ func (s *Server) getCertificateFor(hostname string) (*tls.Certificate, error) {
 		if s.CreateCertificate != nil {
 			cert, err := s.CreateCertificate(hostname)
 			if err == nil {
-				if err := s.Certificates.Add(hostname, cert); err != nil {
-					s.logf("gemini: Failed to add new certificate for %s: %s", hostname, err)
+				s.Certificates.Add(hostname, cert)
+				if err := s.Certificates.Write(hostname, cert); err != nil {
+					s.logf("gemini: Failed to write new certificate for %s: %s", hostname, err)
 				}
 			}
 			return &cert, err
@@ -262,7 +263,7 @@ type ResponseWriter struct {
 	b           *bufio.Writer
 	bodyAllowed bool
 	wroteHeader bool
-	mimetype    string
+	mediatype   string
 }
 
 func newResponseWriter(conn net.Conn) *ResponseWriter {
@@ -301,10 +302,10 @@ func (w *ResponseWriter) WriteStatus(status Status) {
 	w.WriteHeader(status, status.Message())
 }
 
-// SetMimetype sets the mimetype that will be written for a successful response.
+// SetMediaType sets the media type that will be written for a successful response.
 // If the mimetype is not set, it will default to "text/gemini".
-func (w *ResponseWriter) SetMimetype(mimetype string) {
-	w.mimetype = mimetype
+func (w *ResponseWriter) SetMediaType(mediatype string) {
+	w.mediatype = mediatype
 }
 
 // Write writes the response body.
@@ -315,11 +316,11 @@ func (w *ResponseWriter) SetMimetype(mimetype string) {
 // with StatusSuccess and the mimetype set in SetMimetype.
 func (w *ResponseWriter) Write(b []byte) (int, error) {
 	if !w.wroteHeader {
-		mimetype := w.mimetype
-		if mimetype == "" {
-			mimetype = "text/gemini"
+		mediatype := w.mediatype
+		if mediatype == "" {
+			mediatype = "text/gemini"
 		}
-		w.WriteHeader(StatusSuccess, mimetype)
+		w.WriteHeader(StatusSuccess, mediatype)
 	}
 	if !w.bodyAllowed {
 		return 0, ErrBodyNotAllowed

tofu.go

@@ -3,13 +3,12 @@ package gemini
 import (
 	"bufio"
 	"crypto/sha512"
-	"crypto/x509"
 	"fmt"
 	"io"
 	"os"
-	"path/filepath"
 	"strconv"
 	"strings"
+	"time"
 )
 
 // Trust represents the trustworthiness of a certificate.
@@ -25,31 +24,55 @@ const (
 // The zero value for KnownHosts is an empty list ready to use.
 type KnownHosts struct {
 	hosts map[string]Fingerprint
-	file  *os.File
+	out   io.Writer
 }
 
-// LoadDefault loads the known hosts from the default known hosts path, which is
-// $XDG_DATA_HOME/gemini/known_hosts.
-// It creates the path and any of its parent directories if they do not exist.
-// KnownHosts will append to the file whenever a certificate is added.
-func (k *KnownHosts) LoadDefault() error {
-	path, err := defaultKnownHostsPath()
-	if err != nil {
-		return err
+// SetOutput sets the output to which new known hosts will be written to.
+func (k *KnownHosts) SetOutput(w io.Writer) {
+	k.out = w
+}
+
+// Add adds a known host to the list of known hosts.
+func (k *KnownHosts) Add(hostname string, fingerprint Fingerprint) {
+	if k.hosts == nil {
+		k.hosts = map[string]Fingerprint{}
 	}
-	return k.Load(path)
+	k.hosts[hostname] = fingerprint
 }
 
-// Load loads the known hosts from the provided path.
-// It creates the path and any of its parent directories if they do not exist.
-// KnownHosts will append to the file whenever a certificate is added.
-func (k *KnownHosts) Load(path string) error {
-	if dir := filepath.Dir(path); dir != "." {
-		err := os.MkdirAll(dir, 0755)
-		if err != nil {
+// Lookup returns the fingerprint of the certificate corresponding to
+// the given hostname.
+func (k *KnownHosts) Lookup(hostname string) (Fingerprint, bool) {
+	c, ok := k.hosts[hostname]
+	return c, ok
+}
+
+// Write writes a known hosts entry to the configured output.
+func (k *KnownHosts) Write(hostname string, fingerprint Fingerprint) {
+	if k.out != nil {
+		k.writeKnownHost(k.out, hostname, fingerprint)
+	}
+}
+
+// WriteAll writes all of the known hosts to the provided io.Writer.
+func (k *KnownHosts) WriteAll(w io.Writer) error {
+	for h, c := range k.hosts {
+		if _, err := k.writeKnownHost(w, h, c); err != nil {
 			return err
 		}
 	}
+	return nil
+}
+
+// writeKnownHost writes a known host to the provided io.Writer.
+func (k *KnownHosts) writeKnownHost(w io.Writer, hostname string, f Fingerprint) (int, error) {
+	return fmt.Fprintf(w, "%s %s %s %d\n", hostname, f.Algorithm, f.Hex, f.Expires)
+}
+
+// Load loads the known hosts from the provided path.
+// It creates the file if it does not exist.
+// New known hosts will be appended to the file.
+func (k *KnownHosts) Load(path string) error {
 	f, err := os.OpenFile(path, os.O_CREATE|os.O_RDONLY, 0644)
 	if err != nil {
 		return err
@@ -61,43 +84,12 @@ func (k *KnownHosts) Load(path string) error {
 	if err != nil {
 		return err
 	}
-	k.file = f
+	k.out = f
 	return nil
 }
 
-// Add adds a certificate to the list of known hosts.
-// If KnownHosts was loaded from a file, Add will append to the file.
-func (k *KnownHosts) Add(hostname string, cert *x509.Certificate) {
-	k.add(hostname, cert, true)
-}
-
-// AddTemporary adds a certificate to the list of known hosts
-// without writing it to the known hosts file.
-func (k *KnownHosts) AddTemporary(hostname string, cert *x509.Certificate) {
-	k.add(hostname, cert, false)
-}
-
-func (k *KnownHosts) add(hostname string, cert *x509.Certificate, write bool) {
-	if k.hosts == nil {
-		k.hosts = map[string]Fingerprint{}
-	}
-	fingerprint := NewFingerprint(cert)
-	k.hosts[hostname] = fingerprint
-	// Append to the file
-	if write && k.file != nil {
-		appendKnownHost(k.file, hostname, fingerprint)
-	}
-}
-
-// Lookup returns the fingerprint of the certificate corresponding to
-// the given hostname.
-func (k *KnownHosts) Lookup(hostname string) (Fingerprint, bool) {
-	c, ok := k.hosts[hostname]
-	return c, ok
-}
-
 // Parse parses the provided reader and adds the parsed known hosts to the list.
-// Invalid lines are ignored.
+// Invalid entries are ignored.
 func (k *KnownHosts) Parse(r io.Reader) {
 	if k.hosts == nil {
 		k.hosts = map[string]Fingerprint{}
@@ -130,17 +122,6 @@ func (k *KnownHosts) Parse(r io.Reader) {
 	}
 }
 
-// Write writes the known hosts to the provided io.Writer.
-func (k *KnownHosts) Write(w io.Writer) {
-	for h, c := range k.hosts {
-		appendKnownHost(w, h, c)
-	}
-}
-
-func appendKnownHost(w io.Writer, hostname string, f Fingerprint) (int, error) {
-	return fmt.Fprintf(w, "%s %s %s %d\n", hostname, f.Algorithm, f.Hex, f.Expires)
-}
-
 // Fingerprint represents a fingerprint using a certain algorithm.
 type Fingerprint struct {
 	Algorithm string // fingerprint algorithm e.g. SHA-512
@@ -148,9 +129,9 @@ type Fingerprint struct {
 	Expires   int64  // unix time of the fingerprint expiration date
 }
 
-// NewFingerprint returns the SHA-512 fingerprint of the provided certificate.
-func NewFingerprint(cert *x509.Certificate) Fingerprint {
-	sum512 := sha512.Sum512(cert.Raw)
+// NewFingerprint returns the SHA-512 fingerprint of the provided raw data.
+func NewFingerprint(raw []byte, expires time.Time) Fingerprint {
+	sum512 := sha512.Sum512(raw)
 	var b strings.Builder
 	for i, f := range sum512 {
 		if i > 0 {
@@ -161,30 +142,6 @@ func NewFingerprint(cert *x509.Certificate) Fingerprint {
 	return Fingerprint{
 		Algorithm: "SHA-512",
 		Hex:       b.String(),
-		Expires:   cert.NotAfter.Unix(),
+		Expires:   expires.Unix(),
 	}
 }
-
-// defaultKnownHostsPath returns the default known_hosts path.
-// The default path is $XDG_DATA_HOME/gemini/known_hosts
-func defaultKnownHostsPath() (string, error) {
-	dataDir, err := userDataDir()
-	if err != nil {
-		return "", err
-	}
-	return filepath.Join(dataDir, "gemini", "known_hosts"), nil
-}
-
-// userDataDir returns the user data directory.
-func userDataDir() (string, error) {
-	dataDir, ok := os.LookupEnv("XDG_DATA_HOME")
-	if ok {
-		return dataDir, nil
-	}
-
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return "", err
-	}
-	return filepath.Join(home, ".local", "share"), nil
-}