Subject: [Acme] Use of "shortly" in normative language of Section 7.4, Applying for Certificate Issuance

From: Zach Shepherd <[email-masked]>
Date: Wed, 22 Mar 2017 05:14:36 +0000

The following feedback is based on 8010a31 (current HEAD of master).

Section 7.4, Applying for Certificate Issuance, states "The server MUST issue the requested certificate and update the order resource with a URL for the certificate shortly after the client has fulfilled the server’s requirements."

Per RFC 2119 Section 6, the imperative MUST should be used with care and sparingly.

The use of "shortly" in the above sentence is imprecise. It is not possible for a server author to know, with confidence, that they are adhering to this requirement. It is not possible fore a client author to make design or implementation decisions based on this requirement.

I would propose either:
a) Replacing "shortly" with a more precise expectation.
b) Replacing "MUST" with "should".

I believe there are advantages for setting expectations as to the turn-around time for certificate issuance and would therefore prefer option (a), assuming agreement could be reached on more precise language.

Regards,
Zach Shepherd

---

From: Daniel McCarney <[email-masked]>
Date: Wed, 22 Mar 2017 12:39:22 -0400

Hi Zach,

For background I think this MUST originated out of this thread:
https://mailarchive.ietf.org/arch/msg/acme/0lVmGl8e-rmSH0x7ycDW5dj6GAY

I would prefer option A) as well. It seems better to clear up the
non-normative language than to step backwards to a place where proactive
issuance may or may not happen without a clear signalling to the client of
which a server will do.

I think the use of "shortly" here is to allow the server some grace to
determine that the order is completed and issuance can be performed.
Perhaps we could change the language to say "The server MUST issue the
requested certificate and update the order resource with a URL for the
certificate after it has determined the client has fulfilled the server's
requirements" and not impose any specific mention of the time between the
client completing the challenges and the server noticing. Thoughts?

On Wed, Mar 22, 2017 at 1:14 AM, Zach Shepherd <[email-masked]> wrote:

> Section 7.4, Applying for Certificate Issuance, states "The server MUST
> issue the requested certificate and update the order resource with a URL
> for the certificate shortly after the client has fulfilled the server’s
> requirements."
>
> The use of "shortly" in the above sentence is imprecise. It is not
> possible for a server author to know, with confidence, that they are
> adhering to this requirement. It is not possible fore a client author to
> make design or implementation decisions based on this requirement.
>
> I would propose either:
> I believe there are advantages for setting expectations as to the
> turn-around time for certificate issuance and would therefore prefer option
> (a), assuming agreement could be reached on more precise language.
>
> Regards,
> Zach Shepherd
>
>
> _______________________________________________
> Acme mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/acme
>
>

---

From: Jacob Hoffman-Andrews <[email-masked]>
Date: Wed, 22 Mar 2017 10:13:51 -0700

We could say "MUST begin the issuance process"

The main things on my mind that could delay issuance slightly:
 - Submitting to CT
 - Checking CAA
 - Internal queuing for available capacity
 - Manual vetting

I think "MUST begin" covers for all of those, while allowing some
vagueness as to how long they will take.

On 03/22/2017 09:39 AM, Daniel McCarney wrote:
> Hi Zach,
>
> For background I think this MUST originated out of this
> thread: https://mailarchive.ietf.org/arch/msg/acme/0lVmGl8e-rmSH0x7ycDW5dj6GAY 
>
> non-normative language than to step backwards to a place where
> proactive issuance may or may not happen without a clear signalling to
> the client of which a server will do.
>
> certificate after it has determined the client has fulfilled the
> server's requirements" and not impose any specific mention of the time
> between the client completing the challenges and the server noticing.
> Thoughts?
>
> On Wed, Mar 22, 2017 at 1:14 AM, Zach Shepherd <[email-masked]
> <mailto:[email-masked]>> wrote:
>
>     Section 7.4, Applying for Certificate Issuance, states "The server
>     MUST issue the requested certificate and update the order resource
>     with a URL for the certificate shortly after the client has
>     fulfilled the server’s requirements."
>
>     possible for a server author to know, with confidence, that they
>     are adhering to this requirement. It is not possible fore a client
>     author to make design or implementation decisions based on this
>     requirement.
>
>     I would propose either:
>     turn-around time for certificate issuance and would therefore
>     prefer option (a), assuming agreement could be reached on more
>     precise language.
>
>     Regards,
>     Zach Shepherd
>
>     [email-masked] <mailto:[email-masked]>
>     <https://www.ietf.org/mailman/listinfo/acme>
>
>
>
>

---

From: Zach Shepherd <[email-masked]>
Date: Wed, 22 Mar 2017 18:44:44 +0000

I think "MUST begin the issuance process" addresses my concerns and is in line with the discussions around preferring "proactive" issuance.

________________________________
From: Jacob Hoffman-Andrews <[email-masked]>
Sent: Wednesday, March 22, 2017 10:13 AM
To: [email-masked]; Zach Shepherd
Cc: [email-masked]
Subject: Re: [Acme] Use of "shortly" in normative language of Section 7.4, Applying for Certificate Issuance

I think "MUST begin" covers for all of those, while allowing some vagueness as to how long they will take.

For background I think this MUST originated out of this thread: https://mailarchive.ietf.org/arch/msg/acme/0lVmGl8e-rmSH0x7ycDW5dj6GAY<https://urldefense.proofpoint.com/v2/url?u=https-3A__mailarchive.ietf.org_arch_msg_acme_0lVmGl8e-2DrmSH0x7ycDW5dj6GAY&d=DwMD-g&c=uilaK90D4TOVoH58JNXRgQ&r=Z9jmRNJFc0_mrYgZ7k4FWDuC1AsqA1UJKUYIM6ZnnNk&m=IVegRoNI7i9NKYEzqcMfeK47xFPnnNPelVyrANn-ApQ&s=sangkBdLNhQ_KuubT2WqqFvFfy9gCNFcbWH5_NAutl4&e=>

