ウェブプッシュ プロトコル

ここまで、ライブラリを使用して push メッセージをトリガーする仕組みを見てきましたが、これらのライブラリでは具体的にどのようなことが行われるのでしょうか。

ネットワーク リクエストが正しい形式であることを確かめながら行っています。このネットワーク リクエストを定義する仕様は、ウェブプッシュ プロトコルです。

サーバーから push サービスに push メッセージを送信する図

このセクションでは、サーバーがアプリケーション サーバー鍵で自身を識別する方法と、暗号化されたペイロードと関連データの送信方法について説明します。

これはウェブ プッシュの便利な側面ではなく、私は暗号化の専門家ではありませんが、これらのライブラリの内部動作を知ることは便利なので、各要素を見てみましょう。

アプリケーション サーバーキー

ユーザーを登録するときは、applicationServerKey を渡します。このキーは push サービスに渡され、ユーザーをサブスクライブしたアプリが push メッセージをトリガーしているアプリであることを確認するために使用されます。

push メッセージをトリガーすると、push サービスがアプリケーションを認証するための一連のヘッダーが送信されます。(これは VAPID 仕様で定義されています)。

具体的にはどのような意味があり、具体的にどのようなことが起こるのでしょうか。アプリケーションサーバー認証の手順は次のとおりです

  1. アプリケーション サーバーは、プライベート アプリケーション キーを使用して JSON 情報に署名します。
  2. この署名付き情報は、POST リクエストのヘッダーとして push サービスに送信されます。
  3. push サービスは、pushManager.subscribe() から受け取った保存済み公開鍵を使用して、受信した情報が公開鍵に関連する秘密鍵で署名されていることを確認します。注意: 公開鍵は、サブスクライブ呼び出しに渡される applicationServerKey です。
  4. 署名付き情報が有効な場合、push サービスは push メッセージをユーザーに送信します。

この情報の流れの例を以下に示します。(公開鍵と秘密鍵を示す左下の凡例に注意してください)。

メッセージの送信時にアプリケーション サーバーの秘密鍵がどのように使用されるかを示す図

リクエストのヘッダーに追加される「署名付き情報」は JSON ウェブトークンです。

JSON ウェブトークン

JSON ウェブトークン(または JWT)は、受信者が送信元を検証できるように、メッセージをサードパーティに送信する方法です。

サードパーティは、メッセージを受信すると、送信者の公開鍵を取得し、それを使用して JWT の署名を検証する必要があります。署名が有効な場合、JWT は一致する秘密鍵で署名されているため、想定される送信者のものである必要があります。

https://jwt.io/ には、ユーザーの代わりに署名を実行できるライブラリが多数あります。可能であれば署名を行うことをおすすめします。完全性を期すために、署名付き JWT を手動で作成する方法を見てみましょう。

ウェブ push JWT と署名付き JWT

署名付き JWT は単なる文字列ですが、ドットで結合された 3 つの文字列と考えることができます。

JSON Web Token の文字列のイラスト

1 番目と 2 番目の文字列(JWT 情報と JWT データ)は、base64 でエンコードされた JSON であり、一般公開されています。

最初の文字列は JWT 自体に関する情報で、署名の作成に使用されたアルゴリズムを示します。

ウェブプッシュ用の JWT 情報には、次の情報が含まれている必要があります。

{
  "typ": "JWT",
  "alg": "ES256"
}

2 番目の文字列は JWT データです。これにより、JWT の送信者、送信先、有効期間に関する情報が得られます。

ウェブプッシュの場合、データの形式は次のようになります。

{
  "aud": "https://some-push-service.org",
  "exp": "1469618703",
  "sub": "mailto:example@web-push-book.org"
}

aud 値は「オーディエンス」(JWT の対象読者)です。ウェブ push の場合、対象は push サービスであるため、push サービスの送信元に設定します。

exp 値は JWT の有効期限です。これにより、スヌーパーが JWT をインターセプトした場合、その JWT を再利用できなくなります。有効期限は秒単位のタイムスタンプで、24 時間を超えないようにする必要があります。

