easyhttps

README

EasyHTTPS

EasyHTTPS is a Go library that simplifies the process of setting up HTTPS servers with automatic certificate management using Let's Encrypt or any other ACME-compatible certificate authority. Whether you're working on small personal projects or large-scale applications, EasyHTTPS makes it easier than ever to enable HTTPS with minimal setup and advanced customization.

---

Features ✨

• Automatic HTTPS: Instantly obtain and renew SSL/TLS certificates automatically.
• Minimal Setup: Start a secure server with as little as three lines of code.
• Customisable: Fine-grained control over TLS settings and certificate management.
• ACME Compatibility: Works with any ACME-compatible certificate authority, including Let's Encrypt.
• Custom Certificate Storage: Easily implement your own certificate storage backend.
• Flexible Configuration: Customise everything, from TLS settings to ACME client configurations.

---

Table of Contents 📚

• Installation
• Quick Start
• Advanced Usage
• Configuration Options
• Custom Certificate Storage
• Integrating with Other ACME CAs
• TLS Configuration
• License

---

Installation ⚙️

To install EasyHTTPS, simply run the following command:

go get github.com/Dyst0rti0n/easyhttps

Or, if you're using Go modules:

go get github.com/Dyst0rti0n/easyhttps@latest

---

Quick Start 🚀

Here's how to set up a basic HTTPS server with minimal code:

package main

import (
    "net/http"

    "github.com/Dyst0rti0n/easyhttps"
)

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, Secure World!"))
    })

    // Start the server with automatic HTTPS
    err := easyhttps.ListenAndServe(":80", nil)
    if err != nil {
        panic(err)
    }
}

This will:

• Serve your application on port 443 (HTTPS).
• Automatically obtain and renew certificates from Let's Encrypt.
• Redirect all HTTP traffic on port 80 to HTTPS.

Note: Ensure your domain's DNS records point to your server's IP address and that ports 80 and 443 are open.

---

Advanced Usage ⚡

For more control over the server configuration, you can use various options:

package main

import (
    "crypto/tls"
    "log"
    "net/http"

    "github.com/Dyst0rti0n/easyhttps"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, Advanced Secure World!"))
    })

    // Custom TLS configuration
    tlsCustomiser := func(tlsConfig *tls.Config) {
        tlsConfig.MinVersion = tls.VersionTLS13
        // Add additional TLS settings as needed
    }

    // Start the server with advanced options
    err := easyhttps.ListenAndServe(":80", mux,
        easyhttps.WithDomains("example.com", "www.example.com"),
        easyhttps.WithEmail("admin@example.com"),
        easyhttps.WithTLSConfigCustomiser(tlsCustomiser),
        easyhttps.WithRedirectHTTP(false),
        easyhttps.WithHTTPSAddr(":8443"),
    )
    if err != nil {
        log.Fatal(err)
    }
}

---

Configuration Options ⚙️

EasyHTTPS provides various options to customise its behavior:

• WithDomains(domains ...string): Specify domain names for certificate issuance.
• WithEmail(email string): Set the email address for ACME registration.
• WithTLSConfig(tlsConfig *tls.Config): Provide a custom TLS configuration.
• WithTLSConfigCustomiser(customiser func(*tls.Config)): Customise TLS settings with a function.
• WithHTTPHandler(handler http.Handler): Set a custom handler for HTTP challenges.
• WithHTTPSAddr(addr string): Change the address for the HTTPS server (default ":443").
• WithRedirectHTTP(redirect bool): Enable or disable HTTP to HTTPS redirection (default true).
• WithReadTimeout(timeout time.Duration): Set the server's read timeout.
• WithWriteTimeout(timeout time.Duration): Set the server's write timeout.
• WithACMEClient(client *acme.Client): Use a custom ACME client for different CAs.
• WithCertCache(cache autocert.Cache): Provide a custom certificate storage backend.
• WithHostPolicy(policy autocert.HostPolicy): Set a custom host policy for domain validation.

---

Custom Certificate Storage 🗄️

You can implement your own certificate storage backend by satisfying the autocert.Cache interface. This allows you to store certificates in a database, cloud storage, or any other storage solution.

Example:

type CustomCache struct {
    // Implement your storage mechanism
}

func (cc *CustomCache) Get(ctx context.Context, name string) ([]byte, error) {
    // Retrieve data from storage
}

func (cc *CustomCache) Put(ctx context.Context, name string, data []byte) error {
    // Store data in storage
}

func (cc *CustomCache) Delete(ctx context.Context, name string) error {
    // Delete data from storage
}

// Usage
customCache := &CustomCache{}
err := easyhttps.ListenAndServe(":80", mux,
    easyhttps.WithCertCache(customCache),
)

---

Integrating with Other ACME CAs 🔗

EasyHTTPS allows you to integrate with any ACME-compatible certificate authority by providing a custom ACME client:

acmeClient := easyhttps.NewACMEClient("https://acme-staging-v02.api.letsencrypt.org/directory", nil)

err := easyhttps.ListenAndServe(":80", mux,
    easyhttps.WithACMEClient(acmeClient),
)

Replace the directory URL with the ACME server of your chosen certificate authority.

---

TLS Configuration 🔐

For fine-grained control over TLS settings, use WithTLSConfigCustomiser:

