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

Commentary: This PR is a first go at addressing the following points I raised on the mailing list . 
 This allows us to address the account URL recovery use case in without having special handling for empty payloads .
Paragraph (version A):
If the server already has an account registered with the provided
account key, then it MUST return a response with a 200 (OK) status
code and provide the URL of that account in the Location header
field.  This allows a client that has an account key but not the
corresponding account URI to recover the account URL.
Paragraph (version A):
If the client wishes to update this information in the future, it
sends a POST request with updated information to the account URL.
The server MUST ignore any updates to "order" fields or any other
fields it does not recognize.
Paragraph (version B):
If the server already has an account registered with the provided
account key, then it MUST return a response with a 200 (OK) status
code and provide the URL of that account in the Location header
field.  This allows a client that has an account key but not the
corresponding account URL to recover the account URL.
Paragraph (version B):
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 the client wishes to update this information in the future, it
sends a POST request with updated information to the account URL.
The server MUST ignore any updates to "order" fields or any other
fields it does not recognize.  If the server accepts the update, it
MUST return a response with a 200 (OK) status code and the resulting
account object.
Draft: draft-ietf-acme-acme

Commentary: And update certificate section to use it . Also describe Link : rel="up " behavior for pkix - cert .
Paragraph (version A):
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
could use the media type "application/pkix-cert" RFC2585 to request
the end-entity certificate in DER format.
Paragraph (version B):
The default format of the certificate is application/pem-certificate-
chain (see IANA Considerations).
Paragraph (version B):
The ACME client MAY request other formats by including an Accept
header in its request.  For example, the client could use the media
type "application/pkix-cert" RFC2585 to request the end-entity
certificate in DER format.  Server support for alternate formats is
OPTIONAL.  For formats that can only express a single certificate,
the server SHOULD provide one or more "Link: rel="up"" headers
pointing to an issuer or issuers so that ACME clients can build a
certificate chain as defined in TLS.
Paragraph (version B):
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.
Draft: draft-ietf-acme-acme

Commentary: I believe they are unnecessary . The server can set its own policy on whether to give back an existing or a new authz , and the client can choose to accept or reject that . Hugo also pointed out on - list that the status codes for these are inconsistent with the status codes for new - account . If we keep these , we 'd want to fix that . But simpler to delete , I think . 
 Let 's Encrypt tell me that they have had a few reports of buggy clients creating enough pending authorizations to saturate their rate limits , so they need a way for clients to clear these out . These clients are also not keeping around authorization URLs , so they ca n't just go them . My proposed solution would be to re - add the " authorizations " field to the account object , which got lost in the refactor in or so . Together with deactivation , enabling clients to enumerate authorization URLs would solve this problem . You could also envision a more direct solution , offering an endpoint that just deletes all pending authorizations for a client or client+identifier . 
 This is definitely too specific to these buggy clients . For the flow , the list of orders is sufficient . It 's true that technically you can create authorizations through a separate , optional , flow . But Let 's  has no plans to implement that flow , because other CAs have said they can not / would not implement it , so Let 's Encrypt implementing it would split the market . I 'm inclined to say let 's not complicate the protocol , and hypothetical clients that want to do the flow with some hypothetical server need to keep proper track of their authzs . Also , I think the particular issue with hitting limits for pending authzs can be solved in several ways without modifying the protocol . 
 If is merged , I would expect that a reasonable ACME server supporting new - authz would return an exiting authz , instead of giving a rate limit error . Or return existing authz from the beginning . 
 Closing as a result of WG decision at IETF 98
Paragraph (version A):
How an existing authorization should be handled.  Possible values
are "accept" and "require".
Paragraph (version A):
If the authorization request specifies "existing" with a value of
"accept" or "require", before proceeding, the server SHOULD determine
whether there are any existing, valid authorization resources for the
account and given identifier.  If one or more such authorizations
exists, a response SHOULD be returned with status code 303 (See
Other) and a Location header pointing to the existing resource URL;
processing of the request then stops.  If there are multiple such
authorizations, the authorization with the latest expiry date SHOULD
be returned.  If no existing authorizations were found and the value
for "existing" was "require", then the server MUST return status code
404 (Not Found); if it was "accept" or was any other value or was
absent, processing continues as follows.
Draft: draft-ietf-acme-acme

Commentary: Per feedback on - list .
Paragraph (version A):
If the server already has an account registered with the provided
account key, then it MUST return a response with a 200 (OK) status
code and provide the URI of that account in the Content-Location
header field.  This allows a client that has an account key but not
the corresponding account URI to recover the account URI.
Paragraph (version B):
If the server already has an account registered with the provided
account key, then it MUST return a response with a 200 (OK) status
code and provide the URI of that account in the Location header
field.  This allows a client that has an account key but not the
corresponding account URI to recover the account URI.
Draft: draft-ietf-acme-acme

Commentary: Thanks to for the original fixes in . 
 LGTM
