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

Commentary: A few editorial things that  found . 
 Editorial diffs only . Merging as - is . Thanks ! 
 : shipit :
Paragraph (version A):
To enable ACME account binding, a CA needs to provide the ACME client
with a MAC key and a key identifier, using some mechanism outside of
ACME.  The key identifier MUST be an ASCII string.  The MAC key
SHOULD be provided in base64url-encoded form, to maximize
compatibility between non-ACME provisioning systems and ACME clients.
Paragraph (version B):
To enable ACME account binding, the CA operating the ACME server
needs to provide the ACME client with a MAC key and a key identifier,
using some mechanism outside of ACME.  The key identifier MUST be an
ASCII string.  The MAC key SHOULD be provided in base64url-encoded
form, to maximize compatibility between non-ACME provisioning systems
and ACME clients.
Paragraph (version A):
File contains one or more certificates encoded with the PEM textual
encoding, according to RFC 7468 RFC7468.  In order to provide easy
interoperation with TLS, the first certificate MUST be an end-entity
certificate.  Each following certificate SHOULD directly certify one
preceding it.  Because certificate validation requires that trust
anchors be distributed independently, a certificate that specifies a
trust anchor MAY be omitted from the chain, provided that supported
peers are known to possess any omitted certificates.
Paragraph (version B):
File contains one or more certificates encoded with the PEM textual
encoding, according to RFC 7468 RFC7468.  In order to provide easy
interoperation with TLS, the first certificate MUST be an end-entity
certificate.  Each following certificate SHOULD directly certify the
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: In section 7.1.4 " Authorization Objects " the " challenges " field is described as containing : Later , after discussing the array entries a duplicate sentence appears : This is already covered by the initial description of what a final authorization 's challenges array holds and so this commit removes the second redundant sentence .
Paragraph (version A):
For pending authorizations, the challenges that the client can
fulfill in order to prove possession of the identifier.  For final
authorizations (in the "valid" or "invalid" state), 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 (in the "valid" or "invalid" state), 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.
Draft: draft-ietf-acme-acme

Commentary: This PR clarifies that a client SHOULD NOT assume that the " identifiers " , " authorizations " or " challenges " arrays returned in various server response objects are sorted . This PR also clarifies that while some have a 1:1 relationship between order identifiers and order authorizations this is n't a universal truth . This resolves 
 Is 6 days without any feedback on - list sufficient to merge ? 
 On the reuqest , there are two arrays returned , one for the and one for the . However , there is no order specified in ACMEv2 . As two arrays are returned ( and no hash ) , this might imply that the order of matches the order of . This is not specified right now . Having this specified would allow clients to know in advance for which identity they are requesting the authorization challenge before requesting the URL , e.g. for better error reporting . Also ok would be to just explicitly specify that the order is not guaranteed or the number of entries is not guaranteed to match in order to make it more clear to developers . cf . 
 From the outcome of the linked conversation , we should just specify that no specific order is guaranteed . 
 : +1 : - I will start a mailing list thread since this is a new SHOULD NOT . 
 Looks good to me ; let 's wait a little bit for feedback on - list .
Paragraph (version A):
For pending orders, the authorizations that the client needs to
complete before the requested certificate can be issued (see
identifier-authorization).  For final orders (in the "valid" or
"invalid" state), the authorizations that were completed.  Each
entry is a URL from which an authorization can be fetched with a
GET request.
Paragraph (version B):
For pending orders, the authorizations that the client needs to
complete before the requested certificate can be issued (see
identifier-authorization).  The authorizations required are
dictated by server policy and there may not be a 1:1 relationship
between the order identifiers and the authorizations required.
For final orders (in the "valid" or "invalid" state), the
authorizations that were completed.  Each entry is a URL from
which an authorization can be fetched with a GET request.
Paragraph (version A):
resource.
Paragraph (version B):
resource.  Clients SHOULD NOT make any assumptions about the sort
order of "identifiers" or "authorizations" elements in the returned
order object.
Draft: draft-ietf-acme-acme

