Subject: [yang-doctors] Yangdoctors early review of draft-ietf-anima-brski-async-enroll-03

From: Reshad Rahman via Datatracker <[email-masked]>
Date: Sun, 15 Aug 2021 08:22:56 -0700

Reviewer: Reshad Rahman
Review result: Not Ready

Major comments on this document:
- The YANG module has errors. Please validate it first e.g. by using
https://yangvalidator.com/yangvalidator or local tools. Also if you follow
guidelines @ https://datatracker.ietf.org/doc/html/rfc8407#section-3.2, you
will see errors present, if any, on datatracker. See below for the modified
YANG module which is valid, please check whether it is correct. Changes consist
of removing extra "; in author list, adding a revision date and replacing
augment "voucher-request" by augment voucher. - Include a tree diagram as per
https://datatracker.ietf.org/doc/html/rfc8407#section-3.4 - For the security
considerations, please add information as requested in
https://datatracker.ietf.org/doc/html/rfc8407#section-3.7

New assertion-type:
This is regarding issue #18, i.e.
https://github.com/anima-wg/anima-brski-async-enroll/issues/18, the need for
8366bis etc. Email threads:
https://mailarchive.ietf.org/arch/msg/netmod/Om6QOZL-bupgEblNLDL3S0PnaPY/ and
https://mailarchive.ietf.org/arch/msg/netmod/OrJYk01en82VVG-Ncud1YWxCBtg/