tlsCustomiser := func(tlsConfig *tls.Config) {
    tlsConfig.MinVersion = tls.VersionTLS13
    tlsConfig.CurvePreferences = []tls.CurveID{tls.X25519, tls.CurveP256}
    tlsConfig.CipherSuites = []uint16{
        tls.TLS_AES_128_GCM_SHA256,
        tls.TLS_AES_256_GCM_SHA384,
    }
}

err := easyhttps.ListenAndServe(":80", mux,
    easyhttps.WithTLSConfigCustomizer(tlsCustomiser),
)

---

License 📝

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

• func ListenAndServe(addr string, handler http.Handler, options ...Option) error
• func NewACMEClient(directoryURL string, accountKey crypto.Signer) *acme.Client
• type Config
• type CustomCache
• type FileCache
  • func (fc FileCache) Delete(ctx context.Context, name string) error
  • func (fc FileCache) Get(ctx context.Context, name string) ([]byte, error)
  • func (fc FileCache) Put(ctx context.Context, name string, data []byte) error
• type MemoryCache
  • func NewMemoryCache() *MemoryCache
  • func (mc *MemoryCache) Delete(ctx context.Context, name string) error
  • func (mc *MemoryCache) Get(ctx context.Context, name string) ([]byte, error)
  • func (mc *MemoryCache) Put(ctx context.Context, name string, data []byte) error
• type Option
  • func WithACMEClient(client *acme.Client) Option
  • func WithCertCache(cache autocert.Cache) Option
  • func WithDomains(domains ...string) Option
  • func WithEmail(email string) Option
  • func WithHTTPHandler(handler http.Handler) Option
  • func WithHTTPSAddr(addr string) Option
  • func WithHostPolicy(policy autocert.HostPolicy) Option
  • func WithReadTimeout(timeout time.Duration) Option
  • func WithRedirectHTTP(redirect bool) Option
  • func WithTLSConfig(tlsConfig *tls.Config) Option
  • func WithTLSConfigCustomiser(customiser func(*tls.Config)) Option
  • func WithWriteTimeout(timeout time.Duration) Option

Functions

func ListenAndServe

func ListenAndServe(addr string, handler http.Handler, options ...Option) error

Starts HTTPS server with auto cert management.

func NewACMEClient

func NewACMEClient(directoryURL string, accountKey crypto.Signer) *acme.Client

Creates a custom ACME client.

Types

type Config

type Config struct {
	Domains             []string
	Email               string
	TLSConfig           *tls.Config
	TLSConfigCustomiser func(*tls.Config)
	HTTPHandler         http.Handler
	HTTPSAddr           string
	RedirectHTTP        bool
	ReadTimeout         time.Duration
	WriteTimeout        time.Duration
	ACMEClient          *acme.Client
	CertCache           autocert.Cache
	HostPolicy          autocert.HostPolicy
}

Config options

type CustomCache

type CustomCache interface {
	autocert.Cache
}

An interface that extends autocert.Cache

type FileCache

type FileCache struct {
	Dir string
}

Implements CustomCache using the filesystem

func (FileCache) Delete

func (fc FileCache) Delete(ctx context.Context, name string) error

func (FileCache) Get

func (fc FileCache) Get(ctx context.Context, name string) ([]byte, error)

func (FileCache) Put

func (fc FileCache) Put(ctx context.Context, name string, data []byte) error

type MemoryCache

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

Implements CustomCache in memory (not persistent)

func NewMemoryCache

func NewMemoryCache() *MemoryCache

func (*MemoryCache) Delete

func (mc *MemoryCache) Delete(ctx context.Context, name string) error

func (*MemoryCache) Get

func (mc *MemoryCache) Get(ctx context.Context, name string) ([]byte, error)

func (*MemoryCache) Put

func (mc *MemoryCache) Put(ctx context.Context, name string, data []byte) error

type Option

type Option func(*Config)

func WithACMEClient

func WithACMEClient(client *acme.Client) Option

Allows setting a custom ACME client.

func WithCertCache

func WithCertCache(cache autocert.Cache) Option

Allows setting a custom certificate cache.

func WithDomains

func WithDomains(domains ...string) Option

Sets the domains for which to obtain certificates.

func WithEmail

func WithEmail(email string) Option

Sets the email for Let's Encrypt account registration.

func WithHTTPHandler

func WithHTTPHandler(handler http.Handler) Option

sets a custom HTTP handler for HTTP challenges.

func WithHTTPSAddr

func WithHTTPSAddr(addr string) Option

Sets the address for the HTTPS server.

func WithHostPolicy

func WithHostPolicy(policy autocert.HostPolicy) Option

Allows setting a custom host policy.

func WithReadTimeout

func WithReadTimeout(timeout time.Duration) Option

Sets the server's read timeout.

func WithRedirectHTTP

func WithRedirectHTTP(redirect bool) Option

Sets whether to redirect HTTP to HTTPS.

func WithTLSConfig

func WithTLSConfig(tlsConfig *tls.Config) Option

Allows custom TLS configuration.

func WithTLSConfigCustomiser

func WithTLSConfigCustomiser(customiser func(*tls.Config)) Option

Allows fine-grained TLS settings.

func WithWriteTimeout

func WithWriteTimeout(timeout time.Duration) Option

Sets the server's write timeout.