Paragraph (version A):
The status of this authorization.  Possible values are: "pending",
"processing", "valid", "invalid" and "revoked".  If this field is
missing, then the default value is "pending".
Paragraph (version B):
The status of this authorization.  Possible values are: "pending",
"processing", "valid", "invalid" and "revoked".
Paragraph (version A):
A client may wish to change the public key that is associated with a
account in order to recover from a key compromise or proactively
mitigate the impact of an unnoticed key compromise.
Paragraph (version B):
A client may wish to change the public key that is associated with an
account in order to recover from a key compromise or proactively
mitigate the impact of an unnoticed key compromise.
Paragraph (version B):
Check that the payload of the JWS is a well-formed JWS object (the
"inner JWS").
Paragraph (version B):
Check that the inner JWS verifies using the key in its "jwk"
field.
Paragraph (version B):
Check that the payload of the inner JWS is a well-formed key-
change object (as described above).
Paragraph (version B):
Check that the "url" parameters of the inner and outer JWSs are
the same.
Paragraph (version B):
Check that the "account" field of the key-change object contains
the URL for the account matching the old key.
Draft: draft-ietf-acme-acme

Commentary: The client knows what its public key is , because it has to have access to the private key in order to sign new - account requests or updates to the account resource . So this field serves no purpose . 
 Has this been discussed on list ? I 'm concerned that we 're removing information that could be valuable for debugging client issues . There 's no harm in keeping this ; the server has to store this information anyway . 
 Yep , this was discussed on - list . I can say that as a client developer , I 've never found this field useful . Clients need to be able to successfully serialize a jwk in order to speak the protocol . Also , I have no objection to servers including this as an extra field , but it seems wrong to normatively require it when it serves no purpose . 
 For the record where it was available for discussion . For me , the observation that you need the private key to get an account object is dispositive . There 's not even debugging utility here . So I 'm OK to merge .
Paragraph (version A):
The public key of the account's key pair, encoded as a JSON Web
Key object RFC7517.  The client may not directly update this
field, but must use the key-change resource instead.
Paragraph (version A):
The server MUST ignore any values provided in the "key", and "orders"
fields in account bodies sent by the client, as well as any other
fields that it does not recognize.  If new fields are specified in
the future, the specification of those fields MUST describe whether
they can be provided by the client.
Paragraph (version B):
The server MUST ignore any values provided in the "orders" fields in
account bodies sent by the client, as well as any other fields that
it does not recognize.  If new fields are specified in the future,
the specification of those fields MUST describe whether they can be
provided by the client.
Paragraph (version A):
The server creates an account and populates the account object with
the "key" field containing the JWK public key used to verify the JWS.
The server returns this account object in a response with a 201
(Created) status code, with the account URI in a Location header
field.
Paragraph (version B):
The server creates an account and stores the public key used to
verify the JWS (i.e., the "jwk" element of the JWS header) to
authenticate future requests from the account.  The server returns
this account object in a 201 (Created) response, with the account URI
in a Location header field.
Paragraph (version A):
If the client wishes to update this information in the future, it
sends a POST request with updated information to the account URI.
The server MUST ignore any updates to the "key", or "order" fields or
any other fields it does not recognize.  The server MUST verify that
the request is signed with the private key corresponding to the "key"
field of the request before updating the account object.
Paragraph (version B):
If the client wishes to update this information in the future, it
sends a POST request with updated information to the account URI.
The server MUST ignore any updates to "order" fields or any other
fields it does not recognize.
Draft: draft-ietf-acme-acme

Commentary: Removes dnssec error type for a broader " dns " error type . It 's very hard to split out dnssec errors from regular dns problems , because recursive resolvers can only return SERVFAIL . The new dns error type also subsumes " unknownHost . " Introduces a new " incorrectResponse " error type for cases where connection and request were both successful , but the content did n't match . This also puts the validation - related errors at the bottom of the table so they can be viewed in context with each other . Introduces an error field for orders . Orders can fail independent of authorizations because of last - minute CAA checking , failure to submit to CT logs , timeouts , etc .
Paragraph (version B):
The error that occurred while processing the order, if any.  This
field is structured as a problem document RFC7807.
Draft: draft-ietf-acme-acme

Commentary: Instead of defining a whole new key equivalence method just check the JWK verifies the inner  .
Paragraph (version A):
Note that this comparison is equivalent to computing the JWK
thumbprints of the two keys and comparing thumbprints.  The only
difference is that there is no requirement for a hash computation
(and thus it is independent of the choice of hash function) and no
risk of hash collision.
Paragraph (version A):
Check that the "account" field of the key-change object contains
the URL for the account matching the old key.
Paragraph (version A):
Check that the "newKey" field of the key-change object contains
the key used to sign the inner JWS.
Paragraph (version B):
Check that the "newKey" field of the key-change object also
verifies the inner JWS.
Draft: draft-ietf-acme-acme

