draft-ietf-secevent-http-push-00.txt   draft-ietf-secevent-http-push-01.txt 
Network Working Group A. Backman, Ed. Security Events Working Group A. Backman, Ed.
Internet-Draft Amazon Internet-Draft Amazon
Intended status: Standards Track M. Jones, Ed. Intended status: Standards Track M. Jones, Ed.
Expires: October 18, 2018 Microsoft Expires: April 4, 2019 Microsoft
P. Hunt, Ed.
Oracle
M. Scurtescu M. Scurtescu
Google Google
M. Ansari M. Ansari
Cisco Cisco
A. Nadalin A. Nadalin
Microsoft Microsoft
April 16, 2018 October 1, 2018
Push-Based SET Token Delivery Using HTTP Push-Based SET Token Delivery Using HTTP
draft-ietf-secevent-http-push-00 draft-ietf-secevent-http-push-01
Abstract Abstract
This specification defines how a series of security event tokens This specification defines how a series of security event tokens
(SETs) may be delivered to a previously registered receiver using (SETs) may be delivered to a previously registered receiver using
HTTP POST over TLS initiated as a push to the receiver. HTTP POST over TLS initiated as a push to the receiver.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 41 skipping to change at page 1, line 39
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 18, 2018. This Internet-Draft will expire on April 4, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 17 skipping to change at page 2, line 15
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
1.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3
2. SET Event Stream Protocol . . . . . . . . . . . . . . . . . . 4 2. Event Delivery . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Event Delivery Process . . . . . . . . . . . . . . . . . 4 2.1. Event Delivery Process . . . . . . . . . . . . . . . . . 3
2.2. Push Delivery using HTTP . . . . . . . . . . . . . . . . 5 2.2. Transmitting a SET . . . . . . . . . . . . . . . . . . . 4
2.3. Error Response Handling . . . . . . . . . . . . . . . . . 7 2.3. Handling a SET Transmission Request . . . . . . . . . . . 5
3. Authentication and Authorization . . . . . . . . . . . . . . 8 2.3.1. Success Response . . . . . . . . . . . . . . . . . . 5
3.1. Use of Tokens as Authorizations . . . . . . . . . . . . . 9 2.3.2. Failure Response . . . . . . . . . . . . . . . . . . 5
4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 2.3.3. Security Event Token Delivery Error Codes . . . . . . 6
4.1. Authentication Using Signed SETs . . . . . . . . . . . . 10 2.3.4. Error Responses . . . . . . . . . . . . . . . . . . . 7
4.2. HTTP Considerations . . . . . . . . . . . . . . . . . . . 10 3. Authentication and Authorization . . . . . . . . . . . . . . 7
4.3. TLS Support Considerations . . . . . . . . . . . . . . . 10 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7
4.4. Authorization Token Considerations . . . . . . . . . . . 11 4.1. Authentication Using Signed SETs . . . . . . . . . . . . 7
4.4.1. Bearer Token Considerations . . . . . . . . . . . . . 11 4.2. TLS Support Considerations . . . . . . . . . . . . . . . 7
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 11 4.3. Denial of Service . . . . . . . . . . . . . . . . . . . . 8
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 8
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
6.1. Security Event Token Delivery Error Codes . . . . . . . . 8
6.1.1. Registration Template . . . . . . . . . . . . . . . . 8
6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 9
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
7.1. Normative References . . . . . . . . . . . . . . . . . . 12 7.1. Normative References . . . . . . . . . . . . . . . . . . 12
7.2. Informative References . . . . . . . . . . . . . . . . . 13 7.2. Informative References . . . . . . . . . . . . . . . . . 14
Appendix A. Other Streaming Specifications . . . . . . . . . . . 14 Appendix A. Other Streaming Specifications . . . . . . . . . . . 15
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 16 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 16
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 16 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 17
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction and Overview 1. Introduction and Overview
This specification defines how a stream of SETs (see This specification defines how SETs (see [RFC8417]) can be
[I-D.ietf-secevent-token]) can be transmitted to a previously transmitted to a previously registered SET Receiver using HTTP
registered Event Receiver using HTTP [RFC7231] over TLS. The [RFC7231] over TLS. The specification defines a method to push SETs
specification defines a method to push SETs via HTTP POST. via HTTP POST.
This specification defines a method for SET delivery in what is known
as Event Streams.
This specification does not define the method by which Event Streams
are defined, provisioned, managed, monitored, and configured and is
out of scope of this specification.
[[This work is TBD by the SECEVENTS WG]]
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
For purposes of readability examples are not URL encoded. Throughout this documents all figures may contain spaces and extra
Implementers MUST percent encode URLs as described in Section 2.1 of line-wrapping for readability and space limitations.
[RFC3986] .
Throughout this documents all figures MAY contain spaces and extra
line-wrapping for readability and space limitations. Similarly, some
URI's contained within examples, have been shortened for space and
readability reasons.
1.2. Definitions 1.2. Definitions
This specification assumes terminology defined in the Security Event This specification assumes terminology defined in the Security Event
Token specification[I-D.ietf-secevent-token] . Token specification[RFC8417], as well as the terms defined below:
The following definitions are defined for Security Event
distribution:
Event Transmitter SET Transmitter
A service provider that delivers SETs to other providers known as A service provider that delivers SETs to other providers known as
Event Receivers. An Event Transmitter is responsible for offering SET Receivers.
a service that allows the Event Receiver to check the Event Stream
configuration and status known as the "Control Plane".
Event Receiver SET Receiver
A service provider that registers to receive SETs from an Event A service provider that registers to receive SETs from a SET
Transmitter and provides an endpoint to receive SETs via HTTP Transmitter and provides an endpoint to receive SETs via HTTP
POST. Event Receivers can check current Event Stream POST.
configuration and status by accessing the Event Transmitters
"Control Plane".
Event Stream
An Event Stream is a defined location, distribution method and
whereby an Event Transmitter and Event Receiver exchange a pre-
defined family of SETs. A Stream is assumed to have configuration
data such as HTTP endpoints, timeouts, public key sets for signing
and encryption, and Event Families.
Subject
The security subject around which a security event has occurred.
For example, a security subject might per a user, a person, an
email address, a service provider entity, an IP address, an OAuth
Client, a mobile device, or any identifiable thing referenced in
security and authorization systems.
Event
An Event is defined to be an event as represented by a security
event token (SET). See [I-D.ietf-secevent-token].
NumericDate
A JSON numeric value representing the number of seconds from
1970-01-01T00:00:00Z UTC until the specified UTC date/time,
ignoring leap seconds. This is equivalent to the IEEE Std 1003.1,
2013 Edition [POSIX.1] definition "Seconds Since the Epoch", in
which each day is accounted for by exactly 86400 seconds, other
than that non-integer values can be represented. See [RFC3339]
for details regarding date/times in general and UTC in particular.
2. SET Event Stream Protocol
An Event Stream represents the communication channel over which a 2. Event Delivery
series of SETs are delivered to a configured Event Receiver.
2.1. Event Delivery Process 2.1. Event Delivery Process
When an Event occurs, the Event Transmitter constructs a SET token
[I-D.ietf-secevent-token] that describes the Event. The Event
Transmitter determines the Event Streams over which the SET should be
distributed to.
How SETs are defined and the process by which Events are identified
for Event Receivers is out-of-scope of this specification.
When a SET is available for an Event Receiver, the Event Transmitter
attempts to deliver the SET based on the Event Receiver's registered
delivery mechanism:
o The Event Transmitter uses an HTTP/1.1 POST to the Event Receiver
endpoint to deliver the SET;
o Or, the Event Transmitter delivers the Event through a different
method not defined by this specification.
In Push-Based SET Delivery Using HTTP, SETs are delivered one at a In Push-Based SET Delivery Using HTTP, SETs are delivered one at a
time using HTTP POST requests by an Event Transmitter to an Event time using HTTP POST requests by a SET Transmitter to a SET Receiver,
Receiver. The HTTP request body is a JSON Web Token [RFC7519] with a as described below in Section 2.2. Upon receipt, the SET Receiver
"Content-Type" header of "application/secevent+jwt" as defined in acknowledges receipt or indicates an error via the HTTP response, as
Section 2.2 and 6.2 of [I-D.ietf-secevent-token]. Upon receipt, the described below in Section 2.3.
Event Receiver acknowledges receipt with a response with HTTP Status
202, as described below in Section 2.2.
After successful (acknowledged) SET delivery, Event Transmitters After successful (acknowledged) SET delivery, SET Transmitters SHOULD
SHOULD NOT be required to maintain or record SETs for recovery. Once NOT be required to maintain or record SETs for recovery. Once a SET
a SET is acknowledged, the Event Receiver SHALL be responsible for is acknowledged, the SET Receiver SHALL be responsible for retention
retention and recovery. and recovery.
Transmitted SETs SHOULD be self-validating (e.g. signed) if there is Transmitted SETs SHOULD be self-validating (e.g. signed) if there is
a requirement to verify they were issued by the Event Transmitter at a requirement to verify they were issued by the SET Transmitter at a
a later date when de-coupled from the original delivery where later date when de-coupled from the original delivery where
authenticity could be checked via the HTTP or TLS mutual authenticity could be checked via the HTTP or TLS mutual
authentication. authentication.
Upon receiving a SET, the Event Receiver reads the SET and validates Upon receiving a SET, the SET Receiver reads the SET and validates
it. The Event Receiver MUST acknowledge receipt to the Event it. The SET Receiver MUST acknowledge receipt to the SET
Transmitter, using the defined acknowledgement or error method. Transmitter, using the defined acknowledgement or error method.
The Event Receiver SHALL NOT use the Event acknowledgement mechanism The SET Receiver SHALL NOT use the Event acknowledgement mechanism to
to report Event errors other than relating to the parsing and report Event errors other than relating to the parsing and validation
validation of the SET. of the SET.
2.2. Push Delivery using HTTP 2.2. Transmitting a SET
This method allows an Event Transmitter to use HTTP POST This method allows a SET Transmitter to use HTTP POST (Section 4.3.3
(Section 4.3.3 [RFC7231]) to deliver SETs to a previously registered [RFC7231]) to deliver SETs to a previously registered web callback
web callback URI supplied by the Event Receiver as part of an Event URI supplied by the SET Receiver as part of a configuration process
Stream configuration process (not defined by this document). (not defined by this document).
The SET to be delivered MAY be signed and/or encrypted as defined in The SET to be delivered MAY be signed and/or encrypted as defined in
[I-D.ietf-secevent-token]. [RFC8417].
The Event Stream configuration defines a URI of an Event Receiver
provided endpoint which accepts HTTP POST requests (e.g.
"https://rp.example.com/Events").
The HTTP Content-Type (see Section 3.1.1.5 [RFC7231]) for the HTTP The HTTP Content-Type (see Section 3.1.1.5 [RFC7231]) for the HTTP
POST is "application/secevent+jwt" and SHALL consist of a single SET POST is "application/secevent+jwt" and the request body SHALL consist
(see [I-D.ietf-secevent-token]). As per Section 5.3.2 [RFC7231], the of a single SET (see [RFC8417]). As per Section 5.3.2 [RFC7231], the
expected media type ("Accept" header) response is "application/json". value of the "Accept" header is "application/json".
To deliver an Event, the Event Transmitter generates an event The following is a non-normative example of a SET transmission HTTP
delivery message and uses HTTP POST to the configured endpoint with POST request:
the appropriate "Accept" and "Content-Type" headers.
POST /Events HTTP/1.1 POST /Events HTTP/1.1
Host: notify.examplerp.com Host: notify.examplerp.com
Accept: application/json Accept: application/json
Authorization: Bearer h480djs93hd8
Content-Type: application/secevent+jwt Content-Type: application/secevent+jwt
eyJhbGciOiJub25lIn0 eyJhbGciOiJub25lIn0
. .
eyJwdWJsaXNoZXJVcmkiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20iLCJmZWV eyJwdWJsaXNoZXJVcmkiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20iLCJmZWV
kVXJpcyI6WyJodHRwczovL2podWIuZXhhbXBsZS5jb20vRmVlZHMvOThkNTI0Nj kVXJpcyI6WyJodHRwczovL2podWIuZXhhbXBsZS5jb20vRmVlZHMvOThkNTI0Nj
FmYTViYmM4Nzk1OTNiNzc1NCIsImh0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZ FmYTViYmM4Nzk1OTNiNzc1NCIsImh0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZ
WVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3Il0sInJlc291cmNlVXJpcyI6 WVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3Il0sInJlc291cmNlVXJpcyI6
WyJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZ WyJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZ
hYjYxZTc1MjFkOSJdLCJldmVudFR5cGVzIjpbIkNSRUFURSJdLCJhdHRyaWJ1dG hYjYxZTc1MjFkOSJdLCJldmVudFR5cGVzIjpbIkNSRUFURSJdLCJhdHRyaWJ1dG
VzIjpbImlkIiwibmFtZSIsInVzZXJOYW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiX VzIjpbImlkIiwibmFtZSIsInVzZXJOYW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiX
SwidmFsdWVzIjp7ImVtYWlscyI6W3sidHlwZSI6IndvcmsiLCJ2YWx1ZSI6Impk SwidmFsdWVzIjp7ImVtYWlscyI6W3sidHlwZSI6IndvcmsiLCJ2YWx1ZSI6Impk
skipping to change at page 6, line 30 skipping to change at page 4, line 52
WVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3Il0sInJlc291cmNlVXJpcyI6 WVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3Il0sInJlc291cmNlVXJpcyI6
WyJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZ WyJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZ
hYjYxZTc1MjFkOSJdLCJldmVudFR5cGVzIjpbIkNSRUFURSJdLCJhdHRyaWJ1dG hYjYxZTc1MjFkOSJdLCJldmVudFR5cGVzIjpbIkNSRUFURSJdLCJhdHRyaWJ1dG
VzIjpbImlkIiwibmFtZSIsInVzZXJOYW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiX VzIjpbImlkIiwibmFtZSIsInVzZXJOYW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiX
SwidmFsdWVzIjp7ImVtYWlscyI6W3sidHlwZSI6IndvcmsiLCJ2YWx1ZSI6Impk SwidmFsdWVzIjp7ImVtYWlscyI6W3sidHlwZSI6IndvcmsiLCJ2YWx1ZSI6Impk
b2VAZXhhbXBsZS5jb20ifV0sInBhc3N3b3JkIjoibm90NHUybm8iLCJ1c2VyTmF b2VAZXhhbXBsZS5jb20ifV0sInBhc3N3b3JkIjoibm90NHUybm8iLCJ1c2VyTmF
tZSI6Impkb2UiLCJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkiLCJuYW tZSI6Impkb2UiLCJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkiLCJuYW
1lIjp7ImdpdmVuTmFtZSI6IkpvaG4iLCJmYW1pbHlOYW1lIjoiRG9lIn19fQ 1lIjp7ImdpdmVuTmFtZSI6IkpvaG4iLCJmYW1pbHlOYW1lIjoiRG9lIn19fQ
. .
Figure 1: Example HTTP POST Request Figure 1: Example SET Transmission Request
Upon receipt of the request, the Event Receiver SHALL validate the 2.3. Handling a SET Transmission Request
JWT structure of the SET as defined in Section 7.2 [RFC7519]. The
Event Receiver SHALL also validate the SET information as described
in Section 2 [I-D.ietf-secevent-token].
If the SET is determined to be valid, the Event Receiver SHALL Upon receipt of the request, the SET Receiver SHALL validate the JWT
structure of the SET as defined in Section 7.2 [RFC7519]. The SET
Receiver SHALL also validate the SET information as described in
Section 2 [RFC8417].
2.3.1. Success Response
If the SET is determined to be valid, the SET Receiver SHALL
"acknowledge" successful submission by responding with HTTP Status "acknowledge" successful submission by responding with HTTP Status
202 as "Accepted" (see Section 6.3.3 [RFC7231]). 202 as "Accepted" (see Section 6.3.3 [RFC7231]).
In order to maintain compatibility with other methods of In order to maintain compatibility with other methods of
transmission, the Event Receiver SHOULD NOT include an HTTP response transmission, the SET Receiver SHOULD NOT include an HTTP response
body representation of the submitted SET or what the SET's pending body representation of the submitted SET or what the SET's pending
status is when acknowledging success. In the case of an error (e.g. status is when acknowledging success. In the case of an error (e.g.
HTTP Status 400), the purpose of the HTTP response body is to HTTP Status 400), the purpose of the HTTP response body is to
indicate any SET parsing, validation, or cryptographic errors. indicate any SET parsing, validation, or cryptographic errors.
The following is a non-normative example of a successful receipt of a The following is a non-normative example of a successful receipt of a
SET. SET.
HTTP/1.1 202 Accepted HTTP/1.1 202 Accepted
Figure 2: Example Successful Delivery Response Figure 2: Example Successful Delivery Response
Note that the purpose of the "acknowledgement" response is to let the Note that the purpose of the "acknowledgement" response is to let the
Event Transmitter know that a SET has been delivered and the SET Transmitter know that a SET has been delivered and the
information no longer needs to be retained by the Event Transmitter. information no longer needs to be retained by the SET Transmitter.
Before acknowledgement, Event Receivers SHOULD ensure they have Before acknowledgement, SET Receivers SHOULD ensure they have
validated received SETs and retained them in a manner appropriate to validated received SETs and retained them in a manner appropriate to
information retention requirements appropriate to the SET event types information retention requirements appropriate to the SET event types
signaled. The level and method of retention of SETs by Event signaled. The level and method of retention of SETs by SET Receivers
Receivers is out-of-scope of this specification. is out-of-scope of this specification.
In the Event of a general HTTP error condition, the Event Receiver 2.3.2. Failure Response
MAY respond with an appropriate HTTP Status code as defined in
Section 6 [RFC7231].
When the Event Receiver detects an error parsing or validating a In the Event of a general HTTP error condition, the SET Receiver MAY
received SET (as defined by [I-D.ietf-secevent-token]), the Event respond with an appropriate HTTP Status code as defined in Section 6
Receiver SHALL indicate an HTTP Status 400 error with an error code [RFC7231].
as described in Section 2.3.
When the SET Receiver detects an error parsing or validating a
received SET (as defined by [RFC8417]), the SET Receiver SHALL
indicate an HTTP Status 400 error with an error response as described
in Section 2.3.4.
The following is an example non-normative error response. The following is an example non-normative error response.
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
{ {
"err":"dup", "err":"dup",
"description":"SET already received. Ignored." "description":"SET already received. Ignored."
} }
Figure 3: Example HTTP Status 400 Response Figure 3: Example Error Response
2.3. Error Response Handling 2.3.3. Security Event Token Delivery Error Codes
If a SET is invalid, the following error codes are defined: Security Event Token Delivery Error Codes are strings that identify a
specific type of error that may occur when parsing or validating a
SET. Every Security Event Token Delivery Error Code MUST have a
unique name registered in the IANA "Security Event Token Delivery
Error Codes" registry established by Section 6.1.
The following table presents the initial set of Error Codes that are
registered in the IANA "Security Event Token Delivery Error Codes"
registry:
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
| Err Value | Description | | Error | Description |
| Code | |
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
| json | Invalid JSON object. | | json | Invalid JSON object. |
| jwtParse | Invalid or unparsable JWT or JSON structure. | | jwtParse | Invalid or unparsable JWT or JSON structure. |
| jwtHdr | In invalid JWT header was detected. | | jwtHdr | In invalid JWT header was detected. |
| jwtCrypto | Unable to parse due to unsupported algorithm. | | jwtCrypto | Unable to parse due to unsupported algorithm. |
| jws | Signature was not validated. | | jws | Signature was not validated. |
| jwe | Unable to decrypt JWE encoded data. | | jwe | Unable to decrypt JWE encoded data. |
| jwtAud | Invalid audience value. | | jwtAud | Invalid audience value. |
| jwtIss | Issuer not recognized. | | jwtIss | Issuer not recognized. |
| setType | An unexpected Event type was received. | | setType | An unexpected Event type was received. |
| setParse | Invalid structure was encountered such as an | | setParse | Invalid structure was encountered such as an |
| | inability to parse or an incomplete set of Event | | | inability to parse or an incomplete set of Event |
| | claims. | | | claims. |
| setData | SET event claims incomplete or invalid. | | setData | SET event claims incomplete or invalid. |
| dup | A duplicate SET was received and has been ignored. | | dup | A duplicate SET was received and has been ignored. |
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
Table 1: SET Errors Table 1: SET Delivery Error Codes
2.3.4. Error Responses
An error response SHALL include a JSON object which provides details An error response SHALL include a JSON object which provides details
about the error. The JSON object includes the JSON attributes: about the error. The JSON object includes the JSON attributes:
err err
A value which is a keyword that describes the error (see Table 1). A value which is a keyword that describes the error (see Table 1).
description description
A human-readable text that provides additional diagnostic A human-readable text that provides additional diagnostic
information. information.
When included as part of an HTTP Status 400 response, the above JSON When included as part of an HTTP Status 400 response, the above JSON
is the HTTP response body (see Figure 3). is the HTTP response body (see Figure 3).
3. Authentication and Authorization 3. Authentication and Authorization
The SET delivery method described in this specification is based upon The SET delivery method described in this specification is based upon
HTTP and depends on the use of TLS and/or standard HTTP HTTP and depends on the use of TLS and/or standard HTTP
authentication and authorization schemes as per [RFC7235]. For authentication and authorization schemes as per [RFC7235].
example, the following methodologies could be used among others:
TLS Client Authentication
Event delivery endpoints MAY request TLS mutual client
authentication. See Section 7.3 [RFC5246].
Bearer Tokens
Bearer tokens [RFC6750] MAY be used when combined with TLS and a
token framework such as OAuth 2.0 [RFC6749]. For security
considerations regarding the use of bearer tokens in SET delivery
see Section 4.4.1.
Basic Authentication
Usage of basic authentication should be avoided due to its use of
a single factor that is based upon a relatively static, symmetric
secret. Implementers SHOULD combine the use of basic
authentication with other factors. The security considerations of
HTTP BASIC, are well documented in [RFC7617] and SHOULD be
considered along with using signed SETs (see SET Payload
Authentication below).
SET Payload Authentication
In scenarios where SETs are signed and the delivery method is HTTP
POST (see Section 2.2), Event Receivers MAY elect to use Basic
Authentication or not to use HTTP or TLS based authentication at
all. See Section 4.1 for considerations.
As per Section 4.1 of [RFC7235], a SET delivery endpoint SHALL
indicate supported HTTP authentication schemes via the "WWW-
Authenticate" header.
Because SET Delivery describes a simple function, authorization for Because SET Delivery describes a simple function, authorization for
the ability to pick-up or deliver SETs can be derived by considering the ability to pick-up or deliver SETs can be derived by considering
the identity of the SET issuer, or via an authentication method the identity of the SET issuer, or via other employed authentication
above. This specification considers authentication as a feature to methods. Because SETs are not commands (see ), SET Receivers are
prevent denial-of-service attacks. Because SETs are not commands free to ignore SETs that are not of interest.
(see ), Event Receivers are free to ignore SETs that are not of
interest.
For illustrative purposes only, SET delivery examples show an OAuth2
bearer token value [RFC6750] in the authorization header. This is
not intended to imply that bearer tokens are preferred. However, the
use of bearer tokens in the specification does reflect common
practice.
3.1. Use of Tokens as Authorizations
When using bearer tokens or proof-of-possession tokens that represent
an authorization grant such as issued by OAuth (see [RFC6749]),
implementers SHOULD consider the type of authorization granted, any
authorized scopes (see Section 3.3 of [RFC6749]), and the security
subject(s) that SHOULD be mapped from the authorization when
considering local access control rules. Section 6 of the OAuth
Assertions draft [RFC7521], documents common scenarios for
authorization including:
o Clients using an assertion to authenticate and/or act on behalf of
itself;
o Clients acting on behalf of a user; and,
o A Client acting on behalf of an anonymous user (e.g., see next
section).
When using OAuth authorization tokens, implementers MUST take into
account the threats and countermeasures documented in the security
considerations for the use of client authorizations (see Section 8 of
[RFC7521]). When using other token formats or frameworks,
implementers MUST take into account similar threats and
countermeasures, especially those documented by the relevant
specifications.
4. Security Considerations 4. Security Considerations
4.1. Authentication Using Signed SETs 4.1. Authentication Using Signed SETs
In scenarios where HTTP authorization or TLS mutual authentication In scenarios where HTTP authorization or TLS mutual authentication
are not used or are considered weak, JWS signed SETs SHOULD be used are not used or are considered weak, JWS signed SETs SHOULD be used
(see [RFC7515] and Security Considerations (see [RFC7515] and Security Considerations [RFC8417]). This enables
[I-D.ietf-secevent-token]). This enables the Event Receiver to the SET Receiver to validate that the SET issuer is authorized to
validate that the SET issuer is authorized to deliver SETs. deliver SETs.
4.2. HTTP Considerations
SET delivery depends on the use of Hypertext Transfer Protocol and
thus subject to the security considerations of HTTP Section 9
[RFC7230] and its related specifications.
As stated in Section 2.7.1 [RFC7230], an HTTP requestor MUST NOT
generate the "userinfo" (i.e., username and password) component (and
its "@" delimiter) when an "http" URI reference is generated with a
message as they are now disallowed in HTTP.
4.3. TLS Support Considerations 4.2. TLS Support Considerations
SETs contain sensitive information that is considered PII (e.g. SETs contain sensitive information that is considered PII (e.g.
subject claims). Therefore, Event Transmitters and Event Receivers subject claims). Therefore, SET Transmitters and SET Receivers MUST
MUST require the use of a transport-layer security mechanism. Event require the use of a transport-layer security mechanism. Event
delivery endpoints MUST support TLS 1.2 [RFC5246] and MAY support delivery endpoints MUST support TLS 1.2 [RFC5246] and MAY support
additional transport-layer mechanisms meeting its security additional transport-layer mechanisms meeting its security
requirements. When using TLS, the client MUST perform a TLS/SSL requirements. When using TLS, the client MUST perform a TLS/SSL
server certificate check, per [RFC6125]. Implementation security server certificate check, per [RFC6125]. Implementation security
considerations for TLS can be found in "Recommendations for Secure considerations for TLS can be found in "Recommendations for Secure
Use of TLS and DTLS" [RFC7525]. Use of TLS and DTLS" [RFC7525].
4.4. Authorization Token Considerations 4.3. Denial of Service
When using authorization tokens such as those issued by OAuth 2.0
[RFC6749], implementers MUST take into account threats and
countermeasures documented in Section 8 of [RFC7521].
4.4.1. Bearer Token Considerations
Due to the possibility of interception, Bearer tokens MUST be
exchanged using TLS.
Bearer tokens MUST have a limited lifetime that can be determined
directly or indirectly (e.g., by checking with a validation service)
by the service provider. By expiring tokens, clients are forced to
obtain a new token (which usually involves re-authentication) for
continued authorized access. For example, in OAuth2, a client MAY
use OAuth token refresh to obtain a new bearer token after
authenticating to an authorization server. See Section 6 of
[RFC6749].
Implementations supporting OAuth bearer tokens need to factor in The SET Receiver may be vulnerable to a denial-of-service attack
security considerations of this authorization method [RFC7521]. where a malicious party makes a high volume of requests containing
Since security is only as good as the weakest link, implementers also invalid SETs, causing the endpoint to expend significant resources on
need to consider authentication choices coupled with OAuth bearer cryptographic operations that are bound to fail. This may be
tokens. The security considerations of the default authentication mitigated by authenticating SET Transmitters with a mechanism with
method for OAuth bearer tokens, HTTP BASIC, are well documented in low runtime overhead, such as mutual TLS or statically assigned
[RFC7617], therefore implementers are encouraged to prefer stronger bearer tokens.
authentication methods. Designating the specific methods of
authentication and authorization are out-of-scope for the delivery of
SET tokens, however this information is provided as a resource to
implementers.
5. Privacy Considerations 5. Privacy Considerations
If a SET needs to be retained for audit purposes, JWS MAY be used to If a SET needs to be retained for audit purposes, JWS MAY be used to
provide verification of its authenticity. provide verification of its authenticity.
Event Transmitters SHOULD attempt to specialize Event Streams so that
the content is targeted to the specific business and protocol needs
of subscribers.
When sharing personally identifiable information or information that When sharing personally identifiable information or information that
is otherwise considered confidential to affected users, Event is otherwise considered confidential to affected users, SET
Transmitters and Receivers MUST have the appropriate legal agreements Transmitters and Receivers MUST have the appropriate legal agreements
and user consent or terms of service in place. and user consent or terms of service in place.
The propagation of subject identifiers can be perceived as personally The propagation of subject identifiers can be perceived as personally
identifiable information. Where possible, Event Transmitters and identifiable information. Where possible, SET Transmitters and
Receivers SHOULD devise approaches that prevent propagation -- for Receivers SHOULD devise approaches that prevent propagation -- for
example, the passing of a hash value that requires the subscriber to example, the passing of a hash value that requires the subscriber to
already know the subject. already know the subject.
6. IANA Considerations 6. IANA Considerations
There are no IANA considerations. 6.1. Security Event Token Delivery Error Codes
This document defines Security Event Token Delivery Error Codes, for
which IANA is asked to create and maintain a new registry titled
"Security Event Token Delivery Error Codes". Initial values for the
Security Event Token Delivery Error Codes registry are given in
Table 1. Future assignments are to be made through the Expert Review
registration policy ([RFC8126]) and shall follow the template
presented in Section 6.1.1.
6.1.1. Registration Template
Error Code
The name of the Security Event Token Delivery Error Code, as
described in Section 2.3.3. The name MUST be a case-sensitive
ASCII string consisting only of upper-case letters ("A" - "Z"),
lower-case letters ("a" - "z"), and digits ("0" - "9").
Description
A brief human-readable description of the Security Event Token
Delivery Error Code.
Change Controller
For error codes registered by the IETF or its working groups, list
"IETF Secevent Working Group". For all other error codes, list
the name of the party responsible for the registration. Contact
information such as mailing address, email address, or phone
number may also be provided.
Defining Document(s)
A reference to the document or documents that define the Security
Event Token Delivery Error Code. The definition MUST specify the
name and description of the error code, and explain under what
circumstances the error code may be used. URIs that can be used
to retrieve copies of each document at no cost SHOULD be included.
6.1.2. Initial Registry Contents
o
Error Code
json
Description
Invalid JSON object.
Change Controller
IETF Secevent Working Group
Defining Document(s)
Section 2.3.3 of this document.
o
Error Code
jwtParse
Description
Invalid or unparsable JWT or JSON structure.
Change Controller
IETF Secevent Working Group
Defining Document(s)
Section 2.3.3 of this document.
o
Error Code
jwtHdr
Description
An invalid JWT header was detected.
Change Controller
IETF Secevent Working Group
Defining Document(s)
Section 2.3.3 of this document.
o
Error Code
jwtCrypto
Description
Unable to parse due to unsupported algorithm.
Change Controller
IETF Secevent Working Group
Defining Document(s)
Section 2.3.3 of this document.
o
Error Code
jws
Description
Signature was not validated.
Change Controller
IETF Secevent Working Group
Defining Document(s)
Section 2.3.3 of this document.
o
Error Code
jwe
Description
Unable to decrypt JWE encoded data.
Change Controller
IETF Secevent Working Group
Defining Document(s)
Section 2.3.3 of this document.
o
Error Code
jwtAud
Description
Invalid audience value.
Change Controller
IETF Secevent Working Group
Defining Document(s)
Section 2.3.3 of this document.
o
Error Code
jwtIss
Description
Issuer not recognized.
Change Controller
Defining Document(s)
Section 2.3.3 of this document.
o
Error Code
setType
Description
An unexpected Event type was received.
Change Controller
IETF Secevent Working Group
Defining Document(s)
Section 2.3.3 of this document.
o
Error Code
setParse
Description
Invalid structure was encountered such as an inability to parse
or an incomplete set of Event claims.
Change Controller
IETF Secevent Working Group
Defining Document(s)
Section 2.3.3 of this document.
o
Error Code
setData
Description
SET event claims incomplete or invalid.
Change Controller
IETF Secevent Working Group
Defining Document(s)
Section 2.3.3 of this document.
o
Error Code
dup
Description
A duplicate SET was received and has been ignored.
Change Controller
IETF Secevent Working Group
Defining Document(s)
Section 2.3.3 of this document.
7. References 7. References
7.1. Normative References 7.1. Normative References
[I-D.ietf-secevent-token]
Hunt, P., Denniss, W., Ansari, M., and M. Jones, "Security
Event Token (SET)", draft-ietf-secevent-token-00 (work in
progress), January 2017.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
skipping to change at page 13, line 24 skipping to change at page 14, line 5
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/info/rfc7519>. <https://www.rfc-editor.org/info/rfc7519>.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer "Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
2015, <https://www.rfc-editor.org/info/rfc7525>. 2015, <https://www.rfc-editor.org/info/rfc7525>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8417] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
"Security Event Token (SET)", RFC 8417,
DOI 10.17487/RFC8417, July 2018,
<https://www.rfc-editor.org/info/rfc8417>.
7.2. Informative References 7.2. Informative References
[openid-connect-core] [openid-connect-core]
NRI, "OpenID Connect Core 1.0", Nov 2014. NRI, "OpenID Connect Core 1.0", Nov 2014.
[POSIX.1] Institute of Electrical and Electronics Engineers, "The
Open Group Base Specifications Issue 7", IEEE Std 1003.1,
2013 Edition, 2013.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>. <https://www.rfc-editor.org/info/rfc3339>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, Framework: Bearer Token Usage", RFC 6750,
skipping to change at page 16, line 13 skipping to change at page 16, line 48
subscriber subscriber
o Subscriber Pull(poll) - https://cloud.google.com/pubsub/docs/pull o Subscriber Pull(poll) - https://cloud.google.com/pubsub/docs/pull
Appendix B. Acknowledgments Appendix B. Acknowledgments
The editors would like to thanks the members of the SCIM WG which The editors would like to thanks the members of the SCIM WG which
began discussions of provisioning events starting with: draft-hunt- began discussions of provisioning events starting with: draft-hunt-
scim-notify-00 in 2015. scim-notify-00 in 2015.
The editors would like to thank the authors of draft-ietf-secevent- The editors would like to thank Phil Hunt and the other authors of
delivery-02, on which this draft is based. draft-ietf-secevent-delivery-02, on which this draft is based.
The editor would like to thank the participants in the the SECEVENTS The editor would like to thank the participants in the the SECEVENTS
working group for their support of this specification. working group for their support of this specification.
Appendix C. Change Log Appendix C. Change Log
Draft 00 - AB - Based on draft-ietf-secevent-delivery-02 with the Draft 00 - AB - Based on draft-ietf-secevent-delivery-02 with the
following changes: following changes:
o Renamed to "Push-Based SET Token Delivery Using HTTP" o Renamed to "Push-Based SET Token Delivery Using HTTP"
o Removed references to the HTTP Polling delivery method. o Removed references to the HTTP Polling delivery method.
o Removed informative reference to RFC6202. o Removed informative reference to RFC6202.
Draft 01 - AB:
o Fixed area and workgroup to match secevent.
o Removed unused definitions and definitions already covered by SET.
o Renamed Event Transmitter and Event Receiver to SET Transmitter
and SET Receiver, respectively.
o Added IANA registry for SET Delivery Error Codes.
o Removed enumeration of HTTP authentication methods.
o Removed generally applicable guidance for HTTP, authorization
tokens, and bearer tokens.
o Moved guidance for using authentication methods as DoS protection
to Security Considerations.
o Removed redundant instruction to use WWW-Authenticate header.
o Removed further generally applicable guidance for authorization
tokens.
o Removed bearer token from example delivery request, and text
referencing it.
o Broke delivery method description into separate request/response
sections.
o Added missing empty line between headers and body in example
request.
o Removed unapplicable notes about example formatting.
o Removed text about SET creation and handling.
o Removed duplication in protocol description.
o Added "non-normative example" text to example transmission
request.
o Fixed inconsistencies in use of Error Code term.
Authors' Addresses Authors' Addresses
Annabelle Backman (editor) Annabelle Backman (editor)
Amazon Amazon
Email: richanna@amazon.com Email: richanna@amazon.com
Michael B. Jones (editor) Michael B. Jones (editor)
Microsoft Microsoft
Email: mbj@microsoft.com Email: mbj@microsoft.com
URI: http://self-issued.info/ URI: http://self-issued.info/
Phil Hunt (editor)
Oracle Corporation
Email: phil.hunt@yahoo.com
Marius Scurtescu Marius Scurtescu
Google Google
Email: mscurtescu@google.com Email: mscurtescu@google.com
Morteza Ansari Morteza Ansari
Cisco Cisco
Email: morteza.ansari@cisco.com Email: morteza.ansari@cisco.com
 End of changes. 60 change blocks. 
304 lines changed or deleted 387 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/