MILE B. Trammell Internet-Draft ETH Zurich Intended status: BCP November 17, 2011 Expires: May 20, 2012 Guidelines for Extensions to IODEF for Managed Incident Lightweight Exchange draft-ietf-mile-template-00.txt Abstract This document provides guidelines for extensions to IODEF [RFC5070] for lightweight exchange of incident management data, and contains a template for Internet-Drafts describing those extensions, in order to ease the work and improve the quality of extension descriptions. It also specifies additional Expert Review of XML Schemas used to describe these extensions. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on May 20, 2012. Copyright Notice Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of Trammell Expires May 20, 2012 [Page 1]
Internet-Draft MILE Guidelines November 2011 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Applicability of Extensions to IODEF . . . . . . . . . . . . . 3 3. Selecting a Mechanism for IODEF Extension . . . . . . . . . . 4 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 6.1. Normative References . . . . . . . . . . . . . . . . . . . 6 6.2. Informative References . . . . . . . . . . . . . . . . . . 6 Appendix A. Document Template . . . . . . . . . . . . . . . . . . 7 A.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 7 A.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 A.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 7 A.4. Extension Definition . . . . . . . . . . . . . . . . . . . 8 A.4.1. IODEF Data Types . . . . . . . . . . . . . . . . . . . 8 A.4.2. Example Enumerated Type Extension Definition: E.164 Address . . . . . . . . . . . . . . . . . . . . 9 A.4.3. Example Element Definition: Test . . . . . . . . . . . 10 A.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 11 A.6. Security Considerations . . . . . . . . . . . . . . . . . 11 A.7. IANA Considerations . . . . . . . . . . . . . . . . . . . 11 A.8. Appendix: XML Schema Definition for Extension . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 Trammell Expires May 20, 2012 [Page 2]
Internet-Draft MILE Guidelines November 2011 1. Introduction Since the specification of IODEF [RFC5070], the evolution of the threat environment and the practice of cooperative network defense, along with continued implementation and deployment, has indicated the need for guidelines for the implementation and extension of IODEF. This document provides these guidelines. It starts by describing the applicability of IODEF extensions, and the IODEF extension mechanisms, before providing a section Appendix A that is itself designed to be copied out and filled in as the starting point of an Internet-Draft about an IODEF extension. Additionally, IODEF extensions via class extension through AdditionalData and RecordItem elements, as per section 5.2 of [RFC5070], generally register their namespaces and schemas with the IANA XML Namespace registry at http://www.iana.org/assignments/xml-registry/ns.html and the IANA XML Schema registry at http://www.iana.org/assignments/xml-registry/schema.html, respectively [RFC3688]. In addition to schema reviews required by IANA, these registry requests should be accompanied by a review by IODEF experts to ensure the specified AdditionalData and/or RecordItem contents are compatible with IODEF and with other existing IODEF extensions. This document specifies that review in Section 5. 2. Applicability of Extensions to IODEF Before deciding to extend IODEF, the first step is to determine whether an IODEF extension is a good fit for a given problem. There are two sides to this question: 1. Does the problem involve the reporting or sharing of information about an incident? "Incident" is not defined in the terminology for IODEF, but for purposes of IODEF can be loosely described as "something that happened that has some impact on the information security situation of an entity", with quite a bit of leeway for interpretation. If the answer to this question is unequivocally "No", then IODEF is probably not a good choice as a base technology for the application area. 2. Can IODEF adequately represent information about the incident without extension? IODEF has a reasonably rich set of incident- relevant classes. If, after examination of the problem area and the IODEF specification, the answer to this question is "Yes", then extension is not necessary. A non-exhaustive list of good candidate extensions to IODEF includes: Trammell Expires May 20, 2012 [Page 3]
Internet-Draft MILE Guidelines November 2011 1. Allowing standardized reference to external information bases about incidents and incident-relevant information: leveraging existing work in describing aspects of incidents to make IODEF more expressive 2. Allowing the description of new types of entities (e.g., related actors) or new types of characteristics of entities (e.g., financial services-related information) involved in an IODEF incident report 3. Allowing additional semantic or metadata labeling of IODEF Documents (e.g., for handling or disposition instructions, or compliance with data protection and data retention regulations) 3. Selecting a Mechanism for IODEF Extension IODEF was designed to be extended through any combination of: 1. extending the enumerated values of Attributes, as per section 5.1 of [RFC5070]; 2. class extension through AdditionalData and RecordItem elements, as per section 5.2 of [RFC5070]; and/or 3. containment of the IODEF-Document element within an external XML Document, itself containing extension data. Note that in this final case, the extension will not be directly interoperable with IODEF implementations, and must "unwrap" the IODEF document from its container; nevertheless, this may be appropriate for certain use cases involving integration with IODEF within external schemas. Extensions using containment of an IODEF-Document are not further treated in this document, though the document template in Appendix A may be of some use in defining them. Certain attributes containing enumerated values within certain IODEF elements may be extended. For an attribute named "foo", this is achieved by giving the value of "foo" as "ext-value", and adding a new attribute named "ext-foo" containing the extended value. The attributes which can be extended in this way are defined in [RFC5070], and limited to the following: o Incident@purpose o Contact@role Trammell Expires May 20, 2012 [Page 4]
Internet-Draft MILE Guidelines November 2011 o Contact@type o RegistryHandle@registry o Impact@type o TimeImpact@metric o TimeImpact@duration o HistoryItem@action o Expectation@action o System@category o Counter@type o Counter@duration o Address@category o NodeRole@category o RecordPattern@type o RecordPattern@offsetunit o AdditionalData@dtype o RecordItem@dtype An example definition of an attribute extension is given in Appendix A.4.2. IODEF documents can contain extended scalar or XML data using an AdditionalData element or a RecordItem element. Scalar data extensions MUST set the "dtype" attribute of the containing element to the data type to reference one of the IODEF data types as enumerated in Appendix A.4.1, and SHOULD define the use the "meaning" and "formatid" attributes to explain the content of the element. XML extensions within an AdditionalData or RecordItem element use a dtype of "xml", and SHOULD define a schema for the root element within the AdditionalData or RecordItem attribute. An example definition of an element definition is given in Appendix A.4.3. Trammell Expires May 20, 2012 [Page 5]
Internet-Draft MILE Guidelines November 2011 4. Security Considerations This document defines a template for MILE extensions to the IODEF and RID documents; as such, it has no security considerations on its own. 5. IANA Considerations Changes to the XML Schema registry for schema names beginning with "urn:ietf:params:xml:schema:iodef" are subject to an additional IODEF Expert Review [RFC5226]. The IODEF expert(s) for these reviews will be designated by the IETF Security Area Directors. [IANA NOTE: The authors request that IANA include a note at the top of http://www.iana.org/assignments/xml-registry/schema.html, stating "Changes to the XML Schema registry for schema names beginning with 'urn:ietf:params:xml:schema:iodef' are subject to an additional IODEF Expert Review [RFC5226]," and naming the designated expert.] 6. References 6.1. Normative References [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident Object Description Exchange Format", RFC 5070, December 2007. [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. [RFC6045] Moriarty, K., "Real-time Inter-network Defense (RID)", RFC 6045, November 2010. 6.2. Informative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2373] Hinden, R. and S. Deering, "IP Version 6 Addressing Architecture", RFC 2373, July 1998. [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, Trammell Expires May 20, 2012 [Page 6]
Internet-Draft MILE Guidelines November 2011 August 1998. [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April 2001. [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002. [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, July 2003. [RFC4519] Sciberras, A., "Lightweight Directory Access Protocol (LDAP): Schema for User Applications", RFC 4519, June 2006. [RFC6116] Bradner, S., Conroy, L., and K. Fujiwara, "The E.164 to Uniform Resource Identifiers (URI) Dynamic Delegation Discovery System (DDDS) Application (ENUM)", RFC 6116, March 2011. Appendix A. Document Template The document template given in this section is provided as a starting point for writing an Internet-Draft describing an IODEF extension. A.1. Introduction The introduction section introduces the problem being solved by the extension, and motivates the development and deployment of the extension. A.2. Terminology The terminology section introduces and defines terms specific to the document. Terminology from [RFC5070] or [RFC6045] should be referenced in this section, but not redefined or copied. If [RFC2119] terms are used in the document, this should be noted in the terminology section. A.3. Applicability The applicability section defines the use cases to which the extension is applicable, and details any requirements analysis done during the development of the extension. The primary goal of this section is to allow readers to see if an extension is indeed intended to solve a particular problem. This should also the scope of the Trammell Expires May 20, 2012 [Page 7]
Internet-Draft MILE Guidelines November 2011 extension, as appropriate, by pointing out any non-obvious situations to which it is not intended to apply. In addition to defining the applicability, this section may also present example situations, which should then be detailed in the examples section, below. A.4. Extension Definition This section defines the extension. Extensions to enumerated types are defined in one subsection for each attribute to be extended, enumerating the new values with an explanation of the meaning of the new value. An example enumeration extension is shown in Appendix A.4.2, below. Element extensions are defined in one subsection for each element, in top-down order, from the element contained within AdditionalData or RecordItem; an example element extension is shown in Appendix A.4.3, below. Each element should be described by a UML diagram as in Figure 1, followed by a description of each of the attributes, and a short description of each of the child elements. Child elements should then be defined in a subsequent subsection, if not already defined in the IODEF document itself, or in another referenced MILE extension document. +---------------------+ | Element | +---------------------+ | TYPE attribute0 |<>----------[ChildExactlyOne] | TYPE attribute1 |<>--{0..1}--[ChildZeroOrOne] | |<>--{0..*}--[ChildZeroOrMore] | |<>--{1..*}--[ChildOneOrMore] +---------------------+ Figure 1: Example UML Element Diagram Elements containing child elements should indicate the multiplicity of those child elements, as shown in the figure above. Allowable TYPEs are discussed in the following subsection. A.4.1. IODEF Data Types The allowable TYPEs for attributes within IODEF are enumerated in section 2 of [RFC5070], and consist of: o INTEGER Trammell Expires May 20, 2012 [Page 8]
Internet-Draft MILE Guidelines November 2011 o REAL o CHARACTER o STRING o ML_STRING (for strings in encodings other than that of the enclosing document) o BYTE for bytes or byte vectors in Base 64 encoding o HEXBIN for bytes in ascii-hexadecimal encoding o ENUM for enumerated types; allowable values of the enumeration must be defined in the attribute definition o DATETIME for ISO 8601:2000 [RFC3339] encoded timestamps o TIMEZONE for timezones as encoded in section 2.9 of [RFC5070]. o PORTLIST for port lists as encoded in section 2.10 of [RFC5070]. o POSTAL for postal addresses as defined in section 2.23 of [RFC4519]. o NAME for names of natural or legal persons as defined in section 2.3 of [RFC4519]. o PHONE for telephone numbers as defined in section 2.35 of [RFC4519]. o EMAIL for email addresses as defined in section 3.4.1. of [RFC2822]. o URL for URLs as in [RFC2396]. In addition to these simple data types, IODEF provides a compound data type for representing network address information. Addresses included within an extension element should be represented by containing an IODEF:Address element, which supports IPv4 and [RFC2373] IPv6 addresses, as well as MAC, ATM, and BGP autonomous system numbers. Application-layer addresses should be represented with the URL simple attribute type, instead. A.4.2. Example Enumerated Type Extension Definition: E.164 Address This example extends the IODEF Address element to support the encoding of ENUM-mapped telephone numbers [RFC6116]. Trammell Expires May 20, 2012 [Page 9]
Internet-Draft MILE Guidelines November 2011 Attribute: Address@category Extended value(s): enum-e164 Content format: An E.164 telephone number encoded as a domain name in the e164.int space, e.g. "2.1.2.1.5.5.5.2.1.2.1.e164.int." for +1 212 555 1212, as per section 3.2 of [RFC6116]. Additional considerations: none. A.4.3. Example Element Definition: Test This example defines the Test class for labeling IODEF test data. The Test class is intended to be included within an AdditionalData element in an IODEF Document. If a Test element is present, it indicates that an IODEF Document contains test data, not a reference to a real incident. The Test class contains information about how the test data was generated. +---------------------+ | Test | +---------------------+ | ENUM category | | STRING generator | | | | | +---------------------+ Figure 2: The Test class The Test class has two attributes: category: Required. ENUM. The type of test data. The permitted values for this attribute are shown below. The default value is "unspecified". 1. unspecified. The document contains test data, but no further information is available. 2. internal. The test data is intended for the internal use of an implementor, and should not be distributed or used outside the context in which it was generated. 3. unit. The test data is intended for unit testing of an implementation, and may be included with the implementation to Trammell Expires May 20, 2012 [Page 10]
Internet-Draft MILE Guidelines November 2011 support this as part of the build and deployment process. 4. interoperability. The test data is intended for interoperability testing of an implementation, and may be freely shared to support this purpose. generator: Optional. STRING. A free-form string identifying the person, entity, or program which generated the test data. A.5. Examples This section contains example IODEF-Documents illustrating the extension. If example situations are outlined in the applicability section, documents for those examples should be provided in the same order as in the applicability section. Example documents should be tested to validate against the schema given in the appendix. A.6. Security Considerations [SECDIR and RFC-EDITOR NOTE: Despite the title, this section is NOT a Security Considerations section, rather a template Security Considerations section for future extension documents to be built from this template. See Section 4 for Security Considerations for this document.] Any security considerations [RFC3552] raised by this extension or its deployment should be detailed in this section. Guidance should focus on ensuring the users of this extension do so in a secure fashion, with special attention to non-obvious implications of the transmission or storage of the information represented by an extension. A.7. IANA Considerations [IANA and RFC-EDITOR NOTE: Despite the title, this section is NOT an IANA Considerations section, rather a template IANA Considerations section for future extension documents to be built from this template. See Section 5 for IANA Considerations for this document.] Any IANA considerations [RFC5226] for the document should be detailed in this section; if none, the section should exist and contain the text "this document has no actions for IANA". IODEF Extensions adding elements to the AdditionalData section of an IODEF document should register their own namespaces and schemas for extensions with IANA; therefore, this section should contain at least a registration request for the namespace and the schema, as follows, modified as appropriate for the extension: Trammell Expires May 20, 2012 [Page 11]
Internet-Draft MILE Guidelines November 2011 Registration request for the IODEF My-Extension namespace: URI: urn:ietf:params:xml:ns:iodef-myextension-1.0 Registrant Contact: Refer here to the authors' addresses section of the document, or to an organizational contact in the case of an extension supported by an external organization. XML: None Registration request for the IODEF My-Extension XML schema: URI: urn:ietf:params:xml:schema:iodef-myextension-1.0 Registrant Contact: Refer here to the authors' addresses section of the document, or to an organizational contact in the case of an extension supported by an external organization. XML: Refer here to the XML Schema in the appendix of the document, or to a well-known external reference in the case of an extension with an externally-defined schema. A.8. Appendix: XML Schema Definition for Extension The XML Schema describing the elements defined in the Extension Defintion section is given here. Each of the examples in section Appendix A.5 should be verified to validate against this schema by automated tools. Author's Address Brian Trammell Swiss Federal Institute of Technology Zurich Gloriastrasse 35 8092 Zurich Switzerland Phone: +41 44 632 70 13 Email: trammell@tik.ee.ethz.ch Trammell Expires May 20, 2012 [Page 12]
