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

Commentary: The working group has decided that we do not need to tackle specifying the signaling protocol . Rather than leaving the document with it partially specified , remove most of the text related to it . Keep some basic examples of constraints . This also removes the text which claimed that the document would specify rqeuirements for the protocol . It does not . Made a few related editorial changes . 
 As suggested by : Do a pass through the document with this text in mind and make sure it makes sense . Clean up anything that may have depended on removed text . 
 Thanks for putting this together . This seems sufficient , and brief .
User Equipment may send traffic to hosts blocked by the captive
network prior to the Enforcement device granting it access.  The
Enforcement Device rightly blocks or resets these requests.  However,
in the absence of a signal from the Enforcement Device or interaction
with the API server, the User Equipment can only guess at whether it
is captive.  Consequently, allowing the Enforcement Device to
explicitly signal to the User Equipment that the traffic is being
blocked may improve the user's experience.
An Enforcement Device may also want to notify the User Equipment of a
pending expiry of its access to the external network, so providing
the Enforcement Device the ability to preemptively signal may be
desirable.
The Captive Portal Signaling Protocol does not provide any means of
indicating that the network prevents access to some destinations.
The intent is to rely on the Captive Portal API and the web portal to
which it points to communicate local network policies.
The Captive Portal Enforcement function MAY send Captive Portal
Signals when User Equipment that has not satisfied the Captive Portal
Conditions attempts to send traffic to the network.  These signals
MUST be rate-limited to a configurable rate.
The signals MUST NOT be sent to the destinations/peers that the User
Equipment is restricted from accessing.  The indications are only to
be sent to the User Equipment.
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.
An Enforcement Device MUST rate-limit any signal generated in
response to these conditions.  See section_signal_risks for a
discussion of risks related to a Captive Portal Signal.
Draft: draft-ietf-capport-architecture

Commentary: provides a definition of " Global DNS " to which we might want to link . 
 Thanks !
The URLs provided in the API SHOULD contain all the information
necessary to render the resources requested: the resources should not
depend on ambient information, such as remote address on the
connection.  This is to ensure that the content served from these
URLs is correct and meaningful to the User Equipment, even when
accessed from a network other than the one that contains the captive
portal.  One consequence of this is that URLs provided in the API are
expected to be resolved using public DNS.
The URLs provided in the API SHOULD contain all the information
necessary to render the resources requested: the resources should not
depend on ambient information, such as remote address on the
connection.  This is to ensure that the content served from these
URLs is correct and meaningful to the User Equipment, even when
accessed from a network other than the one that contains the captive
portal.  One consequence of this is that URLs provided in the API are
expected to be resolved using public global DNS (as defined in
Section 2 of RFC8499).
Draft: draft-ietf-capport-architecture

Commentary: Trying to improve clarity . 
 Thanks !
None of the above requirements are mandatory because (a) we do not
wish to say users or devices must seek access beyond 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
network, (b) the requirements may be fulfilled by manually visiting
the captive portal web application, and (c) legacy devices must
continue to be supported.
User Equipment may send traffic outside the captive network prior to
the Enforcement device granting it access.  The Enforcement Device
rightly blocks or resets these requests.  However, lacking a signal
from the Enforcement Device or interaction with the API server, the
User Equipment can only guess at whether it is captive.
Consequently, allowing the Enforcement Device to signal to the User
Equipment that there is a problem with its connectivity may improve
the user's experience.
User Equipment may send traffic to hosts blocked by the captive
network prior to the Enforcement device granting it access.  The
Enforcement Device rightly blocks or resets these requests.  However,
lacking a signal from the Enforcement Device or interaction with the
API server, the User Equipment can only guess at whether it is
captive.  Consequently, allowing the Enforcement Device to explicitly
signal to the User Equipment that the traffic is being blocked may
improve the user's experience.
The signals MUST NOT be sent to the Internet devices.  The
indications are only sent to the User Equipment.
The signals MUST NOT be sent to the destinations/peers that the User
Equipment is restricted from accessing.  The indications are only to
be sent to the User Equipment.
When joining a network, some trust is placed in the network operator.
This is usually considered to be a decision by a user on the basis of
the reputation of an organization.  However, once a user makes such a
decision, protocols can support authenticating a network is operated
by who claims to be operating it.  The Provisioning Domain
Architecture RFC7556 provides some discussion on authenticating an
operator.
When joining a network, some trust is placed in the network operator.
This is usually considered to be a decision by a user on the basis of
the reputation of an organization.  However, once a user makes such a
decision, protocols can support authenticating that a network is
operated by who claims to be operating it.  The Provisioning Domain
Architecture RFC7556 provides some discussion on authenticating an
operator.
Draft: draft-ietf-capport-architecture

Commentary: Thanks . I merged in the most recent changes to resolve the conflict .
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC2119.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 RFC2119 RFC8174 when, and only when, they appear in all capitals,
as shown here.
Draft: draft-ietf-capport-architecture

Commentary: This removes some text around discovering URLs with 7710[bis ] and PvD. That extra context can be handled by those documents . This builds on . 
 Looks good 
 Lgtm 
 LGTM
