idnits 2.17.1 draft-ietf-opsawg-smi-datatypes-in-xsd-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. 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 27, 2009) is 5502 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 287, but not defined == Missing Reference: '0-9' is mentioned on line 295, but not defined == Missing Reference: '0-5' is mentioned on line 287, but not defined == Missing Reference: '6-9' is mentioned on line 287, but not defined == Missing Reference: '3-9' is mentioned on line 288, but not defined == Missing Reference: '0-1' is mentioned on line 295, but not defined == Missing Reference: '1-3' is mentioned on line 295, but not defined Summary: 1 error (**), 0 flaws (~~), 8 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Natale 3 Internet-Draft MITRE 4 Intended status: Standards Track March 27, 2009 5 Expires: September 27, 2009 7 Expressing SNMP SMI Datatypes in XML Schema Definition Language 8 draft-ietf-opsawg-smi-datatypes-in-xsd-05.txt 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on September 27, 2009. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents in effect on the date of 40 publication of this document (http://trustee.ietf.org/license-info). 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. 44 Abstract 46 This memo defines the IETF standard expression of Structure of 47 Management Information (SMI) base datatypes in Extensible Markup 48 Language (XML) Schema Definition (XSD) language. The primary 49 objective of this memo is to enable the production of XML documents 50 that are as faithful to the SMI as possible, using XSD as the 51 validation mechanism. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 3. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 4. XSD for SMI Base Datatypes . . . . . . . . . . . . . . . . . . 7 59 5. Rationale . . . . . . . . . . . . . . . . . . . . . . . . . . 10 60 5.1. Numeric Datatypes . . . . . . . . . . . . . . . . . . . . 10 61 5.2. OctetString . . . . . . . . . . . . . . . . . . . . . . . 10 62 5.3. Opaque . . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 5.4. IpAddress . . . . . . . . . . . . . . . . . . . . . . . . 12 64 5.5. ObjectIdentifier . . . . . . . . . . . . . . . . . . . . . 12 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 66 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 67 7.1. SMI Base Datatypes Namespace Registration . . . . . . . . 14 68 7.2. SMI Base Datatypes Schema Registration . . . . . . . . . . 14 69 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 70 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 71 9.1. Normative References . . . . . . . . . . . . . . . . . . . 16 72 9.2. Informational References . . . . . . . . . . . . . . . . . 16 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 17 75 1. Introduction 77 Numerous uses exist -- both within and outside the traditional IETF 78 network management community -- for the expression of management 79 information described in and accessible via SMI Management 80 Information Base (MIB) modules as XML documents [XML]. For example, 81 XML-based management applications which want to incorporate MIB 82 modules as data models and/or to access MIB module instrumentation 83 via gateways to SNMP agents will benefit from an IETF standard 84 mapping of SMI datatypes to XML documents via XSD. 86 MIB data models are described using SMIv2 [RFC2578] and, for legacy 87 MIBs, SMIv1 [RFC1155]. MIB data is conveyed in variable bindings 88 ("varbinds") within protocol data units (PDUs) within SNMP messages 89 using the base/primitive datatypes defined in the SMI. 91 The SMI allows for creation of derivative datatypes, termed "textual 92 conventions" ("TCs"), each of which has a unique name, a syntax which 93 is or refines a primitive SMI datatype, and relatively precise 94 application-level semantics. TCs are used principally to facilitate 95 correct application-level handling of MIB data and for the 96 convenience of humans reading MIB modules and appropriately rendered 97 MIB data output. Values in varbinds corresponding to MIB objects 98 with TC syntaxes are always encoded as the primitive SMI datatype 99 underlying the TC syntax. Thus, the XSD mappings defined in this 100 memo will support MIB objects with TC syntax as well as those with 101 base SMI syntax. 103 Various independent schemes have been devised for expressing the SMI 104 datatypes in XSD [XMLSchema]. These schemes have exhibited a degree 105 of commonality (especially concerning the numeric SMI datatypes), but 106 also sufficient differences (especially concerning the non-numeric 107 SMI datatypes) to preclude uniformity and general interoperability. 109 The primary purpose of this memo is to define a standard expression 110 of SMI base datatypes in XSD to ensure fidelity, consistency, and 111 general interoperability in this respect. Internet operators, 112 management tool developers, and users will benefit from the wider 113 selection of management tools and the greater degree of unified 114 management -- with attendant improvements in timeliness and accuracy 115 of management information -- which such a standard facilitates. 117 On its own, this memo specifies the IETF standard way to render SMI 118 data values carried in SNMP messages as XML in a faithful, 119 consistent, and interoperable way. 121 Certain XML-based applications will find this specification 122 sufficient for their purposes. Other XML applications may need to 123 make more complete reuse of existing MIB modules, requiring standard 124 XSDs for TCs [RFC2579] and MIB structure [RFC2578]. Documents 125 supporting those requirements are planned, but have not been produced 126 at the time of this writing. 128 The objective of this memo, and of any future related specifications 129 that might be produced, is to define the XSD equivalent 130 [XSDDatatypes] of SMIv2 (STD58) to encourage XML-based protocols to 131 carry, and XML-based applications to use, the information modeled in 132 SMIv2-compliant MIB modules. 134 Having such a standard mapping of SMIv2 to XML via XSD validation 135 will enable and promote efficient reuse of existing (including 136 future) MIB modules and instrumentation by XML-based management 137 protocols and applications. 139 The goal of fidelity to the SMIv2 standard (STD58), as specified in 140 the "Requirements" section below, is crucial to this effort to 141 leverage the established "rough consensus" for the precise data 142 modeling used in MIB modules, and to leverage existing "running code" 143 for implemented SMIv2 data models. This effort does not include 144 redesign of SMIv2 datatypes or data structures or textual conventions 145 to overcome known limitations -- that work can be pursued in other 146 efforts. 148 2. Conventions 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 152 document are to be interpreted as described in RFC 2119 [RFC2119]. 154 3. Requirements 156 The following set of requirements is intended to produce XML 157 documents which can be validated via the XSD defined in this 158 specification to faithfully represent values carried "on-the-wire" in 159 SNMP PDUs as defined by the SMI: 161 R1. All SMI base datatypes MUST have a corresponding XSD datatype. 163 R2. SMIv2 is the normative SMI for this document -- SMIv1 modules, 164 if encountered, MUST be converted (at least logically) in 165 accordance with Section 2.1, inclusive, of the "Coexistence" RFC 166 [RFC3584]. 168 R3. The XSD datatype specified for a given SMI datatype MUST be able 169 to represent all valid values for that SMI datatype. 171 R4. The XSD datatype specified for a given SMI datatype MUST 172 represent any special encoding rules associated with that SMI 173 datatype. 175 R5. The XSD datatype specified for a given SMI datatype MUST include 176 any restrictions on values associated with the SMI datatype. 178 R6. The XSD datatype specified for a given SMI datatype MUST be the 179 most direct XSD datatype, with the most parsimonious 180 restrictions, which matches the foregoing requirements. 182 R7. The XML output produced as a result of meeting the foregoing 183 requirements SHOULD be the most direct (i.e., avoiding 184 superfluous "decoration") from the perspective of readability by 185 humans. 187 4. XSD for SMI Base Datatypes 189 This document provides XSD datatype mappings for the SMIv2 base 190 datatypes only -- i.e., the eleven "ObjectSyntax" datatypes defined 191 in RFC 2578. These datatypes -- via tag values defined in the SMIv2 192 to identify them in varbinds -- constrain values carried "on-the- 193 wire" in SNMP PDUs between SNMP management applications and SNMP 194 agents: 196 o INTEGER, Integer32 198 o Unsigned32, Gauge32 200 o Counter32 202 o TimeTicks 204 o Counter64 206 o OCTET STRING 208 o Opaque 210 o IpAddress 212 o OBJECT IDENTIFIER 214 The "BITS" pseudo-type (also referred to as a "construct" in RFC 215 2578) is treated as a Textual Convention, not a base datatype, for 216 the purpose of this document. 218 BEGIN 220 221 228 229 230 Mapping of SMIv2 base datatypes from RFC 2578 232 Contact: Bob Natale 233 Organization: MITRE 234 Address: 7515 Colshire Drive 235 McLean VA 22102 236 USA 237 Telephone: +1 703-983-2505 238 E-Mail: rnatale@mitre.org 239 Last Updated: 200903090000Z 240 241 243 244 245 247 248 249 251 252 253 255 256 257 259 260 261 263 264 265 266 267 268 270 271 272 273 274 276 277 278 280 281 282 289 290 292 293 294 298 299 301 302 END 304 5. Rationale 306 The XSD datatypes, including any specified restrictions, were chosen 307 based on fit with the requirements specified earlier in this 308 document, and with attention to simplicity while maintaining fidelity 309 to the SMI. Also, the "canonical representations" (i.e., refinements 310 of the "lexical representations") documented in the W3C XSD 311 specifications are assumed. 313 5.1. Numeric Datatypes 315 All of the numeric XSD datatypes specified in the previous section -- 316 INTEGER, Integer32, Unsigned32, Gauge32, Counter32, TimeTicks, and 317 Counter64 -- comply with the relevant requirements 319 o They cover all valid values for the corresponding SMI datatypes. 321 o They comply with the standard encoding rules associated with the 322 corresponding SMI datatypes. 324 o They inherently match the range restrictions associated with the 325 corresponding SMI datatypes. 327 o They are the most direct XSD datatypes which exhibit the foregoing 328 characteristics relative to the corresponding SMI datatypes (which 329 is why no "restriction" statements -- other than the "base" XSD 330 type -- are required in the XSD). 332 o The XML output produced from the canonical representation of these 333 XSD datatypes is also the most direct from the perspective of 334 readability by humans (i.e., no leading "+" sign and no leading 335 zeros). 337 Special note to application developers: Compliance with this schema 338 in an otherwise correct translation from raw ("on-the-wire" 339 representation) SNMP MIB data produces values that are faithful to 340 the original. However, the Gauge32, Counter32, Counter64, and 341 TimeTicks datatypes have special application semantics that must be 342 considered when using their raw values for anything other than 343 display, printing, storage, or transmission of the literal value. 344 RFC 2578 provides the necessary details. 346 5.2. OctetString 348 This XSD datatype corresponds to the SMI "OCTET STRING" datatype. 350 Several independent schemes for mapping SMI datatypes to XSD have 351 used the XSD "string" type to represent "OCTET STRING", but this 352 mapping does not conform to the requirements specified in this 353 document. Most notably, "string" cannot faithfully represent all 354 valid values (0 thru 255) that each octet in an "OCTET STRING" can 355 have -- or at least cannot do so in a way that provides for easy 356 human readability of the resulting XML output. 358 Consequently, the XSD datatype "hexBinary" is specified as the 359 standard mapping of the SMI "OCTET STRING" datatype. In hexBinary, 360 each octet is encoded as two hexadecimal digits; the canonical 361 representation limits the set of allowed hexadecimal digits to 0-9 362 and uppercase A-F. 364 The hexBinary representation of "OCTET STRING" complies with the 365 relevant requirements: 367 o It covers all valid values for the corresponding SMI datatype. 369 o It complies with the standard encoding rules associated with the 370 corresponding SMI datatype. 372 o With the "maxLength" restriction to 65535 octets, the XSD datatype 373 specification matches the restrictions associated with the 374 corresponding SMI datatype. 376 o It is the most direct XSD datatype which exhibits the foregoing 377 characteristics relative to the corresponding SMI datatype (which 378 must allow for any valid binary octet value). 380 o The XML output produced from the canonical representation of this 381 XSD datatype is not optimal with respect to readability by humans; 382 however, that is a consequence of the SMI datatype itself. Where 383 human readability is more of a concern, it is likely that the 384 actual MIB objects in question will be represented by textual 385 conventions which limit the set of values that will be included in 386 the OctetStrings and will, thus, bypass the hexBinary typing. 388 5.3. Opaque 390 The "hexBinary" XSD datatype is specified as the representation of 391 the SMI "Opaque" datatype generally for the same reasons as 392 "hexBinary" is specified for the "OctetString" datatype: 394 o It covers all valid values for the corresponding SMI datatype. 396 o It complies with the standard encoding rules associated with the 397 corresponding SMI datatype. 399 o There are no restriction issues associated with using "hexBinary" 400 for "Opaque". 402 o It is the most direct XSD datatype which exhibits the foregoing 403 characteristics relative to the corresponding SMI datatype (which 404 must allow for any valid binary octet value). 406 o The XML output produced from the canonical representation of this 407 XSD datatype is not optimal with respect to readability by humans; 408 however, that is a consequence of the SMI datatype itself. 409 Unmediated "Opaque" data is intended for consumption by 410 applications, not humans. 412 5.4. IpAddress 414 The XSD "string" datatype is the natural choice to represent an 415 IpAddress as XML output. The "pattern" restriction applied in this 416 case results in a dotted-decimal string of four values between "0" 417 and "255" separated by a period (".") character. This pattern also 418 precludes leading zeros. 420 5.5. ObjectIdentifier 422 This XSD datatype corresponds to the SMI "OBJECT IDENTIFIER" 423 datatype. 425 The XSD "string" datatype is also the natural choice to represent an 426 ObjectIdentifier as XML output, for the same reasons as for the 427 IpAddress choice. The "pattern" restriction applied in this case 428 results in a dotted-decimal string of up to 128 elements (referred to 429 as "sub-ids"), each holding an "Unsigned32" integer value. 431 Note that, while not mentioned in Sec. 7.1.3 of RFC 2578, due to the 432 use of Abstract Syntax Notation One (ASN.1) Basic Encoding Rules 433 (BER) the first two components of an "OBJECT IDENTIFIER" have limited 434 value ranges and are encoded into a single sub-id value [Steedman]. 435 The ASN.1/BER standards specify that the numerical value of the first 436 sub-identifier is derived from the values of the first two "OBJECT 437 IDENTIFIER" components in the value being encoded, using the formula: 438 (X*40) + Y, where X is the value of the first component and Y is the 439 value of the second component. This packing of the first two 440 components recognizes that only three values are allocated from the 441 root node, and at most 39 subsequent values from nodes reached by X = 442 0 and X = 1. The minimum length of an "OBJECT IDENTIFIER" is two 443 sub-ids (with a zero-valued "OBJECT IDENTIFIER" represented as 444 "0.0"). No explicit "minLength" restriction (which would be "3" to 445 allow for the minimum of two sub-ids and a single separating dot) is 446 required, since the pattern itself enforces this restriction. 448 6. Security Considerations 450 Security considerations for any given SMI MIB module are likely to be 451 relevant to any XSD/XML mapping of that MIB module; however, the 452 mapping defined in this document does not itself introduce any new 453 security considerations. 455 If and when proxies or gateways are developed to convey SNMP 456 management information from SNMP agents to XML-based management 457 applications via XSD/XML mapping of MIB modules based on this 458 specification and its planned siblings, special care will need to be 459 taken to ensure that all applicable SNMP security mechanisms are 460 supported in an appropriate manner yet to be determined. 462 7. IANA Considerations 464 In accordance with RFC 3688 [RFC3688], we request the following 465 namespace and schema registrations associated with this document in 466 the IANA XML Registry: 468 o urn:ietf:params:xml:ns:opsawg:smi:base:[version_id] 470 o urn:ietf:params:xml:schema:opsawg:smi:base:[version_id] 472 7.1. SMI Base Datatypes Namespace Registration 474 This document registers a URI for the SMI Base Datatypes XML 475 namespace in the IETF XML registry. Following the format in RFC 476 3688, IANA has made the following registration: 478 URI: urn:ietf:params:xml:ns:opsawg:smi:base:1.0 480 Registration Contact: The IESG. 482 XML: N/A, the requested URI is an XML namespace. 484 7.2. SMI Base Datatypes Schema Registration 486 This document registers a URI for the SMI Base Datatypes XML schema 487 in the IETF XML registry. Following the format in RFC 3688, IANA has 488 made the following registration: 490 URI: urn:ietf:params:xml:schema:opsawg:smi:base:1.0 492 Registration Contact: The IESG. 494 XML: Section 4 of this document. 496 8. Acknowledgements 498 Dave Harrington provided strategic and technical leadership to the 499 team which developed this particular specification. Yan Li did much 500 of the research into existing approaches that was used as a baseline 501 for the recommendations in this particular specification. 503 This document owes much to draft-romascanu-netconf-datatypes-xx and 504 to many other sources (including libsmi and group discussions on the 505 NETCONF mailing lists) developed by those who have researched and 506 published candidate mappings of SMI datatypes to XSD. 508 Individuals who participated in various discussions of this topic at 509 IETF meetings and on IETF mailing lists include: Ray Atarashi, 510 Yoshifumi Atarashi, Andy Bierman, Sharon Chisholm, Avri Doria, Mark 511 Ellison, Rob Ennes, Mehmet Ersue, David Harrington, Alfred Hines, 512 Eliot Lear, Chris Lonvick, Faye Ly, Randy Presuhn, Juergen 513 Schoenwaelder, Andre Westerinen, and Bert Wijnen. 515 9. References 517 9.1. Normative References 519 [RFC1155] Rose, M. and K. McCloghrie, "Structure and identification 520 of management information for TCP/IP-based internets", 521 STD 16, RFC 1155, May 1990. 523 [RFC2119] Bradner, s., "Key words for use in RFCs to Indicate 524 Requirement Levels", BCP 14, RFC 2119, March 1997. 526 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 527 Schoenwaelder, Ed., "Structure of Management Information 528 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 530 [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 531 "Coexistence between Version 1, Version 2, and Version 3 532 of the Internet-standard Network Management Framework", 533 BCP 74, RFC 3584, August 2003. 535 9.2. Informational References 537 [RFC2579] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 538 "Textual Conventions for SMIv2", STD 58, RFC 2579, 539 April 1999. 541 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 542 January 2004. 544 [Steedman] 545 Steedman, D., "ASN.1: The Tutorial and Reference". 547 [XML] World Wide Web Consortium, "Extensible Markup Language 548 (XML) 1.0", W3C XML, February 1998, 549 . 551 [XMLSchema] 552 World Wide Web Consortium, "XML Schema Part 1: Structures 553 Second Edition", W3C XML Schema, October 2004, 554 . 556 [XSDDatatypes] 557 World Wide Web Consortium, "XML Schema Part 2: Datatypes 558 Second Edition", W3C XML Schema, October 2004, 559 . 561 Author's Address 563 Bob Natale 564 MITRE 565 7515 Colshire Dr 566 MS H405 567 McLean, VA 22102 568 USA 570 Phone: +1 703-983-2505 571 Email: rnatale@mitre.org