jiebi/TextFlow huggingface dataset:
Original text:
addresses on a single link.  In such cases, identification could be performed by subnet, such as the /64 to which the IP belongs.  3.5. A Captive Portal API needs to present information to clients that is

Reviewer comments:
We've had lots of people asking about the mac address as an identifier. Mention it, and point out that we won't give a deep discussion about it.
This one will likely be controversial. I wouldn't mind input from a few others.
Thanks for the reviews/suggestions.
The MAC address is such an obvious identifier, particularly since it's so widely used. We've have multiple questions about it during reviews. We should probably add some simple text pointing that out. E.g. "The MAC address of a device is often used as an identity in existing implementations. A discussion of it has been omitted for brevity, but the MAC address could be used subject to the criteria in section 3.2"

Revised text:
addresses on a single link.  In such cases, identification could be performed by subnet, such as the /64 to which the IP belongs. <ins> 3.4.3. The MAC address of a device is often used as an identifier in existing implementations.  This document does not discuss the use of MAC addresses within a captive portal system, but they can be used as an identifier type, subject to the criteria in id_recommended_props. </ins> 3.5. A Captive Portal API needs to present information to clients that is
Original text:
Abstract <del> This document describes a captive portal architecture.  DHCP or Router Advertisements (RAs), an optional signaling protocol, and an HTTP API are used to provide the solution.  The role of Provisioning Domains (PvDs) is described. </del>  1.

Reviewer comments:
Open up the abstract's wording a bit so we make it clear that other provisioning protocols could be used in the future for discovering the API URI.
Benjamin writes:

Revised text:
Abstract  <ins> This document describes a captive portal architecture.  Network provisioning protocols such as DHCP or Router Advertisements (RAs), an optional signaling protocol, and an HTTP API are used to provide the solution.  The role of Provisioning Domains (PvDs) is described. </ins> 1.
Original text:
continue to be supported. If User Equipment supports the Captive Portal API, it MUST validate <del> the API server's TLS certificate (see RFC2818).  An Enforcement Device SHOULD allow access to any services that User Equipment could need to contact to perform certificate validation, such as OCSP responders, CRLs, and NTP servers; see Section 4.1 of I-D.ietf- capport-api for more information.  If certificate validation fails, User Equipment MUST NOT proceed with any of the behavior described above. </del>  2.2. The authors thank Lorenzo Colitti for providing the majority of the content for the Captive Portal Signal requirements.  The authors thank various individuals for their feedback on the mailing list and during the IETF98 hackathon: David Bird, Erik Kline, Alexis La Goulette, Alex Roscoe, Darshak Thakore, and Vincent van

Reviewer comments:
A reviewer requested that we provide more detail on how the user equipment should so certificate validation. This does so.
Do this. Figure out the proper 'name type'.
Ben suggests Let's use this, and attribute it to him in the acknowledgements.

Revised text:
continue to be supported. If User Equipment supports the Captive Portal API, it MUST validate  <ins> the API server's TLS certificate (see RFC2818) according to the procedures in RFC6125.  The API server's URI is obtained via a network provisioning protocol, which will typically provide a hostname to be used in TLS server certificate validation, against a DNS-ID in the server certificate.  If the API server is identified by IP address, the iPAddress subjectAltName is used to validate the server certificate.  An Enforcement Device SHOULD allow access to any services that User Equipment could need to contact to perform certificate validation, such as OCSP responders, CRLs, and NTP servers; see Section 4.1 of I-D.ietf-capport-api for more information.  If certificate validation fails, User Equipment MUST NOT proceed with any of the behavior described above. </ins> 2.2. The authors thank Lorenzo Colitti for providing the majority of the content for the Captive Portal Signal requirements. <ins> The authors thank Benjamin Kaduk for providing the content related to TLS certificate validation of the API server. </ins> The authors thank various individuals for their feedback on the mailing list and during the IETF98 hackathon: David Bird, Erik Kline, Alexis La Goulette, Alex Roscoe, Darshak Thakore, and Vincent van
Original text:
the equipment. At minimum, the API MUST provide the state of captivity.  Further the <del> API MUST be able to provide a URI for the User Portal. </del>  A caller to the API needs to be presented with evidence that the content it is receiving is for a version of the API that it supports.

Reviewer comments:
We never talked about TLS for the user portal. Add a bit of language related to that. To discuss: Should this be a MUST? Existing solutions often don't use https, but that may not be a good reason to loosen the requirement. Have I properly mentioned the URI scheme as being https? Do we even need to do that? I'm trying to put a requirement on the API that it provide a URI that lends itself to tls-based communication, which is why I took that approach.
NAME using MUST makes sense. I've taken your suggestion.
Benjamin writes: I would at least like to recommend that it's TLS, so it's considered. Discussion continuing on list.

