hmacsig

README

hmacsig

HMAC Signature Validation Middleware (like GitHub Webhooks Uses)

Supports SHA-1 validation via hmacsig.Handler and SHA-256 validation via hmacsig.Handler256

GitHub now recommends SHA-256 over SHA-1 - read more:

https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/securing-your-webhooks

Example

package main

import (
	"log"
	"net/http"

	"github.com/donatj/hmacsig"
)

func main() {
	h := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("success"))
	})

	s := hmacsig.Handler256(h, "supersecret")

	err := http.ListenAndServe(":8080", s)
	if err != nil {
		log.Fatal(err)
	}
}

Documentation

Overview

Package hmacsig implements an HMAC Signature Validation HTTP Middleware for use with the likes of GitHub Webhooks.

Index

• Constants
• func DefaultMissingSignatureHandler(w http.ResponseWriter, r *http.Request)
• func DefaultVerifyFailedHandler(w http.ResponseWriter, r *http.Request)
• func Handler(h http.Handler, secret string, options ...Option) http.Handler
• func Handler256(h http.Handler, secret string, options ...Option) http.Handler
• func OptionDefaultsSHA256(mux *hmacSig)
• func SHA1Validator(body []byte, sig, secret string) bool
• func SHA256Validator(body []byte, sig, secret string) bool
• type Option
  • func OptionHeader(header string) Option
  • func OptionMissingSignatureHandler(handler http.Handler) Option
  • func OptionSignatureValidator(validator SignatureValidator) Option
  • func OptionVerifyFailedHandler(handler http.Handler) Option
• type SignatureValidator

Constants

const (
	// GithubSignatureHeader is the default header used by GitHub for their
	// SHA-1 WebHook signatures
	GithubSignatureHeader = "X-Hub-Signature"

	// GithubSignatureHeader256 is the default header used by GitHub for their
	// SHA-256 WebHook signatures
	GithubSignatureHeader256 = "X-Hub-Signature-256"

	// MsgMissingSignature is the message returned in the body when the
	// Signature was missing from the request
	MsgMissingSignature = "Missing required header for HMAC verification"

	// MsgFailedHMAC is the message returned in the body when the HMAC did not
	// Validate as Anticpated.
	MsgFailedHMAC = "HMAC verification failed"
)

Functions

func DefaultMissingSignatureHandler

func DefaultMissingSignatureHandler(w http.ResponseWriter, r *http.Request)

DefaultMissingSignatureHandler is the default response to a missing signature

func DefaultVerifyFailedHandler

func DefaultVerifyFailedHandler(w http.ResponseWriter, r *http.Request)

DefaultVerifyFailedHandler is the default response to HMAC verification failing

func Handler

func Handler(h http.Handler, secret string, options ...Option) http.Handler

Handler provides HMAC signature validating middleware.

see: https://developer.github.com/webhooks/securing/

If no options.Header is provided, GithubSignatureHeader will be used.

func Handler256

func Handler256(h http.Handler, secret string, options ...Option) http.Handler

Handler256 provides HMAC signature validating middleware defaulting to SHA256.

Handler256 is a convenience method which invokes Handler while including OptionDefaultsSHA256 as the first Option

func OptionDefaultsSHA256

func OptionDefaultsSHA256(mux *hmacSig)

OptionDefaultsSHA256 configures the HTTP Header and Validator used to the defaults used by GitHub for SHA256 validation

func SHA1Validator

func SHA1Validator(body []byte, sig, secret string) bool

SHA1Validator implements the interface SignatureValidator and SHA-1 HMAC validation

func SHA256Validator

func SHA256Validator(body []byte, sig, secret string) bool

SHA256Validator implements the interface SignatureValidator and SHA-256 HMAC validation

Types

type Option

type Option func(*hmacSig)

Option sets an option of the passed hmacSig

func OptionHeader

func OptionHeader(header string) Option

OptionHeader configures the HTTP Header to read for the signature

func OptionMissingSignatureHandler

func OptionMissingSignatureHandler(handler http.Handler) Option

OptionMissingSignatureHandler configures the http.Handler called on missing signature

func OptionSignatureValidator

func OptionSignatureValidator(validator SignatureValidator) Option

OptionSignatureValidator configures the HMAC SignatureValidator validated against

func OptionVerifyFailedHandler

func OptionVerifyFailedHandler(handler http.Handler) Option

OptionVerifyFailedHandler configures the http.Handler called on HMAC verification failure

type SignatureValidator

type SignatureValidator func(body []byte, sig, secret string) bool

SignatureValidator validates the body of a request against the requests signature and servers secret