Subject: [Acme] AD Review: draft-ietf-acme-star-delegation-04

From: Roman Danyliw <[email-masked]>
Date: Thu, 4 Feb 2021 22:50:32 +0000

Hi!

I did an AD review of draft-ietf-acme-star-delegation-04.  Thanks for this work to apply the STAR profile (rfc8739).  Below are my comments.  There are a number of editorial clarifications proposed below.  The item that likely needs some discussion is the syntax of the CSR template.

** Idnit:
  ** Obsolete normative reference: RFC 6844 (Obsoleted by RFC 8659)

  == Outdated reference: A later version (-04) exists of
     draft-ietf-cdni-interfaces-https-delegation-03

  -- Unexpected draft version: The latest known version of 
     draft-ietf-stir-cert-delegation is -02, but you're referring to -03.

** Section 1.  Editorial.  Missing preposition.
OLD
   This document describes a profile of the ACME protocol [RFC8555] that
   allows the NDC to request the IdO, acting as a profiled ACME server,
   a certificate for a delegated identity
NEW
   This document describes a profile of the ACME protocol [RFC8555] that
   allows the NDC to request from the IdO, acting as a profiled ACME server,
   a certificate for a delegated identity

** Section 2.2.  Editorial.  Recommend symmetry in naming of the orders and being explicit on the order in question.
-- second from last bullet.  s/reflected in the NDC order/reflected in Order 1 (i.e., the NDC Order)/
-- last bullet.  s/moves its state to "valid"/moves the Order 1 state to "valid"/

** Section 2.2. Should the buffering requirement for the CSR be normative - s/The IdO must buffer/The IdO MUST buffer/

** Section 2.2.  Per "[No identify validation]", what is meant by that?

** Section 2.3.1.  Editorial.  s/The IdO can delegate multiple names through each NDC/The IdO can delegate multiple names to a NDC/

** Section 2.3.1.  Are there any constraints to what the delegation URLs could point to?

** Section 2.3.1.  Per "The value of this attribute is the URL pointing to the delegation configuration    object that is to be used for this certificate request", what is the error handling if the delegation attribute doesn't point to a URL found in the delegations URL list?  

** Section 2.3.2.  It might be worth pointing out the obvious when clarifying the properties of the Order objects such as:
-- That the value field will be the delegated name

-- The expected symmetry in field values between NDC-generated order object and the one made by the IdO

** Section 2.3.2.  Per "When the validation of the identifiers has been successfully completed ...", it would be useful to clarify who is doing the validation and when.  Figure 1 suggests that there is only a validation process between IdO client and CA server.  However, wouldn't the IdO server be checking the identifiers submitted by the NDC client too (prior to passing them to the CA server too?

