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.

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.