It was correctly pointed out that the enumeration for "leaf assertion" in
RFC8366 can not be augmented. If my understanding is correct, there is a
suggestion to do a IANA-maintained module for the assertion and republish a new
YANG module revision when a new assertion is added. However, I don't believe
the "assertion values" are actually IANA-maintained. So I don't think that
doing a IANA-maintained module is good in this case (disclaimer: I won't
pretend to be an expert on IANA-maintained modules). As comparision point, the
IANA BFD module at
https://datatracker.ietf.org/doc/html/draft-ietf-bfd-yang-17#section-2.12 is
for BFD registries maintained by IANA
(https://datatracker.ietf.org/doc/html/rfc5880#section-8).

Since 8366bis is being worked on, can the enum be changed to an identity? That
way, when a new assertion is needed, a new identity is added. Identities would
also enable to support "multiple inheritance" as was asked here:
https://mailarchive.ietf.org/arch/msg/netmod/dNGvcvckwuS_pBmkVg_Te8bedZs/. For
an example, see https://datatracker.ietf.org/doc/html/rfc7950#section-7.18.3

Other comments:
- rc:yang-data (RFC8040) is used. While this seems to be fine, if the
voucher-request-async-artifact template needs to be extended in the future, my
understanding is that it is not possible with yang-data. However, you could use
"structure" and (eventually) "augment-structure" from RFC8791 for this. -
Prefix "ivr" is used for ietf-voucher-request although RFC8995 has "vcr". While
this is valid, I am curious why. - Please take a look at
https://datatracker.ietf.org/doc/html/rfc8407#appendix-B for a module remplate.
e.g. data definition statements usualy go after grouping definitions.

Valid YANG module:

   module ietf-async-voucher-request {
     yang-version 1.1;

     namespace
       "urn:ietf:params:xml:ns:yang:ietf-async-voucher-request";
     prefix "constrained";

     import ietf-restconf {
       prefix rc;
       description
         "This import statement is only present to access
          the yang-data extension defined in RFC 8040.";
       reference "RFC 8040: RESTCONF Protocol";
     }

     import ietf-voucher-request {
       prefix ivr;
       description
         "This module defines the format for a voucher request,
             which is produced by a pledge as part of the RFC8995
             onboarding process.";
       reference
         "RFC 8995: Bootstrapping Remote Secure Key Infrastructure";
     }

     organization
      "IETF ANIMA Working Group";

     contact
      "WG Web:   <http://tools.ietf.org/wg/anima/>
       WG List:  <mailto:[email-masked]>
       Author:   Steffen Fries
                 <mailto:[email-masked]>
       Author:   Hendrik Brockhaus
                 <mailto: [email-masked]>
       Author:   Eliot Lear
                 <mailto: [email-masked]>
       Author:   Thomas Werner
                 <mailto: [email-masked]>";
     description
      "This module defines an extension of the RFC8995 voucher
       request to permit a registrar-agent to convey the adjacency
       relationship from the registrar-agent to the registrar.

       The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
       'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY',
       and 'OPTIONAL' in the module text are to be interpreted as
       described in RFC 2119.";
     revision 2021-08-13 {
       description
        "Initial version";
       reference
        "RFC XXXX: Voucher Request for Asynchronous Enrollment";
     }
     rc:yang-data voucher-request-async-artifact {
       // YANG data template for a voucher.
       uses voucher-request-async-grouping;
     }
     // Grouping defined for future usage
     grouping voucher-request-async-grouping {
       description
         "Grouping to allow reuse/extensions in future work.";
       uses ivr:voucher-request-grouping {

         augment voucher {
           description "Base the constrained voucher-request upon the
             regular one";
           leaf agent-signed-data {
             type binary;
             description
               "The agent-signed-data field contains a JOSE [RFC7515]
                object provided by the Registrar-Agent to the Pledge.

                This artifact is signed by the Registrar-Agent
                and contains a copy of the pledge's serial-number.";
           }

           leaf agent-provided-proximity-registrar-cert {
             type binary;
             description
               "An X.509 v3 certificate structure, as specified by
                RFC 5280, Section 4, encoded using the ASN.1
                distinguished encoding rules (DER), as specified
                in ITU X.690.
                The first certificate in the registrar TLS server
                certificate_list sequence (the end-entity TLS
                certificate; see RFC 8446) presented by the
                registrar to the registrar-agent and provided to
                the pledge.
                This MUST be populated in a pledge's voucher-request
                when an agent-proximity assertion is requested.";
             reference
               "ITU X.690: Information Technology - ASN.1 encoding
                rules: Specification of Basic Encoding Rules (BER),
                Canonical Encoding Rules (CER) and Distinguished
                Encoding Rules (DER)
                RFC 5280: Internet X.509 Public Key Infrastructure
                Certificate and Certificate Revocation List (CRL)
                Profile
                RFC 8446: The Transport Layer Security (TLS)
                Protocol Version 1.3";
           }

           leaf agent-sign-cert {
             type binary;
             description
               "An X.509 v3 certificate structure, as specified by
                RFC 5280, Section 4, encoded using the ASN.1
                distinguished encoding rules (DER), as specified
                in ITU X.690.
                This certificate can be used by the pledge,
                the registrar, and the MASA to verify the signature
                of agent-signed-data. It is an optional component
                for the pledge-voucher request.
                This MUST be populated in a registrar's
                voucher-request when an agent-proximity assertion
                is requested.";
             reference
               "ITU X.690: Information Technology - ASN.1 encoding
                rules: Specification of Basic Encoding Rules (BER),
                Canonical Encoding Rules (CER) and Distinguished
                Encoding Rules (DER)
                RFC 5280: Internet X.509 Public Key Infrastructure
                Certificate and Certificate Revocation List (CRL)
                Profile";
           }
         }
       }
     }
   }

---

From: "Fries, Steffen" <[email-masked]>
Date: Wed, 18 Aug 2021 08:43:57 +0000

Hi Reshad,

Thank you for the review. I will address the points in the next update of the draft. 
I took over the proposed changes you made and will provide the tree diagram and the enhancement to the security considerations as suggested. In the ANIMA design team we will discuss the recommendations for RFC 8366bis 
I have some remarks to the other comments:

> See below for the modified YANG module which
> is valid, please check whether it is correct. Changes consist of removing extra ";
> in author list, adding a revision date and replacing augment "voucher-request"
> by augment voucher. 
I'm not sure about the last statement, as we would like to enhance the existing voucher-request definition from RFC 8995 in BRSKI-AE. Does this comment means we cannot augment the voucher-request as it already augments the voucher and therefore have to use the voucher  and only describe the leafs added?

> Other comments:
> - rc:yang-data (RFC8040) is used. While this seems to be fine, if the voucher-
> request-async-artifact template needs to be extended in the future, my
> "structure" and (eventually) "augment-structure" from RFC8791 for this. 
We will discuss this point. Currently there is no explicit need for enhancements.

>- Prefix
> "ivr" is used for ietf-voucher-request although RFC8995 has "vcr". While this is
> valid, I am curious why. 
Changed to match the definition in RFC 8995. Also changed for the "uses" statement in the grouping.

Best regards
Steffen

- Please take a look at
> https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdatatrac
> ker.ietf.org%2Fdoc%2Fhtml%2Frfc8407%23appendix-
> B&amp;data=04%7C01%7Ccef9763c-149c-4881-b9c2-
> 5fedc277663a%40ad011.siemens.com%7C7e6d34307a3642d99cd208d9600095
> 14%7C38ae3bcd95794fd4addab42e1495d55a%7C1%7C0%7C637646377883265
> 554%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiL
> CJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=oyAUYIKQZSQxxURiRc
> j0RTlM6kiupsa6PqRs0hb86jg%3D&amp;reserved=0 for a module remplate.
>       "WG Web:
> <https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Ftools.ietf
> .org%2Fwg%2Fanima%2F&amp;data=04%7C01%7Ccef9763c-149c-4881-b9c2-
> 5fedc277663a%40ad011.siemens.com%7C7e6d34307a3642d99cd208d9600095
> 14%7C38ae3bcd95794fd4addab42e1495d55a%7C1%7C0%7C637646377883265
> 554%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiL
> CJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=7BDzJ4MjL%2BaCAAh
> v4A2PZLl2pB0b7WoNM19qAEGVICU%3D&amp;reserved=0>
> _______________________________________________
> Anima mailing list
> [email-masked]
> https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ietf
> .org%2Fmailman%2Flistinfo%2Fanima&amp;data=04%7C01%7Ccef9763c-149c-
> 4881-b9c2-
> 5fedc277663a%40ad011.siemens.com%7C7e6d34307a3642d99cd208d9600095
> 14%7C38ae3bcd95794fd4addab42e1495d55a%7C1%7C0%7C637646377883265
> 554%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiL
> CJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=BBO%2FhGYnqAUtGF
> 3Jc5KBxe53v3jF%2BpyWdukQSAmp9x8%3D&amp;reserved=0

---

From: Michael Richardson <[email-masked]>
Date: Wed, 18 Aug 2021 07:26:44 -0400

reshad> Other comments: - rc:yang-data (RFC8040) is used. While this
    reshad> seems to be fine, if the voucher- request-async-artifact template
    reshad> needs to be extended in the future, my understanding is that it
    reshad> is not possible with yang-data. However, you could use
    reshad> "structure" and (eventually) "augment-structure" from RFC8791 for
    reshad> this.

I am probably the guilty party that wrote the YANG.
I guess I missed your email (seeing Steffen's reply only), and I'll go back
to the list to find it to understand.

We do want to mix and match the various extensions.
It is not clear to me how to do that.

    > We will discuss this point. Currently there is no explicit need for

    reshad> - Prefix "ivr" is used for ietf-voucher-request although RFC8995 has
    reshad> "vcr". While this is valid, I am curious why.

I didn't think the prefix had relevance outside of the module, but I don't
know a lot here.

--
]               Never tell me the odds!                 | ipv6 mesh networks [
]   Michael Richardson, Sandelman Software Works        |    IoT architect   [
]     [email-masked]  http://www.sandelman.ca/        |   ruby on rails    [

---

From: "Fries, Steffen" <[email-masked]>
Date: Wed, 18 Aug 2021 11:46:24 +0000

Hi Michael, 

> -----Original Message-----
> From: Michael Richardson <[email-masked]>
> Sent: Mittwoch, 18. August 2021 13:27
> 
> I guess I missed your email (seeing Steffen's reply only), and I'll go back to the
> list to find it to understand.
I saw that the constraint voucher follows the same approach.

> It is not clear to me how to do that.
Maybe related to this, would it be better to augment the voucher than as requested by Reshad or the voucher-request as we currently do it. I also had a look into the constraint voucher as there are also enhancements defined. So I guess I should go with the augmented voucher?

> I didn't think the prefix had relevance outside of the module, but I don't know a
> lot here.
I meanwhile changed it to vcr. If it has no relevance outside the module, it should not be a problem

Regards
Steffen

---

From: Reshad Rahman <[email-masked]>
Date: Wed, 18 Aug 2021 21:01:43 +0000 (UTC)

Hi Steffen,

    On Wednesday, August 18, 2021, 04:44:01 AM EDT, Fries, Steffen <[email-masked]> wrote:  
 
 Hi Reshad,

I'm not sure about the last statement, as we would like to enhance the existing voucher-request definition from RFC 8995 in BRSKI-AE. Does this comment means we cannot augment the voucher-request as it already augments the voucher and therefore have to use the voucher  and only describe the leafs added?
<RR> The document currently has the following       uses ivr:voucher-request-grouping {
         augment "voucher-request" {
There is no node "voucher-request" in voucher-request-grouping in RFC8995 (unless I missed it). So I assumed it's the "voucher" node which is intended to be augmented. Disclaimer: I don't fully understand the intent here.
If it is the voucher-request-artifact  from RFC8995 which is to be augmented, I believe that can't be done because yang-data doesn't allow for augments.     // Top-level statement
     rc:yang-data voucher-request-artifact {
       uses voucher-request-grouping;
     }
We will discuss this point. Currently there is no explicit need for enhancements.
<RR> My understanding is that people are being encouraged to use "structure" instead of "yang-data", but I'll fer this to the AD (Rob).
<RR> Ack.
Regards,Reshad.
Best regards
Steffen

- Please take a look at
> Error during processing.
> <Error during processing.
> Error during processing.

| 
| 
| 
|  |  |

 |

 |
| 
|  | 
Error during processing.

 |

 |

 |

Fries, et al.           Expires December 26, 2021              [Page 49]
Internet-Draft                  BRSKI-AE                       June 2021

         augment "voucher-request" {

| 
| 
| 
|  |  |

 |

 |
| 
|  | 
Error during processing.

 |

 |

 |

| 
| 
| 
|  |  |

 |

 |
| 
|  | 
Error during processing.

 |

 |

 |

---

From: Reshad Rahman <[email-masked]>
Date: Wed, 18 Aug 2021 21:07:49 +0000 (UTC)

Hi all,
    On Wednesday, August 18, 2021, 07:46:31 AM EDT, Fries, Steffen <[email-masked]> wrote:  
 
 Hi Michael, 

> list to find it to understand.
<RR> And I didn't receive Michael's response to Steffen. Not in my Junk folder either.....
I saw that the constraint voucher follows the same approach.
<RR> Where is the constraint voucher defined?
Maybe related to this, would it be better to augment the voucher than as requested by Reshad or the voucher-request as we currently do it. I also had a look into the constraint voucher as there are also enhancements defined. So I guess I should go with the augmented voucher?
<RR> I didn't see a voucher-request node but I'm probably looking for the wrong thing.
>    > We will discuss this point. Currently there is no explicit need for
>    > enhancements.
> 
<RR> It doesn't. It's just usually people use the same prefix as defined in the module. No big deal if you want to use a different one, I was just curious why.
Regards,Reshad.
I meanwhile changed it to vcr. If it has no relevance outside the module, it should not be a problem

Regards
Steffen

---

From: "Fries, Steffen" <[email-masked]>
Date: Thu, 19 Aug 2021 06:06:35 +0000

Hi Reshad,

From: Reshad Rahman <[email-masked]>
Sent: Mittwoch, 18. August 2021 23:02
To: [email-masked]; Fries, Steffen (T RDA CST) <[email-masked]>
Cc: [email-masked]; [email-masked]
Subject: Re: [Anima] Yangdoctors early review of draft-ietf-anima-brski-async-enroll-03

Hi Steffen,

On Wednesday, August 18, 2021, 04:44:01 AM EDT, Fries, Steffen <[email-masked]<mailto:[email-masked]>> wrote:

Hi Reshad,

I'm not sure about the last statement, as we would like to enhance the existing voucher-request definition from RFC 8995 in BRSKI-AE. Does this comment means we cannot augment the voucher-request as it already augments the voucher and therefore have to use the voucher  and only describe the leafs added?
<RR> The document currently has the following

If it is the voucher-request-artifact  from RFC8995 which is to be augmented, I believe that can't be done because yang-data doesn't allow for augments.

     // Top-level statement

     }
[stf] thank you, that was the missing piece, so I will go ahead and use the “voucher” instead as you suggested in your first email.

We will discuss this point. Currently there is no explicit need for enhancements.
<RR> My understanding is that people are being encouraged to use "structure" instead of "yang-data", but I'll fer this to the AD (Rob).
[stf] Michael send an email to this yesterday. We will have some further discussion on it.

Best regards
Steffen

Regards,
Reshad.

Best regards
Steffen

- Please take a look at
> Error during processing.<https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdatatrac>
> <Error during processing.<https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Ftools.ietf%2F&data=04%7C01%7Ccef9763c-149c-4881-b9c2-5fedc277663a%40ad011.siemens.com%7C5334aff5dec94c70029908d9628b6551%7C38ae3bcd95794fd4addab42e1495d55a%7C1%7C0%7C637649173116353250%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=1q4RgIEZv9IfCQ2NL%2F8Ks3LkHIMOG51jvMGTBHBjIsU%3D&reserved=0>

>        WG List:  <mailto:[email-masked]<mailto:[email-masked]>>
>        Author:  Steffen Fries
>                  <mailto:[email-masked]<mailto:[email-masked]>>
>                  <mailto: [email-masked]<mailto:[email-masked]>>
>        Author:  Eliot Lear
>                  <mailto: [email-masked]<mailto:[email-masked]>>
>        Author:  Thomas Werner
>                  <mailto: [email-masked]<mailto:[email-masked]>>";
>      description

> [email-masked]<mailto:[email-masked]>
> Error during processing.<https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ietf%2F&data=04%7C01%7Ccef9763c-149c-4881-b9c2-5fedc277663a%40ad011.siemens.com%7C5334aff5dec94c70029908d9628b6551%7C38ae3bcd95794fd4addab42e1495d55a%7C1%7C0%7C637649173116353250%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=7IKtdVMCX0foR2CGHAKLa95DI4ciIrSr4eqdd35D2Dg%3D&reserved=0>

Error during processing.

Error during processing.

Error during processing.

---

From: "Fries, Steffen" <[email-masked]>
Date: Thu, 19 Aug 2021 06:15:34 +0000

Hi Reshad,

From: Reshad Rahman <[email-masked]>
Sent: Mittwoch, 18. August 2021 23:08

<RR> And I didn't receive Michael's response to Steffen. Not in my Junk folder either.....
[stf] Michael also just received my response to your email. ANIMA WG was in cc so I’m not sure what happened.

I saw that the constraint voucher follows the same approach.
<RR> Where is the constraint voucher defined?
[stf] https://datatracker.ietf.org/doc/draft-ietf-anima-constrained-voucher/

Maybe related to this, would it be better to augment the voucher than as requested by Reshad or the voucher-request as we currently do it. I also had a look into the constraint voucher as there are also enhancements defined. So I guess I should go with the augmented voucher?
<RR> I didn't see a voucher-request node but I'm probably looking for the wrong thing.
[stf] You answered this already with your hint in the previous email. We cant augment the yang-data is what I understood as it does not allow augmentation.

Best regards
Steffen

Regards,
Reshad.

Regards
Steffen

> ]    [email-masked]<mailto:[email-masked]>  http://www.sandelman.ca/ <https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.sandelman.ca%2F&data=04%7C01%7Ccef9763c-149c-4881-b9c2-5fedc277663a%40ad011.siemens.com%7Cb2b4f58606d1406a886b08d9628c4028%7C38ae3bcd95794fd4addab42e1495d55a%7C1%7C0%7C637649176775498908%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=UD3E8EaOSYSCy8yqbocjCgtjCZgYXQlOis4fXLSe4iE%3D&reserved=0>       |  ruby on rails    [

---

From: Reshad Rahman <[email-masked]>
Date: Sun, 22 Aug 2021 15:18:08 +0000 (UTC)

On Thursday, August 19, 2021, 04:43:33 PM EDT, Michael Richardson <[email-masked]> wrote:

 On 2021-08-15 11:22 a.m., Reshad Rahman via Datatracker wrote:
> the "assertion values" are actually IANA-maintained. 

The RFC8366bis would create the IANA Registry.

<RR> If you want a central location for these values, then doing IANA maintained values is the way to go. But I am not familiar with the details of the process, so I don't know of the extra cost, if any, of doing it that way. e..g I assume when a new value is needed in the future, we'll need a bis of 8366bis on top of the new document which uses that value?Adding Rob to shed some light on this.
 >So I don't think that

Thank you, I did need another example.

> an example, see https://datatracker.ietf.org/doc/html/rfc7950#section-7.18.3

I don't know if I can use an identity.
<RR> I believe you can use an identity. But if you want a central location for all 'values', identity is not the way to go. If you're ok with having the uses distributed in various documents, identity will work.RFC6020 section 6.2, I think?<RR> No that's identifiers. 
I'm not sure that I understand the 7950 example.<RR> Does this help: https://datatracker.ietf.org/doc/html/rfc7950#section-7.18As opposed to having enum E with e.g. values E1 and E2, you have an identity I (no "base") and then new identities I1 and I2 with I as base. For example:  identity path-type {
    description
      "Base identity for BFD path type. The path type indicates
       the type of path on which BFD is running.";
  }
  identity path-ip-sh {
    base path-type;
    description "BFD on IP single hop.";
    reference
      "RFC 5881: Bidirectional Forwarding Detection (BFD)
       for IPv4 and IPv6 (Single Hop).";
  }
  identity path-ip-mh {
    base path-type;
    description "BFD on IP multihop paths.";
    reference
      "RFC 5883: Bidirectional Forwarding Detection (BFD) for
       Multihop Paths.";
  }

> understanding is that it is not possible with yang-data. However, you could use

Uhm, but we use rc:yang-data in RFC8366, and we extend it in RFC8995 to 
make voucher-request.  And we take that, and we extend it in 
anima-constrained-voucher.

So I'm confused.
Is that we are doing this a bug?<RR> No. When 8366 was written, afaik the work on structure had just started. So it made sense that you used yang-data.

> "structure" and (eventually) "augment-structure" from RFC8791 for this. -

I have read 8791 now.
It seems fine.  I don't see why we would or wouldn't do RFC8366bis as a 
structure.  I would appreciate a deeper understanding of what it does 
better.<RR> structure allows for extensions and doesn't need to be at top-level (which is the case for yang-data). Maybe you don't need those 2 enhancements.

BTW: we plan to rename all of our extensions (still in ID stage) to be 
ietf-voucher-foo, rather than ietf-foo-voucher, and I wondered if there 
was any reason why this was a bad idea.  It seems like a good idea from 
a collection/sorting point of view for the humans involved.<RR> Sounds good.