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

Commentary: Signing with the current account key allows servers to use the same message transport authentication that they use for other requests , simplifying the verification . Also fix two spots where we still described newKey / oldKey as thumbprints . 
 LGTM . I had only done that signing order to be forward - compatible with some imagined future recovery scheme , but if we decide to do that someday , that patch can differ in signature order as well as whatever else .
Paragraph (version A):
The client then encapsulates the key-change object in a JWS, signed
with the client's current account key (i.e., the key matching the
"oldKey" value).
Paragraph (version A):
This inner JWS then become the payload of the JWS that the client
sends to the server.  The outer JWS is signed with the key pair that
the the client wishes to have the server use as its account key
(i.e., the key pair matching the "newKey" value).  The client sends
this outer JWS in a POST request to the server's "key-change"
resource.
Paragraph (version B):
The client then encapsulates the key-change object in a JWS, signed
with the requested new account key (i.e., the key matching the
"newKey" value).
Paragraph (version B):
Validate the POST request belongs to a currently active account,
as described in Message Transport.
Paragraph (version B):
Check that the JWS protected header of the inner JWS has a "jwk"
field.
Paragraph (version B):
Check that the "oldKey" field of the key-change object contains
the current account key.
Paragraph (version B):
Check that the "newKey" field of the key-change object contains
the key used to sign the inner JWS.
Draft: draft-ietf-acme-acme

Commentary: With the combinations array now removed , this is no longer accurate . 
 If you could re - wrap that paragraph to get rid of the short line , LGTM . 
 I tend not to re - wrap Markdown on edits because it makes diffs & blames more meaningful . Do you feel strongly about the wrapping ?
Paragraph (version A):
Presumably, the client's responses provide the server with enough
information to validate one or more challenges.  The server is said
to "finalize" the authorization when it has completed all the
validations it is going to complete, and assigns the authorization a
status of "valid" or "invalid", corresponding to whether it considers
the account authorized for the identifier.  If the final state is
"valid", the server MUST add an "expires" field to the authorization.
When finalizing an authorization, the server MAY remove challenges
other than the one that was completed.  The server SHOULD NOT remove
challenges with status "invalid".
Paragraph (version B):
The server is said to "finalize" the authorization when it has
completed one of the validations, by assigning the authorization a
status of "valid" or "invalid", corresponding to whether it considers
the account authorized for the identifier.  If the final state is
"valid", the server MUST add an "expires" field to the authorization.
When finalizing an authorization, the server MAY remove challenges
other than the one that was completed.  The server SHOULD NOT remove
challenges with status "invalid".
Draft: draft-ietf-acme-acme

Commentary: We are n't using thumbprints for key - change anymore , so this paragraph does n't make sense .
Paragraph (version A):
Both of these thumbprints MUST be computed as specified in RFC7638,
using the SHA-256 digest.  The values in the "oldKey" and "newKey"
fields MUST be the base64url encodings of the thumbprints.
Draft: draft-ietf-acme-acme

Commentary: Remove unknown status from applications and authorizations and processing status from applications 
 LGTM
Paragraph (version A):
The status of this authorization.  Possible values are: "unknown",
"pending", "processing", "valid", and "invalid".
Paragraph (version B):
The status of this application.  Possible values are: "pending",
"valid", and "invalid".
Paragraph (version A):
The status of this authorization.  Possible values are: "unknown",
"pending", "processing", "valid", "invalid" and "revoked".  If
this field is missing, then the default value is "pending".
Paragraph (version B):
The status of this authorization.  Possible values are: "pending",
"processing", "valid", "invalid" and "revoked".  If this field is
missing, then the default value is "pending".
Draft: draft-ietf-acme-acme

Commentary: To avoid confusion with the field , which has the URL for the challenge itself .
Paragraph (version A):
The URI to which a response can be posted.
Paragraph (version B):
The URL to which a response can be posted.
Paragraph (version B):
The URL to be visited.  The scheme of this URL MUST be "http" or
"https".  Note that this field is distinct from the "url" field of
the challenge, which identifies the challenge itself.
Draft: draft-ietf-acme-acme

