Skip to main content

Message Encryption for Web Push

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 8291.
Author Martin Thomson
Last updated 2017-08-17 (Latest revision 2017-02-13)
Replaces draft-thomson-webpush-encryption
RFC stream Internet Engineering Task Force (IETF)
Additional resources Mailing list discussion
Stream WG state Submitted to IESG for Publication
Other - see Comment Log
Document shepherd Phil Sorber
Shepherd write-up Show Last changed 2017-06-15
IESG IESG state Became RFC 8291 (Proposed Standard)
Consensus boilerplate Yes
Telechat date (None)
Responsible AD Adam Roach
Send notices to Phil Sorber <>
IANA IANA review state IANA OK - No Actions Needed
Network Working Group                                         M. Thomson
Internet-Draft                                                   Mozilla
Intended status: Standards Track                       February 14, 2017
Expires: August 18, 2017

                    Message Encryption for Web Push


   A message encryption scheme is described for the Web Push protocol.
   This scheme provides confidentiality and integrity for messages sent
   from an Application Server to a User Agent.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on August 18, 2017.

Copyright Notice

   Copyright (c) 2017 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   ( in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Thomson                  Expires August 18, 2017                [Page 1]
Internet-Draft             Web Push Encryption             February 2017

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   3
   2.  Push Message Encryption Overview  . . . . . . . . . . . . . .   3
     2.1.  Key and Secret Distribution . . . . . . . . . . . . . . .   3
   3.  Push Message Encryption . . . . . . . . . . . . . . . . . . .   4
     3.1.  Diffie-Hellman Key Agreement  . . . . . . . . . . . . . .   4
     3.2.  Push Message Authentication . . . . . . . . . . . . . . .   5
     3.3.  Combining Shared and Authentication Secrets . . . . . . .   5
     3.4.  Encryption Summary  . . . . . . . . . . . . . . . . . . .   5
   4.  Restrictions on Use of "aes128gcm" Content Coding . . . . . .   6
   5.  Push Message Encryption Example . . . . . . . . . . . . . . .   7
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .   8
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .   8
     8.2.  Informative References  . . . . . . . . . . . . . . . . .   9
   Appendix A.  Intermediate Values for Encryption . . . . . . . . .   9
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  11

1.  Introduction

   The Web Push protocol [I-D.ietf-webpush-protocol] is an intermediated
   protocol by necessity.  Messages from an Application Server are
   delivered to a User Agent via a Push Service.

    +-------+           +--------------+       +-------------+
    |  UA   |           | Push Service |       | Application |
    +-------+           +--------------+       +-------------+
        |                      |                      |
        |        Setup         |                      |
        |<====================>|                      |
        |           Provide Subscription              |
        |                      |                      |
        :                      :                      :
        |                      |     Push Message     |
        |    Push Message      |<---------------------|
        |<---------------------|                      |
        |                      |                      |

   This document describes how messages sent using this protocol can be
   secured against inspection, modification and falsification by a Push

   Web Push messages are the payload of an HTTP message [RFC7230].
   These messages are encrypted using an encrypted content encoding

Thomson                  Expires August 18, 2017                [Page 2]
Internet-Draft             Web Push Encryption             February 2017

   [I-D.ietf-httpbis-encryption-encoding].  This document describes how
   this content encoding is applied and describes a recommended key
   management scheme.

   For efficiency reasons, multiple users of Web Push often share a
   central agent that aggregates push functionality.  This agent can
   enforce the use of this encryption scheme by applications that use
   push messaging.  An agent that only delivers messages that are
   properly encrypted strongly encourages the end-to-end protection of

   A web browser that implements the Web Push API [API] can enforce the
   use of encryption by forwarding only those messages that were
   properly encrypted.

1.1.  Notational Conventions

   The words "MUST", "MUST NOT", "SHOULD", and "MAY" are used in this
   document.  It's not shouting, when they are capitalized, they have
   the special meaning described in [RFC2119].

2.  Push Message Encryption Overview

   Encrypting a push message uses elliptic-curve Diffie-Hellman (ECDH)
   [ECDH] on the P-256 curve [FIPS186] to establish a shared secret (see
   Section 3.1) and a symmetric secret for authentication (see
   Section 3.2).

   A User Agent generates an ECDH key pair and authentication secret
   that it associates with each subscription it creates.  The ECDH
   public key and the authentication secret are sent to the Application
   Server with other details of the push subscription.

   When sending a message, an Application Server generates an ECDH key
   pair and a random salt.  The ECDH public key is encoded into the "dh"
   parameter of the Crypto-Key header field; the salt is encoded into
   message payload.  The ECDH key pair can be discarded after encrypting
   the message.

   The content of the push message is encrypted or decrypted using a
   content encryption key and nonce that is derived using all of these
   inputs and the process described in Section 3.

2.1.  Key and Secret Distribution

   The application using the subscription distributes the subscription
   public key and authentication secret to an authorized Application
   Server.  This could be sent along with other subscription information

Thomson                  Expires August 18, 2017                [Page 3]
Internet-Draft             Web Push Encryption             February 2017

   that is provided by the User Agent, such as the push subscription

   An application MUST use an authenticated, confidentiality protected
   communications medium for this purpose.  In addition to the reasons
   described in [I-D.ietf-webpush-protocol], this ensures that the
   authentication secret is not revealed to unauthorized entities, which
   can be used to generate push messages that will be accepted by the
   User Agent.

   Most applications that use push messaging have a pre-existing
   relationship with an Application Server.  Any existing communication
   mechanism that is authenticated and provides confidentiality and
   integrity, such as HTTPS [RFC2818], is sufficient.

3.  Push Message Encryption

   Push message encryption happens in four phases:

   o  A shared secret is derived using elliptic-curve Diffie-Hellman
      [ECDH] (Section 3.1).

   o  The shared secret is then combined with the application secret to
      produce the input keying material used in
      [I-D.ietf-httpbis-encryption-encoding] (Section 3.3).

   o  A content encryption key and nonce are derived using the process
      in [I-D.ietf-httpbis-encryption-encoding].

   o  Encryption or decryption follows according to

   The key derivation process is summarized in Section 3.4.
   Restrictions on the use of the encrypted content coding are described
   in Section 4.

3.1.  Diffie-Hellman Key Agreement

   For each new subscription that the User Agent generates for an
   Application, it also generates a P-256 [FIPS186] key pair for use in
   elliptic-curve Diffie-Hellman (ECDH) [ECDH].

   When sending a push message, the Application Server also generates a
   new ECDH key pair on the same P-256 curve.

   The ECDH public key for the Application Server is included as the
   "keyid" parameter in the encrypted content coding header (see
   Section 2.1 of [I-D.ietf-httpbis-encryption-encoding].

Thomson                  Expires August 18, 2017                [Page 4]
Internet-Draft             Web Push Encryption             February 2017

   An Application combines its ECDH private key with the public key
   provided by the User Agent using the process described in [ECDH]; on
   receipt of the push message, a User Agent combines its private key
   with the public key provided by the Application Server in the "dh"
   parameter in the same way.  These operations produce the same value
   for the ECDH shared secret.

3.2.  Push Message Authentication

   To ensure that push messages are correctly authenticated, a symmetric
   authentication secret is added to the information generated by a User
   Agent.  The authentication secret is mixed into the key derivation
   process shown in Section 3.3.

   A User Agent MUST generate and provide a hard to guess sequence of 16
   octets that is used for authentication of push messages.  This SHOULD
   be generated by a cryptographically strong random number generator

3.3.  Combining Shared and Authentication Secrets

   The shared secret produced by ECDH is combined with the
   authentication secret using HMAC-based key derivation function (HKDF)
   described in [RFC5869].  This produces the input keying material used
   by [I-D.ietf-httpbis-encryption-encoding].

   The HKDF function uses SHA-256 hash algorithm [FIPS180-4] with the
   following inputs:

   salt:  the authentication secret

   IKM:  the shared secret derived using ECDH

   info:  the concatenation of the ASCII-encoded string "WebPush: info",
      a zero octet, the X9.62 encoding of the User Agent ECDH public
      key, and X9.62 encoding of the Application Server ECDH public key;
      that is

   key_info = "WebPush: info" || 0x00 || ua_public || as_public

   L: 32 octets (i.e., the output is the length of the underlying
      SHA-256 HMAC function output)

3.4.  Encryption Summary

   This results in a the final content encryption key and nonce
   generation using the following sequence, which is shown here in

Thomson                  Expires August 18, 2017                [Page 5]
Internet-Draft             Web Push Encryption             February 2017

   pseudocode with HKDF expanded into separate discrete steps using HMAC
   with SHA-256:

      -- For a User Agent:
      ecdh_secret = ECDH(ua_private, as_public)
      auth_secret = random(16)

      -- For an Application Server:
      ecdh_secret = ECDH(as_private, ua_public)
      auth_secret = <from User Agent>

      -- For both:
      PRK_key = HMAC-SHA-256(auth_secret, ecdh_secret)
      key_info = "WebPush: info" || 0x00 || ua_public || as_public
      IKM = HMAC-SHA-256(PRK_cek, key_info || 0x01)

      salt = random(16)
      PRK = HMAC-SHA-256(salt, IKM)
      cek_info = "Content-Encoding: aes128gcm" || 0x00
      CEK = HMAC-SHA-256(PRK, cek_info || 0x01)[0..15]
      nonce_info = "Content-Encoding: nonce" || 0x00
      NONCE = HMAC-SHA-256(PRK, nonce_info || 0x01)[0..11]

   Note that this omits the exclusive OR of the final nonce with the
   record sequence number, since push messages contain only a single
   record (see Section 4) and the sequence number of the first record is

4.  Restrictions on Use of "aes128gcm" Content Coding

   An Application Server MUST encrypt a push message with a single
   record.  This allows for a minimal receiver implementation that
   handles a single record.  An application server MUST set the "rs"
   parameter in the "aes128gcm" content coding header to a size that is
   greater than the some of the length of the plaintext, the padding
   delimiter (1 octet), any padding, and the authentication tag (16

   A push message MUST include the application server ECDH public key in
   the "keyid" parameter of the encrypted content coding header.  The
   uncompressed point form defined in [X9.62] (that is, a 65 octet
   sequence that starts with a 0x04 octet) forms the entirety of the

   A push service is not required to support more than 4096 octets of
   payload body (see Section 7.2 of [I-D.ietf-webpush-protocol]).
   Absent header (86 octets), padding (minimum 2 octets), and expansion

Thomson                  Expires August 18, 2017                [Page 6]
Internet-Draft             Web Push Encryption             February 2017

   for AEAD_AES_128_GCM (16 octets), this equates to at most 3992 octets
   of plaintext.

   An Application Server MUST NOT use other content encodings for push
   messages.  In particular, content encodings that compress could
   result in leaking of push message contents.  The Content-Encoding
   header field therefore has exactly one value, which is "aes128gcm".
   Multiple "aes128gcm" values are not permitted.

   A User Agent is not required to support multiple records.  A User
   Agent MAY ignore the "rs" field.  If a record size is unchecked,
   decryption will fail with high probability for all valid cases.  The
   padding delimiter octet MUST be checked, values other than 0x02 MUST
   cause the message to be discarded.

5.  Push Message Encryption Example

   The following example shows a push message being sent to a push

   POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1
   TTL: 10
   Content-Length: 145
   Content-Encoding: aes128gcm


   This example shows the ASCII encoded string, "When I grow up, I want
   to be a watermelon".  The content body is shown here with line
   wrapping and URL-safe base64url encoding to meet presentation

   The keys used are shown below using the uncompressed form [X9.62]
   encoded using base64url.

      Authentication Secret: BTBZMqHH6r4Tts7J_aSIgg
         private key: q1dXpw3UpT5VOmu_cf_v6ih07Aems3njxI-JWgLcM94
         public key: BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcx
         private key: yfWPiYE-n46HLnH0KqZOF1fJJU3MYrct3AELtAQ-oRw
         public key: <the value of the "dh" parameter>

   Intermediate values for this example are included in Appendix A.

Thomson                  Expires August 18, 2017                [Page 7]
Internet-Draft             Web Push Encryption             February 2017

6.  IANA Considerations

   [[RFC EDITOR: please remote this section before publication.]] This
   document makes no request of IANA.

7.  Security Considerations

   The security considerations of [I-D.ietf-httpbis-encryption-encoding]
   describe the limitations of the content encoding.  In particular, any
   HTTP header fields are not protected by the content encoding scheme.
   A User Agent MUST consider HTTP header fields to have come from the
   Push Service.  An application on the User Agent that uses information
   from header fields to alter their processing of a push message is
   exposed to a risk of attack by the Push Service.

   The timing and length of communication cannot be hidden from the Push
   Service.  While an outside observer might see individual messages
   intermixed with each other, the Push Service will see what
   Application Server is talking to which User Agent, and the
   subscription that is used.  Additionally, the length of messages
   could be revealed unless the padding provided by the content encoding
   scheme is used to obscure length.

8.  References

8.1.  Normative References

   [ECDH]     SECG, "Elliptic Curve Cryptography", SEC 1 , 2000,

              Department of Commerce, National., "NIST FIPS 180-4,
              Secure Hash Standard", March 2012,

   [FIPS186]  National Institute of Standards and Technology (NIST),
              "Digital Signature Standard (DSS)", NIST PUB 186-4 , July

              Thomson, M., "Encrypted Content-Encoding for HTTP", draft-
              ietf-httpbis-encryption-encoding-02 (work in progress),
              June 2016.

Thomson                  Expires August 18, 2017                [Page 8]
Internet-Draft             Web Push Encryption             February 2017

              Thomson, M., Damaggio, E., and B. Raymor, "Generic Event
              Delivery Using HTTP Push", draft-ietf-webpush-protocol-08
              (work in progress), July 2016.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,

   [RFC4086]  Eastlake 3rd, D., Schiller, J., and S. Crocker,
              "Randomness Requirements for Security", BCP 106, RFC 4086,
              DOI 10.17487/RFC4086, June 2005,

   [RFC5869]  Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
              Key Derivation Function (HKDF)", RFC 5869,
              DOI 10.17487/RFC5869, May 2010,

   [X9.62]    ANSI, "Public Key Cryptography For The Financial Services
              Industry: The Elliptic Curve Digital Signature Algorithm
              (ECDSA)", ANSI X9.62 , 1998.

8.2.  Informative References

   [API]      van Ouwerkerk, M. and M. Thomson, "Web Push API", 2015,

   [RFC2818]  Rescorla, E., "HTTP Over TLS", RFC 2818,
              DOI 10.17487/RFC2818, May 2000,

   [RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Message Syntax and Routing",
              RFC 7230, DOI 10.17487/RFC7230, June 2014,

Appendix A.  Intermediate Values for Encryption

   The intermediate values calculated for the example in Section 5 are
   shown here.  The following are inputs to the calculation:

   Plaintext:  V2hlbiBJIGdyb3cgdXAsIEkgd2FudCB0byBiZSBhIHdhdGVybWVsb24

   Application Server public key (as_public):

Thomson                  Expires August 18, 2017                [Page 9]
Internet-Draft             Web Push Encryption             February 2017

   Application Server private key (as_private):  yfWPiYE-n46HLnH0KqZOF1f

   User Agent public key (ua_public):  BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-
      JvLexhqUzORcx aOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4

   User Agent private key (ua_private):

   Salt:  DGv6ra1nlYgDCS1FRnbzlw

   Authentication secret (auth_secret):  BTBZMqHH6r4Tts7J_aSIgg

   Note that knowledge of just one of the private keys is necessary.
   The Application Server randomly generates the salt value, whereas
   salt is input to the receiver.

   This produces the following intermediate values:

   Shared ECDH secret (ecdh_secret):  kyrL1jIIOHEzg3sM2ZWRHDRB62YACZhhSl

   Pseudo-random key for key combining (PRK_key):

   Info for key combining (key_info):  V2ViUHVzaDogaW5mbwAEJXGyvs3942BVG
      q8e0PTNNmwR zr5VX4m8t7GGpTM5FzFo7OLr4BhZe9MEebhuPI-OztV3
      bZIHMtu5pZpTKGSCIA5Zent7wmC6HCJ5mFgJkuk5cwAv MBKiiujwa7t45ewP

   Input keying material for content encryption key derivation (IKM):

   PRK for content encryption (PRK):  09_eUZGrsvxChDCGRCdkLiDXrReGOEVeSC

   Info for content encryption key derivation (cek_info):

   Content encryption key (CEK):  oIhVW04MRdy2XN9CiKLxTg

   Info for content encryption nonce derivation (nonce_info):

   Nonce (NONCE):  4h_95klXJ5E_qnoN

   The salt, record size of 4096, and application server public key
   produce an 86 octet header of DGv6ra1nlYgDCS1FRnbzlwAAEABBBP4z

Thomson                  Expires August 18, 2017               [Page 10]
Internet-Draft             Web Push Encryption             February 2017

   9KsN6nGRTbVYI_c7VJSPQTBtkgcy27ml mlMoZIIgDll6e3vCYLocInmYWAmS6Tlz

   The push message plaintext has the padding delimiter octet (0x02)
   appended to produce V2hlbiBJIGdyb3cgdXAsIEkgd2FudCB0
   byBiZSBhIHdhdGVybWVsb24C.  The plaintext is then encrypted with AES-
   GCM, which emits ciphertext of 8pfeW0KbunFT06SuDKoJH9Ql87S1QUrd
   irN6GcG7sFz1y1sqLgVi1VhjVkHsUoEs bI_0LpXMuGvnzQ.

   The header and cipher text are concatenated and produce the result
   shown in Section 5.

Author's Address

   Martin Thomson


Thomson                  Expires August 18, 2017               [Page 11]