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

Commentary: Instead of just when not using DNSSEC since you do n't know if a domain is secured by DNSSEC until the query is finished . Also rename the section ' DNS Security ' since it also talks about DNSSEC . Also combines the ' DNS Security ' and ' Use of DNSSEC resolvers sections .
Paragraph (version A):
As noted above, DNS forgery attacks against the ACME server can
result in the server making incorrect decisions about domain control
and thus mis-issuing certificates.  Servers SHOULD verify DNSSEC when
it is available for a domain.  When DNSSEC is not available, servers
SHOULD perform DNS queries over TCP, which provides better resistance
to some forgery attacks than DNS over UDP.
Paragraph (version B):
As noted above, DNS forgery attacks against the ACME server can
result in the server making incorrect decisions about domain control
and thus mis-issuing certificates.  Servers SHOULD perform DNS
queries over TCP, which provides better resistance to some forgery
attacks than DNS over UDP.
Draft: draft-ietf-acme-acme

Commentary: Also switches the type of the challenge type to be instead of as  does n't have dictionaries . I 'll push a follow - up PR that will switch the rest of the - .
Paragraph (version A):
Errors can be reported in ACME both at the HTTP layer and within ACME
payloads.  ACME servers can return responses with an HTTP error
response code (4XX or 5XX).  For example: If the client submits a
request using a method not allowed in this document, then the server
MAY return status code 405 (Method Not Allowed).
Paragraph (version B):
Errors can be reported in ACME both at the HTTP layer and within
challenge objects as defined in identifier-validation-challenges.
ACME servers can return responses with an HTTP error response code
(4XX or 5XX).  For example: If the client submits a request using a
method not allowed in this document, then the server MAY return
status code 405 (Method Not Allowed).
Paragraph (version A):
Authorization and challenge objects can also contain error
information to indicate why the server was unable to validate
authorization.
Draft: draft-ietf-acme-acme

Commentary: Public key pinning is n't implemented in most HTTPS libraries outside of browsers , so this is a considerable burden on implementers . Public key pinning carries a fairly high risk of footgunning . The consequence of a failed pin for a CA that serves many ACME clients would be that some of those clients would fail to renew their certs , causing cascading breakage . There is relatively little confidential information conveyed in ACME , and there are other defenses built into ACME ( like including the account key as part of the challenge data ) , so HPKP is not strongly necessary .
Paragraph (version A):
Each ACME function is accomplished by the client sending a sequence
of HTTPS requests to the server, carrying JSON messages RFC7159.  Use
of HTTPS is REQUIRED.  Clients SHOULD support HTTP public key pinning
RFC7469, and servers SHOULD emit pinning headers.  Each subsection of
certificate-management below describes the message formats used by
the function and the order in which messages are sent.
Paragraph (version B):
Each ACME function is accomplished by the client sending a sequence
of HTTPS requests to the server, carrying JSON messages RFC7159.  Use
of HTTPS is REQUIRED.  Each subsection of certificate-management
below describes the message formats used by the function and the
order in which messages are sent.
Draft: draft-ietf-acme-acme

Commentary: In accordance with
Paragraph (version A):
A client creates a new account with the server by sending a POST
request to the server's new-account URI.  The body of the request is
a stub account object containing only the "contact" field.
Paragraph (version B):
A client creates a new account with the server by sending a POST
request to the server's new-account URI.  The body of the request is
a stub account object containing only the "contact" and optionally
the "terms-of-service-agreed" field.
Draft: draft-ietf-acme-acme

Commentary: Per HTTP RFC : See prior discussion at
Paragraph (version B):
The server SHOULD follow redirects when dereferencing the URI.
Draft: draft-ietf-acme-acme

Commentary: This PR fixes a typo reported by in the " Fields in Order Objects " section . Previously it referred to the listed fields as relating to the " new - account request " . This PR changes the text to make it clear they relate to a " new - order request " . Resolves 
 Merging based on manual review ; CircleCI seems to be busted at the moment . 
 The section on the " " registry says that " Fields marked as " client configurable " may be included in a new - account request " . This seems like a copy - paste - o , and perhaps should say that such fields may be included in a new - order request . 
 Good catch . I opened to fix . Thanks !
Paragraph (version A):
This registry lists field names that are defined for use in ACME
order objects.  Fields marked as "client configurable" may be
included in a new-account request.
Paragraph (version B):
This registry lists field names that are defined for use in ACME
order objects.  Fields marked as "client configurable" may be
included in a new-order request.
Draft: draft-ietf-acme-acme

Commentary: Removed unnecessary paragraphs from authorizations field description in order object . 
 Thanks not sure how I missed that in :)