Commentary: requires IDNs be encoded in this way in order to be stored in the X509 certificate dNSNames field . Compliance with this RFC is one of the requirements of the CABForum which CAs are expected to adhere to . We already require domain names transmitted via ACME to use the ASCII encoding , this just formalizes how IDNs should be converted .
Paragraph (version A):
The only type of identifier defined by this specification is a fully-
qualified domain name (type: "dns").  The value of the identifier
MUST be the ASCII representation of the domain name.  Wildcard domain
names (with "*" as the first label) MUST NOT be included in
authorization requests.
Paragraph (version B):
The only type of identifier defined by this specification is a fully-
qualified domain name (type: "dns").  The value of the identifier
MUST be the ASCII representation of the domain name.  If a domain
name contains Unicode characters it MUST be encoded using the rules
defined in RFC3492.  Servers MUST verify any identifier values that
begin with the ASCII Compatible Encoding prefix "xn-" as defined in
RFC5890 are properly encoded.  Wildcard domain names (with "*" as the
first label) MUST NOT be included in authorization requests.
Draft: draft-ietf-acme-acme

Commentary: what 's the difference between " deactivated " and " revoked " ? 
 Deactivated is done by the user ; revoked is done by an administrator . 
 OK , so we need to either say that or use clearer terms :) I talked with offline , and I think he 's going to propose something .
Paragraph (version B):
The status of this registration.  Possible values are: "valid",
"deactivated", and "revoked". "deactivated" should be used to
indicate user initiated deactivation whereas "revoked" should be
used to indicate administratively initiated deactivation.
Draft: draft-ietf-acme-acme

Commentary: Right now , it 's not clear when the client needs to agree to the server 's terms , and what the server should do if it needs the client to re - agree . This PR addresses both with a dedicated error code and some related behaviors .
Paragraph (version A):
If the server wishes to present the client with terms under which the
ACME service is to be used, it MUST indicate the URI where such terms
can be accessed in the "terms-of-service" subfield of the "meta"
field in the directory object, and the server SHOULD reject new-
registration requests that do not contain "terms-of-service-agreed":
true.
Paragraph (version B):
If the server wishes to present the client with terms under which the
ACME service is to be used, it MUST indicate the URI where such terms
can be accessed in the "terms-of-service" subfield of the "meta"
field in the directory object, and the server MUST reject new-
registration requests that do not have the "terms-of-service-agreed"
set to "true".
Paragraph (version B):
As described above, a client can indicate its agreement with the CA's
terms of service by setting the "terms-of-service-agreed" field in
its registration object to "true".
Paragraph (version B):
If the server has changed its terms of service since a client
initially agreed, and the server is unwilling to process a request
without explicit agreement to the new terms, then it MUST return an
error response with status code 403 (Forbidden) and type
"urn:ietf:params:acme:error:agreementRequired".  This response MUST
include a Link header with link relation "terms-of-service" and the
latest terms-of-service URL.
Paragraph (version B):
The problem document returned with the error MUST also include an
"instance" field, indicating a URL that the client should direct a
human user to visit in order for instructions on how to agree to the
terms.
Draft: draft-ietf-acme-acme

Commentary: Prior to this PR the specification seems to be contradictory , indicating that the " new - X " resources must not be duplicated , but that they can live at different URIs . It 's not clear to me what this MUST is trying to prevent , especially in light of an allowance of multiple URIs if functionality is equivalent . Similarly , while the text prior to this PR says " new - X " I believe the intentions of the statements that follow would include some of the resources that have been since , e.g. " key - change " . This PR updates the " new - X " language to include the additional singular resources and removes the MUST . If I 've missed the mark in this clarification perhaps someone who was involved with the spec at the time of this paragraph 's writing can help guide us to something both clear & accurate to the original spirit .
Paragraph (version A):
For the "new-X" resources above, the server MUST have exactly one
resource for each function.  This resource may be addressed by
multiple URIs, but all must provide equivalent functionality.
Paragraph (version B):
For the singular resources above ("directory", "new-registration",
"new-application", "revoke-certificate", and "key-change") the
resource may be addressed by multiple URIs, but all must provide
equivalent functionality.
Draft: draft-ietf-acme-acme