Commentary: Thanks for the comments I 've updated the PR to address . 
 There has been list discussion on this PR and consensus is positive . I 'm going to merge this now that has addressed the feedback provided . 
 LGTM : rocket :
Paragraph (version A):
ACME clients SHOULD send a User-Agent header in accordance with
RFC7231, including the name and version of the ACME software in
addition to the name and version of the underlying HTTP client
software.
Paragraph (version B):
ACME clients MUST send a User-Agent header, in accordance with
RFC7231.  This header SHOULD include the name and version of the ACME
software in addition to the name and version of the underlying HTTP
client software.
Paragraph (version B):
For this reason, it is RECOMMENDED that account key pairs be used for
no other purpose besides ACME authentication.  For example, the
public key of an account key pair SHOULD NOT be included in a
certificate.  ACME clients and servers SHOULD verify that a CSR
submitted in a finalize request does not contain a public key for any
known account key pair.  In particular, when a server receives a
finalize request, it MUST verify that the public key in a CSR is not
the same as the public key of the account key pair used to
authenticate that request.
Draft: draft-ietf-acme-acme

Commentary: When the " ready " status was to the order process we missed a place in Section 7.4 where the specification claims an order should be in status " processing " when it is ready for finalization . This commit changes this sentence to say the order is ready for finalization when it is status " ready " . Thanks to for flagging this issue on - list .
Paragraph (version A):
A request to finalize an order will result in error if the order
indicated does not have status "pending", if the CSR and order
identifiers differ, or if the account is not authorized for the
identifiers indicated in the CSR.
Paragraph (version B):
A request to finalize an order will result in error if the order
indicated does not have status "ready", if the CSR and order
identifiers differ, or if the account is not authorized for the
identifiers indicated in the CSR.
Draft: draft-ietf-acme-acme

Commentary: 1 ) Section 7.1.4 - Include " expires " in possible authz status values . 2 ) 7.1.2.1 - Fix orders link rel relation syntax Thanks to for flagging these issues on - list .
Paragraph (version A):
The status of this authorization.  Possible values are: "pending",
"valid", "invalid", "deactivated", and "revoked".
Paragraph (version B):
The status of this authorization.  Possible values are: "pending",
"valid", "invalid", "deactivated", "expired", and "revoked".
Draft: draft-ietf-acme-acme

Commentary: 1 ) Include optional field in the Account Creation section with a forward pointer to the external account binding section . 2 ) Include the mandatory " orders " field in the example new account response . 3 ) Correct the " orders " field type in Section 9.7.1 to match the type from 7.1.2 Thanks to for flagging these issues on the WG Mailing List .
Paragraph (version B):
An optional field for binding the new account with an existing
non-ACME account (see external-account-binding ).
Draft: draft-ietf-acme-acme

Commentary: Replaces 
 This text looks fine to me . I think there should be discussion in WGLC about this since folks that care about pre - authorization might be surprised by this new constraint .
Paragraph (version A):
If the ACME server does not implement pre-authorization
(Section 7.4.1) it MUST omit the "newAuthz" field of the directory.
Paragraph (version B):
If the ACME server does not implement pre-authorization (pre-
authorization) it MUST omit the "newAuthz" field of the directory.
Paragraph (version A):
The type of identifier.
Paragraph (version A):
The identifier itself.
Paragraph (version B):
Note that because the identifier in a pre-authorization request is
the exact identifier to be included in the authorization object, pre-
authorization cannot be used to authorize issuance with wildcard DNS
identifiers.
Draft: draft-ietf-acme-acme

Commentary: This is my attempt to find a quick way out of this content - type mess . Replaces and 
 This also looks good to me , thanks for drafting it ! 
 +1 - This looks like a low complexity path forward that resolves ambiguity .
