Re: [netconf] Genart last call review of draft-ietf-netconf-crypto-types-28

[[e-mail]]

Kent Watsen <[e-mail]> writes:
> [...]

All of the fixes look good to me and require no comment, except the
following items:

>>   Table 1: Label to RFC Mapping
>> 
>> In -28, this caption appears visually to be the caption of both the
>> dependency diagram at the top of page 5 and the label-to-RFC mapping
>> table at the bottom of page 5, and so probably should be amended to
>> describe both of them together.
>
> s/Label in Diagram to RFC Mapping/Label to RFC Mapping/
>
> Good enough?

Since the title on the table in -28 already is "Label to RFC Mapping", I
think you didn't write here what you meant.

>>    3.10.  The "ietf-crypto-types" YANG Module
>> 
>> The title of this section seems to be uninformative given that 'The
>> "ietf-crypto-types" YANG Module' is the subject of the entire
>> document.  Is this title what was intended?
>
> For the most part, yes, I see your point.
> Maybe s/The/For the/ or s/The/Regarding the/?
>
> In any case, be aware that there exists an IETF-defined template
> for the Security Considerations section that is to be used for each
> YANG module defined in a draft.  So, if a draft defines the three
> modules: ietf-foo-common, ietf-foo-client, and ietf-foo-server, the
> Security Considerations section contains the three subsections:
>
> 	 The "ietf-foo-common" YANG Module
> 	 The "ietf-foo-client" YANG Module
> 	 The "ietf-foo-server" YANG Module
>
> Each containing an instance of the template for that YANG module.

Ah, yes, and having this section hierarchy:

    Security Considerations
 	 The "ietf-foo-common" YANG Module
 	 The "ietf-foo-client" YANG Module
 	 The "ietf-foo-server" YANG Module

is quite clear. ... Even setting the title of the section to
"3.10. Security considerations for the the "ietf-crypto-types" YANG
Module" reads oddly as a subsection of "Security
considerations". ... What you *mean* is "RFC 8407 security
considerations section template", but that's too long.  Perhaps
"Security considerations template"?  "Template for the
"ietf-crypto-types" YANG Module"?

And there's an oddity that although 3.10 is the instantiated template
from RFC 8407/BCP 216 section 3.7.1, the draft doesn't reference RFC
8407/BCP 216.  Could you add e.g. [RFC 8407] as a reference at the very
beginning of 3.10?

>>   Some of the readable data nodes defined in this YANG module may be
>>   considered sensitive or vulnerable in some network environments.  It
>>   is thus important to control read access (e.g., via get, get-config,
>>   or notification) to these data nodes.  These are the subtrees and
>>   data nodes and their sensitivity/vulnerability:
>> 
>> The use of "These" in the last sentence does not have an unambiguous
>> referent as I read it.  Perhaps "These subtrees/data nodes have these
>> particular sensitivities/vulnerabilities:"  Similar considerations
>> apply to the last sentence of:
>> 
>>   Some of the operations in this YANG module may be considered
>>   sensitive or vulnerable in some network environments.  It is thus
>>   important to control access to these operations.  These are the
>>   operations and their sensitivity/vulnerability:
>
> This text comes from the aforementioned template.  That said, I agree
> that it's not great.  Perhaps, even better, "*The following* subtrees and
> data nodes have particular sensitivities/vulnerabilities"?

Yes, your version is clearer.  (And the template should be updated that
way, too!)

Dale