Status Clarifications #400

bifurcation · 2018-03-02T05:32:11Z

This PR attempts to add a lot more clarity to the "status" field on objects and how it evolves.

Adds a section describing the state transitions for the various object types. (This turns out to be a handy protocol summary as well)
Aligns the valid values in the "status" field definitions to the description in that section
Adds a "ready" state on orders to indicate when the order is ready to be finalized

Fixes #391
Fixes #397 (by showing why challenges need separate status)

Slightly beyond the scope of this PR, it might also be good to:

Define an "expired" status for autz, independent of "invalid"
Add a subsection of "Applying for Certificate Issuance" briefly noting / illustrating finalization

cpu

This is a great step towards making sure the status state changes are consistent & understandable.

I've flagged a few issues to address.

cpu · 2018-03-02T19:21:18Z

draft-ietf-acme-acme.md

+validate the challenge multiple times (see {{retrying-challenges}}).
+Likewise, client requests for retries do not cause a state change.
+If validation is successful, the challenge moves to the "valid"
+state; if there is an error, the challenge moves to the "invalid"


If there is an error, and the challenge moves to the "invalid" state, how does the client request retry? That seems like the primary reason you would want to retry and there isn't any information about how the server should handle failures during processing except to change out of processing.

I think "invalid" is a final decision. If the client wants another try, they'd need to create a new order.
Section 8.2 says that "the server SHOULD retry the query after some time".
Being unable to retry individual challenges might mean that some users will have a hard time acquiring a certificate. But then they should just fix their setup and respond to the challenge only when it will work.
I.e. I agree with the above change.

Yeah, what @joernheissler said. I had also been thinking of "invalid" as a final state. ISTM if you want to signal to the client that something has gone wrong and a retry is needed, there are basically three options:

Keep it in "processing" and add to the subproblems array

Move it to "invalid" and add to the subproblems array

Move it to a new "retry" state and add to the subproblems array

(1) is what we do now, and in case you can't tell by my phrasing here, I don't think we need any more signal than adding to the subproblems array. It seems like the only real argument for having a non-"processing" state is if find it distasteful to have "processing" with "error" populated, in which case I would propose we do (3) instead.

Ok. That sounds reasonable.

cpu · 2018-03-02T19:22:17Z

draft-ietf-acme-acme.md

+the challenges listed in the authorization transitions to the
+"valid" state, then the authorization also changes to the "valid"
+state.  If there is an error while the authorization is still
+pending (e.g., the authorization times out), then the authorizatoin


what does "the authorization times out" mean? I thought perhaps expiry but you mention that distinctly later in this paragraph.

*authorizatoin->authorization

cpu · 2018-03-02T19:23:23Z

draft-ietf-acme-acme.md

+pending (e.g., the authorization times out), then the authorizatoin
+transitions to the "invalid" state.  Once the authorization is in
+the valid state, it can expire ("invalid"), be deactivated by the
+client ("deactivated", see {{deactivating-an-authorization}}),


I think you're missing a connecting word here between deactivating and revoking.

or, revoked by the server ("revoked").

cpu · 2018-03-02T19:24:13Z

draft-ietf-acme-acme.md

+           |                       |
+           |                       |
+    Client |                Server |
+   deactiv.|                revoke |


nit: If you put the revocation case on the left fork I think you could fit the whole word "deactivated" on the right fork

cpu · 2018-03-02T19:28:17Z

draft-ietf-acme-acme.md

+"processing" state after the client submits a request to the order's
+"finalize" URL and the CA begins the issuance process for the
+certificate.  Once the certificate is issued, the order enters the
+"valid" state.  If a fatal error occurs at any of these stages, the


I think we should skip the word "fatal" here - we never define what a fatal error is versus a normal error. They're all just errors.

cpu · 2018-03-02T19:29:30Z

draft-ietf-acme-acme.md

+"finalize" URL and the CA begins the issuance process for the
+certificate.  Once the certificate is issued, the order enters the
+"valid" state.  If a fatal error occurs at any of these stages, the
+order moves to the "invalid" state.


This paragraph (& the flow chart) are also missing three ways that an order can become invalid:

One of its authorizations becomes invalid because it was deactivated

One of its authorizations becomes invalid because it expired

The order expires

One of its authorizations becomes invalid because it was deactivated

Or the authorization was revoked. :-)

We should probably say "If any of the authorizations changes to a state other than pending or valid, the order becomes invalid."

jsha · 2018-03-03T02:05:35Z

draft-ietf-acme-acme.md

+the challenges listed in the authorization transitions to the
+"valid" state, then the authorization also changes to the "valid"
+state.  If there is an error while the authorization is still
+pending (e.g., the authorization times out), then the authorizatoin


*authorizatoin->authorization

jsha · 2018-03-03T02:07:31Z

draft-ietf-acme-acme.md

+   +---------+---------+
+   |                   |
+   V                   V
+invalid <----------- valid


Let's treat expired as its own state, and note that it doesn't show up in the "status" field: the URL just starts to 404.

