editorial issues in the SSF spec under public review

[TakahikoKawasaki]

Abstract

- A profile for Security Events Tokens [RFC8417]
+ A profile for Security Event Token [RFC8417]

- Push-Based SET Token Delivery Using HTTP [RFC8935]
- Poll-Based SET Token Delivery Using HTTP [RFC8936]
+ Push-Based Security Event Token (SET) Delivery Using HTTP [RFC8935]
+ Poll-Based Security Event Token (SET) Delivery Using HTTP [RFC8936]

3.1. Subject Members

- A top-level claimnamed
+ A top-level claim named

3.3. Complex Subject Members

  "sub_id": {
    "format": "complex",
-   "user" : {
+   "user": {
      "format": "email",
      "email": "bar@example.com"
    },
-   "tenant" : {
+   "tenant": {
      "format": "iss_sub",
-     "iss" : "https://example.com/idp1",
-     "sub" : "1234"
+     "iss": "https://example.com/idp1",
+     "sub": "1234"
    }
  }

3.5.1. JWT ID Subject Identifier Format

  {
-     "format": "jwt_id",
-     "iss": "https://idp.example.com/123456789/",
-     "jti": "B70BA622-9515-4353-A866-823539EECBC8"
+   "format": "jwt_id",
+   "iss": "https://idp.example.com/123456789/",
+   "jti": "B70BA622-9515-4353-A866-823539EECBC8"
  }

3.5.2. SAML Assertion ID Subject Identifier Format

  {
-     "format": "saml_assertion_id",
-     "issuer": "https://idp.example.com/123456789/",
-     "assertion_id": "_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6"
+   "format": "saml_assertion_id",
+   "issuer": "https://idp.example.com/123456789/",
+   "assertion_id": "_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6"
  }
- 

3.5.3. IP Addresses Subject Identifier Format

  {
-     "format": "ip-addresses",
-     "ip-addresses": ["10.29.37.75", "2001:0db8:0000:0000:0000:8a2e:0370:7334"]
+   "format": "ip-addresses",
+   "ip-addresses": ["10.29.37.75", "2001:0db8:0000:0000:0000:8a2e:0370:7334"]
  }
- 

3.6. Receiver Subject Processing

- A SSF Receiver MUST make
+ An SSF Receiver MUST make

- A SSF Receiver MUST discard
+ An SSF Receiver MUST discard

4.1.1. Explicit Typing of SETs

  {
-   "typ":"secevent+jwt",
-   "alg":"HS256"
+   "typ": "secevent+jwt",
+   "alg": "HS256"
  }

- While current Id Token
+ While current ID Token

4.1.9. The "txn" claim

- across different Security Events Tokens (SETs)
+ across different Security Event Tokens (SETs)

5. Example SETs that conform to the Shared Signals Framework

Figure titles are inconsistent.

• Figure 8: Example: SET Containing an SSF Event with a Simple Subject Member
• Figure 9: Example: SET Containing a RISC Event with a Phone Number Subject
• Figure 10: Example: SET Containing a CAEP Event with Properties
• Figure 11: Example: SET Containing an SSF Event with a Complex Subject Member
• Figure 12: Example: SET Containing an SSF Event with a Simple Subject and a Property Member
• Figure 13: Example: SET Containing an SSF Event with a Proprietary Subject Identifier Format

7.1. Transmitter Configuration Metadata, spec_version

If absent, the Transmitter is assumed to conform to "1_0-ID1" version of the specification.

Is it still true, even in the final version of the SSF specification, that 1_0-ID1 is assumed when spec_version is not specified? Wouldn't it be better to change this to 1_0 instead of 1_0-ID1?

-    {
-         "spec_version": "1_0"
-    }
+ {
+   "spec_version": "1_0"
+ }

7.1.1. Authorization scheme

- The following is a non-normative example of the `spec_urn`
+ The following is a non-normative example of the `spec_urn`:

-    {
-         "spec_urn": "urn:ietf:rfc:6749"
-    }
+ {
+   "spec_urn": "urn:ietf:rfc:6749"
+ }

- Figure 15: Example: `spec_urn` specifying the OAuth protocol for authorization
+ Figure 15: Example: 'spec_urn' specifying the OAuth protocol for authorization

Backticks should be changed to single quotes for consistency with the other figure titles.

7.2.3. Transmitter Configuration Response

- The following is a non-normative example of a Transmitter Configuration Response
+ The following is a non-normative example of a Transmitter Configuration Response:

-   "critical_subject_members": [ "tenant", "user" ],
-   "authorization_schemes":[
+   "critical_subject_members": ["tenant", "user"],
+   "authorization_schemes": [

8.1.1.1. Creating a Stream

    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
-   "description" : "Stream for Receiver A using events type_2, type_3, type_4"
+   "description": "Stream for Receiver A using events type_2, type_3, type_4"
  }

- Figure 21: Example: Create Event Stream Request
+ Figure 21: Example: Create Stream Request

(For the correspondence to "Create Stream Response")

    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
-   "description" : "Stream for Receiver A using events type_2, type_3, type_4"
+   "description": "Stream for Receiver A using events type_2, type_3, type_4"
  }

  HTTP/1.1 201 Created
  Content-Type: application/json
  
  {
    "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
    "iss": "https://tr.example.com",
    "aud": [
-       "https://receiver.example.com/web",
-       "https://receiver.example.com/mobile"
-     ],
+     "https://receiver.example.com/web",
+     "https://receiver.example.com/mobile"
+   ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
-   "description" : "Stream for Receiver A using events type_2, type_3, type_4"
+   "description": "Stream for Receiver A using events type_2, type_3, type_4"
  }

8.1.1.1.1. Validating a Stream Creation Response

- 8.1.1.1.1. Validating a Stream Creation Response
+ 8.1.1.1.1. Validating a Create Stream Response

(For the correspondence to other places)

8.1.1.2. Reading a Stream's Configuration

  HTTP/1.1 200 OK
  Content-Type: application/json
  Cache-Control: no-store
  
  {
    "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
    "iss": "https://tr.example.com",
    "aud": [
-       "https://receiver.example.com/web",
-       "https://receiver.example.com/mobile"
-     ],
+     "https://receiver.example.com/web",
+     "https://receiver.example.com/mobile"
+   ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
-   "description" : "Stream for Receiver A using events type_2, type_3, type_4"
+   "description": "Stream for Receiver A using events type_2, type_3, type_4"
  }

  HTTP/1.1 200 OK
  Content-Type: application/json
  Cache-Control: no-store
  
  [
    {
      "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
      "iss": "https://tr.example.com",
      "aud": [
-         "https://receiver.example.com/web",
-         "https://receiver.example.com/mobile"
-       ],
+       "https://receiver.example.com/web",
+       "https://receiver.example.com/mobile"
+     ],
      "delivery": {
        "method": "urn:ietf:rfc:8935",
        "endpoint_url": "https://receiver.example.com/events"
      },
      "events_supported": [
        "urn:example:secevent:events:type_1",
        "urn:example:secevent:events:type_2",
        "urn:example:secevent:events:type_3"
      ],
      "events_requested": [
        "urn:example:secevent:events:type_2",
        "urn:example:secevent:events:type_3",
        "urn:example:secevent:events:type_4"
      ],
      "events_delivered": [
        "urn:example:secevent:events:type_2",
        "urn:example:secevent:events:type_3"
      ]
    },
    {
      "stream_id": "50b2d39934264897902c0581ba7c21a3",
      "iss": "https://tr.example.com",
      "aud": [
-         "https://receiver.example.com/web",
-         "https://receiver.example.com/mobile"
-       ],
+       "https://receiver.example.com/web",
+       "https://receiver.example.com/mobile"
+     ],
      "delivery": {
        "method": "urn:ietf:rfc:8935",
        "endpoint_url": "https://receiver.example.com/events"
      },
      "events_supported": [
        "urn:example:secevent:events:type_1",
        "urn:example:secevent:events:type_2",
        "urn:example:secevent:events:type_3"
      ],
      "events_requested": [
        "urn:example:secevent:events:type_2",
        "urn:example:secevent:events:type_3",
        "urn:example:secevent:events:type_4"
      ],
      "events_delivered": [
        "urn:example:secevent:events:type_2",
        "urn:example:secevent:events:type_3"
      ],
-     "description" : "Stream for Receiver A using events type_2, type_3, type_4"
+     "description": "Stream for Receiver A using events type_2, type_3, type_4"
    }
  ]

  HTTP/1.1 200 OK
  Content-Type: application/json
  Cache-Control: no-store
  
  [
    {
      "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
      "iss": "https://tr.example.com",
      "aud": [
-         "https://receiver.example.com/web",
-         "https://receiver.example.com/mobile"
-       ],
+       "https://receiver.example.com/web",
+       "https://receiver.example.com/mobile"
+     ],
      "delivery": {
        "method": "urn:ietf:rfc:8935",
        "endpoint_url": "https://receiver.example.com/events"
      },
      "events_supported": [
        "urn:example:secevent:events:type_1",
        "urn:example:secevent:events:type_2",
        "urn:example:secevent:events:type_3"
      ],
      "events_requested": [
        "urn:example:secevent:events:type_2",
        "urn:example:secevent:events:type_3",
        "urn:example:secevent:events:type_4"
      ],
      "events_delivered": [
        "urn:example:secevent:events:type_2",
        "urn:example:secevent:events:type_3"
      ]
    }
  ]

