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

Commentary: Prior to this commit the literal string " . " was being rendered as the start of italics in the generated HTML doc . This commit updates the markup to escape the " * . " ` in the generated document . Originally reported by   - thanks !
Paragraph (version A):
Any identifier of type "dns" in a new-order request MAY have a
wildcard domain name as its value.  A wildcard domain name consists
of a single asterisk character followed by a single full stop
character ("_.") followed by a domain name as defined for use in the
Subject Alternate Name Extension by RFC 5280 . An authorization
returned by the server for a wildcard domain name identifier MUST NOT
include the asterisk and full stop ("_RFC5280.") prefix in the
authorization identifier value.
Paragraph (version B):
Any identifier of type "dns" in a new-order request MAY have a
wildcard domain name as its value.  A wildcard domain name consists
of a single asterisk character followed by a single full stop
character ("*.") followed by a domain name as defined for use in the
Subject Alternate Name Extension by RFC 5280 RFC5280.  An
authorization returned by the server for a wildcard domain name
identifier MUST NOT include the asterisk and full stop ("*.") prefix
in the authorization identifier value.
Draft: draft-ietf-acme-acme

Commentary: Make clear contact field is optional as well . Is n't it correct ? 
 Thanks !
Paragraph (version A):
A client creates a new account with the server by sending a POST
request to the server's new-account URL.  The body of the request is
a stub account object containing the "contact" field and optionally
the "termsOfServiceAgreed" field.
Paragraph (version B):
A client creates a new account with the server by sending a POST
request to the server's new-account URL.  The body of the request is
a stub account object optionally containing the "contact" and
"termsOfServiceAgreed" fields.
Draft: draft-ietf-acme-acme

Commentary: Rewrite " in challenge " , which seems to be incorrect to " of the order " 
 Good catch ! Thank you : eagle : : mag :
Paragraph (version A):
The "authorizations" array in the challenge SHOULD reflect all
authorizations that the CA takes into account in deciding to issue,
even if some authorizations were fulfilled in earlier orders or in
pre-authorization transactions.  For example, if a CA allows multiple
orders to be fulfilled based on a single authorization transaction,
then it SHOULD reflect that authorization in all of the orders.
Paragraph (version B):
The "authorizations" array of the order SHOULD reflect all
authorizations that the CA takes into account in deciding to issue,
even if some authorizations were fulfilled in earlier orders or in
pre-authorization transactions.  For example, if a CA allows multiple
orders to be fulfilled based on a single authorization transaction,
then it SHOULD reflect that authorization in all of the orders.
Draft: draft-ietf-acme-acme

Commentary: As of discussion in 
 Thanks ! : golf :
Paragraph (version A):
To get a fresh nonce, the client sends a HEAD request to the new-
nonce resource on the server.  The server's response MUST include a
Replay-Nonce header field containing a fresh nonce, and SHOULD have
status code 204 (No Content).  The server SHOULD also respond to GET
requests for this resource, returning an empty body (while still
providing a Replay-Nonce header) with a 204 (No Content) status.
Paragraph (version B):
To get a fresh nonce, the client sends a HEAD request to the new-
nonce resource on the server.  The server's response MUST include a
Replay-Nonce header field containing a fresh nonce, and SHOULD have
status code 200 (OK).  The server SHOULD also respond to GET requests
for this resource, returning an empty body (while still providing a
Replay-Nonce header) with a 204 (No Content) status.
Draft: draft-ietf-acme-acme

Commentary: I think without OOB all challenges use key - authorization " JWA " is not defined in this document . I think it can just be omitted 
 Thank you for the change ! : smile : 
 Thanks again I really appreciate your editing & the accompanying PRs ! :-)
Paragraph (version A):
The "JWK_Thumbprint" step indicates the computation specified in
RFC7638, using the SHA-256 digest FIPS180-4.  As noted in JWA RFC7518
any prepended zero octets in the fields of a JWK object MUST be
stripped before doing the computation.
Paragraph (version B):
The "JWK_Thumbprint" step indicates the computation specified in
RFC7638, using the SHA-256 digest FIPS180-4.  As noted in RFC7518 any
prepended zero octets in the fields of a JWK object MUST be stripped
before doing the computation.
Draft: draft-ietf-acme-acme

Commentary: Also , add some more " replace RFC XXXX with this document " notes , for clarity . Thanks to for noticing that this was missing . 
 Merging based on r+ from 
 The new registry looks good : +1 : - no changes to request there . The existing directory registry ( ) should probably have a " meta " entry :
Paragraph (version B):
This registry lists field names that are defined for use in the JSON
object included in the "meta" field of an ACME directory object.
Paragraph (version B):
Initial contents: The fields and descriptions defined in account-
objects.
Draft: draft-ietf-acme-acme

Commentary: Previously there was some notion of being able to hint to the server whether you wanted to reuse authorizations . This was removed from the spec but the pre - authorization flow still made a reference to it . This commit removes that obsolete reference . Thanks to for pointing out the error . Resolves 
 Hi in the section on pre - authz there is this sentence : To request authorization for an identifier , the client sends a POST request to the new - authorization resource specifying the identifier for which authorization is being requested and how the server should behave with respect to existing authorizations for this identifier . the part " and how the server should behave with respect to existing authorizations for this identifier " probably is obsoleted 
 Hi I submitted to fix this . Thanks for spotting & reporting :-)
Paragraph (version A):
To request authorization for an identifier, the client sends a POST
request to the new-authorization resource specifying the identifier
for which authorization is being requested and how the server should
behave with respect to existing authorizations for this identifier.
Paragraph (version B):
To request authorization for an identifier, the client sends a POST
request to the new-authorization resource specifying the identifier
for which authorization is being requested.
Draft: draft-ietf-acme-acme

Commentary: The OOB challenge was to accommodate non - ACME CAs building ACME integrations . Since then two non - ACME CAs have implemented ACME integrations using the external account binding feature but not implementing OOB challenges . Since the target demographic has not implemented this feature and has also not presented a use - case requiring it there seems to be no strong reasons to keep it in - spec . 
 If you could update this to remove the OOB challenge from the , I 'll go ahead and merge 
 Good catch - thanks ! Addressed in .
Paragraph (version A):
There may be cases where a server cannot perform automated validation
of an identifier, for example, if validation requires some manual
steps.  In such cases, the server may provide an "out of band" (OOB)
challenge to request that the client perform some action outside of
ACME in order to validate possession of the identifier.
Paragraph (version A):
The OOB challenge requests that the client have a human user visit a
web page to receive instructions on how to validate possession of the
identifier, by providing a URL for that web page.
Paragraph (version A):
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.
Paragraph (version A):
A client responds to this challenge by presenting the indicated URL
for a human user to navigate to.  If the user chooses to complete
this challenge (by visiting the website and completing its
instructions), the client indicates this by sending a simple
acknowledgement response to the server.  The payload of this response
is an empty JSON object ("{}", or "e30" base64url-encoded).
Paragraph (version A):
On receiving a response, the server MUST verify that the value of the
"type" field is "oob-01".  Otherwise, the steps the server takes to
validate identifier possession are determined by the server's local
policy.
Paragraph (version A):
CAs using ACME to allow clients to agree to terms of service should
keep in mind that ACME clients can automate this agreement, possibly
not involving a human user.  If a CA wishes to have stronger evidence
of user consent, it may present an out-of-band requirement or
challenge to require human involvement.
Paragraph (version B):
CAs using ACME to allow clients to agree to terms of service should
keep in mind that ACME clients can automate this agreement, possibly
not involving a human user.
Draft: draft-ietf-acme-acme

Commentary: While addressing  's Gen - ART comments , it occurred to me that while the document said that a CA could require external account binding , it did n't say how . This PR adds a " meta " field and an error code to support that requirements proactively and reactively . 
 Merging based on review 
 : ship :
Paragraph (version B):
If this field is present and set to "true", then the CA requires
that all new-account requests include an "external-account-
binding" field associating the new account with an external
account.
Paragraph (version B):
If a CA requires that new-account requests contain an "external-
account-binding" field, then it MUST provide the value "true" in the
"external-account-required" subfield of the "meta" field in the
directory object.  If the CA receives a new-account request without
an "external-account-binding" field, then it should reply with an
error of type "externalAccountRequired".
Draft: draft-ietf-acme-acme

Commentary: It is no longer necessary with the order based issuance flow that allows the server to specify which authorizations a client must satisfy to allow issuance of an order . See
Mailing list commentary: Section 7.1.4 " Authorization Objects " describes an optional " scope " field . If present it must be a URI pointing to an order and the authorization is considered to be valid only for that order . If no scope value is present it is assumed that the authorization is valid for any order . Looking back at the PR that introduced the " scope " field[0 ] and knowing the current state of order based issuance I ' m not clear why this field is needed , or what a client could do with the scope information . Can someone clarify or should this part of the spec be removed ? The server determines as a matter of policy which authorizations are required for an order and includes these in the order 's array . If part of that server policy is to treat some valid authorizations as only being valid for a specific order then the server can simply not include those valid authorizations in the order 's authorizations array and can instead create new pending authorizations for the client to solve . The client does n't need to understand authorization scope it just needs to know which authorizations the server says are required and how to move these authorizations to a valid state . Since the client ca n't ask for specific authorizations to be used with specific orders and must react to what the server provides why is it helpful to tell a client that one of the authorizations it solved wo n't be used with future orders ? Similarly I think the scope field interacts weirdly with pre - authorization . Are all authorization objects created with pre - authorization assumed to be global scope since they are n't associated with an order ? Have any ACME clients or servers implemented order scope ? Let 's Encrypt / Boulder / Pebble have not . Daniel / cpu [ 0 ] -
Paragraph (version A):
If this field is present, then it MUST contain a URL for an order
resource, such that this authorization is only valid for that
resource.  If this field is absent, then the CA MUST consider this
authorization valid for all orders until the authorization
expires.
Paragraph (version A):
This process may be repeated to associate multiple identifiers to a
key pair (e.g., to request certificates with multiple identifiers),
or to associate multiple accounts with an identifier (e.g., to allow
multiple entities to manage certificates).  The server may declare
that an authorization is only valid for a specific order by setting
the "scope" field of the authorization to the URL for that order.
Paragraph (version B):
This process may be repeated to associate multiple identifiers to a
key pair (e.g., to request certificates with multiple identifiers),
or to associate multiple accounts with an identifier (e.g., to allow
multiple entities to manage certificates).
Draft: draft-ietf-acme-acme

Commentary: Still pending some mailing list discussion .
Paragraph (version B):
ACME can also be used to automate some aspects of certificate
management even where non-automated processes are still needed.  For
example, the external account binding feature (see external-account-
binding) can be used to associate authorizations with an account that
were not validated through the ACME authorization process.  This
allows ACME to address issuance scenarios that cannot yet be fully
automated, such as the issuance of Extended Validation certificates.
Paragraph (version A):
ACME servers SHOULD follow the recommendations of RFC7525 when
configuring their TLS implementations.  ACME servers that support TLS
because the ACME protocol itself includes anti-replay protections.
Paragraph (version B):
ACME servers SHOULD follow the recommendations of RFC7525 when
configuring their TLS implementations.  ACME servers that support TLS
because the ACME protocol itself includes anti-replay protections
(see replay-protection).
Draft: draft-ietf-acme-acme

Commentary: This does n't address the other piece of feedback , that mailto URLs can contain multiple entries . 
 If you do n't allow , then it 's only possible to have one address . 
 Oh , no , that 's totally wrong , will update .
Paragraph (version A):
The server SHOULD validate that the contact URLs in the "contact"
field are valid and supported by the server.  If the server validates
contact URLs it MUST support the "mailto" scheme.  If the server
rejects a contact URL for using an unsupported scheme it MUST return
an error of type "unsupportedContact", with a description describing
the error and what types of contact URLs the server considers
acceptable.  If the server rejects a contact URL for using a
supported scheme but an invalid value then the server MUST return an
error of type "invalidContact".
Paragraph (version B):
The server SHOULD validate that the contact URLs in the "contact"
field are valid and supported by the server.  If the server validates
contact URLs it MUST support the "mailto" scheme.  Clients MUST NOT
provide a "mailto" URL in the "contact" field that contains "hfields"
RFC6068, or more than one "addr-spec" in the "to" component.  If a
server encounters a "mailto" contact URL that does not meet these
criteria, then it SHOULD reject it as invalid.
Paragraph (version B):
If the server rejects a contact URL for using an unsupported scheme
it MUST return an error of type "unsupportedContact", with a
description describing the error and what types of contact URLs the
server considers acceptable.  If the server rejects a contact URL 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: The URL pathname should start with a slash .
Paragraph (version A):
The path at which the resource is provisioned is comprised of the
fixed prefix ".well-known/acme-challenge/", followed by the "token"
value in the challenge.  The value of the resource MUST be the ASCII
representation of the key authorization.
Paragraph (version B):
The path at which the resource is provisioned is comprised of the
fixed prefix "/.well-known/acme-challenge/", followed by the "token"
value in the challenge.  The value of the resource MUST be the ASCII
representation of the key authorization.
Draft: draft-ietf-acme-acme

Commentary: Fixed some spelling mistakes and grammatical errors in the draft .
Paragraph (version A):
In addition to the human readable "detail" field of the error
response, the server MAY send one or multiple tokens in the "Link"
header pointing to documentation about the specific hit rate limits
using the "urn:ietf:params:acme:documentation" relation.
Paragraph (version B):
In addition to the human-readable "detail" field of the error
response, the server MAY send one or multiple tokens in the "Link"
header pointing to documentation about the specific hit rate limits
using the "urn:ietf:params:acme:documentation" relation.
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 successfully 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.
Paragraph (version A):
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.
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 the 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.
Paragraph (version A):
Has issuance been authorized or forbidden by a Certficate
Authority Authorization (CAA) record?
Paragraph (version B):
Has issuance been authorized or forbidden by a Certificate
Authority Authorization (CAA) record?
Draft: draft-ietf-acme-acme

Commentary: Similar to Section 7.3.1 " Finding an Account URL Given a Key " when a key rollover request will result in a conflict with an existing account the header of the response should indicate the URL of the conflicting account . This saves the client from having to post the new - account endpoint to learn the account URL .
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 (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).
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) and
provide the URL of that account in the Location header field.
Draft: draft-ietf-acme-acme

Commentary: A friendly ping to bring this PR back to life :)
Paragraph (version A):
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.
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 initial authorization
request.
Draft: draft-ietf-acme-acme

Commentary: It is useful in some contexts ( e.g. , ) to have identifiers for non - ACME methods that CAs use to validate control of an identifier . This PR updates the ACME Challenge Types registry to instead address Validation Methods more generally , with a column that indicates whether the method is an ACME method . 
 Okay , I see your point . Fine .
Paragraph (version A):
This registry lists the ways that ACME servers can offer to validate
control of an identifier.  The "Identifier Type" field in the
template must be contained in the Label column of the ACME Identifier
Types registry.
Paragraph (version B):
This registry lists identifiers for the ways that CAs can validate
control of identifiers.  Each method's entry must specify whether it
corresponds to an ACME challenge type.  The "Identifier Type" field
must be contained in the Label column of the ACME Identifier Types
registry.
Paragraph (version B):
ACME: "Y" if the validation method corresponds to an ACME
challenge type; "N" otherwise.
Paragraph (version B):
When evaluating a request for an assignment in this registry, the
designated expert should ensure that the method being registered has
a clear, interoperable definition and does not overlap with existing
validation methods.  That is, it should not be possible for a client
and server to follow take the same set of actions to fulfill two
different validation mechanisms.
Paragraph (version B):
Validation methods do not have to be compatible with ACME in order to
be registered.  For example, a CA might wish to register a validation
method in order to support its use with the ACME extensions to CAA I-
D.ietf-acme-caa.