Revised text:
the equipment. At minimum, the API MUST provide the state of captivity.  Further the  <ins> API MUST be able to provide a URI for the User Portal.  The scheme for the URI MUST be https so that the User Equipment communicates with the User Portal over TLS. </ins> A caller to the API needs to be presented with evidence that the content it is receiving is for a version of the API that it supports.
Original text:
the user in satisfying the conditions to escape captivity. Captive Portal API: Also known as API.  An HTTP API allowing User <del> Equipment to query its state of captivity within the Captive Portal. </del>  Captive Portal API Server: Also known as API Server.  A server hosting the Captive Portal API.

Reviewer comments:
The API provides more than just a simple boolean sttate: it allows the UE to learn how to escape captivity. To set the tone for a more complicated API, mention this in the terminology section's definition of the Captive Portal API.
This currently only mentions the state of captivity, whereas it should also include how to get out captivity.

Revised text:
the user in satisfying the conditions to escape captivity. Captive Portal API: Also known as API.  An HTTP API allowing User  <ins> Equipment to query information about its state of captivity within the Captive Portal.  This information might include how to obtain full network access (e.g. by visting a URI). </ins> Captive Portal API Server: Also known as API Server.  A server hosting the Captive Portal API.
Original text:
4. This section aims to improve understanding by describing a possible <del> workflow of solutions adhering to the architecture. </del>  4.1. A different Captive Portal API URI could be returned in the following cases: <del> Whenever a new Captive Portal API URI is received by end User Equipment, it SHOULD discard the old URI and use the new one for future requests to the API. </del>  5. needs to trust the API server, server authentication will be performed using TLS mechanisms.  7.3. The solution described here requires that the API be secured using

Reviewer comments:
There was some concern that section 4 could be seen as normative. To make matters worse, there was some normative text in there. Rework things a bit to address that. Explicitly call out that section 4 is not normative to avoid confusion Move normative text out of 4.3 into 2.1 Add some more description to 4.3 Describe trust for new URIs
Roman writes, It's meant to be informative. Move it Section 2.1 (User Equipment)
We did this in
Benjamin writes, This should be the same as the initial one we received when first accessing the network(e.g. via DHCP, RAs, etc). Perhaps we don't properly indicate elsewhere that this should be supported. I thought we did, but I can't find it... I think we should add a point to Section 2.1 that the UE SHOULD support updates to the captive portal URI from the network provisioning service, and then mention here that that service is what did it. The same trust as mentioned in section 7.1 still applies.
Benjamin writes, Do it.

Revised text:
4. This section aims to improve understanding by describing a possible  <ins> workflow of solutions adhering to the architecture.  Note that the section is not normative: it describes only as subset of possible implementations. </ins> 4.1. A different Captive Portal API URI could be returned in the following cases:  <ins> When the Network Provisioning Service updates the Captive Portal API URI, the User Equipment can retrieve updated state from the URI immediately, or it can wait as it normally would until the expiry conditions it retrieved from the old URI are about to expire. </ins> 5. needs to trust the API server, server authentication will be performed using TLS mechanisms. <ins> The Captive Portal API URI might change during the Captive Portal Session.  The User Equipment can apply the same trust mechanisms to the new URI as it did to the URI it received initially from the network provisioning service. </ins> 7.3. The solution described here requires that the API be secured using
Original text:
3.2.1. <del> Each instance of User Equipment interacting with the Captive Network MUST be given an identifier that is unique among User Equipment interacting at that time. </del>  Over time, the User Equipment assigned to an identifier value MAY change.  Allowing the identified device to change over time ensures

Reviewer comments:
Fixes issue
Benjamin writes, I suggest: >perhaps "given" is the wrong term here? Should we rephrase to
Looks good. Thanks!

Revised text:
3.2.1.  <ins> The Captive Network MUST associate the User Equipment with an identifier that is unique among the User Equipment that are interacting with the Captive Network at that time. </ins> Over time, the User Equipment assigned to an identifier value MAY change.  Allowing the identified device to change over time ensures
Original text:
toward the User Equipment.  This signal indicates that the User Equipment might need to contact the API Server to receive updated information.  For instance, this signal might be generated when the <del> end of a session is imminent, or when network access was denied. </del>  An Enforcement Device MUST rate-limit any signal generated in response to these conditions.  See section_signal_risks for a

Reviewer comments:
New SHOULD requirement to consider all signals as a single simple hint. Fixes issue Looking for reviewers to confirm this new SHOULD is OK.
Note Benjamin's reply to my question asking for clarification: My reply to that:
Closed in
lgtm

