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

Index

• func AddHandlers(verbose bool, s *SimpleServer, r *mux.Router, Handlers ...SimpleHandler)
• func AddMiddlewares(r *mux.Router, middlewares ...MiddlewareHandler)
• func DefaultLoggingMiddleware(next http.Handler) http.Handler
• func NewDefaultRouter() *mux.Router
• func NewRouter(s *SimpleServer, Handlers []SimpleHandler, Middlewares ...MiddlewareHandler) *mux.Router
• func NewTLSConfig(TLS *TLSBundle) (*tls.Config, error)
• type KeyPair
• type MiddlewareHandler
• type SimpleClient
  • func NewClientHTTP() (*SimpleClient, error)
  • func NewClientHTTPS(TLS *TLSBundle) (*SimpleClient, error)
  • func (C *SimpleClient) Connect(URL *url.URL, Headers map[string]string) error
  • func (C *SimpleClient) Delete(URL *url.URL, Headers map[string]string) error
  • func (C *SimpleClient) Get(URL *url.URL, Headers map[string]string) (*http.Response, error)
  • func (C *SimpleClient) Head(URL *url.URL, Headers map[string]string) (http.Header, error)
  • func (C *SimpleClient) Options(URL *url.URL, Headers map[string]string) error
  • func (C *SimpleClient) Patch(URL *url.URL, Headers map[string]string) error
  • func (C *SimpleClient) Post(URL *url.URL, contents io.Reader, Headers map[string]string) (*http.Response, error)
  • func (C *SimpleClient) Put(URL *url.URL, contents io.Reader, Headers map[string]string) error
  • func (C *SimpleClient) Trace(URL *url.URL, Headers map[string]string) error
• type SimpleHandler
• type SimpleServer
  • func NewServerHTTP(Addr string) (*SimpleServer, error)
  • func NewServerHTTPS(TLS *TLSBundle, Addr string) (*SimpleServer, error)
  • func (S *SimpleServer) EnableAboutHandler(r *mux.Router)
  • func (S *SimpleServer) ListenAndServe() error
  • func (S *SimpleServer) RegisterRouter(r http.Handler)
  • func (S *SimpleServer) Shutdown()
• type TLSBundle

Functions

func AddHandlers

func AddHandlers(verbose bool, s *SimpleServer, r *mux.Router, Handlers ...SimpleHandler)

AddHandlers will add the given handlers to the router, with the verbose flag determining if a log message should be generated for each added route.

func AddMiddlewares

func AddMiddlewares(r *mux.Router, middlewares ...MiddlewareHandler)

AddMiddlewares is a convenience wrapper for the mux.Router "Use" function

func DefaultLoggingMiddleware

func DefaultLoggingMiddleware(next http.Handler) http.Handler

DefaultLoggingMiddleware provides a simple logging middleware, to view incoming connections as they arrive.

func NewDefaultRouter

func NewDefaultRouter() *mux.Router

NewDefaultRouter will initialize a new HTTP Router, based on the gorilla/mux implementation.

func NewRouter

func NewRouter(s *SimpleServer, Handlers []SimpleHandler, Middlewares ...MiddlewareHandler) *mux.Router

NewRouter will build a new complex router, with the given routes, and middlewares. More can be added later, if needed.

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 Client or Server 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 MiddlewareHandler

type MiddlewareHandler func(http.Handler) http.Handler

MiddlewareHandler represents the general format for a Middleware handler.

type SimpleClient

type SimpleClient struct {
	// contains filtered or unexported fields
}

SimpleClient is a renaming of the Standard http.Client for this package, to allow the ease-of-use extensions provided here.

func NewClientHTTP

func NewClientHTTP() (*SimpleClient, error)

NewClientHTTP will create a new SimpleClient, with no TLS settings enabled. This will accept raw HTTP only.

func NewClientHTTPS

func NewClientHTTPS(TLS *TLSBundle) (*SimpleClient, error)