Commentary: The registration object already contains a list of certificate applications , and each application contains a link to the resulting certificate if one was issued . This reduces the number of primitives that an ACME server has to support .
Paragraph (version A):
A URI from which a list of certificates issued for this account
can be fetched via a GET request.  The result of the GET request
MUST be a JSON object whose "certificates" field is an array of
strings, where each string is the URI of a certificate.  The
server SHOULD NOT include expired or revoked certificates.  The
server MAY return an incomplete list, along with a Link header
with link relation "next" indicating a URL to retrieve further
entries.
Draft: draft-ietf-acme-acme

Commentary: This channel no longer exists since the removal of the recovery challenge .
Paragraph (version A):
In practice, the risks to these channels are not entirely separate,
but they are different in most cases.  Each of the three channels,
for example, uses a different communications pattern: the ACME
channel will comprise inbound HTTPS connections to the ACME server,
the validation channel outbound HTTP or DNS requests, and the contact
channel will use channels such as email and PSTN.
Paragraph (version B):
In practice, the risks to these channels are not entirely separate,
but they are different in most cases.  Each channel, for example,
uses a different communications pattern: the ACME channel will
comprise inbound HTTPS connections to the ACME server and the
validation channel outbound HTTP or DNS requests.
Paragraph (version A):
On the ACME channel, in addition to network-layer attackers, we also
need to account for application-layer man in the middle attacks, and
for abusive use of the protocol itself.  Protection against
application-layer MitM addresses potential attackers such as Content
Distribution Networks (CDNs) and middleboxes with a TLS MitM
function.  Preventing abusive use of ACME means ensuring that an
attacker with access to the validation or contact channels can't
obtain illegitimate authorization by acting as an ACME client
(legitimately, in terms of the protocol).
Paragraph (version B):
On the ACME channel, in addition to network-layer attackers, we also
need to account for application-layer man in the middle attacks, and
for abusive use of the protocol itself.  Protection against
application-layer MitM addresses potential attackers such as Content
Distribution Networks (CDNs) and middleboxes with a TLS MitM
function.  Preventing abusive use of ACME means ensuring that an
attacker with access to the validation channel can't obtain
illegitimate authorization by acting as an ACME client (legitimately,
in terms of the protocol).
Draft: draft-ietf-acme-acme

Commentary: The contents of the authorization object , not the registration object , should be returned .
Paragraph (version A):
The server MUST verify that the request is signed by the account key
corresponding to the account that owns the authorization.  If the
server accepts the deactivation, it should reply with a 200 (OK)
status code and the current contents of the registration object.
Paragraph (version B):
The server MUST verify that the request is signed by the account key
corresponding to the account that owns the authorization.  If the
server accepts the deactivation, it should reply with a 200 (OK)
status code and the current contents of the authorization object.
Draft: draft-ietf-acme-acme

Commentary: Also clarify that ACME servers are sometimes clients .
Paragraph (version A):
In all HTTPS transactions used by ACME, the ACME client is the HTTPS
client and the ACME server is the HTTPS server.
Paragraph (version B):
In most HTTPS transactions used by ACME, the ACME client is the HTTPS
client and the ACME server is the HTTPS server.  The ACME server acts
as an HTTP and HTTPS client when validating challenges via HTTP.
Paragraph (version B):
ACME clients SHOULD send a User-Agent header in accordance with
RFC7231, including the name and version of the ACME software in
addition to the name and version of the underlying HTTP client
software.
Paragraph (version B):
ACME clients SHOULD send an Accept-Language header in accordance with
RFC7231 to enable localization of error messages.
Draft: draft-ietf-acme-acme

