jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-capport-architecture

Commentary: A reviewer found a problem with some phrasing , and also noticed that we missed a few captive networks . Clean them up .
Captive Portal User Equipment: Also known as User Equipment.  A
device which has voluntarily joined a network for purposes of
communicating beyond the constraints of the captive network.
Captive Portal User Equipment: Also known as User Equipment.  A
device which has voluntarily joined a network for purposes of
communicating beyond the constraints of the Captive Portal.
None of the above requirements are mandatory because (a) we do not
wish to say users or devices must seek full access to the captive
network, (b) the requirements may be fulfilled by manually visiting
the captive portal web application, and (c) legacy devices must
continue to be supported.
None of the above requirements are mandatory because (a) we do not
wish to say users or devices must seek full access to the Captive
Portal, (b) the requirements may be fulfilled by manually visiting
the captive portal web application, and (c) legacy devices must
continue to be supported.
Though a URI might still correctly resolve when the User Equipment
makes the request from a different network, it is possible that some
functions could be limited to when the User Equipment makes requests
using the captive network.  For example, payment options could be
absent or a warning could be displayed to indicate the payment is not
for the current connection.
Though a URI might still correctly resolve when the User Equipment
makes the request from a different network, it is possible that some
functions could be limited to when the User Equipment makes requests
using the Captive Portal.  For example, payment options could be
absent or a warning could be displayed to indicate the payment is not
for the current connection.
Draft: draft-ietf-capport-architecture

Commentary: The abstract seems weak . It should mention the problem domain and all of the components . Not sure if it needs to mention PvD at all . 
 Personally , I think that aside from the PvD mention , which can be removed , the current is mostly OK . Brief is good .
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.
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.
Draft: draft-ietf-capport-architecture

Commentary: 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 ?  ? 
  writes , We need a bit more text here .
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.
Draft: draft-ietf-capport-architecture

Commentary: 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 
  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 . 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 could n'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 does n'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 .
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.
Draft: draft-ietf-capport-architecture

Commentary: A reviewer pointed out that we used notifying , informing , signalling , and alerting to mean the same thing : sending the Captive Portal Signal . I 've chosen to use signal as the verb of choice . The phrasing seems a bit awkward in a few places , so I 'm not 100 % confident in my choice here . 
  writes , Let 's make this consistent across the entire document . Does n't have to be alert , but should be consistent . 
 Are we using User Equipment of end - user device ?
Captive Portal Signal: A notification from the network used to inform
the User Equipment that the state of its captivity could have
changed.
Captive Portal Signal: A notification from the network used to signal
to the User Equipment that the state of its captivity could have
changed.
Draft: draft-ietf-capport-architecture

Commentary: 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 .
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.
Draft: draft-ietf-capport-architecture

Commentary: We were unnecessarily using normative language in section 3.1 . Replace it with non - normative language . 
  writes of possibilities . Replace the two ' MAY ' occurrences with ' could ' .
An Identifier is a characteristic of the User Equipment used by the
components of a Captive Portal to uniquely determine which specific
User Equipment is interacting with them.  An Identifier MAY be a
field contained in packets sent by the User Equipment to the External
Network.  Or, an Identifier MAY be an ephemeral property not
contained in packets destined for the External Network, but instead
correlated with such information through knowledge available to the
different components.
An Identifier is a characteristic of the User Equipment used by the
components of a Captive Portal to uniquely determine which specific
User Equipment is interacting with them.  An Identifier can be a
field contained in packets sent by the User Equipment to the External
Network.  Or, an Identifier can be an ephemeral property not
contained in packets destined for the External Network, but instead
correlated with such information through knowledge available to the
different components.
Draft: draft-ietf-capport-architecture

Commentary: 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 is n't required , but it could make the user experience better if supported .
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.
Draft: draft-ietf-capport-architecture

Commentary: We did n't really lay out the role of the provisioning service . While we still do n'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 " .
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.
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.
Draft: draft-ietf-capport-architecture

Commentary: One of the reviewers asked for more information about the attacker in section 7.3 . This does so , describing what the attacker could achieve by compromising the security . 
  writes , Without knowing the details of the particular solution , it 's a bit hard to say for sure , but roughly I 'd say it 's someone who wants to interact with the API using the identity of the user . E.g. if we 're using an ' unguessable ' URI , an attacker snooping on the communication with the API could determine the URI , and use it .
An attacker with access to this information might be able to
masquerade as a specific User Equipment when interacting with the
API, which could then allow them to masquerade as that User Equipment
when interacting with the User Portal.  This could give them the
ability to determine whether the User Equipment has accessed the
portal, or deny the User Equipment service by ending their session
using mechanisms provided by the User Portal, or consume that User
Equipment's quota.  An attacker with the ability to modify the
information could deny service to the User Equipment, or cause them
to appear as a different User Equipment.
Draft: draft-ietf-capport-architecture

Commentary: 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 does n'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 . 
  writes While in here , Roland writes : 
 This looks fine , but it might be more concise .
The solution described here assumes that when the User Equipment
needs to trust the API server, server authentication will be
performed using TLS mechanisms.
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.
Draft: draft-ietf-capport-architecture

