idnits 2.17.1 draft-ietf-secevent-http-poll-03.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 : ---------------------------------------------------------------------------- == There are 5 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 8, 2019) is 1752 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: 'RFC3986' is defined on line 692, but no explicit reference was found in the text == Unused Reference: 'RFC7519' is defined on line 722, but no explicit reference was found in the text == Unused Reference: 'RFC3339' is defined on line 748, but no explicit reference was found in the text == Outdated reference: A later version (-14) exists of draft-ietf-secevent-http-push-06 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) Summary: 4 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Backman, Ed. 3 Internet-Draft Amazon 4 Intended status: Standards Track M. Jones, Ed. 5 Expires: January 9, 2020 Microsoft 6 M. Scurtescu 7 Coinbase 8 M. Ansari 9 Cisco 10 A. Nadalin 11 Microsoft 12 July 8, 2019 14 Poll-Based Security Event Token (SET) Delivery Using HTTP 15 draft-ietf-secevent-http-poll-03 17 Abstract 19 This specification defines how a series of Security Event Tokens 20 (SETs) may be delivered to an intended recipient using HTTP POST over 21 TLS initiated as a poll by the recipient. The specification also 22 defines how delivery can be assured, subject to the SET Recipient's 23 need for assurance. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on January 9, 2020. 42 Copyright Notice 44 Copyright (c) 2019 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2 60 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 61 1.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. SET Delivery . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2.1. Polling Delivery using HTTP . . . . . . . . . . . . . . . 4 64 2.2. Polling HTTP Request . . . . . . . . . . . . . . . . . . 4 65 2.3. Polling HTTP Response . . . . . . . . . . . . . . . . . . 5 66 2.4. Poll Request . . . . . . . . . . . . . . . . . . . . . . 6 67 2.4.1. Poll Only Request . . . . . . . . . . . . . . . . . . 7 68 2.4.2. Acknowledge Only Request . . . . . . . . . . . . . . 7 69 2.4.3. Poll with Acknowledgement . . . . . . . . . . . . . . 8 70 2.4.4. Poll with Acknowledgement and Errors . . . . . . . . 9 71 2.5. Poll Response . . . . . . . . . . . . . . . . . . . . . . 10 72 2.6. Error Response Handling . . . . . . . . . . . . . . . . . 12 73 3. Authentication and Authorization . . . . . . . . . . . . . . 12 74 3.1. Use of Tokens as Authorizations . . . . . . . . . . . . . 13 75 4. Security Considerations . . . . . . . . . . . . . . . . . . . 14 76 4.1. Authentication Using Signed SETs . . . . . . . . . . . . 14 77 4.2. HTTP Considerations . . . . . . . . . . . . . . . . . . . 14 78 4.3. Confidentiality of SETs . . . . . . . . . . . . . . . . . 14 79 4.4. Access Token Considerations . . . . . . . . . . . . . . . 15 80 4.4.1. Bearer Token Considerations . . . . . . . . . . . . . 15 81 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 15 82 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 83 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 84 7.1. Normative References . . . . . . . . . . . . . . . . . . 16 85 7.2. Informative References . . . . . . . . . . . . . . . . . 17 86 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 18 87 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 18 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 90 1. Introduction and Overview 92 This specification defines how a stream of Security Event Tokens 93 (SETs) [RFC8417] can be transmitted to an intended SET Recipient 94 using HTTP [RFC7231] over TLS. The specification defines a method to 95 poll for SETs using HTTP POST. 97 A mechanism for exchanging configuration metadata such as endpoint 98 URLs and cryptographic key parameters between the transmitter and 99 recipient is out of scope for this specification. 101 1.1. Notational Conventions 103 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 104 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 105 "OPTIONAL" in this document are to be interpreted as described in BCP 106 14 [RFC2119] [RFC8174] when, and only when, they appear in all 107 capitals, as shown here. 109 Throughout this document, all figures MAY contain spaces and extra 110 line wrapping for readability and due to space limitations. 112 1.2. Definitions 114 This specification utilizes terminology defined in [RFC8417], as well 115 as the terms defined below: 117 SET Transmitter 118 An entity that delivers SETs in its possession to one or more SET 119 Recipients. 121 2. SET Delivery 123 When an event occurs, the SET Transmitter constructs a SET [RFC8417] 124 that describes the event. The SET Transmitter determines the SET 125 Recipients that the SET should be distributed to. 127 How SETs are defined and the process by which events are identified 128 for SET Recipients is out of scope of this specification. 130 When a SET is available for a SET Recipient, the SET Transmitter 131 attempts to deliver the SET by queueing the SET in a buffer so that a 132 SET Recipient can poll for SETs using HTTP/1.1 POST. 134 In Poll-Based SET Delivery Using HTTP, zero or more SETs are 135 delivered in a JSON [RFC8259] document to a SET Recipient in response 136 to an HTTP POST request to the SET Transmitter. Then in a following 137 request, the SET Recipient acknowledges received SETs and can poll 138 for more. All requests and responses are JSON documents and use a 139 "Content-Type" of "application/json", as described in Section 2.1. 141 After successful (acknowledged) SET delivery, SET Transmitters are 142 not be required to retain or record SETs for retransmission. Once a 143 SET is acknowledged, the SET Recipient SHALL be responsible for 144 retention, if needed. 146 Transmitted SETs SHOULD be self-validating (signed) if there is a 147 requirement to verify they were issued by the SET Transmitter at a 148 later date when de-coupled from the original delivery where 149 authenticity could be checked via the HTTP or TLS mutual 150 authentication. 152 Upon receiving a SET, the SET Recipient reads the SET and validates 153 it in the manner described in Section 2 of 154 [I-D.ietf-secevent-http-push]. The SET Recipient MUST acknowledge 155 receipt to the SET Transmitter. The SET Recipient SHALL NOT use the 156 event acknowledgement mechanism to report event errors other than 157 relating to the parsing and validation of the SET. 159 2.1. Polling Delivery using HTTP 161 This method allows a SET Recipient to use HTTP POST (Section 4.3.3 of 162 [RFC7231]) to acknowledge SETs and to check for and receive zero or 163 more SETs. Requests MAY be made at a periodic interval (short 164 polling) or requests MAY wait, pending availability of new SETs using 165 long polling, per Section 2 of [RFC6202]. 167 The delivery of SETs in this method is facilitated by HTTP POST 168 requests initiated by the SET Recipient in which: 170 o The SET Recipient makes a request for available SETs using an HTTP 171 POST to a pre-arranged endpoint provided by the SET Transmitter 172 or, 174 o after validating previously received SETs, the SET Recipient 175 initiates another poll request using HTTP POST that includes 176 acknowledgement of previous SETs and waits for the next batch of 177 SETs. 179 The purpose of the acknowledgement is to inform the SET Transmitter 180 that delivery has succeeded and redelivery is no longer required. 181 Before acknowledgement, SET Recipients SHOULD ensure that received 182 SETs have been validated and retained in a manner appropriate to the 183 recipient's requirements. The level and method of retention of SETs 184 by SET Recipients is out of scope of this specification. 186 2.2. Polling HTTP Request 188 When initiating a poll request, the SET Recipient constructs a JSON 189 document that consists of polling request parameters and SET 190 acknowledgement parameters in the form of JSON objects. The request 191 payloads are delivered in a JSON document, as described in 192 Section 2.4 and Section 2.5. 194 When making a request, the HTTP header "Content-Type" is set to 195 "application/json". 197 The following JSON object members are used in a polling request: 199 Request Processing Parameters 201 maxEvents 202 An OPTIONAL JSON integer value indicating the maximum number of 203 unacknowledged SETs that SHOULD be returned. If more than the 204 maximum number of SETs are available, the oldest SETs available 205 SHOULD be returned first. A value of "0" MAY be used by SET 206 Recipients that would like to perform an acknowledge only 207 request. This enables the Recipient to use separate HTTP 208 requests for acknowledgement and reception of SETs. If this 209 parameter is omitted, no limit is placed on the number of SETs 210 to be returned. 212 returnImmediately 213 An OPTIONAL JSON boolean value that indicates the SET 214 Transmitter SHOULD return an immediate response even if no 215 results are available (short polling). The default value is 216 "false", which indicates the request is to be treated as an 217 HTTP Long Poll, per Section 2 of [RFC6202]. The timeout for 218 the request is part of the configuration between the 219 participants, which is out of scope of this specification. 221 SET Acknowledgment Parameters 223 ack 224 An array of strings that each corresponds to the "jti" of a 225 successfully received SET. If there are no outstanding SETs to 226 acknowledge, the member MAY be omitted. When acknowledging a 227 SET, the SET Transmitter is released from any obligation to 228 retain the SET. 230 setErrs 231 A JSON Object that contains one or more nested JSON object 232 members that correspond to the "jti" of each invalid SET 233 received. The value of each is a JSON object whose contents is 234 an "err" member and "description" member, whose values 235 correspond to the errors described in Section 2.6. 237 2.3. Polling HTTP Response 239 In response to a poll request, the SET Transmitter checks for 240 available SETs and responds with a JSON document containing the 241 following JSON object members: 243 sets 244 A JSON object that contains zero or more nested JSON objects. 245 Each nested JSON object corresponds to the "jti" of a SET to be 246 delivered and whose value is a JSON string containing the value of 247 the encoded corresponding SET. If there are no outstanding SETs 248 to be transmitted, the JSON object SHALL be empty. 250 moreAvailable 251 A JSON boolean value that indicates if more unacknowledged SETs 252 are available to be returned. 254 When making a response, the HTTP header "Content-Type" is set to 255 "application/json". 257 2.4. Poll Request 259 The SET Recipient performs an HTTP POST (see Section 4.3.4 of 260 [RFC7231]) to a pre-arranged polling endpoint URI to check for SETs 261 that are available. Because the SET Recipient has no prior SETs to 262 acknowledge, the "ack" and "errs" request parameters are omitted. 264 If after a period of time, negotiated between the SET Transmitter and 265 Recipient, a SET Transmitter MAY redeliver SETs it has previously 266 delivered. The SET Recipient SHOULD accept repeat SETs and 267 acknowledge the SETs regardless of whether the Recipient believes it 268 has already acknowledged the SETs previously. A SET Transmitter MAY 269 limit the number of times it attempts to deliver a SET. 271 If the SET Recipient has received SETs from the SET Transmitter, the 272 SET Recipient SHOULD parse and validate received SETs to meet its own 273 requirements and SHOULD acknowledge receipt in a timely fashion 274 (e.g., seconds or minutes) so that the SET Transmitter can mark the 275 SETs as received. SET Recipients SHOULD acknowledge receipt before 276 taking any local actions based on the SETs to avoid unnecessary delay 277 in acknowledgement, where possible. 279 Poll requests have three variations: 281 Poll Only 282 In which a SET Recipient asks for the next set of events where no 283 previous SET deliveries are acknowledged (such as in the initial 284 poll request). 286 Acknowledge Only 287 In which a SET Recipient sets the "maxEvents" value to "0" along 288 with "ack" and "err" members indicating the SET Recipient is 289 acknowledging previously received SETs and does not want to 290 receive any new SETs in response to the request. 292 Combined Acknowledge and Poll 293 In which a SET Recipient is both acknowledging previously received 294 SETs using the "ack" and "err" members and will wait for the next 295 group of SETs in the SET Transmitters response. 297 2.4.1. Poll Only Request 299 In the case where no SETs were received in a previous poll (see 300 Figure 7), the SET Recipient simply polls without acknowledgement 301 parameters ("sets" and "setErrs"). 303 The following is an example request made by a SET Recipient that has 304 no outstanding SETs to acknowledge and is polling for available SETs 305 at the endpoint "https://nofity.exampleidp.com/Events": 307 POST /Events HTTP/1.1 309 Host: notify.exampleidp.com 310 Authorization: Bearer h480djs93hd8 311 Accept: application/json 313 { 314 "returnImmediately": true 315 } 317 Figure 1: Example Initial Poll Request 319 A SET Recipient can poll using default parameter values by passing an 320 empty JSON object. 322 The following is a non-normative example default poll request to the 323 endpoint "https://nofity.exampleidp.com/Events": 325 POST /Events HTTP/1.1 327 Host: notify.exampleidp.com 328 Authorization: Bearer h480djs93hd8 329 Accept: application/json 331 {} 333 Figure 2: Example Default Poll Request 335 2.4.2. Acknowledge Only Request 337 In this variation, the SET Recipient acknowledges previously received 338 SETs and indicates it does not want to receive SETs in response by 339 setting the "maxEvents" value to "0". 341 This variation might be used, for instance, when a SET Recipient 342 needs to acknowledge received SETs independently (e.g., on separate 343 threads) from the process of receiving SETs. 345 The following is a non-normative example poll request with 346 acknowledgement of SETs received (for example as shown in Figure 6): 348 POST /Events HTTP/1.1 350 Host: notify.exampleidp.com 351 Authorization: Bearer h480djs93hd8 352 Content-Type: application/json 353 Authorization: Bearer h480djs93hd8 355 { 356 "ack": [ 357 "4d3559ec67504aaba65d40b0363faad8", 358 "3d0c3cf797584bd193bd0fb1bd4e7d30" 359 ], 360 "maxEvents": 0, 361 "returnImmediately": true 362 } 364 Figure 3: Example Acknowledge Only Request 366 2.4.3. Poll with Acknowledgement 368 This variation allows a recipient thread to simultaneously 369 acknowledge previously received SETs and wait for the next group of 370 SETs in a single request. 372 The following is a non-normative example poll with acknowledgement of 373 the SETs received in Figure 6: 375 POST /Events HTTP/1.1 377 Host: notify.exampleidp.com 378 Authorization: Bearer h480djs93hd8 379 Content-Type: application/json 380 Authorization: Bearer h480djs93hd8 382 { 383 "ack": [ 384 "4d3559ec67504aaba65d40b0363faad8", 385 "3d0c3cf797584bd193bd0fb1bd4e7d30" 386 ], 387 "returnImmediately": false 388 } 390 Figure 4: Example Poll with Acknowledgement and No Errors 392 In the above acknowledgement, the SET Recipient has acknowledged 393 receipt of two SETs and has indicated it wants to wait until the next 394 SET is available. 396 2.4.4. Poll with Acknowledgement and Errors 398 In the case where errors were detected in previously delivered SETs, 399 the SET Recipient MAY use the "setErrs" member to communicate the 400 errors in the following poll request. 402 The following is a non-normative example of a response acknowledging 403 one successfully received SET and one SET with an error from the two 404 SETs received in Figure 6: 406 POST /Events HTTP/1.1 408 Host: notify.exampleidp.com 409 Authorization: Bearer h480djs93hd8 410 Content-Type: application/json 411 Authorization: Bearer h480djs93hd8 413 { 414 "ack": ["3d0c3cf797584bd193bd0fb1bd4e7d30"], 415 "setErrs": { 416 "4d3559ec67504aaba65d40b0363faad8": { 417 "err": "jwtAud", 418 "description": "The audience value was invalid." 419 } 420 }, 421 "returnImmediately": true 422 } 424 Figure 5: Example Poll Acknowledgement with Error 426 2.5. Poll Response 428 In response to a poll request, the service provider MAY respond 429 immediately if SETs are available to be delivered. If no SETs are 430 available at the time of the request, the SET Transmitter SHALL delay 431 responding until a SET is available or the timeout interval has 432 elapsed unless the poll request parameter "returnImmediately" is 433 "true". 435 As described in Section 2.3, a JSON document is returned containing a 436 number of members including "sets", which SHALL contain zero or more 437 SETs. 439 The following is a non-normative example response to the request 440 shown in Section 2.4. This example shows two SETs being returned: 442 HTTP/1.1 200 OK 443 Content-Type: application/json 444 Location: https://notify.exampleidp/Events 446 { 447 "sets": { 448 "4d3559ec67504aaba65d40b0363faad8": 449 "eyJhbGciOiJub25lIn0. 450 eyJqdGkiOiI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsImlhdCI6MTQ 451 1ODQ5NjQwNCwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbIm 452 h0dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M 453 2I3NzU0IiwiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIx 454 ZDA4NjQxZDc2NzZlZTciXSwiZXZlbnRzIjp7InVybjppZXRmOnBhcmFtczpzY2ltOmV 455 2ZW50OmNyZWF0ZSI6eyJyZWYiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcn 456 MvNDRmNjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsImF0dHJpYnV0ZXMiOlsiaWQiLCJuY 457 W1lIiwidXNlck5hbWUiLCJwYXNzd29yZCIsImVtYWlscyJdfX19.", 458 "3d0c3cf797584bd193bd0fb1bd4e7d30": 459 "eyJhbGciOiJub25lIn0. 460 eyJqdGkiOiIzZDBjM2NmNzk3NTg0YmQxOTNiZDBmYjFiZDRlN2QzMCIsImlhdCI6MTQ 461 1ODQ5NjAyNSwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbIm 462 h0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M 463 2I3NzU0IiwiaHR0cHM6Ly9qaHViLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIx 464 ZDA4NjQxZDc2NzZlZTciXSwic3ViIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL1V 465 zZXJzLzQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkiLCJldmVudHMiOnsidXJuOmlldG 466 Y6cGFyYW1zOnNjaW06ZXZlbnQ6cGFzc3dvcmRSZXNldCI6eyJpZCI6IjQ0ZjYxNDJkZ 467 jk2YmQ2YWI2MWU3NTIxZDkifSwiaHR0cHM6Ly9leGFtcGxlLmNvbS9zY2ltL2V2ZW50 468 L3Bhc3N3b3JkUmVzZXRFeHQiOnsicmVzZXRBdHRlbXB0cyI6NX19fQ." 469 } 470 } 472 Figure 6: Example Poll Response 474 In the above example, two SETs whose "jti" values are 475 "4d3559ec67504aaba65d40b0363faad8" and 476 "3d0c3cf797584bd193bd0fb1bd4e7d30" are delivered. 478 The following is a non-normative example response to the request 479 shown in Section 2.4, which indicates that no new SETs or 480 unacknowledged SETs are available: 482 HTTP/1.1 200 OK 483 Content-Type: application/json 484 Location: https://notify.exampleidp/Events 486 { 487 "sets": {} 488 } 490 Figure 7: Example No SETs Poll Response 492 Upon receiving the JSON document (e.g., as shown in Figure 6), the 493 SET Recipient parses and verifies the received SETs and notifies the 494 SET Transmitter via the next poll request to the SET Transmitter, as 495 described in Section 2.4.3 or Section 2.4.4. 497 2.6. Error Response Handling 499 If a SET is invalid, error codes from the IANA "Security Event Token 500 Delivery Error Codes" registry established by 501 [I-D.ietf-secevent-http-push] are used in error responses. As 502 described in Section 2.3 of [I-D.ietf-secevent-http-push], an error 503 response is a JSON object providing details about the error that 504 includes the following name/value pairs: 506 err 507 A value from the IANA "Security Event Token Delivery Error Codes" 508 registry that identifies the error. 510 description 511 A human-readable string that provides additional diagnostic 512 information. 514 When included as part of a batch of SETs, the above JSON is included 515 as part of the "setErrs" member, as defined in Section 2.3 and 516 Section 2.4.4. 518 3. Authentication and Authorization 520 The SET delivery method described in this specification is based upon 521 HTTP and depends on the use of TLS and/or standard HTTP 522 authentication and authorization schemes, as per [RFC7235]. For 523 example, the following methodologies could be used among others: 525 TLS Client Authentication 526 Event delivery endpoints MAY request TLS mutual client 527 authentication, per Section 7.3 of [RFC5246]. 529 Bearer Tokens 530 Bearer tokens [RFC6750] MAY be used when combined with TLS and a 531 token framework such as OAuth 2.0 [RFC6749]. For security 532 considerations regarding the use of bearer tokens in SET delivery, 533 see Section 4.4.1. 535 Basic Authentication 536 Use of HTTP BASIC authentication should be avoided due to its use 537 of a single factor that is based upon a relatively static, 538 symmetric secret. When used, implementers SHOULD combine the use 539 of basic authentication with other factors. The security 540 considerations of HTTP BASIC are well documented in [RFC7617] and 541 SHOULD be considered along with using signed SETs, as described in 542 Section 4.1. 544 As per Section 4.1 of [RFC7235], a SET delivery endpoint SHALL 545 indicate supported HTTP authentication schemes via the "WWW- 546 Authenticate" header. 548 Authorization for the ability to pick-up or deliver SETs can be 549 determined by using the identity of the SET issuer, or via an 550 authentication method above. This specification considers 551 authentication as a feature to prevent denial-of-service attacks. 552 Because SETs are not commands, SET Recipients are free to ignore SETs 553 that are not of interest after acknowledging their receipt. 555 For illustrative purposes only, SET delivery examples show an OAuth 556 2.0 bearer token value [RFC6750] in the authorization header. This 557 is not intended to imply that bearer tokens are preferred. However, 558 the use of bearer tokens in the specification does reflect common 559 practice. 561 3.1. Use of Tokens as Authorizations 563 When using bearer tokens or proof-of-possession tokens that represent 564 an authorization grant such as issued by OAuth (see [RFC6749]), 565 implementers SHOULD consider the type of authorization granted, any 566 authorized scopes (see Section 3.3 of [RFC6749]), and the security 567 subject(s) that SHOULD be mapped from the authorization when 568 considering local access control rules. Section 6 of the OAuth 569 Assertion Framework specification [RFC7521] documents common 570 scenarios for authorization including: 572 o Clients using an assertion to authenticate and/or act on behalf of 573 itself; 575 o Clients acting on behalf of a user; and, 577 o A Client acting on behalf of an anonymous user. 579 When using OAuth access tokens, implementers MUST take into account 580 the threats and countermeasures documented in the security 581 considerations for the use of client authorizations (see Section 8 of 582 [RFC7521]). When using other token formats or frameworks, 583 implementers MUST take into account similar threats and 584 countermeasures, especially those documented by the relevant 585 specifications. 587 4. Security Considerations 589 4.1. Authentication Using Signed SETs 591 In scenarios where HTTP authorization or TLS mutual authentication 592 are not used or are considered weak, JWS signed SETs SHOULD be used 593 (see [RFC7515] and Section 5 of [RFC8417]). This enables the SET 594 Recipient to validate that the SET issuer is authorized to deliver 595 the SET. 597 4.2. HTTP Considerations 599 SET delivery depends on the use of Hypertext Transfer Protocol and is 600 thus subject to the security considerations of HTTP Section 9 of 601 [RFC7230] and its related specifications. 603 As stated in Section 2.7.1 of [RFC7230], an HTTP requestor MUST NOT 604 generate the "userinfo" (i.e., username and password) component (and 605 its "@" delimiter) when an "http" URI reference is generated with a 606 message, as they are now disallowed in HTTP. 608 4.3. Confidentiality of SETs 610 SETs may contain sensitive information that is considered Personally 611 Identifiable Information (PII). In such cases, SET Transmitters and 612 SET Recipients MUST protect the confidentiality of the SET contents 613 by encrypting the SET as described in JWE [RFC7516], using a 614 transport-layer security mechanism such as TLS, or both. If an Event 615 delivery endpoint supports TLS, it MUST support at least TLS version 616 1.2 [RFC5246] and SHOULD support the newest version of TLS that meets 617 its security requirements. When using TLS, the client MUST perform a 618 TLS/SSL server certificate check, per [RFC6125]. Implementation 619 security considerations for TLS can be found in "Recommendations for 620 Secure Use of TLS and DTLS" [RFC7525]. 622 4.4. Access Token Considerations 624 When using access tokens, such as those issued by OAuth 2.0 625 [RFC6749], implementers MUST take into account threats and 626 countermeasures documented in Section 8 of [RFC7521]. 628 4.4.1. Bearer Token Considerations 630 Due to the possibility of interception, Bearer tokens MUST be 631 exchanged using TLS. 633 Bearer tokens MUST have a limited lifetime that can be determined 634 directly or indirectly (e.g., by checking with a validation service) 635 by the service provider. By expiring tokens, clients are forced to 636 obtain a new token (which usually involves re-authentication) for 637 continued authorized access. For example, in OAuth 2.0, a client MAY 638 use an OAuth refresh token to obtain a new bearer token after 639 authenticating to an authorization server, per Section 6 of 640 [RFC6749]. 642 Implementations supporting OAuth bearer tokens need to factor in 643 security considerations of this authorization method [RFC7521]. 644 Since security is only as good as the weakest link, implementers also 645 need to consider authentication choices coupled with OAuth bearer 646 tokens. The security considerations of the default authentication 647 method for OAuth bearer tokens, HTTP BASIC, are well documented in 648 [RFC7617], therefore implementers are encouraged to prefer stronger 649 authentication methods. Designating the specific methods of 650 authentication and authorization are out of scope for the delivery of 651 SETs, however this information is provided as a resource to 652 implementers. 654 5. Privacy Considerations 656 If a SET needs to be retained for audit purposes, a JWS signature MAY 657 be used to provide verification of its authenticity. 659 SET Transmitters SHOULD attempt to deliver SETs that are targeted to 660 the specific business and protocol needs of subscribers. 662 When sharing personally identifiable information or information that 663 is otherwise considered confidential to affected users, SET 664 Transmitters and Recipients MUST have the appropriate legal 665 agreements and user consent or terms of service in place. 667 The propagation of subject identifiers can be perceived as personally 668 identifiable information. Where possible, SET Transmitters and 669 Recipients SHOULD devise approaches that prevent propagation, for 670 example, the passing of a hash value that requires the subscriber to 671 already know the subject. 673 6. IANA Considerations 675 This specification requires no IANA actions. 677 7. References 679 7.1. Normative References 681 [I-D.ietf-secevent-http-push] 682 Backman, A., Jones, M., Scurtescu, M., Ansari, M., and A. 683 Nadalin, "Push-Based Security Event Token (SET) Delivery 684 Using HTTP", draft-ietf-secevent-http-push-06 (work in 685 progress), May 2019. 687 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 688 Requirement Levels", BCP 14, RFC 2119, 689 DOI 10.17487/RFC2119, March 1997, 690 . 692 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 693 Resource Identifier (URI): Generic Syntax", STD 66, 694 RFC 3986, DOI 10.17487/RFC3986, January 2005, 695 . 697 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 698 (TLS) Protocol Version 1.2", RFC 5246, 699 DOI 10.17487/RFC5246, August 2008, 700 . 702 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 703 Verification of Domain-Based Application Service Identity 704 within Internet Public Key Infrastructure Using X.509 705 (PKIX) Certificates in the Context of Transport Layer 706 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 707 2011, . 709 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 710 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 711 DOI 10.17487/RFC7231, June 2014, 712 . 714 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 715 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 716 2015, . 718 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 719 RFC 7516, DOI 10.17487/RFC7516, May 2015, 720 . 722 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 723 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 724 . 726 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 727 "Recommendations for Secure Use of Transport Layer 728 Security (TLS) and Datagram Transport Layer Security 729 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 730 2015, . 732 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 733 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 734 May 2017, . 736 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 737 Interchange Format", STD 90, RFC 8259, 738 DOI 10.17487/RFC8259, December 2017, 739 . 741 [RFC8417] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, 742 "Security Event Token (SET)", RFC 8417, 743 DOI 10.17487/RFC8417, July 2018, 744 . 746 7.2. Informative References 748 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 749 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 750 . 752 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 753 "Known Issues and Best Practices for the Use of Long 754 Polling and Streaming in Bidirectional HTTP", RFC 6202, 755 DOI 10.17487/RFC6202, April 2011, 756 . 758 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 759 RFC 6749, DOI 10.17487/RFC6749, October 2012, 760 . 762 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 763 Framework: Bearer Token Usage", RFC 6750, 764 DOI 10.17487/RFC6750, October 2012, 765 . 767 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 768 Protocol (HTTP/1.1): Message Syntax and Routing", 769 RFC 7230, DOI 10.17487/RFC7230, June 2014, 770 . 772 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 773 Protocol (HTTP/1.1): Authentication", RFC 7235, 774 DOI 10.17487/RFC7235, June 2014, 775 . 777 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 778 "Assertion Framework for OAuth 2.0 Client Authentication 779 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 780 May 2015, . 782 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 783 RFC 7617, DOI 10.17487/RFC7617, September 2015, 784 . 786 Appendix A. Acknowledgments 788 The editors would like to thank the members of the SCIM working 789 group, which began discussions of provisioning events starting with 790 draft-hunt-scim-notify-00 in 2015. 792 The editors would like to thank Phil Hunt and the other the authors 793 of draft-ietf-secevent-delivery-02, on which this specification is 794 based. 796 The editors would like to thank the participants in the SecEvents 797 working group for their contributions to this specification. 799 Appendix B. Change Log 801 [[ to be removed by the RFC Editor before publication as an RFC ]] 803 Draft 00 - AB - Based on draft-ietf-secevent-delivery-02 with the 804 following additions: 806 o Renamed to "Poll-Based SET Token Delivery Using HTTP" 808 o Removed references to the HTTP Push delivery method. 810 Draft 01 - mbj: 812 o Addressed problems identified in my 18-Jul-18 review message 813 titled "Issues for both the Push and Poll Specs". 815 o Changes to align terminology with RFC 8417, for instance, by using 816 the already defined term SET Recipient rather than SET Receiver. 818 o Applied editorial and minor normative corrections. 820 o Updated Marius' contact information. 822 o Begun eliminating redundancies between this specification and 823 "Push-Based Security Event Token (SET) Delivery Using HTTP" 824 [I-D.ietf-secevent-http-push], referencing, rather that 825 duplicating common normative text. 827 Draft 02 - mbj: 829 o Removed vestigial language remaining from when the push and poll 830 delivery methods were defined in a common specification. 832 o Replaced remaining uses of the terms Event Transmitter and Event 833 Recipient with the correct terms SET Transmitter and SET 834 Recipient. 836 o Removed uses of the unnecessary term "Event Stream". 838 o Removed dependencies between the semantics of "maxEvents" and 839 "returnImmediately". 841 o Said that PII in SETs is to be encrypted with TLS, JWE, or both. 843 o Corrected grammar and spelling errors. 845 Draft 03 - mbj: 847 o Corrected uses of "attribute" to "member" when describing JSON 848 objects. 850 o Further alignment with the push draft. 852 Authors' Addresses 854 Annabelle Backman (editor) 855 Amazon 857 Email: richanna@amazon.com 858 Michael B. Jones (editor) 859 Microsoft 861 Email: mbj@microsoft.com 862 URI: http://self-issued.info/ 864 Marius Scurtescu 865 Coinbase 867 Email: marius.scurtescu@coinbase.com 869 Morteza Ansari 870 Cisco 872 Email: morteza.ansari@cisco.com 874 Anthony Nadalin 875 Microsoft 877 Email: tonynad@microsoft.com