feat: verify signature from event webhook (#1010)

When enabling the "Signed Event Webhook Requests" feature in Mail Settings, Twilio SendGrid will generate a private and public key pair using the Elliptic Curve Digital Signature Algorithm (ECDSA). Once that is successfully enabled, all new event posts will have two new headers: X-Twilio-Email-Event-Webhook-Signature and X-Twilio-Email-Event-Webhook-Timestamp, which can be used to validate your events.

This SDK update will make it easier to verify signatures from signed event webhook requests by using the VerifySignature method. Pass in the public key, event payload, signature, and timestamp to validate. Note: You will need to convert your public key string to an elliptic public key object in order to use the VerifySignature method.

Author: childish-sambino

examples/eventwebhook/RequestValidator.cs

@@ -0,0 +1,24 @@
+using Microsoft.AspNetCore.Http;
+using SendGrid.Helpers.EventWebhook;
+using System.IO;
+
+public bool IsValidSignature(HttpRequest request)
+{
+    var publicKey = "base64-encoded public key";
+    string requestBody;
+
+    using (var reader = new StreamReader(request.Body))
+    {
+        requestBody = reader.ReadToEnd();
+    }
+
+    var validator = new RequestValidator();
+    var ecPublicKey = validator.ConvertPublicKeyToECDSA(publicKey);
+
+    return validator.VerifySignature(
+        ecPublicKey,
+        requestBody,
+        request.Headers[RequestValidator.SIGNATURE_HEADER],
+        request.Headers[RequestValidator.TIMESTAMP_HEADER]
+    );
+}

src/SendGrid/Helpers/EventWebhook/RequestValidator.cs

@@ -0,0 +1,47 @@
+using EllipticCurve;
+
+namespace SendGrid.Helpers.EventWebhook
+{
+    /// <summary>
+    /// This class allows you to use the Event Webhook feature. Read the docs for
+    /// more details: https://sendgrid.com/docs/for-developers/tracking-events/event
+    /// </summary>
+    public class RequestValidator
+    {
+        /// <summary>
+        /// Signature verification HTTP header name for the signature being sent.
+        /// </summary>
+        public const string SIGNATURE_HEADER = "X-Twilio-Email-Event-Webhook-Signature";
+
+        /// <summary>
+        /// Timestamp HTTP header name for timestamp.
+        /// </summary>
+        public const string TIMESTAMP_HEADER = "X-Twilio-Email-Event-Webhook-Timestamp";
+
+        /// <summary>
+        /// Convert the public key string to a <see cref="PublicKey"/>.
+        /// </summary>
+        /// <param name="publicKey">verification key under Mail Settings</param>
+        /// <returns>public key using the ECDSA algorithm</returns>
+        public PublicKey ConvertPublicKeyToECDSA(string publicKey)
+        {
+            return PublicKey.fromPem(publicKey);
+        }
+
+        /// <summary>
+        /// Verify signed event webhook requests.
+        /// </summary>
+        /// <param name="publicKey">elliptic curve public key</param>
+        /// <param name="payload">event payload in the request body</param>
+        /// <param name="signature">value obtained from the 'X-Twilio-Email-Event-Webhook-Signature' header</param>
+        /// <param name="timestamp">value obtained from the 'X-Twilio-Email-Event-Webhook-Timestamp' header</param>
+        /// <returns>true or false if signature is valid</returns>
+        public bool VerifySignature(PublicKey publicKey, string payload, string signature, string timestamp)
+        {
+            var timestampedPayload = timestamp + payload;
+            var decodedSignature = Signature.fromBase64(signature);
+
+            return Ecdsa.verify(timestampedPayload, decodedSignature, publicKey);
+        }
+    }
+}

tests/SendGrid.Tests/Helpers/EventWebhook/RequestValidatorTests.cs

@@ -0,0 +1,85 @@
+using Xunit;
+using SendGrid.Helpers.EventWebhook;
+
+namespace SendGrid.Tests.Helpers.EventWebhook
+{
+    public class RequestValidatorTests
+    {
+        private const string PUBLIC_KEY = "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEDr2LjtURuePQzplybdC+u4CwrqDqBaWjcMMsTbhdbcwHBcepxo7yAQGhHPTnlvFYPAZFceEu/1FwCM/QmGUhA==";
+        private const string PAYLOAD = "{\"category\":\"example_payload\",\"event\":\"test_event\",\"message_id\":\"message_id\"}";
+        private const string SIGNATURE = "MEUCIQCtIHJeH93Y+qpYeWrySphQgpNGNr/U+UyUlBkU6n7RAwIgJTz2C+8a8xonZGi6BpSzoQsbVRamr2nlxFDWYNH2j/0=";
+        private const string TIMESTAMP = "1588788367";
+
+        [Fact]
+        public void TestVerifySignature()
+        {
+            var isValidSignature = Verify(
+                PUBLIC_KEY,
+                PAYLOAD,
+                SIGNATURE,
+                TIMESTAMP
+            );
+
+            Assert.True(isValidSignature);
+        }
+
+        [Fact]
+        public void TestBadKey()
+        {
+            var isValidSignature = Verify(
+                "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqTxd43gyp8IOEto2LdIfjRQrIbsd4SXZkLW6jDutdhXSJCWHw8REntlo7aNDthvj+y7GjUuFDb/R1NGe1OPzpA==",
+                PAYLOAD,
+                SIGNATURE,
+                TIMESTAMP
+            );
+
+            Assert.False(isValidSignature);
+        }
+
+        [Fact]
+        public void TestBadPayload()
+        {
+            var isValidSignature = Verify(
+                PUBLIC_KEY,
+                "payload",
+                SIGNATURE,
+                TIMESTAMP
+            );
+
+            Assert.False(isValidSignature);
+        }
+
+        [Fact]
+        public void TestBadSignature()
+        {
+            var isValidSignature = Verify(
+                PUBLIC_KEY,
+                PAYLOAD,
+                "MEQCIB3bJQOarffIdM7+MEee+kYAdoViz6RUoScOASwMcXQxAiAcrus/j853JUlVm5qIRfbKBJwJq89znqOTedy3RetXLQ==",
+                TIMESTAMP
+            );
+
+            Assert.False(isValidSignature);
+        }
+
+        [Fact]
+        public void TestBadTimestamp()
+        {
+            var isValidSignature = Verify(
+                PUBLIC_KEY,
+                PAYLOAD,
+                SIGNATURE,
+                "timestamp"
+            );
+
+            Assert.False(isValidSignature);
+        }
+
+        private bool Verify(string publicKey, string payload, string signature, string timestamp)
+        {
+            var validator = new RequestValidator();
+            var ecPublicKey = validator.ConvertPublicKeyToECDSA(publicKey);
+            return validator.VerifySignature(ecPublicKey, payload, signature, timestamp);
+        }
+    }
+}