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

Commentary: Instead of leaving the behavior undefined allow the user to specify a optional parameter for the resource .
Paragraph (version B):
One of the revocation reasonCodes defined in RFC 5280 RFC5280
Section 5.3.1 to be used when generating OCSP responses and CRLs.
If this field is not set the server SHOULD use the unspecified (0)
reasonCode value when generating OCSP responses and CRLs.  The
server MAY disallow a subset of reasonCodes from being used by the
user.
Draft: draft-ietf-acme-acme

Commentary: This uses two JWS signatures to achieve the two - signature property during rollover , instead of using extra layers of encoding and embedding . It also simplifies the logic and splits it out into its own resource .
Paragraph (version A):
The string "reg", indicating an update to the registration.
Paragraph (version A):
The client signs this object with the old key pair and encodes the
object and signature as a JWS.  The client then sends this JWS to the
server in the "rollover" field of a request to update the
registration.
Paragraph (version A):
If all of these checks pass, then the server updates the registration
by replacing the old account key with the public key carried in the
"jwk" header of the request JWS.
Paragraph (version A):
If the update was successful, then the server sends a response with
status code 200 (OK) and the updated registration object as its body.
If the update was not successful, then the server responds with an
error status code and a problem document describing the error.
Paragraph (version B):
A client may wish to change the public key that is associated with a
registration in order to recover from a key compromise or proactively
mitigate the impact of an unnoticed key compromise.
Paragraph (version B):
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):
Check that the JWS protected header container a "jwk" field
containing a key that matches a currently active account.
Paragraph (version B):
Check that there are exactly two signatures on the JWS.
Paragraph (version B):
Check that one of the signatures validates using the account key
from (1).
Paragraph (version B):
Check that the "key" field contains a well-formed JWK that meets
key strength requirements.
Paragraph (version B):
Check that the "key" field is not equivalent to the current
account key or any other currently active account key.
Paragraph (version B):
Check that one of the two signatures on the JWS validates using
the JWK from the "key" field.
Paragraph (version B):
If all of these checks pass, then the server updates the
corresponding registration 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.
Draft: draft-ietf-acme-acme

Commentary: This reverts commit I think we did not reach consensus on the list about this feature . 
 Oh , it 's a shame that this was removed . I was hoping to use this feature to help when my servers were behind a load balancer . We should probably remove this reference as well :
Paragraph (version A):
As a domain may resolve to multiple IPv4 and IPv6 addresses, the
server will connect to at least one of the hosts found in A and AAAA
records.  Because many web servers allocate a default HTTPS virtual
host to a particular low-privilege tenant user in a subtle and non-
intuitive manner, the challenge must be completed over HTTP, not
HTTPS.
Paragraph (version B):
As a domain may resolve to multiple IPv4 and IPv6 addresses, the
server will connect to at least one of the hosts found in A and AAAA
records, at its discretion.  Because many webservers allocate a
default HTTPS virtual host to a particular low-privilege tenant user
in a subtle and non-intuitive manner, the challenge must be completed
over HTTP, not HTTPS.
Paragraph (version A):
An IPv4 or IPv6 address, in dotted decimal form or RFC4291 form,
respectively.  If given, this address MUST be included in the set
of IP addresses to which the domain name resolves when the server
attempts validation.  If given, the server SHOULD connect to that
specific IP address instead of arbitrarily choosing an IP from the
set of A and AAAA records to which the domain name resolves.
Paragraph (version A):
If the client has supplied an address to use, verify that the
address is included in the A or AAAA records to which the domain
name resolves.  If the address is not included in the result, the
validation fails.
Paragraph (version A):
Dereference the URI using an HTTP GET request.  If an address was
supplied by the client, use that address to establish the HTTP
connection.
Paragraph (version B):
Dereference the URI using an HTTP GET request.
Draft: draft-ietf-acme-acme

