Subject: [Acme] Agreement integrity checksum

From: Michael Tandy <[email-masked]>
Date: Tue, 8 Dec 2015 23:15:05 +0000

Currently in the new-reg stage, the client POSTs a signed message, which
may contain the URI of a user agreement. If the content of the URL changes,
the results could be confusing - client software updating certificates
might post the agreement URL without the user having agreed to the revised
terms.

Is it worth adding an optional agreement integrity field? We could use a
format like this:-

"agreement": "
https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf",
"agreement-integrity":
"sha512-3Ys8QL9di54ggXIGBAS2RHr_W6cMurZPizhZihkQjwl3VG2dpXZYmsYZ0B7LG-tWlVE9-Hwp9hL3Mosvbr6lCA"

where the checksum is calculated like so:-

$ cat LE-SA-v1.0.1-July-27-2015.pdf  | openssl dgst -sha512 -binary |
openssl base64 -A | tr -- '+/' '-_' | tr -d '='
3Ys8QL9di54ggXIGBAS2RHr_W6cMurZPizhZihkQjwl3VG2dpXZYmsYZ0B7LG-tWlVE9-Hwp9hL3Mosvbr6lCA

That way if the CA updates the agreement without updating the URL, it'll be
clear which version the user has agreed to.

The main downsides to this are:

1. It complicates setting up the client; realistically, instead of
downloading, reading, and checksumming the user agreement most users will
simply copy-and-paste the configuration data from some website. Why add to
the boilerplate configuration, making the software harder to use for no
real benefit? We all know in reality enforcement of the user agreement will
be by certificate revocation, not by the courts; why add to the sound and
fury of threatening legalese when it signifies nothing?

2. Perhaps allowing CAs to update their user agreements without the user's
knowledge is preferable to CAs breaking users' certificate renewal scripts
without the user's knowledge. The latter could mean that a server that is
running fine and securely one day will become inaccessible the next day,
unable to renew its certificate without manual intervention to accept a new
agreement. Reliably sending e-mail is difficult due to spam filtering, so
many servers aren't set up to push notification to administrators when
problems like this arise.

3. The checksummed agreement could refer to other documents; those would
not be covered by the checksum, so they could be changed. The only thing
preventing this is good faith on the part of the CAs. Given that we rely on
that, why not also rely on the good faith of the CA to update the URL when
they update the agreement?

4. If SHA-512 becomes obsolete, manual intervention may be required to
calculate a new checksum using an updated algorithm. In the event there
were multiple CAs and SHA-512 approached obsolescence, some CAs might only
accept SHA-512 while others didn't accept SHA-512. Clients might be
complicated with an ability to send multiple checksums, or to negotiate the
checksum algorithm.

5. This proposal is similar to http://www.w3.org/TR/SRI/ except this
proposal uses URL- and filename-safe base64 encoding (RFC4648 Section 5
with padding removed), only requires SHA-512, and doesn't explicitly
support multiple hash algorithms; whereas the SRI recommendation uses
traditional base64 encoding (RFC4648 Section 4); requires SHA-256, SHA-384
and SHA-512; and explicitly includes support for multiple hash algorithms.
Designs so similar yet incompatible may be a recipe for confusion; perhaps
additional differences should be introduced so the incompatible standards
are more obviously different.

6. People are already writing client software; maybe it's too late to
update the spec for such a marginal improvement.

What do you think?

---

From: Ángel González <[email-masked]>
Date: Wed, 09 Dec 2015 00:49:42 +0100

> update the spec for such a marginal improvement.

If we don't fix it now, a few years later we will not having changed it
now that it still is "not too late".

IMHO the spec should be updated to include that the client SHOULD
checksum the terms, keep a list of checksums the admin has agreed to,
and include them when agreeing.

The server MAY reject to provide certificates not including the
checksum. This way, we can delay rejecting those not-checksummed
requests for a few months if desired.

> 4. If SHA-512 becomes obsolete, manual intervention may be required
> to calculate a new checksum using an updated algorithm. In the event
> there were multiple CAs and SHA-512 approached obsolescence, some CAs
> might only accept SHA-512 while others didn't accept SHA-512. Clients
> might be complicated with an ability to send multiple checksums, or
> to negotiate the checksum algorithm.> 

Digests are already used at other places, and this is precisely not a
place sensitive to weak hashes. The client should be keeping a copy of
the files (either itself, mailing them to the sysadmin, etc.).

