easytls

README

easy-tls

A set of packages for quickly and easily developing TLS-enabled Web Servers and Clients.

Documentation

Overview

Package easytls is intended to provide a simplification and abstraction layer for quickly creating HTTP(S) enabled web applications. This module intends to provide a simple API to illustrate the parameters needed for proper TLS security, as well as providing simpler methods for performing standard HTTP(S) operations

This package implements two fundamental types, SimpleServer and SimpleClient. These represent a slightly higher level of abstraction for HTTP(S) Servers and Clients. Each of these is a thin wrapper over the standard library http.Client and http.Server, but with common elements abstracted away.

The full TLS settings of this module are defined within the tls-bundle.go file, and the TLSBundle struct. This is intended to allow for commonly required TLS settings to be implemented without explicitly constructing the tls.Config. For example, the full set of accepted Root and Client CA's to trust can be specified by adding the filepaths to the certificates into the AuthorityCertificate slice. These will be read, loaded, and added to a tls.CertPool in the correct format for use with the tls.Config. Likewise with the KeyPair substructs for the Client certificates. The goal of this struct is to allow for common TLS settings such as an application with a dedicated client/server TLS pair to be defined by the paths to the necessary TLS resources, rather than the implementer needing to remember and tick every box along the way.

The SimpleServer struct is heavily based on the gorilla/mux router, as most of the middleware/handler registration is based on that, although work is being done to allow this to work with the default http.ServeMux. A SimpleServer is built from a TLSBundle and an Address to listen on, and can be completed by adding a configured Router. This Router is by default initialized with NotFound and MethodNotAccepted handlers, returning the corresponding error codes. Further routes can be added, typically formatted as SimpleHandlers. This is basic grouping of the HTTP Handler to call, the methods it accepts, and the path to match on. The goal of this is to provide a way to programatically register routes, so that routes can be defined succinctly.

A SimpleServer can be built into a Reverse Proxy. By supplying the Server with a SimpleClient to use to forward the traffic, and the function which determines the remote host to forward to based on the incoming request, a full Reverse Proxy can be constructed. Depending on the TLS and HTTP protocol levels of each component, this Reverse Proxy can easily be used as an HTTP<->HTTPS converter, an HTTP/1.x <-> HTTP/2.0 converter, or any other standard reverse proxy functionality.

The SimpleClient struct is effectively a wrapper of the http.Client, with a more easily accessible flag to determine whether or not TLS is enabled. This also provides explicit functions for each of the Standard HTTP methods, along with a common API for accessing them. Building requests is completely abstracted away, with the limitation of not allowing multipart requests.

Index

• func NewTLSConfig(TLS *TLSBundle) (*tls.Config, error)
• type KeyPair
• type TLSBundle

Functions

func NewTLSConfig

func NewTLSConfig(TLS *TLSBundle) (*tls.Config, error)

NewTLSConfig will convert the TLSBundle, containing the filenames of the relevant certificates and Authorization policy, into a workable tls.Config object, ready to be used by either a SimpleClient or SimpleServer application.

Types

type KeyPair

type KeyPair struct {
	Certificate string
	Key         string
}

KeyPair represents the filenames to a pair of matching TLS Key/Certificate files.

type TLSBundle

type TLSBundle struct {
	AuthorityCertificates []string
	KeyPair               KeyPair
	Auth                  tls.ClientAuthType
	Enabled               bool `json:"-"`
}

TLSBundle represents the set of TLS information required by Dune to assert 2-way TLS verification.