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

Commentary: Since the rest of the spec and protocol makes extensive use of JSON , when I was reading the spec the first time , I did n't know if the link relations were supposed to be JSON link relations like HAL or LinkedData . The spec mentions " link relation " 6 times , but only one of them ( the 2nd - to - last ) makes explicit reference to RFC 5988 for web linking via HTTP header .
Paragraph (version A):
ACME uses different URIs for different management functions.  Each
function is listed in a directory along with its corresponding URI,
so clients only need to be configured with the directory URI.
Paragraph (version B):
ACME uses different URIs for different management functions.  Each
function is listed in a directory along with its corresponding URI,
so clients only need to be configured with the directory URI.  These
URIs are connected by a few different link relations RFC5988.
Draft: draft-ietf-acme-acme

Commentary: This looks consistent with list discussion . Thanks .
Paragraph (version A):
A URI from which a list of authorizations granted to this account
can be fetched via a GET request.  The result of the GET request
MUST be a JSON object whose "authorizations" field is an array of
strings, where each string is the URI of an authorization
belonging to this registration.  The server SHOULD include pending
authorizations, and SHOULD NOT include authorizations that are
invalid or expired.
Paragraph (version A):
A URI from which a list of certificates issued for this account
can be fetched via a GET request.  The result of the GET request
MUST be a JSON object whose "certificates" field is an array of
strings, where each string is the URI of a certificate.  The
server SHOULD NOT include expired or revoked certificates.
Paragraph (version B):
A URI from which a list of authorizations granted to this account
can be fetched via a GET request.  The result of the GET request
MUST be a JSON object whose "authorizations" field is an array of
strings, where each string is the URI of an authorization
belonging to this registration.  The server SHOULD include pending
authorizations, and SHOULD NOT include authorizations that are
invalid or expired.  The server MAY return an incomplete list,
with a "link rel=next" header indicating a URL to retrieve further
entries.
Paragraph (version B):
A URI from which a list of certificates issued for this account
can be fetched via a GET request.  The result of the GET request
MUST be a JSON object whose "certificates" field is an array of
strings, where each string is the URI of a certificate.  The
server SHOULD NOT include expired or revoked certificates.  The
server MAY return an incomplete list, with a "link rel=next"
header indicating a URL to retrieve further entries.
Draft: draft-ietf-acme-acme

Commentary: This looks fine to me , and consistent with the list discussions . ( I have a couple of minor issues , which I filed as . ) I am merging this in preference to , which got negative feedback on the list . 
 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):
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 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.  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 B):
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 A):
Dereference the URI using an HTTP GET request.
Paragraph (version B):
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 B):
Dereference the URI using an HTTP GET request.  If an address was
supplied by the client, use that address to establish the HTTP
connection.
Draft: draft-ietf-acme-acme

Commentary: I 've noticed that boulder uses DNS over TCP . I suppose this has not been an arbitrary choice , but something that would be useful to document . 
 As an FYI ,  currently uses TCP for DNS to its local authoritative resolver , but the resolver uses UDP . We tried making the resolver do upstream resolution with TCP but got a large number of failures .
Paragraph (version A):
There are certain factors that arise in operational reality that
operators of ACME-based CAs will need to keep in mind when
configuring their services.
Draft: draft-ietf-acme-acme

