Poll-Based Security Event Token (SET) Delivery Using HTTP

Poll-based delivery is designed for scenarios where the recipient can make outbound HTTP requests but may not be able to receive push notifications. It is an alternative to push-based delivery (RFC 8935), chosen when the recipient cannot host a publicly reachable endpoint.

http, security

Service providers MAY respond to any invalid poll request with HTTP 400 even when a more specific code might apply, because a more specific code could present an information disclosure risk to the polling client.

http, security

SET Recipients are directed to acknowledge receipt before taking local actions based on SETs to avoid unnecessary acknowledgement delays. This ensures the transmitter can promptly mark SETs as received rather than waiting for downstream processing to complete.

http, security

The Acknowledge-Only request variant (maxEvents=0) exists to allow SET Recipients to acknowledge received SETs independently from the process of receiving new SETs, enabling multi-threaded implementations where acknowledgement and reception occur on separate threads.

http

Error codes used in 'setErrs' responses MUST come from the IANA 'Security Event Token Error Codes' registry established by RFC 8935, ensuring interoperability between SET Transmitters and Recipients from different implementations.

registry, security

This specification is an alternative SET delivery method to push-based delivery defined in RFC 8935. Both methods share the same SET validation procedures (RFC 8935 Section 2) and error code registry, enabling shared implementation components.

http, security

After successful (acknowledged) SET delivery, SET Transmitters are not required to retain or record SETs for retransmission. Once a SET is acknowledged, the SET Recipient SHALL be responsible for retention, if needed.

security, http

If HTTP Authentication is performed using OAuth access tokens, implementers MUST take into account the threats and countermeasures documented in Section 8 of RFC 7521.

oauth, security

If no SETs are available at the time of the request, the SET Transmitter SHALL delay responding until a SET is available or the timeout interval has elapsed unless the poll request parameter 'returnImmediately' is present with the value 'true'.

http

If the poll needs to return immediately in an Acknowledge-Only request, then 'returnImmediately' MUST also be present with the value 'true'; if 'false', a long poll will still occur until an event is ready to be returned.

http

Service providers SHALL respond to an invalid poll request with an HTTP status code of 400 when no more specific code might apply. The response body for responses to invalid poll requests SHOULD be ignored.

http

SET Recipients SHOULD acknowledge receipt before taking any local actions based on the SETs to avoid unnecessary delay in acknowledgement, where possible.

security, http

SET Transmitters and SET Recipients MUST protect the confidentiality of SET contents when SETs may contain sensitive information. The event delivery endpoint MUST support at least TLS version 1.2 and SHOULD support the newest version of TLS that meets its security requirements.

tls, security, privacy

The implementation security considerations for TLS in RFC 7525 MUST be followed. The client MUST perform a TLS/SSL server certificate check using DNS-ID and/or DANE.

tls, security

The SET Recipient MUST acknowledge receipt to the SET Transmitter, and SHOULD do so in a timely fashion. The SET Recipient SHALL NOT use the event acknowledgement mechanism to report event errors other than those relating to the parsing and validation of the SET.

security, http

The SET Recipient SHOULD accept repeat SETs and acknowledge the SETs regardless of whether the Recipient believes it has already acknowledged the SETs previously. A SET Transmitter MAY limit the number of times it attempts to deliver a SET.

http, security

The TLS server certificate MUST be validated using DNS-ID (RFC 6125) and/or DANE (RFC 6698). A SET delivery endpoint SHALL indicate supported HTTP authentication schemes via the 'WWW-Authenticate' header field when using HTTP authentication.

tls, security, http

When sharing personally identifiable information or information that is otherwise considered confidential to affected users, SET Transmitters and Recipients MUST have the appropriate legal agreements and user consent in place. Data that needs confidentiality protection MUST be encrypted, at least with TLS and sometimes also using JWE.

privacy, security, tls

When the SET Recipient includes one or more error responses in a request to the SET Transmitter, it must also include a 'Content-Language' header field whose value indicates the language of the error descriptions.

http

SET Transmitters should attempt to deliver SETs targeted to the specific business and protocol needs of subscribers, minimizing over-sharing of personal or confidential data. Legal agreements and user consent MUST be in place when sharing PII.

privacy

Subject identifiers within SETs may be sensitive information; SET Issuers and Transmitters should consider whether sharing a particular subject identifier with a SET Recipient could enable correlation and/or de-anonymization of data.

privacy, security

A poll response JSON document contains 'sets' (a JSON object mapping jti values to SET strings; SHALL be empty if no SETs available) and 'moreAvailable' (an optional boolean indicating additional unacknowledged SETs exist; default false if omitted).

http, json

A polling request JSON document contains Request Processing Parameters ('maxEvents': optional integer limiting SETs returned; 'returnImmediately': optional boolean controlling short vs. long polling) and SET Acknowledgement Parameters ('ack': array of jti values of successfully received SETs; 'setErrs': JSON object mapping jti values to error objects).

http, json

Error responses for invalid SETs use the IANA 'Security Event Token Error Codes' registry. Each error object includes 'err' (a registered error code string) and 'description' (a human-readable diagnostic string).

http, json, registry

Bearer tokens SHOULD have a limited lifetime. Implementers should prefer stronger authentication methods over HTTP Basic, and must account for RFC 7521 threats when using OAuth access tokens.

security, oauth

JWS signed SETs can be used to enable the SET Recipient to validate that the SET Issuer is authorized to provide actionable SETs, providing authentication beyond transport-layer mechanisms.

security, jose, crypto

SETs may contain sensitive PII or be distributed through third parties; both TLS (mandatory) and JWE encryption (when required) MUST be used to protect confidentiality. TLS 1.2 is the minimum supported version, with TLS 1.3 recommended.

security, tls, privacy

Poll request variations: (1) Poll-Only — no prior SETs to acknowledge, omits 'ack' and 'setErrs'; (2) Acknowledge-Only — sets 'maxEvents' to 0 with 'ack'/'setErrs' populated, no new SETs returned; (3) Combined Acknowledge and Poll — populates 'ack'/'setErrs' while waiting for next batch of SETs.

http

All poll requests and responses use HTTP POST with Content-Type 'application/json'. SETs in the response 'sets' object are keyed by their 'jti' value (string) and encoded as JSON strings representing the SET JWT.

http, json

The 'ack' field in a poll request is a JSON array of strings whose values are JWT 'jti' claim values identifying successfully received SETs. The 'setErrs' field is a JSON object whose keys are 'jti' values and whose values are error objects with 'err' and 'description' members.

http, json, jose