idnits 2.17.1 draft-ietf-mile-template-03.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 (March 7, 2012) is 4404 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC3688' is defined on line 208, but no explicit reference was found in the text == Unused Reference: 'RFC3339' is defined on line 236, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5070 (Obsoleted by RFC 7970) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). 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 March 7, 2012 5 Expires: September 8, 2012 7 Guidelines for Defining Extensions to IODEF 8 draft-ietf-mile-template-03.txt 10 Abstract 12 This document provides guidelines for extensions to IODEF [RFC5070] 13 for exchange of incident management data, and contains a template for 14 Internet-Drafts describing those extensions, in order to ease the 15 work and improve the quality of extension descriptions. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on September 8, 2012. 34 Copyright Notice 36 Copyright (c) 2012 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. Applicability of Extensions to IODEF . . . . . . . . . . . . . 3 53 3. Selecting a Mechanism for IODEF Extension . . . . . . . . . . 4 54 4. Security Considerations . . . . . . . . . . . . . . . . . . . 5 55 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 56 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 5 57 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 7.1. Normative References . . . . . . . . . . . . . . . . . . . 5 59 7.2. Informative References . . . . . . . . . . . . . . . . . . 6 60 Appendix A. Document Template . . . . . . . . . . . . . . . . . . 6 61 A.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 6 62 A.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 63 A.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 7 64 A.4. Extension Definition . . . . . . . . . . . . . . . . . . . 7 65 A.4.1. IODEF Data Types . . . . . . . . . . . . . . . . . . . 8 66 A.5. Security Considerations . . . . . . . . . . . . . . . . . 9 67 A.6. IANA Considerations . . . . . . . . . . . . . . . . . . . 9 68 A.7. References . . . . . . . . . . . . . . . . . . . . . . . . 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 E.164 Address . . . . . . . . . . . . . . . . . . . . 11 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 of an Internet-Draft about an IODEF 87 extension. 89 2. Applicability of Extensions to IODEF 91 Before deciding to extend IODEF, the first step is to determine 92 whether an IODEF extension is a good fit for a given problem. There 93 are two sides to this question: 95 1. Does the problem involve the reporting or sharing of information 96 about an incident? "Incident" is not defined in the terminology 97 for IODEF, but for purposes of IODEF can be loosely described as 98 "something that happened that has some impact on the information 99 security situation of an entity", with quite a bit of leeway for 100 interpretation. If the answer to this question is unequivocally 101 "No", then IODEF is probably not a good choice as a base 102 technology for the application area. 104 2. Can IODEF adequately represent information about the incident 105 without extension? IODEF has a rich set of incident-relevant 106 classes. If, after detailed examination of the problem area and 107 the IODEF specification, the answer to this question is "Yes", 108 then extension is not necessary. 110 A non-exhaustive list of good candidate extensions to IODEF includes: 112 o Leveraging existing work in describing aspects of incidents to 113 make IODEF more expressive, by standardized reference to external 114 information bases about incidents and incident-related information 116 o Allowing the description of new types of entities (e.g., related 117 actors) or new types of characteristics of entities (e.g., 118 information related to financial services) involved in an IODEF 119 incident report 121 o Allowing additional semantic or metadata labeling of IODEF 122 Documents (e.g., for handling or disposition instructions, or 123 compliance with data protection and data retention regulations) 125 3. Selecting a Mechanism for IODEF Extension 127 IODEF was designed to be extended through any combination of: 129 1. extending the enumerated values of Attributes, as per section 5.1 130 of [RFC5070]; 132 2. class extension through AdditionalData and RecordItem elements, 133 as per section 5.2 of [RFC5070]; and/or 135 3. containment of the IODEF-Document element within an external XML 136 Document, itself containing extension data. 138 Note that in this final case, the extension will not be directly 139 interoperable with IODEF implementations, and must "unwrap" the IODEF 140 document from its container; nevertheless, this may be appropriate 141 for certain use cases involving integration of IODEF within external 142 schemas. Extensions using containment of an IODEF-Document are not 143 further treated in this document, though the document template in 144 Appendix A may be of some use in defining them. 146 Certain attributes containing enumerated values within certain IODEF 147 elements may be extended. For an attribute named "foo", this is 148 achieved by giving the value of "foo" as "ext-value", and adding a 149 new attribute named "ext-foo" containing the extended value. The 150 attributes which can be extended this way are limited to the 151 following, denoted in 'Element@attribute' format, referencing the 152 section in which they are defined in [RFC5070]: 154 Incident@purpose, section 3.2 155 AdditionalData@dtype, section 3.6 156 Contact@role, section 3.7 157 Contact@type, section 3.7 158 RegistryHandle@registry, section 3.7.1 159 Impact@type, section 3.10.1 160 TimeImpact@metric, section 3.10.2 161 TimeImpact@duration, section 3.10.2 162 HistoryItem@action, section 3.11.1 163 Expectation@action, section 3.13 164 System@category, section 3.15 165 Counter@type, section 3.16.1 166 Counter@duration, section 3.16.1 167 Address@category, section 3.16.2 168 NodeRole@category, section 3.16.3 169 RecordPattern@type>, section 3.19.2 170 RecordPattern@offsetunit, section 3.19.2 171 RecordItem@dtype, section 3.19.3 173 An example definition of an attribute extension is given in 174 Appendix B. 176 IODEF documents can contain extended scalar or XML data using an 177 AdditionalData element or a RecordItem element. Scalar data 178 extensions must set the "dtype" attribute of the containing element 179 to the data type to reference one of the IODEF data types as 180 enumerated in Appendix A.4.1, and should use the "meaning" and 181 "formatid" attributes to explain the content of the element. 183 XML extensions within an AdditionalData or RecordItem element use a 184 dtype of "xml", and should define a schema for the topmost containing 185 element within the AdditionalData or RecordItem element. An example 186 definition of an element definition is given in Appendix C. 188 4. Security Considerations 190 This document defines a template for extensions to IODEF; the 191 security considerations for IODEF [RFC5070] apply. 193 5. IANA Considerations 195 This document contains no considerations for IANA. 197 6. Acknowledgments 199 Thanks to David Black, Takeshi Takahashi, Tom Millar, and Kathleen 200 Moriarty for their comments. This work is materially supported by 201 the European Union Seventh Framework Program under grant agreement 202 257315 (DEMONS). 204 7. References 206 7.1. Normative References 208 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 209 January 2004. 211 [RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident 212 Object Description Exchange Format", RFC 5070, 213 December 2007. 215 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 216 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 217 May 2008. 219 [I-D.ietf-mile-rfc6045-bis] 220 Moriarty, K., "Real-time Inter-network Defense (RID)", 221 draft-ietf-mile-rfc6045-bis-11 (work in progress), 222 January 2012. 224 7.2. Informative References 226 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 227 Requirement Levels", BCP 14, RFC 2119, March 1997. 229 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 230 Resource Identifier (URI): Generic Syntax", STD 66, 231 RFC 3986, January 2005. 233 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 234 October 2008. 236 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 237 Internet: Timestamps", RFC 3339, July 2002. 239 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 240 Text on Security Considerations", BCP 72, RFC 3552, 241 July 2003. 243 [RFC4519] Sciberras, A., "Lightweight Directory Access Protocol 244 (LDAP): Schema for User Applications", RFC 4519, 245 June 2006. 247 [RFC6116] Bradner, S., Conroy, L., and K. Fujiwara, "The E.164 to 248 Uniform Resource Identifiers (URI) Dynamic Delegation 249 Discovery System (DDDS) Application (ENUM)", RFC 6116, 250 March 2011. 252 Appendix A. Document Template 254 The document template given in this section is provided as a starting 255 point for writing an Internet-Draft describing an IODEF extension. 257 A.1. Introduction 259 The introduction section introduces the problem being solved by the 260 extension, and motivates the development and deployment of the 261 extension. 263 A.2. Terminology 265 The terminology section introduces and defines terms specific to the 266 document. Terminology from [RFC5070] or [I-D.ietf-mile-rfc6045-bis] 267 should be referenced in this section, but not redefined or copied. 268 If [RFC2119] terms are used in the document, this should be noted in 269 the terminology section. 271 A.3. Applicability 273 The applicability section defines the use cases to which the 274 extension is applicable, and details any requirements analysis done 275 during the development of the extension. The primary goal of this 276 section is to allow readers to see if an extension is indeed intended 277 to solve a given problem. This should also define and restrict the 278 scope of the extension, as appropriate, by pointing out any non- 279 obvious situations to which it is not intended to apply. 281 In addition to defining the applicability, this section may also 282 present example situations, which should then be detailed in the 283 examples section, below. 285 A.4. Extension Definition 287 This section defines the extension. 289 Extensions to enumerated types are defined in one subsection for each 290 attribute to be extended, enumerating the new values with an 291 explanation of the meaning of each new value. An example enumeration 292 extension is shown in Appendix B, below. 294 Element extensions are defined in one subsection for each element, in 295 top-down order, from the element contained within AdditionalData or 296 RecordItem; an example element extension is shown in Appendix C, 297 below. Each element should be described by a UML diagram as in 298 Figure 1, followed by a description of each of the attributes, and a 299 short description of each of the child elements. Child elements 300 should then be defined in a subsequent subsection, if not already 301 defined in the IODEF document itself, or in another referenced IODEF 302 extension document. 304 +---------------------+ 305 | Element | 306 +---------------------+ 307 | TYPE attribute0 |<>----------[ChildExactlyOne] 308 | TYPE attribute1 |<>--{0..1}--[ChildZeroOrOne] 309 | |<>--{0..*}--[ChildZeroOrMore] 310 | |<>--{1..*}--[ChildOneOrMore] 311 +---------------------+ 313 Figure 1: Example UML Element Diagram 315 Elements containing child elements should indicate the multiplicity 316 of those child elements, as shown in the figure above. Allowable 317 TYPEs are discussed in the following subsection. 319 A.4.1. IODEF Data Types 321 The allowable TYPEs for attributes within IODEF are enumerated in 322 section 2 of [RFC5070], and consist of: 324 o INTEGER 326 o REAL 328 o CHARACTER 330 o STRING 332 o BYTE for bytes or byte vectors in Base 64 encoding 334 o HEXBIN for bytes in ascii-hexadecimal encoding 336 o ENUM for enumerated types; allowable values of the enumeration 337 must be defined in the attribute definition 339 o DATETIME for [RFC3339]-encoded timestamps 341 o TIMEZONE for timezones as described in section 2.9 of [RFC5070]. 343 o PORTLIST for port lists as described in section 2.10 of [RFC5070]. 345 o POSTAL for postal addresses as described in section 2.23 of 346 [RFC4519]. 348 o NAME for names of natural or legal persons as defined in section 349 2.3 of [RFC4519]. 351 o PHONE for telephone numbers as defined in section 2.35 of 352 [RFC4519]. 354 o EMAIL for email addresses as defined in section 3.4.1. of 355 [RFC5322]. 357 o URL for URIs as in [RFC3986]. 359 In addition to these simple data types, IODEF provides a compound 360 data type for representing network address information. Addresses 361 included within an extension element should be represented by 362 containing an IODEF:Address element, which supports IPv4 and IPv6 363 addresses, as well as MAC, ATM, and BGP autonomous system numbers. 364 Application-layer addresses should be represented with the URL simple 365 attribute type, instead. 367 A.5. Security Considerations 369 [SECDIR and RFC-EDITOR NOTE: Despite the title, this section is NOT a 370 Security Considerations section, rather a template Security 371 Considerations section for future extension documents to be built 372 from this template. See Section 4 for Security Considerations for 373 this document.] 375 Any security considerations [RFC3552] raised by this extension or its 376 deployment should be detailed in this section. Guidance should focus 377 on ensuring the users of this extension do so in a secure fashion, 378 with special attention to non-obvious implications of the 379 transmission of the information represented by this extension. 381 It should also be noted in this section that the security 382 considerations for IODEF [RFC5070] apply to the extension as well. 384 A.6. IANA Considerations 386 [IANA and RFC-EDITOR NOTE: Despite the title, this section is NOT an 387 IANA Considerations section, rather a template IANA Considerations 388 section for future extension documents to be built from this 389 template. See Section 5 for IANA Considerations for this document.] 391 Any IANA considerations [RFC5226] for the document should be detailed 392 in this section; if none, the section should exist and contain the 393 text "this document has no actions for IANA". 395 IODEF Extensions which represent an enumeration should reference an 396 existing IANA registry or subregistry for the values of that 397 enumeration. If no such registry exists, this section should define 398 a new registry to hold the enumeration's values, and define the 399 policies by which additions may be made to the registry. 401 IODEF Extensions adding elements to the AdditionalData section of an 402 IODEF document should register their own namespaces and schemas for 403 extensions with IANA; therefore, this section should contain at least 404 a registration request for the namespace and the schema, as follows, 405 modified as appropriate for the extension: 407 Registration request for the IODEF My-Extension namespace: 409 URI: urn:ietf:params:xml:ns:iodef-myextension-1.0 411 Registrant Contact: Refer here to the authors' addresses section of 412 the document, or to an organizational contact in the case of an 413 extension supported by an external organization. 415 XML: None 417 Registration request for the IODEF My-Extension XML schema: 419 URI: urn:ietf:params:xml:schema:iodef-myextension-1.0 421 Registrant Contact: Refer here to the authors' addresses section of 422 the document, or to an organizational contact in the case of an 423 extension supported by an external organization. 425 XML: Refer here to the XML Schema in Appendix A of the document, or 426 to a well-known external reference in the case of an extension with 427 an externally-defined schema. 429 A.7. References 431 This section lists RFCs, internet-drafts and other documents 432 referenced from the extension, split into normative and informative 433 references. 435 A.8. Appendix A: XML Schema Definition for Extension 437 The XML Schema describing the elements defined in the Extension 438 Defintion section is given here. Each of the examples in section 439 Appendix A.9 should be verified to validate against this schema by 440 automated tools. 442 A.9. Appendix B: Examples 444 This section contains example IODEF-Documents illustrating the 445 extension. If example situations are outlined in the applicability 446 section, documents for those examples should be provided in the same 447 order as in the applicability section. Example documents should be 448 tested to validate against the schema given in the appendix. 450 Appendix B. Example Enumerated Type Extension Definition: E.164 Address 452 This example extends the IODEF Address element to support the 453 encoding of ENUM-mapped telephone numbers [RFC6116]. 455 Attribute: Address@category 457 Extended value(s): enum-e164 459 Value meaning and format: An E.164 telephone number encoded as a 460 domain name in the e164.int space, e.g. 461 "2.1.2.1.5.5.5.2.1.2.1.e164.int." for +1 212 555 1212, as per section 462 3.2 of [RFC6116]. 464 Additional considerations: none. 466 Appendix C. Example Element Definition: Test 468 This example defines the Test class for labeling IODEF test data. 470 The Test class is intended to be included within an AdditionalData 471 element in an IODEF Document. If a Test element is present, it 472 indicates that an IODEF Document contains test data, not a reference 473 to a real incident. 475 The Test class contains information about how the test data was 476 generated. 478 +---------------------+ 479 | Test | 480 +---------------------+ 481 | ENUM category | 482 | STRING generator | 483 | | 484 | | 485 +---------------------+ 487 Figure 2: The Test class 489 The Test class has two attributes: 491 category: Required. ENUM. The type of test data. The permitted 492 values for this attribute are shown below. The default value is 493 "unspecified". 495 1. unspecified. The document contains test data, but no further 496 information is available. 498 2. internal. The test data is intended for the internal use of 499 an implementor, and should not be distributed or used outside 500 the context in which it was generated. 502 3. unit. The test data is intended for unit testing of an 503 implementation, and may be included with the implementation to 504 support this as part of the build and deployment process. 506 4. interoperability. The test data is intended for 507 interoperability testing of an implementation, and may be 508 freely shared to support this purpose. 510 generator: Optional. STRING. A free-form string identifying the 511 person, entity, or program which generated the test data. 513 Author's Address 515 Brian Trammell 516 Swiss Federal Institute of Technology Zurich 517 Gloriastrasse 35 518 8092 Zurich 519 Switzerland 521 Phone: +41 44 632 70 13 522 Email: trammell@tik.ee.ethz.ch