Commentary: This replaces tls - sni-01 with tls - sni-02 , which requires that domains being validated return a certificate which contains a hostname that is not revealed by the server in its handshake . This ensures that challenges can not be passed by domains which auto - generate self - signed certificates in response to requests with SANs for domains not previously seen .
Paragraph (version A):
The client MUST ensure that the certificate is served to TLS
connections specifying a Server Name Indication (SNI) value of SAN B.
Paragraph (version B):
The client MUST ensure that the certificate is served to TLS
connections specifying a Server Name Indication (SNI) value of SAN A.
Paragraph (version A):
Open a TLS connection to the domain name being validated on the
requested port, presenting SAN B in the SNI field.
Paragraph (version A):
The server MUST request the certificate using an SNI value of SAN
B.
Paragraph (version A):
The server SHOULD ensure that it does not reveal SAN A in any way
when making the TLS connection, such that the presentation of SAN
A in the returned certificate proves association with the client.
Paragraph (version B):
Open a TLS connection to the domain name being validated on the
requested port, presenting SAN A in the SNI field.
Paragraph (version B):
The server MUST request the certificate using an SNI value of SAN
A.
Paragraph (version B):
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: Looked like a small grammatical error .
Paragraph (version A):
The client generates a self-signed certificate for with a single
subjectAlternativeName extension dNSName that is
"<Z[0:32]>.<Z[32:64]>.acme.invalid", where "Z[0:32]" and "Z[32:64]"
represent the first 32 and last 32 characters of the hex-encoded
value, respectively (following the notation used in Python).  The
client then configures the TLS server at the domain such that when a
handshake is initiated with the Server Name Indication extension set
to "<Z[0:32]>.<Z[32:64]>.acme.invalid", the corresponding generated
certificate is presented.
Paragraph (version B):
The client generates a self-signed certificate with a single
subjectAlternativeName extension dNSName that is
"<Z[0:32]>.<Z[32:64]>.acme.invalid", where "Z[0:32]" and "Z[32:64]"
represent the first 32 and last 32 characters of the hex-encoded
value, respectively (following the notation used in Python).  The
client then configures the TLS server at the domain such that when a
handshake is initiated with the Server Name Indication extension set
to "<Z[0:32]>.<Z[32:64]>.acme.invalid", the corresponding generated
certificate is presented.
Draft: draft-ietf-acme-acme

Commentary: I approve of this change . 
 This looks good to me . I would like to tighten up the language a bit to clarify that this applies to validation of DNS identifiers , but will do that in a follow - on PR .
Paragraph (version B):
An ACME-based CA needs to make DNS lookups when processing
challenges.  Because the security of an ACME-based CA ultimately
depends entirely on the authenticity of DNS data, every possible
precaution should be taken to secure such lookups.  It is therefore
RECOMMENDED that ACME-based CAs make all DNS resolutions via DNSSEC-
validating stub or recursive resolvers.  This provides additional
protection to domains which choose to make use of DNSSEC.
Paragraph (version B):
An ACME-based CA must use only a resolver if it trusts the resolver
and every component of the network route by which it is accessed.  It
is therefore RECOMMENDED that ACME-based CAs operate their own
DNSSEC-validating resolvers within their trusted network and use
these resolvers both for all CAA record lookups and all record
lookups in furtherance of a challenge scheme (A, AAAA, TXT, etc.).
Draft: draft-ietf-acme-acme

Commentary: Also fixes some RFC3339 timestamps shown in examples , which must include seconds . 
 Authorization expiry should be a timestamp not a date , to allow for authorizations with very short expiry times . All discussion should be done on the mailing list .
Paragraph (version A):
The date after which the server will consider this authorization
invalid, encoded in the format specified in RFC 3339 RFC3339.
Paragraph (version B):
The timestamp after which the server will consider this
authorization invalid, encoded in the format specified in RFC 3339
RFC3339.
Draft: draft-ietf-acme-acme

Commentary: For discussion . 
 See also : 
 I proposed on the mailing list to remove implicit renewal some time ago , and it received some support . Creating this issue to track it . All discussion should be done on the mailing list .
Paragraph (version A):
A certificate resource always represents the most recent certificate
issued for the name/key binding expressed in the CSR.  If the CA
allows a certificate to be renewed, then it publishes renewed
versions of the certificate through the same certificate URI.
Paragraph (version A):
Clients retrieve renewed versions of the certificate using a GET
query to the certificate URI, which the server should then return in
a 200 (OK) response.  The server SHOULD provide a stable URI for each
specific certificate in the Content-Location header field, as shown
above.  Requests to stable certificate URIs MUST always result in the
same certificate.
Paragraph (version A):
To avoid unnecessary renewals, the CA may choose not to issue a
renewed certificate until it receives such a request (if it even
allows renewal at all).  In such cases, if the CA requires some time
to generate the new certificate, the CA MUST return a 202 (Accepted)
response, with a Retry-After header field that indicates when the new
certificate will be available.  The CA MAY include the current (non-
renewed) certificate as the body of the response.
Paragraph (version A):
Likewise, in order to prevent unnecessary renewal due to queries by
parties other than the account key holder, certificate URIs should be
structured as capability URLs W3C.WD-capability-urls-20140218.
Paragraph (version A):
From the client's perspective, there is no difference between a
certificate URI that allows renewal and one that does not.  If the
client wishes to obtain a renewed certificate, and a GET request to
the certificate URI does not yield one, then the client may initiate
a new-certificate transaction to request one.
Paragraph (version B):
A certificate resource represents a single, immutable certificate.
If the client wishes to obtain a renewed certificate, the client
initiates a new-certificate transaction to request one.
Paragraph (version B):
Because certificate resources are immutable once issuance is
complete, the server MAY enable the caching of the resource by adding
Expires and Cache-Control headers specifying a point in time in the
distant future.  These headers have no relation to the certificate's
period of validity.
Draft: draft-ietf-acme-acme