It's not a bad idea to specify the agreement-integrity as a dictionary
instead so in that future case, there's not problem of checksum
negotiation:
"agreement-integrity": {"sha512":
"3Ys8QL9di54ggXIGBAS2RHr_W6cMurZPizhZihkQjwl3VG2dpXZYmsYZ0B7LG-tWlVE9-
Hwp9hL3Mosvbr6lCA"}

> 2. Perhaps allowing CAs to update their user agreements without the
> user's knowledge is preferable to CAs breaking users' certificate
> renewal scripts without the user's knowledge. The latter could mean
> that a server that is running fine and securely one day will become
> inaccessible the next day, unable to renew its certificate without
> manual intervention to accept a new agreement. 

I hate sites that simply ask their users to "check their terms" as they
may change them unilaterally whenever they want. Often not even
bothering to provide version numbers / publication dates.

If it's really an agreement, the owner should be able to read and
ponderate it.

> Reliably sending e-mail is difficult due to spam filtering, so many
> servers aren't set up to push notification to administrators when

IMHO the client should also notify them on each renewal (*including*
the new certificate hash), which should encourage them to have it
properly configured.

---

From: Martin Thomson <[email-masked]>
Date: Wed, 9 Dec 2015 12:10:12 +1100

Two comments: Echoing an etag would be easier.  SHA-512 is overkill.

On 9 December 2015 at 10:15, Michael Tandy <[email-masked]> wrote:
> Currently in the new-reg stage, the client POSTs a signed message, which may
> contain the URI of a user agreement. If the content of the URL changes, the
> results could be confusing - client software updating certificates might
> post the agreement URL without the user having agreed to the revised terms.
>
> "agreement":
> "https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf",
> "agreement-integrity":
> the boilerplate configuration, making the software harder to use for no real
> benefit? We all know in reality enforcement of the user agreement will be by
> certificate revocation, not by the courts; why add to the sound and fury of
> threatening legalese when it signifies nothing?
>
> 3. The checksummed agreement could refer to other documents; those would not
> be covered by the checksum, so they could be changed. The only thing
> calculate a new checksum using an updated algorithm. In the event there were
> multiple CAs and SHA-512 approached obsolescence, some CAs might only accept
> SHA-512 while others didn't accept SHA-512. Clients might be complicated
> with an ability to send multiple checksums, or to negotiate the checksum
> algorithm.
>
> proposal uses URL- and filename-safe base64 encoding (RFC4648 Section 5 with
> padding removed), only requires SHA-512, and doesn't explicitly support
> multiple hash algorithms; whereas the SRI recommendation uses traditional
> base64 encoding (RFC4648 Section 4); requires SHA-256, SHA-384 and SHA-512;
> and explicitly includes support for multiple hash algorithms. Designs so
> similar yet incompatible may be a recipe for confusion; perhaps additional
> differences should be introduced so the incompatible standards are more
> obviously different.
>
> 6. People are already writing client software; maybe it's too late to update
> the spec for such a marginal improvement.
>
> What do you think?
>
> _______________________________________________
> Acme mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/acme
>

---

From: Niklas Keller <[email-masked]>
Date: Wed, 09 Dec 2015 08:56:27 +0000

How about just requiring that CAs update the URL on changes?

Let's Encrypt has a phrase in their agreement that further usage =
agreement to new terms to ensure that it doesn't break automation.

Martin Thomson <[email-masked]> schrieb am Mi., 9. Dez. 2015
02:10:

> may
> real
> user's
> not
> were
> with
> update

---

From: Niklas Keller <[email-masked]>
Date: Wed, 9 Dec 2015 13:57:26 +0100

There's also another issue: We need a standard error code for missing
agreements.

Regards, Niklas

---

From: Jacob Hoffman-Andrews <[email-masked]>
Date: Wed, 9 Dec 2015 10:57:15 -0800

> How about just requiring that CAs update the URL on changes?
I think this is the best, simplest approach.

---

From: Niklas Keller <[email-masked]>
Date: Tue, 15 Dec 2015 13:40:10 +0100

> I think this is the best, simplest approach.

I added a PR: https://github.com/ietf-wg-acme/acme/pull/52

---

From: Richard Barnes <[email-masked]>
Date: Tue, 15 Dec 2015 11:27:34 -0500

Thanks for the PR!  I agree that having an integrity hash is overkill,
and we should focus on advising CAs.

That said, the considerations for how CAs track agreements are very
much specific to each CA, so I'm hesitant to have MUST-level
requirements.  If you change it to a SHOULD, then I think we're good
to go.

---

From: Niklas Keller <[email-masked]>
Date: Wed, 16 Dec 2015 00:04:30 +0100

> requirements.  If you change it to a SHOULD, then I think we're good

I don't know whether it should be a MUST or SHOULD. It's not only
CAs that track agreement, but also the clients.

I'd like some additional way to signal to a client that continued usage
signifies acceptance of new terms for a given CA. Based on that the
client can check for the terms URI every time it starts and update the
registration if necessary. Otherwise it would have to error out in a hard
way breaking automation.

---

From: Richard Barnes <[email-masked]>
Date: Mon, 28 Dec 2015 14:18:49 -0500

Reading this PR again, I think I can live with it as is.  The caveat
"in a way that requires an agreement update" makes clear that this is
a way for CAs to trigger clients to update.  I went ahead and merged
it.  Thanks!