idnits 2.17.1 draft-trammell-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 (July 26, 2011) is 4658 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5070 (Obsoleted by RFC 7970) ** 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) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Individual Submission B. Trammell 3 Internet-Draft ETH Zurich 4 Intended status: Informational July 26, 2011 5 Expires: January 27, 2012 7 Guidelines for Extensions to IODEF for Managed Incident Lightweight 8 Exchange 9 draft-trammell-mile-template-01.txt 11 Abstract 13 This document provides guidelines for extensions to IODEF [RFC5070] 14 for lightweight exchange of incident management data, and contains a 15 template for Internet-Drafts describing those extensions, in order to 16 ease the work and improve 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 January 27, 2012. 35 Copyright Notice 37 Copyright (c) 2011 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. Document Template . . . . . . . . . . . . . . . . . . . . . . 5 56 4.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 5 57 4.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 58 4.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 6 59 4.4. Extension Definition . . . . . . . . . . . . . . . . . . . 6 60 4.4.1. IODEF Data Types . . . . . . . . . . . . . . . . . . . 7 61 4.4.2. Example Enumerated Type Extension Definition: 62 E.164 Address . . . . . . . . . . . . . . . . . . . . 8 63 4.4.3. Example Element Definition: Test . . . . . . . . . . . 8 64 4.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 9 65 4.6. Security Considerations . . . . . . . . . . . . . . . . . 9 66 4.7. IANA Considerations . . . . . . . . . . . . . . . . . . . 10 67 4.8. Appendix: XML Schema Definition for Extension . . . . . . 11 68 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 69 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 70 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 7.1. Normative References . . . . . . . . . . . . . . . . . . . 11 72 7.2. Informative References . . . . . . . . . . . . . . . . . . 11 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 75 1. Introduction 77 Since the specification of IODEF [RFC5070], the evolution of the 78 threat environment and the practice of cooperative network defense, 79 along with continued implementation and deployment, has indicated the 80 need for guidelines for the implementation and extension of IODEF. 81 This document provides these guidelines. It starts by describing the 82 applicability of IODEF extensions, and the IODEF extension 83 mechanisms, before providing a section Section 4 that is itself 84 designed to be copied out and filled in as the starting point of an 85 Internet-Draft about an IODEF extension. 87 2. Applicability of Extensions to IODEF 89 Before deciding to extend IODEF, the first step is to determine 90 whether an IODEF extension is a good fit for a given problem. There 91 are two sides to this question: 93 1. Does the problem involve the reporting or sharing of information 94 about an incident? "Incident" is not defined in the terminology 95 for IODEF, but for purposes of IODEF can be loosely described as 96 "something that happened that has some impact on the information 97 security situation of an entity", with quite a bit of leeway for 98 interpretation. If the answer to this question is unequivocally 99 "No", then IODEF is probably not a good choice as a base 100 technology for the application area. 102 2. Can IODEF adequately represent information about the incident 103 without extension? IODEF has a reasonably rich set of incident- 104 relevant classes. If, after examination of the problem area and 105 the IODEF specification, the answer to this question is "Yes", 106 then extension is not necessary. 108 A non-exhaustive list of good candidate extensions to IODEF includes: 110 1. Allowing standardized reference to external information bases 111 about incidents and incident-relevant information: leveraging 112 existing work in describing aspects of incidents to make IODEF 113 more expressive 115 2. Allowing the description of new types of entities (e.g., related 116 actors) or new types of characteristics of entities (e.g., 117 financial services-related information) involved in an IODEF 118 incident report 120 3. Allowing additional semantic or metadata labeling of IODEF 121 Documents (e.g., for handling or disposition instructions, or 122 compliance with data protection and data retention regulations) 124 3. Selecting a Mechanism for IODEF Extension 126 IODEF was designed to be extended through any combination of: 128 1. extending the enumerated values of Attributes, as per section 5.1 129 of [RFC5070]; 131 2. class extension through AdditionalData and RecordItem elements, 132 as per section 5.2 of [RFC5070]; and/or 134 3. containment of the IODEF-Document element within an external XML 135 Document, itself containing extension data. 137 Note that in this final case, the extension will not be directly 138 interoperable with IODEF implementations, and must "unwrap" the IODEF 139 document from its container; nevertheless, this may be appropriate 140 for certain use cases involving integration with IODEF within 141 external schemas. Extensions using containment of an IODEF-Document 142 are not further treated in this document, though the document 143 template in Section 4 may be of some use in defining them. 145 Certain attributes containing enumerated values within certain IODEF 146 elements may be extended. For an attribute named "foo", this is 147 achieved by giving the value of "foo" as "ext-value", and adding a 148 new attribute named "ext-foo" containing the extended value. The 149 attributes which can be extended in this way are defined in 150 [RFC5070], and limited to only these: 152 o Incident@purpose 154 o Contact@role 156 o Contact@type 158 o RegistryHandle@registry 160 o Impact@type 162 o TimeImpact@metric 164 o TimeImpact@duration 166 o HistoryItem@action 167 o Expectation@action 169 o System@category 171 o Counter@type 173 o Counter@duration 175 o Address@category 177 o NodeRole@category 179 o RecordPattern@type 181 o RecordPattern@offsetunit 183 o AdditionalData@dtype 185 o RecordItem@dtype 187 An example definition of an attribute extension is given in 188 Section 4.4.2. 190 IODEF documents can contain extended scalar or XML data using an 191 AdditionalData element or a RecordItem element. Scalar data 192 extensions MUST set the "dtype" attribute of the containing element 193 to the data type to reference one of the IODEF data types as 194 enumerated in Section 4.4.1, and SHOULD define the use the "meaning" 195 and "formatid" attributes to explain the content of the element. 197 XML extensions within an AdditionalData or RecordItem element use a 198 dtype of "xml", and SHOULD define a schema for the root element 199 within the AdditionalData or RecordItem attribute. An example 200 definition of an element definition is given in Section 4.4.3. 202 4. Document Template 204 Documents describing an IODEF extension should follow the document 205 template given in this section. 207 4.1. Introduction 209 The introduction section introduces the problem being solved by the 210 extension, and motivates the development and deployment of the 211 extension. 213 4.2. Terminology 215 The terminology section introduces and defines terms specific to the 216 document. Terminology from [RFC5070] or [RFC6045] should be 217 referenced in this section, but not redefined or copied. If 218 [RFC2119] terms are used in the document, this should be noted in the 219 terminology section. 221 4.3. Applicability 223 The applicability section defines the use cases to which the 224 extension is applicable, and details any requirements analysis done 225 during the development of the extension. The primary goal of this 226 section is to allow readers to see if an extension is indeed intended 227 to solve a particular problem. This should also the scope of the 228 extension, as appropriate, by pointing out any non-obvious situations 229 to which it is not intended to apply. 231 In addition to defining the applicability, this section may also 232 present example situations, which should then be detailed in the 233 examples section, below. 235 4.4. Extension Definition 237 This section defines the extension. 239 Extensions to enumerated types are defined in one subsection for each 240 attribute to be extended, enumerating the new values with an 241 explanation of the meaning of the new value. An example enumeration 242 extension is shown in Section 4.4.2, below. 244 Element extensions are defined in one subsection for each element, in 245 top-down order, from the element contained within AdditionalData or 246 RecordItem; an example element extension is shown in Section 4.4.3, 247 below. Each element should be described by a UML diagram as in 248 Figure 1, followed by a description of each of the attributes, and a 249 short description of each of the child elements. Child elements 250 should then be defined in a subsequent subsection, if not already 251 defined in the IODEF document itself, or in another referenced MILE 252 extension document. 254 +---------------------+ 255 | Element | 256 +---------------------+ 257 | TYPE attribute0 |<>----------[ChildExactlyOne] 258 | TYPE attribute1 |<>--{0..1}--[ChildZeroOrOne] 259 | |<>--{0..*}--[ChildZeroOrMore] 260 | |<>--{1..*}--[ChildOneOrMore] 261 +---------------------+ 263 Figure 1: Example UML Element Diagram 265 Elements containing child elements should indicate the multiplicity 266 of those child elements, as shown in the figure above. Allowable 267 TYPEs are discussed in the following subsection. 269 4.4.1. IODEF Data Types 271 The allowable TYPEs for attributes within IODEF are enumerated in 272 section 2 of [RFC5070], and consist of: 274 o INTEGER 276 o REAL 278 o CHARACTER 280 o STRING 282 o ML_STRING (for strings in encodings other than that of the 283 enclosing document) 285 o BYTE for bytes or byte vectors in Base 64 encoding 287 o HEXBIN for bytes in ascii-hexadecimal encoding 289 o ENUM for enumerated types; allowable values of the enumeration 290 must be defined in the attribute definition 292 o DATETIME for ISO 8601:2000 [RFC3339] encoded timestamps 294 o TIMEZONE for timezones as encoded in section 2.9 of [RFC5070]. 296 o PORTLIST for port lists as encoded in section 2.10 of [RFC5070]. 298 o POSTAL for postal addresses as defined in section 2.23 of 299 [RFC4519]. 301 o NAME for names of natural or legal persons as defined in section 302 2.3 of [RFC4519]. 304 o PHONE for telephone numbers as defined in section 2.35 of 305 [RFC4519]. 307 o EMAIL for email addresses as defined in section 3.4.1. of 308 [RFC2822]. 310 o URL for URLs as in [RFC2396]. 312 In addition to these simple data types, IODEF provides a compound 313 data type for representing network address information. Addresses 314 included within an extension element should be represented by 315 containing an IODEF:Address element, which supports IPv4 and 316 [RFC2373] IPv6 addresses, as well as MAC, ATM, and BGP autonomous 317 system numbers. Application-layer addresses should be represented 318 with the URL simple attribute type, instead. 320 4.4.2. Example Enumerated Type Extension Definition: E.164 Address 322 This example extends the IODEF Address element to support the 323 encoding of ENUM-mapped telephone numbers [RFC6116]. 325 Attribute: Address@category 327 Extended value(s): enum-e164 329 Content format: An E.164 telephone number encoded as a domain name in 330 the e164.int space, e.g. "2.1.2.1.5.5.5.2.1.2.1.e164.int." for +1 212 331 555 1212, as per section 3.2 of [RFC6116]. 333 Additional considerations: none. 335 4.4.3. Example Element Definition: Test 337 This example defines the Test class for labeling IODEF test data. 339 The Test class is intended to be included within an AdditionalData 340 element in an IODEF Document. If a Test element is present, it 341 indicates that an IODEF Document contains test data, not a reference 342 to a real incident. 344 The Test class contains information about how the test data was 345 generated. 347 +---------------------+ 348 | Test | 349 +---------------------+ 350 | ENUM category | 351 | STRING generator | 352 | | 353 | | 354 +---------------------+ 356 Figure 2: The Test class 358 The Test class has two attributes: 360 category: Required. ENUM. The type of test data. The permitted 361 values for this attribute are shown below. The default value is 362 "unspecified". 364 1. unspecified. The document contains test data, but no further 365 information is available. 367 2. internal. The test data is intended for the internal use of 368 an implementor, and should not be distributed or used outside 369 the context in which it was generated. 371 3. unit. The test data is intended for unit testing of an 372 implementation, and may be included with the implementation to 373 support this as part of the build and deployment process. 375 4. interoperability. The test data is intended for 376 interoperability testing of an implementation, and may be 377 freely shared to support this purpose. 379 generator: Optional. STRING. A free-form string identifying the 380 person, entity, or program which generated the test data. 382 4.5. Examples 384 This section contains example IODEF-Documents illustrating the 385 extension. If example situations are outlined in the applicability 386 section, documents for those examples should be provided in the same 387 order as in the applicability section. Example documents should be 388 tested to validate against the schema given in the appendix. 390 4.6. Security Considerations 392 [SECDIR and RFC-EDITOR NOTE: Despite the title, this section is NOT a 393 Security Considerations section, rather a template Security 394 Considerations section for future extension documents to be built 395 from this template. See Section 5 for Security Considerations for 396 this document.] 398 Any security considerations [RFC3552] raised by this extension or its 399 deployment should be detailed in this section. Guidance should focus 400 on ensuring the users of this extension do so in a secure fashion, 401 with special attention to non-obvious implications of the 402 transmission or storage of the information represented by an 403 extension. 405 4.7. IANA Considerations 407 [IANA and RFC-EDITOR NOTE: Despite the title, this section is NOT an 408 IANA Considerations section, rather a template IANA Considerations 409 section for future extension documents to be built from this 410 template. See Section 6 for IANA Considerations for this document.] 412 Any IANA considerations [RFC5226] for the document should be detailed 413 in this section; if none, the section should exist and contain the 414 text "this document has no actions for IANA". 416 IODEF Extensions adding elements to the AdditionalData section of an 417 IODEF document should register their own namespaces and schemas for 418 extensions with IANA; therefore, this section should contain at least 419 a registration request for the namespace and the schema, as follows, 420 modified as appropriate for the extension: 422 Registration request for the IODEF My-Extension namespace: 424 URI: urn:ietf:params:xml:ns:iodef-myextension-1.0 426 Registrant Contact: Refer here to the authors' addresses section of 427 the document, or to an organizational contact in the case of an 428 extension supported by an external organization. 430 XML: None 432 Registration request for the IODEF My-Extension XML schema: 434 URI: urn:ietf:params:xml:schema:iodef-myextension-1.0 436 Registrant Contact: Refer here to the authors' addresses section of 437 the document, or to an organizational contact in the case of an 438 extension supported by an external organization. 440 XML: Refer here to the XML Schema in the appendix of the document, 441 or to a well-known external reference in the case of an extension 442 with an externally-defined schema. 444 4.8. Appendix: XML Schema Definition for Extension 446 The XML Schema describing the elements defined in the Extension 447 Defintion section is given here. Each of the examples in section 448 Section 4.5 should be verified to validate against this schema by 449 automated tools. 451 5. Security Considerations 453 This document defines a template for MILE extensions to the IODEF and 454 RID documents; as such, it has no security considerations on its own. 456 6. IANA Considerations 458 This document has no actions for IANA. 460 7. References 462 7.1. Normative References 464 [RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident 465 Object Description Exchange Format", RFC 5070, 466 December 2007. 468 [RFC6045] Moriarty, K., "Real-time Inter-network Defense (RID)", 469 RFC 6045, November 2010. 471 7.2. Informative References 473 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 474 Requirement Levels", BCP 14, RFC 2119, March 1997. 476 [RFC2373] Hinden, R. and S. Deering, "IP Version 6 Addressing 477 Architecture", RFC 2373, July 1998. 479 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 480 Resource Identifiers (URI): Generic Syntax", RFC 2396, 481 August 1998. 483 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, 484 April 2001. 486 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 487 Internet: Timestamps", RFC 3339, July 2002. 489 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 490 Text on Security Considerations", BCP 72, RFC 3552, 491 July 2003. 493 [RFC4519] Sciberras, A., "Lightweight Directory Access Protocol 494 (LDAP): Schema for User Applications", RFC 4519, 495 June 2006. 497 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 498 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 499 May 2008. 501 [RFC6116] Bradner, S., Conroy, L., and K. Fujiwara, "The E.164 to 502 Uniform Resource Identifiers (URI) Dynamic Delegation 503 Discovery System (DDDS) Application (ENUM)", RFC 6116, 504 March 2011. 506 Author's Address 508 Brian Trammell 509 Swiss Federal Institute of Technology Zurich 510 Gloriastrasse 35 511 8092 Zurich 512 Switzerland 514 Phone: +41 44 632 70 13 515 Email: trammell@tik.ee.ethz.ch