idnits 2.17.1 draft-ietf-secevent-http-poll-07.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 (February 5, 2020) is 1513 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-07 ** 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: August 8, 2020 Microsoft 6 M. Scurtescu 7 Coinbase 8 M. Ansari 9 Cisco 10 A. Nadalin 11 Microsoft 12 February 5, 2020 14 Poll-Based Security Event Token (SET) Delivery Using HTTP 15 draft-ietf-secevent-http-poll-07 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 August 8, 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 . . . . . . . . . . . . 13 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. Acknowledgments . . . . . . . . . . . . . . . . . . 17 87 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 17 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. This is an alternative SET delivery 96 method to the one defined in [I-D.ietf-secevent-http-push]. 98 A mechanism for exchanging configuration metadata such as endpoint 99 URLs and cryptographic keys between the transmitter and recipient is 100 out of scope for this specification. How SETs are defined and the 101 process by which security events are identified for SET Recipients 102 are specified in [RFC8417]. 104 1.1. Notational Conventions 106 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 107 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 108 "OPTIONAL" in this document are to be interpreted as described in BCP 109 14 [RFC2119] [RFC8174] when, and only when, they appear in all 110 capitals, as shown here. 112 Throughout this document, all figures may contain spaces and extra 113 line wrapping for readability and due to space limitations. 115 1.2. Definitions 117 This specification utilizes terminology defined in [RFC8417] and 118 [I-D.ietf-secevent-http-push]. 120 2. SET Delivery 122 When a SET is available for a SET Recipient, the SET Transmitter 123 queues the SET in a buffer so that a SET Recipient can poll for SETs 124 using HTTP/1.1 POST. 126 In Poll-Based SET Delivery Using HTTP, zero or more SETs are 127 delivered in a JSON [RFC8259] document to a SET Recipient in response 128 to an HTTP POST request to the SET Transmitter. Then in a following 129 request, the SET Recipient acknowledges received SETs and can poll 130 for more. All requests and responses are JSON documents and use a 131 "Content-Type" of "application/json", as described in Section 2.1. 133 After successful (acknowledged) SET delivery, SET Transmitters are 134 not required to retain or record SETs for retransmission. Once a SET 135 is acknowledged, the SET Recipient SHALL be responsible for 136 retention, if needed. 138 Upon receiving a SET, the SET Recipient reads the SET and validates 139 it in the manner described in Section 2 of 140 [I-D.ietf-secevent-http-push]. The SET Recipient MUST acknowledge 141 receipt to the SET Transmitter, and SHOULD do in a timely fashion, as 142 described in Section 2.4. The SET Recipient SHALL NOT use the event 143 acknowledgement mechanism to report event errors other than those 144 relating to the parsing and validation of the SET. 146 2.1. Polling Delivery using HTTP 148 This method allows a SET Recipient to use HTTP POST (Section 4.3.3 of 149 [RFC7231]) to acknowledge SETs and to check for and receive zero or 150 more SETs. Requests MAY be made at a periodic interval (short 151 polling) or requests MAY wait, pending availability of new SETs using 152 long polling, per Section 2 of [RFC6202]. Note that short polling 153 will result in retrieving zero or more SETs whereas long polling will 154 typically result in retrieving one or more SETs unless a timeout 155 occurs. 157 The delivery of SETs in this method is facilitated by HTTP POST 158 requests initiated by the SET Recipient in which: 160 o The SET Recipient makes a request for available SETs using an HTTP 161 POST to a pre-arranged endpoint provided by the SET Transmitter 162 or, 164 o after validating previously received SETs, the SET Recipient 165 initiates another poll request using HTTP POST that includes 166 acknowledgement of previous SETs and requests the next batch of 167 SETs. 169 The purpose of the acknowledgement is to inform the SET Transmitter 170 that delivery has succeeded and redelivery is no longer required. 171 Before acknowledgement, SET Recipients SHOULD ensure that received 172 SETs have been validated and retained in a manner appropriate to the 173 recipient's requirements. The level and method of retention of SETs 174 by SET Recipients is out of scope of this specification. 176 2.2. Polling HTTP Request 178 When initiating a poll request, the SET Recipient constructs a JSON 179 document that consists of polling request parameters and SET 180 acknowledgement parameters in the form of JSON objects. 182 When making a request, the HTTP header "Content-Type" is set to 183 "application/json". 185 The following JSON object members are used in a polling request: 187 Request Processing Parameters 189 maxEvents 190 An OPTIONAL JSON integer value indicating the maximum number of 191 unacknowledged SETs that SHOULD be returned. If more than the 192 maximum number of SETs are available, the oldest SETs available 193 SHOULD be returned first. A value of "0" MAY be used by SET 194 Recipients that would like to perform an acknowledge only 195 request. This enables the Recipient to use separate HTTP 196 requests for acknowledgement and reception of SETs. If this 197 parameter is omitted, no limit is placed on the number of SETs 198 to be returned. 200 returnImmediately 201 An OPTIONAL JSON boolean value that indicates the SET 202 Transmitter SHOULD return an immediate response even if no 203 results are available (short polling). The default value is 204 "false", which indicates the request is to be treated as an 205 HTTP Long Poll, per Section 2 of [RFC6202]. The timeout for 206 the request is part of the configuration between the 207 participants, which is out of scope of this specification. 209 SET Acknowledgment Parameters 211 ack 212 A JSON array of strings whose values are the "jti" values of 213 successfully received SETs that are being acknowledged. If 214 there are no outstanding SETs to acknowledge, this member is 215 omitted. Once a SET has been acknowledged, the SET Transmitter 216 is released from any obligation to retain the SET. 218 setErrs 219 A JSON object with one or more members whose keys are the "jti" 220 values of invalid SETs received. The values of these objects 221 are themselves JSON objects that describe the errors detected 222 using the "err" and "description" values specified in 223 Section 2.6. If there are no outstanding SETs with errors to 224 report, this member is omitted. 226 2.3. Polling HTTP Response 228 In response to a poll request, the SET Transmitter checks for 229 available SETs and responds with a JSON document containing the 230 following JSON object members: 232 sets 233 A JSON object containing zero or more SETs being returned. Each 234 member name is the "jti" of a SET to be delivered and its value is 235 a JSON string representing the corresponding SET. If there are no 236 outstanding SETs to be transmitted, the JSON object SHALL be 237 empty. 239 moreAvailable 240 A JSON boolean value that indicates if more unacknowledged SETs 241 are available to be returned. This member MAY be omitted, with 242 the meaning being the same as including it with the boolean value 243 "false". 245 When making a response, the HTTP header "Content-Type" is set to 246 "application/json". 248 2.4. Poll Request 250 The SET Recipient performs an HTTP POST (see Section 4.3.4 of 251 [RFC7231]) to a pre-arranged polling endpoint URI to check for SETs 252 that are available. Because the SET Recipient has no prior SETs to 253 acknowledge, the "ack" and "setErrs" request parameters are omitted. 255 After a period of time configured between the SET Transmitter and 256 Recipient, a SET Transmitter MAY redeliver SETs it has previously 257 delivered. The SET Recipient SHOULD accept repeat SETs and 258 acknowledge the SETs regardless of whether the Recipient believes it 259 has already acknowledged the SETs previously. A SET Transmitter MAY 260 limit the number of times it attempts to deliver a SET. 262 If the SET Recipient has received SETs from the SET Transmitter, the 263 SET Recipient SHOULD parse and validate received SETs to meet its own 264 requirements and SHOULD acknowledge receipt in a timely fashion 265 (e.g., seconds or minutes) so that the SET Transmitter can mark the 266 SETs as received. SET Recipients SHOULD acknowledge receipt before 267 taking any local actions based on the SETs to avoid unnecessary delay 268 in acknowledgement, where possible. 270 Poll requests have three variations: 272 Poll Only 273 In which a SET Recipient asks for the next set of events where no 274 previous SET deliveries are acknowledged (such as in the initial 275 poll request). 277 Acknowledge Only 278 In which a SET Recipient sets the "maxEvents" value to "0" along 279 with "ack" and "setErrs" members indicating the SET Recipient is 280 acknowledging previously received SETs and does not want to 281 receive any new SETs in response to the request. 283 Combined Acknowledge and Poll 284 In which a SET Recipient is both acknowledging previously received 285 SETs using the "ack" and "setErrs" members and will wait for the 286 next group of SETs in the SET Transmitters response. 288 2.4.1. Poll Only Request 290 In the case where no SETs were received in a previous poll (see 291 Figure 7), the SET Recipient simply polls without acknowledgement 292 parameters ("ack" and "setErrs"). 294 The following is an example request made by a SET Recipient that has 295 no outstanding SETs to acknowledge and is polling for available SETs 296 at the endpoint "https://notify.idp.example.com/Events": 298 POST /Events HTTP/1.1 299 Host: notify.idp.example.com 300 Content-Type: application/json 302 { 303 "returnImmediately": true 304 } 306 Figure 1: Example Initial Poll Request 308 A SET Recipient can poll using default parameter values by passing an 309 empty JSON object. 311 The following is a non-normative example default poll request to the 312 endpoint "https://notify.idp.example.com/Events": 314 POST /Events HTTP/1.1 315 Host: notify.idp.example.com 316 Content-Type: application/json 318 {} 320 Figure 2: Example Default Poll Request 322 2.4.2. Acknowledge Only Request 324 In this variation, the SET Recipient acknowledges previously received 325 SETs and indicates it does not want to receive SETs in response by 326 setting the "maxEvents" value to "0". 328 This variation might be used, for instance, when a SET Recipient 329 needs to acknowledge received SETs independently (e.g., on separate 330 threads) from the process of receiving SETs. 332 The following is a non-normative example poll request with 333 acknowledgement of SETs received (for example as shown in Figure 6): 335 POST /Events HTTP/1.1 336 Host: notify.idp.example.com 337 Content-Type: application/json 339 { 340 "ack": [ 341 "4d3559ec67504aaba65d40b0363faad8", 342 "3d0c3cf797584bd193bd0fb1bd4e7d30" 343 ], 344 "maxEvents": 0, 345 "returnImmediately": true 346 } 348 Figure 3: Example Acknowledge Only Request 350 2.4.3. Poll with Acknowledgement 352 This variation allows a recipient thread to simultaneously 353 acknowledge previously received SETs and wait for the next group of 354 SETs in a single request. 356 The following is a non-normative example poll with acknowledgement of 357 the SETs received in Figure 6: 359 POST /Events HTTP/1.1 360 Host: notify.idp.example.com 361 Content-Type: application/json 363 { 364 "ack": [ 365 "4d3559ec67504aaba65d40b0363faad8", 366 "3d0c3cf797584bd193bd0fb1bd4e7d30" 367 ], 368 "returnImmediately": false 369 } 371 Figure 4: Example Poll with Acknowledgement and No Errors 373 In the above acknowledgement, the SET Recipient has acknowledged 374 receipt of two SETs and has indicated it wants to wait until the next 375 SET is available. 377 2.4.4. Poll with Acknowledgement and Errors 379 In the case where errors were detected in previously delivered SETs, 380 the SET Recipient MAY use the "setErrs" member to communicate the 381 errors in the following poll request. 383 The following is a non-normative example of a response acknowledging 384 one successfully received SET and one SET with an error from the two 385 SETs received in Figure 6: 387 POST /Events HTTP/1.1 388 Host: notify.idp.example.com 389 Content-Language: en-US 390 Content-Type: application/json 392 { 393 "ack": ["3d0c3cf797584bd193bd0fb1bd4e7d30"], 394 "setErrs": { 395 "4d3559ec67504aaba65d40b0363faad8": { 396 "err": "authentication_failed", 397 "description": "The SET could not be authenticated" 398 } 399 }, 400 "returnImmediately": true 401 } 403 Figure 5: Example Poll Acknowledgement with Error 405 2.5. Poll Response 407 In response to a valid poll request, the service provider MAY respond 408 immediately if SETs are available to be delivered. If no SETs are 409 available at the time of the request, the SET Transmitter SHALL delay 410 responding until a SET is available or the timeout interval has 411 elapsed unless the poll request parameter "returnImmediately" is 412 present with the value "true". 414 As described in Section 2.3, a JSON document is returned containing 415 members including "sets", which SHALL contain zero or more SETs. 417 The following is a non-normative example response to the request 418 shown in Section 2.4. This example shows two SETs being returned: 420 HTTP/1.1 200 OK 421 Content-Type: application/json 423 { 424 "sets": { 425 "4d3559ec67504aaba65d40b0363faad8": 426 "eyJhbGciOiJub25lIn0. 427 eyJqdGkiOiI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsImlhdCI6MTQ 428 1ODQ5NjQwNCwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbIm 429 h0dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M 430 2I3NzU0IiwiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIx 431 ZDA4NjQxZDc2NzZlZTciXSwiZXZlbnRzIjp7InVybjppZXRmOnBhcmFtczpzY2ltOmV 432 2ZW50OmNyZWF0ZSI6eyJyZWYiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcn 433 MvNDRmNjE0MmRmOTZiZDZhYjYxZTc1MjFkOSIsImF0dHJpYnV0ZXMiOlsiaWQiLCJuY 434 W1lIiwidXNlck5hbWUiLCJwYXNzd29yZCIsImVtYWlscyJdfX19.", 435 "3d0c3cf797584bd193bd0fb1bd4e7d30": 436 "eyJhbGciOiJub25lIn0. 437 eyJqdGkiOiIzZDBjM2NmNzk3NTg0YmQxOTNiZDBmYjFiZDRlN2QzMCIsImlhdCI6MTQ 438 1ODQ5NjAyNSwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwiYXVkIjpbIm 439 h0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MWZhNWJiYzg3OTU5M 440 2I3NzU0IiwiaHR0cHM6Ly9qaHViLmV4YW1wbGUuY29tL0ZlZWRzLzVkNzYwNDUxNmIx 441 ZDA4NjQxZDc2NzZlZTciXSwic3ViIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL1V 442 zZXJzLzQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkiLCJldmVudHMiOnsidXJuOmlldG 443 Y6cGFyYW1zOnNjaW06ZXZlbnQ6cGFzc3dvcmRSZXNldCI6eyJpZCI6IjQ0ZjYxNDJkZ 444 jk2YmQ2YWI2MWU3NTIxZDkifSwiaHR0cHM6Ly9leGFtcGxlLmNvbS9zY2ltL2V2ZW50 445 L3Bhc3N3b3JkUmVzZXRFeHQiOnsicmVzZXRBdHRlbXB0cyI6NX19fQ." 446 } 447 } 449 Figure 6: Example Poll Response 451 In the above example, two SETs whose "jti" values are 452 "4d3559ec67504aaba65d40b0363faad8" and 453 "3d0c3cf797584bd193bd0fb1bd4e7d30" are delivered. 455 The following is a non-normative example response to the request 456 shown in Section 2.4.1, which indicates that no new SETs or 457 unacknowledged SETs are available: 459 HTTP/1.1 200 OK 460 Content-Type: application/json 462 { 463 "sets": {} 464 } 466 Figure 7: Example No SETs Poll Response 468 Upon receiving the JSON document (e.g., as shown in Figure 6), the 469 SET Recipient parses and verifies the received SETs and notifies the 470 SET Transmitter of successfully received SETs and SETs with errors 471 via the next poll request to the SET Transmitter, as described in 472 Section 2.4.3 or Section 2.4.4. 474 2.5.1. Poll Error Response 476 In the event of a general HTTP error condition in the context of 477 processing a poll request, the service provider SHOULD respond with 478 an appropriate HTTP Response Status Code as defined in Section 6 of 479 [RFC7231]. 481 Service providers MAY respond to any invalid poll request with an 482 HTTP Response Status Code of 400 (Bad Request) even when a more 483 specific code might apply, for example if the service provider deemed 484 that a more specific code presented an information disclosure risk. 485 When no more specific code might apply, the service provider SHALL 486 respond to an invalid poll request with an HTTP Status Code of 400. 488 The response body for responses to invalid poll requests is left 489 undefined, and its contents SHOULD be ignored. 491 The following is a non-normative example of a response to an invalid 492 poll request: 494 HTTP/1.1 400 Bad Request 496 Example Poll Error Response 498 2.6. Error Response Handling 500 If a SET is invalid, error codes from the IANA "Security Event Token 501 Delivery Error Codes" registry established by 502 [I-D.ietf-secevent-http-push] are used in error responses. As 503 described in Section 2.3 of [I-D.ietf-secevent-http-push], an error 504 response is a JSON object providing details about the error that 505 includes the following name/value pairs: 507 err 508 A value from the IANA "Security Event Token Delivery Error Codes" 509 registry that identifies the error. 511 description 512 A human-readable string that provides additional diagnostic 513 information. 515 When included as part of a batch of SETs, the above JSON is included 516 as part of the "setErrs" member, as defined in Section 2.2 and 517 Section 2.4.4. 519 When the SET Recipient includes one or more error responses in a 520 request to the SET Transmitter, it must also include in the request a 521 "Content-Language" header whose value indicates the language of the 522 error descriptions included in the request. The method of language 523 selection in the case when the SET Recipient can provide error 524 messages in multiple languages is out of scope for this 525 specification. 527 3. Authentication and Authorization 529 The SET delivery method described in this specification is based upon 530 HTTP and and HTTP over TLS [RFC2818] and/or standard HTTP 531 authentication and authorization schemes, as per [RFC7235]. The TLS 532 server certificate MUST be validated, per [RFC6125]. As per 533 Section 4.1 of [RFC7235], a SET delivery endpoint SHALL indicate 534 supported HTTP authentication schemes via the "WWW-Authenticate" 535 header when using HTTP authentication. 537 Authorization for the eligibility to provide actionable SETs can be 538 determined by using the identity of the SET Issuer, validating the 539 polling endpoint URL, perhaps using TLS, or via other employed 540 authentication methods. Among other benefits, authentication can 541 help prevent denial-of-service attacks. Because SETs are not 542 commands, SET Recipients are free to ignore SETs that are not of 543 interest after acknowledging their receipt. 545 4. Security Considerations 546 4.1. Authentication Using Signed SETs 548 In scenarios where HTTP authorization or TLS mutual authentication 549 are not used or are considered weak, JWS signed SETs SHOULD be used 550 (see [RFC7515] and Section 5 of [RFC8417]). This enables the SET 551 Recipient to validate that the SET Issuer is authorized to provide 552 actionable SETs. 554 4.2. HTTP Considerations 556 SET delivery depends on the use of Hypertext Transfer Protocol and is 557 thus subject to the security considerations of HTTP Section 9 of 558 [RFC7230] and its related specifications. 560 As stated in Section 2.7.1 of [RFC7230], an HTTP requestor MUST NOT 561 generate the "userinfo" (i.e., username and password) component (and 562 its "@" delimiter) when an "http" URI reference is generated with a 563 message, as they are now disallowed in HTTP. 565 4.3. Confidentiality of SETs 567 SETs may contain sensitive information that is considered Personally 568 Identifiable Information (PII). In such cases, SET Transmitters and 569 SET Recipients MUST protect the confidentiality of the SET contents 570 by encrypting the SET as described in JWE [RFC7516], using a 571 transport-layer security mechanism such as TLS, or both. If an Event 572 delivery endpoint supports TLS, it MUST support at least TLS version 573 1.2 [RFC5246] and SHOULD support the newest version of TLS that meets 574 its security requirements, which as of the time of this publication 575 is TLS 1.3 [RFC8446]. When using TLS, the client MUST perform a TLS/ 576 SSL server certificate check using DNS-ID [RFC6125]. Implementation 577 security considerations for TLS can be found in "Recommendations for 578 Secure 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 Due to the possibility of interception, Bearer tokens [RFC6750] MUST 589 be exchanged using TLS. 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, either via TLS or using JSON Web Encryption (JWE) 620 [RFC7516], or both. 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 Transmitters should consider 625 the ramifications of sharing a particular subject identifier with a 626 SET Recipient (e.g., whether doing so could enable correlation and/or 627 de-anonymization of data), and choose appropriate subject identifiers 628 for 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-07 (work in 642 progress), July 2019. 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. Acknowledgments 740 The editors would like to thank the members of the SCIM working 741 group, which began discussions of provisioning events starting with 742 draft-hunt-scim-notify-00 in 2015. 744 The editors would like to thank Phil Hunt and the other the authors 745 of draft-ietf-secevent-delivery-02, on which this specification is 746 based. 748 The editors would like to thank the participants in the SecEvents 749 working group for their contributions to this specification. 751 Appendix B. Change Log 753 [[ to be removed by the RFC Editor before publication as an RFC ]] 755 Draft 00 - AB - Based on draft-ietf-secevent-delivery-02 with the 756 following additions: 758 o Renamed to "Poll-Based SET Token Delivery Using HTTP" 760 o Removed references to the HTTP Push delivery method. 762 Draft 01 - mbj: 764 o Addressed problems identified in my 18-Jul-18 review message 765 titled "Issues for both the Push and Poll Specs". 767 o Changes to align terminology with RFC 8417, for instance, by using 768 the already defined term SET Recipient rather than SET Receiver. 770 o Applied editorial and minor normative corrections. 772 o Updated Marius' contact information. 774 o Begun eliminating redundancies between this specification and 775 "Push-Based Security Event Token (SET) Delivery Using HTTP" 777 [I-D.ietf-secevent-http-push], referencing, rather that 778 duplicating common normative text. 780 Draft 02 - mbj: 782 o Removed vestigial language remaining from when the push and poll 783 delivery methods were defined in a common specification. 785 o Replaced remaining uses of the terms Event Transmitter and Event 786 Recipient with the correct terms SET Transmitter and SET 787 Recipient. 789 o Removed uses of the unnecessary term "Event Stream". 791 o Removed dependencies between the semantics of "maxEvents" and 792 "returnImmediately". 794 o Said that PII in SETs is to be encrypted with TLS, JWE, or both. 796 o Corrected grammar and spelling errors. 798 Draft 03 - mbj: 800 o Corrected uses of "attribute" to "member" when describing JSON 801 objects. 803 o Further alignment with the push draft. 805 Draft 04 - AB + mbj 807 o Referenced SET Transmitter definition in http-push. 809 o Removed incorrect normative text regarding SET construction. 811 o Consolidated general out-of-scope items under Introduction. 813 o Removed unnecessary HTTP headers in examples and added Content- 814 Type. 816 o Added Content-Language requirement for error descriptions, 817 aligning with http-push. 819 o Stated that bearer tokens SHOULD have a limited lifetime. 821 o Minor editorial fixes. 823 Draft 05 - AB + mbj 824 o Added normative text defining how to respond to invalid poll 825 requests. 827 o Addressed shepherd comments by Yaron Sheffer. 829 Draft 06 - mbj 831 o Addressed nits identified by the idnits tool. 833 Draft 07 - mbj 835 o Addressed area director review comments by Benjamin Kaduk. 837 Authors' Addresses 839 Annabelle Backman (editor) 840 Amazon 842 Email: richanna@amazon.com 844 Michael B. Jones (editor) 845 Microsoft 847 Email: mbj@microsoft.com 848 URI: http://self-issued.info/ 850 Marius Scurtescu 851 Coinbase 853 Email: marius.scurtescu@coinbase.com 855 Morteza Ansari 856 Cisco 858 Email: morteza.ansari@cisco.com 860 Anthony Nadalin 861 Microsoft 863 Email: tonynad@microsoft.com