I would prefer option A) as well. It seems better to clear up the non-normative language than to step backwards to a place where proactive issuance may or may not happen without a clear signalling to the client of which a server will do.

I think the use of "shortly" here is to allow the server some grace to determine that the order is completed and issuance can be performed.
Perhaps we could change the language to say "The server MUST issue the requested certificate and update the order resource with a URL for the certificate after it has determined the client has fulfilled the server's requirements" and not impose any specific mention of the time between the client completing the challenges and the server noticing. Thoughts?

On Wed, Mar 22, 2017 at 1:14 AM, Zach Shepherd <[email-masked]<mailto:[email-masked]>> wrote:
The following feedback is based on 8010a31 (current HEAD of master).

I would propose either:

Regards,
Zach Shepherd

_______________________________________________
Acme mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/acme<https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_acme&d=DwMD-g&c=uilaK90D4TOVoH58JNXRgQ&r=Z9jmRNJFc0_mrYgZ7k4FWDuC1AsqA1UJKUYIM6ZnnNk&m=IVegRoNI7i9NKYEzqcMfeK47xFPnnNPelVyrANn-ApQ&s=0aKjhUeYQGvrvF_50ZzCMUIEt6uUg18yDmXhGuk5KRY&e=>

_______________________________________________
Acme mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/acme<https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_acme&d=DwMD-g&c=uilaK90D4TOVoH58JNXRgQ&r=Z9jmRNJFc0_mrYgZ7k4FWDuC1AsqA1UJKUYIM6ZnnNk&m=IVegRoNI7i9NKYEzqcMfeK47xFPnnNPelVyrANn-ApQ&s=0aKjhUeYQGvrvF_50ZzCMUIEt6uUg18yDmXhGuk5KRY&e=>

---

From: Daniel McCarney <[email-masked]>
Date: Wed, 22 Mar 2017 14:54:58 -0400

+1 for "MUST begin the issuance process" - thanks for the suggestion Jacob.

On Wed, Mar 22, 2017 at 2:44 PM, Zach Shepherd <[email-masked]> wrote:

> I think "MUST begin the issuance process" addresses my concerns and is in
> line with the discussions around preferring "proactive" issuance.
>
> ------------------------------
> *From:* Jacob Hoffman-Andrews <[email-masked]>
> *Sent:* Wednesday, March 22, 2017 10:13 AM
> *To:* [email-masked]; Zach Shepherd
> *Cc:* [email-masked]
> *Subject:* Re: [Acme] Use of "shortly" in normative language of Section
> 7.4, Applying for Certificate Issuance
>
> <https://urldefense.proofpoint.com/v2/url?u=https-3A__mailarchive.ietf.org_arch_msg_acme_0lVmGl8e-2DrmSH0x7ycDW5dj6GAY&d=DwMD-g&c=uilaK90D4TOVoH58JNXRgQ&r=Z9jmRNJFc0_mrYgZ7k4FWDuC1AsqA1UJKUYIM6ZnnNk&m=IVegRoNI7i9NKYEzqcMfeK47xFPnnNPelVyrANn-ApQ&s=sangkBdLNhQ_KuubT2WqqFvFfy9gCNFcbWH5_NAutl4&e=>
>
>
>> <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_acme&d=DwMD-g&c=uilaK90D4TOVoH58JNXRgQ&r=Z9jmRNJFc0_mrYgZ7k4FWDuC1AsqA1UJKUYIM6ZnnNk&m=IVegRoNI7i9NKYEzqcMfeK47xFPnnNPelVyrANn-ApQ&s=0aKjhUeYQGvrvF_50ZzCMUIEt6uUg18yDmXhGuk5KRY&e=>
>>
>>
>
>
> Acme mailing [email-masked]://www.ietf.org/mailman/listinfo/acme <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_acme&d=DwMD-g&c=uilaK90D4TOVoH58JNXRgQ&r=Z9jmRNJFc0_mrYgZ7k4FWDuC1AsqA1UJKUYIM6ZnnNk&m=IVegRoNI7i9NKYEzqcMfeK47xFPnnNPelVyrANn-ApQ&s=0aKjhUeYQGvrvF_50ZzCMUIEt6uUg18yDmXhGuk5KRY&e=>
>
>
>

---

From: Zach Shepherd <[email-masked]>
Date: Thu, 23 Mar 2017 18:41:23 +0000

I've submitted a PR for this change: https://github.com/ietf-wg-acme/acme/pull/286

Regards,

Zach

________________________________
From: Daniel McCarney <[email-masked]>
Sent: Wednesday, March 22, 2017 11:54 AM
To: Zach Shepherd
Cc: Jacob Hoffman-Andrews; [email-masked]
Subject: Re: [Acme] Use of "shortly" in normative language of Section 7.4, Applying for Certificate Issuance

On Wed, Mar 22, 2017 at 2:44 PM, Zach Shepherd <[email-masked]<mailto:[email-masked]>> wrote:

________________________________
From: Jacob Hoffman-Andrews <[email-masked]<mailto:[email-masked]>>
Sent: Wednesday, March 22, 2017 10:13 AM
To: [email-masked]<mailto:[email-masked]>; Zach Shepherd
Cc: [email-masked]<mailto:[email-masked]>
Subject: Re: [Acme] Use of "shortly" in normative language of Section 7.4, Applying for Certificate Issuance

I would propose either:

Regards,
Zach Shepherd