Revised text:
toward the User Equipment.  This signal indicates that the User Equipment might need to contact the API Server to receive updated information.  For instance, this signal might be generated when the  <ins> end of a session is imminent, or when network access was denied.  For simplicity, and to reduce the attack surface, all signals SHOULD be considered equivalent by the User Equipment: as a hint to contact the API.  If future solutions have multiple signal types, each type SHOULD be rate-limited independently. </ins> An Enforcement Device MUST rate-limit any signal generated in response to these conditions.  See section_signal_risks for a
Original text:
7.2. <del> The solution described here assumes that when the User Equipment needs to trust the API server, server authentication will be performed using TLS mechanisms. </del>  The Captive Portal API URI might change during the Captive Portal Session.  The User Equipment can apply the same trust mechanisms to

Reviewer comments:
A reviewer pointed out that we need to specify how TLS is used. Link to the existing procedure in the User Equipment requirements. Also rephrase so that it doesn't sound like we're suggestion that using TLS is optional.
I'm not sure if my 'link' is a good idea. I could just repeat the procedure verbatim, I suppose, but it seems like a waste of text.
Benjamin writes While in here, Roland writes:
This looks fine, but it might be more concise.

Revised text:
7.2.  <ins> The solution described here requires that when the User Equipment needs to access the API server, the User Equipment authenticates the server; see section_client. </ins> The Captive Portal API URI might change during the Captive Portal Session.  The User Equipment can apply the same trust mechanisms to
Original text:
2.2. <del> Here we discuss candidate mechanisms for provisioning the User Equipment with the Captive Portal API URI to query captive portal state and navigate the portal. </del>  2.2.1.

Reviewer comments:
We didn't really lay out the role of the provisioning service. While we still don't have any requirements on it, this changes the provisioning service section to give more guidance about its role in the network.
Any thoughts on whether we should expand to add some requirements? E.g. URI scheme MUST be HTTPS.
Roman writes, "The Provisioning Service is primarily responsible for providing a portal URI to the User Equipment when it connects to the network, and later if the URI changes. The provisioning service could also be the same service which is responsible for provisioning the User Equipment for access to the Captive Network (e.g. by providing it with an IP address). This section discusses two mechanisms which may be used to provide the portal URI to the User Equipment. It is expected that the provided URI will be for the API described in Section 2.3".

Revised text:
2.2.  <ins> The Provisioning Service is primarily responsible for providing a Captive Portal API URI to the User Equipment when it connects to the network, and later if the URI changes.  The provisioning service could also be the same service which is responsible for provisioning the User Equipment for access to the Captive Network (e.g., by providing it with an IP address).  This section discusses two mechanisms which may be used to provide the Captive Portal API URI to the User Equipment. </ins> 2.2.1.
Original text:
information.  If certificate validation fails, User Equipment MUST NOT make any calls to the API server.  2.2. The Provisioning Service is primarily responsible for providing a

Reviewer comments:
In section 4.2, we describe a condition where the session is about to expire. The UE detects this by consulting some form of storage. Yet, we never mentioned that it was proper to store any state. This commit adds a small section outlining that the UE can store state, with a brief discussion about the tradeoffs in doing so.
Roman writes, it retrieved from the API so that it could consult the time remaining (seconds-remainingin the API document). I can update section 2.1 to indicate that the UE could store informationfrom the API's response in order to trigger workflows related to imminent expiry of its access.Storing the state isn't required, but it could make the user experience better if supported.

Revised text:
information.  If certificate validation fails, User Equipment MUST NOT make any calls to the API server. <ins> The User Equipment can store the last response it received from the Captive Portal API as a cached view of its state within the Captive Network.  This state can be used to determine whether its Captive Portal Session is near expiry.  For example, the User Equipment might compare a timestamp indicating when the session expires to the current time.  Storing state in this way can reduce the need for communication with the Captive Portal API.  However, it could lead to the state becoming stale if the User Equipment's view of the relevant conditions (byte quota, for example) is not consistent with the Captive Portal API's. </ins> 2.2. The Provisioning Service is primarily responsible for providing a
Original text:
An Identifier is a characteristic of the User Equipment used by the components of a Captive Portal to uniquely determine which specific <del> User Equipment is interacting with them.  An Identifier MAY be a </del>  field contained in packets sent by the User Equipment to the External <del> Network.  Or, an Identifier MAY be an ephemeral property not </del>  contained in packets destined for the External Network, but instead correlated with such information through knowledge available to the different components.

Reviewer comments:
We were unnecessarily using normative language in section 3.1. Replace it with non-normative language.
Alvaro writes of possibilities. Replace the two 'MAY' occurrences with 'could'.