Node.js では、有効期限は次のように設定されます。

Math.floor(Date.now() / 1000) + 12 * 60 * 60;

送信元アプリケーションと push サービスのクロックの違いによる問題を回避するため、24 時間ではなく 12 時間に設定します。

最後に、sub 値は URL または mailto メールアドレスにする必要があります。これは、push サービスが送信者に連絡する必要がある場合に、JWT から連絡先情報を検索できるようにするためです。(これが、web-push ライブラリにメールアドレスが必要な理由です)。

JWT 情報と同様に、JWT データは URL セーフの Base64 文字列としてエンコードされます。

3 番目の文字列である署名は、最初の 2 つの文字列(JWT 情報と JWT データ)を取得し、ドット文字(ここでは「署名なしトークン」と呼びます)で結合して署名した結果です。

署名プロセスでは、ES256 を使用して「署名なしトークン」を暗号化する必要があります。JWT の仕様によると、ES256 は「P-256 曲線と SHA-256 ハッシュ アルゴリズムを使用した ECDSA」の略です。ウェブ暗号を使用すると、次のように署名を作成できます。

// Utility function for UTF-8 encoding a string to an ArrayBuffer.
const utf8Encoder = new TextEncoder('utf-8');

// The unsigned token is the concatenation of the URL-safe base64 encoded
// header and body.
const unsignedToken = .....;

// Sign the |unsignedToken| using ES256 (SHA-256 over ECDSA).
const key = {
  kty: 'EC',
  crv: 'P-256',
  x: window.uint8ArrayToBase64Url(
    applicationServerKeys.publicKey.subarray(1, 33)),
  y: window.uint8ArrayToBase64Url(
    applicationServerKeys.publicKey.subarray(33, 65)),
  d: window.uint8ArrayToBase64Url(applicationServerKeys.privateKey),
};

// Sign the |unsignedToken| with the server's private key to generate
// the signature.
return crypto.subtle.importKey('jwk', key, {
  name: 'ECDSA', namedCurve: 'P-256',
}, true, ['sign'])
.then((key) => {
  return crypto.subtle.sign({
    name: 'ECDSA',
    hash: {
      name: 'SHA-256',
    },
  }, key, utf8Encoder.encode(unsignedToken));
})
.then((signature) => {
  console.log('Signature: ', signature);
});

push サービスは、公開アプリケーション サーバー鍵を使用して JWT を検証し、署名を復号し、復号された文字列が「署名なしトークン」(JWT の最初の 2 つの文字列)と同じであることを確認できます。

署名付き JWT(ドットで結合された 3 つの文字列すべて)は、次のように WebPush が付加された Authorization ヘッダーとしてウェブ push サービスに送信されます。

Authorization: 'WebPush [JWT Info].[JWT Data].[Signature]';

ウェブプッシュ プロトコルには、公開アプリケーション サーバー鍵を URL セーフの Base64 エンコード文字列として Crypto-Key ヘッダーで送信し、先頭に p256ecdsa= を付加しなければならないことも明記されています。

Crypto-Key: p256ecdsa=[URL Safe Base64 Public Application Server Key]

ペイロードの暗号化

次に、ウェブアプリが push メッセージを受信したときに受信したデータにアクセスできるように、push メッセージでペイロードを送信する方法を見てみましょう。

他のプッシュ サービスを使用したことのある方からよく寄せられる質問として、ウェブプッシュ ペイロードを暗号化する必要があるのはなぜでしょうか。ネイティブ アプリの場合、push メッセージは書式なしテキストとしてデータを送信できます。

ウェブプッシュの利点の一つは、すべてのプッシュ サービスが同じ API(ウェブプッシュ プロトコル)を使用するため、デベロッパーは push サービスが誰であるかを考慮する必要がないことです。適切な形式でリクエストを行い、プッシュ メッセージが送信されることを期待できます。この方法の欠点は、デベロッパーが信頼できない push サービスにメッセージを送信する可能性があることです。ペイロードを暗号化すると、push サービスは送信されたデータを読み取ることができません。ブラウザだけが情報を復号できます。これにより、ユーザーのデータが保護されます。