Commentary: As discussed in the thread about , we can have a fairly clean recovery story ( assuming a MAC key can be provisioned . As a first step , we should reverse the order of the signatures in the roll - over request object .
Paragraph (version A):
The client signs this object with the new key pair and encodes the
object and signature as a JWS.  The client then sends this JWS to the
server in the "newKey" field of a request to update the registration.
Paragraph (version A):
If all of these checks pass, then the server updates the registration
by replacing the old account key with the public key carried in the
"jwk" header parameter of the "newKey" JWS object.
Paragraph (version B):
The client signs this object with the old key pair and encodes the
object and signature as a JWS.  The client then sends this JWS to the
server in the "rollover" field of a request to update the
registration.
Paragraph (version B):
If all of these checks pass, then the server updates the registration
by replacing the old account key with the public key carried in the
"jwk" header of the request JWS.
Draft: draft-ietf-acme-acme

Commentary: We need a challenge type to cover types of validation that ca n't be done automatically , in band to ACME . For example , a CA doing OV or EV validation might need the applicant to upload some documents through a web form . We should add a generic " out - of - band " challenge type that has a URL for a web site where the applicant gan go for instructions . I think the challenge object would look something like : There would be no response object ; you just click the link , and when you complete the instructions there , the CA reflects this in the " status " field of the challenge object . 
 A few months back I wrote up a for this idea -- the hope is that ACME could evolve to become the language that all cert issuers talk to support a standard for cert management and exchange . 
 At IETF 95 , agreed that this seemed reasonable to pursue , but needs to have a PR that describes what the URI characteristics are .
Paragraph (version B):
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 B):
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 B):
A client responds to this challenge by presenting the indicated URL
for a human user to navigate to.  If the user choses to complete this
challege (by vising the website and completing its instructions), the
client indicates this by sending a simple acknowledgement response to
the server.
Paragraph (version B):
On receiving a response, the server MUST verify that the value of the
"type" field is as required.  Otherwise, the steps the server takes
to validate identifier possession are determined by the server's
local policy.
Draft: draft-ietf-acme-acme

Commentary: As discussed at IETF 95 , the server should fail a new - cert request if it can not fulfill it precisely . It must not modify the request to something it is willing to fulfill . 
 We need to clarify when an ACME server can ignore attributes in a request that it does n't like , and when it should ignore them and proceed . For example , if a requested validity date is longer than the policy , should it error back or just ignore that attribute and issue a cert good for as long as it wants ? That seems okay . But what about an unsupported request for issuance in the future ? Ignoring that seems wrong , and risky . 
 I think in general ACME should take the approach of refusing to issue a cert if requested parameters ( dates , or extensions ) are unacceptable . It 's cheap for the client to re - request with acceptable parameters , assuming the error message is detailed enough . 
 Scoping this down to new - certificate requests , since there 's not really enough latitude in the other types of request to cause this problem . 
 Agreed in B.A. to fail , fail , fail , but return information helpful to a human , explicitly not machine - recoverable . It may be possible to give a trivial amount of altitude ( e.g. 90 days -- will it not be okay if 90 - days minus 15 seconds is given ? )
Paragraph (version A):
The values provided in the CSR are only a request, and are not
guaranteed.  The server SHOULD return an error if it cannot fulfil
the request as specified, but MAY issue a certificate with contents
other than those requested, according to its local policy (e.g.,
removing identifiers for which the client is not authorized).
Paragraph (version B):
The server MUST return an error if it cannot fulfil the request as
specified, and MUST NOT issue a certificate with contents other than
those requested.  If the server requires the request to be modified
in a certain way, it should indicate the required changes using an
appropriate error code and description.
Draft: draft-ietf-acme-acme

