idnits 2.17.1 draft-ietf-mile-template-05.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 date (June 8, 2012) is 4339 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5070 (Obsoleted by RFC 7970) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 2 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: Informational June 8, 2012 5 Expires: December 10, 2012 7 Guidelines and Template for Defining Extensions to IODEF 8 draft-ietf-mile-template-05.txt 10 Abstract 12 This document provides guidelines for extensions to the Incident 13 Object Description Exchange Format (IODEF) [RFC5070] for exchange of 14 incident management data, and contains a template for Internet-Drafts 15 describing those extensions, in order to ease the work and improve 16 the quality of extension descriptions. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on December 10, 2012. 35 Copyright Notice 37 Copyright (c) 2012 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Applicability of Extensions to IODEF . . . . . . . . . . . . . 3 54 3. Selecting a Mechanism for IODEF Extension . . . . . . . . . . 4 55 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 56 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 57 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 6 58 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 7.1. Normative References . . . . . . . . . . . . . . . . . . . 6 60 7.2. Informative References . . . . . . . . . . . . . . . . . . 6 61 Appendix A. Document Template . . . . . . . . . . . . . . . . . . 7 62 A.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 7 63 A.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 64 A.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 7 65 A.4. Extension Definition . . . . . . . . . . . . . . . . . . . 8 66 A.5. Security Considerations . . . . . . . . . . . . . . . . . 8 67 A.6. IANA Considerations . . . . . . . . . . . . . . . . . . . 9 68 A.7. Manageability Considerations . . . . . . . . . . . . . . . 10 69 A.8. Appendix A: XML Schema Definition for Extension . . . . . 10 70 A.9. Appendix B: Examples . . . . . . . . . . . . . . . . . . . 10 71 Appendix B. Example Enumerated Type Extension Definition: 72 Presentation Action . . . . . . . . . . . . . . . . . 10 73 Appendix C. Example Element Definition: Test . . . . . . . . . . 11 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 76 1. Introduction 78 In the five years since the specification of IODEF [RFC5070], the 79 threat environment has evolved, as has the practice of cooperative 80 network defense. These trends, along with experience gained through 81 implementation and deployment, have indicated the need to extend 82 IODEF. This document provides guidelines for defining these 83 extensions. It starts by describing the applicability of IODEF 84 extensions, and the IODEF extension mechanisms, before providing a 85 section (Appendix A) that is itself designed to be copied out and 86 filled in as the starting point for an Internet-Draft about an IODEF 87 extension. 89 This document is designed to give guidance on the extension of IODEF, 90 especially for those extension authors who may be new to the IETF 91 process. Nothing in this document should be construed as defining 92 policies for the definition of these extensions. 94 At publication time, the Managed Incident Lightweight Exchange (MILE) 95 working group of the IETF provides a home for work on IODEF 96 extensions that do not otherwise have a natural home. IODEF 97 extensions that require the expertise of other IETF working groups or 98 other standards development organizations may be done within those 99 groups with consultation of IODEF experts, such as those appointed 100 for review as in [I-D.ietf-mile-iodef-xmlreg]. 102 2. Applicability of Extensions to IODEF 104 Before deciding to extend IODEF, the first step is to determine 105 whether an IODEF extension is a good fit for a given problem. There 106 are two sides to this question: 108 1. Does the problem involve the reporting or sharing of 109 observations, indications, or other information about an 110 incident, whether in progress or completed, hypothetical or real? 111 "Incident" is defined in the terminology for the original IODEF 112 requirements [RFC3067]: an event that involves a security 113 violation, whether a single attack of a group thereof. If the 114 answer to this question is unequivocally "No", then IODEF is 115 probably not a good choice as a base technology for the 116 application area. 118 2. Can IODEF adequately represent information about the incident 119 without extension? IODEF has a rich set of incident-relevant 120 classes. If, after detailed examination of the problem area and 121 the IODEF specification, and consultation with IODEF experts, the 122 answer to this question is "Yes", then extension is not 123 necessary. 125 Examples of such extensions to IODEF might include: 127 o Leveraging existing work in describing aspects of incidents to 128 make IODEF more expressive, by standardized reference to external 129 information bases about incidents and incident-related information 131 o Allowing the description of new types of entities (e.g., related 132 actors) or new types of characteristics of entities (e.g., 133 information related to financial services) involved in an IODEF 134 incident report 136 o Allowing the representation of new types of indicators, 137 observables, or incidents in an IODEF incident report 139 o Allowing additional semantic or metadata labeling of IODEF 140 Documents (e.g., for handling or disposition instructions, or 141 compliance with data protection and data retention regulations) 143 3. Selecting a Mechanism for IODEF Extension 145 IODEF was designed to be extended through any combination of: 147 1. extending the enumerated values of Attributes, as per section 5.1 148 of [RFC5070]; 150 2. class extension through AdditionalData or RecordItem elements, as 151 per section 5.2 of [RFC5070]; and/or 153 3. containment of the IODEF-Document element within an external XML 154 Document, itself containing extension data, as done by RID 155 [RFC6545]. 157 Note that in this final case, the extension will not be directly 158 interoperable with IODEF implementations, and must "unwrap" the IODEF 159 document from its container; nevertheless, this may be appropriate 160 for certain use cases involving integration of IODEF within external 161 schemas. Extensions using containment of an IODEF-Document are not 162 further treated in this document, though the document template in 163 Appendix A may be of some use in defining them. 165 Certain attributes containing enumerated values within certain IODEF 166 elements may be extended. For an attribute named "foo", this is 167 achieved by giving the value of "foo" as "ext-value", and adding a 168 new attribute named "ext-foo" containing the extended value. The 169 attributes which can be extended this way are limited to the 170 following, denoted in 'Element@attribute' format, referencing the 171 section in which they are defined in [RFC5070]: 173 Incident@purpose, section 3.2 174 AdditionalData@dtype, section 3.6 175 Contact@role, section 3.7 176 Contact@type, section 3.7 177 RegistryHandle@registry, section 3.7.1 178 Impact@type, section 3.10.1 179 TimeImpact@metric, section 3.10.2 180 TimeImpact@duration, section 3.10.2 181 HistoryItem@action, section 3.11.1 182 Expectation@action, section 3.13 183 System@category, section 3.15 184 Counter@type, section 3.16.1 185 Counter@duration, section 3.16.1 186 Address@category, section 3.16.2 187 NodeRole@category, section 3.16.3 188 RecordPattern@type, section 3.19.2 189 RecordPattern@offsetunit, section 3.19.2 190 RecordItem@dtype, section 3.19.3 192 Note that this list is current as of publication time; the set of 193 IODEF Data Types may be extended by future specifications which 194 update [RFC5070]. 196 An example definition of an attribute extension is given in 197 Appendix B. 199 IODEF documents can contain extended scalar or XML data using an 200 AdditionalData element or a RecordItem element. Scalar data 201 extensions must set the "dtype" attribute of the containing element 202 to the data type to reference one of the IODEF data types as 203 enumerated inin section 2 of [RFC5070], and should use the "meaning" 204 and "formatid" attributes to explain the content of the element. 206 XML extensions within an AdditionalData or RecordItem element use a 207 dtype of "xml", and should define a schema for the topmost containing 208 element within the AdditionalData or RecordItem element. An example 209 definition of an element definition is given in Appendix C. 211 When adding elements to the AdditionalData section of an IODEF 212 document, an extension's namespace and schema should be registered 213 with IANA; see Appendix A.6 for details. 215 4. Security Considerations 217 This document raises no security issues itself. Extensions defined 218 using the template in Appendix A need to provide an analysis of 219 security issues they may raise. See Appendix A.5 for details. 221 5. IANA Considerations 223 This document contains no considerations for IANA. 225 6. Acknowledgments 227 Thanks to David Black, Benoit Claise, Martin Duerst, Eran Hammer, Tom 228 Millar, Kathleen Moriarty, Peter Saint-Andre, Robert Sparks, Takeshi 229 Takahashi, Sean Turner, Samuel Weiler, and Peter Yee, for their 230 reviews and comments. This work is materially supported by the 231 European Union Seventh Framework Program under grant agreement 257315 232 (DEMONS). 234 7. References 236 7.1. Normative References 238 [RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident 239 Object Description Exchange Format", RFC 5070, 240 December 2007. 242 7.2. Informative References 244 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 245 Requirement Levels", BCP 14, RFC 2119, March 1997. 247 [RFC3067] Arvidsson, J., Cormack, A., Demchenko, Y., and J. Meijer, 248 "TERENA'S Incident Object Description and Exchange Format 249 Requirements", RFC 3067, February 2001. 251 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 252 Text on Security Considerations", BCP 72, RFC 3552, 253 July 2003. 255 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 256 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 257 May 2008. 259 [RFC5706] Harrington, D., "Guidelines for Considering Operations and 260 Management of New Protocols and Protocol Extensions", 261 RFC 5706, November 2009. 263 [RFC6545] Moriarty, K., "Real-time Inter-network Defense (RID)", 264 RFC 6545, April 2012. 266 [I-D.ietf-mile-iodef-xmlreg] 267 Trammell, B., "Expert Review for IODEF Extensions in IANA 268 XML Registry", draft-ietf-mile-iodef-xmlreg-01 (work in 269 progress), May 2012. 271 Appendix A. Document Template 273 The document template given in this section is provided as a starting 274 point for writing an Internet-Draft describing an IODEF extension. 275 RFCs are subject to additional formatting requirements and must 276 contain additional sections not described in this template; consult 277 the RFC Editor style guide 278 (http://www.rfc-editor.org/styleguide.html) for more information. 280 This template is informational in nature; in case of any future 281 conflict with RFC Editor requirements for Internet-Drafts, those 282 requirements take precedence. 284 A.1. Introduction 286 The introduction section introduces the problem being solved by the 287 extension, and motivates the development and deployment of the 288 extension. 290 A.2. Terminology 292 The terminology section introduces and defines terms specific to the 293 document. Terminology from [RFC5070] or [RFC6545] should be 294 referenced in this section, but not redefined or copied. If 295 [RFC2119] terms are used in the document, this should be noted in the 296 terminology section. 298 A.3. Applicability 300 The applicability section defines the use cases to which the 301 extension is applicable, and details any requirements analysis done 302 during the development of the extension. The primary goal of this 303 section is to allow readers to see if an extension is indeed intended 304 to solve a given problem. This section should also define and 305 restrict the scope of the extension, as appropriate, by pointing out 306 any non-obvious situations to which it is not intended to apply. 308 In addition to defining the applicability, this section may also 309 present example situations, which should then be detailed in the 310 examples section, below. 312 A.4. Extension Definition 314 This section defines the extension. 316 Extensions to enumerated types are defined in one subsection for each 317 attribute to be extended, enumerating the new values with an 318 explanation of the meaning of each new value. An example enumeration 319 extension is shown in Appendix B, below. 321 Element extensions are defined in one subsection for each element, in 322 top-down order, from the element contained within AdditionalData or 323 RecordItem; an example element extension is shown in Appendix C, 324 below. Each element should be described by a UML diagram as in 325 Figure 1, followed by a description of each of the attributes, and a 326 short description of each of the child elements. Child elements 327 should then be defined in a subsequent subsection, if not already 328 defined in the IODEF document itself, or in another referenced IODEF 329 extension document. 331 +---------------------+ 332 | Element | 333 +---------------------+ 334 | TYPE attribute0 |<>----------[ChildExactlyOne] 335 | TYPE attribute1 |<>--{0..1}--[ChildZeroOrOne] 336 | |<>--{0..*}--[ChildZeroOrMore] 337 | |<>--{1..*}--[ChildOneOrMore] 338 +---------------------+ 340 Figure 1: Example UML Element Diagram 342 Elements containing child elements should indicate the multiplicity 343 of those child elements, as shown in the figure above. Allowable 344 TYPEs are are enumerated in section 2 of [RFC5070]. 346 A.5. Security Considerations 348 [SECDIR and RFC-EDITOR NOTE: Despite the title, this section is NOT a 349 Security Considerations section, rather a template Security 350 Considerations section for future extension documents to be built 351 from this template. See Section 4 for Security Considerations for 352 this document.] 354 Any security considerations [RFC3552] raised by this extension or its 355 deployment should be detailed in this section. Guidance should focus 356 on ensuring the users of this extension do so in a secure fashion, 357 with special attention to non-obvious implications of the 358 transmission of the information represented by this extension. 359 [RFC3552] may be a useful reference in determining what to cover in 360 this section. This section is required by the RFC Editor. 362 It should also be noted in this section that the security 363 considerations for IODEF [RFC5070] apply to the extension as well. 365 A.6. IANA Considerations 367 [IANA and RFC-EDITOR NOTE: Despite the title, this section is NOT an 368 IANA Considerations section, rather a template IANA Considerations 369 section for future extension documents to be built from this 370 template. See Section 5 for IANA Considerations for this document.] 372 Any IANA considerations [RFC5226] for the document should be detailed 373 in this section. Note that IODEF extension documents will generally 374 register new namespaces and schemas. In addition, this section is 375 required by the RFC Editor, so if there are no IANA considerations, 376 the section should exist and contain the text "this document has no 377 actions for IANA". 379 IODEF Extensions which represent an enumeration should reference an 380 existing IANA registry or subregistry for the values of that 381 enumeration. If no such registry exists, this section should define 382 a new registry to hold the enumeration's values, and define the 383 policies by which additions may be made to the registry. 385 IODEF Extensions adding elements to the AdditionalData section of an 386 IODEF document should register their own namespaces and schemas for 387 extensions with IANA; therefore, this section should contain at least 388 a registration request for the namespace and the schema, as follows, 389 modified as appropriate for the extension: 391 Registration request for the IODEF My-Extension namespace: 393 URI: urn:ietf:params:xml:ns:iodef-myextension-1.0 395 Registrant Contact: Refer here to the authors' addresses section of 396 the document, or to an organizational contact in the case of an 397 extension supported by an external organization. 399 XML: None 401 Registration request for the IODEF My-Extension XML schema: 403 URI: urn:ietf:params:xml:schema:iodef-myextension-1.0 404 Registrant Contact: Refer here to the authors' addresses section of 405 the document, or to an organizational contact in the case of an 406 extension supported by an external organization. 408 XML: Refer here to the XML Schema in Appendix A of the document, or 409 to a well-known external reference in the case of an extension with 410 an externally-defined schema. 412 A.7. Manageability Considerations 414 If any of the operational and/or management considerations listed in 415 Appendix A of [RFC5706] apply to the extension, address them in this 416 section. If no such considerations apply, this section can be 417 omitted. 419 A.8. Appendix A: XML Schema Definition for Extension 421 The XML Schema describing the elements defined in the Extension 422 Defintion section is given here. Each of the examples in 423 Appendix A.9 will be verified to validate against this schema by 424 automated tools. 426 A.9. Appendix B: Examples 428 This section contains example IODEF-Documents illustrating the 429 extension. If example situations are outlined in the applicability 430 section, documents for those examples should be provided in the same 431 order as in the applicability section. Example documents will be 432 tested to validate against the schema given in the appendix. 434 Appendix B. Example Enumerated Type Extension Definition: Presentation 435 Action 437 This example extends the IODEF Expectation element to represent the 438 expectation that a slide deck be derived from the IODEF Incident, and 439 that a presentation be given by the recipient's organization thereon. 441 Attribute: Expectation@action 443 Extended value(s): give-a-presentation 445 Value meaning: generate a slide deck from the provided incident 446 information and give a presentation thereon. 448 Additional considerations: the format of the slide deck is left to 449 the recipient to determine in accordance with its established 450 practices for the presentation of incident reports. 452 Appendix C. Example Element Definition: Test 454 This example defines the Test class for labeling IODEF test data. 456 The Test class is intended to be included within an AdditionalData 457 element in an IODEF Document. If a Test element is present, it 458 indicates that an IODEF Document contains test data, not a 459 information about a real incident. 461 The Test class contains information about how the test data was 462 generated. 464 +---------------------+ 465 | Test | 466 +---------------------+ 467 | ENUM category | 468 | STRING generator | 469 | | 470 | | 471 +---------------------+ 473 Figure 2: The Test class 475 The Test class has two attributes: 477 category: Required. ENUM. The type of test data. The permitted 478 values for this attribute are shown below. The default value is 479 "unspecified". 481 1. unspecified. The document contains test data, but no further 482 information is available. 484 2. internal. The test data is intended for the internal use of 485 an implementor, and should not be distributed or used outside 486 the context in which it was generated. 488 3. unit. The test data is intended for unit testing of an 489 implementation, and may be included with the implementation to 490 support this as part of the build and deployment process. 492 4. interoperability. The test data is intended for 493 interoperability testing of an implementation, and may be 494 freely shared to support this purpose. 496 generator: Optional. STRING. A free-form string identifying the 497 person, entity, or program which generated the test data. 499 Author's Address 501 Brian Trammell 502 Swiss Federal Institute of Technology Zurich 503 Gloriastrasse 35 504 8092 Zurich 505 Switzerland 507 Phone: +41 44 632 70 13 508 Email: trammell@tik.ee.ethz.ch