Commentary: As discussed at IETF 96 , ACME server processing of the " url " field should perform an exact string equality test between the URL string provided to the client and the string provided by the client in its " url " parameter . Effectively , this turns " url " values into opaque service labels , which just happen to have the side effect of being able to direct an HTTP request .
Paragraph (version A):
Except for the directory resource, all ACME resources are addressed
with URLs provided to the client by the server.  In such cases, the
client MUST set the "url" field to the exact string provided by the
server (rather than performing any re-encoding on the URL).
Paragraph (version B):
Except for the directory resource, all ACME resources are addressed
with URLs provided to the client by the server.  For these resources,
the client MUST set the "url" field to the exact string provided by
the server (rather than performing any re-encoding on the URL).  The
server SHOULD perform the corresponding string equality check,
configuring each resource with the URL string provided to clients and
having the resource check that requests have the same string in their
"url" fields.
Draft: draft-ietf-acme-acme

Commentary: It seem like the only way to retrieve an existing registration object for a given key is to provoke an error by attempting to register again with the same key and read the Location from it . As a client library implementor , I would expect to and to not be recoverable . I think its strange that the only way to recover the registration object is by triggering an error . Would it make sense to add an extra endpoint to simply retrieve the registration object ? Alternatively , I do n't see any reason for the endpoint not to return when already registered ( instead of when it create the registration ) as opposed to a . Also , the returned error type in boulder is , which does not make much sense to me since the request was not malformed . If its an expected behaviour to provoke an error to recover data from the response , the error type should be specify into the spec and unique so its can be recovered from easily . Implementation in boulder and initial discussion in the ruby .
Paragraph (version A):
If the server already has a registration object with the provided
account key, then it MUST return a 409 (Conflict) response and
provide the URI of that registration in a Location header field.
This allows a client that has an account key but not the
corresponding registration URI to recover the registration URI.
Paragraph (version B):
If the server already has a registration object with the provided
account key, then it MUST return a 200 (OK) response and provide the
URI of that registration in a Content-Location header field.  This
allows a client that has an account key but not the corresponding
registration URI to recover the registration URI.
Draft: draft-ietf-acme-acme

Commentary: Fixing two minor typos in Section 6.2.1 " Account Key Roll - over "
Paragraph (version A):
Check that the JWS protected header container a "jwk" field
containing a key that matches a currently active account.
Paragraph (version B):
Check that the JWS protected header contains a "jwk" field
containing a key that matches a currently active account.
Draft: draft-ietf-acme-acme

