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, true)

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, true)
// OR Sign using the 'Authorization' header
httpsignatures.DefaultSha256Signer.AuthRequest("KeyId", "Key", r, true)

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, true) {
		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, isHex bool) 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, toHex bool) error
  • func (s Signer) SignRequest(id, key string, r *http.Request, toHex bool) error

Examples

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

Constants

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

Variables

var (
	AlgorithmHmacSha256 = &Algorithm{"hmac-sha256", sha256.New}
	AlgorithmRsaSha256  = &Algorithm{"rsa-sha256", sha256.New}
	AlgorithmHmacSha1   = &Algorithm{"hmac-sha1", sha1.New}
	AlgorithmRsaSha1    = &Algorithm{"rsa-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, isHex bool) 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, toHex bool) error

AuthRequest adds a http signature to the Authorization: HTTP Header

func (Signer) SignRequest

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

SignRequest adds a http signature to the Signature: HTTP Header