jiebi/TextFlow huggingface dataset:
Original text:
Captive Portal API Server: Also known as API Server.  A server hosting the Captive Portal API. <del> Captive Portal Signal: A notification from the network used to inform the User Equipment that the state of its captivity could have </del>  changed. Captive Portal Signaling Protocol: Also known as Signaling Protocol.

Reviewer comments:
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.
Alvaro writes, Let's make this consistent across the entire document. Doesn't have to be alert, but should be consistent.
Are we using User Equipment of end-user device?

Revised text:
Captive Portal API Server: Also known as API Server.  A server hosting the Captive Portal API.  <ins> Captive Portal Signal: A notification from the network used to signal to the User Equipment that the state of its captivity could have </ins> changed. Captive Portal Signaling Protocol: Also known as Signaling Protocol.
Original text:
7.5. <del> The Captive Portal Signal could inform the User Equipment that it is being held captive.  There is no requirement that the User Equipment do something about this.  Devices MAY permit users to disable automatic reaction to Captive Portal Signals indications for privacy reasons.  However, there would be the trade-off that the user doesn't get notified when network access is restricted.  Hence, end-user devices MAY allow users to manually control captive portal </del>  interactions, possibly on the granularity of Provisioning Domains.

Reviewer comments:
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.
Alvaro writes, Let's make this consistent across the entire document. Doesn't have to be alert, but should be consistent.
Are we using User Equipment of end-user device?

Revised text:
7.5.  <ins> The Captive Portal Signal could signal to the User Equipment that it is being held captive.  There is no requirement that the User Equipment do something about this.  Devices MAY permit users to disable automatic reaction to Captive Portal Signals indications for privacy reasons.  However, there would be the trade-off that the user doesn't get notified when network access is restricted.  Hence, end- user devices MAY allow users to manually control captive portal </ins> interactions, possibly on the granularity of Provisioning Domains.
Original text:
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 <del> the solution.  The role of Provisioning Domains (PvDs) is described. </del>  1.

Reviewer comments:
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.

Revised text:
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  <ins> the solution. </ins> 1.
Original text:
The User Equipment's access to the outside network continues uninterrupted  5. The authors thank Lorenzo Colitti for providing the majority of the

Reviewer comments:
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 don't hold any state for these resources, that's probably OK.
NAME 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!

Revised text:
The User Equipment's access to the outside network continues uninterrupted <ins> 4.3. A different Captive Portal API URI could be returned in the following cases: 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. </ins> 5. The authors thank Lorenzo Colitti for providing the majority of the
Original text:
the equipment. At minimum, the API MUST provide: (1) the state of captivity and (2) <del> a URI for the Captive Portal Server.  The API SHOULD provide evidence to the caller that it supports the present architecture. </del>  When User Equipment receives Captive Portal Signals, the User Equipment MAY query the API to check the state.  The User Equipment

Reviewer comments:
Everyone was confused by the phrasing that the API needed to provide evidence it supported the architecture. Since it's a proper component of the architecture, it doesn't really need to; that is assumed. Rather, it needs to inform the client of versions/types/etc so that the client can determine whether it supports the API. Rephrase accordingly. Fixes issue
Thanks again for the suggested text, NAME
A reviewer says, Suggestion: state that a version of the protocol should be included in the API response.
Isn't the content-type of the API response sufficient indication? That implies that we might need a new content-type if we want to make incompatible changes in a subsequent revision, but I think that is a good plan.
At the architecture level, can we state the point more clearly? Maybe better to state what the User Equipment should do if the API response doesn't make sense?
So, the fact that we've discovered the API likely means that we're interacting with the architecture -- i.e. we got there from PvD or the dhcp option. So, I'm not sure what it would mean to not support the architecture in that case. It would be a provisioning mistake, I guess? We should suggest what the UE could do in that case, though, for robustness. So, maybe mention that the API should have a content-type in the response to indicate that it is indeed a captive portal API, and then what to do if the UE doesn't recognize that?
So I think that the reviewer here was simply confused about the choice of words and phrasing. How about: 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 {{API}} this might be achieved by using a content type that is unique to the protocol.