8.1.1.3. Updating a Stream's Configuration

  PATCH /ssf/stream HTTP/1.1
  Host: transmitter.example.com
  Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
  
  {
    "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
-   "description" : "Stream for Receiver B using events type_2, type_3, type_4"
+   "description": "Stream for Receiver B using events type_2, type_3, type_4"
  }

  HTTP/1.1 200 OK
  Content-Type: application/json
  Cache-Control: no-store
  
  {
    "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
    "iss": "https://tr.example.com",
    "aud": [
      "https://receiver.example.com/web",
      "https://receiver.example.com/mobile"
    ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
-   "description" : "Stream for Receiver B using events type_2, type_3, type_4"
+   "description": "Stream for Receiver B using events type_2, type_3, type_4"
  }

8.1.1.4. Replacing a Stream's Configuration

  PUT /ssf/stream HTTP/1.1
  Host: transmitter.example.com
  Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
  
  {
    "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
-   "description" : "Stream for Receiver C"
+   "description": "Stream for Receiver C"
  }

  HTTP/1.1 200 OK
  Content-Type: application/json
  Cache-Control: no-store
  
  {
    "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
    "iss": "https://tr.example.com",
    "aud": [
      "https://receiver.example.com/web",
      "https://receiver.example.com/mobile"
    ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
-   "description" : "Stream for Receiver C"
+   "description": "Stream for Receiver C"
  }

8.1.2. Stream Status

- Authorization: Bearer zzzz
+ Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

8.1.3.2. Adding a Subject to a Stream

- containing in the body a JSON object the following claims:
+ containing in the body a JSON object with the following claims:

8.1.4.1. Verification Event

- OPTIONAL An opaque value
+ OPTIONAL. An opaque value

- if the request is otherwiseinvalid
+ if the request is otherwise invalid

8.1.4.2. Triggering a Verification Event.

- 8.1.4.2. Triggering a Verification Event.
+ 8.1.4.2. Triggering a Verification Event

  {
    "jti": "123456",
    "iss": "https://transmitter.example.com",
    "aud": "receiver.example.com",
    "iat": 1493856000,
    "sub_id": {
      "format": "opaque",
      "id": "f67e39a0a4d34d56b3aa1bc4cff0069f"
    },
    "events": {
-     "https://schemas.openid.net/secevent/ssf/event-type/verification":{
+     "https://schemas.openid.net/secevent/ssf/event-type/verification": {
        "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
      }
    }
  }

8.1.5. Stream Updated Event

- Stream Id for which the status has been updated.
+ Stream ID for which the status has been updated.

11. IANA Considerations

- Subject Identifiers defined in this document will be added to the "Security Events Subject Identifier Types" registry.
+ Subject Identifiers defined in this document will be added to the "Security Event Identifier Formats" registry.

Note that the registry name written in RFC 9493 is "Security Event Identifier Formats". However, the actual registry name in IANA is "Security Event Token (SET) / Subject Identifier Formats". The registry name the SSF spec mentions matches neither of them.

Appendix A. Acknowledgements

- The authors wish to thank all members of the OpenID Foundation SSF Working Group
+ The authors wish to thank all members of the OpenID Foundation Shared Signals Working Group

[tulshi]

I read through and verified many of these changes. All of those look good. Could you please create a PR for this? I'll be happy to review that.

[TakahikoKawasaki]

@tulshi Hi, I've created PR #278 for this issue. However, the PR does not modify the figure titles in Section 5, as I couldn't decide how best to revise them.

[iamseanodentity]

We will make the changes to the figure titles for Section 5 to only mention SSF event if it is a verification event.

[tulshi]

@TakahikoKawasaki , could you please review the couple of comments on your PR ? Otherwise the PR looks good.