jiebi/TextFlow huggingface dataset:
Original text:
multiple entities to manage certificates). Authorization resources are created by the server in response to <del> newOrder or newAuthorization requests submitted by an account key holder; their URLs are provided to the client in the responses to these requests.  The authorization object is implicitly tied to the account key used to sign the request. </del>  When a client receives an order from the server in reply to a newOrder request, it downloads the authorization resources by sending

Reviewer comments:
"newAuthorization" -> "newAuthz" Reverted the indentation on the IANA considerations since that resulted in the wrong XML

Revised text:
multiple entities to manage certificates). Authorization resources are created by the server in response to  <ins> newOrder or newAuthz requests submitted by an account key holder; their URLs are provided to the client in the responses to these requests.  The authorization object is implicitly tied to the account key used to sign the request. </ins> When a client receives an order from the server in reply to a newOrder request, it downloads the authorization resources by sending
Original text:
can be accessed in a Link header with link relation "terms-of- service".  As noted above, the client may indicate its agreement with these terms by updating its registration to include the "agreement" <del> field, with the terms URI as its value. </del>  If the client wishes to update this information in the future, it sends a POST request with updated information to the registration

Reviewer comments:
I'm not sure whether we should add something like:
I think "in a way that requires an agreement update" as you've written is clear enough. Users won't need to re-agree if just fixing a typographical error.

Revised text:
can be accessed in a Link header with link relation "terms-of- service".  As noted above, the client may indicate its agreement with these terms by updating its registration to include the "agreement"  <ins> field, with the terms URI as its value.  When these terms change in a way that requires an agreement update, the server MUST use a different URI in the Link header. </ins> If the client wishes to update this information in the future, it sends a POST request with updated information to the registration
Original text:
CAs that use ACME to automate issuance will need to ensure that their servers perform all necessary checks before issuing. <del> 10.  References </del>  <del> 10.1.  URIs </del>  [1] https://github.com/ietf-wg-acme/acme

Reviewer comments:
At the IETF meeting, we discussed the possibility of simplifying the "tls-sni-01" challenge to remove the iterations, as suggested in . NAME noted that if we were going to do that, we should recommend some ways for CAs to check whether a default vhost was in play. This PR adds such a note, and creates an "Operational Considerations" section for any future such notes that might come along.

Revised text:
CAs that use ACME to automate issuance will need to ensure that their servers perform all necessary checks before issuing.  <ins> 10. </ins>  <ins> There are certain factors that arise in operational reality that operators of ACME-based CAs will need to keep in mind when configuring their services. [[ TODO: Other operational considerations ]] 10.1. In many cases, TLS-based services are deployed on hosted platforms that use the Server Name Indication (SNI) TLS extension to distinguish between different hosted services or "virtual hosts". When a client initiates a TLS connection with an SNI value indicating a provisioned host, the hosting platform routes the connection to that host. When a connection come in with an unknown SNI value, one might expect the hosting platform to terminate the TLS connection.  However, some hosting platforms will choose a virtual host to be the "default", and route connections with unknown SNI values to that host. In such cases, the owner of the default virtual host can complete a TLS-based challenge (e.g., "tls-sni-01") for any domain with an A record that points to the hosting platform.  This could result in mis-issuance in cases where there are multiple hosts with different owners resident on the hosting platform. A CA that accepts TLS-based proof of domain control should attempt to check whether a domain is hosted on a domain with a default virtual host before allowing an authorization request for this host to use a TLS-based challenge.  A default virtual host can be detected by initiating TLS connections to the host with random SNI values within the namespace used for the TLS-based challenge (the "acme.invalid" namespace for "tls-sni-01"). 11.  References 11.1.  URIs </ins> [1] https://github.com/ietf-wg-acme/acme
Original text:
The server provides the following fields as part of the challenge: <del> The string "proofOfPossession-01" </del>  An array of certificates, in Base64url-encoded DER format, that contain acceptable public keys. object including data related to the challenge.  The validation object covered by the signature has the following fields: <del> The string "proofOfPossession" </del>  A list of identifiers for which the holder of the prior key authorizes the new key with a signature over that nonce by one of the private keys requested by the server. <del> The string "proofOfPossession" </del>  The validation JWS Decode the payload of the JWS as UTF-8 encoded JSON Verify that there are exactly three fields in the decoded object, <del> and that: * The "type" field is set to "proofOfPossession" * The </del>  "identifier" field contains the identifier for which authorization is being validated * The "accountKey" field matches the account key for which the challenge was issued

Reviewer comments:
awesome thanks :+1:
Any reason for the inconsistent naming of the challenge types? Specifically vs Wouldn't it make sense to stick to dash delimited words? or just camelCase, not that it matter as long as its consistent. I would personally avoid camelcase in that context since there is already a lot acronyms.