Paragraph (version A):
The status of the authorization.  This field MUST have the same
value as it does in the underlying authorization object.
Paragraph (version A):
A URL from which the authorization can be fetched with a GET
request.
Draft: draft-ietf-acme-acme

Commentary: The new - nonce endpoint in defines a new endpoint which returns information just in headers , but with a 200 response code . I feel this would be more appropriate as a 204 No Content response code . I 'm not sure what the approach to making this sort of change is . Should I create this change as a PR ? 
 A PR and a small note to the mailing list is probably the best approach . I 'm not an HTTP status lawyer but it seems like 204 is the more - appropriate choice in this context and seems to agree with you : I would : +1 : the PR to change to 204 for :-)
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 200 (OK).  The server SHOULD also respond to GET requests
for this resource, returning an empty body (while still providing a
Replay-Nonce header).
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 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).
Draft: draft-ietf-acme-acme

Commentary: Failure to synchronize between and . Also removes a stray word and some whitespace in the vicinity . 
 Also in the registries ( and in the " Order Objects " section ) , is the authorizations property of an order object an array of strings ( URLs ) or an array of dictionaries ( each of which contains status and URL parameters ) ? 
 array of strings , since
Paragraph (version B):
No transformation needed.
Draft: draft-ietf-acme-acme

Commentary: Implements from the mailing list .
Paragraph (version A):
The elements of the "authorizations" array are immutable once set.
If any change is made to the array after the object is created, the
client MUST consider the order invalid.
Paragraph (version B):
The elements of the "authorizations" array are immutable once set.
The server MUST NOT change the contents of the "authorizations" array
after it is created.  If a client observes a change in the contents
of the "authorizations" array, then it SHOULD consider the order
invalid.
Draft: draft-ietf-acme-acme

Commentary: In some cases , it might be important for a client to know that a server has or has not processed an extension field . For example , if we had an extension that requested some higher level of assurance , then a client would want to know that the CA was going to provide that level of assurance . This PR specifies some rudimentary feature detection to support this objective .
Paragraph (version B):
In general, the server MUST ignore any fields in the request object
that it does not recognize.  In particular, it MUST NOT reflect
unrecognized fields in the resulting account object.  This allows
clients to detect when servers do not support an extension field.
Draft: draft-ietf-acme-acme

