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

Commentary: As pointed out to the list : There is this sentence in the security considerations ( 10.2 Integrity of Authorizations ) that strikes me as extremely misleading : " All of the challenges above have a binding between the account private key and the validation query made by the server , via the key authorization . The key authorization is signed by the account private key , reflects the corresponding public key , and is provided to the server in the validation response . " The key authorization itself does NOT contain the signature of the account 's key . It gets though signed by the account 's key later on in the challenge response ( not the validation response ) over the ACME channel ( not the validation channel ) . What about saying that in the chronological order of events ?
Paragraph (version A):
All of the challenges above have a binding between the account
private key and the validation query made by the server, via the key
authorization.  The key authorization is signed by the account
private key, reflects the corresponding public key, and is provided
to the server in the validation response.
Paragraph (version B):
All of the challenges above have a binding between the account
private key and the validation query made by the server, via the key
authorization.  The key authorization reflects the account public
key, is provided to the server in the validation response over the
validation channel and signed afterwards by the corresponding private
key in the challenge response over the ACME channel.
Draft: draft-ietf-acme-acme

Commentary: As requested by on the mailing list . 
 Merging based on from and
Paragraph (version B):
Note that changing the account key for an account SHOULD NOT have any
other impact on the account.  For example, the server MUST NOT
invalidate pending orders or authorization transactions based on a
change of account key.
Paragraph (version A):
Verify that key authorization provided by the HTTP server matches
the token for this challenge and the client's account key.
Paragraph (version B):
Verify that key authorization provided by the HTTP server matches
the key authorization provided by the client in its response to
the challenge.
Draft: draft-ietf-acme-acme

Commentary: It makes sense to cancel any pending cert orders when an account is deactivated , where the cert has not been issued yet .
Paragraph (version A):
Once an account is deactivated, the server MUST NOT accept further
requests authorized by that account's key.  A server may take a
variety of actions in response to an account deactivation, e.g.,
deleting data related to that account or sending mail to the
account's contacts.  Servers SHOULD NOT revoke certificates issued by
the deactivated account, since this could cause operational
disruption for servers using these certificates.  ACME does not
provide a way to reactivate a deactivated account.
Paragraph (version B):
Once an account is deactivated, the server MUST NOT accept further
requests authorized by that account's key.  The server SHOULD cancel
any pending operations authorized by the account's key, such as
certificate orders.  A server may take a variety of actions in
response to an account deactivation, e.g., deleting data related to
that account or sending mail to the account's contacts.  Servers
SHOULD NOT revoke certificates issued by the deactivated account,
since this could cause operational disruption for servers using these
certificates.  ACME does not provide a way to reactivate a
deactivated account.
Draft: draft-ietf-acme-acme

Commentary: 2 unrelated editorial changes
Paragraph (version A):
For pending authorizations, the challenges that the client can
fulfill in order to prove possession of the identifier.  For final
authorizations, the challenges that were used.  Each array entry
is an object with parameters required to validate the challenge.
A client should attempt to fulfill one of these challenges, and a
server should consider any one of the challenges sufficient to
make the authorization valid.  For final authorizations it
contains the challenges that were completed.
Paragraph (version B):
For pending authorizations, the challenges that the client can
fulfill in order to prove possession of the identifier.  For final
authorizations, the challenges that were used.  Each array entry
is an object with parameters required to validate the challenge.
A client should attempt to fulfill one of these challenges, and a
server should consider any one of the challenges sufficient to
make the authorization valid.  For final authorizations it
contains the challenges that were successfully completed.
Draft: draft-ietf-acme-acme

Commentary: The verification step is missing from the informal list of steps .
Paragraph (version B):
The CA verifies that the client controls the requested domain
name(s).
Draft: draft-ietf-acme-acme