Revised text:
An Identifier is a characteristic of the User Equipment used by the components of a Captive Portal to uniquely determine which specific  <ins> User Equipment is interacting with them.  An Identifier can be a </ins> field contained in packets sent by the User Equipment to the External  <ins> Network.  Or, an Identifier can be an ephemeral property not </ins> contained in packets destined for the External Network, but instead correlated with such information through knowledge available to the different components.
Original text:
provide credentials to an attacker.  Browsers can authenticate servers but cannot detect cleverly misspelled domains, for example.  7.2. The solution described here requires that when the User Equipment

Reviewer comments:
When we trust a network, we introduce the risk of on path attacks. Mention a few of them as possibilities. A few questions for the reviewers: Should we mention that the list is not exhaustive, or is that implied? Should we mention mitigating factors? (i.e. some of the attacks I've mentioned should be prevented w/ proper use of TLS).
Roman writes, text as just one example.

Revised text:
provide credentials to an attacker.  Browsers can authenticate servers but cannot detect cleverly misspelled domains, for example. <ins> Further, the possibility of an on-path attacker in an attacking network introduces some risks.  The attacker could redirect traffic to arbitrary destinations.  The attacker could analyze the user's traffic leading to loss of confidentiality.  Or, the attacker could modify the traffic inline. </ins> 7.2. The solution described here requires that when the User Equipment
Original text:
for the URI MUST be https so that the User Equipment communicates with the User Portal over TLS.  A caller to the API needs to be presented with evidence that the content it is receiving is for a version of the API that it supports. For an HTTP-based interaction, such as in I-D.ietf-capport-api this

Reviewer comments:
A reviewer pointed out that we never really said that it was a desired proprety of the API that it limit access to a UE's state to itself. Add a requirement to that effect so we're explicit about that goal, and reference the identifier section that describes that it's a good property for the identity.
One thing we're not addressing here is a similar requirement on the User Portal. I feel like we should probably have one. Thoughts?
Thanks. Perhaps I'll do this in a separate PR to address
Roman writes, Martin agreed that we should do something like this in response to my question: We can add a requirement stating that the only the UE should be able to check its own state of captivity (work on the phrasing/normative text).
This sentence refers to URLs in the API blob, not the API itself. We definitely are okay with a common API URL or a guessable one. That’s an option.
Right. I'm not sure what I was thinking. NAME What about the URIs provided by the API itself? Do you have an opinion whether we should suggest that they be unguessable? One thought is that the API server and web portal could agree on an mechanism to cipher the UE's identifier, so that even if it's something possible guessable (i.e. the IP), and attacker couldn't spoof it.
Nice. I think that this is sufficient. The portal itself can use things like capability URLs to avoid needing this sort of check. (And then we're far into design and not architecture; this is nice because it talks about requirements.) If you feel motivated, you could add something, but it's tricky. The user portal doesn't need to use strong identifiers, because it can base its decisions on other things than the UE identifier. For instance, a capability URL (that is, a hard-to-guess URL) embedded in the API requires no external authentication.

Revised text:
for the URI MUST be https so that the User Equipment communicates with the User Portal over TLS. <ins> If the API receives a request for state that does not correspond to the requesting User Equipment, the API SHOULD deny access.  Given that the API might use the User Equipment's identifier for authentication, this requirement motivates id_recommended_hard. </ins> A caller to the API needs to be presented with evidence that the content it is receiving is for a version of the API that it supports. For an HTTP-based interaction, such as in I-D.ietf-capport-api this
Original text:
doesn't get notified when network access is restricted.  Hence, end- user devices MAY allow users to manually control captive portal interactions, possibly on the granularity of Provisioning Domains. 

Reviewer comments:
This adds a privacy section which discusses the implications of the User Equipment identity. I'm open to suggestions for more content here. Some thoughts: State that may not contain the identity, but can be mapped to from it? Logging?
Benjamin writes, We need a bit more text here.

Revised text:
doesn't get notified when network access is restricted.  Hence, end- user devices MAY allow users to manually control captive portal interactions, possibly on the granularity of Provisioning Domains. <ins> 7.6. ue_identity describes a mechanism by which all components within the Captive Portal are designed to use the same identifier to uniquely identify the User Equipment.  This identifier could be abused to track the user.  Implementers and designers of Captive Portals should take care to ensure that identifiers, if stored, are stored securely. Likewise, if any component communicates the identifier over the network, it should ensure the confidentiality of the identifier on the wire by using encryption such as TLS. There are benfits to choosing mutable anonymous identifiers.  For example, User Equipment could cycle through multiple identifiers to help prevent long-term tracking.  However, if the components of the network use an internal mapping to map the identity to a stable, long-term value in order to deal with changing identifiers, they need to treat that value as sensitive information: an attacker could use it to tie traffic back to the originating User Equipment, despite the User Equipment having changed identifiers. </ins>