Revised text:
The server provides the following fields as part of the challenge:  <ins> The string "proof-of-possession-01" </ins> An array of certificates, in Base64url-encoded DER format, that contain acceptable public keys. object including data related to the challenge.  The validation object covered by the signature has the following fields:  <ins> The string "proof-of-possession" </ins> A list of identifiers for which the holder of the prior key authorizes the new key with a signature over that nonce by one of the private keys requested by the server.  <ins> The string "proof-of-possession" </ins> The validation JWS Decode the payload of the JWS as UTF-8 encoded JSON Verify that there are exactly three fields in the decoded object,  <ins> and that: * The "type" field is set to "proof-of-possession" * The </ins> "identifier" field contains the identifier for which authorization is being validated * The "accountKey" field matches the account key for which the challenge was issued
Original text:
In order to help clients configure themselves with the right URIs for each ACME operation, ACME servers provide a directory object.  This <del> should be the root URL with which clients are configured.  It is a JSON dictionary, whose keys are the "resource" values listed in https-requests, and whose values are the URIs used to accomplish the </del>  corresponding function.  Clients access the directory by sending a GET request to the directory URI.

Reviewer comments:
The current wording ("root URL") may lead readers to believe that the ACME directory URI's path is "/", whereas it could actually be anything. Reword to "only URL" and provide examples which emphasize that the choice of the URL for the dictionary object is arbitrary.

Revised text:
In order to help clients configure themselves with the right URIs for each ACME operation, ACME servers provide a directory object.  This  <ins> should be the only URL needed to configure clients.  It is a JSON dictionary, whose keys are the "resource" values listed in https- requests, and whose values are the URIs used to accomplish the </ins> corresponding function. <ins> There is no constraint on the actual URI of the directory except that it should be different from the other ACME server resources' URIs, and that it should not clash with other services.  For instance: a host which function as both an ACME and Web server may want to keep the root path "/" for an HTML "front page", and and place the ACME directory under path "/acme". a host which only functions as an ACME server could place the directory under path "/". </ins> Clients access the directory by sending a GET request to the directory URI.
Original text:
"pending", "processing", "valid", "invalid" and "revoked".  If this field is missing, then the default value is "pending". <del> The date after which the server will consider this authorization invalid, encoded in the format specified in RFC 3339 RFC3339. </del>  The challenges that the client needs to fulfill in order to prove possession of the identifier (for pending authorizations).  For

Reviewer comments:
Also fixes some RFC3339 timestamps shown in examples, which must include seconds.
Authorization expiry should be a timestamp not a date, to allow for authorizations with very short expiry times. All discussion should be done on the mailing list.

Revised text:
"pending", "processing", "valid", "invalid" and "revoked".  If this field is missing, then the default value is "pending".  <ins> The timestamp after which the server will consider this authorization invalid, encoded in the format specified in RFC 3339 RFC3339. </ins> The challenges that the client needs to fulfill in order to prove possession of the identifier (for pending authorizations).  For
Original text:
validation query to a server of the attacker's choosing.  There are a few different mitigations that ACME servers can apply: <del> Checking the DNSSEC status of DNS records used in ACME validation (for zones that are DNSSEC-enabled) </del>  Querying the DNS from multiple vantage points to address local attackers the namespace used for the TLS-based challenge (the "acme.invalid" namespace for "tls-sni-01").  11.  References 11.1.  URIs

Reviewer comments:
I approve of this change.
This looks good to me. I would like to tighten up the language a bit to clarify that this applies to validation of DNS identifiers, but will do that in a follow-on PR.

Revised text:
validation query to a server of the attacker's choosing.  There are a few different mitigations that ACME servers can apply:  <ins> Always querying the DNS using a DNSSEC-validating resolver (enhancing security for zones that are DNSSEC-enabled) </ins> Querying the DNS from multiple vantage points to address local attackers the namespace used for the TLS-based challenge (the "acme.invalid" namespace for "tls-sni-01"). <ins> 10.2. An ACME-based CA needs to make DNS lookups when processing challenges.  Because the security of an ACME-based CA ultimately depends entirely on the authenticity of DNS data, every possible precaution should be taken to secure such lookups.  It is therefore RECOMMENDED that ACME-based CAs make all DNS resolutions via DNSSEC- validating stub or recursive resolvers.  This provides additional protection to domains which choose to make use of DNSSEC. An ACME-based CA must use only a resolver if it trusts the resolver and every component of the network route by which it is accessed.  It is therefore RECOMMENDED that ACME-based CAs operate their own DNSSEC-validating resolvers within their trusted network and use these resolvers both for all CAA record lookups and all record lookups in furtherance of a challenge scheme (A, AAAA, TXT, etc.). </ins> 11.  References 11.1.  URIs
Original text:
half. The client MUST ensure that the certificate is served to TLS <del> connections specifying a Server Name Indication (SNI) value of SAN B. </del>  The response to the TLS-SNI challenge simply acknowledges that the client is ready to fulfill this challenge. Compute SAN A and SAN B in the same way as the client. Open a TLS connection to the domain name being validated on the <del> requested port, presenting SAN B in the SNI field. </del>  The server MUST request the certificate using an SNI value of SAN <del> B. </del>  <del> The server SHOULD ensure that it does not reveal SAN A in any way </del>  when making the TLS connection, such that the presentation of SAN <del> A in the returned certificate proves association with the client. </del>  Verify that the certificate contains a subjectAltName extension containing dNSName entries of SAN A and SAN B and no other

