Subject: [Acme] Spec change to allow retrieval of Terms of Service URL

From: Matthew Holt <[email-masked]>
Date: Fri, 06 Nov 2015 19:03:35 +0000

I'd like to propose a change that allows clients of the ACME protocol to
obtain the URL to the CA's current Terms of Service (if any) without
re-registering or trying to obtain a certificate and getting a failure
response.

This proposal has two parts: adding an entry to the directory, and adding
the current ToS URL to response headers.

Section 6.2 explains the directory, and adding an entry to the directory
seems logical:

{
  "new-reg": "https://example.com/acme/new-reg",
  "recover-reg": "https://example.com/acme/recover-reg",
  "new-authz": "https://example.com/acme/new-authz",
  "new-cert": "https://example.com/acme/new-cert",
  "revoke-cert": "https://example.com/acme/revoke-cert",
*  "agreement-url": "https://example.com/acme/subscriber-agreement-v01.pdf
<https://example.com/acme/subscriber-agreement-v01.pdf>",*
}

Additionally, including the current ToS in response headers of a failed
request will allow clients to show the current terms and re-prompt the user
immediately, if available. Something like this:

*Agreement-URL: https://example.com/acme/subscriber-agreement-v01.pdf
<https://example.com/acme/subscriber-agreement-v01.pdf>*

Both of these could be optional (as the CA sees fit), but it makes it
possible for clients to offer a better user experience.

Thanks,
Matt Holt

---

From: Daniel Kahn Gillmor <[email-masked]>
Date: Wed, 11 Nov 2015 21:06:09 -0500

> possible for clients to offer a better user experience.

Doesn't this depend on the nature of the data fetched at the given URL?
I'd hope that any inclusion of some mechanism like this would be tightly
constrained with guidance that makes the data both self-contained and
immutable.  Something like:

 a) all the necessary data to understand the subscriber agreement is
    available from that specific URL, without requiring any additional
    resource fetches, arbitrary code execution, etc.  I shouldn't need
    to pull in external stylesheets or images, to run javascript,
    receive or send cookies, etc. in order to be able to render the
    document to the user.  You've used .pdf in your example above: there
    are now PDFs that violate all these assumptions.  Maybe we could
    limit to text/plain; charset=UTF-8, or (if PDF is needed) to PDF/A
    or some similar archival-quality subset of PDF?

 b) That the resource fetched from that URL will never change.  I don't
    want to retrieve the URL at time T, display it to the user, and then
    have the user continue the process at time T+2 when the document
    changed at time T+1.

    --dkg

---

From: Yoav Nir <[email-masked]>
Date: Thu, 12 Nov 2015 09:10:18 +0200

> On 12 Nov 2015, at 4:06 AM, Daniel Kahn Gillmor <[email-masked]> wrote:
> 

Lawyers use PDFs, and often use the cringeworthy practice of scanning type-written or printed pages into a PDF. So I don’t think we can require text/plain. I think it’s fine to require PDF/A, especially because there are a lot of PDF viewers out there and not all of them support the advanced stuff like attachments. Realistically, this would not be enforced. I wouldn’t write my ACME client such that it downloads the PDF and validates that it is valid plaintext or PDF/A.

>    have the user continue the process at time T+2 when the document

Definitely a good idea to keep the agreement stable at least as long as certificates that were issued under it are still unexpired, probably a few more years. The name in the example does suggest versioning to support just that.

Yoav

---

From: Matthew Holt <[email-masked]>
Date: Thu, 12 Nov 2015 15:30:44 +0000

>     or some similar archival-quality subset of PDF?

I agree; I only used pdf in my example because the current Let's Encrypt SA
is in PDF format:
https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf - indeed a
text document would be simpler and safer.

If the client leaves it up to the user to follow the link, then the format
shouldn't matter in terms of the ACME spec; it is up to the document
renderer (browser) to do so safely and correctly.

If the client were to actually download and show the document to the user,
then yes, plain text would be much better. Most terminal-based clients will
probably not want to show the full legal terms in the terminal window, but
would prefer a link. Simpler, less screen space required, accomplishes same
goal.

>     have the user continue the process at time T+2 when the document

That's the idea. The URL to that version of the document should never
change (ideally, but I suppose that is up to the CAs), but if it does, it
means there is a new document, i.e. updated terms, the user must agree to.
So the URL would be assumed to be a key or token value representing the
actual legal text; if it changes, the user should be re-prompted.

---

From: Daniel Kahn Gillmor <[email-masked]>
Date: Thu, 12 Nov 2015 16:57:07 -0500

> renderer (browser) to do so safely and correctly.

if the spec has any implications that the user is agreeing to something
by proceeding with the process, then the spec needs to be really clear
what it means.  If a document is unreadable by a user with (for example)
a browser that declines to execute javascript, or a browser cannot
access third-party resources, then the spec is encouraging both parties
(subscribers and CAs) to lie to each other.

> would prefer a link. Simpler, less screen space required, accomplishes same

They don't appear to accomplish the same goal to me.  Maybe we need to
spell out what the goal is more explicitly?

> actual legal text; if it changes, the user should be re-prompted.

If the intent is to be able to update the terms of service in
continuance of the subscriber relationship, then the immutability of the
provided statement needs to be much more carefully spelled out.

Terms of Service, notice, and consent are complex problems with effects
going all the way up the stack to layer 9.  If ACME proposes to treat
them as in-scope for the specification, we need to be careful and
explicit about how they're being tied in.

I know "the IETF does not do UI", but we need to describe at least the
semantics of tasks that the UI needs to perform on behalf of the
subscriber (or, possibly, of the CA) if we expect this additional field
to be a meaningful part of the protocol.

         --dkg