Revised text:
the equipment. At minimum, the API MUST provide: (1) the state of captivity and (2)  <ins> a URI for the Captive Portal Server. 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 might be achieved by using a content type that is unique to the protocol. </ins> When User Equipment receives Captive Portal Signals, the User Equipment MAY query the API to check the state.  The User Equipment
Original text:
The length of the Certificate message once it is uncompressed.  If after decompression the specified length does not match the actual length, the party receiving the invalid message MUST abort the <del> connection with the "bad_certificate" alert. </del>  The compressed body of the Certificate message, in the same format as it would normally be expressed in.  The compression algorithm

Reviewer comments:
State explicitly that we do not define any compression dictionaries. Explain the rationale behind the uncompressed_length field. Addresses comments from John Mattsson on the list.
Actually, I have a small nit.

Revised text:
The length of the Certificate message once it is uncompressed.  If after decompression the specified length does not match the actual length, the party receiving the invalid message MUST abort the  <ins> connection with the "bad_certificate" alert.  The presence of this field allows the receiver to pre-allocate the buffer for the uncompressed Certificate message and to enforce limits on the message size before performing decompression. </ins> The compressed body of the Certificate message, in the same format as it would normally be expressed in.  The compression algorithm
Original text:
brotli, the Certificate message MUST be compressed with the Brotli compression algorithm as defined in RFC7932.  If the received CompressedCertificate message cannot be decompressed, the connection MUST be torn down with the "bad_certificate" alert.

Reviewer comments:
State explicitly that we do not define any compression dictionaries. Explain the rationale behind the uncompressed_length field. Addresses comments from John Mattsson on the list.
Actually, I have a small nit.

Revised text:
brotli, the Certificate message MUST be compressed with the Brotli compression algorithm as defined in RFC7932. <ins> It is possible to define a certificate compression algorithm that uses a pre-shared dictionary to achieve higher compression ratio. This document does not define any such algorithms. </ins> If the received CompressedCertificate message cannot be decompressed, the connection MUST be torn down with the "bad_certificate" alert.
Original text:
message MUST be compressed with the ZLIB compression algorithm, as defined in RFC1950.  If the specified compression algorithm is brotli, the Certificate message MUST be compressed with the Brotli <del> compression algorithm as defined in RFC7932. </del>  It is possible to define a certificate compression algorithm that uses a pre-shared dictionary to achieve higher compression ratio.

Reviewer comments:
Parking this here; if we have a consensus on the list to add it, we should merge this.

Revised text:
message MUST be compressed with the ZLIB compression algorithm, as defined in RFC1950.  If the specified compression algorithm is brotli, the Certificate message MUST be compressed with the Brotli  <ins> compression algorithm as defined in RFC7932.  If the specified compression algorithm is zstd, the Certificate message MUST be compressed with the Zstandard compression algorithm as defined in RFC8478. </ins> It is possible to define a certificate compression algorithm that uses a pre-shared dictionary to achieve higher compression ratio.
Original text:
4.3.1. <del> An endpoint can use the critical Default-Uri-Host Option to indicate the default value for the Uri-Host Options in the messages that it sends to the other endpoint.  Its value MUST be a valid value for the Uri-Host Option (Section 5.10.1 of RFC7252). For TLS, the base value for the Default-Uri-Host Option in the direction from the Connection Initiator to the Connection Acceptor is given by the SNI value. For WebSockets, the base value for the Default-Uri-Host Option in the direction from the Connection Initiator to the Connection Acceptor is given by the HTTP Host header field. The active value of the Default-Uri-Host Option is replaced each time the option is sent with a modified value.  Its starting value is its base value (if available). 4.3.2. </del> The sender can use the elective Max-Message-Size Option to indicate the maximum message size in bytes that it can receive.

Reviewer comments:
The next pass will add text related to the default URI-Host for TLS SNI cases.

