idnits 2.17.1 draft-gajda-dav-push-00.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 -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: ; A list of topics without active subscribers. ; Applications servers SHOULD not send further push messages for the ; enlisted topics to this transport unless a new client subscribes on ; this transport. no-subscribers-list "no-subscribers" [ 1* topic } ] == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: A Push Gateway MUST not accept subscription requests with an expiration time that would exceed the refresh interval. -- The document date (May 2, 2017) is 2523 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) == Unused Reference: 'RFC3339' is defined on line 1001, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Gajda 3 Internet-Draft dmfs 4 Intended status: Standards Track May 2, 2017 5 Expires: November 3, 2017 7 Push Discovery and Notification Dispatch Protocol 8 draft-gajda-dav-push-00 10 Abstract 12 This specification defines a framework and protocols for a push 13 notification system that allows clients, application servers and push 14 notification servers to interact with each other in a standardized 15 manner. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on November 3, 2017. 34 Copyright Notice 36 Copyright (c) 2017 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 53 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 4. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4 55 4.1. Application Server . . . . . . . . . . . . . . . . . . . 5 56 4.2. Push Gateway . . . . . . . . . . . . . . . . . . . . . . 5 57 4.3. Push Delivery Service . . . . . . . . . . . . . . . . . . 6 58 4.4. Client . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 5. Protocol Workflows . . . . . . . . . . . . . . . . . . . . . 6 60 5.1. App Server <-> Push Gateway bootstrap workflow . . . . . 6 61 5.2. Client <-> App Server workflow . . . . . . . . . . . . . 7 62 5.2.1. Client discovery and subscription workflow - Generic 7 63 5.2.2. Unsubscribe . . . . . . . . . . . . . . . . . . . . . 7 64 5.2.3. Client discovery and subscription workflow - WebDAV . 8 65 5.3. App Server -> Push Gateway subscribe workflow . . . . . . 10 66 5.4. App Server -> Push Gateway push workflow . . . . . . . . 11 67 6. Syntax Elements/Properties . . . . . . . . . . . . . . . . . 13 68 6.1. Push gateway protocol . . . . . . . . . . . . . . . . . . 13 69 6.1.1. Bootstrapping . . . . . . . . . . . . . . . . . . . . 13 70 6.1.2. Subscription . . . . . . . . . . . . . . . . . . . . 13 71 6.1.3. Update notification . . . . . . . . . . . . . . . . . 15 72 6.2. XML Element definitions . . . . . . . . . . . . . . . . . 16 73 6.2.1. WebDAV Properties . . . . . . . . . . . . . . . . . . 16 74 6.2.2. Subscription request . . . . . . . . . . . . . . . . 19 75 7. HTTP Headers for DAV-Push . . . . . . . . . . . . . . . . . . 21 76 7.1. Push-Client-Id Header . . . . . . . . . . . . . . . . . . 21 77 8. Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . 21 78 8.1. Application Servers . . . . . . . . . . . . . . . . . . . 21 79 8.2. Clients . . . . . . . . . . . . . . . . . . . . . . . . . 22 80 8.3. Push Gateway . . . . . . . . . . . . . . . . . . . . . . 22 81 9. Security Considerations . . . . . . . . . . . . . . . . . . . 23 82 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 83 10.1. Namespace Registration . . . . . . . . . . . . . . . . . 23 84 11. Normative References . . . . . . . . . . . . . . . . . . . . 23 85 Appendix A. Change History (To be removed by RFC Editor before 86 publication) . . . . . . . . . . . . . . . . . . . . 24 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 24 89 1. Introduction 91 In a client/server protocol, clients can typically create, update, 92 delete "resources" (data) on the server, as well as retrieve data on 93 the server. 95 In many cases, data can appear on the server as the result of some 96 other client or server-side process interacting with the server. 98 Thus clients need a way to detect when the data on the server has 99 changed. 101 Most protocols provide a data synchronization mechanism to support 102 that, but typically clients need to "poll" the server to find out 103 when changes have occurred. Network based polling is inefficient, 104 and instead push notifications are preferred as a way of alerting 105 clients to new data or changes to existing data on the server 107 2. Conventions Used in This Document 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 111 "OPTIONAL" in this document are to be interpreted as described in 112 [RFC2119] 114 When XML element types in the namespaces "DAV:" and 115 "urn:ietf:params:xml:ns:dav-push" are referenced in this document 116 outside of the context of an XML fragment, the string "DAV:" and 117 "DAV-PUSH:" will be prefixed to the element type names respectively. 119 3. Terminology 121 Application Server Provides resources a client application might 122 want to monitor for changes. Typical applications are email, 123 calendars and address books. 125 Push Gateway A service to provide a common, standardized interface 126 to Push Delivery Services. A Push Gateway provides or relays one 127 or multiple delivery channels, the so called Transports. 129 Push Delivery Service A Service which provides the actual push 130 transport mechanism to the client application. 132 Transport A Transport is a logical channel to a specific Push 133 Delivery Service, provided by a Push Gateway. It is identified by 134 the transport-uri. 136 Client Application An application that uses the services of the 137 Application Server and wants to get notified instantaneously about 138 certain changes on the server. A client application typically 139 runs on a mobile or desktop device. 141 Push Notification A message sent from the Application server to the 142 Client Application to notify the client of an update. The basic 143 information carried by the notification is "there was a change" 144 for a specific Topic. 146 Topic A Topic is a name for a notification feed or channel. Each 147 watchable resource has a Topic that clients can subscribe to. 148 Each subscriber to a particular topic will receive a notification 149 when a substantial change was made to any of the resources with 150 that Topic. 152 4. Architecture 154 This document introduces an entity called "Push Gateway" which acts 155 as a proxy between an application server and a push delivery service. 156 A Push Gateway provides at least one Transport. Each Transport is 157 identified by a URI and connects to exactly one Push Delivery 158 Service. 160 Push Gateways MAY support relaying, so a push gateway might forward 161 all or some notifications to another push gateway. 163 +----------------------------+ 164 | Application Server | 165 +-----------------------+----+ 166 ^ | 167 | | 168 | | 169 | | 170 | v 171 | +-------------------------+ 172 | | Push Gateway | 173 | +---------+---------------+ 174 | | 175 | | 176 | | 177 | v 178 | +-------------------------+ 179 | | Push delivery Service | 180 | +---------+---------------+ 181 | | 182 | | 183 | | 184 | | 185 | v 186 +-----+--------------------+ 187 | Client Application | 188 +--------------------------+ 190 4.1. Application Server 192 The server is responsible for generating push topics and sending 193 update notifications to the Push Gateway. A push topic is a unique 194 token that identifies the update notification feed of a resource or a 195 group of resources. The topic is forwarded to the Push Gateway 196 whenever a relevant change in one of these resources occurs. 198 This document doesn't specify how topics are generated. However, for 199 privacy reasons the topic MUST NOT contain user names, user data 200 (like folder/collection names) or URLs in plain text. If a server 201 doesn't maintain opaque, anonymous identifiers it SHOULD use a hash 202 algorithm, like SHA256, to generate an opaque identifier from 203 resource properties. 205 Push topics MAY be generated on a per-user base for shared resources. 207 A server MAY change push topics at any time to improve privacy. If 208 doing so the server MUST continue to send out push notifications for 209 the old topic until all subscriptions to that topic have expired. 211 The application server maintains a mapping of subscribed push topics 212 to a list of push gateways. It updates this mapping whenever 214 o A new subscription request is received, 216 o A response from the push gateway indicates that there are no 217 active subscribers for a particular topic. 219 The application server doesn't maintain references to push clients, 220 because this information is opaque to the application server. 222 4.2. Push Gateway 224 The Push Gateway maintains a mapping of push-topics to a list of 225 subscribed clients and expiration times. It updates the list 226 whenever 228 o it receives a new subscription, 230 o a subscription expires or 232 o the Push Delivery Service returns that a specific client is no 233 longer available. 235 If a push message for a specific topic is received the push gateway 236 will notify all clients with an active (not expired) subscription for 237 that topic. 239 A push gateway may relay messages for other gateways. A gateway that 240 supports relaying MUST maintain a map of topics to gateways just like 241 an application server. 243 4.3. Push Delivery Service 245 TBD: Minimum requirements for PDS to support this protocol. Describe 246 what state information the PDS needs to maintain. 248 4.4. Client 250 TBD: what information does the client need to maintain 252 5. Protocol Workflows 254 5.1. App Server <-> Push Gateway bootstrap workflow 256 This protocol allows an application server to initialize the 257 supported push transports by querying a set of configured push 258 gateways. This requires that the application server knows the root 259 URL of each configured gateway. In order to retrieve the list of 260 supported transports it posts a JSON object with an empty list of 261 push-transports to each gateway. 263 The following request shows the bootstrap request of an application 264 server that was configured with the Push Gateway URL 265 https://push.example.com/gateway 267 POST /gateway 268 Host: push.example.com 269 Content-Type: application/json 270 Content-Length: xxx 272 { "push-transports": []} 274 The push gateway responds with a JSON object that contains an array 275 of push transports. 277 HTTP/1.1 200 OK 278 Content-Type: application/json 279 Content-Length: xxx 281 { "push-transports": [ 282 { 283 "transport": { 284 "transport-uri": 285 "https://push.example.com/transport", 286 "refresh-interval": 172800, 287 "transport-data" : { ... } 288 } 289 },{ 290 "transport": { 291 "transport-uri": 292 "urn:uuid:01234567-0123-0123-0123-0123456789ab", 293 "refresh-interval": 172800, 294 "transport-data" : { ... } 295 } 296 }] 297 } 299 TBD: HTTP status for failure with a XML/JSON error response body 301 5.2. Client <-> App Server workflow 303 The communication between Client and Application Server is defined in 304 the respective application protocol. The application protocol needs 305 to be extended in order to support push. 307 This document describes the general idea behind the required 308 extensions and gives a concrete definition for a WebDAV extension. 310 5.2.1. Client discovery and subscription workflow - Generic 312 TBD: 314 5.2.2. Unsubscribe 316 This document doesn't specify an explicit unsubscribe method. A 317 client that doesn't wish to receive any further push notifications 318 for a specific topic, MAY send a subscription with an expiration date 319 in the past. 321 An application server which receives such a subscription MUST handle 322 it like any other subscription. In particular the Application Server 323 MUST 324 o verify the Push Topic and 326 o forward the susbcription to the Push Gateway. 328 A Push Gateway which receives a subscription with a passed expiration 329 date MUST 331 o remove the client from the list of subscribers to this topic and 333 o not send out any further push messages to this client. 335 5.2.3. Client discovery and subscription workflow - WebDAV 337 5.2.3.1. Push discovery 339 The following example shows a PROPFIND request on a user's calendar 340 home to discover push support. 342 PROPFIND http://calendar.example.com/calendars/ 343 Content-Type: application/xml 344 Depth: 0 345 Content-Length: xxx 347 348 349 /> 350 351 352 353 354 356 The server responds with the respective properties. In this 357 particular case the server added an empty P:transport element to 358 signal it will accept any transport provided by the client. > 359 Response 360 HTTP/1.1 207 Multistatus 361 Content-Type: application/xml; charset=UTF-8 362 Content-Length: xxx 364 365 366 /calendars/ 367 368 369 370 https://calendar.example.com/subscribe 371 372 373 374 375 urn:uuid:01234567-0123-0123-0123-0123456789ab 377 378 ... 379 380 172800 381 382 383 https://push.example.com/transport 385 386 ... 387 388 172800 389 390 391 123 392 1 393 394 HTTP/1.1 200 OK 395 396 397 399 5.2.3.2. Push subscribe 401 Calendar server -> Client - CS server advertises its supported push 402 mechanisms Clients request POST to P:subscribe-URL - does the actual 403 subscription to the calendar server: 405 POST /subscribe HTTP/1.1 406 Host: calendar.example.com 407 Content-Type: application/xml; charset=UTF-8 409 410 123 411 abc 412 413 https://push.example.com/transport 415 XYZ 416 417 2017-10-07T12:00:00Z 418 420 If one or more topics are invalid the enitre request MUST fail 421 without any subscriptions being recorded. In this case the server 422 MUST return an error response containg a list of topics that failed. 423 If a topic is valid but the authenticated user doesn't have access to 424 any of the resources that the topic belongs to, the server SHOULD 425 treat this topic as being invalid and the request SHOULD fail. 427 TBD: response 429 5.3. App Server -> Push Gateway subscribe workflow 431 When a client sends a request to subscribe to specific topics, the 432 application server MUST foward the subscription to the chosen gateway 433 or to the gateway that announced itself as a proxy for the chosen 434 gateway. 436 If a gateway acts as a proxy for another gateway it MUST forward the 437 request to the proxied gateway. 439 The following example shows a request to subscribe to two topics. 441 POST / HTTP/1.1 442 Host: push.example.com 443 Content-Type: application/json 445 { 446 "push-subscribe": { 447 "topics": [ "123", "abc" ], 448 "transport": { 449 "transport-uri": "https://push.example.com/transport", 450 "client-data": "XYZ" 451 }, 452 "expires": "2017-10-07T12:00:00Z" 453 } 454 } 456 Response: HTTP status for success, or HTTP status for failure with a 457 XML/JSON error response body To acknowledge the subscription the 458 gateway SHOULD send an initial PUSH notification to the client. 460 TBD: responses A successful response containt the URL to send update 461 messages to. The URL may be different than the transport URL. An 462 Application Server MUST use this URL when sending push notifications 463 to transports provided by clients. 465 HTTP/1.1 200 OK 466 Content-Type: application/json 468 { "push-url": "https://push.example.com/" } 470 5.4. App Server -> Push Gateway push workflow 472 Whenever a substantial change occurs in any of the resources, the 473 application server sends a Push Message to the gateway containing the 474 Topics of the resources that have changed. The following example 475 sends a push notification for the Topics "123" and "abc". The 476 message for Topic "123" also contains a "client-id" to omit any 477 notification to the sole client that modified the resource and caused 478 this push message. The second message has a low priority and no 479 "client-id". Such a message could be generated by multiple clients 480 acknowledging an alarm on a shared calendar. 482 POST / HTTP/1.1 483 Host: push.example.com 484 Content-Type: application/json 486 { 487 "push": { 488 "messages" : [{ 489 "topic": "123", 490 "priority": 100, 491 "timestamp": "2017-10-01T14:00:52Z", 492 "client-id": "xyz" 493 }, { 494 "topic": "abc", 495 "priority": 0, 496 "timestamp": "2017-10-01T14:00:53Z" 497 }] 498 } 499 } 501 Response: HTTP status for success, or HTTP status for failure with a 502 XML/JSON error response body It's not an error if a topic is unknown 503 or there are no active subscribers for this topic. Instead the 504 response will contain a list of all topics without subscribers. The 505 application server SHOULD update its topic-to-gateway mapping 506 accordingly. The application server MUST assume that topics which 507 were in the request and not in the "no-subscribers" list have been 508 pushed to the client. If there is a subscriber for each topic in the 509 request, the no-subscribers list MUST be omitted. 511 HTTP/1.1 200 OK 512 Content-Type: application/json 514 { "push-response": {} } 516 If there are topics without active subscribers: 518 HTTP/1.1 200 OK 519 Content-Type: application/json 521 { 522 "push-response": { 523 "no-subscribers": [ 524 { "topic": "123"} 525 ] 526 } 527 } 529 6. Syntax Elements/Properties 531 6.1. Push gateway protocol 533 6.1.1. Bootstrapping 535 ; root element 536 root { 537 push-transports 538 } 540 ; a list of push transports supported by a gateway 541 ; in the request sent by the application server this is empty 542 push-transports "push-transports" [ 543 * transport 544 ] 546 transport "transport" { 548 ; The uri of the transport. 549 "transport-uri" : uri, 551 transport-data? 552 } 554 ; optional data the client needs to know in order to subscribe 555 ; to allow easy conversion to other formats, 556 ; this object MUST NOT contain structured data. 557 transport-data "transport-data" { 558 ^"": any 559 } 561 6.1.2. Subscription 562 ; root element 563 root { 564 push-subscribe 565 } 567 ; the object describing the subscription 568 push-subscribe "push-subscribe" { 569 topic-list, 570 selected-transport, 571 expires 572 } 574 ; The list of topics to subscribe to. Unless a previous 575 ; subscription is updated by a request, existing 576 ; subscriptions won't be affected by new subscriptions. 577 topic-list "topics" [ 578 * topic 579 } 581 ; The chosen transport type 582 selected-transport "selected-transport" { 584 ; The transport-uri of the chosen transport 585 "transport-uri" : uri, 587 ; The client-data string as sent by the client 588 "client-data" : string 589 } 591 ; The time of when the subscription expires 592 ; must be a UTC timestamp following 593 ; https://tools.ietf.org/html/rfc3339 594 expires "expires" : RFC 3339 timestamp 595 ; root element 596 root { 597 error 598 } 600 ; the object describing the failure 601 error "error" { 602 invalid-topic-list 603 } 605 ; The list of topics that the user can't subscribe to 606 invalid-topic-list "invalid-topics" [ 607 1* topic 608 } 610 6.1.3. Update notification 612 ; The root object 613 root { 614 "push" [ 1* message ] 615 } 617 ; A message object, describing the update 618 message { 619 topic, 620 ? priority, 621 timestamp, 622 ? client-id 623 } 625 ; The topic of the resource that has been updated 626 topic "topic" : string 628 ; The priority of the change, with 0 being the lowest and 100 629 ; being the highest priority 630 ; If omitted, implementations SHOULD default to 50. 631 priority "priority" : integer 0..100 633 ; The time of when the change occurred. The value MUST be a 634 ; timestamp in UTC following https://tools.ietf.org/html/rfc3339 635 ; If the server aggregated multiple updates before sending the push 636 ; message, this MUST be the timestamp of the most recent update. 637 timestamp "timestamp" : RFC 3339 timestamp 639 ; An optional id that identifies the client that triggered the update 640 ; notification. Push gateways can use this information to suppress 641 ; push messages to this particular client, in order to avoid 642 ; unnecessary sync operations. 643 ; If the server aggregated multiple updates from different clients 644 ; into one message, it MUST omit the client-id to ensure all clients 645 ; receive the push message. 646 client-id "client-id": string 648 ; root element of the push subscribe response 649 root { 650 ? no-subscribers-list 651 } 653 ; A list of topics without active subscribers. 654 ; Applications servers SHOULD not send further push messages for the 655 ; enlisted topics to this transport unless a new client subscribes on 656 ; this transport. 657 no-subscribers-list "no-subscribers" [ 658 1* topic } 659 ] 661 6.2. XML Element definitions 663 6.2.1. WebDAV Properties 665 6.2.1.1. DAV-PUSH:push-subscribe-URL 667 Name: push-subscribe-URL 669 Namespace: urn:ietf:params:xml:ns:dav-push 671 Purpose: Specifies the address to send the subscription requests to. 673 Description: The push-subscribe-URL element contains exactly one 674 DAV:href element with a URL that points to the subscription 675 service endpoint. 677 Definition: 679 681 6.2.1.2. DAV-PUSH:supported-transport-set 683 Name: supported-transport-set 685 Namespace: urn:ietf:params:xml:ns:dav-push 687 Purpose: Specifies a list of transports supported by the application 688 server. 690 Description: This element contains the set of push transports 691 supported by the server. The transport-uri element of each 692 transport must be unique within the set of transports. 694 The set MAY contain one transport element without any child 695 elements to indicate that the client may provide its own 696 transport. 698 Definition: 700 702 6.2.1.3. DAV-PUSH:transport 704 Name: transport 706 Namespace: urn:ietf:params:xml:ns:dav-push 708 Purpose: Describes a specific transport. 710 Description: A transport element represents a specific push 711 transport path to clients on a specific service. In general it 712 contains a transport-uri element that uniquely identifies the 713 transport. 715 Definition: 717 720 6.2.1.4. DAV-PUSH:transport-uri 722 Name: transport-uri 724 Namespace: urn:ietf:params:xml:ns:dav-push 726 Purpose: Specifies the URI that identifes the transport. 728 Description: Clients compare the provided transport-uris to the 729 transport-uris they support. 731 Definition: 733 734 PCDATA value: The URI identifying the transport. 736 6.2.1.5. DAV-PUSH:transport-data 738 Name: transport-data 740 Namespace: urn:ietf:params:xml:ns:dav-push 742 Purpose: Contains a list of additional attributes that client needs 743 to know in order to subscribe on this transport. 745 Description: 747 Definition: 749 751 6.2.1.6. DAV-PUSH:refresh-interval 753 Name: refresh-interval 755 Namespace: urn:ietf:params:xml:ns:dav-push 757 Purpose: Specifies the maximum refresh interval. 759 Description: Specifies the duration in seconds after which the 760 client is expected to re-subscribe. If the client didn't res- 761 subscribe within this period of time the gateway MUST remove all 762 subscriptions and no further push notifications will be delivered 763 to the client until it subscribes again. 765 A Push Gateway MUST not accept subscription requests with an 766 expiration time that would exceed the refresh interval. 768 Definition: 770 771 PCDATA value: the maximum refresh interval in seconds 773 6.2.1.7. DAV-PUSH:topic 775 Name: topic 777 Namespace: urn:ietf:params:xml:ns:dav-push 779 Purpose: Specifies the push topic of a resource. 781 Description: The topic identifies the name of the update channel for 782 a resource. Clients send the topic in a subscription request to 783 inform application server and gateway that it wants to receive 784 update notifications for the resource. 786 This document doesn't specify a specific format for topics nor a 787 specifc algorithm to generate them. 789 Server developers MUST ensure that topics on different 790 installations won't collide. 792 Resources within the same domain MAY share topics. 794 Definition: 796 797 PCDATA value: the push topic 799 6.2.1.8. DAV-PUSH:version 801 Name: push-version 803 Namespace: urn:ietf:params:xml:ns:dav-push 805 Purpose: Specifies the highest version number of the push protocol 806 supported by this server. 808 Description: 810 Definition: 812 813 PCDATA value: the highest push protocol version number 814 supported by the application server 816 6.2.2. Subscription request 818 6.2.2.1. DAV-PUSH:subscribe 820 Name: subscribe 822 Namespace: urn:ietf:params:xml:ns:dav-push 824 Purpose: Represents a subscription request document. 826 Description: The subscribe request contains all information to 827 subscribe to specific topics selecting a specific transport to 828 deliver push notifications. 830 A subscription must have an expiration date after which the 831 subscriptions will become void. 833 Definition: 835 838 6.2.2.2. DAV-PUSH:selected-transport 840 Name: selected-transport 842 Namespace: urn:ietf:params:xml:ns:dav-push 844 Purpose: Specifies the transport the client has chosen. 846 Description: The selected-transport element contains the transport- 847 uri of the transport that the client has chosen for push delivery. 848 It also contains a client-data element to be forwarded to the push 849 gateway. 851 Definition: 853 856 6.2.2.3. DAV-PUSH:client-data 858 Name: client-data 860 Namespace: urn:ietf:params:xml:ns:dav-push 862 Purpose: Contains a string the client needs to provide to the push- 863 gateway for the chosen transport. 865 Description: This element provides a mechanism for the client to 866 communicate to the gateway. The format of the data string is not 867 defined in this document. The application server MUST forward the 868 client-data string as provided by the client. 869 Gateways SHOULD use this to authenticate clients. 871 Definition: 873 874 PCDATA value: client data as required by the push gateway 875 Name: invalid-topics (precondition) 877 Purpose: The request could not succeed, because it contained 878 invalid push topics. This element contains one topic element 879 for each rejected push topic. The client may repeat the 880 request without those topics. 882 Definition: 884 886 7. HTTP Headers for DAV-Push 888 7.1. Push-Client-Id Header 890 Push-Client-Id = "Push-Client-Id" ":" token 892 The client sends this header to identify itself to the application 893 server as the modifying instance. If the application server didn't 894 coalesce multiple updates from different clients into a single push 895 message, it SHOULD include the value in the update notification 896 message. The provided token ([RFC7230]) MUST be percent-encoded as 897 per[RFC3986]. Gateways can use this information to suppress push 898 messages to this particular client. 900 The actual value of token is part of the contract between client and 901 gateway. The token MUST NOT contain any sensitive data like user 902 name or device identifiers. It SHOULD be either a random or an 903 obfuscated token (using a cryptographic hash function). 905 8. Guidelines 907 8.1. Application Servers 909 Servers may want to implement some form of "keep-alive" within the 910 push protocol to ensures clients know they are still connected in 911 cases where actual data changes happen at long intervals (e.g., a 912 calendar user who only makes changes once a day) 914 Priorities: Range 0 - 100 - 0 is lowest and 100 is highest e.g.: low 915 priority - updates due to other attendees changing their partstat 916 high priority - updates to events ocurring in the next 24 hours 917 Priority is used by a client to indicate what level of push they want 918 at a specific time. It can also be used by the push gateway or push 919 delivery system to throttle push notifications to the client based on 920 load. 922 Servers MAY delay the delivery of push notifications for several 923 seconds in order to coalesce notifications. This is useful to give 924 the server a certain amount of control over the client's behavior 925 during times of high load. 927 Servers MUST NOT coalesce push notifications based on priority. 929 Application servers MAY allow clients to provide their own 930 transports. If the transport-uri is not among the transport-uris as 931 advertised by the application server, the transport-uri MUST be an 932 HTTPS URL. If a client sends such a transport-uri, the application 933 server SHOULD perform a transport discovery on the provided URL to 934 discover all transports supported on this gateway. 936 8.2. Clients 938 Clients MUST be prepared that they might receive an initial push 939 notification that acknowledges the subscription before the response 940 to the push-subscribe request has been received. 942 Clients SHOULD NOT rely solely on push notifications. The framework 943 described in this document does not make any guarantees about the 944 delivery of a push notification. Clients should be prepared to 945 trigger a synchronization themselves if no push message has been 946 received within some time period. 948 Clients can expect that sometimes they will get a push but then not 949 detect any actual changes when they sync (i.e., "no-op" push from 950 server as a "keep-alive" mechanism). 952 8.3. Push Gateway 954 A Push Gateway SHOULD require some kind of authentication to be 955 encoded in the client-data string. This document doesn't specify any 956 authentication methods. However, among others, encrypting the 957 client-data string with a shared secret and digitally signing the 958 data are two possible options to achieve this. 960 Client data MAY contain additional per-client preferences, like 961 minimum priority to deliver or maximum delay of notifications when 962 doing coalescing. This is part of the contract between client and 963 transport an not subject of this specification. 965 Gateways MAY coalesce push notifications based on priority. 967 9. Security Considerations 969 To prevent abuse of the service, Push Gateways SHOULD require either 970 servers or clients or both to authenticate. Servers SHOULD 971 authenticate every request of Protocol #2 via HTTP. 973 Push Gateways use the information to authenticate 974 subscription requests from a Server by relating them to Client 975 authorization requests. Clients will typically be authenticating to 976 Servers to access protected data on the server and thus SHOULD 977 authenticate when using Protocol #1. 979 10. IANA Considerations 981 This document uses a URN to describe a new XML namespace conforming 982 to the registry mechanism described in[RFC3688]. 984 10.1. Namespace Registration 986 Registration request for the push namespace: 988 URI: urn:ietf:params:xml:ns:dav-push 990 Registrant Contact: The IESG 992 XML: None - not applicable for namespace registrations. 994 11. Normative References 996 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 997 Requirement Levels", BCP 14, RFC 2119, 998 DOI 10.17487/RFC2119, March 1997, 999 . 1001 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1002 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1003 . 1005 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1006 DOI 10.17487/RFC3688, January 2004, 1007 . 1009 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1010 Resource Identifier (URI): Generic Syntax", STD 66, 1011 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1012 . 1014 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1015 Protocol (HTTP/1.1): Message Syntax and Routing", 1016 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1017 . 1019 Appendix A. Change History (To be removed by RFC Editor before 1020 publication) 1022 Changes in -01: 1024 1. 1026 Author's Address 1028 Marten Gajda 1029 dmfs GmbH 1030 Schandauer Strasse 34 1031 Dresden 01309 1032 Germany 1034 Email: marten@dmfs.org 1035 URI: http://dmfs.org