Reviewer comments:
This replaces tls-sni-01 with tls-sni-02, which requires that domains being validated return a certificate which contains a hostname that is not revealed by the server in its handshake. This ensures that challenges cannot be passed by domains which auto-generate self-signed certificates in response to requests with SANs for domains not previously seen.

Revised text:
half. The client MUST ensure that the certificate is served to TLS  <ins> connections specifying a Server Name Indication (SNI) value of SAN A. </ins> The response to the TLS-SNI challenge simply acknowledges that the client is ready to fulfill this challenge. Compute SAN A and SAN B in the same way as the client. Open a TLS connection to the domain name being validated on the  <ins> requested port, presenting SAN A in the SNI field. </ins> The server MUST request the certificate using an SNI value of SAN  <ins> A. </ins>  <ins> The server SHOULD ensure that it does not reveal SAN B in any way </ins> when making the TLS connection, such that the presentation of SAN  <ins> B in the returned certificate proves association with the client. </ins> Verify that the certificate contains a subjectAltName extension containing dNSName entries of SAN A and SAN B and no other
Original text:
There are certain factors that arise in operational reality that operators of ACME-based CAs will need to keep in mind when <del> configuring their services. </del>  [[ TODO: Other operational considerations ]]

Reviewer comments:
I've noticed that boulder uses DNS over TCP. I suppose this has not been an arbitrary choice, but something that would be useful to document.
As an FYI, Boulder currently uses TCP for DNS to its local authoritative resolver, but the resolver uses UDP. We tried making the resolver do upstream resolution with TCP but got a large number of failures.

Revised text:
There are certain factors that arise in operational reality that operators of ACME-based CAs will need to keep in mind when  <ins> configuring their services.  For example: It is advisable to perform DNS queries via TCP to mitigate DNS forgery attacks over UDP </ins> [[ TODO: Other operational considerations ]]
Original text:
When the server responds with an error status, it SHOULD provide additional information using problem document I-D.ietf-appsawg-http- <del> problem.  The "type" and "detail" fields MUST be populated.  To facilitate automatic response to errors, this document defines the following standard tokens for use in the "type" field (within the "urn:ietf:params:acme:error:" namespace): </del>  This list is not exhaustive.  The server MAY return errors whose "type" field is set to a URI other than those defined above.  Servers

Reviewer comments:
These fields are not required by draft-ietf-appsawg-http-problem-03.

Revised text:
When the server responds with an error status, it SHOULD provide additional information using problem document I-D.ietf-appsawg-http-  <ins> problem.  To facilitate automatic response to errors, this document defines the following standard tokens for use in the "type" field (within the "urn:ietf:params:acme:error:" namespace): </ins> This list is not exhaustive.  The server MAY return errors whose "type" field is set to a URI other than those defined above.  Servers
Original text:
ACME uses different URIs for different management functions.  Each function is listed in a directory along with its corresponding URI, <del> so clients only need to be configured with the directory URI. </del>  The "up" link relation is used with challenge resources to indicate the authorization resource to which a challenge belongs.  It is also

Reviewer comments:
Since the rest of the spec and protocol makes extensive use of JSON, when I was reading the spec the first time, I didn't know if the link relations were supposed to be JSON link relations like HAL or LinkedData. The spec mentions "link relation" 6 times, but only one of them (the 2nd-to-last) makes explicit reference to RFC 5988 for web linking via HTTP header.

Revised text:
ACME uses different URIs for different management functions.  Each function is listed in a directory along with its corresponding URI,  <ins> so clients only need to be configured with the directory URI.  These URIs are connected by a few different link relations RFC5988. </ins> The "up" link relation is used with challenge resources to indicate the authorization resource to which a challenge belongs.  It is also
Original text:
by replacing the old account key with the public key carried in the "jwk" header parameter of the "newKey" JWS object.  6.5. Once a client has created an account with an ACME server, it is