Commentary: Attempting to fix issue . I attempted to reword the principles , adding more prose for the rationale . Also upgraded some SHOULD NOT to MUST NOT because it seems some people thought the SHOULD NOT says the existing approach is OK . These are just some ideas . I wo n't be offended if rejected . 
 I believe I addressed all comments . You 'll probably want to review the complete diff again . 
  writes in his review :  replied with this suggested text : This seems reasonable , as I mentioned in the reply . We should go with it , unless anyone has an objection . Also , attribute it to   . 
 S. Moonesamy writes 
 One approach I suggested in my reply to the feedback : 
 This is good . Thanks for sorting through this ; it 's important that this is right , and you have cleared it up a lot . Much clearer . Thanks !
The authors thank Michael Richardson for providing wording requiring
DNSSEC and TLS to operate without the user adding exceptions.
Draft: draft-ietf-capport-architecture

Commentary: The language of this section was hard for some of the reviewers to understand . Rephrase it to be more explicit and clear . 
 Yes . We should probably rephrase this . E.g. " The user makes an informed choice in deciding to visit and trust the Captive Portal URI . Since the network provides   URI to the user equipment , thenetwork SHOULD do so securely so that the user 's trust in the network can extend to their trust of the Captive Portal URI . E.g. , the DHCPv6 AUTH option can sign this information . "
Given that a user chooses to visit a Captive Portal URI, the URI
location SHOULD be securely provided to the user's device.  E.g., the
DHCPv6 AUTH option can sign this information.
The user makes an informed choice to visit and trust the Captive
Portal URI.  Since the network provides Captive Portal URI to the
user equipment, the network SHOULD do so securely so that the user's
trust in the network can extend to their trust of the Captive Portal
URI.  E.g., the DHCPv6 AUTH option can sign this information.
Draft: draft-ietf-capport-architecture

Commentary: 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
When User Equipment first connects to a network, or when there are
changes in status, the Enforcement Device could generate a signal
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
end of a session is imminent, or when network access was denied.
When User Equipment first connects to a network, or when there are
changes in status, the Enforcement Device could generate a signal
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
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.
Draft: draft-ietf-capport-architecture

Commentary: Fixes issue 
  writes , I suggest : perhaps " given " is the wrong term here ? Should we rephrase to 
 Looks good . Thanks !
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.
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.
Draft: draft-ietf-capport-architecture

Commentary: 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 
  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 do n't properly indicate elsewhere that this should be supported . I thought we did , but I ca n'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 . 
  writes , Do it .
This section aims to improve understanding by describing a possible
workflow of solutions adhering to the architecture.
This section aims to improve understanding by describing a possible
workflow of solutions adhering to the architecture.  Note that the
section is not normative: it describes only as subset of possible
implementations.
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.
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.
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.
Draft: draft-ietf-capport-architecture

Commentary: 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 .
Captive Portal API: Also known as API.  An HTTP API allowing User
Equipment to query its state of captivity within the Captive Portal.
Captive Portal API: Also known as API.  An HTTP API allowing User
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).
Draft: draft-ietf-capport-architecture

Commentary: The idea of a session is important , both because it is used in the API document , and because it helps to tie everything together . Define it in the terminology . 
 This is a first stab at defining the session . I suspect we may need to iterate on it once or twice . Let me know if you think it deserves its own section on top of the terminology . 
 Thanks for doing this ! Here ’s a suggested alternate way to explain this . Feel free to modify as desired . Captive Portal Session : Also referred to simply as the “ session ” , a Captive Portal Session is the association for a particular User Equipment that starts when it interacts with the Captive Portal and gains open access to the network , and ends when the User Equipment moves back into the original captive state . The Captive Network maintains the state of each active Session , and can limit Sessions based on a length of time or a number of bytes used . The Session is associated with a particular User Equipment using the User Equipment 's identifier ( see < xref target="ue_identity"/ ) . 
 Your phrasing is better . It manages to work in the session limits while keeping it about the same lenght . I 've taken it almost verbatim . Do you have any input on this topic ? 
 From  's review of the API document , we should define " session " formally in the architecture . The architecture doc mentions it in passing once already . The API doc uses the term session much more .
Captive Portal Session: Also referred to simply as the "session", a
Captive Portal Session is the association for a particular User
Equipment that starts when it interacts with the Captive Portal and
gains open access to the network, and ends when the User Equipment
moves back into the original captive state.  The Captive Network
maintains the state of each active Session, and can limit Sessions
based on a length of time or a number of bytes used.  The Session is
associated with a particular User Equipment using the User
Equipment's identifier (see ue_identity).
Draft: draft-ietf-capport-architecture

Commentary: Whether or not the user visits the User Portal is optional : the user could choose not to , or the Captive Portal may not provide one . Clarify that the case presented in the component diagram is the one where the User Portal is present , and where the user chooses to visit it .
The following diagram shows the communication between each component.
The following diagram shows the communication between each component
in the case where the Captive Network has a User Portal, and the User
Equipment chooses to visit the User Portal in response to discovering
and interacting with the API Server.
Draft: draft-ietf-capport-architecture

Commentary: 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 do n'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 . 
 using MUST makes sense . I 've taken your suggestion . 
  writes : I would at least like to recommend that it 's TLS , so it 's considered . Discussion continuing on list .
At minimum, the API MUST provide the state of captivity.  Further the
API MUST be able to provide a URI for the User Portal.
At minimum, the API MUST provide the state of captivity.  Further the
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.