Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: verify signature from event webhook #969

Merged
merged 1 commit into from
May 29, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,5 @@ test.php
.vscode
prism
temp.php
example*.php
TODO.txt
sendgrid-php.zip
4 changes: 3 additions & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
"require": {
"php": ">=5.6",
"sendgrid/php-http-client": "~3.10",
"starkbank/ecdsa": "0.*",
"ext-curl": "*",
"ext-json": "*",
"ext-mbstring": "*",
Expand All @@ -31,8 +32,9 @@
"type": "library",
"autoload": {
"psr-4": {
"SendGrid\\Mail\\": "lib/mail/",
"SendGrid\\Contacts\\": "lib/contacts/",
"SendGrid\\EventWebhook\\": "lib/eventwebhook/",
"SendGrid\\Mail\\": "lib/mail/",
"SendGrid\\Stats\\": "lib/stats/"
},
"classmap": [
Expand Down
20 changes: 20 additions & 0 deletions examples/helpers/eventwebhook/example.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
<?php

use SendGrid\EventWebhook\EventWebhook;
use SendGrid\EventWebhook\EventWebhookHeader;


function isValidSignature($request)
{
$publicKey = 'base64-encoded public key';

$eventWebhook = new EventWebhook();
$ecPublicKey = $eventWebhook->convertPublicKeyToECDSA($publicKey);

return $eventWebhook->verifySignature(
$ecPublicKey,
$request->getContent(),
$request->header(EventWebhookHeader::SIGNATURE),
$request->header(EventWebhookHeader::TIMESTAMP)
);
}
46 changes: 46 additions & 0 deletions lib/eventwebhook/EventWebhook.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
<?php

namespace SendGrid\EventWebhook;

use EllipticCurve\Ecdsa;
use EllipticCurve\PublicKey;
use EllipticCurve\Signature;

/**
* 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
*
* @package SendGrid\EventWebhook
*/
class EventWebhook
{
/**
* Convert the public key string to a ECPublicKey.
*
* @param string $publicKey verification key under Mail Settings
* @return PublicKey public key using the ECDSA algorithm
*/
public function convertPublicKeyToECDSA($publicKey)
{
return PublicKey::fromString($publicKey);
}

/**
* Verify signed event webhook requests.
*
* @param PublicKey $publicKey elliptic curve public key
eshanholtz marked this conversation as resolved.
Show resolved Hide resolved
* @param string $payload event payload in the request body
* @param string $signature value obtained from the
* 'X-Twilio-Email-Event-Webhook-Signature' header
* @param string $timestamp value obtained from the
* 'X-Twilio-Email-Event-Webhook-Timestamp' header
* @return bool true or false if signature is valid
*/
public function verifySignature($publicKey, $payload, $signature, $timestamp)
{
$timestampedPayload = $timestamp . $payload;
$decodedSignature = Signature::fromBase64($signature);

return Ecdsa::verify($timestampedPayload, $decodedSignature, $publicKey);
}
}
15 changes: 15 additions & 0 deletions lib/eventwebhook/EventWebhookHeader.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
<?php

namespace SendGrid\EventWebhook;

/**
* This class lists headers that get posted to the webhook. Read the docs for
* more details: https://sendgrid.com/docs/for-developers/tracking-events/event
*
* @package SendGrid\EventWebhook
*/
abstract class EventWebhookHeader
{
const SIGNATURE = "X-Twilio-Email-Event-Webhook-Signature";
const TIMESTAMP = "X-Twilio-Email-Event-Webhook-Timestamp";
}
1 change: 1 addition & 0 deletions lib/loader.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
require_once __DIR__ . '/TwilioEmail.php';
require_once __DIR__ . '/contacts/Recipient.php';
require_once __DIR__ . '/contacts/RecipientForm.php';
require_once __DIR__ . '/eventwebhook/EventWebhook.php';
require_once __DIR__ . '/mail/EmailAddress.php';
require_once __DIR__ . '/mail/Asm.php';
require_once __DIR__ . '/mail/Attachment.php';
Expand Down
94 changes: 94 additions & 0 deletions test/unit/EventWebhookTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
<?php

namespace SendGrid\Tests\Unit;

use PHPUnit\Framework\TestCase;
use SendGrid\EventWebhook\EventWebhook;

/**
* This class tests the EventWebhook functionality.
*
* @package SendGrid\Tests\Unit
*/
class EventWebhookTest extends TestCase
{
const PUBLIC_KEY = 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEDr2LjtURuePQzplybd
C+u4CwrqDqBaWjcMMsTbhdbcwHBcepxo7yAQGhHPTnlvFYPAZFceEu/1FwCM/QmGUhA==';
const PAYLOAD = '{"category":"example_payload","event":"test_event","message_id":"message_id"}';
const SIGNATURE = 'MEUCIQCtIHJeH93Y+qpYeWrySphQgpNGNr/U+UyUlBkU6n7RAwIgJTz2
C+8a8xonZGi6BpSzoQsbVRamr2nlxFDWYNH2j/0=';
const TIMESTAMP = '1588788367';

public function testVerifySignature()
{
$isValidSignature = $this->verify(
self::PUBLIC_KEY,
self::PAYLOAD,
self::SIGNATURE,
self::TIMESTAMP
);

$this->assertTrue($isValidSignature);
}

public function testBadKey()
{
$isValidSignature = $this->verify(
'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqTxd43gyp8IOEto2LdIfjRQrIbsd4S
XZkLW6jDutdhXSJCWHw8REntlo7aNDthvj+y7GjUuFDb/R1NGe1OPzpA==',
self::PAYLOAD,
self::SIGNATURE,
self::TIMESTAMP
);

$this->assertFalse($isValidSignature);
}

public function testBadPayload()
{
$isValidSignature = $this->verify(
self::PUBLIC_KEY,
'payload',
self::SIGNATURE,
self::TIMESTAMP
);

$this->assertFalse($isValidSignature);
}

public function testBadSignature()
{
$isValidSignature = $this->verify(
self::PUBLIC_KEY,
self::PAYLOAD,
'signature',
self::TIMESTAMP
);

$this->assertFalse($isValidSignature);
}

public function testBadTimestamp()
{
$isValidSignature = $this->verify(
self::PUBLIC_KEY,
self::PAYLOAD,
self::SIGNATURE,
'timestamp'
);

$this->assertFalse($isValidSignature);
}

private function verify($publicKey, $payload, $signature, $timestamp)
eshanholtz marked this conversation as resolved.
Show resolved Hide resolved
{
$eventWebhook = new EventWebhook();
$ecPublicKey = $eventWebhook->convertPublicKeyToECDSA($publicKey);
return $eventWebhook->verifySignature(
$ecPublicKey,
$payload,
$signature,
$timestamp
);
}
}