Paragraph (version A):
The JWS MUST NOT have multiple signatures.
Paragraph (version A):
The JWS Compact Serialization RFC7515 MUST be used.
Paragraph (version A):
Either the JWS Flattened JSON Serialization RFC7515 or the JWS
General JSON Serialization RFC7515 MUST be used.
Paragraph (version A):
The JWS Unprotected Header RFC7515 SHOULD NOT be used.
Paragraph (version A):
In the examples below, JWS objects are shown in the Flattened JSON
serialization, with the protected header and payload expressed as
base64url(content) instead of the actual base64-encoded value, so
that the content is readable.
Paragraph (version B):
Because client requests in ACME carry JWS objects in the Flattened
JSON Serialization, they must have the "Content-Type" header field
set to "application/jose+json".  If a request does not meet this
requirement, then the server MUST return a response with status code
415 (Unsupported Media Type).
Draft: draft-ietf-acme-acme

Commentary: Merging because editorial . 
 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 . To me ( non - native English speaker ) " were not " refers to " an account " which would be a grammar mistake . If it refers to " authorizations " would it be better to switch " authorizations " and " an account " ? 
 I think it is technically correct ( it does refer to " authorizations " ) , but I agree it 's an awkward sentence . Filed to address .
Paragraph (version A):
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 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 allow an ACME account to use authorizations that have
been granted to an external, non-ACME account.  This allows ACME to
address issuance scenarios that cannot yet be fully automated, such
as the issuance of Extended Validation certificates.
Draft: draft-ietf-acme-acme

Commentary: I believe this PR could be regarded as editorial as it does n't really change meaning .
Paragraph (version A):
The client's order for a certificate describes the desired
certificate using a PKCS#10 Certificate Signing Request (CSR) plus a
few additional fields that capture semantics that are not supported
in the CSR format.  If the server is willing to consider issuing such
a certificate, it responds with a list of requirements that the
client must satisfy before the certificate will be issued.
Paragraph (version B):
The client's order for a certificate describes the desired
identifiers plus a few additional fields that capture semantics that
are not supported in the CSR format.  If the server is willing to
consider issuing such a certificate, it responds with a list of
requirements that the client must satisfy before the certificate will
be issued.
Paragraph (version A):
Once the validation process is complete and the server is satisfied
that the client has met its requirements, the server will issue the
requested certificate and make it available to the client.
Paragraph (version B):
Once the validation process is complete and the server is satisfied
that the client has met its requirements, the client finalizes the
order by submitting a PKCS#10 Certificate Signing Request (CSR).  The
server will issue the requested certificate and make it available to
the client.
Draft: draft-ietf-acme-acme

Commentary: Section " Request Authentication " already forbade it . 
 In general , we have not been making MUST - level requirements for servers in this document because CAs are subject to a lot of external constraints already . Under that theory , I would say we should just close this .  ? 
 If you do n't want this change , can you change " Servers MUST NOT respond to GET requests for resources that might be considered sensitive . Account resources are the only sensitive resources defined in this specification . " instead to resolve the inconsistency ? 
 I agree with - this is n't a new MUST - level requirement , it 's already said elsewhere that the server MUST NOT respond to sensitive resources and the account object has contact information you would n't want returned to an unauthenticated GET request . It seems fine to emphasize this in the account information section . 
 I 'm going to merge this . gives an OOB +1 . Thanks !
Paragraph (version A):
Servers SHOULD NOT respond to GET requests for account resources as
these requests are not authenticated.  If a client wishes to query
the server for information about its account (e.g., to examine the
"contact" or "orders" fields), 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):
Servers MUST NOT respond to GET requests for account resources as
these requests are not authenticated.  If a client wishes to query
the server for information about its account (e.g., to examine the
"contact" or "orders" fields), 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 ({}).
Draft: draft-ietf-acme-acme

Commentary: As suggested by Felipe Gasper 
 fixed . Note , also standardized on " validation method " ( vs. " mechanism " ) .
Paragraph (version B):
An ACME challenge object represents a server's offer to validate a
client's possession of an identifier in a specific way.  Unlike the
other objects listed above, there is not a single standard structure
for a challenge object.  The contents of a challenge object depend on
the validation method being used.  The general structure of challenge
objects and an initial set of validation methods are described in
identifier-validation-challenges.
Paragraph (version A):
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):
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 methods.
Draft: draft-ietf-acme-acme

