Hi folks,
On August 14th, 2018 we will be deploying a backwards compatibility breaking change for the staging environment ACME v2 Key Rollover endpoint. This change is scheduled to be promoted to the production environment the following week on August 23rd. If your ACME v2 compatible client has implemented the ACME key rollover feature you will need to update your implementation according to the draft-13 specification.
Edit: This change is now live in both the staging and production environment.
Background
Between draft-ietf-acme-12 and draft-ietf-acme-13 a backwards compatibility breaking change was introduced in the Account Key Rollover feature of the draft ACME protocol. Let’s Encrypt’s V2 API account key rollover support was implemented prior to draft-13 and we are now switching to the new draft-13 behaviour.
In draft-12 Section 7.3.6 the payload of the inner JWS of a key rollover request is described to carry an "account" field with an account URL, and a "newkey" field with the new JWK intended to be used as the new account key.
In draft-13 Section 7.3.6 the payload of the inner JWS of a key rollover request was changed to carry an "account" field with an account URL, and an "oldKey" field with the old JWK that is the current account key.
It is unnecessary to specify the new key in the inner JWS body because it is already present in the embedded JWK that authenticates the inner JWS. Specifying the old key in the inner JWS body ensures that the old key has signed the new key (by way of the outer JWS encapsulating the inner JWS) and that the new key has signed the old key (by way of the inner JWS encapsulating the old JWK in its body).
Client implementation advice
@rmbolger helpfully suggested a strategy for client developers to allow preparing a release immediately that will support both the draft-12 key rollover presently in production and the new draft-13 key rollover soon to be in staging by sending both the "oldKey" and "newKey" fields in all key rollover requests. Production will ignore the new "oldKey" field for legacy requests and staging will ignore the legacy "newKey" field for draft-13 requests. Once both staging and production are updated a subsequent release can cease sending the "newKey" field.
Future changes
The ACME draft protocol is approaching final RFC status and we hope that this will be one of the last backwards compatibility breaking changes. Thank you to everyone for your patience as we continue to iterate on the draft protocol standard.