Also, there should be an arrow from pending to expired.

We don't require 404 when an authz expires:

If the client fails to complete the required actions before the "expires" time, then the server SHOULD change the status of the order to "invalid" and MAY delete the order resource.

So we shouldn't add any text here that would imply that 404 is necessary.

jsha · 2018-03-03T02:08:51Z

draft-ietf-acme-acme.md

+
+Order objects are created in the "pending" state.  Once all of the
+authorizations listed in the order object are in the "valid" state,
+the order transitions to the "ready" state.  The order moves to the


The "ready" state makes some sense but is a significant addition. I'm inclined to leave it out of this change, to more clearly separate "additional documentation" from "protocol changes".

Funny you should say that, because "expires" is also a new state :) This change is not large in spec terms -- this PR is all it needs. It doesn't seem like it should be a huge change for implementations either.

jsha · 2018-03-03T02:38:54Z

draft-ietf-acme-acme.md

+"finalize" URL and the CA begins the issuance process for the
+certificate.  Once the certificate is issued, the order enters the
+"valid" state.  If a fatal error occurs at any of these stages, the
+order moves to the "invalid" state.


One of its authorizations becomes invalid because it was deactivated

Or the authorization was revoked. :-)

We should probably say "If any of the authorizations changes to a state other than pending or valid, the order becomes invalid."

cpu

This is looking better after the last few rounds of feedback were applied.

One oversight that still remains is in the "Applying for Certificate Issuance" section.

There is a section about how the status of the order post-finalization tells the client what to do. It covers "invalid", "pending", "processing" and "valid" - I think it needs to be updated with "ready". Similarly the existing text for "processing" doesn't match this new state model.

cpu

Two small pieces of feedback

cpu · 2018-03-05T22:11:35Z

draft-ietf-acme-acme.md

-  is in the process of generating the certificate.  Retry after the time given
-  in the "Retry-After" header field of the response, if any.
+* "ready": The server agrees that the requirements have been
+  fulfilled, and is awaiting on finalization.  Submit a finalization


nit: "and is awaiting on finalization" -> "and is awaiting finalization".

cpu · 2018-03-05T22:13:03Z

draft-ietf-acme-acme.md

+  fulfilled, and is awaiting on finalization.  Submit a finalization
+  request.
+
+* "processing": The certificate is being issued.  Retry after the


"Retry" in this case might need to be disambiguated slightly, what about "Poll the order again after the ... " ?

jsha · 2018-03-05T22:30:34Z

I'm fine accepting the "ready" state based on the above, although Let's Encrypt won't have it implemented by v2 launch time. I think that's fine. One tiny bit of further clarification: I was thinking of "expired" as a meta-state that is not necessarily reflected in the status field. I think we can just add a sentence saying something like "objects in an expired state may simply return 404."

bifurcation added 2 commits March 2, 2018 00:21

Add a section describing state transitions

b057051

Align status field values with description

9a219ae

bifurcation requested review from cpu and jsha March 2, 2018 05:35

Retry clarification

bfaf423

cpu suggested changes Mar 2, 2018

View reviewed changes

jsha suggested changes Mar 3, 2018

View reviewed changes

bifurcation added 3 commits March 4, 2018 22:34

@cpu comments

819909e

Merge branch 'master' into status

0918cc7

@jsha comments

fa8ba15

cpu suggested changes Mar 5, 2018

View reviewed changes

Clarify 'Applying for Certificate Issuance' section

111f566

cpu suggested changes Mar 5, 2018

View reviewed changes

Typos

3734a82

cpu approved these changes Mar 5, 2018

View reviewed changes

Clarify that some states may be transient

6099d4f

jsha approved these changes Mar 5, 2018

View reviewed changes

bifurcation merged commit 5da11f7 into master Mar 5, 2018

jsha deleted the status branch March 6, 2018 00:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Status Clarifications #400

Status Clarifications #400

bifurcation commented Mar 2, 2018

cpu left a comment

cpu Mar 2, 2018 •

edited

joernheissler Mar 4, 2018

bifurcation Mar 5, 2018

cpu Mar 5, 2018

cpu Mar 2, 2018

jsha Mar 3, 2018

cpu Mar 2, 2018

cpu Mar 2, 2018

cpu Mar 2, 2018

cpu Mar 2, 2018

jsha Mar 3, 2018

jsha Mar 3, 2018

jsha Mar 3, 2018

bifurcation Mar 5, 2018

jsha Mar 3, 2018

bifurcation Mar 5, 2018

jsha Mar 3, 2018

cpu left a comment

cpu left a comment

cpu Mar 5, 2018

cpu Mar 5, 2018

jsha commented Mar 5, 2018

Status Clarifications #400

Status Clarifications #400

Conversation

bifurcation commented Mar 2, 2018

cpu left a comment

Choose a reason for hiding this comment

cpu Mar 2, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cpu left a comment

Choose a reason for hiding this comment

cpu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jsha commented Mar 5, 2018

cpu Mar 2, 2018 •

edited