--- 1/draft-ietf-netmod-yang-usage-09.txt 2010-08-11 20:12:54.000000000 +0200 +++ 2/draft-ietf-netmod-yang-usage-10.txt 2010-08-11 20:12:54.000000000 +0200 @@ -1,18 +1,18 @@ Internet Engineering Task Force A. Bierman -Internet-Draft InterWorking Labs -Intended status: Informational July 12, 2010 -Expires: January 13, 2011 +Internet-Draft Brocade +Intended status: Informational August 11, 2010 +Expires: February 12, 2011 Guidelines for Authors and Reviewers of YANG Data Model Documents - draft-ietf-netmod-yang-usage-09 + draft-ietf-netmod-yang-usage-10 Abstract This memo provides guidelines for authors and reviewers of standards track specifications containing YANG data model modules. Applicable portions may be used as a basis for reviews of other YANG data model documents. Recommendations and procedures are defined, which are intended to increase interoperability and usability of Network Configuration Protocol (NETCONF) implementations which utilize YANG data model modules. @@ -25,21 +25,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on January 13, 2011. + This Internet-Draft will expire on February 12, 2011. Copyright Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -73,41 +73,43 @@ 4.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.4. Conditional Statements . . . . . . . . . . . . . . . . . . 12 4.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 12 4.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 13 4.7. Module Header, Meta, and Revision Statements . . . . . . . 14 4.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 15 4.9. Top Level Data Definitions . . . . . . . . . . . . . . . . 16 4.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 16 4.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 17 4.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 17 - 4.13. Operation Definitions . . . . . . . . . . . . . . . . . . 18 + 4.13. Operation Definitions . . . . . . . . . . . . . . . . . . 19 4.14. Notification Definitions . . . . . . . . . . . . . . . . . 19 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 - 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22 - 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 - 8.1. Normative References . . . . . . . . . . . . . . . . . . . 23 - 8.2. Informative References . . . . . . . . . . . . . . . . . . 23 - Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 25 - Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 27 - Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 30 - C.1. Changes from 08 to 09 . . . . . . . . . . . . . . . . . . 30 - C.2. Changes from 07 to 08 . . . . . . . . . . . . . . . . . . 30 - C.3. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 30 - C.4. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 30 - C.5. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 30 - C.6. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 31 - C.7. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 32 - C.8. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 32 - C.9. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 32 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 33 + 6.1. Security Considerations Section Template . . . . . . . . . 21 + 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 + 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 + 8.1. Normative References . . . . . . . . . . . . . . . . . . . 25 + 8.2. Informative References . . . . . . . . . . . . . . . . . . 25 + Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 27 + Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 29 + Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 32 + C.1. Changes from 09 to 10 . . . . . . . . . . . . . . . . . . 32 + C.2. Changes from 08 to 09 . . . . . . . . . . . . . . . . . . 32 + C.3. Changes from 07 to 08 . . . . . . . . . . . . . . . . . . 32 + C.4. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 32 + C.5. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 32 + C.6. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 32 + C.7. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 33 + C.8. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 34 + C.9. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 34 + C.10. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 34 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 36 1. Introduction The standardization of network configuration interfaces for use with the Network Configuration Protocol (NETCONF) [RFC4741] requires a modular set of data models, which can be reused and extended over time. This document defines a set of usage guidelines for standards track documents containing YANG [I-D.ietf-netmod-yang] data models. YANG @@ -435,20 +437,30 @@ 'if-feature' and/or 'when' statements. Data model designers need to carefully consider all modularity aspects, including the use of YANG conditional statements. If a data definition is optional, depending on server support for a NETCONF protocol capability, then a YANG 'feature' statement SHOULD be defined to indicate that the NETCONF capability is supported within the data model. + If any notification data, or any data definition, for a non- + configuration data node is not mandatory, then the server may or may + not be required to return an instance of this data node. If any + conditional requirements exist for returning the data node in a + notification payload or retrieval request, they MUST be documented + somewhere. For example, a 'when' or 'if-feature' statement could + apply to the data node, or the conditional requirements could be + explained in a 'description' statement within the data node or one of + its ancestors (if any). + 4.5. XPath Usage This section describes guidelines for using the XML Path Language [W3C.REC-xpath-19991116] (XPath) within YANG modules. The 'attribute' and 'namespace' axes are not supported in YANG, and MAY be empty in a NETCONF server implementation. The 'position' and 'last' functions MAY be used with caution. A server is not required to maintain any particular XML document order @@ -541,21 +553,23 @@ A revision statement MUST be present for each published version of the module. The revision statement MUST have a reference substatement. It MUST identify the published document which contains the module. Modules are often extracted from their original documents and it is useful for developers and operators to know how to find the original source document in a consistent manner. The revision statement MAY have a description substatement. Each new revision MUST include a revision date which is higher than - any other revision date in the module. + any other revision date in the module. The revision date does not + need to be updated if the module contents do not change in the new + document revision. It is acceptable to reuse the same revision statement within unpublished versions (i.e., Internet-Drafts), but the revision date MUST be updated to a higher value each time the Internet-Draft is re- published. 4.8. Namespace Assignments It is RECOMMENDED that only valid YANG modules are included in documents, whether they are published yet or not. This allows: @@ -788,20 +804,90 @@ This document defines documentation guidelines for NETCONF content defined with the YANG data modeling language. The guidelines for how to write a Security Considerations section for a YANG module are defined in the online document http://www.ops.ietf.org/netconf/yang-security-considerations.txt This document does not introduce any new or increased security risks into the management system. + The following section contains the security considerations template + dated 2010-06-16. Be sure to check the WEB page at the URL listed + above in case there is a more recent version available. + + Each specification that defines one or more YANG modules MUST contain + a section that discusses security considerations relevant to those + modules. This section MUST be patterned after the latest approved + template (available at [ed: URL TBD]). + + In particular, writable data nodes that could be especially + disruptive if abused MUST be explicitly listed by name and the + associated security risks MUST be spelled out. + + Similarly, readable data nodes that contain especially sensitive + information or that raise significant privacy concerns MUST be + explicitly listed by name and the reasons for the sensitivity/privacy + concerns MUST be explained. + + Further, if new RPC operations have been defined, then the security + considerations of each new RPC operation MUST be explained. + +6.1. Security Considerations Section Template + X. Security Considerations + + The YANG module defined in this memo is designed to be accessed + via the NETCONF protocol [RFC4741]. The lowest NETCONF layer is + the secure transport layer and the mandatory to implement secure + transport is SSH [RFC4742]. + + -- if you have any writeable data nodes (those are all the + -- "config true" nodes, and remember, that is the default) + -- describe their specific sensitivity or vulnerability. + + There are a number of data nodes defined in this YANG module + which are writable/creatable/deletable (i.e. config true, which + is the default). These data nodes may be considered sensitive + or vulnerable in some network environments. Write operations + (e.g. edit-config) to these data nodes without proper protection + can have a negative effect on network operations. These are + the subtrees and data nodes and their sensitivity/vulnerability: + + + + -- for all YANG modules you must evaluate whether any readable data + -- nodes (those are all the "config false" nodes, but also all other + -- nodes, because they can also be read via operations like get or + -- get-config) are sensitive or vulnerable (for instance, if they + -- might reveal customer information or violate personal privacy + -- laws such as those of the European Union if exposed to + -- unauthorized parties) + + Some of the readable data nodes 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: + + + + -- if your YANG module has defined any rpc operations + -- describe their specific sensitivity or vulnerability. + + Some of the RPC 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: + + + Figure 2 + 7. Acknowledgments The structure and contents of this document are adapted from Guidelines for MIB Documents [RFC4181], by C. M. Heard. The working group thanks Martin Bjorklund and Juergen Schoenwaelder for their extensive reviews and contributions to this document. 8. References @@ -823,21 +909,21 @@ [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006. [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide to the IETF Trust", BCP 78, RFC 5378, November 2008. [RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers, and Boilerplates", RFC 5741, December 2009. [W3C.REC-xpath-19991116] - DeRose, S. and J. Clark, "XML Path Language (XPath) + Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999, . [I-D.ietf-netmod-yang] Bjorklund, M., "YANG - A data modeling language for the Network Configuration Protocol (NETCONF)", draft-ietf-netmod-yang-13 (work in progress), June 2010. [I-D.ietf-netmod-yang-types] @@ -1022,73 +1108,83 @@ // rpc statements // notification statements // DO NOT put deviation statements in a published module } - Figure 2 + Figure 3 Appendix C. Change Log -C.1. Changes from 08 to 09 +C.1. Changes from 09 to 10 + + o Added security considerations section template. + + o Added guideline for documenting conditional requirements for non- + mandatory non-configuration data nodes. + + o Clarified that revision date update applies to the module + contents. + +C.2. Changes from 08 to 09 o Clarifications and corrections to address Gen-ART review comments. -C.2. Changes from 07 to 08 +C.3. Changes from 07 to 08 o Corrected YANG security considerations URL. o Expanded 'CODE BEGINS' example. o Added RPC operations to the security considerations guidelines section. o Removed guideline about leading and trailing whitespace. -C.3. Changes from 06 to 07 +C.4. Changes from 06 to 07 o Corrected title change bug; supposed to be page header instead. o Fixed typos added to last revision. o Added sentence to checklist to make sure text outside module contains citations for imports. -C.4. Changes from 05 to 06 +C.5. Changes from 05 to 06 o Several clarifications and corrections, based on the AD review by Dan Romascanu. -C.5. Changes from 04 to 05 +C.6. Changes from 04 to 05 o Changed 'object' terminology to 'data definition'. o Put XPath guidelines in separate section. o Clarified XPath usage for XML document order dependencies. o Updated guidelines to current conventions. o Added informative reference for IANA considerations guidelines and XML registry. o Updated IANA Considerations section to reserve the ietf-template module in the YANG Module Name Registry so it cannot be reused accidently. o Many other clarifications and fixed typos found in WGLC reviews. -C.6. Changes from 03 to 04 +C.7. Changes from 03 to 04 o Removed figure 1 to reduce duplication, just refer to 4741bis draft. o Fixed bugs and typos found in WGLC reviews. o Removed some guidelines and referring to YANG draft instead of duplicating YANG rules here. o Changed security guidelines so they refer to the IETF Trust TLP @@ -1117,47 +1213,47 @@ o Added guideline that strings should not rely on preservation of leading and trailing whitespace characters. o Relaxed some XPath and anyxml guidelines from SHOULD NOT or MUST NOT to MAY use with caution. o Updated the TLP text within the example module again. o Reversed order of change log so most recent entries are first. -C.7. Changes from 02 to 03 +C.8. Changes from 02 to 03 o Updated figure 1 to align with 4741bis draft. o Updated guidelines for import-by-revision and include-by-revision. o Added file name to code begins convention in ietf-template module. -C.8. Changes from 01 to 02 +C.9. Changes from 01 to 02 o Updated figure 1 per mailing list comments. o Updated suggested organization to include the working group name. o Updated ietf-template.yang to use new organization statement value. o Updated Code Component requirements as per new TLP. o Updated ietf-template.yang to use new Code Component begin and end markers. o Updated references to the TLP in a couple sections. o Change manager/agent terminology to client/server. -C.9. Changes from 00 to 01 +C.10. Changes from 00 to 01 o Added transport 'TLS' to figure 1. o Added note about RFC 2119 terminology. o Corrected URL for instructions to authors. o Updated namespace procedures section. o Updated guidelines on module contact, reference, and organization @@ -1168,13 +1264,13 @@ o Added section on temporary namespace statement values. o Added section on top level database objects. o Added ietf-template.yang appendix. Author's Address Andy Bierman - InterWorking Labs + Brocade - Email: andyb@iwl.com + Email: andy.bierman@brocade.com