feat: verify signature from event webhook

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);
+ }
+ }
+}