Revised text:
4.3.1.  The sender can use the elective Max-Message-Size Option to indicate the maximum message size in bytes that it can receive.
Original text:
the option is sent with a modified value.  Its starting value is its base value. <del> 4.3.3. </del>  A sender can use the elective Block-wise Transfer Option to indicate that it supports the block-wise transfer protocol RFC7959.

Reviewer comments:
The next pass will add text related to the default URI-Host for TLS SNI cases.

Revised text:
the option is sent with a modified value.  Its starting value is its base value.  <ins> 4.3.2. </ins> A sender can use the elective Block-wise Transfer Option to indicate that it supports the block-wise transfer protocol RFC7959.
Original text:
Release messages can indicate one or more reasons using elective options.  The following options are defined: <del> The elective Bad-Default-Uri-Host Option indicates that the default indicated by the CSM Default-Uri-Host Option is unlikely to be useful for this server. </del> The elective Alternative-Address Option requests the peer to instead open a connection of the same scheme as the present connection to the alternative transport address given.  Its value is in the form

Reviewer comments:
The next pass will add text related to the default URI-Host for TLS SNI cases.

Revised text:
Release messages can indicate one or more reasons using elective options.  The following options are defined:  The elective Alternative-Address Option requests the peer to instead open a connection of the same scheme as the present connection to the alternative transport address given.  Its value is in the form
Original text:
successful connection to the Alternative-Address inherits all the security properties of the current connection. <del> SNI vs. Default-Uri-Host: Any security negotiated in the TLS handshake is for the SNI name exchanged in the TLS handshake and checked against the certificate provided by the server.  The Default-Uri-Host Option cannot be used to extend these security properties to the additional server name. </del> 9. 9.1.

Reviewer comments:
The next pass will add text related to the default URI-Host for TLS SNI cases.

Revised text:
successful connection to the Alternative-Address inherits all the security properties of the current connection.  9. 9.1.
Original text:
environments, CoAP needs to support different transport protocols, namely TCP RFC0793, in some situations secured by TLS RFC5246. <del> In addition, some corporate networks only allow Internet access via a HTTP proxy.  In this case, the best transport for CoAP might be the RFC6455.  The WebSocket protocol provides two-way communication between a WebSocket client and a WebSocket server after upgrading an RFC7230 connection and may be available in an environment that blocks CoAP over UDP.  Another scenario for CoAP over WebSockets is a CoAP application running inside a web browser without access to connectivity other than HTTP and WebSockets. </del>  This document specifies how to access resources using CoAP requests and responses over the TCP, TLS and WebSocket protocols.  This allows

Reviewer comments:
I realize that the specific review feedback was for the Introduction - but might we also want to "minimize" the number of WS configurations discussed in Section 4 to focus on the browser motivation?
While the third configuration is not mentioned in the introduction, all three are motivated by in-browser app use cases. So I don’t see a need to cut down the discussion in Section 4. Grüße, Carsten
: The introduction motivates the layering of COAP over WebSockets to allow it to be used in a network that only allows external access through a HTTP proxy. In fact, it is not necessary to use WebSockets to do so; HTTP CONNECT provides a tunnel in this scenario. WebSockets is a specialised protocol that allows bidirectional, stream-based transport from a Web browser -- it is effectively TCP wrapped into the Web browser's security model, to make doing so safe. Using it for other purposes (i.e., non-browser use cases) isn't really appropriate. I'd suggest either removing the WebSockets binding, or changing its motivation in the Introduction. For reference, the original URL motivation:

Revised text:
environments, CoAP needs to support different transport protocols, namely TCP RFC0793, in some situations secured by TLS RFC5246.  <ins> CoAP applications running inside a web browser without access to connectivity other than HTTP and the RFC6455 may cross-proxy their CoAP requests via HTTP to a HTTP-to-CoAP cross-proxy or transport them via the the WebSocket protocol, which provides two-way communication between a WebSocket client and a WebSocket server after upgrading an RFC7230 connection. </ins> This document specifies how to access resources using CoAP requests and responses over the TCP, TLS and WebSocket protocols.  This allows
Original text:
can send a CoAP Ping Signaling message (see sec-ping) to test the connection and verify that the CoAP server is responsive.  4. CoAP over WebSockets is intentionally similar to CoAP over TCP;