Commentary: The current wording ( " root URL " ) may lead readers to believe that the ACME directory URI 's path is " / " , whereas it could actually be anything . Reword to " only URL " and provide examples which emphasize that the choice of the URL for the dictionary object is arbitrary .
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 root URL with which clients are configured.  It is a
JSON dictionary, whose keys are the "resource" values listed in
https-requests, and whose values are the URIs used to accomplish the
corresponding function.
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
dictionary, whose keys are the "resource" values listed in https-
requests, and whose values are the URIs used to accomplish the
corresponding function.
Paragraph (version B):
a host which function as both an ACME and Web server may want to
keep the root path "/" for an HTML "front page", and and place the
ACME directory under path "/acme".
Paragraph (version B):
a host which only functions as an ACME server could place the
directory under path "/".
Draft: draft-ietf-acme-acme

Commentary: At the IETF meeting , we discussed the possibility of simplifying the " tls - sni-01 " challenge to remove the iterations , as suggested in . noted that if we were going to do that , we should recommend some ways for CAs to check whether a default vhost was in play . This PR adds such a note , and creates an " Operational Considerations " section for any future such notes that might come along .
Paragraph (version B):
There are certain factors that arise in operational reality that
operators of ACME-based CAs will need to keep in mind when
configuring their services.
Paragraph (version B):
In many cases, TLS-based services are deployed on hosted platforms
that use the Server Name Indication (SNI) TLS extension to
distinguish between different hosted services or "virtual hosts".
When a client initiates a TLS connection with an SNI value indicating
a provisioned host, the hosting platform routes the connection to
that host.
Paragraph (version B):
When a connection come in with an unknown SNI value, one might expect
the hosting platform to terminate the TLS connection.  However, some
hosting platforms will choose a virtual host to be the "default", and
route connections with unknown SNI values to that host.
Paragraph (version B):
In such cases, the owner of the default virtual host can complete a
TLS-based challenge (e.g., "tls-sni-01") for any domain with an A
record that points to the hosting platform.  This could result in
mis-issuance in cases where there are multiple hosts with different
owners resident on the hosting platform.
Paragraph (version B):
A CA that accepts TLS-based proof of domain control should attempt to
check whether a domain is hosted on a domain with a default virtual
host before allowing an authorization request for this host to use a
TLS-based challenge.  A default virtual host can be detected by
initiating TLS connections to the host with random SNI values within
the namespace used for the TLS-based challenge (the "acme.invalid"
namespace for "tls-sni-01").
Draft: draft-ietf-acme-acme

Commentary: I 'm not sure whether we should add something like : 
 I think " in a way that requires an agreement update " as you 've written is clear enough . Users wo n't need to re - agree if just fixing a typographical error .
Paragraph (version A):
If the server wishes to present the client with terms under which the
ACME service is to be used, it MUST indicate the URI where such terms
can be accessed in a Link header with link relation "terms-of-
service".  As noted above, the client may indicate its agreement with
these terms by updating its registration to include the "agreement"
field, with the terms URI as its value.
Paragraph (version B):
If the server wishes to present the client with terms under which the
ACME service is to be used, it MUST indicate the URI where such terms
can be accessed in a Link header with link relation "terms-of-
service".  As noted above, the client may indicate its agreement with
these terms by updating its registration to include the "agreement"
field, with the terms URI as its value.  When these terms change in a
way that requires an agreement update, the server MUST use a
different URI in the Link header.
Draft: draft-ietf-acme-acme

