idnits 2.17.1 draft-ietf-opsawg-smi-datatypes-in-xsd-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 1, 2010) is 5169 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: '0-4' is mentioned on line 331, but not defined == Missing Reference: '0-9' is mentioned on line 339, but not defined == Missing Reference: '0-5' is mentioned on line 331, but not defined == Missing Reference: '6-9' is mentioned on line 331, but not defined == Missing Reference: '3-9' is mentioned on line 332, but not defined == Missing Reference: '0-1' is mentioned on line 339, but not defined == Missing Reference: '1-3' is mentioned on line 339, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XMLSchema' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSDDatatypes' Summary: 1 error (**), 0 flaws (~~), 8 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Ellison 3 Internet-Draft Ellison Software Consulting 4 Intended status: Standards Track B. Natale 5 Expires: September 2, 2010 MITRE 6 March 1, 2010 8 Expressing SNMP SMI Datatypes in XML Schema Definition Language 9 draft-ietf-opsawg-smi-datatypes-in-xsd-06.txt 11 Abstract 13 This memo defines the IETF standard expression of Structure of 14 Management Information (SMI) base datatypes in Extensible Markup 15 Language (XML) Schema Definition (XSD) language. The primary 16 objective of this memo is to enable the production of XML documents 17 that are as faithful to the SMI as possible, using XSD as the 18 validation mechanism. 20 Status of this Memo 22 This Internet-Draft is submitted to IETF in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as Internet- 28 Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt. 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 This Internet-Draft will expire on September 2, 2010. 43 Copyright Notice 45 Copyright (c) 2010 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 4. XSD for SMI Base Datatypes . . . . . . . . . . . . . . . . . . 7 64 5. Rationale . . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 5.1. Numeric Datatypes . . . . . . . . . . . . . . . . . . . . 11 66 5.2. OctetString . . . . . . . . . . . . . . . . . . . . . . . 11 67 5.3. Opaque . . . . . . . . . . . . . . . . . . . . . . . . . . 12 68 5.4. IpAddress . . . . . . . . . . . . . . . . . . . . . . . . 13 69 5.5. ObjectIdentifier . . . . . . . . . . . . . . . . . . . . . 13 70 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 71 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 72 7.1. SMI Base Datatypes Namespace Registration . . . . . . . . 16 73 7.2. SMI Base Datatypes Schema Registration . . . . . . . . . . 16 74 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17 75 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 76 9.1. Normative References . . . . . . . . . . . . . . . . . . . 18 77 9.2. Informational References . . . . . . . . . . . . . . . . . 18 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19 80 1. Introduction 82 Numerous use cases exist for expressing the management information 83 described by SMI Management Information Base (MIB) modules in XML 84 [XML]. Potential use cases reside both outside and within the 85 traditional IETF network management community. For example, 86 developers of some XML-based management applications may want to 87 incorporate the rich set of data models provided by MIB modules. 88 Developers of other XML-based management applications may want to 89 access MIB module instrumentation via gateways to SNMP agents. Such 90 applications benefit from the IETF standard mapping of SMI datatypes 91 to XML datatypes via XSD [XMLSchema], [XSDDatatypes]. 93 MIB modules use SMIv2 [RFC2578] to describe data models. For legacy 94 MIB modules, SMIv1 [RFC1155] was used. MIB data conveyed in variable 95 bindings ("varbinds") within protocol data units (PDUs) of SNMP 96 messages use the primitive, base datatypes defined by the SMI. 98 The SMI allows for the creation of derivative datatypes, "textual 99 conventions" ("TCs") [RFC2579]. A TC has a unique name, has a syntax 100 that either refines or is a base SMI datatype and has relatively 101 precise application-level semantics. TCs facilitate correct 102 application-level handling of MIB data, improve readability of MIB 103 modules by humans and support appropriate renderings of MIB data. 105 Values in varbinds corresponding to MIB objects defined with TC 106 syntax are always encoded as the base SMI datatype underlying the TC 107 syntax. Thus, the XSD mappings defined in this memo provide support 108 for values of MIB objects defined with TC syntax as well as for 109 values of MIB objects defined with base SMI syntax. 111 Various independent schemes have been devised for expressing SMI 112 datatypes in XSD. These schemes exhibit a degree of commonality, 113 especially concerning numeric SMI datatypes, but these schemes also 114 exhibit sufficient differences, especially concerning the non-numeric 115 SMI datatypes, precluding uniformity of expression and general 116 interoperability. 118 Throughout this memo, the term "fidelity" refers to the quality of an 119 accurate, consistent representation of SMI data values and the term 120 "faithful" refers to the quality of reliably reflecting the semantics 121 of SMI data values. Thus defined, the characteristics of fidelity 122 and being faithful are essential to uniformity of expression and 123 general interoperability in the XML representation of SMI data 124 values. 126 The primary purpose of this memo is to define the standard expression 127 of SMI base datatypes in XML documents that is both uniform and 128 interoperable. This standard expression enables Internet operators, 129 management application developers, and users to benefit from a wider 130 range of management tools and to benefit from a greater degree of 131 unified management. Thus, standard expression enables and 132 facilitates improvements to the timeliness, accuracy and utility of 133 management information. 135 The overall objective of this memo, and of any related future memos 136 as may be published, is to define the XSD equivalent [XSDDatatypes] 137 of SMIv2 (STD58) and to encourage XML-based protocols to carry, and 138 XML-based applications to use, the management information defined in 139 SMIv2-compliant MIB modules. The use of a standard mapping from 140 SMIv2 to XML via XSD validation enables and promotes the efficient 141 reuse of existing and future MIB modules and instrumentation by XML- 142 based protocols and management applications. 144 Developers of certain XML-based management applications will find 145 this specification sufficient for their purposes. Developers of 146 other XML-based management applications may need to make more 147 complete reuse of existing MIB modules, requiring standard XSD 148 documents for TCs [RFC2579] and MIB structure [RFC2578]. Memos 149 supporting such requirements are planned, but have not been produced 150 at the time of this writing. 152 Finally, it is worthwhile to note that the goal of fidelity to the 153 SMIv2 standard (STD58), as specified in the "Requirements" section 154 below, is crucial to this effort. Fidelity leverages the established 155 "rough consensus" of the precise SMIv2 data models contained in MIB 156 modules, and leverages existing instrumentation, the "running code" 157 implementing SMIv2 data models. This effort does not include any 158 redesign of SMIv2 datatypes, data structures or textual conventions 159 in order to overcome known limitations. Such work can be pursued by 160 other efforts. 162 2. Conventions 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 166 document are to be interpreted as described in RFC 2119 [RFC2119]. 168 3. Requirements 170 The following set of requirements is intended to produce XML 171 documents which can be validated via the XSD defined in this 172 specification to faithfully represent values carried "on-the-wire" in 173 SNMP PDUs as defined by the SMI: 175 R1. All SMI base datatypes MUST have a corresponding XSD datatype. 177 R2. SMIv2 is the normative SMI for this document. Prior to mapping 178 datatypes into XSD, legacy SMIv1 modules MUST be converted (at 179 least logically) in accordance with Section 2.1, inclusive, of 180 the "Coexistence" RFC [RFC3584]. 182 R3. The XSD datatype specified for a given SMI datatype MUST be able 183 to represent all valid values for that SMI datatype. 185 R4. The XSD datatype specified for a given SMI datatype MUST 186 represent any special encoding rules associated with that SMI 187 datatype. 189 R5. The XSD datatype specified for a given SMI datatype MUST include 190 any restrictions on values associated with the SMI datatype. 192 R6. The XSD datatype specified for a given SMI datatype MUST be the 193 most logical XSD datatype, with the fewest necessary 194 restrictions on its set of values, consistent with the foregoing 195 requirements. 197 R7. The XML output produced as a result of meeting the foregoing 198 requirements SHOULD be the most coherent and succinct 199 representation (i.e., avoiding superfluous "decoration") from 200 the perspective of readability by humans. 202 4. XSD for SMI Base Datatypes 204 This document provides XSD datatype mappings for the SMIv2 base 205 datatypes only -- i.e., the eleven "ObjectSyntax" datatypes defined 206 in RFC 2578. These datatypes -- via tag values defined in the SMIv2 207 to identify them in varbinds -- constrain values carried "on-the- 208 wire" in SNMP PDUs between SNMP management applications and SNMP 209 agents: 211 o INTEGER, Integer32 213 o Unsigned32, Gauge32 215 o Counter32 217 o TimeTicks 219 o Counter64 221 o OCTET STRING 223 o Opaque 225 o IpAddress 227 o OBJECT IDENTIFIER 229 The "BITS" pseudo-type (also referred to as a "construct" in RFC 230 2578) is treated as a Textual Convention, not a base datatype, for 231 the purpose of this document. 233 BEGIN 235 236 243 244 245 Mapping of SMIv2 base datatypes from RFC 2578 247 Contact: Mark Ellison 248 Organization: Ellison Software Consulting 249 Address: 38 Salem Road 250 Atkinson, NH 03811 251 USA 252 Telephone: +1 603-362-9270 253 E-Mail: ietf@EllisonSoftware.com 255 Contact: Bob Natale 256 Organization: MITRE 257 Address: 300 Sentinel Drive 258 6th Floor 259 Annapolis Junction MD 20701 260 USA 261 Telephone: +1 301-617-3008 262 E-Mail: rnatale@mitre.org 264 Last Updated: 201002260000Z 266 Copyright (c) 2010 IETF Trust and the persons 267 identified as the document authors. All rights 268 reserved. 270 Redistribution and use in source and binary forms, 271 with or without modification, is permitted pursuant 272 to, and subject to the license terms contained in, 273 the Simplified BSD License set forth in Section 274 4.c of the IETF Trust's Legal Provisions Relating to 275 IETF Documents (http://trustee.ietf.org/license-info). 277 This version of this XML Schema Definition (XSD) 278 document is part of RFC XXXX; see the RFC itself for 279 full legal notices." 280 RFC Editor - please replace XXXX with the value allocated 281 for publication as an RFC. 283 284 286 287 288 290 291 292 294 295 296 298 299 300 302 303 304 306 307 308 310 311 312 314 315 316 317 318 320 321 322 324 325 326 333 334 336 337 338 342 343 345 346 END 348 5. Rationale 350 The XSD datatypes, including any specified restrictions, were chosen 351 based on fit with the requirements specified earlier in this 352 document, and with attention to simplicity while maintaining fidelity 353 to the SMI. Also, the "canonical representations" (i.e., refinements 354 of the "lexical representations") documented in the W3C XSD 355 specification [XMLSchema], [XSDDatatypes] are assumed. 357 5.1. Numeric Datatypes 359 All of the numeric XSD datatypes specified in the previous section -- 360 INTEGER, Integer32, Unsigned32, Gauge32, Counter32, TimeTicks, and 361 Counter64 -- comply with the relevant requirements 363 o They cover all valid values for the corresponding SMI datatypes. 365 o They comply with the standard encoding rules associated with the 366 corresponding SMI datatypes. 368 o They inherently match the range restrictions associated with the 369 corresponding SMI datatypes. 371 o They are the most direct XSD datatypes which exhibit the foregoing 372 characteristics relative to the corresponding SMI datatypes (which 373 is why no "restriction" statements -- other than the "base" XSD 374 type -- are required in the XSD). 376 o The XML output produced from the canonical representation of these 377 XSD datatypes is also the most direct from the perspective of 378 readability by humans (i.e., no leading "+" sign and no leading 379 zeros). 381 Special note to application developers: Compliance with this schema 382 in an otherwise correct translation from raw ("on-the-wire" 383 representation) SNMP MIB data produces values that are faithful to 384 the original. However, the Gauge32, Counter32, Counter64, and 385 TimeTicks datatypes have special application semantics that must be 386 considered when using their raw values for anything other than 387 display, printing, storage, or transmission of the literal value. 388 RFC 2578 provides the necessary details. 390 5.2. OctetString 392 This XSD datatype corresponds to the SMI "OCTET STRING" datatype. 394 Several independent schemes for mapping SMI datatypes to XSD have 395 used the XSD "string" type to represent "OCTET STRING", but this 396 mapping does not conform to the requirements specified in this 397 document. Most notably, "string" cannot faithfully represent all 398 valid values (0 thru 255) that each octet in an "OCTET STRING" can 399 have -- or at least cannot do so in a way that provides for easy 400 human readability of the resulting XML output. 402 Consequently, the XSD datatype "hexBinary" is specified as the 403 standard mapping of the SMI "OCTET STRING" datatype. In hexBinary, 404 each octet is encoded as two hexadecimal digits; the canonical 405 representation limits the set of allowed hexadecimal digits to 0-9 406 and uppercase A-F. 408 The hexBinary representation of "OCTET STRING" complies with the 409 relevant requirements: 411 o It covers all valid values for the corresponding SMI datatype. 413 o It complies with the standard encoding rules associated with the 414 corresponding SMI datatype. 416 o With the "maxLength" restriction to 65535 octets, the XSD datatype 417 specification matches the restrictions associated with the 418 corresponding SMI datatype. 420 o It is the most direct XSD datatype which exhibits the foregoing 421 characteristics relative to the corresponding SMI datatype (which 422 must allow for any valid binary octet value). 424 o The XML output produced from the canonical representation of this 425 XSD datatype is not optimal with respect to readability by humans; 426 however, that is a consequence of the SMI datatype itself. Where 427 human readability is more of a concern, it is likely that the 428 actual MIB objects in question will be represented by textual 429 conventions which limit the set of values that will be included in 430 the OctetStrings and will, thus, bypass the hexBinary typing. 432 5.3. Opaque 434 The "hexBinary" XSD datatype is specified as the representation of 435 the SMI "Opaque" datatype generally for the same reasons as 436 "hexBinary" is specified for the "OctetString" datatype: 438 o It covers all valid values for the corresponding SMI datatype. 440 o It complies with the standard encoding rules associated with the 441 corresponding SMI datatype. 443 o There are no restriction issues associated with using "hexBinary" 444 for "Opaque". 446 o It is the most direct XSD datatype which exhibits the foregoing 447 characteristics relative to the corresponding SMI datatype (which 448 must allow for any valid binary octet value). 450 o The XML output produced from the canonical representation of this 451 XSD datatype is not optimal with respect to readability by humans; 452 however, that is a consequence of the SMI datatype itself. 453 Unmediated "Opaque" data is intended for consumption by 454 applications, not humans. 456 5.4. IpAddress 458 The XSD "string" datatype is the natural choice to represent an 459 IpAddress as XML output. The "pattern" restriction applied in this 460 case results in a dotted-decimal string of four values between "0" 461 and "255" separated by a period (".") character. This pattern also 462 precludes leading zeros. 464 Note that the SMI relies upon Textual Conventions (TCs) to specify an 465 IPv6 address. As such, the representation of an IPv6 address as an 466 XSD datatype is beyond the scope of this document. 468 5.5. ObjectIdentifier 470 This XSD datatype corresponds to the SMI "OBJECT IDENTIFIER" 471 datatype. 473 The XSD "string" datatype is also the natural choice to represent an 474 ObjectIdentifier as XML output, for the same reasons as for the 475 IpAddress choice. The "pattern" restriction applied in this case 476 results in a dotted-decimal string of up to 128 elements (referred to 477 as "sub-ids"), each holding an "Unsigned32" integer value. 479 Note that the first two components of an "OBJECT IDENTIFIER" each 480 have a limited range of values as indicated in the XSD pattern 481 restriction and as described in The ASN1.1/BER standard [ASN.1]. 483 There are three values allocated for the root node, and at most 39 484 values for nodes subordinate to a root node value of 0 or 1. 486 The minimum length of an "OBJECT IDENTIFIER" is two sub-ids and the 487 representation of a zero-valued "OBJECT IDENTIFIER" is "0.0". 489 Note that no explicit "minLength" restriction, which would be "3" to 490 allow for the minimum of two sub-ids and a single separating dot, is 491 required since the pattern itself enforces this restriction. 493 6. Security Considerations 495 Security considerations for any given SMI MIB module are likely to be 496 relevant to any XSD/XML mapping of that MIB module; however, the 497 mapping defined in this document does not itself introduce any new 498 security considerations. 500 If and when proxies or gateways are developed to convey SNMP 501 management information from SNMP agents to XML-based management 502 applications via XSD/XML mapping of MIB modules based on this 503 specification and its planned siblings, special care will need to be 504 taken to ensure that all applicable SNMP security mechanisms are 505 supported in an appropriate manner yet to be determined. 507 7. IANA Considerations 509 In accordance with RFC 3688 [RFC3688], we request the following 510 namespace and schema registrations associated with this document in 511 the IANA XML Registry: 513 o urn:ietf:params:xml:ns:opsawg:smi:base:[version_id] 515 o urn:ietf:params:xml:schema:opsawg:smi:base:[version_id] 517 7.1. SMI Base Datatypes Namespace Registration 519 This document registers a URI for the SMI Base Datatypes XML 520 namespace in the IETF XML registry. Following the format in RFC 521 3688, IANA has made the following registration: 523 URI: urn:ietf:params:xml:ns:opsawg:smi:base:1.0 525 Registration Contact: The IESG. 527 XML: N/A, the requested URI is an XML namespace. 529 7.2. SMI Base Datatypes Schema Registration 531 This document registers a URI for the SMI Base Datatypes XML schema 532 in the IETF XML registry. Following the format in RFC 3688, IANA has 533 made the following registration: 535 URI: urn:ietf:params:xml:schema:opsawg:smi:base:1.0 537 Registration Contact: The IESG. 539 XML: Section 4 of this document. 541 8. Acknowledgements 543 Dave Harrington provided strategic and technical leadership to the 544 team which developed this particular specification. Yan Li did much 545 of the research into existing approaches that was used as a baseline 546 for the recommendations in this particular specification. 548 This document owes much to draft-romascanu-netconf-datatypes-xx and 549 to many other sources (including libsmi and group discussions on the 550 NETCONF mailing lists) developed by those who have researched and 551 published candidate mappings of SMI datatypes to XSD. 553 Individuals who participated in various discussions of this topic at 554 IETF meetings and on IETF mailing lists include: Ray Atarashi, 555 Yoshifumi Atarashi, Andy Bierman, Sharon Chisholm, Avri Doria, Rob 556 Ennes, Mehmet Ersue, David Harrington, Alfred Hines, Eliot Lear, 557 Chris Lonvick, Faye Ly, Randy Presuhn, Juergen Schoenwaelder, Andre 558 Westerinen, and Bert Wijnen. 560 9. References 562 9.1. Normative References 564 [RFC1155] Rose, M. and K. McCloghrie, "Structure and identification 565 of management information for TCP/IP-based internets", 566 STD 16, RFC 1155, May 1990. 568 [RFC2119] Bradner, s., "Key words for use in RFCs to Indicate 569 Requirement Levels", BCP 14, RFC 2119, March 1997. 571 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 572 Schoenwaelder, Ed., "Structure of Management Information 573 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 575 [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 576 "Coexistence between Version 1, Version 2, and Version 3 577 of the Internet-standard Network Management Framework", 578 BCP 74, RFC 3584, August 2003. 580 [XML] World Wide Web Consortium, "Extensible Markup Language 581 (XML) 1.0", W3C XML, February 1998, 582 . 584 [XMLSchema] 585 World Wide Web Consortium, "XML Schema Part 1: Structures 586 Second Edition", W3C XML Schema, October 2004, 587 . 589 [XSDDatatypes] 590 World Wide Web Consortium, "XML Schema Part 2: Datatypes 591 Second Edition", W3C XML Schema, October 2004, 592 . 594 9.2. Informational References 596 [ASN.1] International Organization for Standardization, 597 "Information processing systems - Open Systems 598 Interconnection - Specification of Basic Encoding Rules 599 for Abstract Syntax Notation One (ASN.1)", International 600 Standard 8825, December 1987. 602 [RFC2579] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 603 "Textual Conventions for SMIv2", STD 58, RFC 2579, 604 April 1999. 606 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 607 January 2004. 609 Authors' Addresses 611 Mark Ellison 612 Ellison Software Consulting 613 38 Salem Road 614 Atkinson, NH 03811 615 USA 617 Phone: +1 603-362-9270 618 Email: ietf@ellisonsoftware.com 620 Bob Natale 621 MITRE 622 300 Sentinel Drive 623 6th Floor 624 Annapolis Junction, MD 20701 625 USA 627 Phone: +1 301-617-3008 628 Email: rnatale@mitre.org