A standard for providing a portal URI using DHCP or Router
Advertisements is described in RFC7710.  The CAPPORT architecture
expects this URI to indicate the API described in section_api.
A standard for providing a portal URI using DHCP or Router
Advertisements is described in RFC7710bis.  The CAPPORT architecture
expects this URI to indicate the API described in section_api.
The PvD security model provides secure binding between the
information provided by the trusted Router Advertisement and the
HTTPS server.
Draft: draft-ietf-capport-architecture

Commentary: Note that this leaves this paragraph intact : That paragraph probably needs to go based on what is in 7710bis now . 
 And remove some of the stuff that is speculative from SS2.2.1 .
A standard for providing a portal URI using DHCP or Router
Advertisements is described in RFC7710.  The CAPPORT architecture
expects this URI to indicate the API described in section_api.
A standard for providing a portal URI using DHCP or Router
Advertisements is described in RFC7710bis.  The CAPPORT architecture
expects this URI to indicate the API described in section_api.
Draft: draft-ietf-capport-architecture

Commentary: Thanks for doing this ! I 've left a few minor comments . 
 Just for transparency .  and I discussed this and made a few editorial changes . 
 thanks , was just trying to work on the changes here 
 Based on discussion in Singapore , the group decided to recommend ( not require ) that URLs use names that can be resolved from the public DNS ( no split horizon , etc ... ) . The content served from those URLs should also not be dependent on the network path , but instead the URL would include all information necessary to produce the resource . 
 i remember we were talking about primarily venue URL should be context free however , the architecture doc does not mention the venue URL ( only portal URL ) which section shall we add this context - free please ? ( maybe in  ? ) shall we also mention this in the api doc ? 
 I think that might want to think about what to include once we have text here . The text can be generic . I would suggest a new Section 3.5 as this relates to identification of UE . That is , you say that information presented in the API - and in particular URLs - need to include identification UE information . In particular , any information that is used from this context should not depend on ambient information , such as the remote address on a connection , as this information might be used by the UE on a different network interface . For example , a user might access venue information URLs from another network . You might also then mention that this might expose the service to spoofing or replay of that information in those cases . This might mean that though the URL might " work " , it might not present all options . For instance , payment options might not be offered , or if they are , warnings might be shown that the payment is not for the current connection . 
 Thanks for doing this . This seems to accurately capture the outcome of the discussion we had .
The URLs provided in the API SHOULD contain all the information
necessary to render the resources requested: the resources should not
depend on ambient information, such as remote address on the
connection.  This is to ensure that the content served from these
URLs is correct and meaningful to the User Equipment, even when
accessed from a network other than the one that contains the captive
portal.  One consequence of this is that URLs provided in the API are
expected to be resolved using public DNS.
Though a URL might still correctly resolve when the UE makes the
request from a different network, it is possible that some functions
could be limited to when the UE 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.
URLs could include some means of identifying the User Equipment in
the URLs.  However, including unauthenticated User Equipment
identifiers in the URL may expose the service to spoofing or replay
attacks.
Draft: draft-ietf-capport-architecture

Commentary: PvD is almost certainly going to be published first , so remove the lead - in to it in preparation for integrating the full rfc soon . 
 When the document says : It might be better to just remove the lead - in part , since it appears PvD will be published ahead of this document .
Although still a work in progress, I-D.ietf-intarea-provisioning-
domains proposes a mechanism for User Equipment to be provided with
PvD Bootstrap Information containing the URI for a JSON file
containing key-value pairs to be downloaded over HTTPS.  This JSON
file would fill the role of the Captive Portal API described in
section_api.
I-D.ietf-intarea-provisioning-domains proposes a mechanism for User
Equipment to be provided with PvD Bootstrap Information containing
the URI for a JSON file containing key-value pairs to be downloaded
over HTTPS.  This JSON file would fill the role of the Captive Portal
API described in section_api.
Draft: draft-ietf-capport-architecture

Commentary: We were using CAPPORT API to refer to the API or the API server without any real consistency . Clean this up by removing CAPPORT and using API / API Server as the short forms for the Captive Portal API and Captive Portal API Server . I also removed all references to from the architecture diagram . I think the only remaining " CAPPORT " occurrences refer to the architecture itself . Not sure what we want to do there . Fixes Issue . 
 This is a little inconsistent . I see " CAPPORT API " and " Captive Portal API " , but mostly just " API " or " API server " . Having a short form ( API ) seems useful . The longer form probably needs to be " Captive Portal API " to avoid having to define what " CAPPORT " means . There seems to be value in distinguishing between the API and the entity that provides it , so maybe the latter distinction is fine to leave alone . 
 So " API " as short for " Captive Portal API " and " API server " as short for " Captive Portal API server " ? Seems reasonable . 
 Fixed in 
 Very nice , thanks .
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 Server: Also known as API Server.  A server
hosting the Captive Portal API.
During provisioning (e.g., DHCP), the User Equipment acquires the
URI for the CAPPORT API.
During provisioning (e.g., DHCP), the User Equipment acquires the
URI for the Captive Portal API.
The CAPPORT web portal server directs the Captive Portal
Enforcement device to either allow or deny external network access
for the User Equipment.
Although the provisioning, API, and web portal functions are shown as
discrete blocks, they could of course be combined into a single
element.
The Web Portal Server directs the Captive Portal Enforcement
device to either allow or deny external network access for the
User Equipment.
Although the Provisioning Service, API Server, and Web Portal Server
functions are shown as discrete blocks, they could of course be
combined into a single element.
Since the API will need to perform operations which rely on the
identity of the user equipment, such as query whether it is captive,
the API needs to be able to relate requests to the User Equipment
making the request.
Since the API Server will need to perform operations which rely on
the identity of the user equipment, such as query whether it is
captive, the API Server needs to be able to relate requests to the
User Equipment making the request.
Draft: draft-ietf-capport-architecture