ペイロードの暗号化は、Message Encryption の仕様で定義されています。

push メッセージ ペイロードを暗号化する具体的な手順を確認する前に、暗号化プロセスで使用されるいくつかの手法について説明します。(プッシュ暗号化に関する優れた記事を Mat Scales に紹介しています)。

ECDH と HKDF

ECDH と HKDF はともに暗号化プロセス全体で使用され、情報を暗号化する目的においてメリットがあります。

ECDH: 楕円曲線 Diffie-Hellman 鍵交換

アリスとボブという 2 人が情報を共有したいとします。 Alice と Bob は、それぞれ独自の公開鍵と秘密鍵を持っています。Alice と Bob は公開鍵を共有しています。

ECDH で生成された鍵の有用な特性は、Alice が自分の秘密鍵と Bob の公開鍵を使用してシークレット値「X」を作成できることです。Bob も同様に、秘密鍵と Alice の公開鍵を使用して同じ値「X」を独立して作成します。これにより「X」は共有シークレットとなり、Alice と Bob は公開鍵を共有するだけで済みます。これで、Bob と Alice は「X」を使用して、両者間のメッセージの暗号化と復号を行えるようになりました。

ECDH は、私の知る限りでは、共有シークレット「X」を作成するこの「機能」を可能にする曲線の特性を定義しています。

こちらは ECDH の概要をまとめたものです。詳しくは、こちらの動画をご覧ください

コードの面では、ほとんどの言語 / プラットフォームには、これらのキーを簡単に生成するためのライブラリが付属しています。

ノードでは、次のようにします。

const keyCurve = crypto.createECDH('prime256v1');
keyCurve.generateKeys();

const publicKey = keyCurve.getPublicKey();
const privateKey = keyCurve.getPrivateKey();

HKDF: HMAC ベースの鍵導出関数

ウィキペディアに HKDF の簡潔な説明があります。

HKDF は HMAC ベースの鍵導出関数であり、脆弱な鍵マテリアルを暗号的に強力な鍵マテリアルに変換します。たとえば、Diffie Hellman が交換した共有シークレットを、暗号化、整合性チェック、認証で使用するのに適した鍵マテリアルに変換するために使用できます。

基本的に、HKDF は安全性が特に高くない入力を受け取り、安全性を高めます。

この暗号化を定義する仕様では、ハッシュ アルゴリズムとして SHA-256 を使用する必要があり、ウェブプッシュで生成される HKDF の鍵は 256 ビット(32 バイト)以下にする必要があります。

ノードでは、次のように実装できます。

// Simplified HKDF, returning keys up to 32 bytes long
function hkdf(salt, ikm, info, length) {
  // Extract
  const keyHmac = crypto.createHmac('sha256', salt);
  keyHmac.update(ikm);
  const key = keyHmac.digest();

  // Expand
  const infoHmac = crypto.createHmac('sha256', key);
  infoHmac.update(info);

  // A one byte long buffer containing only 0x01
  const ONE_BUFFER = new Buffer(1).fill(1);
  infoHmac.update(ONE_BUFFER);

  return infoHmac.digest().slice(0, length);
}

Mat Scale のこのサンプルコードに関する記事をご覧ください。

これは ECDHHKDF を大まかにカバーしています。

ECDH は、公開鍵を共有し、共有シークレットを生成する安全な方法。HKDF は 安全でない素材を 保護する方法です

これはペイロードの暗号化時に使用されます。次に 入力として何を受け取り その暗号化をどう行うかを見てみましょう

入力

ペイロードを使用してプッシュ メッセージをユーザーに送信する場合、次の 3 つの入力が必要です。

  1. ペイロード自体。
  2. PushSubscription からの auth Secret。
  3. PushSubscriptionp256dh キー。

authp256dh の値が PushSubscription から取得される例を見てきましたが、簡単に説明すると、定期購入の場合は以下の値が必要になります。

subscription.toJSON().keys.auth;
subscription.toJSON().keys.p256dh;

