httpsignature

Documentation

Overview

Package httpsignature contains methods for signing and verifing HTTP requests per https://www.ietf.org/id/draft-cavage-http-signatures-08.txt

Index

• Constants
• type Algorithm
  • func (a *Algorithm) MarshalText() (text []byte, err error)
  • func (a Algorithm) String() string
  • func (a *Algorithm) UnmarshalText(text []byte) (err error)
• type Ed25519PubKey
  • func GenerateEd25519Key(rand io.Reader) (Ed25519PubKey, ed25519.PrivateKey, error)
  • func (pk Ed25519PubKey) String() string
  • func (pk Ed25519PubKey) Verify(message, sig []byte, opts crypto.SignerOpts) (bool, error)
• type HMACKey
  • func (key HMACKey) Sign(rand io.Reader, message []byte, opts crypto.SignerOpts) (signature []byte, err error)
  • func (key HMACKey) String() string
  • func (key HMACKey) Verify(message, sig []byte, opts crypto.SignerOpts) (bool, error)
• type Keystore
• type ParameterizedKeystoreVerifier
  • func (pkv *ParameterizedKeystoreVerifier) VerifyRequest(req *http.Request) (context.Context, string, error)
• type ParameterizedSignator
  • func (p *ParameterizedSignator) SignRequest(req *http.Request) error
• type Signator
• type SignatureParams
  • func SignatureParamsFromRequest(req *http.Request) (*SignatureParams, error)
  • func (sp *SignatureParams) BuildSigningString(req *http.Request) (out []byte, err error)
  • func (sp *SignatureParams) IsMalformed() bool
  • func (sp *SignatureParams) Sign(signator Signator, opts crypto.SignerOpts, req *http.Request) error
  • func (sp *SignatureParams) Verify(verifier Verifier, opts crypto.SignerOpts, req *http.Request) (bool, error)
• type StaticKeystore
  • func (sk *StaticKeystore) LookupVerifier(ctx context.Context, keyID string) (context.Context, *Verifier, error)
• type Verifier

Constants

const (
	// HostHeader is the host header
	HostHeader = "host"
	// DigestHeader is the header where a digest of the body will be stored
	DigestHeader = "digest"
	// RequestTargetHeader is a pseudo header consisting of the HTTP method and request uri
	RequestTargetHeader = "(request-target)"
)

Types

type Algorithm

type Algorithm int

Algorithm is an enum-like representing an algorithm that can be used for http signatures

const (

	// ED25519 EdDSA - deprecated, all algorithm strings should be replaced with HS2019
	ED25519 Algorithm
	// HS2019 is a catch-all value for all algorithms
	HS2019
)

func (*Algorithm) MarshalText

func (a *Algorithm) MarshalText() (text []byte, err error)

MarshalText marshalls the algorithm into text.

func (Algorithm) String

func (a Algorithm) String() string

func (*Algorithm) UnmarshalText

func (a *Algorithm) UnmarshalText(text []byte) (err error)

UnmarshalText unmarshalls the algorithm from text.

type Ed25519PubKey

type Ed25519PubKey ed25519.PublicKey

Ed25519PubKey a wrapper type around ed25519.PublicKey to fulfill interface Verifier

func GenerateEd25519Key

func GenerateEd25519Key(rand io.Reader) (Ed25519PubKey, ed25519.PrivateKey, error)

GenerateEd25519Key generate an ed25519 keypair and return it

func (Ed25519PubKey) String

func (pk Ed25519PubKey) String() string

func (Ed25519PubKey) Verify

func (pk Ed25519PubKey) Verify(message, sig []byte, opts crypto.SignerOpts) (bool, error)

Verify the signature sig for message using the ed25519 public key pk Returns true if the signature is valid, false if not and error if the key provided is not valid

type HMACKey

type HMACKey string

HMACKey is a symmetric key that can be used for HMAC-SHA512 request signing and verification

func (HMACKey) Sign

func (key HMACKey) Sign(rand io.Reader, message []byte, opts crypto.SignerOpts) (signature []byte, err error)

Sign the message using the hmac key

func (HMACKey) String

func (key HMACKey) String() string

func (HMACKey) Verify

func (key HMACKey) Verify(message, sig []byte, opts crypto.SignerOpts) (bool, error)

Verify the signature sig for message using the hmac key

type Keystore

type Keystore interface {
	// LookupVerifier based on the keyID
	LookupVerifier(ctx context.Context, keyID string) (context.Context, *Verifier, error)
}

Keystore provides a way to lookup a public key based on the keyID a request was signed with

type ParameterizedKeystoreVerifier

type ParameterizedKeystoreVerifier struct {
	SignatureParams
	Keystore Keystore
	Opts     crypto.SignerOpts
}

ParameterizedKeystoreVerifier is an interface for cryptographic signature verification

func (*ParameterizedKeystoreVerifier) VerifyRequest

func (pkv *ParameterizedKeystoreVerifier) VerifyRequest(req *http.Request) (context.Context, string, error)

VerifyRequest using keystore to lookup verifier with options opts returns the key id if the signature is valid and an error otherwise

type ParameterizedSignator

type ParameterizedSignator struct {
	SignatureParams
	Signator Signator
	Opts     crypto.SignerOpts
}

ParameterizedSignator contains the parameters / options needed to create signatures and a signator

func (*ParameterizedSignator) SignRequest

func (p *ParameterizedSignator) SignRequest(req *http.Request) error

SignRequest using signator and options opts in the parameterized signator

type Signator

type Signator interface {
	Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) (signature []byte, err error)
}

Signator is an interface for cryptographic signature creation NOTE that this is a subset of the crypto.Signer interface

type SignatureParams

type SignatureParams struct {
	Algorithm       Algorithm
	KeyID           string
	DigestAlgorithm *crypto.Hash // optional
	Headers         []string     // optional
}

SignatureParams contains parameters needed to create and verify signatures

func SignatureParamsFromRequest

func SignatureParamsFromRequest(req *http.Request) (*SignatureParams, error)

SignatureParamsFromRequest extracts the signature parameters from a signed http request

func (*SignatureParams) BuildSigningString

func (sp *SignatureParams) BuildSigningString(req *http.Request) (out []byte, err error)

BuildSigningString builds the signing string according to the SignatureParams s and HTTP request req TODO Add support for digest generation based on req.Body?

func (*SignatureParams) IsMalformed

func (sp *SignatureParams) IsMalformed() bool

IsMalformed returns true if the signature parameters are invalid

func (*SignatureParams) Sign

func (sp *SignatureParams) Sign(signator Signator, opts crypto.SignerOpts, req *http.Request) error

Sign the included HTTP request req using signator and options opts

func (*SignatureParams) Verify

func (sp *SignatureParams) Verify(verifier Verifier, opts crypto.SignerOpts, req *http.Request) (bool, error)

Verify the HTTP signature s over HTTP request req using verifier with options opts

type StaticKeystore

type StaticKeystore struct {
	Verifier
}

StaticKeystore is a keystore that always returns a static verifier independent of keyID

func (*StaticKeystore) LookupVerifier

func (sk *StaticKeystore) LookupVerifier(ctx context.Context, keyID string) (context.Context, *Verifier, error)

LookupVerifier by returning a static verifier

type Verifier

type Verifier interface {
	Verify(message, sig []byte, opts crypto.SignerOpts) (bool, error)
	String() string
}

Verifier is an interface for cryptographic signature verification