Commentary: Just realized that , this section may also apply to the case of initial provisioning of Portal URI if multiple ways are used , such as : DHCPv4 / DHCPv6 / RA could be used at the same time , and they return different values ; to quote 7710bis : However , if the URIs learned are not in fact all identical the captive device MUST prioritize URIs learned from network provisioning or configuration mechanisms before all other URIs . Specifically , URIs learned via any of the options in Section 2 should take precedence over any URI learned via some other mechanism , such as a redirect . Shall we mention anything on the initial provisioning case too here ? or that will only in 7710bis ? 
 Probably not a lot , except that future requests might go there . Because we do n't hold any state for these resources , that 's probably OK . 
 do you think that you could take a swing at this ? 
 By portal URI , you meant the URL to the json file ? If so , it seems the ways how it could be changed are : In the case of DHCPv4 / v6,in a renewal / rebind of DHCPv4 / v6 lease , the end user equipment could receive a new portal URI in the DHCP renew / rebind response . In the case of RA , the end user device may receive a new portal URI in a new RA message . ( In RA case , is it possible that there are multiple RA servers sending out different portal URI ? ) Is there any other possibilities ? Do I understand correctly that you are suggesting add something like the following ? If a new Portal URI is provided via DHCPv4 / v6 renew / rebind or RA , use the new one . Where shall we add this section please ? a new paragraph under 2.2.1 . DHCP or Router Advertisements ? or a new sub section 4.3 under 4 Solution Workflow ? 
 Right . I forget whether this was about the API URL ( the JSON ) or the user portal URL . In either case , they can change and I think that 's OK . The RA case is interesting in the sense that it might imply a different router advertising different coordinates , as you say , but if it is the same router , then that should be regarded as a change . This came up in discussion and some people felt that it needed to be acknowledged . Your suggested outcome is probably the only sensible one : if you need to contact the API , use the most recent value you have . As for location in the document , a new Section 4.x describing how updated details can be acquired seems right . 
 Fixed in 
 Thanks for doing this . I have a few small suggestions . Looks good . Thanks !
If DHCP is used, a lease renewal/rebind may return a different
Captive Portal API URI.
If RA is used, a new Captive Portal API URI may be specified in a
new RA message received by end user equipment.
Whenever a new Portal URI is received by end user equipment, it
SHOULD discard the old URI and use the new one for future requests to
the API.
Draft: draft-ietf-capport-architecture

Commentary: Point out that future Captive Portal Signalling Protocols will not enable non - binary blocking . Fixes Issue 
 There are networks that want to selectively block things . We are n't going to get consensus on whether that is good practice , but we do have consensus that we do n't provide protocol mechanisms for communicating about selective blocking . Document that fact . 
 Closed in .
The Captive Portal Signaling Protocol does not provide any means of
indicating that the network prevents access to some destinations.
The intent is to rely on the Captive Portal API and the web portal to
which it points to communicate local network policies.
Draft: draft-ietf-capport-architecture

Commentary: Fixes Issue 
 Thanks for the quick review . 
 The information needs to only apply to the current point of network attachment . That is obvious , perhaps , but worth stating . Thanks to   . 
 Can you take a look at PR ? I want to make sure I 've captured Warren 's point properly . 
 I think that 's about right . But you should avoid 2119 language . I have a few suggestions ( if only GitHub had multi - line suggestions ... ) .
An identifier might only apply to the current point of network
attachment.  If the device moves to a different network location its
identity could change.
Draft: draft-ietf-capport-architecture

Commentary: We want to make TLS a requirement , not a suggestion , so I 've chagned the wording around TLS to reflect this . I also a section to the security section discussing the motivation behind the requirement . 
 Can you forward to the list please ?
The CAPPORT API MUST support TLS for privacy and server
authentication.
The API MUST use TLS for privacy and server authentication.  The
implementation of the API MUST ensure both privacy and integrity of
any information provided by or required by it.
The solution described here assumes that when the User Equipment
needs to trust the API server, server authentication will be utilized
using TLS mechanisms.
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 the API be secured using
TLS.  This is required to allow the user equipment and API server to
exchange secrets which can be used to validate future interactions.
The API must ensure the integrity of this information, as well as its
confidentiality.