Reviewer comments:
I'm not sure if this is the correct place for issues with the actual server, but https://acme-URL is returning me an error message of When accessed from several machines.
No, this isn't the right place. Contact LetsEncrypt directly. This is for discussing the IETF protocol.
https://ietf-wg-URL does not detail what status code should be returned. I assume it should be a 202, in line with Registration update, but it needs specifying IMO.

Revised text:
by replacing the old account key with the public key carried in the "jwk" header parameter of the "newKey" JWS object. <ins> If the update was successful, then the server sends a response with status code 200 (OK) and the updated registration object as its body. If the update was not successful, then the server responds with an error status code and a problem document describing the error. </ins> 6.5. Once a client has created an account with an ACME server, it is
Original text:
Registrar. This is done with an HTTPS POST using the operation path value of <del> "/requestvoucher". </del>  The request media types are: requirement that holds for any REST interface). This is done with an HTTP POST using the operation path value of <del> "/requestvoucher". </del>  The request media type is: in the log. This is done with an HTTP GET using the operation path value of <del> "/requestauditlog". </del>  The Registrar MUST HTTP POSTs the same Registrar voucher-request as it did when requesting a Voucher.  It is posted to the request with the original, and by now already validated, Registrar voucher-request so as to avoid an extra crypto validation.  The request media type is: The request is a "YANG-defined JSON document that has been signed

Reviewer comments:
Proposes 201/Location: operation optional for /requestauditlog end-point.
Think we should discuss.

Revised text:
Registrar. This is done with an HTTPS POST using the operation path value of  <ins> "/.well-known/est/requestvoucher". </ins> The request media types are: requirement that holds for any REST interface). This is done with an HTTP POST using the operation path value of  <ins> "/.well-known/est/requestvoucher". </ins> The request media type is: in the log. This is done with an HTTP GET using the operation path value of  <ins> "/.well-known/est/requestauditlog". </ins> The Registrar MUST HTTP POSTs the same Registrar voucher-request as it did when requesting a Voucher.  It is posted to the request with the original, and by now already validated, Registrar voucher-request so as to avoid an extra crypto validation. <ins> Rather than returning the audit log as a response to the POST (with a return code 200), the MASA MAY instead return a 201 ("Created") RESTful response (RFC7231 section 7.1) containing a URL to the prepared (and easily cachable) audit response. MASA servers that return URLs SHOULD take care to make the returned URL unguessable.  URLs containing a database number such as https://example.com/auditlog/1234 or the EUI of the device such https://example.com/auditlog/10-00-00-11-22-33, would be easily enumerable by an attacker.  It is recommended put to put some meaningless randomly generated slug that indexes a database instead. A MASA that returns a code 200 MAY also include a Location: header for future reference by the Registrar. </ins> The request media type is: The request is a "YANG-defined JSON document that has been signed
Original text:
The primary method of Registrar "authentication" by the MASA is detailed in RequestVoucherFromMASA.  As detailed in securityconsiderations the MASA might find it necessary to request <del> additional Registrar authentication.  Registrars MUST be prepared to support TLS client certificate authentication and HTTP Basic or Digest authentication as described in RFC7030 for EST clients. </del>  Implementors are advised that contacting the MASA is to establish a secured REST connection with a web service and that there are a number of authentication models being explored within the industry. administrative notifications or logs in the advent of unexpected HTTP 401 (Unauthorized) responses from the MASA.  5.4. When a Registrar receives a Pledge voucher-request it in turn submits

Reviewer comments:
Adds text to include SNI in BRSKI-MASA handshake.
I like the first diff (expanding the client authentication discussion into a paragraph). I don't see the need for RFC6066 SNI reference. But since it is a "SHOULD" don't have a technical complaint.

Revised text:
The primary method of Registrar "authentication" by the MASA is detailed in RequestVoucherFromMASA.  As detailed in securityconsiderations the MASA might find it necessary to request  <ins> additional Registrar authentication. The Registrar is the client in the BRSKI-MASA connection.  When operating as such, the Registrars MUST be prepared to support TLS client certificate authentication.  The registrar should also be configurable to support HTTP Basic or Digest authentication as described in RFC7030 for EST clients: provision of such credentials of outside the scope of this document and would be part of a supply- chain integration process. </ins> Implementors are advised that contacting the MASA is to establish a secured REST connection with a web service and that there are a number of authentication models being explored within the industry. administrative notifications or logs in the advent of unexpected HTTP 401 (Unauthorized) responses from the MASA. <ins> In order to support multi-tenant MASA implementations the Registrar SHOULD include the RFC6066 Server Name Indicator. </ins> 5.4. When a Registrar receives a Pledge voucher-request it in turn submits