subscription.getKey('auth');
subscription.getKey('p256dh');

auth 値はシークレットとして扱い、アプリケーションの外部で共有されないようにする必要があります。

p256dh 鍵は公開鍵で、クライアント公開鍵と呼ばれることもあります。ここでは、p256dh をサブスクリプションの公開鍵と呼びます。定期購入の公開鍵はブラウザによって生成されます。ブラウザは秘密鍵を秘密にし、ペイロードの復号に使用します。

これら authp256dhpayload の 3 つの値は入力として必要です。暗号化処理の結果は、暗号化されたペイロード、ソルト値、データの暗号化のためだけに使用される公開鍵になります。

ソルト

ソルトには 16 バイトのランダムデータが必要です。NodeJS では、次の手順でソルトを作成します。

const salt = crypto.randomBytes(16);

公開鍵 / 秘密鍵

公開鍵と秘密鍵は、P-256 楕円曲線を使用して生成する必要があります。これは Node で次のように行います。

const localKeysCurve = crypto.createECDH('prime256v1');
localKeysCurve.generateKeys();

const localPublicKey = localKeysCurve.getPublicKey();
const localPrivateKey = localKeysCurve.getPrivateKey();

これらのキーを「ローカルキー」と呼びます。これらは暗号化のためだけに使用され、アプリケーション サーバー鍵とは関係ありません。

ペイロード、認証シークレット、サブスクリプションの公開鍵を入力として使用し、新しく生成されたソルトとローカル鍵のセットを使用して、実際に暗号化を行う準備が整います。

共有シークレット

最初のステップは、サブスクリプションの公開鍵と新しい秘密鍵を使用して共有シークレットを作成することです(Alice と Bob による ECDH の説明を覚えていますか?それと同じだ)。

const sharedSecret = localKeysCurve.computeSecret(
  subscription.keys.p256dh,
  'base64',
);

これは、次のステップで疑似ランダム鍵(PRK)を計算するために使用されます。

擬似ランダム鍵

疑似ランダム鍵(PRK)は、push サブスクリプションの認証シークレットと、先ほど作成した共有シークレットを組み合わせたものです。

const authEncBuff = new Buffer('Content-Encoding: auth\0', 'utf8');
const prk = hkdf(subscription.keys.auth, sharedSecret, authEncBuff, 32);

Content-Encoding: auth\0 文字列は何のためのものですか。つまり、ブラウザは受信メッセージを復号し、想定されるコンテンツ エンコードを探すことはできますが、明確な目的はありません。\0 は、値が 0 のバイトをバッファの最後に追加します。これは、ブラウザがメッセージを復号する場合に想定されます。つまり、コンテンツのエンコード用に大量のバイト、値 0 のバイト、暗号化されたデータの続きが想定されます。

Google の擬似ランダム鍵は、HKDF を介して認証、共有シークレット、エンコード情報を実行する(つまり、暗号的にを強化する)だけです。

背景情報

「コンテキスト」とは、後で暗号化ブラウザで 2 つの値を計算するために使用されるバイトのセットです。基本的には、サブスクリプションの公開鍵とローカルの公開鍵を含むバイトの配列です。

const keyLabel = new Buffer('P-256\0', 'utf8');

// Convert subscription public key into a buffer.
const subscriptionPubKey = new Buffer(subscription.keys.p256dh, 'base64');

const subscriptionPubKeyLength = new Uint8Array(2);
subscriptionPubKeyLength[0] = 0;
subscriptionPubKeyLength[1] = subscriptionPubKey.length;

const localPublicKeyLength = new Uint8Array(2);
subscriptionPubKeyLength[0] = 0;
subscriptionPubKeyLength[1] = localPublicKey.length;

const contextBuffer = Buffer.concat([
  keyLabel,
  subscriptionPubKeyLength.buffer,
  subscriptionPubKey,
  localPublicKeyLength.buffer,
  localPublicKey,
]);

最後のコンテキスト バッファは、ラベル、サブスクリプション公開鍵のバイト数、キー自体、ローカル公開鍵のバイト数、キー自体と続きます。