Commentary: Also : Forbid the use of MAC - based JWS algorithms ( in case this was n't obvious ) Sort error codes alphabetically 
 The server needs to support whatever the client sends . We should have an error code for this , and a way for the server to specify what algorithms it does support in the error message .
Paragraph (version B):
If the client sends a JWS signed with an algorithm that the server
does not support, then the server MUST return an error with status
code 400 (Bad Request) and type
"urn:ietf:params:acme:error:badSignatureAlgorithm".  The problem
document returned with the error MUST include an "algorithms" field
with an array of supported "alg" values.
Draft: draft-ietf-acme-acme

Commentary: Per mailing list discussion 2016 - 11 - 25 .
Paragraph (version A):
When a server rejects a request because its nonce value was
unacceptable (or not present), it SHOULD provide HTTP status code 400
(Bad Request), and indicate the ACME error code
"urn:ietf:params:acme:error:badNonce".  An error response with the
"badNonce" error code MUST include a Replay-Nonce header with a fresh
nonce.  On receiving such a response, a client SHOULD retry the
request using the new nonce.
Paragraph (version B):
When a server rejects a request because its nonce value was
unacceptable (or not present), it MUST provide HTTP status code 400
(Bad Request), and indicate the ACME error code
"urn:ietf:params:acme:error:badNonce".  An error response with the
"badNonce" error code MUST include a Replay-Nonce header with a fresh
nonce.  On receiving such a response, a client SHOULD retry the
request using the new nonce.
Draft: draft-ietf-acme-acme

Commentary: This is a variant of that uses a MAC key to perform the account binding instead of a bearer token . Thanks to for pointing out the need for this on the ACME mailing list . 
 Question : will you require a CA that does n't use external account bindings to reject a request if it contains an external - account - binding member ? nit : s / field / member / g , consistent with RFC 7159 . 
 StartCom plan to use ACME protocol for StartEncrypt , we need to identify the client 's validation level , so the subscriber administration can generate a special token in the account that send this token to the email address used in the registration . At the registration , user need to enter email and this token with the certificate to let the CA system know this customer 's validation level . After the CA system receive the email , the token and signing certificate , CA system know what type of certificate we can issue to this client ; if this client account is class 4 validated , then the client can get EV SSL certificate , not DV SSL . please add this a parameter to the ACME protocol , thanks . 
 This request should be sent to the ACME mailing list ( ) for further discussion , it would also be very useful to know what your EV ( or OV ) validation flow would look like using ACME as most likely the current certificate application object would need to be changed to identify those requirements to the server . 
 This was fixed by 
 Minor editorial comments .
Paragraph (version B):
The server MAY require a value to be present for the "external-
account-binding" field.  This can be used to an ACME account with an
existing account in a non-ACME system, such as a CA customer
database.
Paragraph (version B):
To enable ACME account binding, a CA needs to provision the ACME
client with a MAC key and a key identifier.  The key identifier MUST
be an ASCII string.  The MAC key SHOULD be provided in base64url-
encoded form, to maximize compatibility between provisioning systems
and ACME clients.
Paragraph (version B):
The "signature" field of the JWS will contain the MAC value computed
with the MAC key provided by the CA.
Paragraph (version B):
If all of these checks pass and the CA creates a new account, then
the CA may consider the new account associated with the external
account corresponding to the MAC key, and MUST reflect value of the
"external-account-binding" field in the resulting account object.  If
any of these checks fail, then the CA MUST reject the new-
registration request.
Draft: draft-ietf-acme-acme

Commentary: As discussed at IETF 97 , this PR creates specification - required registries of fields in ACME objects , so that they can be extended in an orderly fashion . Currently only applies to account and order objects , not authorizations . Not for any ideological reason -- I would be happy to add that for symmetry if people think there might be a need ..
Paragraph (version B):
This registry lists field names that are defined for use in ACME
account objects.  Fields marked as "client configurable" may be
included in a new-account request.
Paragraph (version B):
Initial contents: The fields and descriptions defined in account-
objects.
Paragraph (version B):
This registry lists field names that are defined for use in ACME
order objects.  Fields marked as "client configurable" may be
included in a new-account request.
Paragraph (version B):
Initial contents: The fields and descriptions defined in order-
objects.
Draft: draft-ietf-acme-acme

Commentary: As far as I am aware there has been no explicit use case for this and Boulder explicitly disallows URIs to be used . should be the only explicitly supported URI type in the spec and others should be left up to implementing CAs to document . 
 Conversation on - list went more in the direction of specifying that providing any contact with an unrecognized URI scheme should result in a hard error of . Renaming appropriately .
Paragraph (version B):
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.
Draft: draft-ietf-acme-acme

Commentary: Pull request was recently merged to clarify that HTTP and TLS challenge requests must use port 80 and 443 respectively . The " TLS with Server Name Indication ( TLS SNI ) " section was updated to read : This is a typo ( " port 443 the domain name " ) and also still includes the phrase " on the requested port " , which is no longer true . This PR updates the SNI challenge description to fix the typo and to explicitly say that the server MUST use port 443 in the same style / manner as the HTTP edit from . 
 Thanks for fixing my lame typos
Paragraph (version A):
Open a TLS connection to TCP port 443 the domain name being
validated on the requested port, presenting SAN A in the SNI
field.  In the ClientHello initiating the TLS handshake, the
server MUST include a server_name extension (i.e., SNI) containing
SAN A.  The server SHOULD ensure that it does not reveal SAN B in
any way when making the TLS connection, such that the presentation
of SAN B in the returned certificate proves association with the
client.
Paragraph (version B):
Open a TLS connection to the domain name being validated,
presenting SAN A in the SNI field.  This connection MUST be sent
to TCP port 443 on the server.  In the ClientHello initiating the
TLS handshake, the server MUST include a server_name extension
(i.e., SNI) containing SAN A.  The server SHOULD ensure that it
does not reveal SAN B in any way when making the TLS connection,
such that the presentation of SAN B in the returned certificate
proves association with the client.
Draft: draft-ietf-acme-acme

Commentary: This is no longer true after PR
Paragraph (version A):
The client's response to this challenge indicates its agreement to
this challenge by sending the server the key authorization covering
the challenge's token and the client's account key.  In addition, the
client MAY advise the server at which IP the challenge is
provisioned.
Paragraph (version B):
The client's response to this challenge indicates its agreement to
this challenge by sending the server the key authorization covering
the challenge's token and the client's account key.
Draft: draft-ietf-acme-acme

Commentary: I spotted a typo / error introduced by this PR and submitted a follow - up : 
 Since we did not get consensus around , we should be explicit that HTTP is TCP port 80 , and HTTPS is TCP port 443 , and that holds for redirects as well . The is pretty much a minor wording change only .
Paragraph (version A):
Dereference the URI using an HTTP GET request.
Paragraph (version B):
Dereference the URI using an HTTP GET request.  This request MUST
be sent to TCP port 80 on the server.
Paragraph (version A):
Open a TLS connection to the domain name being validated on the
requested port, presenting SAN A in the SNI field.  In the
ClientHello initiating the TLS handshake, the server MUST include
a server_name extension (i.e., SNI) containing SAN A.  The server
SHOULD ensure that it does not reveal SAN B in any way when making
the TLS connection, such that the presentation of SAN B in the
returned certificate proves association with the client.
Paragraph (version B):
Open a TLS connection to TCP port 443 the domain name being
validated on the requested port, presenting SAN A in the SNI
field.  In the ClientHello initiating the TLS handshake, the
server MUST include a server_name extension (i.e., SNI) containing
SAN A.  The server SHOULD ensure that it does not reveal SAN B in
any way when making the TLS connection, such that the presentation
of SAN B in the returned certificate proves association with the
client.
Draft: draft-ietf-acme-acme

Commentary: This was part of ( see removal of oldKey from example payload ) , but I missed these two other spots . oldKey is fully specified by the account URL in the payload .
Paragraph (version A):
Check that the "oldKey" field of the key-change object contains
the current account key.
Draft: draft-ietf-acme-acme

Commentary: and provide a reference to the relevant RFC .
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 integrity for the HTTPS request
URI.
Paragraph (version B):
Communications between an ACME client and an ACME server are done
over HTTPS, using JSON Web Signature (JWS) RFC7515 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.
Draft: draft-ietf-acme-acme

Commentary: One of the most common ACME deployment failures observed in practice is for servers to be configured to serve only the end - entity certificate , without the intermediate certificates . This is a particularly pernicious problem because some browsers will still trust the resulting one - certificate chain , due to caching or fetching of URLs from Authority Information Access . But other browsers will not , resulting in a " works on my computer " problem . Arguably this configuration is the result of incorrect clients , but we should expect that most clients will do the easiest thing . This change aligns the easiest thing with the most correct thing . 
 You should include advice here on omitting trust anchors . TLS 1.3 has you could crib from ( see the definition of ) . 
 Hi , the PEM text is not correct : application / x - pem - file is not a registered media type , among other things . Will post to mailing list with details .
Paragraph (version A):
The default format of the certificate is DER (application/pkix-cert).
The client may request other formats by including an Accept header in
its request.  For example, the client may use the media type
application/x-pem-file to request the certificate in PEM format.
Paragraph (version A):
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.
Paragraph (version B):
The default format of the certificate is PEM (application/x-pem-file)
as specified by RFC7468.  This format should contain the end-entity
certificate first, followed by any intermediate certificates that are
needed to build a path to a trusted root.  Servers SHOULD NOT include
self-signed trust anchors.  The client may request other formats by
including an Accept header in its request.  For example, the client
may use the media type application/pkix-cert to request the end-
entity certificate in DER format.
Paragraph (version B):
The server MAY provide one or more link relation header fields
RFC5988 with relation "alternate".  Each such field should express an
alternative certificate chain starting with the same end-entity
certificate.  This can be used to express paths to various trust
anchors.  Clients can fetch these alternates and use their own
heuristics to decide which is optimal.
Draft: draft-ietf-acme-acme

Commentary: Previously , each authenticated POST included a copy of its public key in the JWS protected header . Servers were required to canonicalize this key in some way and look it up in a database , then verify the payload . However , servers also had the option of verifying the payload , and then looking up the key in the database . This opened up a category of potential bugs based on truncated database fields or hash collisions , where an attacker could craft a key pair the would potentially be matched to someone else 's account . Incidental benefits : Switching to kid makes payloads somewhat smaller , and removes the need to define key equality in the ACME spec . 
 Updated based on feedback . 
 Updated . Rather than have a switch / case about how to authenticate revoke - cert , I split it into two resources , authenticated different ways : one by account , one by cert key .
Paragraph (version A):
Note that this implies that GET requests are not authenticated.
Servers MUST NOT respond to GET requests for resources that might be
considered sensitive.
Paragraph (version B):
"kid" (for all other requests).
Paragraph (version B):
The "jwk" and "kid" fields are mutually exclusive.  Servers MUST
reject requests that contain both.
Paragraph (version B):
For new-reg requests, and for revoke-cert requests authenticated by
certificate key, there MUST be a "jwk" field.
Paragraph (version B):
For all other requests, there MUST be a "kid" field.  This field must
contain the account URI received by POSTing to the new-reg resource.
Paragraph (version B):
Note that authentication via signed POST implies that GET requests
are not authenticated.  Servers MUST NOT respond to GET requests for
resources that might be considered sensitive.