Commentary: Section 6.2 " Request Authentication " says : Prior to this commit Section 7.3 " Account Creation " does n't mention that the account URL also doubles as the key ID . To make the question of " What is my Key ID ? " more obvious for client implementers this commit adds a brief mention of this fact where the specification discusses the account URL . Thanks to for flagging this and providing a chance to avoid confusion and add clarity . 
 thanks
Paragraph (version A):
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 URL
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 URL
in a Location header field.  The account URL is used as the "kid"
value in the JWS authenticating subsequent requests by this account
(See request-authentication).
Draft: draft-ietf-acme-acme

Commentary: As recommended by . Thanks to for the catch . 
 I believe you need write , admin , or owner permissions on the repo for a " changes requested " review to show up this way in the GH UI . 
 ( Merging myself because it 's the real author is I 'm just the scribe ) 
 Could you please change the spelling ? ( Why wo n't I get a " Changes requested " with red marker ? )
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.  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.
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 omit the reasonCode CRL
entry extension 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: In Section 7.4.1 " Pre - Authorization " the spec says : If a CA wishes to allow pre - authorization within ACME , it can offer a " new authorization " resource in its directory by adding the field " newAuthz " with a URL for the new authorization resource . That text indicates that the CA may wish to not support pre - authorization in which case the " newAuthz " resource will not be present in the directory . One example of an ACME CA choosing to not support pre - authorization is Let 's Encrypt . This commit clarifies the " newAuthz " field of the directory is optional in Section 7.1.1 " Directory " where a developer is likely to look to understand which resources must be supported / present in the directory and which are optional ( " meta " , " newAuthz " ) . If the server does n't support pre - authorization it MUST omit the " newAuthz " field .
Paragraph (version B):
If the ACME server does not implement pre-authorization
(Section 7.4.1) it MUST omit the "newAuthz" field of the directory.
Draft: draft-ietf-acme-acme

Commentary: The example was misleading in case a certificate is revoked by signing the revocation request with the certificate 's private key . I assume " jwk " should be the public key from the certificate in this case and not the account key ; see 
 Merging because it looks like the issue raised by has been addressed .
Paragraph (version A):
For new-account 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 URL received by POSTing to the new-account
resource.
Paragraph (version B):
For newAccount requests, and for revokeCert requests authenticated by
certificate key, there MUST be a "jwk" field.  This field MUST
contain the public key corresponding to the private key used to sign
the JWS.
Paragraph (version B):
For all other requests, the request is signed using an existing
account and there MUST be a "kid" field.  This field MUST contain the
account URL received by POSTing to the newAccount resource.
Paragraph (version B):
Revocation requests are different from other ACME requests in that
they can be signed either with an account key pair or the key pair in
the certificate.
Draft: draft-ietf-acme-acme

Commentary: Prior to this commit the IDN prefix referenced from RFC5890 was being turned from to . This commit escapes the two dashes so they remain in the generated doc . Thanks to for reporting ! Resolves 
 In https://ietf - wg- This should be : 
 Opened with a fix . Thanks !
Paragraph (version A):
The only type of identifier defined by this specification is a fully-
qualified domain name (type: "dns").  If a domain name contains non-
ASCII Unicode characters it MUST be encoded using the rules defined
in RFC3492.  Servers MUST verify any identifier values that begin
with the ASCII Compatible Encoding prefix "xn-" as defined in RFC5890
are properly encoded.  Wildcard domain names (with "*" as the first
label) MUST NOT be included in authorization objects.
Paragraph (version B):
The only type of identifier defined by this specification is a fully-
qualified domain name (type: "dns").  If a domain name contains non-
ASCII Unicode characters it MUST be encoded using the rules defined
in RFC3492.  Servers MUST verify any identifier values that begin
with the ASCII Compatible Encoding prefix "xn--" as defined in
RFC5890 are properly encoded.  Wildcard domain names (with "*" as the
first label) MUST NOT be included in authorization objects.