idnits 2.17.1 draft-ietf-mile-template-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC5070]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (February 16, 2012) is 4446 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5070 (Obsoleted by RFC 7970) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 6045 (Obsoleted by RFC 6545) -- Obsolete informational reference (is this intentional?): RFC 2373 (Obsoleted by RFC 3513) -- Obsolete informational reference (is this intentional?): RFC 2396 (Obsoleted by RFC 3986) -- Obsolete informational reference (is this intentional?): RFC 2822 (Obsoleted by RFC 5322) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 mile Working Group B. Trammell 3 Internet-Draft ETH Zurich 4 Intended status: BCP February 16, 2012 5 Expires: August 19, 2012 7 Guidelines for Extensions to IODEF for Managed Incident Lightweight 8 Exchange 9 draft-ietf-mile-template-01.txt 11 Abstract 13 This document provides guidelines for extensions to IODEF [RFC5070] 14 for exchange of incident management data, and contains a template for 15 Internet-Drafts describing those extensions, in order to ease the 16 work and improve the quality of extension descriptions. It also 17 specifies additional Expert Review of XML Schemas used to describe 18 these extensions. 20 Status of this Memo 22 This Internet-Draft is submitted 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). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 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 This Internet-Draft will expire on August 19, 2012. 37 Copyright Notice 39 Copyright (c) 2012 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Applicability of Extensions to IODEF . . . . . . . . . . . . . 3 56 3. Selecting a Mechanism for IODEF Extension . . . . . . . . . . 4 57 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 58 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 59 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 6 60 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 7.1. Normative References . . . . . . . . . . . . . . . . . . . 6 62 7.2. Informative References . . . . . . . . . . . . . . . . . . 7 63 Appendix A. Document Template . . . . . . . . . . . . . . . . . . 7 64 A.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 7 65 A.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 66 A.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 8 67 A.4. Extension Definition . . . . . . . . . . . . . . . . . . . 8 68 A.4.1. IODEF Data Types . . . . . . . . . . . . . . . . . . . 9 69 A.5. Security Considerations . . . . . . . . . . . . . . . . . 10 70 A.6. IANA Considerations . . . . . . . . . . . . . . . . . . . 10 71 A.7. Appendix A: XML Schema Definition for Extension . . . . . 11 72 A.8. Appendix B: Examples . . . . . . . . . . . . . . . . . . . 11 73 Appendix B. Example Enumerated Type Extension Definition: 74 E.164 Address . . . . . . . . . . . . . . . . . . . . 11 75 Appendix C. Example Element Definition: Test . . . . . . . . . . 12 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 78 1. Introduction 80 In the five years since the specification of IODEF [RFC5070], the 81 threat environment has evolved, as has the practice of cooperative 82 network defense. These trends, along with experience gained through 83 implementation and deployment, have indicated the need to extend 84 IODEF. This document provides guidelines for defining these 85 extensions. It starts by describing the applicability of IODEF 86 extensions, and the IODEF extension mechanisms, before providing a 87 section Appendix A that is itself designed to be copied out and 88 filled in as the starting point of an Internet-Draft about an IODEF 89 extension. 91 Additionally, IODEF extensions through AdditionalData and RecordItem 92 elements, as per section 5.2 of [RFC5070], generally register their 93 namespaces and schemas with the IANA XML Namespace registry at 94 http://www.iana.org/assignments/xml-registry/ns.html and the IANA XML 95 Schema registry at 96 http://www.iana.org/assignments/xml-registry/schema.html, 97 respectively [RFC3688]. In addition to schema reviews required by 98 IANA, these registry requests should be accompanied by a review by 99 IODEF experts to ensure the specified AdditionalData and/or 100 RecordItem contents are compatible with IODEF and with other existing 101 IODEF extensions. This document specifies that review in Section 5. 103 2. Applicability of Extensions to IODEF 105 Before deciding to extend IODEF, the first step is to determine 106 whether an IODEF extension is a good fit for a given problem. There 107 are two sides to this question: 109 1. Does the problem involve the reporting or sharing of information 110 about an incident? "Incident" is not defined in the terminology 111 for IODEF, but for purposes of IODEF can be loosely described as 112 "something that happened that has some impact on the information 113 security situation of an entity", with quite a bit of leeway for 114 interpretation. If the answer to this question is unequivocally 115 "No", then IODEF is probably not a good choice as a base 116 technology for the application area. 118 2. Can IODEF adequately represent information about the incident 119 without extension? IODEF has a reasonably rich set of incident- 120 relevant classes. If, after examination of the problem area and 121 the IODEF specification, the answer to this question is "Yes", 122 then extension is not necessary. 124 A non-exhaustive list of good candidate extensions to IODEF includes: 126 o Leveraging existing work in describing aspects of incidents to 127 make IODEF more expressive, by standardized reference to external 128 information bases about incidents and incident-related information 130 o Allowing the description of new types of entities (e.g., related 131 actors) or new types of characteristics of entities (e.g., 132 information related to financial services) involved in an IODEF 133 incident report 135 o Allowing additional semantic or metadata labeling of IODEF 136 Documents (e.g., for handling or disposition instructions, or 137 compliance with data protection and data retention regulations) 139 3. Selecting a Mechanism for IODEF Extension 141 IODEF was designed to be extended through any combination of: 143 1. extending the enumerated values of Attributes, as per section 5.1 144 of [RFC5070]; 146 2. class extension through AdditionalData and RecordItem elements, 147 as per section 5.2 of [RFC5070]; and/or 149 3. containment of the IODEF-Document element within an external XML 150 Document, itself containing extension data. 152 Note that in this final case, the extension will not be directly 153 interoperable with IODEF implementations, and must "unwrap" the IODEF 154 document from its container; nevertheless, this may be appropriate 155 for certain use cases involving integration with IODEF within 156 external schemas. Extensions using containment of an IODEF-Document 157 are not further treated in this document, though the document 158 template in Appendix A may be of some use in defining them. 160 Certain attributes containing enumerated values within certain IODEF 161 elements may be extended. For an attribute named "foo", this is 162 achieved by giving the value of "foo" as "ext-value", and adding a 163 new attribute named "ext-foo" containing the extended value. The 164 attributes which can be extended in this way are defined in Section 165 5.1 of [RFC5070], and limited to the following: 167 o Incident@purpose 169 o Contact@role 171 o Contact@type 172 o RegistryHandle@registry 174 o Impact@type 176 o TimeImpact@metric 178 o TimeImpact@duration 180 o HistoryItem@action 182 o Expectation@action 184 o System@category 186 o Counter@type 188 o Counter@duration 190 o Address@category 192 o NodeRole@category 194 o RecordPattern@type 196 o RecordPattern@offsetunit 198 o AdditionalData@dtype 200 o RecordItem@dtype 202 An example definition of an attribute extension is given in 203 Appendix B. 205 IODEF documents can contain extended scalar or XML data using an 206 AdditionalData element or a RecordItem element. Scalar data 207 extensions MUST set the "dtype" attribute of the containing element 208 to the data type to reference one of the IODEF data types as 209 enumerated in Appendix A.4.1, and SHOULD define the use the "meaning" 210 and "formatid" attributes to explain the content of the element. 212 XML extensions within an AdditionalData or RecordItem element use a 213 dtype of "xml", and SHOULD define a schema for the root element 214 within the AdditionalData or RecordItem attribute. An example 215 definition of an element definition is given in Appendix C. 217 4. Security Considerations 219 This document defines a template for extensions to IODEF; the 220 security considerations for IODEF [RFC5070] apply. 222 5. IANA Considerations 224 Changes to the XML Schema registry for schema names beginning with 225 "urn:ietf:params:xml:schema:iodef" are subject to an additional IODEF 226 Expert Review [RFC5226]. The IODEF expert(s) for these reviews will 227 be designated by the IETF Security Area Directors. 229 [IANA NOTE: The authors request that IANA include a note at the top 230 of http://www.iana.org/assignments/xml-registry/schema.html, stating 231 "Changes to the XML Schema registry for schema names beginning with 232 'urn:ietf:params:xml:schema:iodef' are subject to an additional IODEF 233 Expert Review [RFC5226]," and naming the designated expert.] 235 6. Acknowledgments 237 Thanks to David Black, Takeshi Takahashi, Tom Millar, and Kathleen 238 Moriarty for their comments. This work is materially supported by 239 the European Union Seventh Framework Program under grant agreement 240 257315 (DEMONS). 242 7. References 244 7.1. Normative References 246 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 247 January 2004. 249 [RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident 250 Object Description Exchange Format", RFC 5070, 251 December 2007. 253 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 254 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 255 May 2008. 257 [RFC6045] Moriarty, K., "Real-time Inter-network Defense (RID)", 258 RFC 6045, November 2010. 260 7.2. Informative References 262 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 263 Requirement Levels", BCP 14, RFC 2119, March 1997. 265 [RFC2373] Hinden, R. and S. Deering, "IP Version 6 Addressing 266 Architecture", RFC 2373, July 1998. 268 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 269 Resource Identifiers (URI): Generic Syntax", RFC 2396, 270 August 1998. 272 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, 273 April 2001. 275 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 276 Internet: Timestamps", RFC 3339, July 2002. 278 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 279 Text on Security Considerations", BCP 72, RFC 3552, 280 July 2003. 282 [RFC4519] Sciberras, A., "Lightweight Directory Access Protocol 283 (LDAP): Schema for User Applications", RFC 4519, 284 June 2006. 286 [RFC6116] Bradner, S., Conroy, L., and K. Fujiwara, "The E.164 to 287 Uniform Resource Identifiers (URI) Dynamic Delegation 288 Discovery System (DDDS) Application (ENUM)", RFC 6116, 289 March 2011. 291 Appendix A. Document Template 293 The document template given in this section is provided as a starting 294 point for writing an Internet-Draft describing an IODEF extension. 296 A.1. Introduction 298 The introduction section introduces the problem being solved by the 299 extension, and motivates the development and deployment of the 300 extension. 302 A.2. Terminology 304 The terminology section introduces and defines terms specific to the 305 document. Terminology from [RFC5070] or [RFC6045] should be 306 referenced in this section, but not redefined or copied. If 308 [RFC2119] terms are used in the document, this should be noted in the 309 terminology section. 311 A.3. Applicability 313 The applicability section defines the use cases to which the 314 extension is applicable, and details any requirements analysis done 315 during the development of the extension. The primary goal of this 316 section is to allow readers to see if an extension is indeed intended 317 to solve a particular problem. This should also the scope of the 318 extension, as appropriate, by pointing out any non-obvious situations 319 to which it is not intended to apply. 321 In addition to defining the applicability, this section may also 322 present example situations, which should then be detailed in the 323 examples section, below. 325 A.4. Extension Definition 327 This section defines the extension. 329 Extensions to enumerated types are defined in one subsection for each 330 attribute to be extended, enumerating the new values with an 331 explanation of the meaning of the new value. An example enumeration 332 extension is shown in Appendix B, below. 334 Element extensions are defined in one subsection for each element, in 335 top-down order, from the element contained within AdditionalData or 336 RecordItem; an example element extension is shown in Appendix C, 337 below. Each element should be described by a UML diagram as in 338 Figure 1, followed by a description of each of the attributes, and a 339 short description of each of the child elements. Child elements 340 should then be defined in a subsequent subsection, if not already 341 defined in the IODEF document itself, or in another referenced MILE 342 extension document. 344 +---------------------+ 345 | Element | 346 +---------------------+ 347 | TYPE attribute0 |<>----------[ChildExactlyOne] 348 | TYPE attribute1 |<>--{0..1}--[ChildZeroOrOne] 349 | |<>--{0..*}--[ChildZeroOrMore] 350 | |<>--{1..*}--[ChildOneOrMore] 351 +---------------------+ 353 Figure 1: Example UML Element Diagram 355 Elements containing child elements should indicate the multiplicity 356 of those child elements, as shown in the figure above. Allowable 357 TYPEs are discussed in the following subsection. 359 A.4.1. IODEF Data Types 361 The allowable TYPEs for attributes within IODEF are enumerated in 362 section 2 of [RFC5070], and consist of: 364 o INTEGER 366 o REAL 368 o CHARACTER 370 o STRING 372 o ML_STRING (for strings in encodings other than that of the 373 enclosing document) 375 o BYTE for bytes or byte vectors in Base 64 encoding 377 o HEXBIN for bytes in ascii-hexadecimal encoding 379 o ENUM for enumerated types; allowable values of the enumeration 380 must be defined in the attribute definition 382 o DATETIME for ISO 8601:2000 [RFC3339] encoded timestamps 384 o TIMEZONE for timezones as encoded in section 2.9 of [RFC5070]. 386 o PORTLIST for port lists as encoded in section 2.10 of [RFC5070]. 388 o POSTAL for postal addresses as defined in section 2.23 of 389 [RFC4519]. 391 o NAME for names of natural or legal persons as defined in section 392 2.3 of [RFC4519]. 394 o PHONE for telephone numbers as defined in section 2.35 of 395 [RFC4519]. 397 o EMAIL for email addresses as defined in section 3.4.1. of 398 [RFC2822]. 400 o URL for URLs as in [RFC2396]. 402 In addition to these simple data types, IODEF provides a compound 403 data type for representing network address information. Addresses 404 included within an extension element should be represented by 405 containing an IODEF:Address element, which supports IPv4 and 406 [RFC2373] IPv6 addresses, as well as MAC, ATM, and BGP autonomous 407 system numbers. Application-layer addresses should be represented 408 with the URL simple attribute type, instead. 410 A.5. Security Considerations 412 [SECDIR and RFC-EDITOR NOTE: Despite the title, this section is NOT a 413 Security Considerations section, rather a template Security 414 Considerations section for future extension documents to be built 415 from this template. See Section 4 for Security Considerations for 416 this document.] 418 Any security considerations [RFC3552] raised by this extension or its 419 deployment should be detailed in this section. Guidance should focus 420 on ensuring the users of this extension do so in a secure fashion, 421 with special attention to non-obvious implications of the 422 transmission of the information represented by an extension. 424 It should also be noted in this section that the security 425 considerations for IODEF [RFC5070] apply to the extension as well. 427 A.6. IANA Considerations 429 [IANA and RFC-EDITOR NOTE: Despite the title, this section is NOT an 430 IANA Considerations section, rather a template IANA Considerations 431 section for future extension documents to be built from this 432 template. See Section 5 for IANA Considerations for this document.] 434 Any IANA considerations [RFC5226] for the document should be detailed 435 in this section; if none, the section should exist and contain the 436 text "this document has no actions for IANA". 438 IODEF Extensions which represent an enumeration should reference an 439 existing IANA registry or subregistry for the values of that 440 enumeration. If no such registry exists, this section should define 441 a new registry to hold the enumeration's values, and define the 442 policies by which additions may be made to the registry. 444 IODEF Extensions adding elements to the AdditionalData section of an 445 IODEF document should register their own namespaces and schemas for 446 extensions with IANA; therefore, this section should contain at least 447 a registration request for the namespace and the schema, as follows, 448 modified as appropriate for the extension: 450 Registration request for the IODEF My-Extension namespace: 452 URI: urn:ietf:params:xml:ns:iodef-myextension-1.0 454 Registrant Contact: Refer here to the authors' addresses section of 455 the document, or to an organizational contact in the case of an 456 extension supported by an external organization. 458 XML: None 460 Registration request for the IODEF My-Extension XML schema: 462 URI: urn:ietf:params:xml:schema:iodef-myextension-1.0 464 Registrant Contact: Refer here to the authors' addresses section of 465 the document, or to an organizational contact in the case of an 466 extension supported by an external organization. 468 XML: Refer here to the XML Schema in the appendix of the document, 469 or to a well-known external reference in the case of an extension 470 with an externally-defined schema. 472 A.7. Appendix A: XML Schema Definition for Extension 474 The XML Schema describing the elements defined in the Extension 475 Defintion section is given here. Each of the examples in section 476 Appendix A.8 should be verified to validate against this schema by 477 automated tools. 479 A.8. Appendix B: Examples 481 This section contains example IODEF-Documents illustrating the 482 extension. If example situations are outlined in the applicability 483 section, documents for those examples should be provided in the same 484 order as in the applicability section. Example documents should be 485 tested to validate against the schema given in the appendix. 487 Appendix B. Example Enumerated Type Extension Definition: E.164 Address 489 This example extends the IODEF Address element to support the 490 encoding of ENUM-mapped telephone numbers [RFC6116]. 492 Attribute: Address@category 494 Extended value(s): enum-e164 496 Value meaning and format: An E.164 telephone number encoded as a 497 domain name in the e164.int space, e.g. 498 "2.1.2.1.5.5.5.2.1.2.1.e164.int." for +1 212 555 1212, as per section 499 3.2 of [RFC6116]. 501 Additional considerations: none. 503 Appendix C. Example Element Definition: Test 505 This example defines the Test class for labeling IODEF test data. 507 The Test class is intended to be included within an AdditionalData 508 element in an IODEF Document. If a Test element is present, it 509 indicates that an IODEF Document contains test data, not a reference 510 to a real incident. 512 The Test class contains information about how the test data was 513 generated. 515 +---------------------+ 516 | Test | 517 +---------------------+ 518 | ENUM category | 519 | STRING generator | 520 | | 521 | | 522 +---------------------+ 524 Figure 2: The Test class 526 The Test class has two attributes: 528 category: Required. ENUM. The type of test data. The permitted 529 values for this attribute are shown below. The default value is 530 "unspecified". 532 1. unspecified. The document contains test data, but no further 533 information is available. 535 2. internal. The test data is intended for the internal use of 536 an implementor, and should not be distributed or used outside 537 the context in which it was generated. 539 3. unit. The test data is intended for unit testing of an 540 implementation, and may be included with the implementation to 541 support this as part of the build and deployment process. 543 4. interoperability. The test data is intended for 544 interoperability testing of an implementation, and may be 545 freely shared to support this purpose. 547 generator: Optional. STRING. A free-form string identifying the 548 person, entity, or program which generated the test data. 550 Author's Address 552 Brian Trammell 553 Swiss Federal Institute of Technology Zurich 554 Gloriastrasse 35 555 8092 Zurich 556 Switzerland 558 Phone: +41 44 632 70 13 559 Email: trammell@tik.ee.ethz.ch