Guidelines for Extensions to IODEF for Managed Incident Lightweight Exchange
draft-trammell-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.

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 January 05, 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 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 2. Applicability of Extensions to IODEF
• 3. Selecting a Mechanism for IODEF Extension
• 4. Conventions used in MILE Extension Documents
• 5. Document Template
• 5.1. Introduction
• 5.2. Terminology
• 5.3. Applicability
• 5.4. Extension Definition
• 5.4.1. IODEF Data Types
• 5.4.2. Example Enumerated Type Extension Definition
• 5.4.3. Example Element Definition
• 5.5. Examples
• 5.6. Security Considerations
• 5.7. IANA Considerations
• 5.8. Appendix: XML Schema Definition for Extension
• 6. Security Considerations
• 7. IANA Considerations
• 8. References
• 8.1. Normative References
• 8.2. Informative References
• Author's Address

1. Introduction

[TODO]

2. Applicability of Extensions to IODEF

[TODO: explain what makes a good IODEF extension. basically: is it a noun?]

3. Selecting a Mechanism for IODEF Extension

IODEF was designed to be extended through any combination of

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.

4. Conventions used in MILE Extension Documents

This section outlines conventions used in MILE extension documents. Following these conventions ensures the documents produced by the MILE effort have a consistent terminology and are easily readable as a set.

5. Document Template

Documents describing am IODEF extension should follow the document template given in this section.

5.1. Introduction

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

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

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

In addition to defining the applicability, this section may also present example situations, which should then be detailed in the examples section, below.

5.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 Section 5.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 Section 5.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]
+---------------------+

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.

The allowable TYPEs for attributes within IODEF are enumerated in section 2 of [RFC5070], and consist of:

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.

5.4.1. IODEF Data Types

5.4.2. Example Enumerated Type Extension Definition

[TODO provide an example]

5.4.3. Example Element Definition

[TODO provide an example]

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

5.6. Security Considerations

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.

5.7. IANA Considerations

[IANA 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 7 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:

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.

5.8. Appendix: XML Schema Definition for Extension

The XML Schema describing the elements defined in the Extension Defintion section is given here.

[TODO: provide guidelines for hacking schemas]

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

7. IANA Considerations

This document has no actions for IANA.

8. References

8.1. Normative References

8.2. Informative References

Author's Address