Commentary: Is 200 really correct ? This seems like a 404 maybe ? Also we should specify the body ( empty ) . 
 Would a problem document be appropriate ( with either a pre - existing ACME error type or a new one like " accountDoesNotExist " ) ? 
 404 talks about the effective request URI , so that 's not going to work . I think that a 400 would be better on the basis that the request checked , but failed ( suggestion is a fine enhancement ) . The reason you make this request is to check ; and having a 4xx series code is easier to test than the absence of a header field . 
 Thanks and implemented this in the latest commit . 
 As discussed ; this is fine .
Paragraph (version A):
If a client wishes to find the URL for an existing account and does
not want an account to be created if one does not already exist, then
it SHOULD do so by sending a POST request to the new-account URL with
a JWS whose payload has an "only-return-existing" field set to "true"
({"only-return-existing": true}).
Paragraph (version B):
If a client wishes to find the URL for an existing account and does
not want an account to be created if one does not already exist, then
it SHOULD do so by sending a POST request to the new-account URL with
a JWS whose payload has an "only-return-existing" field set to "true"
({"only-return-existing": true}).  If a client sends such a request
and an account does not exist, then the server MUST return an error
response with status code 400 (Bad Request) and type
"urn:ietf:params:acme:error:accountDoesNotExist".
Draft: draft-ietf-acme-acme

Commentary: Not a substantive change IMO .
Paragraph (version A):
If all of these checks pass, then the server updates the
corresponding account by replacing the old account key with the new
public key and returns status code 200.  Otherwise, the server
responds with an error status code and a problem document describing
the error.
Paragraph (version B):
Check that no account exists whose account key is the same as the
key in the "newKey" field.
Paragraph (version B):
If all of these checks pass, then the server updates the
corresponding account by replacing the old account key with the new
public key and returns status code 200 (OK).  Otherwise, the server
responds with an error status code and a problem document describing
the error.  If there is an existing account with the new key
provided, then the server SHOULD use status code 409 (Conflict).
Draft: draft-ietf-acme-acme

Commentary: No substantive change , just caveats .
Paragraph (version A):
File should contain one or more certificates encoded as PEM according
to RFC 7468.  In order to provide easy interoperation with TLS, the
first certificate MUST be an end-entity certificate.  Each following
certificate SHOULD directly certify one preceding it.  Because
certificate validation requires that trust anchors be distributed
independently, a certificate that specifies a trust anchor MAY be
omitted from the chain, provided that supported peers are known to
possess any omitted certificates.
Paragraph (version B):
File should contain one or more certificates encoded as PEM according
to RFC 7468 RFC7468.  In order to provide easy interoperation with
TLS, the first certificate MUST be an end-entity certificate.  Each
following certificate SHOULD directly certify one preceding it.
Because certificate validation requires that trust anchors be
distributed independently, a certificate that specifies a trust
anchor MAY be omitted from the chain, provided that supported peers
are known to possess any omitted certificates.
Paragraph (version B):
ACME provides certificate chains in the widely-used format known
colloquially as PEM (though it may diverge from the actual Privacy
Enhanced Mail specifications RFC1421, as noted in RFC7468).  Some
current software will allow the configuration of a private key and a
certificate in one PEM file, by concatenating the textual encodings
of the two objects.  In the context of ACME, such software might be
vulnerable to "key replacement" attacks.  A malicious ACME server
could cause a client to use a private key of its choosing by
including the key in the PEM file returned in response to a query for
a certificate URL.
Paragraph (version B):
When processing an file of type "application/pem-certificate-chain",
a client SHOULD verify that the file contains only encoded
certificates.  If anything other than a certificate is found (i.e.,
if the string "---BEGIN" is ever followed by anything other than
"CERTIFICATE"), then the client MUST reject the file as invalid.
Draft: draft-ietf-acme-acme