Commentary: Usage of is slightly confusing when we are not using int - enumerated error codes . RFC 7807 also refers to the problem document error types as and the field is called so this seems to make the most sense .
Paragraph (version A):
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.
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 type
"urn:ietf:params:acme:error:badNonce".  An error response with the
"badNonce" error type 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 A):
The server MUST return an error if it cannot fulfill 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.
Paragraph (version B):
The server MUST return an error if it cannot fulfill 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 type and description.
Paragraph (version A):
Initial contents: The codes and descriptions in the table in errors
above, with the Reference field set to point to this specification.
Paragraph (version B):
Initial contents: The types and descriptions in the table in errors
above, with the Reference field set to point to this specification.
Draft: draft-ietf-acme-acme

Commentary: Follow - up to , catches a few more references I initially missed . 
 I think ' field name ' makes more sense ... but I 'm not really we d to either .
Paragraph (version A):
In order to help clients configure themselves with the right URIs for
each ACME operation, ACME servers provide a directory object.  This
should be the only URL needed to configure clients.  It is a JSON
dictionary, 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 URIs 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 A):
The dictionary MAY additionally contain a key "meta".  If present, it
MUST be a JSON dictionary; each item in the dictionary is an item of
metadata relating to the service provided by the ACME server.
Paragraph (version B):
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 A):
The challenges that the client can fulfill in order to prove
possession of the identifier (for pending authorizations).  For
final authorizations, the challenges that were used.  Each array
entry is a dictionary with parameters required to validate the
challenge.  A client should attempt to fulfill at most one of
these challenges, and a server should consider any one of the
challenges sufficient to make the authorization valid.
Paragraph (version B):
The challenges that the client can fulfill in order to prove
possession of the identifier (for pending authorizations).  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 at most one of
these challenges, and a server should consider any one of the
challenges sufficient to make the authorization valid.
Draft: draft-ietf-acme-acme

Commentary: Previously these were spread among the various challenges . We can simplify by putting them in one place . Replaces .
Paragraph (version A):
It is RECOMMENDED that the server perform multiple DNS queries from
various network perspectives, in order to make MitM attacks harder.
Paragraph (version B):
It is RECOMMENDED that the server perform DNS queries and make HTTP
and TLS connections from various network perspectives, in order to
make MitM attacks harder.
Draft: draft-ietf-acme-acme

Commentary: In the term " registration " was changed to " account " . In and in some of the remaining references to " registration " were removed , but some ' new - reg ' and references to " registration " remained . This PR removes , hopefully , the last references to " registration " .
Paragraph (version A):
For new-reg requests, and for revoke-cert requests authenticated by
certificate key, there MUST be a "jwk" field.
Paragraph (version A):
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):
For new-account 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-account
resource.
Paragraph (version A):
If the client wishes to update this information in the future, it
sends a POST request with updated information to the account URI.
The server MUST ignore any updates to the "key", or "order" fields or
any other fields it does not recognize.  The server MUST verify that
the request is signed with the private key corresponding to the "key"
field of the request before updating the registration.
Paragraph (version B):
If the client wishes to update this information in the future, it
sends a POST request with updated information to the account URI.
The server MUST ignore any updates to the "key", or "order" fields or
any other fields it does not recognize.  The server MUST verify that
the request is signed with the private key corresponding to the "key"
field of the request before updating the account object.
Paragraph (version A):
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.
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-account
request.
Draft: draft-ietf-acme-acme

Commentary: Instead of leaving it ambiguous .
Paragraph (version A):
One of the revocation reasonCodes defined in Section 5.3.1 of
RFC5280 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.
Paragraph (version B):
One of the revocation reasonCodes defined in Section 5.3.1 of
RFC5280 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.  If a request contains a disallowed reasonCode the server
MUST reject it with the error type
"urn:ietf:params:acme:error:badRevocationReason".  The problem
document detail SHOULD indicate which reasonCodes are allowed.
Draft: draft-ietf-acme-acme

Commentary: As they are all fulfilled by the endpoint and are unnecessary . The relation is removed as the SCT will be provided by the CA via the certificate or a OCSP response , if it does n't provide these then the client should be able to retrieve the SCT itself from the logs it expects to find the certificate in ( or submit it itself ) . Also removes a paragraph about Certificate Transparency from the ' Downloading the Certificate ' section as it is irrelevant to the section and discusses operations of the CA unrelated to the ACME protocol . Additionally changes the relation which is not registered with a URI extension using the ACME URN namespace . 
 Looks good . Was posted on the list two weeks ago , with no objections , so merging .
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 "rate-limit" 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):
The "directory" link relation is present on all resources other than
the directory and indicates the directory URL.
Paragraph (version B):
The "index" link relation is present on all resources other than the
directory and indicates the directory URL.
Paragraph (version A):
The server MUST also provide a link relation header field with
relation "author" to indicate the order under which this certificate
was issued.
Paragraph (version A):
If the CA participates in Certificate Transparency (CT) RFC6962, then
they may want to provide the client with a Signed Certificate
Timestamp (SCT) that can be used to prove that a certificate was
submitted to a CT log.  An SCT can be included as an extension in the
certificate or as an extension to OCSP responses for the certificate.
The server can also provide the client with direct access to an SCT
for a certificate using a Link relation header field with relation
"ct-sct".