Guidelines for Defining Extensions to IODEF
Swiss Federal Institute of Technology Zurich
Gloriastrasse 358092 ZurichSwitzerland+41 44 632 70 13trammell@tik.ee.ethz.ch
Security
mile Working GroupThis document provides guidelines for extensions to IODEF 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.In the five years since the specification of IODEF, 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 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 through AdditionalData
and RecordItem elements, as per section 5.2 of ,
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 . 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 .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 .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: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.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: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 informationAllowing 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 reportAllowing additional semantic or metadata labeling of IODEF Documents (e.g., for handling or disposition instructions, or compliance with data protection and data retention regulations)IODEF was designed to be extended through any combination of:extending the enumerated values of Attributes, as per section 5.1 of ;class extension through AdditionalData and RecordItem elements, as per section 5.2 of ; and/orcontainment 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 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 Section 5.1 of , and limited to the following:Incident@purposeContact@roleContact@typeRegistryHandle@registryImpact@typeTimeImpact@metricTimeImpact@durationHistoryItem@actionExpectation@actionSystem@categoryCounter@typeCounter@durationAddress@categoryNodeRole@categoryRecordPattern@typeRecordPattern@offsetunitAdditionalData@dtypeRecordItem@dtypeAn example definition of an attribute extension is given in .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 , 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 .This document defines a template for extensions to IODEF; the
security considerations for IODEF apply.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. 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," and naming the designated
expert.]Thanks to David Black, Takeshi Takahashi, Tom Millar, and Kathleen Moriarty
for their comments. This work is materially supported by the European Union
Seventh Framework Program under grant agreement 257315 (DEMONS).The document template given in this section is provided as a starting
point for writing an Internet-Draft describing an IODEF extension.The introduction section introduces the problem being solved by the
extension, and motivates the development and deployment of the
extension.The terminology section introduces and defines terms specific to the
document. Terminology from or should be referenced in this section, but not redefined
or copied. If terms are used in the document,
this should be noted in the terminology section.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 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.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 , 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 , below. Each element should be described by a UML
diagram as in , 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.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 , and consist of:INTEGERREALCHARACTERSTRINGML_STRING (for strings in encodings other than that of the enclosing document)BYTE for bytes or byte vectors in Base 64 encodingHEXBIN for bytes in ascii-hexadecimal encodingENUM for enumerated types; allowable values of the enumeration must be defined in the attribute definitionDATETIME for ISO 8601:2000 encoded timestampsTIMEZONE for timezones as encoded in section 2.9 of .PORTLIST for port lists as encoded in section 2.10 of .POSTAL for postal addresses as defined in section 2.23 of .NAME for names of natural or legal persons as defined in section 2.3 of .PHONE for telephone numbers as defined in section 2.35 of .EMAIL for email addresses as defined in section 3.4.1. of .URL for URLs as in .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.[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
for Security Considerations for this
document.]Any security considerations 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 an extension.It
should also be noted in this section that the security considerations for
IODEF apply to the extension as well. [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 for IANA Considerations for this document.]Any IANA considerations 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 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 the appendix of the document, or to a well-known external reference in the case of an extension with an externally-defined schema.The XML Schema describing the elements defined in the Extension Defintion section is given here. Each of the examples in section should be verified to validate against this schema by automated tools.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.This example extends the IODEF Address element to support the encoding of ENUM-mapped telephone numbers .Attribute: Address@categoryExtended value(s): enum-e164Value 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.int." for +1 212 555 1212, as per section 3.2 of .Additional considerations: none.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.The Test class has two attributes:Required. ENUM. The type of test data. The permitted values for this attribute are shown below. The default value is "unspecified".
unspecified. The document contains test data, but no further information is available.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.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.interoperability. The test data is intended for interoperability testing of an implementation, and may be freely shared to support this purpose.Optional. STRING. A free-form string identifying the person, entity, or program which generated the test data.