Commentary: In the JSON , could be called a " field name " or a " key . " We use both in this document , but we should consolidate one one . I think " field name " is better ( and agrees ) . In part this avoids any ambiguity with cryptographic keys .
Paragraph (version A):
In order to help clients configure themselves with the right URLs for
each ACME operation, ACME servers provide a directory object.  This
should be the only URL needed to configure clients.  It is a JSON
object, whose keys are drawn from the following table and whose
values are the corresponding URLs.
Paragraph (version B):
In order to help clients configure themselves with the right URLs for
each ACME operation, ACME servers provide a directory object.  This
should be the only URL needed to configure clients.  It is a JSON
object, whose fields names are drawn from the following table and
whose values are the corresponding URLs.
Paragraph (version A):
The object MAY additionally contain a key "meta".  If present, it
MUST be a JSON object; each field in the object is an item of
metadata relating to the service provided by the ACME server.
Paragraph (version B):
The object MAY additionally contain a field "meta".  If present, it
MUST be a JSON object; each field in the object is an item of
metadata relating to the service provided by the ACME server.
Paragraph (version A):
If a CA wishes to allow pre-authorization within ACME, it can offer a
"new authorization" resource in its directory by adding the key "new-
authz" with a URL for the new authorization resource.
Paragraph (version B):
If a CA wishes to allow pre-authorization within ACME, it can offer a
"new authorization" resource in its directory by adding the field
"new-authz" with a URL for the new authorization resource.
Draft: draft-ietf-acme-acme

Commentary: As discussed on the list and at IETF 98 .
Paragraph (version A):
The server SHOULD also consider a revocation request valid if it is
signed with the private key corresponding to the public key in the
certificate.
Paragraph (version B):
The server MUST also consider a revocation request valid if it is
signed with the private key corresponding to the public key in the
certificate.
Draft: draft-ietf-acme-acme

Commentary: Currently says This registry lists the types of identifiers that ACME clients may request authorization to issue in certificates . But ACME clients no longer directly request authorization ; instead this section lists identifiers that the servers may create authorizations for based on new - order .
Paragraph (version A):
This registry lists the types of identifiers in certificates that
ACME clients may request authorization to issue.
Paragraph (version B):
This registry lists the types of identifiers that can be present in
ACME authorization objects.
Draft: draft-ietf-acme-acme

Commentary: A refinement on Servers reflect their state in and Clients can request a retry by re - ing
Paragraph (version A):
The error that occurred while the server was validating the
challenge, if any.  This field is structured as a problem document
RFC7807.
Paragraph (version B):
Errors that occurred while the server was validating the
challenge, if any, structured as problem documents RFC7807.  The
server MUST NOT modify the array except by appending entries onto
the end.  The server can limit the size of this object by limiting
the number of times it will retry a challenge.
Paragraph (version B):
ACME challenges typically require the client to set up some network-
accessible resource that the server can query in order to validate
that the client controls an identifier.  In practice it is not
uncommon for the server's queries to fail while a resource is being
set up, e.g., due to information propagating across a cluster or
firewall rules not being in place.
Paragraph (version B):
Clients SHOULD NOT respond to challenges until they believe that the
server's queries will succeed.  If a server's initial validation
query fails, the server SHOULD retry the query after some time.
While the server is still trying, the status of the challenge remains
"pending"; it is only marked "invalid" once the server has given up.
Paragraph (version B):
The server MUST provide information about its retry state to the
client via the "errors" field in the challenge and the Retry-After
HTTP header field in response to requests to the challenge resource.
The server MUST add an entry to the "errors" field in the challenge
after each failed validation query.  The server SHOULD set the Retry-
After header field to a time after the server's next validation
query, since the status of the challenge will not change until that
time.
Paragraph (version B):
Clients can explicitly request a retry by re-sending their response
to a challenge in a new POST request (with a new nonce, etc.).  This
allows clients to request a retry when state has changed (e.g., after
firewall rules have been updated).  Servers SHOULD retry a request
immediately on receiving such a POST request.  In order to avoid
denial-of-service attacks via client-initiated retries, servers
SHOULD rate-limit such requests.
Draft: draft-ietf-acme-acme

Commentary: Depends on 
 This allows us to address the account URL recovery use case in without having special handling for empty payloads .