このコンテキスト値を使用して、ノンスとコンテンツ暗号鍵(CEK)を作成できます。

コンテンツ暗号鍵とノンス

ノンスは、1 回だけ使用する必要があるため、リプレイ攻撃を防ぐ値です。

コンテンツ暗号鍵(CEK)は、最終的にペイロードの暗号化に使用される鍵です。

まず、ノンスと CEK のデータのバイトを作成する必要があります。これは、単純にコンテンツ エンコード文字列の後に計算したコンテキスト バッファが続くものです。

const nonceEncBuffer = new Buffer('Content-Encoding: nonce\0', 'utf8');
const nonceInfo = Buffer.concat([nonceEncBuffer, contextBuffer]);

const cekEncBuffer = new Buffer('Content-Encoding: aesgcm\0');
const cekInfo = Buffer.concat([cekEncBuffer, contextBuffer]);

この情報は、ソルトおよび PRK を nonceInfo および cekInfo と組み合わせて HKDF を通じて実行されます。

// The nonce should be 12 bytes long
const nonce = hkdf(salt, prk, nonceInfo, 12);

// The CEK should be 16 bytes long
const contentEncryptionKey = hkdf(salt, prk, cekInfo, 16);

これにより、ノンスとコンテンツ暗号鍵を取得できます。

暗号化を実行する

コンテンツ暗号鍵が用意できたので、ペイロードを暗号化できます。

コンテンツ暗号鍵を鍵として使用して AES128 暗号を作成します。ノンスは初期化ベクトルです。

Node では次のようになります。

const cipher = crypto.createCipheriv(
  'id-aes128-GCM',
  contentEncryptionKey,
  nonce,
);

ペイロードを暗号化する前に、ペイロードの前に追加するパディングの量を定義する必要があります。パディングを追加するのは、盗聴者がペイロード サイズに基づいてメッセージの「タイプ」を判断できなくなるリスクを回避するためです。

2 バイトのパディングを追加して、追加するパディングの長さを示す必要があります。

たとえば、パディングを追加しないと、値が 0 の 2 バイト(パディングが存在しない)になるため、この 2 バイトの後にペイロードが読み取られます。5 バイトのパディングを追加すると、最初の 2 バイトの値は 5 になるため、コンシューマーはさらに 5 バイトを読み取り、ペイロードの読み取りを開始します。

const padding = new Buffer(2 + paddingLength);
// The buffer must be only zeros, except the length
padding.fill(0);
padding.writeUInt16BE(paddingLength, 0);

次に、この暗号を使用してパディングとペイロードを実行します。

const result = cipher.update(Buffer.concat(padding, payload));
cipher.final();

// Append the auth tag to the result -
// https://nodejs.org/api/crypto.html#crypto_cipher_getauthtag
const encryptedPayload = Buffer.concat([result, cipher.getAuthTag()]);

これで、暗号化されたペイロードが作成されました。正解です。

あとは、このペイロードを push サービスに送信する方法を決定するだけです。

暗号化されたペイロードのヘッダーと本文

この暗号化されたペイロードを push サービスに送信するには、POST リクエストでいくつかのヘッダーを定義する必要があります。

暗号化ヘッダー

「Encryption」ヘッダーには、ペイロードの暗号化に使用されるソルトが含まれている必要があります。

16 バイトのソルトは、次のように Base64 で URL セーフにエンコードし、暗号化ヘッダーに追加する必要があります。

Encryption: salt=[URL Safe Base64 Encoded Salt]

Crypto-Key ヘッダー

「Application Server Keys」セクションで、公開アプリケーション サーバー鍵を格納するために Crypto-Key ヘッダーが使用されていることがわかりました。

このヘッダーは、ペイロードの暗号化に使用されるローカル公開鍵の共有にも使用されます。

結果として得られるヘッダーは次のようになります。

Crypto-Key: dh=[URL Safe Base64 Encoded Local Public Key String]; p256ecdsa=[URL Safe Base64 Encoded Public Application Server Key]

コンテンツ タイプ、長さ、エンコード ヘッダー