Commentary: As PHB noted in his presentation at IETF 95 , the examples in the doc should indicate clearly the start and end of payload of the JWS object , e.g. : 
 The spec indicates that it ’s possible to request certificates of types other than DER ; however , there is no indication of what those MIME types are . PEM would be a very useful format ; would it be useful to indicate in here what that MIME type is , or at least where to find a list of MIME types that would work here ? 
 The answer is :) But I can agree that it would be good to remind people of this in the spec . 
 CA certificates are 
 The documentation seems unclear as to how certificate “ up ” links are to handle the case of multiple intermediate certificates between root and the issued certificate . Are both certificates part of the payload of the “ up ” link ? Does each “ up ” link whose payload is not a root certificate ( or “ last - before - root ” ) have its own “ up ” link ? Thank you ! 
 It seems pretty clear to me that the right answer is to have one " up " link per parent cert , but allow multiple links per cert . We can add some text to clarify this .
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.
Paragraph (version A):
The server provides metadata about the certificate in HTTP headers.
In particular, the server MUST include a Link relation header field
RFC5988 with relation "up" to provide a certificate under which this
certificate was issued, and one with relation "author" to indicate
the registration under which this certificate was issued.
Paragraph (version B):
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 B):
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 MUST also provide a link relation header field with
relation "author" to indicate the registration under which this
certificate was issued.
Draft: draft-ietf-acme-acme

Commentary: Typo fix
Paragraph (version A):
Communications between an ACME client and an ACME server are done
over HTTPS, using JWS to provide som 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 a degree of integrity for the
HTTPS request URI.
Draft: draft-ietf-acme-acme

Commentary: ( Re - adding the editorial changes that got lumped in ) 
 r+ ; thanks for pulling these out alone
Paragraph (version A):
A string containing a URI identifying the current terms of
service.
Paragraph (version A):
String containing an HTTP or HTTPS URL locating a website
providing more information about the ACME server.
Paragraph (version A):
If present, MUST be an array of strings.  Each string MUST be a
lowercase hostname which the ACME server recognises as referring
to itself for the purposes of CAA record validation as defined in
RFC6844.  This allows clients to determine the correct issuer
domain name to use when configuring CAA record.
Paragraph (version B):
A URI identifying the current terms of service.
Paragraph (version B):
An HTTP or HTTPS URL locating a website providing more information
about the ACME server.
Paragraph (version B):
Each string MUST be a lowercase hostname which the ACME server
recognises as referring to itself for the purposes of CAA record
validation as defined in RFC6844.  This allows clients to
determine the correct issuer domain name to use when configuring
CAA record.
Draft: draft-ietf-acme-acme

Commentary: Move description of registration and authorization objects to Certificate Management section Re - frame Protocol Elements section to be more clearly about the transport layer Fix some references
Paragraph (version A):
This section describes several components that are used by ACME, and
general rules that apply to ACME transactions.
Paragraph (version A):
Each ACME function is accomplished by the client sending a sequence
of HTTPS requests to the server, carrying JSON messages.  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):
ACME uses a combination of HTTPS and JWS to create a messaging layer
with a few important security properties.
Paragraph (version B):
Communications between an ACME client and an ACME server are done
over HTTPS, using JWS to provide som 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):
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):
It is common in deployment the entity terminating TLS for HTTPS to be
different from the entity operating the logical HTTPS server, with a
"request routing" layer in the middle.  For example, an ACME CA might
have a content delivery network terminate TLS connections from
clients so that it can inspect client requests for denial-of-service
protection.
Paragraph (version B):
These intermediaries can also change values in the request that are
not signed in the HTTPS request, e.g., the request URI and headers.
ACME uses JWS to provides a limited integrity mechanism, which
protects against an intermediary changing the request URI to anothe
ACME URI of a different type.  (It does not protect against changing
between URIs of the same type, e.g., from one authorization URI to
another).
Draft: draft-ietf-acme-acme

Commentary: Rate limits can be used to show warnings to the user , e.g. when certificate issuance is limited to 5 certificates per 7 days and you already issued 3 . A single client ca n't count these , because they may be on different servers using different clients .
Paragraph (version A):
Once the rate limit is exceeded, the server responds with an error
with the code "rateLimited".
Paragraph (version B):
Creation of resources can be rate limited to ensure fair usage and
prevent abuse.  Once the rate limit is exceeded, the server MUST
respond with an error with the code "rateLimited".  Additionally, the
server SHOULD send a "Retry-After" header indicating when the current
request may succeed again.  If multiple rate limits are in place,
that is the time where all rate limits allow access again for the
current request with exactly the same parameters.
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 "rate-limit" relation.
Draft: draft-ietf-acme-acme