Paragraph (version B):
If this field is present with the value "true", then the server
MUST NOT create a new account if one does not already exist.  This
allows a client to look up an account URL based on an account key
(see finding-an-account-url-given-a-key).
Paragraph (version A):
If a client wishes to recover an existing account and does not want a
non existing account to be created, then it SHOULD do so by sending a
POST request with an empty update.  That is, it should send a JWS
whose payload is an empty object ({}).
Paragraph (version B):
If a client wishes to find the URL for an existing account and does
not want an account to be created if one does not already exist, then
it SHOULD do so by sending a POST request to the new-account URL with
a JWS whose payload has an "only-return-existing" field set to "true"
({"only-return-existing": true}).
Draft: draft-ietf-acme-acme

Commentary: Proposed replacement for
Paragraph (version B):
Has issuance been authorized or forbidden by a Certficate
Authority Authorization (CAA) record?
Draft: draft-ietf-acme-acme

Commentary: Firstly , this PR updates the table of errors in Section 6.6 " Errors " to add an " unsupportedContact " error type in addition to " invalidContact " . The former is returned when the contact URI protocol is unsupported and the latter when the protocol is supported but the provided contact is invalid . Secondly , this PR updates Section 7.3 " Account Creation " to both mention the new " unsupportedContact " error type and to make support of the " mailto : " protocol a MUST . 
 Thanks for the feedback - updated . 
 Should the " unsupportedContact " error include a separate machine - readable field with the types of contacts acceptable ? 
 Let 's discuss that in a follow - on issue / PR .
Paragraph (version A):
The server SHOULD validate that the contact URLs in the "contact"
field are valid and supported by the server.  If the client provides
the server with an invalid or unsupported contact URL, then the
server MUST return an error of type "invalidContact", with a
description describing the error and what types of contact URL the
server considers acceptable.
Paragraph (version B):
The server SHOULD validate that the contact URIs in the "contact"
field are valid and supported by the server.  If the server validates
contact URIs it MUST support the "mailto" scheme.  If the server
rejects a contact URI for using an unsupported scheme it MUST return
an error of type "unsupportedContact", with a description describing
the error and what types of contact URIs the server considers
acceptable.  If the server rejects a contact URI for using a
supported scheme but an invalid value then the server MUST return an
error of type "invalidContact".
Draft: draft-ietf-acme-acme

Commentary: And clarify " high probability . " 
 While we 're clarifying , I might add an encrypted counter another option that is guaranteed unique . 
 I do n't think we need to get into that level of prescribing implementation detail ; once you mention it at all it immediately sounds half - specified . As a reader , I would want to know " what algorithm ? shared across how many frontends ? how does key management and rotation work ? " Better to just say it should be unique ( with high probability ) and leave it to the implementer .
Paragraph (version A):
The "Replay-Nonce" header field includes a server-generated value
that the server can use to detect unauthorized replay in future
client requests.  The server should generate the value provided in
Replay-Nonce in such a way that they are unique to each message, with
high probability.
Paragraph (version B):
The "Replay-Nonce" header field includes a server-generated value
that the server can use to detect unauthorized replay in future
client requests.  The server MUST generate the value provided in
Replay-Nonce in such a way that they are unique to each message, with
high probability.  For instance, it is acceptable to generate Replay-
Nonces randomly.
Draft: draft-ietf-acme-acme

