Documentation
¶
Overview ¶
Package signature signs and verifies webhooks the Standard Webhooks way (https://www.standardwebhooks.com): three headers (webhook-id, webhook-timestamp, webhook-signature), an HMAC-SHA256 over "<id>.<timestamp>.<body>", and secrets written "whsec_" plus base64.
It imports only the standard library, so a Go service that receives the webhooks plugin/webhook sends can verify them without depending on the auth library at all; the plugin signs through the same functions, so the sender and the receiver cannot drift apart. Any other Standard Webhooks library (Svix's, the reference ones in other languages) verifies what Sign produces.
Index ¶
- Constants
- Variables
- func DecodeSecret(secret string) ([]byte, error)
- func Headers(msgID string, ts time.Time, payload []byte, secrets ...string) (http.Header, error)
- func NewSecret() string
- func Sign(secret, msgID string, ts time.Time, payload []byte) (string, error)
- func Verify(secret string, header http.Header, payload []byte) error
- func VerifyAt(secret string, header http.Header, payload []byte, now time.Time, ...) error
Constants ¶
const ( // HeaderID carries the message id: the same on every retry of one // message, so a receiver uses it as its idempotency key. HeaderID = "webhook-id" // HeaderTimestamp carries the send time in Unix seconds; it is signed, // which is what makes an old captured request useless (Tolerance). HeaderTimestamp = "webhook-timestamp" // HeaderSignature carries one or more space-separated "v1,<base64>" // signatures: more than one while a secret is being rotated. HeaderSignature = "webhook-signature" )
Header names, as the spec spells them.
const ( // SecretPrefix starts every secret, so one found in a log or a commit is // recognisable as a webhook secret and its scanners can flag it. SecretPrefix = "whsec_" // VersionV1 names the symmetric HMAC-SHA256 scheme; a signature is // "v1," followed by the base64 MAC. VersionV1 = "v1" // SecretSize is the length of a key NewSecret makes: 32 bytes (256 bits), // the MAC's own size, inside the spec's 24 to 64. SecretSize = 32 // MinSecretSize and MaxSecretSize are the spec's bounds on a key; a // decoded secret outside them is refused, because a short key is // guessable and the spec names no use for a longer one. MinSecretSize = 24 MaxSecretSize = 64 // DefaultTolerance is how far a timestamp may be from the receiver's // clock, either way, before Verify refuses it: long enough for clock // skew and a slow network, short enough that a captured request cannot // be replayed later. The spec names no number; five minutes is what the // reference libraries use. //ds:def id=defaulttolerance-8j3tkkz8 DefaultTolerance = 5 * time.Minute )
Secret and signature format.
Variables ¶
var ( // ErrBadSecret: the secret is not "whsec_" plus base64 of 24 to 64 bytes. ErrBadSecret = errors.New("signature: secret is not whsec_ and base64 of 24 to 64 bytes") // ErrMissingHeader: one of the three headers is absent or empty. ErrMissingHeader = errors.New("signature: a webhook header is missing") // ErrBadID: the message id contains a "." (which would make the signed // content ambiguous) or is empty. ErrBadID = errors.New("signature: message id is empty or contains a dot") // ErrBadTimestamp: webhook-timestamp is not an integer. ErrBadTimestamp = errors.New("signature: webhook-timestamp is not a Unix time in seconds") // ErrTimestampOutOfRange: the timestamp is further from now than the // tolerance, in either direction: a replay, or a badly wrong clock. ErrTimestampOutOfRange = errors.New("signature: webhook-timestamp is outside the tolerance") // ErrNoMatch: no signature in the header matches the body. ErrNoMatch = errors.New("signature: no signature matches") )
Errors Verify and DecodeSecret answer. A receiver answers 400 or 401 to any of them; which one it was is for its own log, not for the sender.
Functions ¶
func DecodeSecret ¶
DecodeSecret returns the key a secret stands for. The prefix is optional, as in the reference libraries, so a key pasted without it still works; the decoded length must be within MinSecretSize and MaxSecretSize.
func Headers ¶
Headers returns the three headers for one send: the id, ts as Unix seconds, and one signature per secret, space-separated, in the order given. Two secrets is a rotation: a receiver still holding the old one keeps verifying until it switches.
func NewSecret ¶
func NewSecret() string
NewSecret returns a fresh secret: SecretSize random bytes as "whsec_" plus standard base64.
func Sign ¶
Sign returns the "v1,<base64>" signature of payload sent as message msgID at ts. The payload is the exact request body: a receiver verifies the bytes it received, so re-encoding JSON between signing and sending breaks it.
func Verify ¶
Verify checks a received webhook against secret at the current time with DefaultTolerance. payload is the raw body, read before any JSON decoding.
func VerifyAt ¶
func VerifyAt(secret string, header http.Header, payload []byte, now time.Time, tolerance time.Duration) error
VerifyAt is Verify with the clock and the tolerance given, for a test or a receiver that wants a tighter window. Every candidate signature is compared with hmac.Equal, in constant time, and every one is compared even after a match would be known, so the time taken does not say which one matched.
Types ¶
This section is empty.