idnits 2.17.1 draft-ietf-secevent-http-poll-11.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 date (June 15, 2020) is 1408 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) == Outdated reference: A later version (-14) exists of draft-ietf-secevent-http-push-11 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** 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: 5 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Security Events Working Group A. Backman, Ed. 3 Internet-Draft Amazon 4 Intended status: Standards Track M. Jones, Ed. 5 Expires: December 17, 2020 Microsoft 6 M. Scurtescu 7 Coinbase 8 M. Ansari 9 Cisco 10 A. Nadalin 11 Microsoft 12 June 15, 2020 14 Poll-Based Security Event Token (SET) Delivery Using HTTP 15 draft-ietf-secevent-http-poll-11 17 Abstract 19 This specification defines how a series of Security Event Tokens 20 (SETs) can 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 December 17, 2020. 42 Copyright Notice 44 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . . . . . . 9 72 2.5.1. Poll Error Response . . . . . . . . . . . . . . . . . 11 73 2.6. Error Response Handling . . . . . . . . . . . . . . . . . 11 74 3. Authentication and Authorization . . . . . . . . . . . . . . 12 75 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 76 4.1. Authentication Using Signed SETs . . . . . . . . . . . . 12 77 4.2. HTTP Considerations . . . . . . . . . . . . . . . . . . . 13 78 4.3. Confidentiality of SETs . . . . . . . . . . . . . . . . . 13 79 4.4. Access Token Considerations . . . . . . . . . . . . . . . 13 80 4.4.1. Bearer Token Considerations . . . . . . . . . . . . . 13 81 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 14 82 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 83 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 84 7.1. Normative References . . . . . . . . . . . . . . . . . . 14 85 7.2. Informative References . . . . . . . . . . . . . . . . . 16 86 Appendix A. Unencrypted Transport Considerations . . . . . . . . 16 87 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 17 88 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 17 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 91 1. Introduction and Overview 93 This specification defines how a stream of Security Event Tokens 94 (SETs) [RFC8417] can be transmitted to an intended SET Recipient 95 using HTTP [RFC7231] over TLS. The specification defines a method to 96 poll for SETs using HTTP POST. This is an alternative SET delivery 97 method to the one defined in [I-D.ietf-secevent-http-push]. 99 A mechanism for exchanging configuration metadata such as endpoint 100 URLs and cryptographic keys between the transmitter and recipient is 101 out of scope for this specification. How SETs are defined and the 102 process by which security events are identified for SET Recipients 103 are specified in [RFC8417]. 105 1.1. Notational Conventions 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 109 "OPTIONAL" in this document are to be interpreted as described in BCP 110 14 [RFC2119] [RFC8174] when, and only when, they appear in all 111 capitals, as shown here. 113 Throughout this document, all figures may contain spaces and extra 114 line wrapping for readability and due to space limitations. 116 1.2. Definitions 118 This specification utilizes terminology defined in [RFC8417] and 119 [I-D.ietf-secevent-http-push]. 121 2. SET Delivery 123 When a SET is available for a SET Recipient, the SET Transmitter 124 queues the SET in a buffer so that a SET Recipient can poll for SETs 125 using HTTP POST. 127 In poll-based SET delivery using HTTP over TLS, zero or more SETs are 128 delivered in a JSON [RFC8259] document to a SET Recipient in response 129 to an HTTP POST request to the SET Transmitter. Then in a following 130 request, the SET Recipient acknowledges received SETs and can poll 131 for more. All requests and responses are JSON documents and use a 132 "Content-Type" of "application/json", as described in Section 2.1. 134 After successful (acknowledged) SET delivery, SET Transmitters are 135 not required to retain or record SETs for retransmission. Once a SET 136 is acknowledged, the SET Recipient SHALL be responsible for 137 retention, if needed. Transmitters may also discard undelivered SETs 138 under deployment-specific conditions, such as if they have not been 139 polled for over too long a period of time or if an excessive amount 140 of storage is needed to retain them. 142 Upon receiving a SET, the SET Recipient reads the SET and validates 143 it in the manner described in Section 2 of 145 [I-D.ietf-secevent-http-push]. The SET Recipient MUST acknowledge 146 receipt to the SET Transmitter, and SHOULD do in a timely fashion, as 147 described in Section 2.4. The SET Recipient SHALL NOT use the event 148 acknowledgement mechanism to report event errors other than those 149 relating to the parsing and validation of the SET. 151 2.1. Polling Delivery using HTTP 153 This method allows a SET Recipient to use HTTP POST (Section 4.3.3 of 154 [RFC7231]) to acknowledge SETs and to check for and receive zero or 155 more SETs. Requests MAY be made at a periodic interval (short 156 polling) or requests MAY wait, pending availability of new SETs using 157 long polling, per Section 2 of [RFC6202]. Note that short polling 158 will result in retrieving zero or more SETs whereas long polling will 159 typically result in retrieving one or more SETs unless a timeout 160 occurs. 162 The delivery of SETs in this method is facilitated by HTTP POST 163 requests initiated by the SET Recipient in which: 165 o The SET Recipient makes a request for available SETs using an HTTP 166 POST to a pre-arranged endpoint provided by the SET Transmitter 167 or, 169 o after validating previously received SETs, the SET Recipient 170 initiates another poll request using HTTP POST that includes 171 acknowledgement of previous SETs and requests the next batch of 172 SETs. 174 The purpose of the acknowledgement is to inform the SET Transmitter 175 that delivery has succeeded and redelivery is no longer required. 176 Before acknowledgement, SET Recipients SHOULD ensure that received 177 SETs have been validated and retained in a manner appropriate to the 178 recipient's requirements. The level and method of retention of SETs 179 by SET Recipients is out of scope of this specification. 181 2.2. Polling HTTP Request 183 When initiating a poll request, the SET Recipient constructs a JSON 184 document that consists of polling request parameters and SET 185 acknowledgement parameters in the form of JSON objects. 187 When making a request, the HTTP header "Content-Type" is set to 188 "application/json". 190 The following JSON object members are used in a polling request: 192 Request Processing Parameters 193 maxEvents 194 An OPTIONAL JSON integer value indicating the maximum number of 195 unacknowledged SETs that SHOULD be returned. If more than the 196 maximum number of SETs are available, the oldest SETs available 197 SHOULD be returned first. A value of "0" MAY be used by SET 198 Recipients that would like to perform an acknowledge only 199 request. This enables the Recipient to use separate HTTP 200 requests for acknowledgement and reception of SETs. If this 201 parameter is omitted, no limit is placed on the number of SETs 202 to be returned. 204 returnImmediately 205 An OPTIONAL JSON boolean value that indicates the SET 206 Transmitter SHOULD return an immediate response even if no 207 results are available (short polling). The default value is 208 "false", which indicates the request is to be treated as an 209 HTTP Long Poll, per Section 2 of [RFC6202]. The timeout for 210 the request is part of the configuration between the 211 participants, which is out of scope of this specification. 213 SET Acknowledgment Parameters 215 ack 216 A JSON array of strings whose values are the "jti" values of 217 successfully received SETs that are being acknowledged. If 218 there are no outstanding SETs to acknowledge, this member is 219 omitted. Once a SET has been acknowledged, the SET Transmitter 220 is released from any obligation to retain the SET. 222 setErrs 223 A JSON object with one or more members whose keys are the "jti" 224 values of invalid SETs received. The values of these objects 225 are themselves JSON objects that describe the errors detected 226 using the "err" and "description" values specified in 227 Section 2.6. If there are no outstanding SETs with errors to 228 report, this member is omitted. 230 2.3. Polling HTTP Response 232 In response to a poll request, the SET Transmitter checks for 233 available SETs and responds with a JSON document containing the 234 following JSON object members: 236 sets 237 A JSON object containing zero or more SETs being returned. Each 238 member name is the "jti" of a SET to be delivered and its value is 239 a JSON string representing the corresponding SET. If there are no 240 outstanding SETs to be transmitted, the JSON object SHALL be 241 empty. 243 moreAvailable 244 A JSON boolean value that indicates if more unacknowledged SETs 245 are available to be returned. This member MAY be omitted, with 246 the meaning being the same as including it with the boolean value 247 "false". 249 When making a response, the HTTP header "Content-Type" is set to 250 "application/json". 252 2.4. Poll Request 254 The SET Recipient performs an HTTP POST (see Section 4.3.4 of 255 [RFC7231]) to a pre-arranged polling endpoint URI to check for SETs 256 that are available. Because the SET Recipient has no prior SETs to 257 acknowledge, the "ack" and "setErrs" request parameters are omitted. 259 After a period of time configured between the SET Transmitter and 260 Recipient, a SET Transmitter MAY redeliver SETs it has previously 261 delivered. The SET Recipient SHOULD accept repeat SETs and 262 acknowledge the SETs regardless of whether the Recipient believes it 263 has already acknowledged the SETs previously. A SET Transmitter MAY 264 limit the number of times it attempts to deliver a SET. 266 If the SET Recipient has received SETs from the SET Transmitter, the 267 SET Recipient SHOULD parse and validate received SETs to meet its own 268 requirements and SHOULD acknowledge receipt in a timely fashion 269 (e.g., seconds or minutes) so that the SET Transmitter can mark the 270 SETs as received. SET Recipients SHOULD acknowledge receipt before 271 taking any local actions based on the SETs to avoid unnecessary delay 272 in acknowledgement, where possible. 274 Poll requests have three variations: 276 Poll Only 277 In which a SET Recipient asks for the next set of events where no 278 previous SET deliveries are acknowledged (such as in the initial 279 poll request). 281 Acknowledge Only 282 In which a SET Recipient sets the "maxEvents" value to "0" along 283 with "ack" and "setErrs" members indicating the SET Recipient is 284 acknowledging previously received SETs and does not want to 285 receive any new SETs in response to the request. 287 Combined Acknowledge and Poll 288 In which a SET Recipient is both acknowledging previously received 289 SETs using the "ack" and "setErrs" members and will wait for the 290 next group of SETs in the SET Transmitters response. 292 2.4.1. Poll Only Request 294 In the case where no SETs were received in a previous poll (see 295 Figure 7), the SET Recipient simply polls without acknowledgement 296 parameters ("ack" and "setErrs"). 298 The following is an example request made by a SET Recipient that has 299 no outstanding SETs to acknowledge and is polling for available SETs 300 at the endpoint "https://notify.idp.example.com/Events": 302 POST /Events HTTP/1.1 303 Host: notify.idp.example.com 304 Content-Type: application/json 306 { 307 "returnImmediately": true 308 } 310 Figure 1: Example Initial Poll Request 312 A SET Recipient can poll using default parameter values by passing an 313 empty JSON object. 315 The following is a non-normative example default poll request to the 316 endpoint "https://notify.idp.example.com/Events": 318 POST /Events HTTP/1.1 319 Host: notify.idp.example.com 320 Content-Type: application/json 322 {} 324 Figure 2: Example Default Poll Request 326 2.4.2. Acknowledge Only Request 328 In this variation, the SET Recipient acknowledges previously received 329 SETs and indicates it does not want to receive SETs in response by 330 setting the "maxEvents" value to "0". 332 This variation might be used, for instance, when a SET Recipient 333 needs to acknowledge received SETs independently (e.g., on separate 334 threads) from the process of receiving SETs. 336 The following is a non-normative example poll request with 337 acknowledgement of SETs received (for example as shown in Figure 6): 339 POST /Events HTTP/1.1 340 Host: notify.idp.example.com 341 Content-Type: application/json 343 { 344 "ack": [ 345 "4d3559ec67504aaba65d40b0363faad8", 346 "3d0c3cf797584bd193bd0fb1bd4e7d30" 347 ], 348 "maxEvents": 0, 349 "returnImmediately": true 350 } 352 Figure 3: Example Acknowledge Only Request 354 2.4.3. Poll with Acknowledgement 356 This variation allows a recipient thread to simultaneously 357 acknowledge previously received SETs and wait for the next group of 358 SETs in a single request. 360 The following is a non-normative example poll with acknowledgement of 361 the SETs received in Figure 6: 363 POST /Events HTTP/1.1 364 Host: notify.idp.example.com 365 Content-Type: application/json 367 { 368 "ack": [ 369 "4d3559ec67504aaba65d40b0363faad8", 370 "3d0c3cf797584bd193bd0fb1bd4e7d30" 371 ], 372 "returnImmediately": false 373 } 375 Figure 4: Example Poll with Acknowledgement and No Errors 377 In the above acknowledgement, the SET Recipient has acknowledged 378 receipt of two SETs and has indicated it wants to wait until the next 379 SET is available. 381 2.4.4. Poll with Acknowledgement and Errors 383 In the case where errors were detected in previously delivered SETs, 384 the SET Recipient MAY use the "setErrs" member to communicate the 385 errors in the following poll request. 387 The following is a non-normative example of a response acknowledging 388 one successfully received SET and one SET with an error from the two 389 SETs received in Figure 6: 391 POST /Events HTTP/1.1 392 Host: notify.idp.example.com 393 Content-Language: en-US 394 Content-Type: application/json 396 { 397 "ack": ["3d0c3cf797584bd193bd0fb1bd4e7d30"], 398 "setErrs": { 399 "4d3559ec67504aaba65d40b0363faad8": { 400 "err": "authentication_failed", 401 "description": "The SET could not be authenticated" 402 } 403 }, 404 "returnImmediately": true 405 } 407 Figure 5: Example Poll Acknowledgement with Error 409 2.5. Poll Response 411 In response to a valid poll request, the service provider MAY respond 412 immediately if SETs are available to be delivered. If no SETs are 413 available at the time of the request, the SET Transmitter SHALL delay 414 responding until a SET is available or the timeout interval has 415 elapsed unless the poll request parameter "returnImmediately" is 416 present with the value "true". 418 As described in Section 2.3, a JSON document is returned containing 419 members including "sets", which SHALL contain zero or more SETs. 421 The following is a non-normative example response to the request 422 shown in Section 2.4. This example shows two SETs being returned: 424 HTTP/1.1 200 OK 425 Content-Type: application/json 427 { 428 "sets": { 429 "4d3559ec67504aaba65d40b0363faad8": 430 "eyJhbGciOiJub25lIn0. 431 eyJqdGkiOiI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsImlhdCI6MTQ 432 1ODQ5NjQwNCwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbIm 433 h0dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M 434 2I3NzU0IiwiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIx 435 ZDA4NjQxZDc2NzZlZTciXSwiZXZlbnRzIjp7InVybjppZXRmOnBhcmFtczpzY2ltOmV 436 2ZW50OmNyZWF0ZSI6eyJyZWYiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcn 437 MvNDRmNjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsImF0dHJpYnV0ZXMiOlsiaWQiLCJuY 438 W1lIiwidXNlck5hbWUiLCJwYXNzd29yZCIsImVtYWlscyJdfX19.", 439 "3d0c3cf797584bd193bd0fb1bd4e7d30": 440 "eyJhbGciOiJub25lIn0. 441 eyJqdGkiOiIzZDBjM2NmNzk3NTg0YmQxOTNiZDBmYjFiZDRlN2QzMCIsImlhdCI6MTQ 442 1ODQ5NjAyNSwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbIm 443 h0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M 444 2I3NzU0IiwiaHR0cHM6Ly9qaHViLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIx 445 ZDA4NjQxZDc2NzZlZTciXSwic3ViIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL1V 446 zZXJzLzQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkiLCJldmVudHMiOnsidXJuOmlldG 447 Y6cGFyYW1zOnNjaW06ZXZlbnQ6cGFzc3dvcmRSZXNldCI6eyJpZCI6IjQ0ZjYxNDJkZ 448 jk2YmQ2YWI2MWU3NTIxZDkifSwiaHR0cHM6Ly9leGFtcGxlLmNvbS9zY2ltL2V2ZW50 449 L3Bhc3N3b3JkUmVzZXRFeHQiOnsicmVzZXRBdHRlbXB0cyI6NX19fQ." 450 } 451 } 453 Figure 6: Example Poll Response 455 In the above example, two SETs whose "jti" values are 456 "4d3559ec67504aaba65d40b0363faad8" and 457 "3d0c3cf797584bd193bd0fb1bd4e7d30" are delivered. 459 The following is a non-normative example response to the request 460 shown in Section 2.4.1, which indicates that no new SETs or 461 unacknowledged SETs are available: 463 HTTP/1.1 200 OK 464 Content-Type: application/json 466 { 467 "sets": {} 468 } 470 Figure 7: Example No SETs Poll Response 472 Upon receiving the JSON document (e.g., as shown in Figure 6), the 473 SET Recipient parses and verifies the received SETs and notifies the 474 SET Transmitter of successfully received SETs and SETs with errors 475 via the next poll request to the SET Transmitter, as described in 476 Section 2.4.3 or Section 2.4.4. 478 2.5.1. Poll Error Response 480 In the event of a general HTTP error condition in the context of 481 processing a poll request, the service provider SHOULD respond with 482 an appropriate HTTP Response Status Code as defined in Section 6 of 483 [RFC7231]. 485 Service providers MAY respond to any invalid poll request with an 486 HTTP Response Status Code of 400 (Bad Request) even when a more 487 specific code might apply, for example if the service provider deemed 488 that a more specific code presented an information disclosure risk. 489 When no more specific code might apply, the service provider SHALL 490 respond to an invalid poll request with an HTTP Status Code of 400. 492 The response body for responses to invalid poll requests is left 493 undefined, and its contents SHOULD be ignored. 495 The following is a non-normative example of a response to an invalid 496 poll request: 498 HTTP/1.1 400 Bad Request 500 Example Poll Error Response 502 2.6. Error Response Handling 504 If a SET is invalid, error codes from the IANA "Security Event Token 505 Delivery Error Codes" registry established by 506 [I-D.ietf-secevent-http-push] are used in error responses. As 507 described in Section 2.3 of [I-D.ietf-secevent-http-push], an error 508 response is a JSON object providing details about the error that 509 includes the following name/value pairs: 511 err 512 A value from the IANA "Security Event Token Delivery Error Codes" 513 registry that identifies the error. 515 description 516 A human-readable string that provides additional diagnostic 517 information. 519 When included as part of a batch of SETs, the above JSON is included 520 as part of the "setErrs" member, as defined in Section 2.2 and 521 Section 2.4.4. 523 When the SET Recipient includes one or more error responses in a 524 request to the SET Transmitter, it must also include in the request a 525 "Content-Language" header whose value indicates the language of the 526 error descriptions included in the request. The method of language 527 selection in the case when the SET Recipient can provide error 528 messages in multiple languages is out of scope for this 529 specification. 531 3. Authentication and Authorization 533 The SET delivery method described in this specification is based upon 534 HTTP over TLS [RFC2818] and standard HTTP authentication and 535 authorization schemes, as per [RFC7235]. The TLS server certificate 536 MUST be validated, per [RFC6125]. As per Section 4.1 of [RFC7235], a 537 SET delivery endpoint SHALL indicate supported HTTP authentication 538 schemes via the "WWW-Authenticate" header when using HTTP 539 authentication. 541 Authorization for the eligibility to provide actionable SETs can be 542 determined by using the identity of the SET Issuer, validating the 543 polling endpoint URL, perhaps using mutual TLS, or via other employed 544 authentication methods. Because SETs are not commands, SET 545 Recipients are free to ignore SETs that are not of interest after 546 acknowledging their receipt. 548 4. Security Considerations 550 4.1. Authentication Using Signed SETs 552 JWS signed SETs can be used (see [RFC7515] and Section 5 of 553 [RFC8417]) to enable the SET Recipient to validate that the SET 554 Issuer is authorized to provide actionable SETs. 556 4.2. HTTP Considerations 558 SET delivery depends on the use of Hypertext Transfer Protocol and is 559 thus subject to the security considerations of HTTP Section 9 of 560 [RFC7230] and its related specifications. 562 4.3. Confidentiality of SETs 564 SETs may contain sensitive information that is considered Personally 565 Identifiable Information (PII). In such cases, SET Transmitters and 566 SET Recipients MUST protect the confidentiality of the SET contents. 567 In some use cases, using TLS to secure the transmitted SETs will be 568 sufficient. In other use cases, encrypting the SET as described in 569 JWE [RFC7516] will also be required. The Event delivery endpoint 570 MUST support at least TLS version 1.2 [RFC5246] and SHOULD support 571 the newest version of TLS that meets its security requirements, which 572 as of the time of this publication is TLS 1.3 [RFC8446]. The client 573 MUST perform a TLS/SSL server certificate check using DNS-ID 574 [RFC6125]. How a SET Recipient determines the expected service 575 identity to match the SET Transmitter's server certificate against is 576 out of scope for this document. Implementation security 577 considerations for TLS can be found in "Recommendations for Secure 578 Use of TLS and DTLS" [RFC7525]. 580 4.4. Access Token Considerations 582 If HTTP Authentication is performed using OAuth access tokens 583 [RFC6749], implementers MUST take into account the threats and 584 countermeasures documented in Section 8 of [RFC7521]. 586 4.4.1. Bearer Token Considerations 588 Transmitting Bearer tokens [RFC6750] using TLS helps prevent their 589 interception. 591 Bearer tokens SHOULD have a limited lifetime that can be determined 592 directly or indirectly (e.g., by checking with a validation service) 593 by the service provider. By expiring tokens, clients are forced to 594 obtain a new token (which usually involves re-authentication) for 595 continued authorized access. For example, in OAuth 2.0, a client MAY 596 use an OAuth refresh token to obtain a new bearer token after 597 authenticating to an authorization server, per Section 6 of 598 [RFC6749]. 600 Implementations supporting OAuth bearer tokens need to factor in 601 security considerations of this authorization method [RFC7521]. 602 Since security is only as good as the weakest link, implementers also 603 need to consider authentication choices coupled with OAuth bearer 604 tokens. The security considerations of the default authentication 605 method for OAuth bearer tokens, HTTP Basic, are well documented in 606 [RFC7617], therefore implementers are encouraged to prefer stronger 607 authentication methods. 609 5. Privacy Considerations 611 SET Transmitters SHOULD attempt to deliver SETs that are targeted to 612 the specific business and protocol needs of subscribers. 614 When sharing personally identifiable information or information that 615 is otherwise considered confidential to affected users, SET 616 Transmitters and Recipients MUST have the appropriate legal 617 agreements and user consent or terms of service in place. 618 Furthermore, data that needs confidentiality protection MUST be 619 encrypted, at least with TLS and sometimes also using JSON Web 620 Encryption (JWE) [RFC7516]. 622 In some cases, subject identifiers themselves may be considered 623 sensitive information, such that their inclusion within a SET may be 624 considered a violation of privacy. SET Issuers should consider the 625 ramifications of sharing a particular subject identifier with a SET 626 Recipient (e.g., whether doing so could enable correlation and/or de- 627 anonymization of data) and choose appropriate subject identifiers for 628 their use cases. 630 6. IANA Considerations 632 This specification requires no IANA actions. 634 7. References 636 7.1. Normative References 638 [I-D.ietf-secevent-http-push] 639 Backman, A., Jones, M., Scurtescu, M., Ansari, M., and A. 640 Nadalin, "Push-Based Security Event Token (SET) Delivery 641 Using HTTP", draft-ietf-secevent-http-push-11 (work in 642 progress), June 2020. 644 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 645 Requirement Levels", BCP 14, RFC 2119, 646 DOI 10.17487/RFC2119, March 1997, 647 . 649 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 650 DOI 10.17487/RFC2818, May 2000, 651 . 653 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 654 (TLS) Protocol Version 1.2", RFC 5246, 655 DOI 10.17487/RFC5246, August 2008, 656 . 658 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 659 Verification of Domain-Based Application Service Identity 660 within Internet Public Key Infrastructure Using X.509 661 (PKIX) Certificates in the Context of Transport Layer 662 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 663 2011, . 665 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 666 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 667 DOI 10.17487/RFC7231, June 2014, 668 . 670 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 671 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 672 2015, . 674 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 675 RFC 7516, DOI 10.17487/RFC7516, May 2015, 676 . 678 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 679 "Assertion Framework for OAuth 2.0 Client Authentication 680 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 681 May 2015, . 683 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 684 "Recommendations for Secure Use of Transport Layer 685 Security (TLS) and Datagram Transport Layer Security 686 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 687 2015, . 689 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 690 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 691 May 2017, . 693 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 694 Interchange Format", STD 90, RFC 8259, 695 DOI 10.17487/RFC8259, December 2017, 696 . 698 [RFC8417] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, 699 "Security Event Token (SET)", RFC 8417, 700 DOI 10.17487/RFC8417, July 2018, 701 . 703 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 704 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 705 . 707 7.2. Informative References 709 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 710 "Known Issues and Best Practices for the Use of Long 711 Polling and Streaming in Bidirectional HTTP", RFC 6202, 712 DOI 10.17487/RFC6202, April 2011, 713 . 715 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 716 RFC 6749, DOI 10.17487/RFC6749, October 2012, 717 . 719 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 720 Framework: Bearer Token Usage", RFC 6750, 721 DOI 10.17487/RFC6750, October 2012, 722 . 724 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 725 Protocol (HTTP/1.1): Message Syntax and Routing", 726 RFC 7230, DOI 10.17487/RFC7230, June 2014, 727 . 729 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 730 Protocol (HTTP/1.1): Authentication", RFC 7235, 731 DOI 10.17487/RFC7235, June 2014, 732 . 734 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 735 RFC 7617, DOI 10.17487/RFC7617, September 2015, 736 . 738 Appendix A. Unencrypted Transport Considerations 740 Earlier versions of this specification made the use of TLS optional 741 and described security and privacy considerations resulting from use 742 of unencrypted HTTP as the underlying transport. When the working 743 group decided to mandate usage HTTP over TLS, it also decided to 744 preserve the description of these considerations in a non-normative 745 manner. 747 The considerations for using unencrypted HTTP with this protocol are 748 the same as those described in Appendix A of 749 [I-D.ietf-secevent-http-push], and are therefore not repeated here. 751 Appendix B. Acknowledgments 753 The editors would like to thank the members of the SCIM working 754 group, which began discussions of provisioning events starting with 755 draft-hunt-scim-notify-00 in 2015. We would like to thank Phil Hunt 756 and the other the authors of draft-ietf-secevent-delivery-02, upon 757 which this specification is based. We would like to thank the 758 participants in the SecEvents working group for their contributions 759 to this specification. 761 Additionally, we would like to thank the following individuals for 762 their reviews of the specification: Benjamin Kaduk, Mark Nottingham, 763 Yaron Sheffer, Valery Smyslov, and Robert Sparks. 765 Appendix C. Change Log 767 [[ to be removed by the RFC Editor before publication as an RFC ]] 769 Draft 00 - AB - Based on draft-ietf-secevent-delivery-02 with the 770 following additions: 772 o Renamed to "Poll-Based SET Token Delivery Using HTTP" 774 o Removed references to the HTTP Push delivery method. 776 Draft 01 - mbj: 778 o Addressed problems identified in my 18-Jul-18 review message 779 titled "Issues for both the Push and Poll Specs". 781 o Changes to align terminology with RFC 8417, for instance, by using 782 the already defined term SET Recipient rather than SET Receiver. 784 o Applied editorial and minor normative corrections. 786 o Updated Marius' contact information. 788 o Begun eliminating redundancies between this specification and 789 "Push-Based Security Event Token (SET) Delivery Using HTTP" 790 [I-D.ietf-secevent-http-push], referencing, rather that 791 duplicating common normative text. 793 Draft 02 - mbj: 795 o Removed vestigial language remaining from when the push and poll 796 delivery methods were defined in a common specification. 798 o Replaced remaining uses of the terms Event Transmitter and Event 799 Recipient with the correct terms SET Transmitter and SET 800 Recipient. 802 o Removed uses of the unnecessary term "Event Stream". 804 o Removed dependencies between the semantics of "maxEvents" and 805 "returnImmediately". 807 o Said that PII in SETs is to be encrypted with TLS, JWE, or both. 809 o Corrected grammar and spelling errors. 811 Draft 03 - mbj: 813 o Corrected uses of "attribute" to "member" when describing JSON 814 objects. 816 o Further alignment with the push draft. 818 Draft 04 - AB + mbj 820 o Referenced SET Transmitter definition in http-push. 822 o Removed incorrect normative text regarding SET construction. 824 o Consolidated general out-of-scope items under Introduction. 826 o Removed unnecessary HTTP headers in examples and added Content- 827 Type. 829 o Added Content-Language requirement for error descriptions, 830 aligning with http-push. 832 o Stated that bearer tokens SHOULD have a limited lifetime. 834 o Minor editorial fixes. 836 Draft 05 - AB + mbj 838 o Added normative text defining how to respond to invalid poll 839 requests. 841 o Addressed shepherd comments by Yaron Sheffer. 843 Draft 06 - mbj 845 o Addressed nits identified by the idnits tool. 847 Draft 07 - mbj 849 o Addressed area director review comments by Benjamin Kaduk. 851 Draft 08 - mbj + AB 853 o Corrected editorial nits. 855 Draft 09 - AB 857 o Addressed area director review comments by Benjamin Kaduk: 859 * Added text clarifying that determining the SET Recipient's 860 service identity is out of scope. 862 * Removed unelaborated reference to use of authentication to 863 prevent DoS attacks. 865 Draft 10 - mbj 867 o Addressed SecDir review comments by Valery Smyslov on draft-ietf- 868 secevent-http-push-10 that also applied here. 870 o Addressed IETF last call comments by Mark Nottingham. 872 o Addressed GenArt review comments by Robert Sparks. 874 Draft 11 - mbj 876 o Revised to unambiguously require the use of TLS, while preserving 877 descriptions of precautions needed for non-TLS use in an appendix. 879 Authors' Addresses 881 Annabelle Backman (editor) 882 Amazon 884 Email: richanna@amazon.com 885 Michael B. Jones (editor) 886 Microsoft 888 Email: mbj@microsoft.com 889 URI: https://self-issued.info/ 891 Marius Scurtescu 892 Coinbase 894 Email: marius.scurtescu@coinbase.com 896 Morteza Ansari 897 Cisco 899 Email: morteza.ansari@cisco.com 901 Anthony Nadalin 902 Microsoft 904 Email: tonynad@microsoft.com