Documentation
¶
Overview ¶
Package hmacsig is the one definition of a webhook HMAC signature: which bytes are signed, how the signature is written into its header, and how a header is read back into the signatures it carries (#1996).
The platform verifies these signatures on its inbound webhook sources (internal/webhook/whauth) and writes them on an outbound connection whose auth_mode is hmac (internal/upstreamauth). Both build on this package, so a connection and a source configured with the same values agree by construction rather than by two implementations being kept in step.
It knows nothing about requests, sources or connections: a caller hands it a Scheme, the secret, the delivery id and timestamp it read or chose, and the body.
Index ¶
- Constants
- Variables
- func ValidAlgorithm(a string) bool
- func ValidEncoding(e string) bool
- func ValidFormat(f string) bool
- func ValidSigned(v string) bool
- type Preset
- type Scheme
- func (s Scheme) Header(secret, id, timestamp string, body []byte) string
- func (s Scheme) MAC(secret, id, timestamp string, body []byte) []byte
- func (s Scheme) Matches(sig Signature, secrets []string, id, timestamp string, body []byte) bool
- func (s Scheme) Parse(value string) (Signature, error)
- func (s Scheme) Payload(id, timestamp string, body []byte) []byte
- func (s Scheme) UsesID() bool
- func (s Scheme) UsesTimestamp() bool
- type Signature
Constants ¶
const ( AlgorithmSHA256 = "sha256" AlgorithmSHA1 = "sha1" AlgorithmSHA512 = "sha512" )
Algorithms a scheme signs with.
const ( EncodingHex = "hex" EncodingBase64 = "base64" )
Encodings a signature is written in.
const ( // SignedBody signs the raw body. SignedBody = "body" // SignedTimestampBody signs the timestamp, a ".", and the raw body, // which is what makes a replayed request with an old timestamp fail // even though its signature once verified. SignedTimestampBody = "timestamp.body" // SignedIDTimestampBody signs the delivery id, a ".", the timestamp, a // ".", and the raw body: the Standard Webhooks form. SignedIDTimestampBody = "id.timestamp.body" )
What a scheme signs.
const ( // FormatPlain writes the prefix and the signature. A header may carry // several, separated by spaces, which is how a sender rotating its // secret signs with both (Standard Webhooks' "v1,<a> v1,<b>"). FormatPlain = "" // FormatStripe writes "t=<timestamp>,v1=<signature>": the timestamp is // in the signature header rather than a header of its own, and the // signed bytes are always the timestamp, a ".", and the body. FormatStripe = "stripe" )
How the signature header is written.
const ( PresetStandardWebhooks = "standard_webhooks" PresetGitHub = "github" PresetStripe = "stripe" // PresetPlatform is what the platform's own inbound webhook // documentation configures a source with, so a deployment's script can // deliver to another deployment's source with one setting. PresetPlatform = "platform" )
Presets by name.
Variables ¶
var ErrMalformed = errors.New("hmacsig: the signature header is malformed")
ErrMalformed is returned for a signature header that cannot be read as the scheme writes one.
Functions ¶
func ValidAlgorithm ¶
ValidAlgorithm reports whether a is an algorithm a scheme signs with.
func ValidEncoding ¶
ValidEncoding reports whether e is an encoding a signature is written in.
func ValidFormat ¶
ValidFormat reports whether f names a signature header format.
func ValidSigned ¶
ValidSigned reports whether v names what a scheme signs.
Types ¶
type Preset ¶
Preset names a sender's whole signing convention in one setting.
func LookupPreset ¶
LookupPreset returns the named convention.
type Scheme ¶
Scheme is how one sender signs.
func (Scheme) Matches ¶
Matches reports whether any of the signatures is the scheme's signature of the payload under any of the secrets. Every comparison is constant-time.
func (Scheme) Parse ¶
Parse reads a signature header's value. A value none of whose signatures can be read is ErrMalformed.
func (Scheme) UsesTimestamp ¶
UsesTimestamp reports whether the signed bytes include a timestamp.
Source Files