NewClientHTTPS will create a new TLS-Enabled SimpleClient. This will

func (*SimpleClient) Connect

func (C *SimpleClient) Connect(URL *url.URL, Headers map[string]string) error

Connect will (Not yet implemented)

func (*SimpleClient) Delete

func (C *SimpleClient) Delete(URL *url.URL, Headers map[string]string) error

Delete represents the abstraction of the HTTP Delete request, accounting for creating the request, setting headers, and asserting a valid status code. Closing the response body is the responsibility of this function.

func (*SimpleClient) Get

func (C *SimpleClient) Get(URL *url.URL, Headers map[string]string) (*http.Response, error)

Get represents the abstraction of the HTTP Get request, accounting for creating the request, setting headers, and asserting a valid status code. Closing the response body is the responsibility of the caller.

func (*SimpleClient) Head

func (C *SimpleClient) Head(URL *url.URL, Headers map[string]string) (http.Header, error)

Head represents the abstraction of the HTTP Head request, accounting for creating the request, setting headers, and asserting a valid status code. Closing the response body is the responsibility of this function, as Head only returns the headers.

func (*SimpleClient) Options

func (C *SimpleClient) Options(URL *url.URL, Headers map[string]string) error

Options will (Not yet implemented)

func (*SimpleClient) Patch

func (C *SimpleClient) Patch(URL *url.URL, Headers map[string]string) error

Patch will (Not yet implemented)

func (*SimpleClient) Post

func (C *SimpleClient) Post(URL *url.URL, contents io.Reader, Headers map[string]string) (*http.Response, error)

Post represents the abstraction of the HTTP Post request, accounting for creating the request, setting headers, and asserting a valid status code. Closing the response body is the responsibility of the caller.

func (*SimpleClient) Put

func (C *SimpleClient) Put(URL *url.URL, contents io.Reader, Headers map[string]string) error

Put represents the abstraction of the HTTP Put request, accounting for creating the request, setting headers, and asserting a valid status code. Closing the response body is the responsibility of this function.

func (*SimpleClient) Trace

func (C *SimpleClient) Trace(URL *url.URL, Headers map[string]string) error

Trace will (Not yet implemented)

type SimpleHandler

type SimpleHandler struct {
	Handler http.HandlerFunc
	Path    string
	Methods []string
}

SimpleHandler represents a simplification to the standard http handlerFuncs, allowing simpler registration and logging with Routers.

type SimpleServer

type SimpleServer struct {
	// contains filtered or unexported fields
}

SimpleServer represents an extension to the standard http.Server

func NewServerHTTP

func NewServerHTTP(Addr string) (*SimpleServer, error)

NewServerHTTP will create a new http.Server, with no TLS settings enabled. This will accept raw HTTP only.

func NewServerHTTPS

func NewServerHTTPS(TLS *TLSBundle, Addr string) (*SimpleServer, error)

NewServerHTTPS will create a new TLS-Enabled http.Server. This will

func (*SimpleServer) EnableAboutHandler

func (S *SimpleServer) EnableAboutHandler(r *mux.Router)

EnableAboutHandler will enable and set up the "about" handler, to display the available routes. This must be the last route registered in order for the full set of routes to be displayed.

func (*SimpleServer) ListenAndServe

func (S *SimpleServer) ListenAndServe() error

ListenAndServe will start the SimpleServer, serving HTTPS if enabled, or HTTP if not

func (*SimpleServer) RegisterRouter

func (S *SimpleServer) RegisterRouter(r http.Handler)

RegisterRouter will register the given Handler (typically an *http.ServeMux or *mux.Router) as the http Handler for the server.

func (*SimpleServer) Shutdown

func (S *SimpleServer) Shutdown()

Shutdown will safely shut down the SimpleServer, returning any errors

type TLSBundle

type TLSBundle struct {
	AuthorityCertificates []string
	KeyPairs              []KeyPair
	Auth                  tls.ClientAuthType
	Enabled               bool
}

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