idnits 2.17.1 draft-ietf-webpush-vapid-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (December 22, 2016) is 2674 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS186' ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-09) exists of draft-ietf-webpush-encryption-06 Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Thomson 3 Internet-Draft Mozilla 4 Intended status: Standards Track P. Beverloo 5 Expires: June 25, 2017 Google 6 December 22, 2016 8 Voluntary Application Server Identification for Web Push 9 draft-ietf-webpush-vapid-02 11 Abstract 13 An application server can voluntarily identify itself to a push 14 service using the described technique. This identification 15 information can be used by the push service to attribute requests 16 that are made by the same application server to a single entity. 17 This can used to reduce the secrecy for push subscription URLs by 18 being able to restrict subscriptions to a specific application 19 server. An application server is further able to include additional 20 information that the operator of a push service can use to contact 21 the operator of the application server. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on June 25, 2017. 40 Copyright Notice 42 Copyright (c) 2016 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 1.1. Voluntary Identification . . . . . . . . . . . . . . . . 3 59 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 60 2. Application Server Self-Identification . . . . . . . . . . . 4 61 2.1. Application Server Contact Information . . . . . . . . . 4 62 2.2. Additional Claims . . . . . . . . . . . . . . . . . . . . 4 63 2.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3. Vapid Authentication Scheme . . . . . . . . . . . . . . . . . 6 65 3.1. Token Parameter (t) . . . . . . . . . . . . . . . . . . . 6 66 3.2. Public Key Parameter (k) . . . . . . . . . . . . . . . . 6 67 4. Subscription Restriction . . . . . . . . . . . . . . . . . . 7 68 4.1. Creating a Restricted Push Subscription . . . . . . . . . 7 69 4.2. Using Restricted Subscriptions . . . . . . . . . . . . . 8 70 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 71 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 72 6.1. Vapid Authentication Scheme Parameters . . . . . . . . . 9 73 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 74 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 75 8.1. Normative References . . . . . . . . . . . . . . . . . . 10 76 8.2. Informative References . . . . . . . . . . . . . . . . . 11 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 79 1. Introduction 81 The Web Push protocol [I-D.ietf-webpush-protocol] describes how an 82 application server is able to request that a push service deliver a 83 push message to a user agent. 85 As a consequence of the expected deployment architecture, there is no 86 basis for an application server to be known to a push service prior 87 to requesting delivery of a push message. Requiring that the push 88 service be able to authenticate application servers places an 89 unwanted constraint on the interactions between user agents and 90 application servers, who are the ultimate users of a push service. 91 That constraint would also degrade the privacy-preserving properties 92 the protocol provides. For these reasons, 93 [I-D.ietf-webpush-protocol] does not define a mandatory system for 94 authentication of application servers. 96 An unfortunate consequence of this design is that a push service is 97 exposed to a greater risk of denial of service attack. While 98 requests from application servers can be indirectly attributed to 99 user agents, this is not always efficient or even sufficient. 100 Providing more information about the application server directly to a 101 push service allows the push service to better distinguish between 102 legitimate and bogus requests. 104 Additionally, this design also relies on endpoint secrecy as any 105 application server in possession of the endpoint is able to send 106 messages, albeit without payloads. In situations where usage of a 107 subscription can be limited to a single application server, the 108 ability to associate a subscription with the application server could 109 reduce the impact of a data leak. 111 1.1. Voluntary Identification 113 This document describes a system whereby an application server can 114 volunteer information about itself to a push service. At a minimum, 115 this provides a stable identity for the application server, though 116 this could also include contact information, such as an email 117 address. 119 A consistent identity can be used by a push service to establish 120 behavioral expectations for an application server. Significant 121 deviations from an established norm can then be used to trigger 122 exception handling procedures. 124 Voluntarily-provided contact information can be used to contact an 125 application server operator in the case of exceptional situations. 127 Experience with push service deployment has shown that software 128 errors or unusual circumstances can cause large increases in push 129 message volume. Contacting the operator of the application server 130 has proven to be valuable. 132 Even in the absence of usable contact information, an application 133 server that has a well-established reputation might be given 134 preference over an unidentified application server when choosing 135 whether to discard a push message. 137 1.2. Notational Conventions 139 The words "MUST", "MUST NOT", "SHOULD", and "MAY" are used in this 140 document. It's not shouting, when they are capitalized, they have 141 the special meaning described in [RFC2119]. 143 The terms "push message", "push service", "push subscription", 144 "application server", and "user agent" are used as defined in 145 [I-D.ietf-webpush-protocol]. 147 2. Application Server Self-Identification 149 Application servers that wish to self-identify generate and maintain 150 a signing key pair. This key pair MUST be usable with elliptic curve 151 digital signature (ECDSA) over the P-256 curve [FIPS186]. Use of 152 this key when sending push messages establishes an identity for the 153 application server that is consistent across multiple messages. 155 When requesting delivery of a push message, the application includes 156 a JSON Web Token (JWT) [RFC7519], signed using its signing key. The 157 token includes a number of claims as follows: 159 o An "aud" (Audience) claim in the token MUST include the unicode 160 serialization of the origin (Section 6.1 of [RFC6454]) of the push 161 resource URL. This binds the token to a specific push service. 162 This ensures that the token is reusable for all push resource URLs 163 that share the same origin. 165 o An "exp" (Expiry) claim MUST be included with the time after which 166 the token expires. This limits the time that a token over which a 167 token is valid. An "exp" claim MUST NOT be more than 24 hours 168 from the time of the request. 170 This JWT is included in an Authorization header field, using an auth- 171 scheme of "vapid". A push service MAY reject a request with a 403 172 (Forbidden) status code [RFC7235] if the JWT signature or its claims 173 are invalid. 175 The JWT MUST use a JSON Web Signature (JWS) [RFC7515]. The signature 176 MUST use ECDSA on the NIST P-256 curve [FIPS186] which is identified 177 as "ES256" [RFC7518]. 179 2.1. Application Server Contact Information 181 If the application server wishes to provide contact details it MAY 182 include a "sub" (Subject) claim in the JWT. The "sub" claim SHOULD 183 include a contact URI for the application server as either a 184 "mailto:" (email) [RFC6068] or an "https:" [RFC2818] URI. 186 2.2. Additional Claims 188 An application server MAY include additional claims using public or 189 private names (see Sections 4.2 and 4.3 of [RFC7519]). Since the JWT 190 is in a header field, the size of additional claims SHOULD be kept as 191 small as possible. 193 2.3. Example 195 An application server requests the delivery of a push message as 196 described in [I-D.ietf-webpush-protocol]. If the application server 197 wishes to self-identify, it includes an Authorization header field 198 with credentials that use the "vapid" authentication scheme 199 (Section 3). 201 POST /p/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1 202 Host: push.example.net 203 TTL: 30 204 Content-Length: 136 205 Content-Encoding: aes128gcm 206 Authorization: vapid 207 t=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJhdWQiOiJodHRwczovL3 208 B1c2guZXhhbXBsZS5uZXQiLCJleHAiOjE0NTM1MjM3NjgsInN1YiI6Im1ha 209 Wx0bzpwdXNoQGV4YW1wbGUuY29tIn0.i3CYb7t4xfxCDquptFOepC9GAu_H 210 LGkMlMuCGSK2rpiUfnK9ojFwDXb1JrErtmysazNjjvW2L9OkSSHzvoD1oA, 211 k=BA1Hxzyi1RUM1b5wjxsn7nGxAszw2u61m164i3MrAIxHF6YK5h4SDYic-dR 212 uU_RCPCfA5aq9ojSwk5Y2EmClBPs 214 { encrypted push message } 216 Figure 1: Requesting Push Message Delivery with JWT 218 Note that the example header fields in this document include extra 219 line wrapping to meet formatting constraints. 221 The "t" parameter of the Authorization header field contains a JWT; 222 the "k" parameter includes the base64url-encoded key that signed that 223 token. The JWT input values and the JWK [RFC7517] corresponding to 224 the signing key are shown in Figure 2 with additional whitespace 225 added for readability purposes. This JWT would be valid until 226 2016-01-21T01:53:25Z [RFC3339]. 228 JWT header = { "typ": "JWT", "alg": "ES256" } 229 JWT body = { "aud": "https://push.example.net", 230 "exp": 1453341205, 231 "sub": "mailto:push@example.com" } 232 JWK = { "crv":"P-256", 233 "kty":"EC", 234 "x":"DUfHPKLVFQzVvnCPGyfucbECzPDa7rWbXriLcysAjEc", 235 "y":"F6YK5h4SDYic-dRuU_RCPCfA5aq9ojSwk5Y2EmClBPs" } 237 Figure 2: Decoded Example Values 239 3. Vapid Authentication Scheme 241 A new "vapid" HTTP authentication scheme [RFC7235] is defined. This 242 authentication scheme carries a signed JWT, as described in 243 Section 2, plus the key that signed that JWT. 245 This authentication scheme is for origin-server authentication only. 246 Therefore, this authentication scheme MUST NOT be used with the 247 Proxy-Authenticate or Proxy-Authorization header fields. 249 This authentication scheme does not require a challenge. Clients are 250 able to generate the Authorization header field without any 251 additional information from a server. Therefore, a challenge for 252 this authentication scheme MUST NOT be sent in a WWW-Authenticate 253 header field. 255 Two parameters are defined for this authentication scheme: "t" and 256 "k". All unknown or unsupported parameters to "vapid" authentication 257 credentials MUST be ignored. The "realm" parameter is ignored for 258 this authentication scheme. 260 This authentication scheme is intended for use by an application 261 server when using the Web Push protocol [I-D.ietf-webpush-protocol], 262 but it could be used in other contexts if applicable. 264 3.1. Token Parameter (t) 266 The "t" parameter of the "vapid" authentication scheme carries a JWT 267 as described in Section 2. 269 3.2. Public Key Parameter (k) 271 In order for the push service to be able to validate the JWT, it 272 needs to learn the public key of the application server. A "k" 273 parameter is defined for the "vapid" authentication scheme to carry 274 this information. 276 The "k" parameter includes an elliptic curve digital signature 277 algorithm (ECDSA) public key [FIPS186] in uncompressed form [X9.62] 278 that is encoded using base64url encoding [RFC7515]. 280 Note: X9.62 encoding is used over JWK [RFC7517] for two reasons. A 281 JWK does not have a canonical form, so X9.62 encoding makes it 282 easier for the push service to handle comparison of keys from 283 different sources. Secondarily, the X9.62 encoding is also 284 considerably smaller. 286 Some implementations permit the same P-256 key to be used for signing 287 and key exchange. An application server MUST select a different 288 private key for the key exchange [I-D.ietf-webpush-encryption] and 289 signing the authentication token. Though a push service is not 290 obligated to check either parameter for every push message, a push 291 service SHOULD reject push messages that have identical values for 292 these parameters with a 400 (Bad Request) status code. 294 4. Subscription Restriction 296 The public key of the application server serves as a stable 297 identifier for the server. This key can be used to restrict a push 298 subscription to a specific application server. 300 Subscription restriction reduces the reliance on endpoint secrecy by 301 requiring proof of possession to be demonstrated by an application 302 server when requesting delivery of a push message. This provides an 303 additional level of protection against leaking of the details of the 304 push subscription. 306 4.1. Creating a Restricted Push Subscription 308 The user agent includes the public key of the application server when 309 requesting the creation of a push subscription. This restricts use 310 of the resulting subscription to application servers that are able to 311 provide proof of possession for the corresponding private key. 313 The public key is then added to the request to create a push 314 subscription. The push subscription request is extended to include a 315 body. The body of the request is a JSON object as described in 316 [RFC7159]. A "vapid" member is added to this JSON object, containing 317 the public key on the P-256 curve, encoded in the uncompressed form 318 [X9.62] and base64url encoded [RFC7515]. The MIME media type of the 319 body is set to "application/json". 321 The example in Figure 3 shows a restriction to the key used in 322 Figure 1. Extra whitespace is added to to meet formatting 323 constraints. 325 POST /subscribe/ HTTP/1.1 326 Host: push.example.net 327 Content-Type: application/json;charset=utf-8 328 Content-Length: 104 330 { "vapid": "BA1Hxzyi1RUM1b5wjxsn7nGxAszw2u61m164i3MrAIxH 331 F6YK5h4SDYic-dRuU_RCPCfA5aq9ojSwk5Y2EmClBPs" } 333 Figure 3: Example Subscribe Request 335 An application might use the Web Push API [API] to provide the user 336 agent with a public key. 338 4.2. Using Restricted Subscriptions 340 When a push subscription has been associated with an application 341 server, the request for push message delivery MUST include proof of 342 possession for the associated private key that was used when creating 343 the push subscription. 345 A push service MUST reject a message that omits mandatory credentials 346 with a 401 (Unauthorized) status code. A push service MAY reject a 347 message that includes invalid credentials with a 403 (Forbidden) 348 status code. Credentials are invalid if: 350 o either the authentication token or public key are not included in 351 the request, 353 o the signature on the JWT cannot be successfully verified using the 354 included public key, 356 o the current time is later than the time identified in the "exp" 357 (Expiry) claim or more than 24 hours before the expiry time, 359 o the origin of the push resource is not included in the "aud" 360 (Audience) claim, or 362 o the public key used to sign the JWT doesn't match the one that was 363 included in the creation of the push subscription. 365 A push service MUST NOT forward the JWT or public key to the user 366 agent when delivering the push message. 368 5. Security Considerations 370 This authentication scheme is vulnerable to replay attacks if an 371 attacker can acquire a valid JWT. Applying narrow limits to the 372 period over which a replayable token can be reused limits the 373 potential value of a stolen token to an attacker and can increase the 374 difficulty of stealing a token. 376 An application server might offer falsified contact information. A 377 push service operator therefore cannot use the presence of 378 unvalidated contact information as input to any security-critical 379 decision-making process. 381 Validation of a signature on the JWT requires a non-trivial amount of 382 computation. For something that might be used to identify legitimate 383 requests under denial of service attack conditions, this is not 384 ideal. Application servers are therefore encouraged to reuse tokens, 385 which permits the push service to cache the results of signature 386 validation. 388 6. IANA Considerations 390 This document registers the "vapid" authentication scheme in the 391 "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry" 392 established in [RFC7235]. 394 Authentication Scheme Name: vapid 396 Pointer to specification text: Section 3 of this document 398 Notes: This scheme is origin-server only and does not define a 399 challenge. 401 6.1. Vapid Authentication Scheme Parameters 403 This creates a "Vapid Authentication Scheme Parameters" registry for 404 parameters to the "vapid" authentication scheme. This registry is 405 under the "WebPush Parameters" grouping. The registry operates on 406 the "Specification Required" policy [RFC5226]. 408 Registrations MUST include the following information: 410 Parameter Name: A name for the parameter, which conforms to the 411 "token" grammar [RFC7230] 413 Purpose (optional): A brief identifying the purpose of the 414 parameter. 416 Specification: A link to the specification that defines the format 417 and semantics of the parameter. 419 This registry initially contains the following entries: 421 +---------------+-------------------------+-------------------------+ 422 | Parameter | Purpose | Specification | 423 | Name | | | 424 +---------------+-------------------------+-------------------------+ 425 | t | JWT authentication | [[RFC-to-be]], Section | 426 | | token | 3.1 | 427 | | | | 428 | k | ECDSA signing key | [[RFC-to-be]], Section | 429 | | | 3.2 | 430 +---------------+-------------------------+-------------------------+ 432 7. Acknowledgements 434 This document would have been much worse than it currently is if not 435 for the contributions of Benjamin Bangert, JR Conlin, Chris Karlof, 436 Costin Manolache, and others. 438 8. References 440 8.1. Normative References 442 [FIPS186] National Institute of Standards and Technology (NIST), 443 "Digital Signature Standard (DSS)", NIST PUB 186-4 , July 444 2013. 446 [I-D.ietf-webpush-protocol] 447 Thomson, M., Damaggio, E., and B. Raymor, "Generic Event 448 Delivery Using HTTP Push", draft-ietf-webpush-protocol-12 449 (work in progress), October 2016. 451 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 452 Requirement Levels", BCP 14, RFC 2119, 453 DOI 10.17487/RFC2119, March 1997, 454 . 456 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 457 DOI 10.17487/RFC2818, May 2000, 458 . 460 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 461 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 462 DOI 10.17487/RFC5226, May 2008, 463 . 465 [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' 466 URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010, 467 . 469 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 470 DOI 10.17487/RFC6454, December 2011, 471 . 473 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 474 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 475 2014, . 477 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 478 Protocol (HTTP/1.1): Message Syntax and Routing", 479 RFC 7230, DOI 10.17487/RFC7230, June 2014, 480 . 482 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 483 Protocol (HTTP/1.1): Authentication", RFC 7235, 484 DOI 10.17487/RFC7235, June 2014, 485 . 487 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 488 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 489 2015, . 491 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 492 DOI 10.17487/RFC7518, May 2015, 493 . 495 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 496 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 497 . 499 [X9.62] ANSI, "Public Key Cryptography For The Financial Services 500 Industry: The Elliptic Curve Digital Signature Algorithm 501 (ECDSA)", ANSI X9.62 , 1998. 503 8.2. Informative References 505 [API] van Ouwerkerk, M. and M. Thomson, "Web Push API", 2015, 506 . 508 [I-D.ietf-webpush-encryption] 509 Thomson, M., "Message Encryption for Web Push", draft- 510 ietf-webpush-encryption-06 (work in progress), October 511 2016. 513 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 514 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 515 . 517 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 518 DOI 10.17487/RFC7517, May 2015, 519 . 521 Authors' Addresses 523 Martin Thomson 524 Mozilla 526 Email: martin.thomson@gmail.com 528 Peter Beverloo 529 Google 531 Email: beverloo@google.com