One document matched: draft-ietf-mile-template-05.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<rfc ipr="trust200902" category="info" docName="draft-ietf-mile-template-05.txt">
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<front>
<title abbrev="IODEF Extension Guidelines">
Guidelines and Template for Defining Extensions to IODEF
</title>
<author initials="B." surname="Trammell" fullname="Brian Trammell">
<organization abbrev="ETH Zurich">
Swiss Federal Institute of Technology Zurich
</organization>
<address>
<postal>
<street>Gloriastrasse 35</street>
<city>8092 Zurich</city>
<country>Switzerland</country>
</postal>
<phone>+41 44 632 70 13</phone>
<email>trammell@tik.ee.ethz.ch</email>
</address>
</author>
<date month='June' day='8' year='2012' />
<area>Security</area>
<workgroup>mile Working Group</workgroup>
<abstract>
<t>This document provides guidelines for extensions to the Incident Object
Description Exchange Format <xref target="RFC5070">(IODEF)</xref> 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. <!--It also specifies
additional Expert Review of XML Schemas used to describe these
extensions.--></t>
</abstract>
</front>
<middle>
<section title="Introduction" anchor="sec-intro">
<t>In the five years since the specification of <xref
target="RFC5070">IODEF</xref>, 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 (<xref
target="sec-template"/>) that is itself designed to be copied out and filled
in as the starting point for an Internet-Draft about an IODEF extension.</t>
<t>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.</t>
<t>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 <xref
target="I-D.ietf-mile-iodef-xmlreg"/>.</t>
<!--<t>Additionally, IODEF extensions through AdditionalData
and RecordItem elements, as per section 5.2 of <xref target="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 <xref
target="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 <xref target="sec-iana"/>.</t>-->
</section>
<!-- <section title="Terminology">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <xref target="RFC2119"/>.</t>
</section> -->
<section title="Applicability of Extensions to IODEF">
<t>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:</t>
<t><list style="numbers">
<t>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 <xref target="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.</t>
<t>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 necessary.</t>
</list></t>
<t>Examples of such extensions to IODEF might include:</t>
<t><list style="symbols">
<t>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</t>
<t>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</t>
<t>Allowing the representation of new types of indicators, observables,
or incidents in an IODEF incident report</t>
<t>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)</t>
</list></t>
</section>
<section title="Selecting a Mechanism for IODEF Extension" anchor="sec-mechanisms">
<t>IODEF was designed to be extended through any combination of:</t>
<t><list style="numbers">
<t>extending the enumerated values of Attributes, as per section 5.1 of
<xref target="RFC5070"/>;</t>
<t>class extension through AdditionalData or RecordItem elements, as
per section 5.2 of <xref target="RFC5070"/>; and/or</t>
<t>containment of the IODEF-Document element within an external XML
Document, itself containing extension data, as done by RID <xref
target="RFC6545"/>.</t>
</list></t>
<t>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 <xref
target="sec-template"/> may be of some use in defining them.</t>
<t>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 <xref target="RFC5070"/>:</t>
<t><list style="empty">
<t>Incident@purpose, section 3.2<vspace blankLines='0'/>
AdditionalData@dtype, section 3.6<vspace blankLines='0'/>
Contact@role, section 3.7<vspace blankLines='0'/>
Contact@type, section 3.7<vspace blankLines='0'/>
RegistryHandle@registry, section 3.7.1<vspace blankLines='0'/>
Impact@type, section 3.10.1<vspace blankLines='0'/>
TimeImpact@metric, section 3.10.2<vspace blankLines='0'/>
TimeImpact@duration, section 3.10.2<vspace blankLines='0'/>
HistoryItem@action, section 3.11.1<vspace blankLines='0'/>
Expectation@action, section 3.13<vspace blankLines='0'/>
System@category, section 3.15<vspace blankLines='0'/>
Counter@type, section 3.16.1<vspace blankLines='0'/>
Counter@duration, section 3.16.1<vspace blankLines='0'/>
Address@category, section 3.16.2<vspace blankLines='0'/>
NodeRole@category, section 3.16.3<vspace blankLines='0'/>
RecordPattern@type, section 3.19.2<vspace blankLines='0'/>
RecordPattern@offsetunit, section 3.19.2<vspace blankLines='0'/>
RecordItem@dtype, section 3.19.3</t>
</list></t>
<t>Note that this list is current as of publication time; the set of
IODEF Data Types may be extended by future specifications which update
<xref target="RFC5070"/>.</t>
<t>An example definition of an attribute extension is given in <xref
target="ext-defenum"/>.</t>
<t>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 inin section 2 of
<xref target="RFC5070"/>, and should use the "meaning" and "formatid"
attributes to explain the content of the element.</t>
<t>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 <xref
target="ext-defelem"/>.</t>
<t>When adding elements to the AdditionalData section of an IODEF
document, an extension's namespace and schema should be registered with
IANA; see <xref target="ext-iana"/> for details.</t>
</section>
<section title="Security Considerations" anchor="sec-security">
<t>This document raises no security issues itself. Extensions defined using
the template in Appendix A need to provide an analysis of security issues
they may raise. See <xref target="ext-security"/> for details.</t>
</section>
<section title="IANA Considerations" anchor="sec-iana">
<t>This document contains no considerations for IANA.</t>
<!-- <t>Changes to the XML Schema registry for schema names beginning with
"urn:ietf:params:xml:schema:iodef" are subject to an additional IODEF <xref
target="RFC5226">Expert Review</xref>. The IODEF expert(s) for these reviews
will be designated by the IETF Security Area Directors.</t>
<t>[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 <xref
target="RFC5226">Expert Review</xref>," and naming the designated
expert.]</t> -->
</section>
<section title="Acknowledgments">
<t>Thanks to David Black, Benoit Claise, Martin Dürst, Eran Hammer, Tom
Millar, Kathleen 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 (DEMONS).</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include="reference.RFC.5070" ?>
</references>
<references title="Informative References">
<?rfc include="reference.RFC.2119" ?>
<?rfc include="reference.RFC.3067" ?>
<!-- <?rfc include="reference.RFC.3986" ?> -->
<!-- <?rfc include="reference.RFC.5322" ?> -->
<!-- <?rfc include="reference.RFC.3339" ?> -->
<?rfc include="reference.RFC.3552" ?>
<!-- <?rfc include="reference.RFC.4519" ?> -->
<!-- <?rfc include="reference.RFC.6116" ?> -->
<?rfc include="reference.RFC.5226" ?>
<?rfc include="reference.RFC.5706" ?>
<?rfc include="reference.RFC.6545" ?>
<?rfc include="reference.I-D.ietf-mile-iodef-xmlreg" ?>
</references>
<section title="Document Template" anchor="sec-template">
<t>The document template given in this section is provided as a starting
point for writing an Internet-Draft describing an IODEF extension. RFCs
are subject to additional formatting requirements and must contain
additional sections not described in this template; consult the RFC Editor
style guide (http://www.rfc-editor.org/styleguide.html) for more
information.</t>
<t>This template is informational in nature; in case of any future
conflict with RFC Editor requirements for Internet-Drafts, those
requirements take precedence.</t>
<section title="Introduction" anchor="ext-intro">
<t>The introduction section introduces the problem being solved by the
extension, and motivates the development and deployment of the
extension.</t>
</section>
<section title="Terminology" anchor="ext-terminology">
<t>The terminology section introduces and defines terms specific to the
document. Terminology from <xref target="RFC5070"/> or <xref
target="RFC6545"/> should be referenced in this section,
but not redefined or copied. If <xref target="RFC2119"/> terms are used in
the document, this should be noted in the terminology section.</t>
</section>
<section title="Applicability" anchor="ext-applicability">
<t>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 situations to
which it is not intended to apply.</t>
<t>In addition to defining the applicability, this section may also
present example situations, which should then be detailed in the examples
section, below.</t>
</section>
<section title="Extension Definition" anchor="ext-definition">
<t>This section defines the extension.</t>
<t>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 <xref target="ext-defenum"/>, below.</t>
<t>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 <xref
target="ext-defelem"/>, below. Each element should be described by a UML
diagram as in <xref target="fig-element"/>, 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.</t>
<figure title="Example UML Element Diagram" anchor="fig-element">
<artwork><![CDATA[
+---------------------+
| Element |
+---------------------+
| TYPE attribute0 |<>----------[ChildExactlyOne]
| TYPE attribute1 |<>--{0..1}--[ChildZeroOrOne]
| |<>--{0..*}--[ChildZeroOrMore]
| |<>--{1..*}--[ChildOneOrMore]
+---------------------+
]]></artwork>
</figure>
<t>Elements containing child elements should indicate the multiplicity of those child elements, as shown in the figure above. Allowable TYPEs are are enumerated in section 2 of <xref target="RFC5070"/>.</t>
<!--
<t><list style="symbols">
<t>INTEGER</t>
<t>REAL</t>
<t>CHARACTER</t>
<t>STRING</t>
<t>ML_STRING (for strings in encodings other than that of the enclosing document)</t>
<t>BYTE for bytes or byte vectors in Base 64 encoding</t>
<t>HEXBIN for bytes in ascii-hexadecimal encoding</t>
<t>ENUM for enumerated types; allowable values of the enumeration must be defined in the attribute definition</t>
<t>DATETIME for <xref target="RFC3339"/>-encoded timestamps</t>
<t>TIMEZONE for timezones as described in section 2.9 of <xref target="RFC5070"/>.</t>
<t>PORTLIST for port lists as described in section 2.10 of <xref target="RFC5070"/>.</t>
<t>POSTAL for postal addresses as described in section 2.23 of <xref target="RFC4519"/>.</t>
<t>NAME for names of natural or legal persons as defined in section 2.3 of <xref target="RFC4519"/>.</t>
<t>PHONE for telephone numbers as defined in section 2.35 of <xref target="RFC4519"/>.</t>
<t>EMAIL for email addresses as defined in section 3.4.1. of <xref target="RFC5322"/>.</t>
<t>URL for URIs as in <xref target="RFC3986"/>.</t>
</list></t>
<t>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.</t>
<t>Note that this list is present as of publication time; the set of
IODEF Data Types may be extended by future specifications which update
<xref target="RFC5070"/>.</t>
-->
</section>
<section title="Security Considerations" anchor="ext-security">
<t>[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
<xref target="sec-security"/> for Security Considerations for this
document.]</t>
<t>Any <xref target="RFC3552">security considerations</xref> 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. <xref
target="RFC3552"/> may be a useful reference in determining what to cover
in this section. This section is required by the RFC Editor.</t>
<t>It should also be noted in this section that the security
considerations for <xref target="RFC5070">IODEF</xref> apply to the
extension as well. </t>
</section>
<section title="IANA Considerations" anchor="ext-iana">
<t>[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 <xref
target="sec-iana"/> for IANA Considerations for this document.]</t>
<t>Any <xref target="RFC5226">IANA considerations</xref> 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".</t>
<t>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.</t>
<t>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:</t>
<t>Registration request for the IODEF My-Extension namespace:</t>
<t> URI: urn:ietf:params:xml:ns:iodef-myextension-1.0 </t>
<t> 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.</t>
<t> XML: None </t>
<t>Registration request for the IODEF My-Extension XML schema:</t>
<t> URI: urn:ietf:params:xml:schema:iodef-myextension-1.0 </t>
<t> 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.</t>
<t> 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.</t>
</section>
<section title="Manageability Considerations" anchor="ext-ops">
<t>If any of the operational and/or management considerations listed in Appendix A of <xref target="RFC5706"/> apply to the extension, address them in this section. If no such considerations apply, this section can be omitted.</t>
</section>
<!--
<section title="References">
<t>This section lists RFCs, internet-drafts and other documents referenced
from the extension, split into normative and informative references. This
section is required by the RFC Editor</t>
</section>
-->
<section title="Appendix A: XML Schema Definition for Extension" anchor="ext-schema">
<t>The XML Schema describing the elements defined in the Extension Defintion section is given here. Each of the examples in <xref target="ext-examples"/> will be verified to validate against this schema by automated tools.</t>
</section>
<section title="Appendix B: Examples" anchor="ext-examples">
<t>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.</t>
</section>
</section>
<section title="Example Enumerated Type Extension Definition: Presentation Action" anchor="ext-defenum">
<t>This example extends the IODEF Expectation element to represent the expectation that a slide deck be derived from the IODEF Incident, and that a presentation be given by the recipient's organization thereon.</t>
<t>Attribute: Expectation@action</t>
<t>Extended value(s): give-a-presentation</t>
<t>Value meaning: generate a slide deck from the provided incident
information and give a presentation thereon.</t>
<t>Additional considerations: the format of the slide deck is left to
the recipient to determine in accordance with its established practices
for the presentation of incident reports.</t>
</section>
<!--
<section title="Example Enumerated Type Extension Definition: E.164 Address" anchor="ext-defenum">
<t>This example extends the IODEF Address element to support the encoding of ENUM-mapped telephone numbers <xref target="RFC6116"/>.</t>
<t>Attribute: Address@category</t>
<t>Extended value(s): enum-e164</t>
<t>Value meaning and 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.arpa." for +1 212 555 1212, as per section 3.2 of <xref target="RFC6116"/>.</t>
<t>Additional considerations: none.</t>
</section>
-->
<section title="Example Element Definition: Test" anchor="ext-defelem">
<t>This example defines the Test class for labeling IODEF test data.</t>
<t>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.</t>
<t>The Test class contains information about how the test data was generated.</t>
<figure title="The Test class" anchor="fig-test">
<artwork><![CDATA[
+---------------------+
| Test |
+---------------------+
| ENUM category |
| STRING generator |
| |
| |
+---------------------+
]]></artwork>
</figure>
<t>The Test class has two attributes:</t>
<t><list style="hanging">
<t hangText="category: ">Required. ENUM. The type of test data. The permitted values for this attribute are shown below. The default value is "unspecified".
<list style="numbers">
<t>unspecified. The document contains test data, but no further information is available.</t>
<t>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.</t>
<t>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.</t>
<t>interoperability. The test data is intended for interoperability testing of an implementation, and may be freely shared to support this purpose.</t>
</list>
</t>
<t hangText="generator: ">Optional. STRING. A free-form string identifying the person, entity, or program which generated the test data.</t>
</list></t>
</section>
</back>
</rfc>| PAFTECH AB 2003-2026 | 2026-04-24 06:31:29 |