Revert to using hexadecimal to encode fingerprints

cert.go

@@ -2,12 +2,14 @@ package gemini
 
 import (
 	"crypto"
+	"crypto/ecdsa"
 	"crypto/ed25519"
+	"crypto/elliptic"
 	"crypto/rand"
 	"crypto/tls"
 	"crypto/x509"
+	"crypto/x509/pkix"
 	"encoding/pem"
-	"log"
 	"math/big"
 	"net"
 	"os"
@@ -16,19 +18,22 @@ import (
 	"time"
 )
 
-// CertificateStore maps certificate scopes to certificates.
+// CertificateDir maps certificate scopes to certificates.
-// The zero value of CertificateStore is an empty store ready to use.
+type CertificateStore map[string]tls.Certificate
-type CertificateStore struct {
+
-	store map[string]tls.Certificate
+// CertificateDir represents a certificate store optionally loaded from a directory.
-	dir   bool
+// The zero value of CertificateDir is an empty store ready to use.
-	path  string
+type CertificateDir struct {
+	CertificateStore
+	dir  bool
+	path string
 }
 
 // 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) {
+func (c *CertificateDir) Add(scope string, cert tls.Certificate) {
-	if c.store == nil {
+	if c.CertificateStore == nil {
-		c.store = map[string]tls.Certificate{}
+		c.CertificateStore = CertificateStore{}
 	}
 	// Parse certificate if not already parsed
 	if cert.Leaf == nil {
@@ -37,29 +42,27 @@ func (c *CertificateStore) Add(scope string, cert tls.Certificate) {
 			cert.Leaf = parsed
 		}
 	}
+	c.CertificateStore[scope] = cert
+}
+
+// Write writes the provided certificate to the certificate directory.
+func (c *CertificateDir) Write(scope string, cert tls.Certificate) error {
 	if c.dir {
-		// Write certificates
+		// Escape slash character
-		log.Printf("gemini: Writing certificate for %s to %s", scope, c.path)
+		scope = strings.ReplaceAll(scope, "/", ":")
 		certPath := filepath.Join(c.path, scope+".crt")
 		keyPath := filepath.Join(c.path, scope+".key")
 		if err := WriteCertificate(cert, certPath, keyPath); err != nil {
-			log.Printf("gemini: Failed to write certificate for %s: %s", scope, err)
+			return err
 		}
 	}
-	c.store[scope] = cert
+	return nil
 }
 
 // Lookup returns the certificate for the given scope.
-func (c *CertificateStore) Lookup(scope string) (*tls.Certificate, error) {
+func (c *CertificateDir) Lookup(scope string) (tls.Certificate, bool) {
-	cert, ok := c.store[scope]
+	cert, ok := c.CertificateStore[scope]
-	if !ok {
+	return cert, ok
-		return nil, ErrCertificateNotFound
-	}
-	// Ensure that the certificate is not expired
-	if cert.Leaf != nil && cert.Leaf.NotAfter.Before(time.Now()) {
-		return &cert, ErrCertificateExpired
-	}
-	return &cert, nil
 }
 
 // Load loads certificates from the given path.
@@ -68,7 +71,7 @@ func (c *CertificateStore) Lookup(scope string) (*tls.Certificate, error) {
 // For example, the hostname "localhost" would have the corresponding files
 // localhost.crt (certificate) and localhost.key (private key).
 // New certificates will be written to this directory.
-func (c *CertificateStore) Load(path string) error {
+func (c *CertificateDir) Load(path string) error {
 	matches, err := filepath.Glob(filepath.Join(path, "*.crt"))
 	if err != nil {
 		return err
@@ -80,6 +83,8 @@ func (c *CertificateStore) Load(path string) error {
 			continue
 		}
 		scope := strings.TrimSuffix(filepath.Base(crtPath), ".crt")
+		// Unescape slash character
+		scope = strings.ReplaceAll(scope, ":", "/")
 		c.Add(scope, cert)
 	}
 	c.dir = true
@@ -87,11 +92,37 @@ func (c *CertificateStore) Load(path string) error {
 	return nil
 }
 
-// CertificateOptions configures how a certificate is created.
+// SetDir sets the directory that new certificates will be written to.
+func (c *CertificateDir) SetDir(path string) {
+	c.dir = true
+	c.path = path
+}
+
+// CertificateOptions configures the creation of a certificate.
 type CertificateOptions struct {
+	// Subject Alternate Name values.
+	// Should contain the IP addresses that the certificate is valid for.
 	IPAddresses []net.IP
-	DNSNames    []string
+
-	Duration    time.Duration
+	// Subject Alternate Name values.
+	// Should contain the DNS names that this certificate is valid for.
+	// E.g. example.com, *.example.com
+	DNSNames []string
+
+	// Subject specifies the certificate Subject.
+	//
+	// Subject.CommonName can contain the DNS name that this certificate
+	// is valid for. Server certificates should specify both a Subject
+	// and a Subject Alternate Name.
+	Subject pkix.Name
+
+	// Duration specifies the amount of time that the certificate is valid for.
+	Duration time.Duration
+
+	// Ed25519 specifies whether to generate an Ed25519 key pair.
+	// If false, an ECDSA key will be generated instead.
+	// Ed25519 is not as widely supported as ECDSA.
+	Ed25519 bool
 }
 
 // CreateCertificate creates a new TLS certificate.
@@ -109,15 +140,27 @@ func CreateCertificate(options CertificateOptions) (tls.Certificate, error) {
 
 // newX509KeyPair creates and returns a new certificate and private key.
 func newX509KeyPair(options CertificateOptions) (*x509.Certificate, crypto.PrivateKey, error) {
-	// Generate an ED25519 private key
+	var pub crypto.PublicKey
-	_, priv, err := ed25519.GenerateKey(rand.Reader)
+	var priv crypto.PrivateKey
-	if err != nil {
+	if options.Ed25519 {
-		return nil, nil, err
+		// Generate an Ed25519 private key
+		var err error
+		pub, priv, err = ed25519.GenerateKey(rand.Reader)
+		if err != nil {
+			return nil, nil, err
+		}
+	} else {
+		// Generate an ECDSA private key
+		private, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+		if err != nil {
+			return nil, nil, err
+		}
+		priv = private
+		pub = &private.PublicKey
 	}
-	public := priv.Public()
 
-	// ED25519 keys should have the DigitalSignature KeyUsage bits set
+	// ECDSA and Ed25519 keys should have the DigitalSignature KeyUsage bits
-	// in the x509.Certificate template
+	// set in the x509.Certificate template
 	keyUsage := x509.KeyUsageDigitalSignature
 
 	serialNumberLimit := new(big.Int).Lsh(big.NewInt(1), 128)
@@ -138,9 +181,10 @@ func newX509KeyPair(options CertificateOptions) (*x509.Certificate, crypto.Priva
 		BasicConstraintsValid: true,
 		IPAddresses:           options.IPAddresses,
 		DNSNames:              options.DNSNames,
+		Subject:               options.Subject,
 	}
 
-	crt, err := x509.CreateCertificate(rand.Reader, &template, &template, public, priv)
+	crt, err := x509.CreateCertificate(rand.Reader, &template, &template, pub, priv)
 	if err != nil {
 		return nil, nil, err
 	}

client.go

@@ -4,20 +4,24 @@ import (
 	"bufio"
 	"crypto/tls"
 	"crypto/x509"
+	"errors"
 	"net"
 	"net/url"
 	"path"
 	"strings"
+	"sync"
 	"time"
 )
 
 // Client is a Gemini client.
+//
+// Clients are safe for concurrent use by multiple goroutines.
 type Client struct {
 	// KnownHosts is a list of known hosts.
-	KnownHosts KnownHosts
+	KnownHosts KnownHostsFile
 
 	// Certificates stores client-side certificates.
-	Certificates CertificateStore
+	Certificates CertificateDir
 
 	// Timeout specifies a time limit for requests made by this
 	// Client. The timeout includes connection time and reading
@@ -39,15 +43,14 @@ type Client struct {
 	GetInput func(prompt string, sensitive bool) (input string, ok bool)
 
 	// CheckRedirect determines whether to follow a redirect.
-	// If CheckRedirect is nil, a default policy of no more than 5 consecutive
+	// If CheckRedirect is nil, redirects will not be followed.
-	// redirects will be enforced.
 	CheckRedirect func(req *Request, via []*Request) error
 
 	// CreateCertificate is called to generate a certificate upon
 	// 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.
@@ -59,6 +62,8 @@ type Client struct {
 	// If TrustCertificate returns TrustAlways, the certificate will also be
 	// written to the known hosts file.
 	TrustCertificate func(hostname string, cert *x509.Certificate) Trust
+
+	mu sync.Mutex
 }
 
 // Get performs a Gemini request for the given url.
@@ -72,10 +77,20 @@ func (c *Client) Get(url string) (*Response, error) {
 
 // Do performs a Gemini request and returns a Gemini response.
 func (c *Client) Do(req *Request) (*Response, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
 	return c.do(req, nil)
 }
 
 func (c *Client) do(req *Request, via []*Request) (*Response, error) {
+	// Extract hostname
+	colonPos := strings.LastIndex(req.Host, ":")
+	if colonPos == -1 {
+		colonPos = len(req.Host)
+	}
+	hostname := req.Host[:colonPos]
+
 	// Connect to the host
 	config := &tls.Config{
 		InsecureSkipVerify: true,
@@ -86,11 +101,13 @@ func (c *Client) do(req *Request, via []*Request) (*Response, error) {
 		VerifyConnection: func(cs tls.ConnectionState) error {
 			return c.verifyConnection(req, cs)
 		},
+		ServerName: hostname,
 	}
-	conn, err := tls.Dial("tcp", req.Host, config)
+	netConn, err := (&net.Dialer{}).DialContext(req.Context, "tcp", req.Host)
 	if err != nil {
 		return nil, err
 	}
+	conn := tls.Client(netConn, config)
 	// Set connection deadline
 	if d := c.Timeout; d != 0 {
 		conn.SetDeadline(time.Now().Add(d))
@@ -108,6 +125,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()
 
@@ -125,20 +143,22 @@ func (c *Client) do(req *Request, via []*Request) (*Response, error) {
 				return resp, err
 			}
 			c.Certificates.Add(hostname+path, cert)
+			c.Certificates.Write(hostname+path, cert)
+			req.Certificate = &cert
 			return c.do(req, via)
 		}
-		return resp, ErrCertificateRequired
+		return resp, nil
 
 	case resp.Status.Class() == StatusClassInput:
 		if c.GetInput != nil {
 			input, ok := c.GetInput(resp.Meta, resp.Status == StatusSensitiveInput)
 			if ok {
 				req.URL.ForceQuery = true
-				req.URL.RawQuery = url.QueryEscape(input)
+				req.URL.RawQuery = QueryEscape(input)
 				return c.do(req, via)
 			}
 		}
-		return resp, ErrInputRequired
+		return resp, nil
 
 	case resp.Status.Class() == StatusClassRedirect:
 		if via == nil {
@@ -151,23 +171,17 @@ func (c *Client) do(req *Request, via []*Request) (*Response, error) {
 			return resp, err
 		}
 		target = req.URL.ResolveReference(target)
-		redirect, err := NewRequestFromURL(target)
-		if err != nil {
-			return resp, err
-		}
 
+		redirect := NewRequestFromURL(target)
+		redirect.Context = req.Context
 		if c.CheckRedirect != nil {
 			if err := c.CheckRedirect(redirect, via); err != nil {
 				return resp, err
 			}
-		} else if len(via) > 5 {
+			return c.do(redirect, via)
-			// Default policy of no more than 5 redirects
-			return resp, ErrTooManyRedirects
 		}
-		return c.do(redirect, via)
 	}
 
-	resp.Request = req
 	return resp, nil
 }
 
@@ -180,13 +194,14 @@ func (c *Client) getClientCertificate(req *Request) (*tls.Certificate, error) {
 	// Search recursively for the certificate
 	scope := req.URL.Hostname() + strings.TrimSuffix(req.URL.Path, "/")
 	for {
-		cert, err := c.Certificates.Lookup(scope)
+		cert, ok := c.Certificates.Lookup(scope)
-		if err == nil {
+		if ok {
-			// Store the certificate
+			// Ensure that the certificate is not expired
-			req.Certificate = cert
+			if cert.Leaf != nil && !time.Now().After(cert.Leaf.NotAfter) {
-			return cert, err
+				// Store the certificate
-		}
+				req.Certificate = &cert
-		if err == ErrCertificateExpired {
+				return &cert, nil
+			}
 			break
 		}
 		scope = path.Dir(scope)
@@ -213,22 +228,30 @@ func (c *Client) verifyConnection(req *Request, cs tls.ConnectionState) error {
 	if c.InsecureSkipTrust {
 		return nil
 	}
+
 	// Check the known hosts
-	err := c.KnownHosts.Lookup(hostname, cert)
+	knownHost, ok := c.KnownHosts.Lookup(hostname)
-	switch err {
+	if !ok || !time.Now().Before(knownHost.Expires) {
-	case ErrCertificateExpired, ErrCertificateNotFound:
 		// See if the client trusts the certificate
 		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 ErrCertificateNotTrusted
+		return errors.New("gemini: certificate not trusted")
 	}
-	return err
+
+	fingerprint := NewFingerprint(cert.Raw, cert.NotAfter)
+	if knownHost.Hex == fingerprint.Hex {
+		return nil
+	}
+	return errors.New("gemini: fingerprint does not match")
 }

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

@@ -3,8 +3,10 @@
 package main
 
 import (
+	"crypto/sha512"
 	"crypto/tls"
 	"crypto/x509"
+	"crypto/x509/pkix"
 	"fmt"
 	"log"
 	"time"
@@ -12,35 +14,19 @@ import (
 	"git.sr.ht/~adnano/go-gemini"
 )
 
-type user struct {
+type User struct {
-	password string // TODO: use hashes
+	Name string
-	admin    bool
-}
-
-type session struct {
-	username   string
-	authorized bool // whether or not the password was supplied
 }
 
 var (
-	// Map of usernames to user data
+	// Map of certificate hashes to users
-	logins = map[string]user{
+	users = map[string]*User{}
-		"admin": {"p@ssw0rd", true}, // NOTE: These are bad passwords!
-		"user1": {"password1", false},
-		"user2": {"password2", false},
-	}
-
-	// Map of certificate fingerprints to sessions
-	sessions = map[string]*session{}
 )
 
 func main() {
 	var mux gemini.ServeMux
-	mux.HandleFunc("/", login)
+	mux.HandleFunc("/", profile)
-	mux.HandleFunc("/password", loginPassword)
+	mux.HandleFunc("/username", changeUsername)
-	mux.HandleFunc("/profile", profile)
-	mux.HandleFunc("/admin", admin)
-	mux.HandleFunc("/logout", logout)
 
 	var server gemini.Server
 	if err := server.Certificates.Load("/var/lib/gemini/certs"); err != nil {
@@ -48,6 +34,9 @@ func main() {
 	}
 	server.CreateCertificate = func(hostname string) (tls.Certificate, error) {
 		return gemini.CreateCertificate(gemini.CertificateOptions{
+			Subject: pkix.Name{
+				CommonName: hostname,
+			},
 			DNSNames: []string{hostname},
 			Duration: time.Hour,
 		})
@@ -59,62 +48,9 @@ func main() {
 	}
 }
 
-func getSession(cert *x509.Certificate) (*session, bool) {
+func fingerprint(cert *x509.Certificate) string {
-	fingerprint := gemini.Fingerprint(cert)
+	b := sha512.Sum512(cert.Raw)
-	session, ok := sessions[fingerprint]
+	return string(b[:])
-	return session, ok
-}
-
-func login(w *gemini.ResponseWriter, r *gemini.Request) {
-	if r.Certificate == nil {
-		w.WriteStatus(gemini.StatusCertificateRequired)
-		return
-	}
-	username, ok := gemini.Input(r)
-	if !ok {
-		w.WriteHeader(gemini.StatusInput, "Username")
-		return
-	}
-	fingerprint := gemini.Fingerprint(r.Certificate.Leaf)
-	sessions[fingerprint] = &session{
-		username: username,
-	}
-	w.WriteHeader(gemini.StatusRedirect, "/password")
-}
-
-func loginPassword(w *gemini.ResponseWriter, r *gemini.Request) {
-	if r.Certificate == nil {
-		w.WriteStatus(gemini.StatusCertificateRequired)
-		return
-	}
-	session, ok := getSession(r.Certificate.Leaf)
-	if !ok {
-		w.WriteStatus(gemini.StatusCertificateNotAuthorized)
-		return
-	}
-
-	password, ok := gemini.Input(r)
-	if !ok {
-		w.WriteHeader(gemini.StatusSensitiveInput, "Password")
-		return
-	}
-	expected := logins[session.username].password
-	if password == expected {
-		session.authorized = true
-		w.WriteHeader(gemini.StatusRedirect, "/profile")
-	} else {
-		w.WriteHeader(gemini.StatusSensitiveInput, "Wrong password. Try again")
-	}
-}
-
-func logout(w *gemini.ResponseWriter, r *gemini.Request) {
-	if r.Certificate == nil {
-		w.WriteStatus(gemini.StatusCertificateRequired)
-		return
-	}
-	fingerprint := gemini.Fingerprint(r.Certificate.Leaf)
-	delete(sessions, fingerprint)
-	fmt.Fprintln(w, "Successfully logged out.")
 }
 
 func profile(w *gemini.ResponseWriter, r *gemini.Request) {
@@ -122,31 +58,27 @@ func profile(w *gemini.ResponseWriter, r *gemini.Request) {
 		w.WriteStatus(gemini.StatusCertificateRequired)
 		return
 	}
-	session, ok := getSession(r.Certificate.Leaf)
+	fingerprint := fingerprint(r.Certificate.Leaf)
+	user, ok := users[fingerprint]
 	if !ok {
-		w.WriteStatus(gemini.StatusCertificateNotAuthorized)
+		user = &User{}
-		return
+		users[fingerprint] = user
 	}
-	user := logins[session.username]
+	fmt.Fprintln(w, "Username:", user.Name)
-	fmt.Fprintln(w, "Username:", session.username)
+	fmt.Fprintln(w, "=> /username Change username")
-	fmt.Fprintln(w, "Admin:", user.admin)
-	fmt.Fprintln(w, "=> /logout Logout")
 }
 
-func admin(w *gemini.ResponseWriter, r *gemini.Request) {
+func changeUsername(w *gemini.ResponseWriter, r *gemini.Request) {
 	if r.Certificate == nil {
 		w.WriteStatus(gemini.StatusCertificateRequired)
 		return
 	}
-	session, ok := getSession(r.Certificate.Leaf)
+
+	username, ok := gemini.Input(r)
 	if !ok {
-		w.WriteStatus(gemini.StatusCertificateNotAuthorized)
+		w.WriteHeader(gemini.StatusInput, "Username")
 		return
 	}
-	user := logins[session.username]
+	users[fingerprint(r.Certificate.Leaf)].Name = username
-	if !user.admin {
+	w.WriteHeader(gemini.StatusRedirect, "/")
-		w.WriteStatus(gemini.StatusCertificateNotAuthorized)
-		return
-	}
-	fmt.Fprintln(w, "Welcome to the admin portal.")
 }

examples/cert.go

@@ -3,6 +3,7 @@
 package main
 
 import (
+	"crypto/x509/pkix"
 	"fmt"
 	"log"
 	"os"
@@ -22,6 +23,9 @@ func main() {
 		log.Fatal(err)
 	}
 	options := gemini.CertificateOptions{
+		Subject: pkix.Name{
+			CommonName: host,
+		},
 		DNSNames: []string{host},
 		Duration: duration,
 	}

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,10 @@ 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 {
-		fmt.Printf(trustPrompt, hostname, gemini.Fingerprint(cert))
+		fingerprint := gemini.NewFingerprint(cert.Raw, cert.NotAfter)
+		fmt.Printf(trustPrompt, hostname, fingerprint.Hex)
 		scanner.Scan()
 		switch scanner.Text() {
 		case "t":
@@ -79,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)

examples/server.go

@@ -4,6 +4,7 @@ package main
 
 import (
 	"crypto/tls"
+	"crypto/x509/pkix"
 	"log"
 	"time"
 
@@ -19,8 +20,11 @@ func main() {
 	}
 	server.CreateCertificate = func(hostname string) (tls.Certificate, error) {
 		return gemini.CreateCertificate(gemini.CertificateOptions{
+			Subject: pkix.Name{
+				CommonName: hostname,
+			},
 			DNSNames: []string{hostname},
-			Duration: time.Minute, // for testing purposes
+			Duration: 365 * 24 * time.Hour,
 		})
 	}
 

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)
 }
@@ -96,9 +96,9 @@ func openFile(p string) (File, error) {
 			if stat.Mode().IsRegular() {
 				return f, nil
 			}
-			return nil, ErrNotAFile
+			return nil, os.ErrNotExist
 		} else if !stat.Mode().IsRegular() {
-			return nil, ErrNotAFile
+			return nil, os.ErrNotExist
 		}
 	}
 	return f, nil

gemini.go

@@ -1,46 +1,63 @@
+/*
+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")
 
 // Errors.
 var (
-	ErrInvalidURL            = errors.New("gemini: invalid URL")
+	ErrInvalidURL      = errors.New("gemini: invalid URL")
-	ErrInvalidResponse       = errors.New("gemini: invalid response")
+	ErrInvalidResponse = errors.New("gemini: invalid response")
-	ErrCertificateExpired    = errors.New("gemini: certificate expired")
+	ErrBodyNotAllowed  = errors.New("gemini: response body not allowed")
-	ErrCertificateNotFound   = errors.New("gemini: certificate not found")
-	ErrCertificateNotTrusted = errors.New("gemini: certificate not trusted")
-	ErrCertificateRequired   = errors.New("gemini: certificate required")
-	ErrNotAFile              = errors.New("gemini: not a file")
-	ErrNotAGeminiURL         = errors.New("gemini: not a Gemini URL")
-	ErrBodyNotAllowed        = errors.New("gemini: response status code does not allow for body")
-	ErrTooManyRedirects      = errors.New("gemini: too many redirects")
-	ErrInputRequired         = errors.New("gemini: input required")
 )
-
-// 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()
-	})
-}

query.go

@@ -0,0 +1,17 @@
+package gemini
+
+import (
+	"net/url"
+	"strings"
+)
+
+// QueryEscape properly escapes a string for use in a Gemini URL query.
+// It is like url.PathEscape except that it also replaces plus signs with their percent-encoded counterpart.
+func QueryEscape(query string) string {
+	return strings.ReplaceAll(url.PathEscape(query), "+", "%2B")
+}
+
+// QueryUnescape is identical to url.PathUnescape.
+func QueryUnescape(query string) (string, error) {
+	return url.PathUnescape(query)
+}

request.go

@@ -2,6 +2,7 @@ package gemini
 
 import (
 	"bufio"
+	"context"
 	"crypto/tls"
 	"net"
 	"net/url"
@@ -33,6 +34,10 @@ type Request struct {
 	// connection on which the request was received.
 	// This field is ignored by the client.
 	TLS tls.ConnectionState
+
+	// Context specifies the context to use for client requests.
+	// Context must not be nil.
+	Context context.Context
 }
 
 // NewRequest returns a new request. The host is inferred from the URL.
@@ -41,23 +46,24 @@ func NewRequest(rawurl string) (*Request, error) {
 	if err != nil {
 		return nil, err
 	}
-	return NewRequestFromURL(u)
+	return NewRequestFromURL(u), nil
 }
 
 // NewRequestFromURL returns a new request for the given URL.
 // The host is inferred from the URL.
-func NewRequestFromURL(url *url.URL) (*Request, error) {
+//
-	if url.Scheme != "" && url.Scheme != "gemini" {
+// Callers should be careful that the URL query is properly escaped.
-		return nil, ErrNotAGeminiURL
+// See the documentation for QueryEscape for more information.
-	}
+func NewRequestFromURL(url *url.URL) *Request {
 	host := url.Host
 	if url.Port() == "" {
 		host += ":1965"
 	}
 	return &Request{
-		URL:  url,
+		URL:     url,
-		Host: host,
+		Host:    host,
-	}, nil
+		Context: context.Background(),
+	}
 }
 
 // write writes the Gemini request to the provided buffered writer.

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

@@ -3,6 +3,7 @@ package gemini
 import (
 	"bufio"
 	"crypto/tls"
+	"errors"
 	"log"
 	"net"
 	"net/url"
@@ -25,12 +26,17 @@ type Server struct {
 	WriteTimeout time.Duration
 
 	// Certificates contains the certificates used by the server.
-	Certificates CertificateStore
+	Certificates CertificateDir
 
 	// CreateCertificate, if not nil, will be called to create a new certificate
 	// if the current one is expired or missing.
 	CreateCertificate func(hostname string) (tls.Certificate, error)
 
+	// ErrorLog specifies an optional logger for errors accepting connections
+	// and file system errors.
+	// If nil, logging is done via the log package's standard logger.
+	ErrorLog *log.Logger
+
 	// registered responders
 	responders map[responderKey]Responder
 	hosts      map[string]bool
@@ -117,7 +123,7 @@ func (s *Server) Serve(l net.Listener) error {
 				if max := 1 * time.Second; tempDelay > max {
 					tempDelay = max
 				}
-				log.Printf("gemini: Accept error: %v; retrying in %v", err, tempDelay)
+				s.logf("gemini: Accept error: %v; retrying in %v", err, tempDelay)
 				time.Sleep(tempDelay)
 				continue
 			}
@@ -145,22 +151,25 @@ func (s *Server) getCertificate(h *tls.ClientHelloInfo) (*tls.Certificate, error
 
 func (s *Server) getCertificateFor(hostname string) (*tls.Certificate, error) {
 	if _, ok := s.hosts[hostname]; !ok {
-		return nil, ErrCertificateNotFound
+		return nil, errors.New("hostname not registered")
 	}
-	cert, err := s.Certificates.Lookup(hostname)
 
-	switch err {
+	// Generate a new certificate if it is missing or expired
-	case ErrCertificateNotFound, ErrCertificateExpired:
+	cert, ok := s.Certificates.Lookup(hostname)
+	if !ok || cert.Leaf != nil && cert.Leaf.NotAfter.Before(time.Now()) {
 		if s.CreateCertificate != nil {
 			cert, err := s.CreateCertificate(hostname)
 			if err == nil {
 				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
 		}
+		return nil, errors.New("no certificate")
 	}
-
+	return &cert, nil
-	return cert, err
 }
 
 // respond responds to a connection.
@@ -194,11 +203,6 @@ func (s *Server) respond(conn net.Conn) {
 		// Note that we return an error status if User is specified in the URL
 		w.WriteStatus(StatusBadRequest)
 	} else {
-		// If no scheme is specified, assume a default scheme of gemini://
-		if url.Scheme == "" {
-			url.Scheme = "gemini"
-		}
-
 		// Store information about the TLS connection
 		connState := conn.(*tls.Conn).ConnectionState()
 		var cert *tls.Certificate
@@ -241,12 +245,20 @@ func (s *Server) responder(r *Request) Responder {
 	return nil
 }
 
+func (s *Server) logf(format string, args ...interface{}) {
+	if s.ErrorLog != nil {
+		s.ErrorLog.Printf(format, args...)
+	} else {
+		log.Printf(format, args...)
+	}
+}
+
 // ResponseWriter is used by a Gemini handler to construct a Gemini response.
 type ResponseWriter struct {
 	b           *bufio.Writer
 	bodyAllowed bool
 	wroteHeader bool
-	mimetype    string
+	mediatype   string
 }
 
 func newResponseWriter(conn net.Conn) *ResponseWriter {
@@ -285,10 +297,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) {
+func (w *ResponseWriter) SetMediaType(mediatype string) {
-	w.mimetype = mimetype
+	w.mediatype = mediatype
 }
 
 // Write writes the response body.
@@ -299,11 +311,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
+		mediatype := w.mediatype
-		if mimetype == "" {
+		if mediatype == "" {
-			mimetype = "text/gemini"
+			mediatype = "text/gemini"
 		}
-		w.WriteHeader(StatusSuccess, mimetype)
+		w.WriteHeader(StatusSuccess, mediatype)
 	}
 	if !w.bodyAllowed {
 		return 0, ErrBodyNotAllowed

tofu.go

@@ -3,11 +3,9 @@ package gemini
 import (
 	"bufio"
 	"crypto/sha512"
-	"crypto/x509"
 	"fmt"
 	"io"
 	"os"
-	"path/filepath"
 	"strconv"
 	"strings"
 	"time"
@@ -22,35 +20,62 @@ const (
 	TrustAlways              // The certificate is trusted always.
 )
 
-// KnownHosts represents a list of known hosts.
+// KnownHosts maps hosts to fingerprints.
-// The zero value for KnownHosts is an empty list ready to use.
+type KnownHosts map[string]Fingerprint
-type KnownHosts struct {
+
-	hosts map[string]certInfo
+// KnownHostsFile represents a list of known hosts optionally loaded from a file.
-	file  *os.File
+// The zero value for KnownHostsFile represents an empty list ready to use.
+type KnownHostsFile struct {
+	KnownHosts
+	out io.Writer
 }
 
-// LoadDefault loads the known hosts from the default known hosts path, which is
+// SetOutput sets the output to which new known hosts will be written to.
-// $XDG_DATA_HOME/gemini/known_hosts.
+func (k *KnownHostsFile) SetOutput(w io.Writer) {
-// It creates the path and any of its parent directories if they do not exist.
+	k.out = w
-// KnownHosts will append to the file whenever a certificate is added.
+}
-func (k *KnownHosts) LoadDefault() error {
+
-	path, err := defaultKnownHostsPath()
+// Add adds a known host to the list of known hosts.
-	if err != nil {
+func (k *KnownHostsFile) Add(hostname string, fingerprint Fingerprint) {
-		return err
+	if k.KnownHosts == nil {
+		k.KnownHosts = KnownHosts{}
 	}
-	return k.Load(path)
+	k.KnownHosts[hostname] = fingerprint
 }
 
-// Load loads the known hosts from the provided path.
+// Lookup returns the fingerprint of the certificate corresponding to
-// It creates the path and any of its parent directories if they do not exist.
+// the given hostname.
-// KnownHosts will append to the file whenever a certificate is added.
+func (k *KnownHostsFile) Lookup(hostname string) (Fingerprint, bool) {
-func (k *KnownHosts) Load(path string) error {
+	c, ok := k.KnownHosts[hostname]
-	if dir := filepath.Dir(path); dir != "." {
+	return c, ok
-		err := os.MkdirAll(dir, 0755)
+}
-		if err != nil {
+
+// Write writes a known hosts entry to the configured output.
+func (k *KnownHostsFile) 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 *KnownHostsFile) WriteAll(w io.Writer) error {
+	for h, c := range k.KnownHosts {
+		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 *KnownHostsFile) 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.Unix())
+}
+
+// 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 *KnownHostsFile) Load(path string) error {
 	f, err := os.OpenFile(path, os.O_CREATE|os.O_RDONLY, 0644)
 	if err != nil {
 		return err
@@ -62,65 +87,15 @@ 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]certInfo{}
-	}
-	info := certInfo{
-		Algorithm:   "SHA-512",
-		Fingerprint: Fingerprint(cert),
-		Expires:     cert.NotAfter.Unix(),
-	}
-	k.hosts[hostname] = info
-	// Append to the file
-	if write && k.file != nil {
-		appendKnownHost(k.file, hostname, info)
-	}
-}
-
-// Lookup looks for the provided certificate in the list of known hosts.
-// If the hostname is not in the list, Lookup returns ErrCertificateNotFound.
-// If the fingerprint doesn't match, Lookup returns ErrCertificateNotTrusted.
-// Otherwise, Lookup returns nil.
-func (k *KnownHosts) Lookup(hostname string, cert *x509.Certificate) error {
-	now := time.Now().Unix()
-	fingerprint := Fingerprint(cert)
-	if c, ok := k.hosts[hostname]; ok {
-		if c.Expires <= now {
-			// Certificate is expired
-			return ErrCertificateExpired
-		}
-		if c.Fingerprint != fingerprint {
-			// Fingerprint does not match
-			return ErrCertificateNotTrusted
-		}
-		// Certificate is found
-		return nil
-	}
-	return ErrCertificateNotFound
-}
-
 // 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) {
+func (k *KnownHostsFile) Parse(r io.Reader) {
-	if k.hosts == nil {
+	if k.KnownHosts == nil {
-		k.hosts = map[string]certInfo{}
+		k.KnownHosts = map[string]Fingerprint{}
 	}
 	scanner := bufio.NewScanner(r)
 	for scanner.Scan() {
@@ -135,40 +110,32 @@ func (k *KnownHosts) Parse(r io.Reader) {
 		if algorithm != "SHA-512" {
 			continue
 		}
-		fingerprint := parts[2]
+		hex := parts[2]
-		expires, err := strconv.ParseInt(parts[3], 10, 0)
+
+		unix, err := strconv.ParseInt(parts[3], 10, 0)
 		if err != nil {
 			continue
 		}
+		expires := time.Unix(unix, 0)
 
-		k.hosts[hostname] = certInfo{
+		k.KnownHosts[hostname] = Fingerprint{
-			Algorithm:   algorithm,
+			Algorithm: algorithm,
-			Fingerprint: fingerprint,
+			Hex:       hex,
-			Expires:     expires,
+			Expires:   expires,
 		}
 	}
 }
 
-// Write writes the known hosts to the provided io.Writer.
+// Fingerprint represents a fingerprint using a certain algorithm.
-func (k *KnownHosts) Write(w io.Writer) {
+type Fingerprint struct {
-	for h, c := range k.hosts {
+	Algorithm string    // fingerprint algorithm e.g. SHA-512
-		appendKnownHost(w, h, c)
+	Hex       string    // fingerprint in hexadecimal, with ':' between each octet
-	}
+	Expires   time.Time // unix time of the fingerprint expiration date
 }
 
-type certInfo struct {
+// NewFingerprint returns the SHA-512 fingerprint of the provided raw data.
-	Algorithm   string // fingerprint algorithm e.g. SHA-512
+func NewFingerprint(raw []byte, expires time.Time) Fingerprint {
-	Fingerprint string // fingerprint in hexadecimal, with ':' between each octet
+	sum512 := sha512.Sum512(raw)
-	Expires     int64  // unix time of certificate notAfter date
-}
-
-func appendKnownHost(w io.Writer, hostname string, c certInfo) (int, error) {
-	return fmt.Fprintf(w, "%s %s %s %d\n", hostname, c.Algorithm, c.Fingerprint, c.Expires)
-}
-
-// Fingerprint returns the SHA-512 fingerprint of the provided certificate.
-func Fingerprint(cert *x509.Certificate) string {
-	sum512 := sha512.Sum512(cert.Raw)
 	var b strings.Builder
 	for i, f := range sum512 {
 		if i > 0 {
@@ -176,29 +143,9 @@ func Fingerprint(cert *x509.Certificate) string {
 		}
 		fmt.Fprintf(&b, "%02X", f)
 	}
-	return b.String()
+	return Fingerprint{
-}
+		Algorithm: "SHA-512",
-
+		Hex:       b.String(),
-// defaultKnownHostsPath returns the default known_hosts path.
+		Expires:   expires,
-// 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
 }