RESTification

[bifurcation]

This PR closes #23. It updates the overall flow of the protocol to make better use of HTTP. There are no changes to the validation challenges. In case it helps, there's a side-by-side comparison of protocol messages here:

http://www.ipv.sx/tmp/restification.html

[pde]

We're planning to do a line-by-line review of this PR this week.

[martinthomson]

s/reference by an A/referenced by an A/

[jsha]

Can you clarify here what an 'initial' authorization object means, versus a regular authorization object?

[jsha]

All done with my review. The two big items that I think need fixing are:

• GET requests cannot be signed using our current JWS scheme. We should do one of:
  1. Define all GET resources as fully public and deal with what that means for the protocol, or
  2. Define a way for GET requests to be signed by an account key, or
  3. Turn any non-public GET resources back into POSTs, even if it is a slight divergence from REST.
• Using JSON merge patch from the client to modify a security-critical data structure is inherently risky. We should go back to an explicit ChallengeResponse object.

[pde]

@jsha on GET requests, I'd vote for option iii. It's both cleanest and safest to wrap everything in JWS signatures.

[martinthomson]

Are there any resources that are confidential and need to respond to a GET? My preference would be to try to find a place where all the GET resources don't need confidentiality: i.e., the first option.

I don't think that a capability URL is bad for information that is not especially sensitive, like whether domain X has a valid authorization. For those resources that need GET, is there a case in the threat model that supports the need for any confidentiality protection (i.e., authorization based on account key)?

[jsha]

@martinthomson: It seems like the authorization resource is currently in an in-between state. It was designed as an resource that would be confidential by the nature of the protocol. This branch makes it non-confidential because that approach fits the REST model better, but I think has not fully updated the model to reflect that. For instance, as you pointed out, it currently includes a 'contact' field, which should be confidential.

I think it will be much easier to analyze the security of the system if we adopt clear security boundaries, i.e.:

• authenticated / unauthenticated
• confidential / public

I think introducing a new authentication type (capability URLs) and a new confidentiality level (not especially sensitive) is going to make our jobs a lot harder, and potentially lead to implementation mistakes.

As far as I can tell, the main reason to introduce the new authentication type for Authorization resources is to allow them to be fetched via GET during polling, and therefore match REST semantics better. I like the REST model, but when it increases complexity rather than reducing it, I think we should modify the model a little bit.

So I prefer item (iii) in my previous comment. It also happens to be the smallest departure from the existing spec, which will help us with the schedule.

[jdkasten]

This data structure change makes it difficult to issue challenges of the same type. This isn't a problem given the current challenges and as ACME's goal is DV. However, if there is a challenge someday where different parameters to the challenge prove different components of the authorization we will be stuck with a hack (some form of compound challenge or defining multiple challenges of the same type with different names). This probably doesn't justify the complication involved with using a list and indices, but is something to keep in mind.

[jsha]

This is a good point. For instance, in the future we will want to issue wildcard certificates. You can imagine wanting to do two different SimpleHTTPS challenges to two different random subdomains, to verify full control of the domain.

Both this and the previous list/indices approach also introduce an awkward non-locality in evaluating the data structure. Proposal: Snap the pointers. Instead of challenges, and combinations, have a single field challengeSets, which is an array of arrays of challenges. This may mean a small amount of duplication, but I think it simplifies the structure.

[bifurcation]

We had a call about this (me, martinthomson, jsha, pde, jdkasten, et al.). Besides the obvious typo fixes, our resolutions came to the following major changes:

• Sensitive information from Authorizations is moved to Registration objects, and a separate registration transaction updates them.
• Challenges will be their own resources, to which responses will be POSTed.

There are also some more minor structural changes to authorizations, and I'm also planning to add more link relations to tie things together.

[jsha]

Confirming my understanding: Link relations are expressed in headers, so they can't be JWS-signed, right? But responses from the server are never JWS signed and are secured instead by HTTPS?

Also, we should probably add the constraint: "All link relations must be specified relative to the current scheme, host, and port. The client MUST reject responses that include a link relation that specifies a scheme, host, or port."

[martinthomson]

I think that Richard needs to clean this up. A link relation is a link in the 5988 sense. It doesn't matter where it appears, it can still be a link relation. The header field vs. body distinction doesn't read on the subject.

[jsha]

Done with today's round of reviews. I think we're pretty close to merging.

@martinthomson, as a separate task, can you document the decision to go with a REST architecture? It was made before I started dedicating a lot of time to the project, and it deeply shapes a lot of our architectural decisions reflected in this doc, so it would be great to have a section in the doc describing why we use it.

[martinthomson]

@jsha, that's @bifurcation's doing entirely.

All I ever said was: "If you are using HTTP, might as well do it properly". I just noted a few points where some of the basic principles seem to fit. Like how having different identifiers for each of the "things" helps. If you wanted to go all out, there's plenty more to do, though at some point you realize that you're off the reservation. Usually at the point where you are delving into signatures over HTTP messages.

It seems to me that this is an improvement, and not just because it's had a lot more attention paid to it. Do you have specific architectural concerns that this redesign doesn't address? Or concerns that it raises? I think that we covered the confidentiality concerns.

[jsha]

@martinthomson: My main concern was, as you mentioned, the confidentiality issue. I agree that we've resolved them, but there are a couple of additional places they popped up in my latest review (registration resources, refresh certificate resources). We also wound up resolving those. But I still don't 100% understand why we switched some requests from POSTs to GETs in the first place. I'm not requesting that we revise that aspect of the spec further at this late date, but I think documenting the choice would be very helpful to future reviewers.

[martinthomson]

GET has robustness advantages over POST. If the GET fails, any layer of the stack can automatically retry it. In this specific case, it also makes it easier to distribute certificates using a CDN. Many CDNs won't handle "application logic", but all of them are happy to take a GET request.

[frasertweedale]

Why? What is the reason behind this?

I consider this to be an unreasonable imposition, for the following reason:

Suppose a certain JOSE library serialises a JWS with a single signature
using the General JWS JSON Serialization Syntax. That library cannot
be used with ACME.

According to the JWS draft there is no requirement or recommendation for an implementation
to serialise a single-signature JWS using the Flattened syntax, nor is there
a requirement or recommendation to provide users a knob to control how to deal with this
ambiguous case.

So if there is no important reason to have this requirement in ACME,
please remove it.