Commentary: Adds a little more granularity to section headings . 
 It should be possible for a client to delete his account / registration , and to renounce authorization for a domain . The right way to do this is probably to define a " delete " object that can be POSTed to the reg / account URI , rather than having a separate endpoint ( as for certificate revocation ) .
Paragraph (version B):
If a client no longer wishes to have an account key registered with
the server, it may request that the server delete its account by
sending a POST request to the account URI containing the "delete"
field.
Paragraph (version B):
delete (required, boolean): The boolean value "true".
Paragraph (version B):
The request object MUST contain the "resource" field as required
above(with the value "reg").  It MUST NOT contain any fields besides
"resource" and "delete".
Paragraph (version B):
Note that although this object is very simple, the risk of replay or
fraudulent generation via signing oracles is mitigated by the need
for an anti-replay token in the protected header of the JWS.
Paragraph (version B):
On receiving a POST to an account URI containing a "delete" field,
the server MUST verify that no other fields were sent in the object
(other than "resource"), and it MUST verify that the value of the
"delete" field is "true" (as a boolean, not a string).  If either of
these checks fails, then the server MUST reject the request with
status code 400 (Bad Request).
Paragraph (version B):
If the server accepts the deletion request, then it MUST delete the
account and all related objects and send a response with a 200 (OK)
status code and an empty body.  The server SHOULD delete any
authorization objects related to the deleted account, since they can
no longer be used.  The server SHOULD NOT delete certificate objects
related to the account, since certificates issued under the account
continue to be valid until they expire or are revoked.
Paragraph (version B):
If a client wishes to relinquish its authorization to issue
certificates for an identifier, then it may request that the server
delete the authorization.  The client makes this request by sending a
POST request to the authorization URI containing a payload in the
same format as in deleting-an-account.  The only difference is that
the value of the "resource" field is "authz".
Paragraph (version B):
The server MUST perform the same validity checks as in deleting-an-
account and reject the request if they fail.  If the server deletes
the account then it MUST send a response with a 200 (OK) status code
and an empty body.
Draft: draft-ietf-acme-acme

Commentary: I 'm not sure if this is the correct place for issues with the actual server , but  is returning me an error message of When accessed from several machines . 
 No , this is n't the right place . Contact LetsEncrypt directly . This is for discussing the IETF protocol . 
 https://ietf - wg- does not detail what status code should be returned . I assume it should be a 202 , in line with Registration update , but it needs specifying IMO .
Paragraph (version B):
If the update was successful, then the server sends a response with
status code 200 (OK) and the updated registration object as its body.
If the update was not successful, then the server responds with an
error status code and a problem document describing the error.
Draft: draft-ietf-acme-acme

Commentary: The format should be specified more clearly , by reference to a couple of RFCs The " peer " provision seems kind of awkward . For server implementations where the validation is done by a separate entity than the ACME interactions ( like ) , this means that the challenge no longer has all the information that the validation agent needs to do the validation . I 'm inclined to drop it and put the burden on the client .
Paragraph (version A):
An IPv4 or IPv6 address which, if given, MUST be included in the
set of IP addresses to which the domain name resolves.  If given,
the server will connect to that specific IP address instead of
arbitrarily choosing an IP from the set of A and AAAA records to
which the domain name resolves.  If the field is given but equal
to ""peer"", the server MUST treat the field as if it contained
the IP address from which the response was received.
Paragraph (version B):
An IPv4 or IPv6 address which, in dotted decimal form or RFC4291
form, respectively.  If given, this address MUST be included in
the set of IP addresses to which the domain name resolves.  If
given, the server SHOULD connect to that specific IP address
instead of arbitrarily choosing an IP from the set of A and AAAA
records to which the domain name resolves.