Content-Length ヘッダーは、暗号化されたペイロードのバイト数です。「Content-Type」ヘッダーと「Content-Encoding」ヘッダーは固定値です。これを以下に示しています。

Content-Length: [Number of Bytes in Encrypted Payload]
Content-Type: 'application/octet-stream'
Content-Encoding: 'aesgcm'

これらのヘッダーを設定したら、暗号化されたペイロードをリクエストの本文として送信する必要があります。Content-Typeapplication/octet-stream に設定されていることに注意してください。これは、暗号化されたペイロードをバイト ストリームとして送信する必要があるためです。

NodeJS では、次のようにします。

const pushRequest = https.request(httpsOptions, function(pushResponse) {
pushRequest.write(encryptedPayload);
pushRequest.end();

ヘッダーの追加

JWT / アプリケーション サーバーキーに使用されるヘッダー(push サービスでアプリケーションを識別する方法)と、暗号化されたペイロードの送信に使用されるヘッダーについて説明しました。

push サービスが送信メッセージの動作を変更するために使用する追加のヘッダーがあります。これらのヘッダーには、必須のものと任意のものがあります。

TTL ヘッダー

必須

TTL(有効期間)は、プッシュ メッセージを配信する前に push サービスで公開する秒数を指定する整数です。TTL が期限切れになると、メッセージは push サービス キューから削除され、配信されなくなります。

TTL: [Time to live in seconds]

TTL を 0 に設定すると、push サービスはすぐにメッセージの配信を試みますが、デバイスに到達できない場合、メッセージはすぐに push サービス キューから削除されます。

技術的には、push サービスは必要に応じて push メッセージの TTL を削減できます。これが発生したかどうかは、push サービスからのレスポンスの TTL ヘッダーを調べると確認できます。

トピック

任意

トピックは、トピック名が一致する場合に、保留中のメッセージを新しいメッセージに置き換えるために使用できる文字列です。

これは、デバイスがオフラインのときに複数のメッセージが送信され、デバイスの電源が入っているときにのみユーザーに最新のメッセージのみを表示させる場合に便利です。

緊急性

任意

緊急度は、ユーザーに対するメッセージの重要性を push サービスに示します。これをプッシュ サービスで使用すると、電池残量が少ないときにのみ重要なメッセージのためにスリープ状態から復帰し、ユーザーのデバイスの電池寿命を節約できます。

ヘッダー値は、次のように定義されます。デフォルト値は normal です。

Urgency: [very-low | low | normal | high]

すべてを 1 つに統合

この仕組みについてさらに質問がある場合は、ライブラリが web-push-libs 組織で push メッセージをどのようにトリガーするかをいつでも確認できます。

暗号化されたペイロードと上記のヘッダーを作成したら、あとは PushSubscriptionendpoint に対して POST リクエストを行うだけです。

この POST リクエストに対するレスポンスをどのように処理すればよいでしょうか。

push サービスからのレスポンス

push サービスにリクエストを行ったら、レスポンスのステータス コードを確認して、リクエストが成功したかどうかを判断する必要があります。

Status Code 説明
201 作成済み。push メッセージの送信リクエストが受信され、承認されました。
429 リクエスト数が多すぎます。これは、アプリケーション サーバーが push サービスのレート制限に達したことを意味します。push サービスには、別のリクエストを実行できるまでの時間を示す「Retry-After」ヘッダーを含める必要があります。
400 無効なリクエストです。通常、ヘッダーのいずれかが無効であるか、形式が正しくありません。
404 見つかりません。これは、定期購入が期限切れで使用できないことを示します。この場合は、「PushSubscription」を削除し、クライアントがユーザーを再登録するまで待つ必要があります。
410 消えた。サブスクリプションが有効でなくなったため、アプリケーション サーバーから削除する必要があります。これは「PushSubscription」で「unsubscribe()」を呼び出すことで再現できます。
413 ペイロード サイズが大きすぎます。push サービスがサポートする必要がある最小サイズのペイロードは、4,096 バイト(4 KB)です。

次のステップ

Codelab