httpsignatures

README

httpsignatures-go

Golang library for the http-signatures spec.

See https://godoc.org/github.com/99designs/httpsignatures-go for documentation and examples

Documentation

Overview

httpsignatures is a golang implementation of the http-signatures spec found at https://tools.ietf.org/html/draft-cavage-http-signatures

Example (CustomSigning)

signer := httpsignatures.NewSigner(
	httpsignatures.AlgorithmHmacSha256,
	httpsignatures.RequestTarget, "date", "content-length",
)

r, _ := http.NewRequest("GET", "http://example.com/some-api", nil)

signer.SignRequest("KeyId", "Key", r)

http.DefaultClient.Do(r)

Example (Signing)

r, _ := http.NewRequest("GET", "http://example.com/some-api", nil)

// Sign using the 'Signature' header
httpsignatures.DefaultSha256Signer.SignRequest("KeyId", "Key", r)
// OR Sign using the 'Authorization' header
httpsignatures.DefaultSha256Signer.AuthRequest("KeyId", "Key", r)

http.DefaultClient.Do(r)

Example (Verification)

_ = func(w http.ResponseWriter, r *http.Request) {
	sig, err := httpsignatures.FromRequest(r)
	if err != nil {
		// Probably a malformed header
		http.Error(w, "Bad Request", http.StatusBadRequest)
		panic(err)
	}

	// if you have headers that must be signed check
	// that they are in sig.Headers

	var key string // = lookup using sig.KeyID
	if !sig.IsValid(key, r) {
		http.Error(w, "Forbidden", http.StatusForbidden)
		return
	}

	// request was signed correctly.
}

Index

• Constants
• Variables
• type Algorithm
• type HeaderList
  • func (h HeaderList) String() string
• type Signature
  • func FromRequest(r *http.Request) (*Signature, error)
  • func FromString(in string) (*Signature, error)
  • func (s Signature) IsValid(key string, r *http.Request) bool
  • func (s Signature) String() string
• type Signer
  • func NewSigner(algorithm *Algorithm, headers ...string) *Signer
  • func (s Signer) AuthRequest(id, key string, r *http.Request) error
  • func (s Signer) SignRequest(id, key string, r *http.Request) error

Examples

• Package (CustomSigning)
• Package (Signing)
• Package (Verification)

Constants

const (
	RequestTarget = "(request-target)"
)

Variables

var (
	AlgorithmHmacSha256 = &Algorithm{"hmac-sha256", sha256.New}
	AlgorithmHmacSha1   = &Algorithm{"hmac-sha1", sha1.New}

	ErrorUnknownAlgorithm = errors.New("Unknown Algorithm")
)

var (
	// DefaultSha1Signer will sign requests with the url and date using the SHA1 algorithm.
	// Users are encouraged to create their own signer with the headers they require.
	DefaultSha1Signer = NewSigner(AlgorithmHmacSha1, RequestTarget, "date")

	// DefaultSha256Signer will sign requests with the url and date using the SHA256 algorithm.
	// Users are encouraged to create their own signer with the headers they require.
	DefaultSha256Signer = NewSigner(AlgorithmHmacSha256, RequestTarget, "date")
)

var (
	ErrorNoSignatureHeader = errors.New("No Signature header found in request")
)

Types

type Algorithm

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

type HeaderList

type HeaderList []string

func (HeaderList) String

func (h HeaderList) String() string

type Signature

type Signature struct {
	KeyID     string
	Algorithm *Algorithm
	Headers   HeaderList
	Signature string
}

Signature is the hashed key + headers, either from a request or a signer

func FromRequest

func FromRequest(r *http.Request) (*Signature, error)

FromRequest creates a new Signature from the Request both Signature and Authorization http headers are supported.

func FromString

func FromString(in string) (*Signature, error)

FromString creates a new Signature from its encoded form, eg `keyId="a",algorithm="b",headers="c",signature="d"`

func (Signature) IsValid

func (s Signature) IsValid(key string, r *http.Request) bool

IsValid validates this signature for the given key

func (Signature) String

func (s Signature) String() string

String returns the encoded form of the Signature

type Signer

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

Signer is used to create a signature for a given request.

func NewSigner

func NewSigner(algorithm *Algorithm, headers ...string) *Signer

func (Signer) AuthRequest

func (s Signer) AuthRequest(id, key string, r *http.Request) error

AuthRequest adds a http signature to the Authorization: HTTP Header

func (Signer) SignRequest

func (s Signer) SignRequest(id, key string, r *http.Request) error

SignRequest adds a http signature to the Signature: HTTP Header