Commentary: Various minor clarifications and fixes
Paragraph (version A):
The two main roles in ACME are "client" and "server".  The ACME
client uses the protocol to request certificate management actions,
such as issuance or revocation.  An ACME client therefore typically
runs on a web server, mail server, or some other server system which
requires valid TLS certificates.  The ACME server runs at a
certification authority, and responds to client requests, performing
the requested actions if the client is authorized.
Paragraph (version B):
The two main roles in ACME are "client" and "server".  The ACME
client uses the protocol to request certificate management actions,
such as issuance or revocation.  An ACME client may run on a web
server, mail server, or some other server system which requires valid
TLS certificates.  Or, it may run on a separate server that does not
consume the certificate, but is authorized to respond to a CA-
provided challenge.  The ACME server runs at a certification
authority, and responds to client requests, performing the requested
actions if the client is authorized.
Paragraph (version A):
This list is not exhaustive.  The server MAY return errors whose
"type" field is set to a URI other than those defined above.  Servers
MUST NOT use the ACME URN namespace for errors other than the
standard types.  Clients SHOULD display the "detail" field of all
errors.
Paragraph (version B):
This list is not exhaustive.  The server MAY return errors whose
"type" field is set to a URI other than those defined above.  Servers
MUST NOT use the ACME URN RFC3553 namespace for errors other than the
standard types.  Clients SHOULD display the "detail" field of all
errors.
Paragraph (version A):
The certificate may be constructed arbitrarily, except that each
certificate MUST have exactly two subjectAlternativeNames, SAN A and
SAN B.  Both MUST be dNSNames.
Paragraph (version B):
The certificate may be constructed arbitrarily, except that each
certificate MUST have exactly two subjectAlternativeNames, SAN A and
SAN B.  Both MUST be dNSNames RFC5280.
Paragraph (version A):
It is RECOMMENDED that the server opens multiple TLS connections from
various network perspectives, in order to make MitM attacks harder.
Draft: draft-ietf-acme-acme

Commentary: This change replaces " shortly " in the normative language of Section 7.4 , Applying for Certificate Issuance , with the more precise expectation that the server begin the issuance process , as discussed on the mailing list .
Mailing list commentary: We could say " MUST begin the issuance process " The main things on my mind that could delay issuance slightly : Submitting to CT Checking CAA Internal queuing for available capacity  vetting I think " MUST begin " covers for all of those , while allowing some vagueness as to how long they will take .
Paragraph (version A):
The server MUST issue the requested certificate and update the order
resource with a URL for the certificate shortly after the client has
fulfilled the server's requirements.  If the client has already
satisfied the server's requirements at the time of this request
(e.g., by obtaining authorization for all of the identifiers in the
certificate in previous transactions), then the server MUST
proactively issue the requested certificate and provide a URL for it
in the "certificate" field of the order.  The server MUST, however,
still list the completed authorizations in the "authorizations"
array.
Paragraph (version B):
The server MUST begin the issuance process for the requested
certificate and update the order resource with a URL for the
certificate once the client has fulfilled the server's requirements.
If the client has already satisfied the server's requirements at the
time of this request (e.g., by obtaining authorization for all of the
identifiers in the certificate in previous transactions), then the
server MUST proactively issue the requested certificate and provide a
URL for it in the "certificate" field of the order.  The server MUST,
however, still list the completed authorizations in the
"authorizations" array.
Draft: draft-ietf-acme-acme

Commentary: Per feedback from Zach Shepherd[0 ] on the mailing list the justification for the 128 bits of required token entropy from section 8.2 is at odds with the actual rationale ( as I understand it ) . This commit updates the justification for the entropy requirement to not mention being secret from an attacker , but instead not predictable by a naive challenge response server that would complete challenges without having been a party to the authz / chal creation . 
 It seems like whatever change is made should be applied to sections 8.2 , 8.3 , and 8.4 . 
 Based on zjs ' feedback , I think it makes more sense for the individual token fields to just say " MUST have 128 bits " , and explain why in one place in the Security Considerations section . 
 Updated . Thanks for the feedback !
Paragraph (version B):
The http-01, tls-sni-02 and dns-01 validation methods mandate the
usage of a random token value to uniquely identify the challenge.
The value of the token is required to contain at least 128 bits of
entropy for the following security properties.  First, the ACME
client should not be able to influence the ACME server's choice of
token as this may allow an attacker to reuse a domain owner's
previous challenge responses for a new validation request.  Secondly,
the entropy requirement prevents ACME clients from implementing a
"naive" validation server that automatically replies to challenges
without participating in the creation of the intial authorization
request.