letsencrypt
/
boulder
mirror of https://github.com/letsencrypt/boulder.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update acme-divergences documentation for draft-06 & draft-07 (#2845) 

The IETF working group has published a [draft-06](https://tools.ietf.org/html/draft-ietf-acme-acme-07) and [draft-07 revision of ACME](https://tools.ietf.org/html/draft-ietf-acme-acme-07). This PR updates the Boulder `docs/acme-divergences.md` documentation for both drafts. Primarily this meant updating section numbers and links. 

Notable updates:
* Added "index" directory Link divergence
* Removed divergence for "existing" field of authorizations - this was removed from the spec so it isn't a divergence anymore \o/
* Added divergence for the Boulder certificates endpoint not respecting client `Accept` headers and using the `application/pkix-cert` content type in responses vs `application/pem-certificate-chain`
* Added divergence for `unsupportedContact` and `accountDoesNotExist` errors.
* Added divergence for the `only-return-existing` field.
* Added divergence for retrying challenges
* Removed "meta" directory divergence since Boulder supports this now

Resolves #2825
This commit is contained in:
Daniel McCarney 2017-07-05 15:24:12 -04:00 committed by Jacob Hoffman-Andrews
parent f710e574b3
commit bbd0587440
1 changed files with 34 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
docs/acme-divergences.md
View File

@ -4,33 +4,35 @@ While Boulder attempts to implement the ACME specification as strictly as possib
This document details these differences, since ACME is not yet finalized it will be updated as numbered drafts are published.
Current draft: [`draft-ietf-acme-acme-05`](https://tools.ietf.org/html/draft-ietf-acme-acme-05).
Current draft: [`draft-ietf-acme-acme-07`](https://tools.ietf.org/html/draft-ietf-acme-acme-07).
## [Section 5](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-5)
## [Section 6](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-6)
Boulder does not implement the [general JWS syntax](https://tools.ietf.org/html/rfc7515#page-20), but only accepts the [flattened syntax](https://tools.ietf.org/html/rfc7515#page-21).
## [Section 5.2](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-5.2)
## [Section 6.2](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-6.2)
Boulder enforces the presence of the `jwk` field in JWS objects, and does not support the `kid` field.
## [Section 5.4.1](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-5.4.1)
## [Section 6.3.1](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-6.3.1)
Boulder does not use the `url` field from the JWS protected resource. Instead Boulder will validate the `resource` field from the JWS payload matches the resource being requested. Boulder implements the resource types described in [draft-ietf-acme-02 Section 6.1](https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.1) plus the additional "KeyChange" resource. Boulder verifies the `resource` field contains the `/directory` URI for the requested resource.
## [Section 5.6.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-5.6)
## [Section 6.5](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-6.5)
Boulder does not provide a `Retry-After` header when a user hits a rate-limit, nor does it provide `Link` headers to further documentation on rate-limiting.
## [Section 5.7.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-5.7)
## [Section 6.6](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-6.6)
Boulder doesn't return errors under the `urn:ietf:params:acme:error:` namespace but instead uses the `urn:acme:error:` namespace from [draft-ietf-acme-01 Section 5.4](https://tools.ietf.org/html/draft-ietf-acme-acme-01#section-5.4).
Boulder uses `invalidEmail` in place of the error `invalidContact` defined in [draft-ietf-acme-01 Section 5.4](https://tools.ietf.org/html/draft-ietf-acme-acme-01#section-5.4).
Boulder does not implement the `unsupportedContact` and `accountDoesNotExist` errors.
Boulder does not implement the `caa` and `dnssec` errors.
## [Section 6.1.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-6.1)
## [Section 7.1](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.1)
Boulder does not implement the `new-order` resource. Instead of `new-order` Boulder implements the `new-cert` resource that is defined in [draft-ietf-acme-02 Section 6.5](https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.5).
@ -44,27 +46,25 @@ new-authz to new-cert, as specified in
these links are not provided in the latest draft, and clients should use URLs
from the directory instead.
## [Section 6.1.1.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-6.1.1)
Boulder does not provide the "index" link relation pointing at the directory URL.
Boulder does not implement the `meta` field returned by the `directory` endpoint.
## [Section 6.1.2.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-6.1.2)
## [Section 7.1.2](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.1.2)
Boulder does not implement the `terms-of-service-agreed` or `orders` fields in the registration object (nor the endpoints the latter links to).
## [Section 6.1.3.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-6.1.3)
## [Section 7.1.3](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.1.3)
Boulder does not implement orders, instead it implements the `new-cert` flow from [draft-ietf-acme-02 Section 6.5](https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.5). Instead of authorizations in the order response, Boulder currently uses authorizations that are created using the `new-authz` flow from [draft-ietf-acme-02 Section 6.4](https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.4).
## [Section 6.1.4.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-6.1.4)
## [Section 7.1.4](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.1.4)
Boulder does not implement the `scope` field in authorization objects.
## [Section 6.2.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-6.2)
## [Section 7.2](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.2)
Boulder doesn't implement the `new-nonce` endpoint, instead it responds to `HEAD` requests with a valid `Replay-Nonce` header per [draft-ietf-acme-03 Section 5.4](https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-5.4).
## [Section 6.3.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-6.3)
## [Section 7.3](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.3)
Boulder only allows `mailto` URIs in the registrations `contact` list.
@ -72,32 +72,42 @@ Boulder uses an HTTP status code 409 (Conflict) response for an already existing
Boulder does not return the `status` field.
## [Section 6.3.3.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-6.3.3)
Boulder does not implement the `only-return-existing` field.
## [Section 7.3.1](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.3.1)
Boulder does not implement the `only-return-existing` behaviour and will always create a new account if an account for the given key does not exist.
## [Section 7.3.6](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.3.6)
Boulder implements draft-05 style key roll-over with a few divergences. Since Boulder doesn't currently use the registration URL to identify users we do not check for that field in the JWS protected headers but do check for it in the inner payload. Boulder also requires the outer JWS payload contains the `"resource": "key-change"` field.
## [Section 6.4.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-6.4)
## [Section 7.4](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.4)
Boulder does not implement orders, instead it implements the `new-cert` flow from [draft-ietf-acme-02 Section 6.5](https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.5). Instead of authorizations in the order response, Boulder currently uses authorizations that are created using the `new-authz` flow from [draft-ietf-acme-02 Section 6.4](https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.4). Certificates are not proactively issued, a user must request issuance via the `new-cert` endpoint instead of assuming a certificate will be created once all required authorizations are validated.
## [Section 6.4.1.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-6.4.1)
## [Section 7.4.2](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.4.2)
Boulder ignores the `existing` field in authorization request objects.
Boulder does not process `Accept` headers for `Content-Type` negotiation when retrieving certificates. Boulder returns certificates with the `Content-Type` value `application/pkix-cert` instead of `application/pem-certificate-chain`.
## [Section 7.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-7)
## [Section 7.5](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.5)
Boulder returns an `uri` instead of an `url` field in challenge objects.
Boulder uses an HTTP status code 202 (Accepted) response for correct challenge responses instead of 200 (OK) as defined in [Section 6.1](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-6.1).
Boulder uses an HTTP status code 202 (Accepted) response for correct challenge responses instead of 200 (OK) as defined in [Section 7.1](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-7.1).
## [Section 7.3.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-7.3)
## [Section 8.2](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-8.2)
Boulder does not implement the ability to retry challenges or the `Retry-After` header.
## [Section 8.4](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-8.4)
Boulder implements `tls-sni-01` from [draft-ietf-acme-01 Section 7.3](https://tools.ietf.org/html/draft-ietf-acme-acme-01#section-7.3) instead of the `tls-sni-02` validation method.
## [Section 7.5.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-7.5)
## [Section 8.6](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-8.6)
Boulder does not implement the `oob-01` validation method.
## [Section 8.5.](https://tools.ietf.org/html/draft-ietf-acme-acme-05#section-8.5)
## [Section 9.5](https://tools.ietf.org/html/draft-ietf-acme-acme-07#section-9.6)
Boulder uses the `urn:acme:` namespace from [draft-ietf-acme-01 Section 5.4](https://tools.ietf.org/html/draft-ietf-acme-acme-01#section-5.4) for errors instead of `urn:ietf:params:acme:`.