Add v3 webhook signature verification

This change is an extension of the PR raised by @ChezCrawford (#326), where the
requested changes have been applied to the branch and all commits have been
squashed.

This adds a new function to the package, VerifySignatureWebhookV3, which accepts
an *http.Request and a secret, and validates that the request is properly signed
using that secret. This function does return some sentinel error values so that
you can choose which HTTP status to send back to the caller.

Supersedes #326

Author: ChuckCrawford

README.md

@@ -173,6 +173,14 @@ if ok { // resp is an *http.Response we can inspect
 }
 ```
 
+#### Included Packages
+
+##### webhookv3
+
+Support for V3 of PagerDuty Webhooks is provided via the `webhookv3` package.
+The intent is for this package to provide signature verification and decoding
+helpers.
+
 ## Contributing
 
 1. Fork it ( https://github.com/PagerDuty/go-pagerduty/fork )

examples/webhooks/webhook_server.go

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"fmt"
+	"log"
+	"net/http"
+
+	"github.com/PagerDuty/go-pagerduty/webhookv3"
+)
+
+const (
+	secret = "lDQHScfUeXUKaQRNF+8XIiDKZ7XX3itBAYzwU0TARw8lJqRnkKl2iB1anSb0Z+IK"
+)
+
+func main() {
+	http.HandleFunc("/webhook", handler)
+	log.Fatal(http.ListenAndServe(":8080", nil))
+}
+
+func handler(w http.ResponseWriter, r *http.Request) {
+	err := webhookv3.VerifySignature(r, secret)
+	if err != nil {
+		switch err {
+		case webhookv3.ErrNoValidSignatures:
+			w.WriteHeader(http.StatusUnauthorized)
+
+		case webhookv3.ErrMalformedBody, webhookv3.ErrMalformedHeader:
+			w.WriteHeader(http.StatusBadRequest)
+
+		default:
+			w.WriteHeader(http.StatusInternalServerError)
+		}
+
+		fmt.Fprintf(w, "%v", err)
+		return
+	}
+
+	fmt.Fprintf(w, "received signed webhook")
+}

webhookv3/webhookv3.go

@@ -0,0 +1,107 @@
+// Package webhookv3 provides functionality for working with V3 PagerDuty
+// Webhooks, including signature verification and decoding.
+package webhookv3
+
+import (
+	"bytes"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"io/ioutil"
+	"net/http"
+	"strings"
+)
+
+// ErrNoValidSignatures is returned when a webhook is not properly signed
+// with the expected signature. When receiving this error, it is reccommended
+// that the server return HTTP 403 to prevent redelivery.
+var ErrNoValidSignatures = errors.New("invalid webhook signature")
+
+// ErrMalformedHeader is returned when the *http.Request is missing the
+// X-PagerDuty-Signature header. When receiving this error, it is recommended
+// that the server return HTTP 400 to prevent redelivery.
+var ErrMalformedHeader = errors.New("X-PagerDuty-Signature header is either missing or malformed")
+
+// ErrMalformedBody is returned when the *http.Request body is either
+// missing or malformed. When receiving this error, it's recommended that the
+// server return HTTP 400 to prevent redelivery.
+var ErrMalformedBody = errors.New("HTTP request body is either empty or malformed")
+
+const (
+	webhookSignaturePrefix = "v1="
+	webhookSignatureHeader = "X-PagerDuty-Signature"
+	webhookBodyReaderLimit = 2 * 1024 * 1024 // 2MB
+)
+
+// VerifySignature compares the provided signature of a PagerDuty v3 Webhook
+// against the expected value and returns an ErrNoValidSignature error if the
+// values do not match. This function may also return ErrMalformedHeader or
+// ErrMalformedBody if the request appears to be malformed.
+//
+// See https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTkz-verifying-signatures for more details.
+//
+// This function will fail to read any HTTP request body that's 2MB or larger.
+func VerifySignature(r *http.Request, secret string) error {
+	h := r.Header.Get(webhookSignatureHeader)
+	if len(h) == 0 {
+		return ErrMalformedHeader
+	}
+
+	orb := r.Body
+
+	b, err := ioutil.ReadAll(io.LimitReader(r.Body, webhookBodyReaderLimit))
+	if err != nil {
+		return fmt.Errorf("failed to read response body: %w", err)
+	}
+
+	defer func() { _ = orb.Close() }()
+	r.Body = ioutil.NopCloser(bytes.NewReader(b))
+
+	if len(b) == 0 {
+		return ErrMalformedBody
+	}
+
+	sigs := extractPayloadSignatures(h)
+	if len(sigs) == 0 {
+		return ErrMalformedHeader
+	}
+
+	s := calculateSignature(b, secret)
+
+	for _, sig := range sigs {
+		if hmac.Equal(s, sig) {
+			return nil
+		}
+	}
+
+	return ErrNoValidSignatures
+}
+
+func extractPayloadSignatures(s string) [][]byte {
+	var sigs [][]byte
+
+	for _, sv := range strings.Split(s, ",") {
+		// Ignore any signatures that are not the initial v1 version.
+		if !strings.HasPrefix(sv, webhookSignaturePrefix) {
+			continue
+		}
+
+		sig, err := hex.DecodeString(strings.TrimPrefix(sv, webhookSignaturePrefix))
+		if err != nil {
+			continue
+		}
+
+		sigs = append(sigs, sig)
+	}
+
+	return sigs
+}
+
+func calculateSignature(payload []byte, secret string) []byte {
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write(payload)
+	return mac.Sum(nil)
+}

webhookv3/webhookv3_test.go

@@ -0,0 +1,84 @@
+package webhookv3
+
+import (
+	"errors"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+const (
+	secret      = "lDQHScfUeXUKaQRNF+8XIiDKZ7XX3itBAYzwU0TARw8lJqRnkKl2iB1anSb0Z+IK" /* #nosec */
+	defaultBody = `{"event":{"id":"01BWDWL3NYY7LUFPZCC28QUCMK","event_type":"incident.priority_updated","resource_type":"incident","occurred_at":"2021-04-26T17:36:27.458Z","agent":{"html_url":"https://acme.pagerduty.com/users/PLH1HKV","id":"PLH1HKV","self":"https://api.pagerduty.com/users/PLH1HKV","summary":"Tenex Engineer","type":"user_reference"},"client":null,"data":{"id":"PGR0VU2","type":"incident","self":"https://api.pagerduty.com/incidents/PGR0VU2","html_url":"https://acme.pagerduty.com/incidents/PGR0VU2","number":2,"status":"triggered","title":"A little bump in the road","service":{"html_url":"https://acme.pagerduty.com/services/PF9KMXH","id":"PF9KMXH","self":"https://api.pagerduty.com/services/PF9KMXH","summary":"API Service","type":"service_reference"},"assignees":[{"html_url":"https://acme.pagerduty.com/users/PTUXL6G","id":"PTUXL6G","self":"https://api.pagerduty.com/users/PTUXL6G","summary":"User 123","type":"user_reference"}],"escalation_policy":{"html_url":"https://acme.pagerduty.com/escalation_policies/PUS0KTE","id":"PUS0KTE","self":"https://api.pagerduty.com/escalation_policies/PUS0KTE","summary":"Default","type":"escalation_policy_reference"},"teams":[{"html_url":"https://acme.pagerduty.com/teams/PFCVPS0","id":"PFCVPS0","self":"https://api.pagerduty.com/teams/PFCVPS0","summary":"Engineering","type":"team_reference"}],"priority":{"html_url":"https://acme.pagerduty.com/account/incident_priorities","id":"PSO75BM","self":"https://api.pagerduty.com/priorities/PSO75BM","summary":"P1","type":"priority_reference"},"urgency":"high","conference_bridge":{"conference_number":1000,"conference_url":"https://example.com"},"resolve_reason":null}}}`
+)
+
+func TestVerifySignature(t *testing.T) {
+	tests := []struct {
+		name string
+		sig  string
+		body string
+		err  error
+	}{
+		{
+			name: "valid",
+			sig:  "v1=0c0b9495b893a39e70d1fea2fe11fbe0a825f88b9f67846f6cc07dd2bc5476cd",
+			body: defaultBody,
+		},
+		{
+			name: "mismatch",
+			sig:  "v1=7020c8a7ec668a9b7012bc3dd82e483394b038f4230acc6785efbf2a7d8bcaf5",
+			body: defaultBody,
+			err:  ErrNoValidSignatures,
+		},
+		{
+			name: "malformed_header",
+			body: defaultBody,
+			err:  ErrMalformedHeader,
+		},
+		{
+			name: "malformed_body",
+			sig:  "v1=0c0b9495b893a39e70d1fea2fe11fbe0a825f88b9f67846f6cc07dd2bc5476cd",
+			err:  ErrMalformedBody,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req, err := http.NewRequest(http.MethodGet, "http://127.0.0.1:80/test", strings.NewReader(tt.body))
+			if err != nil {
+				t.Fatalf("failed to generate new request: %s", err.Error())
+			}
+
+			req.Header.Set("X-PagerDuty-Signature", tt.sig)
+
+			testErrIs(t, "VerifySignature", tt.err, VerifySignature(req, secret))
+		})
+	}
+}
+
+// testErrIs looks to see if wantErr is gotErr. If not, this calls t.Fatal(). It
+// also calls t.Fatal() if there gotErr is not nil, but wantErr is. Returns true
+// if you should continue running the test, or false if you should stop the
+// test.
+func testErrIs(t *testing.T, name string, wantErr, gotErr error) bool {
+	t.Helper()
+
+	if wantErr != nil {
+		if gotErr == nil {
+			t.Fatalf("%s error = <nil>, should be %v", name, wantErr)
+			return false
+		}
+
+		if !errors.Is(gotErr, wantErr) {
+			t.Fatalf("error %v is not %v", gotErr, wantErr)
+			return false
+		}
+	}
+
+	if wantErr == nil && gotErr != nil {
+		t.Fatalf("%s unexpected error: %v", name, gotErr)
+		return false
+	}
+
+	return true
+}