** Section 2.3.2 and 2.3.3.  I didn't  understand the titles used to organize of content -- "Order Object on the NDC-IdO side" vs. "IdO-CA side".  They didn't follow the clear convention introduced by Figure 1 of NDC client, IdO client, IdO server and CA server.  Additionally, Section 2.3.2 discusses behavior which seems to be IdO client-to-CA Server (which doesn't seem like "NDC IdO side").  Additionally, Section 2.3.3. seems to be describing the requirements that correspond to construction of the order sent to the CA which is also covered at the end of Section 2.3.2.

** Section 2.4.  Per "The authors believe that this is a very minor security risk", it would be worth explicitly explaining that position (and not framed as the belief of the authors)

** Section 2.5.  This section introduces a new architectural element, ACME Delegation server, but doesn't define it.  Simply referencing the use cases in Section 4.1.2 isn't enough as this section doesn't even use those words ("Delegation server").

** Section 2.5.  Per "The "Location" header must be rewritten", it would be useful to describe the new target.

** Section 3.1.  There are some challenges with the template syntax.
-- Where is the normative format for the syntax?  Section 3.1 points to Appendix B which lists JSON schema whose format is specified "draft 7 of JSON Schema, which may not be the latest version of the corresponding Internet Draft [I-D.handrews-json-schema] at the time of publication".  As far as I can tell "draft 7 of JSON Schema" seems to resolve to https://json-schema.org/specification-links.html which points back to draft-handrews-json-schema.  This draft appears to be an expired, individual draft codifying.  This ambiguity and lack of stable reference is problematic.

-- Accepting the Json schema as is, there is no annotation on the fields.  The field names very much look like X.509 fields but the text provides no guidance on how they should be interpreted to create a CSR beyond explaining "**", "*" and what is mandatory.  I would have expected a field mapping but the text explicitly says "The mapping between X.509 CSR fields and the template will be defined in a future revision of this document.".  

** Section 3.1.
The NDC MUST NOT include in the CSR any fields that are not specified
   in the template, and in particular MUST NOT add any extensions unless
   those were previously negotiated out of band with the IdO.

These two normative clauses seem to conflict.  The first clause says that the CSR can only have fields listed in the template (and nothing else).  How would one include extensions not in the template based on out of band negotiation?  It seems like it is either in the template or not.

** Section 4.  Is this entire section normative protocol guidance? Or just informatively describing use cases?  If it is informative, please say so.  

** Section 4.1.* Please expand UA = User Agent and CP = Content Provider prior to their introduction in the figures

** Section 4.1.2.1.  Please expand SAN.

** Section 4.1.2.1.  There is a TBD text here, "TBD bootstrap, see https://github.com/yaronf/I-D/issues/47"

** Section 4.1.2.1  Step 2 of Figure 6.  Editorial.  Don't use colloquial language "CDNI things" - s/CDNI things/CDNU meta-data/

** Section 5.*.  Add "registry" to the name of the registry in question.  For example, in Section 5.1.: s/ACME Directory Metadata Fields/ACME Directory Metadata Registry/

** Section 5.4.  If there isn't a registry, why are they in the IANA section?  Should we create a registry?

** Section 5.5. Editorial.  To make the bulleted list explaining the fields symmetric with the registry columns:
NEW:
An extension name

An extension type (the syntax, as a JSON Schema snippet)

The mapping to an X.509 certificate extension.

** Section 5.5.  Per the definition of the "type" column:

-- Formally, what is a JSON Schema snippet?  In particular, the three pre-loaded values reference seem to reference "Appendix B" which doesn't seem like a "snippet" (it containing a fully valid and well-formed XML file).

-- The registration policy is "expert review" so in theory a document is not needed.  Is the thinking that the registry row could contain a bare JSON snippet?

** Section 5.5.  What does "(only for the supported name formats)" mean in the "Mapping to X.509" of subjectAltName

** Section 6.2. Editorial. s/cert/certificate/

** Section 6.2.  Per the enumeration of the "two separate parts" of the delegation process, isn't there also:
-- serving the certificate back to the NDC 
-- a process for handling revocation of the delegation and the certificate itself

Both of these seem to be discussed in Section 6.3 in some form.

** Figure 1 and 8.  In the spirit of consistency, consider if the CA should be named the "CA Server" (per figure 1) or "ACME server" (per figure 8).

** Section 6.4.  s/Following is the proposed solution where/The following is a possible mitigation when/

Regards,
Roman

---

From: Yaron Sheffer <[email-masked]>
Date: Sat, 06 Feb 2021 00:44:52 +0200

Hi Roman,

Thank you for the detailed review. We will go through your comments and will rev the document accordingly, but in the meantime, let me respond specifically to the issue of the CSR template syntax.

The CSR template is potentially a long/complicated JSON document (example: [1]), and we felt that rather than including an informal definition which is easy to get wrong or a long sequence of examples, our audience would be better served by a formal definition.

To the best of my knowledge, by far the most common way to specify a JSON document format is with JSON Schema documents. Granted this spec is still a moving target, but it's already widely implemented. Also, there are discussions between the leaders of the JSON Schema effort and people on the HTTP-API working group, with the goal of standardizing it there.

JSON Schema draft-7 is defined by draft-handrews-json-schema-validation-01 (and a few companion document), and not (as we incorrectly noted) by the latest version of that draft. Clearly it's not ideal to refer to a specific, expired version of an I-D. The situation is mitigated to a certain degree by the schema document [2] mentioning explicitly the supported version: 

  "$schema": "http://json-schema.org/draft-07/schema#"

I hope this clarifies things. Regarding your two related comments:

- Yes, we should have specified the mapping of fields into X.509, and will do that when we address your comments.
- The notion of "snippet" is actually well defined when we say, "a JSON Schema snippet that defines a type". Formally this is a valid JSON object with a "type" attribute, per draft-handrews-json-schema-validation-01 Sec. 6.1.1.

Thanks,
	Yaron

[1] https://raw.githubusercontent.com/yaronf/I-D/master/STAR-Delegation/CSR-template/example-template.json
[2] https://raw.githubusercontent.com/yaronf/I-D/master/STAR-Delegation/CSR-template/template-schema.json

On 2/5/21, 00:50, "Roman Danyliw" <[email-masked]> wrote:

    Hi!

    ** Idnit:

    ** Section 3.1.

    Regards,
    Roman

---

From: Roman Danyliw <[email-masked]>
Date: Tue, 23 Feb 2021 16:31:29 +0000

Hi Yaron!

Thanks for all of the work that went into -05.  It addresses all of my concerns but the following:

(1) Section 3.1.  The updated language is helpful, but I recommend a bit more precision to cover all of the fields.

OLD
The subject field and its subfields are mapped into the subject field of the CSR, as per [RFC5280], Sec. 4.1.2.6. Other extension fields of the CSR template are mapped into the CSR according to the table in Section 5.6.

NEW
The "Subject" field and its subfields per Section 4.1.2.6 of [RFC5280] are mapped into the "subject" field of the CSR template. The "Subject Public Key Info" field and its subfields per Section 4.1.2.7 of [RFC5280] are mapped into the "keyTypes" field of the CSR template.  Other extension fields are mapped as subfields of the "extensions" field in the CSR template according to the table in Section 5.6.

(2) The more thorny issue is how to handle a normative dependence on the JSON schema.  Short of it being in the document, whatever is the formal language used to define the CSR template needs an appropriate normative reference describing it.  Currently, [json-schema-07] in Appendix B would need to be normative (not informative).  I confirmed my concern with the ART ADs, and there is agreement that neither draft-handrews-json-schema-validation or http://json-schema.org will be an adequate normative references (i.e., [json-schema-07]).  

IMO, JSON still seems like the right architectural pattern here.  I also don't see an issue with the Schema that was specified.

A possible compromise (vetted with the ART ADs) is to follow the pattern of RFC8727 which also tried to use JSON Schema but couldn't find a usable normative reference -- full disclosure, I was a co-author.  This RFC normatively specified the "schema" via CDDL but also informatively provided the same schema via [json-schema-07].  Practically, implementers ignore the CDDL and use the more assessible JSON.  I appreciate this approach is additional work and pulls in another "technology" that isn't a natural fit in the ACME ecosystem.  

Do you see any alternatives?

Regards,
Roman

> -----Original Message-----
> From: Yaron Sheffer <[email-masked]>
> Sent: Friday, February 5, 2021 5:45 PM
> To: Roman Danyliw <[email-masked]>; IETF ACME <[email-masked]>
> Subject: Re: [Acme] AD Review: draft-ietf-acme-star-delegation-04
> 
> Hi Roman,
> 
> Thank you for the detailed review. We will go through your comments and will
> rev the document accordingly, but in the meantime, let me respond specifically
> to the issue of the CSR template syntax.
> 
> The CSR template is potentially a long/complicated JSON document (example:
> [1]), and we felt that rather than including an informal definition which is easy
> to get wrong or a long sequence of examples, our audience would be better
> served by a formal definition.
> 
> To the best of my knowledge, by far the most common way to specify a JSON
> document format is with JSON Schema documents. Granted this spec is still a
> moving target, but it's already widely implemented. Also, there are discussions
> between the leaders of the JSON Schema effort and people on the HTTP-API
> working group, with the goal of standardizing it there.
> 
> JSON Schema draft-7 is defined by draft-handrews-json-schema-validation-01
> (and a few companion document), and not (as we incorrectly noted) by the
> latest version of that draft. Clearly it's not ideal to refer to a specific, expired
> version of an I-D. The situation is mitigated to a certain degree by the schema
> document [2] mentioning explicitly the supported version:
> 
> - The notion of "snippet" is actually well defined when we say, "a JSON Schema
> snippet that defines a type". Formally this is a valid JSON object with a "type"
> attribute, per draft-handrews-json-schema-validation-01 Sec. 6.1.1.
> 
> Thanks,
> 	Yaron
> 
> 
> [1] https://raw.githubusercontent.com/yaronf/I-D/master/STAR-
> Delegation/CSR-template/example-template.json
> [2] https://raw.githubusercontent.com/yaronf/I-D/master/STAR-
> Delegation/CSR-template/template-schema.json
> 
> 
>     I did an AD review of draft-ietf-acme-star-delegation-04.  Thanks for this
> work to apply the STAR profile (rfc8739).  Below are my comments.  There are
> a number of editorial clarifications proposed below.  The item that likely needs
> some discussion is the syntax of the CSR template.
> 
>     ** Idnit:
>     ** Section 2.2. Should the buffering requirement for the CSR be normative -
> s/The IdO must buffer/The IdO MUST buffer/
> 
>     ** Section 2.3.1.  Editorial.  s/The IdO can delegate multiple names through
> each NDC/The IdO can delegate multiple names to a NDC/
> 
>     ** Section 2.3.1.  Per "The value of this attribute is the URL pointing to the
> delegation configuration    object that is to be used for this certificate request",
> what is the error handling if the delegation attribute doesn't point to a URL
> found in the delegations URL list?
> 
>     ** Section 2.3.2.  It might be worth pointing out the obvious when clarifying
> the properties of the Order objects such as:
>     ** Section 2.3.2.  Per "When the validation of the identifiers has been
> successfully completed ...", it would be useful to clarify who is doing the
> validation and when.  Figure 1 suggests that there is only a validation process
> between IdO client and CA server.  However, wouldn't the IdO server be
> checking the identifiers submitted by the NDC client too (prior to passing them
> to the CA server too?
> 
>     ** Section 2.3.2 and 2.3.3.  I didn't  understand the titles used to organize of
> content -- "Order Object on the NDC-IdO side" vs. "IdO-CA side".  They didn't
> follow the clear convention introduced by Figure 1 of NDC client, IdO client, IdO
> server and CA server.  Additionally, Section 2.3.2 discusses behavior which
> seems to be IdO client-to-CA Server (which doesn't seem like "NDC IdO side").
> Additionally, Section 2.3.3. seems to be describing the requirements that
> correspond to construction of the order sent to the CA which is also covered at
> the end of Section 2.3.2.
> 
>     ** Section 2.4.  Per "The authors believe that this is a very minor security
> risk", it would be worth explicitly explaining that position (and not framed as
> the belief of the authors)
> 
>     ** Section 2.5.  This section introduces a new architectural element, ACME
> Delegation server, but doesn't define it.  Simply referencing the use cases in
> Section 4.1.2 isn't enough as this section doesn't even use those words
> ("Delegation server").
> 
>     -- Where is the normative format for the syntax?  Section 3.1 points to
> Appendix B which lists JSON schema whose format is specified "draft 7 of JSON
> Schema, which may not be the latest version of the corresponding Internet
> Draft [I-D.handrews-json-schema] at the time of publication".  As far as I can
> tell "draft 7 of JSON Schema" seems to resolve to https://json-
> schema.org/specification-links.html which points back to draft-handrews-json-
> schema.  This draft appears to be an expired, individual draft codifying.  This
> ambiguity and lack of stable reference is problematic.
> 
>     -- Accepting the Json schema as is, there is no annotation on the fields.  The
> field names very much look like X.509 fields but the text provides no guidance
> on how they should be interpreted to create a CSR beyond explaining "**", "*"
> and what is mandatory.  I would have expected a field mapping but the text
> explicitly says "The mapping between X.509 CSR fields and the template will be
> defined in a future revision of this document.".
> 
>     ** Section 3.1.
>     These two normative clauses seem to conflict.  The first clause says that the
> CSR can only have fields listed in the template (and nothing else).  How would
> one include extensions not in the template based on out of band negotiation?
> It seems like it is either in the template or not.
> 
>     ** Section 4.  Is this entire section normative protocol guidance? Or just
> informatively describing use cases?  If it is informative, please say so.
> 
>     ** Section 4.1.* Please expand UA = User Agent and CP = Content Provider
> prior to their introduction in the figures
> 
>     ** Section 4.1.2.1  Step 2 of Figure 6.  Editorial.  Don't use colloquial
> language "CDNI things" - s/CDNI things/CDNU meta-data/
> 
>     ** Section 5.*.  Add "registry" to the name of the registry in question.  For
> example, in Section 5.1.: s/ACME Directory Metadata Fields/ACME Directory
> Metadata Registry/
> 
>     -- Formally, what is a JSON Schema snippet?  In particular, the three pre-
> loaded values reference seem to reference "Appendix B" which doesn't seem
> like a "snippet" (it containing a fully valid and well-formed XML file).
> 
>     -- The registration policy is "expert review" so in theory a document is not
> needed.  Is the thinking that the registry row could contain a bare JSON
> snippet?
> 
>     ** Figure 1 and 8.  In the spirit of consistency, consider if the CA should be
> named the "CA Server" (per figure 1) or "ACME server" (per figure 8).
>

---

From: "Salz, Rich" <[email-masked]>
Date: Tue, 23 Feb 2021 17:16:20 +0000

> I appreciate this approach is additional work and pulls in another "technology" that isn't a natural fit in the ACME ecosystem.  

I think using CDDL is a bad idea.  As you point out, it's not a natural fit.  I looked at Appendix B of RFC 8610, and while I *think* it would work, I'm not positive.

None of the other ACME documents have used a schema and seem to be acceptable. If the WG authors really think a schema language is needed, I betcha they could craft ABNF or even ASN.1  (ISO X.697 if you need to go that far). Make Appendix B informative and change the second bullet in 5.6 to be "A description of the extension syntax." Beware of over-specifying.

When JSON Schema finally becomes published, re-open ACME (heh:) and put out an "updates" document that makes everything like you want it to be.

>Also, there are discussions

As a co-chair of that group I'll say that the HTTP-API group does not feel json schema belongs there as we have too much work already and JSON isn't just about API's. My guess is it will end up in another group. Which will of course mean things take even longer.

---

From: Roman Danyliw <[email-masked]>
Date: Tue, 23 Feb 2021 17:41:00 +0000

Hi Rich!

> From: Salz, Rich <[email-masked]>
> Sent: Tuesday, February 23, 2021 12:16 PM
> To: Roman Danyliw <[email-masked]>; Yaron Sheffer <[email-masked]>;
> IETF ACME <[email-masked]>
> > I appreciate this approach is additional work and pulls in another
> "technology" that isn't a natural fit in the ACME ecosystem.
> 
> I think using CDDL is a bad idea.  As you point out, it's not a natural fit.  I looked
> at Appendix B of RFC 8610, and while I *think* it would work, I'm not positive.
> 
> None of the other ACME documents have used a schema and seem to be
> acceptable. If the WG authors really think a schema language is needed, I
> betcha they could craft ABNF or even ASN.1  (ISO X.697 if you need to go that
> far). Make Appendix B informative and change the second bullet in 5.6 to be "A
> description of the extension syntax." Beware of over-specifying.

I think there is a lot of flexibility on the modeling language.  There just needs to be something formally describing the langauge.   <No Hat>Whatever is done, I hope the existing schema stays in the document as I think it will be helpful to implementors.</No Hat>

> When JSON Schema finally becomes published, re-open ACME (heh:) and put
> out an "updates" document that makes everything like you want it to be.
>
> > between the leaders of the JSON Schema effort and people on the
> >HTTP-API  working group, with the goal of standardizing it there.
>
> As a co-chair of that group I'll say that the HTTP-API group does not feel json
> schema belongs there as we have too much work already and JSON isn't just
> about API's. My guess is it will end up in another group. Which will of course
> mean things take even longer.

Thanks for the update.  It seems like there is a need here.  I hope a home can be found.

Roman

---

From: Yaron Sheffer <[email-masked]>
Date: Wed, 24 Feb 2021 16:08:11 +0200

Hi Roman,

(1) In fact the existing language is more accurate. The CSR template is sent to the NDC in order to constrain what the NDC puts in the CSR. So the text that describes the mapping *from* the CSR template *to* the CSR is correct. Also, SPKI is freshly generated by the NDC, guided by the constraint on which key types it may use. So maybe:

The subject field and its subfields are mapped into the subject field of the CSR, as per [RFC5280], Sec. 4.1.2.6. Other extension fields of the CSR template are mapped into the CSR according to the table in Section 5.6. The Subject Public Key Info field of the CSR is generated by the NDC according to the constraints defined by the "keyTypes" object of the template.

(2) It turns out that my coauthor Thomas is a native CDDL speaker. So we will include a CDDL schema in addition to the JSON Schema. I concur that developers are much more likely to use the latter.

Thanks,
	Yaron

On 2/23/21, 18:31, "Roman Danyliw" <[email-masked]> wrote:

    Hi Yaron!

    OLD

    NEW

    Regards,
    Roman

---

From: Roman Danyliw <[email-masked]>
Date: Wed, 24 Feb 2021 14:20:03 +0000

Hi Yaron and Thomas!

> Sent: Wednesday, February 24, 2021 9:08 AM
> (1) In fact the existing language is more accurate. The CSR template is sent to
> the NDC in order to constrain what the NDC puts in the CSR. So the text that
> describes the mapping *from* the CSR template *to* the CSR is correct. Also,
> SPKI is freshly generated by the NDC, guided by the constraint on which key
> types it may use. So maybe:
> 
> The subject field and its subfields are mapped into the subject field of the CSR,
> as per [RFC5280], Sec. 4.1.2.6. Other extension fields of the CSR template are
> mapped into the CSR according to the table in Section 5.6. The Subject Public
> Key Info field of the CSR is generated by the NDC according to the constraints
> defined by the "keyTypes" object of the template.
> 
> (2) It turns out that my coauthor Thomas is a native CDDL speaker. So we will
> include a CDDL schema in addition to the JSON Schema. I concur that
> developers are much more likely to use the latter.

Great. Thanks for adding this unexpected element.

Roman

>     The subject field and its subfields are mapped into the subject field of the
> CSR, as per [RFC5280], Sec. 4.1.2.6. Other extension fields of the CSR template
> are mapped into the CSR according to the table in Section 5.6.
> 
>     NEW
>     The "Subject" field and its subfields per Section 4.1.2.6 of [RFC5280] are
> mapped into the "subject" field of the CSR template. The "Subject Public Key
> Info" field and its subfields per Section 4.1.2.7 of [RFC5280] are mapped into
> the "keyTypes" field of the CSR template.  Other extension fields are mapped as
> subfields of the "extensions" field in the CSR template according to the table in
> Section 5.6.
> 
>     (2) The more thorny issue is how to handle a normative dependence on the
> JSON schema.  Short of it being in the document, whatever is the formal
> language used to define the CSR template needs an appropriate normative
> reference describing it.  Currently, [json-schema-07] in Appendix B would need
> to be normative (not informative).  I confirmed my concern with the ART ADs,
> and there is agreement that neither draft-handrews-json-schema-validation or
> http://json-schema.org will be an adequate normative references (i.e., [json-
> schema-07]).
> 
>     IMO, JSON still seems like the right architectural pattern here.  I also don't
> see an issue with the Schema that was specified.
> 
>     A possible compromise (vetted with the ART ADs) is to follow the pattern of
> RFC8727 which also tried to use JSON Schema but couldn't find a usable
> normative reference -- full disclosure, I was a co-author.  This RFC normatively
> specified the "schema" via CDDL but also informatively provided the same
> schema via [json-schema-07].  Practically, implementers ignore the CDDL and
> use the more assessible JSON.  I appreciate this approach is additional work and
> pulls in another "technology" that isn't a natural fit in the ACME ecosystem.
> 
>     > - Yes, we should have specified the mapping of fields into X.509, and will
> do
>     > that when we address your comments.
>     >     ** Section 2.2.  Editorial.  Recommend symmetry in naming of the orders
> and
>     > being explicit on the order in question.
>     >     -- second from last bullet.  s/reflected in the NDC order/reflected in
> Order 1
>     > (i.e., the NDC Order)/
>     >     ** Section 2.5.  Per "The "Location" header must be rewritten", it would
> be
>     > useful to describe the new target.
>     >
>     >     ** Section 5.5.  What does "(only for the supported name formats)"
> mean in
>     > the "Mapping to X.509" of subjectAltName
>     >
>     >     ** Section 6.4.  s/Following is the proposed solution where/The
> following is a
>     > possible mitigation when/
>     >
>     >     Regards,
>     >     Roman
>     >
>     >
>     >
> 
>