Commentary: I was unable to generate the latest draft using make . This PR fixes the missing references .
Paragraph (version A):
An example of how to compute a JWK thumbprint can be found in
Section 3.1 of RFC7638.  Note that some cryptographic libraries
prepend a zero octet to the representation of the RSA public key
parameters N and E, in order to avoid ambiguity with regard to the
sign of the number.  As noted in JWA, a JWK object MUST NOT include
this zero octet.  That is, any initial zero octets MUST be stripped
before the values are Base64url-encoded.
Paragraph (version B):
An example of how to compute a JWK thumbprint can be found in
Section 3.1 of RFC7638.  Note that some cryptographic libraries
prepend a zero octet to the representation of the RSA public key
parameters N and E, in order to avoid ambiguity with regard to the
sign of the number.  As noted in JWA RFC7518, a JWK object MUST NOT
include this zero octet.  That is, any initial zero octets MUST be
stripped before the values are Base64url-encoded.
Draft: draft-ietf-acme-acme

Commentary: vs. The spec does n't seem to be consistent . And why does it have to be completed with HTTP ? I honestly do n't understand that . 
 LE 's seems to give a choice . I 'd really prefer that . This would make it possible to not even listen on port 80 for things like APIs , e.g. GitHub does that on . 
 As discussed on the list and in the document , the HTTP challenge needs to be HTTP - only in order to avoid the default - vhost issues . Thanks for catching the stray HTTPS text . I will remove it . 
 Do you have a link to the discussion ? 
 See Is that example just bogus or what 's the for ? There are only two challenges , so it ca n't be an index there . 
 Good point . Left over from when we had three challenges in the example . 
 Contact information may have been misspelled during registration . Contact information such as phone numbers may also change .  exposes only the endpoint and that endpoint does n't accept updates , because it has to respond with 409 Conflict for already existing keys . There should be a way to update that information . See also 
 thanks yes updating the contact email for registered LE account is a must have feature otherwise an LE notifications / renew notices may end up going to invalid email addresses . 
 Right now , the spec says that you can update anything in the registration with a : Note that the request goes to the registration URL , not the new - registration URL . I 'll add an example to the document to clarify .
Paragraph (version A):
Dereference the URI using an HTTP or HTTPS GET request.  If using
HTTPS, the ACME server MUST ignore the certificate provided by the
HTTPS server.
Paragraph (version B):
Dereference the URI using an HTTP GET request.
Draft: draft-ietf-acme-acme

Commentary: In addition to adding the error , as proposed in , this PR fixes some issues discussed in the F2F meeting , namely moving ACME URNs under the IETF parameters space , and having errors be a sub - namespace of an overall ACME namespace .
Paragraph (version B):
This list is not exhaustive.  The server MAY return errors whose
"type" field is set to a URI other than those defined above.  Servers
MUST NOT use the ACME URN namespace for errors other than the
standard types.  Clients SHOULD display the "detail" field of such
errors.
Draft: draft-ietf-acme-acme

Commentary: What advantage does including the old key provide ? 
 Having the new key sign over the field makes the hand - over mutual -- the old key blesses the new key by signing over the JWS and the new key accepts by signing over the thumbprint . Basically , the field is acting as an identifier for the registration for purposes of the new key 's acceptance of the hand - over . Note that this is well - defined because the server is required to only have one registration for a given key - pair ( it MUST return a 409 / Conflict if there 's an attempt to duplicate ) . 
 Account keys should change over time to improve security . We should have a way to change the key associated with an account with changing anything else about the account . Something liike : Post : /rotate - key { " key " : { /\ JWK key / } } Note : The request should be signed with the old key . All authorizations should remain with the account . If there are any requests being validated then they should still use the old key ( as specified by the oriignal authorization request .
Paragraph (version B):
The string "reg", indicating an update to the registration.
Paragraph (version B):
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 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 parameter of the "newKey" JWS object.
Draft: draft-ietf-acme-acme

Commentary: The idea here is that if the CA opts not to log the precertificates it has a mechanism for publishing the proofs that are associated with a cert . 
 There are two good mechanisms to do this without adding a new endpoint : The CA implementing ACME can include SCTs in its OCSP responses Subscribers that wish to use SCTs , for instance in the TLS Extension mode of operation , may fetch those SCTs directly from the CT logs . 
 Neither of these seem like great substitutes . The first seems to violate straightforward reference semantics . The second puts a lot more work on the server . 
 I think this can be easily solved with a .
Paragraph (version B):
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 certicate was issued.
Paragraph (version B):
If the CA particpates 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 a 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".