Individual Submission B. Trammell
Internet-Draft ETH Zurich
Intended status: Informational July 4, 2011
Expires: January 5, 2012
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 5, 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.
Trammell Expires January 5, 2012 [Page 1]
Internet-Draft MILE Template July 2011
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Applicability of Extensions to IODEF . . . . . . . . . . . . . 3
3. Selecting a Mechanism for IODEF Extension . . . . . . . . . . . 3
4. Conventions used in MILE Extension Documents . . . . . . . . . 3
5. Document Template . . . . . . . . . . . . . . . . . . . . . . . 3
5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3
5.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4
5.3. Applicability . . . . . . . . . . . . . . . . . . . . . . . 4
5.4. Extension Definition . . . . . . . . . . . . . . . . . . . 4
5.4.1. IODEF Data Types . . . . . . . . . . . . . . . . . . . 5
5.4.2. Example Enumerated Type Extension Definition . . . . . 6
5.4.3. Example Element Definition . . . . . . . . . . . . . . 6
5.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.6. Security Considerations . . . . . . . . . . . . . . . . . . 6
5.7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 6
5.8. Appendix: XML Schema Definition for Extension . . . . . . . 7
6. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8
8.1. Normative References . . . . . . . . . . . . . . . . . . . 8
8.2. Informative References . . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9
Trammell Expires January 5, 2012 [Page 2]
Internet-Draft MILE Template July 2011
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
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.
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
Trammell Expires January 5, 2012 [Page 3]
Internet-Draft MILE Template July 2011
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.
Trammell Expires January 5, 2012 [Page 4]
Internet-Draft MILE Template July 2011
+---------------------+
| 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.
5.4.1. IODEF Data Types
The allowable TYPEs for attributes within IODEF are enumerated in
section 2 of [RFC5070], and consist of:
o INTEGER
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].
Trammell Expires January 5, 2012 [Page 5]
Internet-Draft MILE Template July 2011
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.
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
Trammell Expires January 5, 2012 [Page 6]
Internet-Draft MILE Template July 2011
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.
Trammell Expires January 5, 2012 [Page 7]
Internet-Draft MILE Template July 2011
7. IANA Considerations
This document has no actions for IANA.
8. References
8.1. Normative References
[RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident
Object Description Exchange Format", RFC 5070,
December 2007.
[RFC6045] Moriarty, K., "Real-time Inter-network Defense (RID)",
RFC 6045, November 2010.
8.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,
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.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
Trammell Expires January 5, 2012 [Page 8]
Internet-Draft MILE Template July 2011
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 January 5, 2012 [Page 9]