Merge pull request #41 from web-push-libs/vapid

Add VAPID compatibility, close #8

Author: Minishlink

.travis.yml

@@ -13,7 +13,7 @@ before_install:
   - nvm install node
 
 install:
-  - npm install web-push-testing-service@0.2.1 -g
+  - npm install web-push-testing-service@0.3.0 -g
 
 before_script:
   - composer install --prefer-source -n --no-dev

CONTRIBUTING.md

@@ -20,8 +20,4 @@ following commands:
 **For a Single Test**
     `php phpunit.phar . --filter "/::testPadPayload( .*)?$/"` (regex)
 
-Some tests have a custom decorator @skipIfTravis. The reason is that
-there's no way in Travis to update the push subscription, so the endpoint
-in my phpunit.travis.xml would ultimately expire
-(and require a human modification), and the corresponding tests would fail.
 But locally, these tests are handy.

README.md

@@ -70,24 +70,39 @@ There are several good examples and tutorials on the web:
 * Google's [introduction to push notifications](https://developers.google.com/web/fundamentals/getting-started/push-notifications/) (as of 03-20-2016, it doesn't mention notifications with payload)
 * you may want to take a look at my own implementation: [sw.js](https://github.com/Minishlink/physbook/blob/2ed8b9a8a217446c9747e9191a50d6312651125d/web/service-worker.js) and [app.js](https://github.com/Minishlink/physbook/blob/d6855ca8f485556ab2ee5c047688fbf745367045/app/Resources/public/js/app.js)
 
-### GCM servers notes (Chrome)
-For compatibility reasons, this library detects if the server is a GCM server and appropriately sends the notification.
+### Authentication
+Browsers need to verify your identity. A standard called VAPID can authenticate you for all browsers. You'll need to create and provide a public and private key for your server.
 
-You will need to specify your GCM api key when instantiating WebPush:
+You can specify your authentication details when instantiating WebPush. The keys can be passed directly, or you can load a PEM file or its content:
 ```php
 <?php
 
 use Minishlink\WebPush\WebPush;
 
 $endpoint = 'https://android.googleapis.com/gcm/send/abcdef...'; // Chrome
-$apiKeys = array(
-    'GCM' => 'MY_GCM_API_KEY',
+
+$auth = array(
+    'GCM' => 'MY_GCM_API_KEY', // deprecated and optional, it's here only for compatibility reasons
+    'VAPID' => array(
+        'subject' => 'mailto:[email protected]', // can be a mailto: or your website address
+        'publicKey' => '~88 chars', // uncompressed public key P-256 encoded in Base64-URL
+        'privateKey' => '~44 chars', // in fact the secret multiplier of the private key encoded in Base64-URL
+        'pemFile' => 'path/to/pem', // if you have a PEM file and can link to it on your filesystem
+        'pem' => 'pemFileContent', // if you have a PEM file and want to hardcode its content
+    ),
 );
 
-$webPush = new WebPush($apiKeys);
+$webPush = new WebPush($auth);
 $webPush->sendNotification($endpoint, null, null, null, true);
 ```
 
+In order to generate the uncompressed public and secret key, encoded in Base64, enter the following in your Linux bash:
+```
+$ openssl ecparam -genkey -name prime256v1 -out private_key.pem
+$ openssl ec -in private_key.pem -pubout -outform DER|tail -c 65|base64|tr -d '=' |tr '/+' '_-' >> public_key.txt
+$ openssl ec -in private_key.pem -outform DER|tail -c +8|head -c 32|base64|tr -d '=' |tr '/+' '_-' >> private_key.txt
+```
+
 ### Notification options
 Each notification can have a specific Time To Live, urgency, and topic.
 You can change the default options with `setDefaultOptions()` or in the constructor:

composer.json

@@ -18,7 +18,8 @@
     "mdanter/ecc": "^0.4.0",
     "lib-openssl": "*",
     "spomky-labs/base64url": "^1.0",
-    "spomky-labs/php-aes-gcm": "^1.0"
+    "spomky-labs/php-aes-gcm": "^1.0",
+    "spomky-labs/jose": "^6.0"
   },
   "require-dev": {
     "phpunit/phpunit": "4.8.*"

phpunit.dist.xml

@@ -23,5 +23,8 @@
         <env name="GCM_USER_PUBLIC_KEY" value="" />
         <env name="GCM_USER_AUTH_TOKEN" value="" />
         <env name="GCM_API_KEY" value="" />
+
+        <env name="VAPID_PUBLIC_KEY" value="" />
+        <env name="VAPID_PRIVATE_KEY" value="" />
     </php>
 </phpunit>

src/Encryption.php

@@ -21,20 +21,22 @@ final class Encryption
 
     /**
      * @param string $payload
-     * @param bool $automatic
+     * @param bool   $automatic
+     *
      * @return string padded payload (plaintext)
      */
     public static function padPayload($payload, $automatic)
     {
         $payloadLen = Utils::safeStrlen($payload);
         $padLen = $automatic ? self::MAX_PAYLOAD_LENGTH - $payloadLen : 0;
+
         return pack('n*', $padLen).str_pad($payload, $padLen + $payloadLen, chr(0), STR_PAD_LEFT);
     }
 
     /**
-     * @param string $payload With padding
-     * @param string $userPublicKey Base 64 encoded (MIME or URL-safe)
-     * @param string $userAuthToken Base 64 encoded (MIME or URL-safe)
+     * @param string $payload          With padding
+     * @param string $userPublicKey    Base 64 encoded (MIME or URL-safe)
+     * @param string $userAuthToken    Base 64 encoded (MIME or URL-safe)
      * @param bool   $nativeEncryption Use OpenSSL (>PHP7.1)
      *
      * @return array
@@ -60,8 +62,7 @@ public static function encrypt($payload, $userPublicKey, $userAuthToken, $native
         $userPublicKeyObject = $generator->getPublicKeyFrom($pointUserPublicKey->getX(), $pointUserPublicKey->getY(), $generator->getOrder());
 
         // get shared secret from user public key and local private key
-        $localPrivateSecret = $localPrivateKeyObject->getSecret();
-        $sharedSecret = hex2bin($math->decHex(gmp_strval($userPublicKeyObject->getPoint()->mul($localPrivateSecret)->getX())));
+        $sharedSecret = hex2bin($math->decHex(gmp_strval($userPublicKeyObject->getPoint()->mul($localPrivateKeyObject->getSecret())->getX())));
 
         // generate salt
         $salt = openssl_random_pseudo_bytes(16);
@@ -85,7 +86,7 @@ public static function encrypt($payload, $userPublicKey, $userAuthToken, $native
         // encrypt
         // "The additional data passed to each invocation of AEAD_AES_128_GCM is a zero-length octet sequence."
         if (!$nativeEncryption) {
-            list($encryptedText, $tag) = \AESGCM\AESGCM::encrypt($contentEncryptionKey, $nonce, $payload, "");
+            list($encryptedText, $tag) = \AESGCM\AESGCM::encrypt($contentEncryptionKey, $nonce, $payload, '');
         } else {
             $encryptedText = openssl_encrypt($payload, 'aes-128-gcm', $contentEncryptionKey, OPENSSL_RAW_DATA, $nonce, $tag); // base 64 encoded
         }
@@ -99,7 +100,7 @@ public static function encrypt($payload, $userPublicKey, $userAuthToken, $native
     }
 
     /**
-     * HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
+     * HMAC-based Extract-and-Expand Key Derivation Function (HKDF).
      *
      * This is used to derive a secure encryption key from a mostly-secure shared
      * secret.
@@ -115,6 +116,7 @@ public static function encrypt($payload, $userPublicKey, $userAuthToken, $native
      * @param $ikm string Input keying material
      * @param $info string Application-specific context
      * @param $length int The length (in bytes) of the required output key
+     *
      * @return string
      */
     private static function hkdf($salt, $ikm, $info, $length)
@@ -130,11 +132,13 @@ private static function hkdf($salt, $ikm, $info, $length)
      * Creates a context for deriving encyption parameters.
      * See section 4.2 of
      * {@link https://tools.ietf.org/html/draft-ietf-httpbis-encryption-encoding-00}
-     * From {@link https://github.com/GoogleChrome/push-encryption-node/blob/master/src/encrypt.js}
+     * From {@link https://github.com/GoogleChrome/push-encryption-node/blob/master/src/encrypt.js}.
      *
      * @param $clientPublicKey string The client's public key
      * @param $serverPublicKey string Our public key
+     *
      * @return string
+     *
      * @throws \ErrorException
      */
     private static function createContext($clientPublicKey, $serverPublicKey)
@@ -156,14 +160,17 @@ private static function createContext($clientPublicKey, $serverPublicKey)
     /**
      * Returns an info record. See sections 3.2 and 3.3 of
      * {@link https://tools.ietf.org/html/draft-ietf-httpbis-encryption-encoding-00}
-     * From {@link https://github.com/GoogleChrome/push-encryption-node/blob/master/src/encrypt.js}
+     * From {@link https://github.com/GoogleChrome/push-encryption-node/blob/master/src/encrypt.js}.
      *
      * @param $type string The type of the info record
      * @param $context string The context for the record
+     *
      * @return string
+     *
      * @throws \ErrorException
      */
-    private static function createInfo($type, $context) {
+    private static function createInfo($type, $context)
+    {
         if (Utils::safeStrlen($context) !== 135) {
             throw new \ErrorException('Context argument has invalid size');
         }

src/Notification.php

@@ -25,7 +25,7 @@ class Notification
     /** @var string */
     private $userAuthToken;
 
-    /** @var array Options : TTL, urgency, topic **/
+    /** @var array Options : TTL, urgency, topic * */
     private $options;
 
     public function __construct($endpoint, $payload, $userPublicKey, $userAuthToken, $options)
@@ -71,16 +71,16 @@ public function getUserAuthToken()
 
     /**
      * @param array $defaultOptions
+     *
      * @return array
      */
     public function getOptions(array $defaultOptions = array())
     {
         $options = $this->options;
-        $options['TTL'] = array_key_exists('TTL', $options) ?  $options['TTL'] : $defaultOptions['TTL'];
+        $options['TTL'] = array_key_exists('TTL', $options) ? $options['TTL'] : $defaultOptions['TTL'];
         $options['urgency'] = array_key_exists('urgency', $options) ? $options['urgency'] : $defaultOptions['urgency'];
         $options['topic'] = array_key_exists('topic', $options) ? $options['topic'] : $defaultOptions['topic'];
 
         return $options;
     }
-
 }

src/Utils.php

@@ -13,7 +13,8 @@
 
 class Utils
 {
-    public static function safeStrlen($string) {
-        return mb_strlen($string, "8bit");
+    public static function safeStrlen($string)
+    {
+        return mb_strlen($string, '8bit');
     }
 }

src/VAPID.php

@@ -0,0 +1,134 @@
+<?php
+
+/*
+ * This file is part of the WebPush library.
+ *
+ * (c) Louis Lagrange <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Minishlink\WebPush;
+
+use Base64Url\Base64Url;
+use Jose\Factory\JWKFactory;
+use Jose\Factory\JWSFactory;
+use Mdanter\Ecc\EccFactory;
+use Mdanter\Ecc\Serializer\Point\UncompressedPointSerializer;
+use Mdanter\Ecc\Serializer\PrivateKey\DerPrivateKeySerializer;
+use Mdanter\Ecc\Serializer\PrivateKey\PemPrivateKeySerializer;
+
+class VAPID
+{
+    /**
+     * @param array $vapid
+     *
+     * @return array
+     *
+     * @throws \ErrorException
+     */
+    public static function validate(array $vapid)
+    {
+        if (!array_key_exists('subject', $vapid)) {
+            throw new \ErrorException('[VAPID] You must provide a subject that is either a mailto: or a URL.');
+        }
+
+        if (array_key_exists('pemFile', $vapid)) {
+            $vapid['pem'] = file_get_contents($vapid['pemFile']);
+
+            if (!$vapid['pem']) {
+                throw new \ErrorException('Error loading PEM file.');
+            }
+        }
+
+        if (array_key_exists('pem', $vapid)) {
+            $pem = $vapid['pem'];
+            $posStartKey = strpos($pem, '-----BEGIN EC PRIVATE KEY-----');
+            $posEndKey = strpos($pem, '-----END EC PRIVATE KEY-----');
+
+            if ($posStartKey === false || $posEndKey === false) {
+                throw new \ErrorException('Invalid PEM data.');
+            }
+
+            $posStartKey += 30; // length of '-----BEGIN EC PRIVATE KEY-----'
+
+            $pemSerializer = new PemPrivateKeySerializer(new DerPrivateKeySerializer());
+            $keys = $pemSerializer->parse(substr($pem, $posStartKey, $posEndKey - $posStartKey));
+
+            $pointSerializer = new UncompressedPointSerializer(EccFactory::getAdapter());
+            $vapid['publicKey'] = base64_encode(hex2bin($pointSerializer->serialize($keys->getPublicKey()->getPoint())));
+            $vapid['privateKey'] = base64_encode(hex2bin(gmp_strval($keys->getSecret(), 16)));
+        }
+
+        if (!array_key_exists('publicKey', $vapid)) {
+            throw new \ErrorException('[VAPID] You must provide a public key.');
+        }
+
+        $publicKey = Base64Url::decode($vapid['publicKey']);
+
+        if (Utils::safeStrlen($publicKey) !== 65) {
+            throw new \ErrorException('[VAPID] Public key should be 65 bytes long when decoded.');
+        }
+
+        if (!array_key_exists('privateKey', $vapid)) {
+            throw new \ErrorException('[VAPID] You must provide a private key.');
+        }
+
+        $privateKey = Base64Url::decode($vapid['privateKey']);
+
+        if (Utils::safeStrlen($privateKey) !== 32) {
+            throw new \ErrorException('[VAPID] Private key should be 32 bytes long when decoded.');
+        }
+
+        return array(
+            'subject' => $vapid['subject'],
+            'publicKey' => $publicKey,
+            'privateKey' => $privateKey,
+        );
+    }
+
+    /**
+     * This method takes the required VAPID parameters and returns the required
+     * header to be added to a Web Push Protocol Request.
+     *
+     * @param string $audience   This must be the origin of the push service
+     * @param string $subject    This should be a URL or a 'mailto:' email address
+     * @param string $publicKey  The decoded VAPID public key
+     * @param string $privateKey The decoded VAPID private key
+     * @param int    $expiration The expiration of the VAPID JWT. (UNIX timestamp)
+     *
+     * @return array Returns an array with the 'Authorization' and 'Crypto-Key' values to be used as headers
+     */
+    public static function getVapidHeaders($audience, $subject, $publicKey, $privateKey, $expiration = null)
+    {
+        $expirationLimit = time() + 86400;
+        if (!isset($expiration) || $expiration > $expirationLimit) {
+            $expiration = $expirationLimit;
+        }
+
+        $header = array(
+            'typ' => 'JWT',
+            'alg' => 'ES256',
+        );
+
+        $jwtPayload = json_encode(array(
+            'aud' => $audience,
+            'exp' => $expiration,
+            'sub' => $subject,
+        ), JSON_UNESCAPED_SLASHES | JSON_NUMERIC_CHECK);
+
+        $generator = EccFactory::getNistCurves()->generator256();
+        $privateKeyObject = $generator->getPrivateKeyFrom(gmp_init(bin2hex($privateKey), 16));
+        $pemSerialize = new PemPrivateKeySerializer(new DerPrivateKeySerializer());
+        $pem = $pemSerialize->serialize($privateKeyObject);
+
+        $jwk = JWKFactory::createFromKey($pem, null);
+        $jws = JWSFactory::createJWSToCompactJSON($jwtPayload, $jwk, $header);
+
+        return array(
+          'Authorization' => 'WebPush '.$jws,
+          'Crypto-Key' => 'p256ecdsa='.Base64Url::encode($publicKey),
+        );
+    }
+}