Reviewer comments:
1: It is not clear how the protocol reacts the errors from transport layers (e.g. connection failure). The protocol will just inform apps of the events and the app will decide what to do or the protocol itself will do something? The WebSockets case is addressed by RFC6455: -and- After review with the authors, we'll append a clarification for CoAP over TCP in its Connection Health section.

Revised text:
can send a CoAP Ping Signaling message (see sec-ping) to test the connection and verify that the CoAP server is responsive. <ins> When the underlying TCP connection is closed or reset, the signaling state and any observation state (see observe-cancel) associated with the reliable connection are removed.  In flight messages may or may not be lost. </ins> 4. CoAP over WebSockets is intentionally similar to CoAP over TCP;
Original text:
method allowed for doing MAC-ed messages.  In COSE, all of the key management methods can be used for MAC-ed messages.  5.2.2. In key wrapping mode, the CEK is randomly generated and that key is

Reviewer comments:
Correct descriptions of Direct and Key Agreement Direct Change examples in the back to have "real" examples - they are JSON rather than CBOR, but that makes them shorter and easier to read.

Revised text:
method allowed for doing MAC-ed messages.  In COSE, all of the key management methods can be used for MAC-ed messages. <ins> The COSE_encrypt structure for the recipient is organized as follows: The 'protected', 'iv', 'aad', 'ciphertext' and 'recipients' fields MUST be null. The plain text to be encrypted is the key from next layer down (usually the content layer). At a minimum, the 'unprotected' field SHOULD contain the 'alg' parameter as well as a parameter identifying the shared secret. </ins> 5.2.2. In key wrapping mode, the CEK is randomly generated and that key is
Original text:
The COSE_encrypt structure for the recipient is organized as follows:  5.2.5. Key Agreement with Key Wrapping uses a randomly generated CEK.  The

Reviewer comments:
Correct descriptions of Direct and Key Agreement Direct Change examples in the back to have "real" examples - they are JSON rather than CBOR, but that makes them shorter and easier to read.

Revised text:
The COSE_encrypt structure for the recipient is organized as follows: <ins> The 'protected', 'aad', 'iv', and 'tag' fields all use the 'null' value. At a minimum, the 'unprotected' field SHOULD contain the 'alg' parameter as well as a parameter identifying the asymmetric key. The 'unprotected' field MUST contain the 'epk' parameter. </ins> 5.2.5. Key Agreement with Key Wrapping uses a randomly generated CEK.  The
Original text:
This parameter holds a part of the IV value.  When using the COSE_Encrypted structure, frequently a portion of the IV is part of the context associated with the key value.  This field is used <del> to carry the portion of the IV that changes for each message.  As the IV is authenticated by the encryption process, this value can be placed in the unprotected header bucket.  The 'Initialization Vector' and 'Partial Initialization Vector' parameters MUST NOT be present in the same security layer. The final IV is generated by concatenating the fixed portion of the IV, a zero string and the changing portion of the IV.  The length of the zero string is computed by taking the required IV length and subtracting the lengths of the fixed and changing IV portions. </del>  This parameter holds a counter signature value.  Counter signatures provide a method of having a second party sign some

Reviewer comments:
This was inspired by the IV computation for TLS. It may or may not make things more secure. The old behavior is easy to get by making the context IV have trailing zeros.

Revised text:
This parameter holds a part of the IV value.  When using the COSE_Encrypted structure, frequently a portion of the IV is part of the context associated with the key value.  This field is used  <ins> to carry a value that causes the IV to be changed for each message.  As the IV is authenticated by the encryption process, this value can be placed in the unprotected header bucket.  The 'Initialization Vector' and 'Partial Initialization Vector' parameters MUST NOT be present in the same security layer. The message IV is generated by the following steps: Left pad the partial IV with zeros to the length of IV. XOR the padded partial IV with the context IV. </ins> This parameter holds a counter signature value.  Counter signatures provide a method of having a second party sign some