Commentary: does this look better ? 
 LGTM , though I 'd change the attacker from a " he " to a " they " on general principles . 
 Not a huge fan of the singular " they " , but ca n't be bothered to rewrite around it :) 
 Yes , this is clearer . Thanks . Saying " will cause the server to query an arbitrary URI " is good . Technically you can even specify a non - HTTP protocol in an HTTP redirect , and this language should cover that too . ( Go 's net / http used by  only does HTTP and HTTPS I think , but things like libcurl support a slightly insane number of protocols . ) I 'm not sure if the usages of " URI " vs " URL " in this section are correct , you may want to make them consistent . I never know which one to actually use . This looks good to me .
Paragraph (version A):
The risk of SSRF through this channel is limited by the fact that the
attacker can only control the domain of the URL, not the path.
Nonetheless, in order to further limit the SSRF risk, ACME server
operators should ensure that validation queries can only be sent to
servers on the public Internet, and not, say, web services within the
server operator's internal network.  Since the attacker could make
requests to these public servers himself, he can't gain anything
extra through an SSRF attack on ACME aside from a layer of
anonymization.
Paragraph (version B):
It might seem that the risk of SSRF through this channel is limited
by the fact that the attacker can only control the domain of the URL,
not the path.  However, if the attacker first sets the domain to one
they control, then they can send the server an HTTP redirect (e.g., a
302 response) which will cause the server to query an arbitrary URI.
Paragraph (version B):
In order to further limit the SSRF risk, ACME server operators should
ensure that validation queries can only be sent to servers on the
public Internet, and not, say, web services within the server
operator's internal network.  Since the attacker could make requests
to these public servers himself, he can't gain anything extra through
an SSRF attack on ACME aside from a layer of anonymization.
Draft: draft-ietf-acme-acme

Commentary: Move some sections around and fix some headings Declare references inline instead of up front  small tweaks
Paragraph (version A):
Generate a PKCS#10 RFC2314 Certificate Signing Request (CSR).
Paragraph (version B):
Generate a PKCS#10 RFC2986 Certificate Signing Request (CSR).
Paragraph (version A):
ACME uses a combination of HTTPS and JWS to create a messaging layer
with a few important security properties.
Paragraph (version A):
Communications between an ACME client and an ACME server are done
over HTTPS, using JWS to provide some additional security properties
for messages sent from the client to the server.  HTTPS provides
server authentication and confidentiality.  With some ACME-specific
extensions, JWS provides authentication of the client's request
payloads, anti-replay protection, and a degree of integrity for the
HTTPS request URI.
Paragraph (version B):
Communications between an ACME client and an ACME server are done
over HTTPS, using JWS to provide some additional security properties
for messages sent from the client to the server.  HTTPS provides
server authentication and confidentiality.  With some ACME-specific
extensions, JWS provides authentication of the client's request
payloads, anti-replay protection, and integrity for the HTTPS request
URI.
Paragraph (version A):
The following diagram illustrates the relations between resources on
an ACME server.  The solid lines indicate link relations, and the
dotted lines correspond to relationships expressed in other ways,
e.g., the Location header in a 201 (Created) response.
Paragraph (version A):
The error that occurred while the server was validating the
challenge, if any.  This field is structured as a problem document
I-D.ietf-appsawg-http-problem.
Paragraph (version B):
The error that occurred while the server was validating the
challenge, if any.  This field is structured as a problem document
RFC7807.
Draft: draft-ietf-acme-acme

Commentary: The current mechanism has a potential copy / paste vulnerability . Karthik proposed on the list : That is , you need the full matrix of " X signs over Y " -- " new / old " , " new / new " , " old / old " , " old / new " -- so that both sides explicitly agree to the ( old , new ) pair . But the current design has only has " old / new " and " new / new " . That raises a risk that if you got an " old / new " signature , you could copy / paste the " new / new " signature and get a valid request . As long as we have parallel signatures ( cf . ) , we need to have both the old and new keys in the payloads .
Paragraph (version A):
To change the key associate with an account, the client POSTs a key-
change object with a "key" field containing a JWK representation of
the new public key.  The JWS of this POST must have two signatures:
one signature from the existing key on the account, and one signature
from the new key that the client proposes to use.  This demonstrates
that the client actually has control of the private key corresponding
to the new public key.  The protected header must contain a JWK field
containing the current account key.
Paragraph (version B):
The JWS of this POST must have two signatures: one signature from the
existing key on the account, and one signature from the new key that
the client proposes to use.  This demonstrates that the client
actually has control of the private key corresponding to the new
public key.  The protected header must contain a JWK field containing
the current account key.
Draft: draft-ietf-acme-acme

Commentary: send MUST -MUST send
Paragraph (version A):
The server provides metadata about the certificate in HTTP headers.
In particular, the server send MUST one or more link relation header
fields RFC5988 with relation "up", each indicating a single
certificate resource for the issuer of this certificate.  The server
MAY also include the "up" links from these resources to enable the
client to build a full certificate chain.
Paragraph (version B):
The server provides metadata about the certificate in HTTP headers.
In particular, the server MUST send one or more link relation header
fields RFC5988 with relation "up", each indicating a single
certificate resource for the issuer of this certificate.  The server
MAY also include the "up" links from these resources to enable the
client to build a full certificate chain.