httpsig

README

httpsig

Documentation

Overview

Package httpsig implements HTTP Signatures according to draft-cavage-http-signatures-08 https://datatracker.ietf.org/doc/draft-cavage-http-signatures/

Index

• Constants
• func Middleware(t HeaderType, getter KeyGetter, next http.Handler) http.Handler
• func ValidKeyID(keyID string) bool
• type Algorithm
  • func ParseAlgorithm(val string) Algorithm
  • func (a Algorithm) Sign(key interface{}, data []byte) ([]byte, error)
  • func (a Algorithm) String() string
  • func (a Algorithm) Transport(keyID string, key interface{}, opts ...TransportOption) http.RoundTripper
  • func (a Algorithm) Verify(key interface{}, data, sig []byte) error
• type Header
  • func (h *Header) SignatureString(req *http.Request, headers ...string) []byte
  • func (h Header) String() string
  • func (h Header) Verify(getter KeyGetter, req *http.Request) error
• type HeaderType
  • func (t HeaderType) Parse(req *http.Request) (*Header, error)
  • func (t HeaderType) Set(a Algorithm, keyID string, key interface{}, req *http.Request, ...) error
  • func (t HeaderType) String() string
  • func (t HeaderType) Verify(getter KeyGetter, req *http.Request) error
• type KeyGetter
• type KeyGetterFunc
  • func (f KeyGetterFunc) GetKey(keyID string) (key interface{}, err error)
• type TransportOption
  • func WithAuthorizationHeader() TransportOption
  • func WithDigestAlgorithm(val digest.Algorithm) TransportOption
  • func WithTracer(tracer opentracing.Tracer) TransportOption

Constants

const (
	DefaultDigestAlgo = digest.SHA256
	DefaultHeaderType = SignatureHeader
)

These are the default values for TransportOptions

Functions

func Middleware

func Middleware(t HeaderType, getter KeyGetter, next http.Handler) http.Handler

Middleware is an HTTP middleware that will call next only if the request's HTTP signature is valid

func ValidKeyID

func ValidKeyID(keyID string) bool

ValidKeyID returns true if the keyID doesn't contain any quote (`"`) or comma (`,`) characters

Types

type Algorithm

type Algorithm int

Algorithm represents the type of HTTP signature to use

const (
	Unknown Algorithm = iota
	RSASHA1
	RSASHA256
	HMACSHA256
	ECDSASHA256
)

These are the available Algorithms to use

func ParseAlgorithm

func ParseAlgorithm(val string) Algorithm

ParseAlgorithm parses a string into an Algorithm

func (Algorithm) Sign

func (a Algorithm) Sign(key interface{}, data []byte) ([]byte, error)

Sign signs the data with the provided key. key is expected to be an rsa.PrivateKey, []byte for HMAC or ecdsa.PrivateKey

func (Algorithm) String

func (a Algorithm) String() string

func (Algorithm) Transport

func (a Algorithm) Transport(keyID string, key interface{}, opts ...TransportOption) http.RoundTripper

Transport returns an http.RoundTripper that sets HTTP signatures on outgoing requests

func (Algorithm) Verify

func (a Algorithm) Verify(key interface{}, data, sig []byte) error

Verify verifies that data was properly signed by key. sig is the already signed data. key is expected to be an rsa.PublicKey, []byte for HMAC or ecdsa.PublicKey. PrivateKeys may also be used.

type Header

type Header struct {
	KeyID     string
	Algorithm Algorithm
	Headers   []string
	Signature []byte
}

A Header represents the parts of the HTTP signature header

func (*Header) SignatureString

func (h *Header) SignatureString(req *http.Request, headers ...string) []byte

SignatureString returns the string that should be signed for the request. It also populates Header.Headers. If headers has values, only those will be used to produce the string. Otherwise, all headers except Host, User-Agent, Content-Length, Transfer-Encoding and Trailer will be used.

func (Header) String

func (h Header) String() string

func (Header) Verify

func (h Header) Verify(getter KeyGetter, req *http.Request) error

Verify ensures that the Header is valid

type HeaderType

type HeaderType string

HeaderType dictates which HTTP header to use and the format of the value for generating and verifying HTTP signatures

const (
	SignatureHeader     HeaderType = "Signature"
	AuthorizationHeader HeaderType = "Authorization"
)

These are the available HeaderTypes to use

func (HeaderType) Parse

func (t HeaderType) Parse(req *http.Request) (*Header, error)

Parse returns a Header populated with the fields extracted from the HTTP signature

func (HeaderType) Set

func (t HeaderType) Set(a Algorithm, keyID string, key interface{}, req *http.Request, digestAlgo digest.Algorithm) error

Set sets the appropriate HTTP header to make an HTTP signature on the request

func (HeaderType) String

func (t HeaderType) String() string

func (HeaderType) Verify

func (t HeaderType) Verify(getter KeyGetter, req *http.Request) error

Verify ensures that the HTTP signature on the request is valid

type KeyGetter

type KeyGetter interface {
	GetKey(keyID string) (key interface{}, err error)
}

A KeyGetter gets a key for HTTP signature verification based on the keyID

type KeyGetterFunc

type KeyGetterFunc func(keyID string) (key interface{}, err error)

The KeyGetterFunc type is an adapter to allow the use of ordinary functions as KeyGetters. If f is a function with the appropriate signature, KeyGetterFunc(f) is a KeyGetter that calls f.

func (KeyGetterFunc) GetKey

func (f KeyGetterFunc) GetKey(keyID string) (key interface{}, err error)

GetKey returns f(keyID)

type TransportOption

type TransportOption func(*transport)

A TransportOption is an option that can be used with Algorithm.Transport

func WithAuthorizationHeader

func WithAuthorizationHeader() TransportOption

WithAuthorizationHeader causes the Transport to use the Authorization header for HTTP signatures instead of the Signature header

func WithDigestAlgorithm

func WithDigestAlgorithm(val digest.Algorithm) TransportOption

WithDigestAlgorithm causes the Transport to use the digest algorithm val when generating HTTP Digest headers

func WithTracer

func WithTracer(tracer opentracing.Tracer) TransportOption

WithTracer sets the tracer to be used by the Transport