mile Working Group                                           B. Trammell
Internet-Draft                                                ETH Zurich
Intended status: Informational                              May 10,                              June 8, 2012
Expires: November 11, December 10, 2012

        Guidelines and Template for Defining Extensions to IODEF


   This document provides guidelines for extensions to IODEF the Incident
   Object Description Exchange Format (IODEF) [RFC5070] for 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.

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

   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 November 11, December 10, 2012.

Copyright Notice

   Copyright (c) 2012 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
   ( 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
   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  . . . . . . . . . . . . . . . . . . .  5  6
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  5  6
   6.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . .  5  6
   7.  References . . . . . . . . . . . . . . . . . . . . . . . . . .  6
     7.1.  Normative References . . . . . . . . . . . . . . . . . . .  6
     7.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 . . . . . . . . . . . . . . . . . . .  7
       A.4.1.  IODEF Data Types . . . . . . . . . . . . . . . . . . .  8
     A.5.  Security Considerations  . . . . . . . . . . . . . . . . .  9  8
     A.6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . 10  9
     A.7.  References . . . . . . . . .  Manageability Considerations . . . . . . . . . . . . . . . 11 10
     A.8.  Appendix A: XML Schema Definition for Extension  . . . . . 11 10
     A.9.  Appendix B: Examples . . . . . . . . . . . . . . . . . . . 11 10
   Appendix B.  Example Enumerated Type Extension Definition:
                E.164 Address . . .
                Presentation Action . . . . . . . . . . . . . . . . . 11 10
   Appendix C.  Example Element Definition: Test  . . . . . . . . . . 11
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.  Introduction

   In the five years since the specification of IODEF [RFC5070], the
   threat environment has evolved, as has the practice of cooperative
   network defense.  These trends, along with experience gained through
   implementation and deployment, have indicated the need to extend
   IODEF.  This document provides guidelines for defining these
   extensions.  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 for an Internet-Draft about an IODEF

   This document is designed to give guidance on the extension of IODEF,
   especially for those extension authors who may be new to the IETF
   process.  Nothing in this document should be construed as defining
   policies for the definition of these extensions.

   At publication time, the Managed Incident Lightweight Exchange (MILE)
   working group of the IETF provides a home for work on IODEF
   extensions that do not otherwise have a natural home.  IODEF
   extensions that require the expertise of other IETF working groups or
   other standards development organizations may be done within those
   groups with consultation of IODEF experts, such as those appointed
   for review as in [I-D.ietf-mile-iodef-xmlreg].

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
       observations, indications, or other information about an
       incident, whether in progress or completed, hypothetical or real?
       "Incident" is defined in the terminology for the original IODEF
       requirements [RFC3067]: an event that involves a security
       violation, whether a single attack of a group thereof.  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 rich set of incident-relevant
       classes.  If, after detailed examination of the problem area and
       the IODEF specification, and consultation with IODEF experts, the
       answer to this question is "Yes", then extension is not

   A non-exhaustive list

   Examples of good candidate such extensions to IODEF includes: might include:

   o  Leveraging existing work in describing aspects of incidents to
      make IODEF more expressive, by standardized reference to external
      information bases about incidents and incident-related information

   o  Allowing the description of new types of entities (e.g., related
      actors) or new types of characteristics of entities (e.g.,
      information related to financial services) involved in an IODEF
      incident report

   o  Allowing the representation of new types of indicators,
      observables, or incidents in an IODEF incident report

   o  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 or 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. data, as done by RID

   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 of 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 this way are limited to the
   following, denoted in 'Element@attribute' format, referencing the
   section in which they are defined in [RFC5070]:

      Incident@purpose, section 3.2
      AdditionalData@dtype, section 3.6
      Contact@role, section 3.7
      Contact@type, section 3.7
      RegistryHandle@registry, section 3.7.1
      Impact@type, section 3.10.1
      TimeImpact@metric, section 3.10.2
      TimeImpact@duration, section 3.10.2
      HistoryItem@action, section 3.11.1
      Expectation@action, section 3.13
      System@category, section 3.15
      Counter@type, section 3.16.1
      Counter@duration, section 3.16.1
      Address@category, section 3.16.2
      NodeRole@category, section 3.16.3
      RecordPattern@type, section 3.19.2
      RecordPattern@offsetunit, section 3.19.2
      RecordItem@dtype, section 3.19.3

   Note that this list is present current as of publication time; the set of
   IODEF Data Types may be extended by future specifications which
   update [RFC5070].

   An example definition of an attribute extension is given in
   Appendix B.

   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, inin section 2 of [RFC5070], and should 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 topmost containing
   element within the AdditionalData or RecordItem element.  An example
   definition of an element definition is given in Appendix C.

   When adding elements to the AdditionalData section of an IODEF
   document, an extension's namespace and schema should be registered
   with IANA; see Appendix A.6 for details.

4.  Security Considerations

   This document defines a raises no security issues itself.  Extensions defined
   using the template for extensions in Appendix A need to IODEF; the provide an analysis of
   security considerations issues they may raise.  See Appendix A.5 for IODEF [RFC5070] apply. details.

5.  IANA Considerations

   This document contains no considerations for IANA.

6.  Acknowledgments

   Thanks to David Black, Takeshi Takahashi, Benoit Claise, Martin Duerst, Eran Hammer, Tom
   Millar, and Kathleen
   Moriarty Moriarty, Peter Saint-Andre, Robert Sparks, Takeshi
   Takahashi, Sean Turner, Samuel Weiler, and Peter Yee, for their
   reviews and comments.  This work is materially supported by the
   European Union Seventh Framework Program under grant agreement 257315

7.  References

7.1.  Normative References

   [RFC5070]  Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident
              Object Description Exchange Format", RFC 5070,
              December 2007.

   [RFC6545]  Moriarty, K., "Real-time Inter-network Defense (RID)",
              RFC 6545, April 2012.

7.2.  Informative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3067]  Arvidsson, J., Cormack, A., Demchenko, Y., and J. Meijer,
              "TERENA'S Incident Object Description and Exchange Format
              Requirements", RFC 3067, February 2001.

   [RFC3986]  Berners-Lee, T., Fielding, R.,

   [RFC3552]  Rescorla, E. and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66, B. Korver, "Guidelines for Writing RFC 3986, January 2005.

   [RFC5226]  Narten, T.
              Text on Security Considerations", BCP 72, RFC 3552,
              July 2003.

   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
              May 2008.

   [RFC5322]  Resnick, P., Ed., "Internet Message Format", RFC 5322,
              October 2008.

   [RFC3339]  Klyne, G., Ed. and C. Newman, "Date and Time on the
              Internet: Timestamps", RFC 3339, July 2002.

   [RFC3552]  Rescorla, E. and B. Korver,

   [RFC5706]  Harrington, D., "Guidelines for Writing RFC
              Text on Security Considerations", BCP 72, RFC 3552,
              July 2003.

   [RFC4519]  Sciberras, A., "Lightweight Directory Access Considering Operations and
              Management of New Protocols and Protocol
              (LDAP): Schema for User Applications", Extensions",
              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)", 5706, November 2009.

   [RFC6545]  Moriarty, K., "Real-time Inter-network Defense (RID)",
              RFC 6116,
              March 2011. 6545, April 2012.

              Trammell, B., "Expert Review for IODEF Extensions in IANA
              XML Registry", draft-ietf-mile-iodef-xmlreg-01 (work in
              progress), May 2012.

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.
   In addition
   RFCs are subject to the sections given here, an Internet-Draft additional formatting requirements and must also
   contain an Abstract, Status of This Memo, Copyright Notice, and
   Author's Addresses sections: additional sections not described in this template; consult
   the RFC Editor style guide
   ( for more information.

   This template is informational in nature; in case of any future
   conflict with RFC Editor requirements for Internet-Drafts, those
   requirements take precedence.

A.1.  Introduction

   The introduction section introduces the problem being solved by the
   extension, and motivates the development and deployment of the

A.2.  Terminology

   The terminology section introduces and defines terms specific to the
   document.  Terminology from [RFC5070] or [RFC6545] 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 given problem.  This section should also define and
   restrict the scope of the extension, as appropriate, by pointing out
   any non-
   obvious 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 each new value.  An example enumeration
   extension is shown in Appendix B, 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 C,
   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 IODEF
   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  REAL


   o  STRING

   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 [RFC3339]-encoded timestamps

   o  TIMEZONE for timezones as described in section 2.9 of [RFC5070].

   o  PORTLIST for port lists as described in section 2.10 of [RFC5070].

   o  POSTAL for postal addresses as described in section 2.23 of

   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

   o  EMAIL for email addresses as defined in section 3.4.1. of

   o  URL for URIs as in [RFC3986].

   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 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.

   Note that this list is present as of publication time; the set of
   IODEF Data Types may be extended by future specifications which
   update [RFC5070].

A.5.  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 of the information represented by this extension.
   [RFC3552] may be a useful reference in determining what to cover in
   this section.  This section is required by the RFC Editor.

   It should also be noted in this section that the security
   considerations for IODEF [RFC5070] apply to the extension as well.

A.6.  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.  Note that IODEF extension documents will generally
   register new namespaces and schemas.  In addition, this section is
   required by the RFC Editor, so if there are no IANA considerations,
   the section should exist and contain the text "this document has no
   actions for IANA".

   IODEF Extensions which represent an enumeration should reference an
   existing IANA registry or subregistry for the values of that
   enumeration.  If no such registry exists, this section should define
   a new registry to hold the enumeration's values, and define the
   policies by which additions may be made to the registry.

   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:

   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 Appendix A of the document, or
   to a well-known external reference in the case of an extension with
   an externally-defined schema.

A.7.  References

   This section lists RFCs, internet-drafts and other documents
   referenced from  Manageability Considerations

   If any of the operational and/or management considerations listed in
   Appendix A of [RFC5706] apply to the extension, split into normative and informative
   references.  This address them in this
   section.  If no such considerations apply, this section is required by the RFC Editor can be

A.8.  Appendix A: 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.9 will be verified to validate against this schema by
   automated tools.

A.9.  Appendix B: 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 will be
   tested to validate against the schema given in the appendix.

Appendix B.  Example Enumerated Type Extension Definition: E.164 Address Presentation

   This example extends the IODEF Address Expectation element to support represent the
   encoding of ENUM-mapped telephone numbers [RFC6116].
   expectation that a slide deck be derived from the IODEF Incident, and
   that a presentation be given by the recipient's organization thereon.

   Attribute: Address@category Expectation@action

   Extended value(s): enum-e164 give-a-presentation

   Value meaning meaning: generate a slide deck from the provided incident
   information and format: An E.164 telephone number encoded as give a
   domain name in presentation thereon.

   Additional considerations: the space, e.g.
   "" format of the slide deck is left to
   the recipient to determine in accordance with its established
   practices for +1 212 555 1212, as per section
   3.2 the presentation of [RFC6116].

   Additional considerations: none. incident reports.

Appendix C.  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
   information about a real incident.

   The Test class contains information about how the test data was

   | 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

      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
          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.

Author's Address

   Brian Trammell
   Swiss Federal Institute of Technology Zurich
   Gloriastrasse 35
   8092 Zurich

   Phone: +41 44 632 70 13