Guidelines for Defining Extensions to IODEF
draft-ietf-mile-template-02
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 6684.
|
|
|---|---|---|---|
| Author | Brian Trammell | ||
| Last updated | 2012-02-17 (Latest revision 2012-02-16) | ||
| Replaces | draft-trammell-mile-template | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Formats | |||
| Reviews | |||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | In WG Last Call | |
| Document shepherd | Kathleen Moriarty | ||
| IESG | IESG state | Became RFC 6684 (Informational) | |
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-ietf-mile-template-02
mile Working Group B. Trammell
Internet-Draft ETH Zurich
Intended status: BCP February 17, 2012
Expires: August 20, 2012
Guidelines for Defining Extensions to IODEF
draft-ietf-mile-template-02.txt
Abstract
This document provides guidelines for extensions to 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. It also
specifies additional Expert Review of XML Schemas used to describe
these extensions.
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 August 20, 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
(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
Trammell Expires August 20, 2012 [Page 1]
Internet-Draft IODEF Extension Guidelines February 2012
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Applicability of Extensions to IODEF . . . . . . . . . . . . . 3
4. Selecting a Mechanism for IODEF Extension . . . . . . . . . . 4
5. Security Considerations . . . . . . . . . . . . . . . . . . . 6
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 6
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6
8.1. Normative References . . . . . . . . . . . . . . . . . . . 6
8.2. Informative References . . . . . . . . . . . . . . . . . . 7
Appendix A. Document Template . . . . . . . . . . . . . . . . . . 7
A.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 7
A.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8
A.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 8
A.4. Extension Definition . . . . . . . . . . . . . . . . . . . 8
A.4.1. IODEF Data Types . . . . . . . . . . . . . . . . . . . 9
A.5. Security Considerations . . . . . . . . . . . . . . . . . 10
A.6. IANA Considerations . . . . . . . . . . . . . . . . . . . 10
A.7. Appendix A: XML Schema Definition for Extension . . . . . 11
A.8. Appendix B: Examples . . . . . . . . . . . . . . . . . . . 11
Appendix B. Example Enumerated Type Extension Definition:
E.164 Address . . . . . . . . . . . . . . . . . . . . 12
Appendix C. Example Element Definition: Test . . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13
Trammell Expires August 20, 2012 [Page 2]
Internet-Draft IODEF Extension Guidelines February 2012
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 of an Internet-Draft about an IODEF
extension.
Additionally, IODEF extensions through AdditionalData and RecordItem
elements, as per section 5.2 of [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 [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 Section 6.
2. Terminology
The key words
strOid The string representation for the oid.
public Oid(InputStream derOid) throws GSSException
Creates an Oid object from its DER encoding. This refers to the full
encoding including tag and length. The structure and encoding of
Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is
identical in functionality to its byte array counterpart.
Parameters:
derOid Stream containing the DER-encoded oid.
public Oid(byte[] DEROid) throws GSSException
Creates an Oid object from its DER encoding. This refers to the full
encoding including tag and length. The structure and encoding of
Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is
identical in functionality to its byte array counterpart.
Parameters:
derOid Byte array storing a DER-encoded oid.
6.7.2. toString
public String toString()
Returns a string representation of the oid's integer components in
dot separated notation (e.g., "1.2.840.113554.1.2.2").
6.7.3. equals
public boolean equals(Object Obj)
Returns "true" if the two Oid objects represent the same oid value.
(Note that the Java language specification [JLS] requires that two
objects that are equal according to the equals(Object) method must
return the same integer result when the hashCode() method is called
on them.)
Parameters:
obj Another Oid object with which to compare.
Upadhyay, et al. Expires February 5, 2018 [Page 75]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
6.7.4. getDER
public byte[] getDER()
Returns the full ASN.1 DER encoding for this oid object, which
includes the tag and length.
6.7.5. containedIn
public boolean containedIn(Oid[] oids)
A utility method to test if an Oid object is contained within the
supplied Oid object array.
Parameters:
oids An array of oids to search.
6.8. public class GSSException extends Exception
This exception is thrown whenever a fatal GSS-API error occurs
including mechanism-specific errors. It may contain both, the major
and minor, GSS-API status codes. The mechanism implementors are
responsible for setting appropriate minor status codes when throwing
this exception. Aside from delivering the numeric error code(s) to
the caller, this class performs the mapping from their numeric values
to textual representations. This exception may also include an
output token that should be sent to the peer. For example, when an
initSecContext call fails due to a fatal error, the mechanism may
define an error token that should be sent to the peer for debugging
or informational purpose. All Java GSS-API methods are declared
throwing this exception.
All implementations are encouraged to use the Java
internationalization techniques to provide local translations of the
message strings.
6.8.1. Static Constants
All valid major GSS-API error code values are declared as constants
in this class.
public static final int BAD_BINDINGS
Channel bindings mismatch error. The value of this constant is 1.
public static final int BAD_MECH
Upadhyay, et al. Expires February 5, 2018 [Page 76]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
Unsupported mechanism requested error. The value of this constant is
2.
public static final int BAD_NAME
Invalid name provided error. The value of this constant is 3.
public static final int BAD_NAMETYPE
Name of unsupported type provided error. The value of this constant
is 4.
public static final int BAD_STATUS
Invalid status code error - this is the default status value. The
value of this constant is 5.
public static final int BAD_MIC
Token had invalid integrity check error. The value of this constant
is 6.
public static final int CONTEXT_EXPIRED
Specified security context expired error. The value of this constant
is 7.
public static final int CREDENTIALS_EXPIRED
Expired credentials detected error. The value of this constant is 8.
public static final int DEFECTIVE_CREDENTIAL
Defective credential error. The value of this constant is 9.
public static final int DEFECTIVE_TOKEN
Defective token error. The value of this constant is 10.
public static final int FAILURE
General failure, unspecified at GSS-API level. The value of this
constant is 11.
public static final int NO_CONTEXT
Invalid security context error. The value of this constant is 12.
Upadhyay, et al. Expires February 5, 2018 [Page 77]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
public static final int NO_CRED
Invalid credentials error. The value of this constant is 13.
public static final int BAD_QOP
Unsupported QOP value error. The value of this constant is 14.
public static final int UNAUTHORIZED
Operation unauthorized error. The value of this constant is 15.
public static final int UNAVAILABLE
Operation unavailable error. The value of this constant is 16.
public static final int DUPLICATE_ELEMENT
Duplicate credential element requested error. The value of this
constant is 17.
public static final int NAME_NOT_MN
Name contains multi-mechanism elements error. The value of this
constant is 18.
public static final int DUPLICATE_TOKEN
The token was a duplicate of an earlier token. This is contained in
an exception only when detected during context establishment, in
which case it is considered a fatal error. (Non-fatal supplementary
codes are indicated via the MessageProp object.) The value of this
constant is 19.
public static final int OLD_TOKEN
The token's validity period has expired. This is contained in an
exception only when detected during context establishment, in which
case it is considered a fatal error. (Non-fatal supplementary codes
are indicated via the MessageProp object.) The value of this
constant is 20.
public static final int UNSEQ_TOKEN
A later token has already been processed. This is contained in an
exception only when detected during context establishment, in which
case it is considered a fatal error. (Non-fatal supplementary codes
Upadhyay, et al. Expires February 5, 2018 [Page 78]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
are indicated via the MessageProp object.) The value of this
constant is 21.
public static final int GAP_TOKEN
An expected per-message token was not received. This is contained in
an exception only when detected during context establishment, in
which case it is considered a fatal error. (Non-fatal supplementary
codes are indicated via the MessageProp object.) The value of this
constant is 22.
6.8.2. Constructors
public GSSException(int majorCode)
Creates a GSSException object with a specified major code.
Calling this constructor is equivalent to calling
GSSException(majorCode, null, 0, null, null).
public GSSException(int majorCode, int minorCode, String minorString)
Creates a GSSException object with the specified major code, minor
code, and minor code textual explanation. This constructor is to be
used when the exception is originating from the security mechanism.
It allows to specify the GSS code and the mechanism code.
Calling this constructor is equivalent to calling
GSSException(majorCode, null, minorCode, minorString, null).
public GSSException(int majorCode, String majorString,
int minorCode, String minorString,
byte[] outputToken)
Creates a GSSException object with the specified major code, major
code textual explanation, minor code, minor code textual explanation,
and an output token. This is a general-purpose constructor that can
be used to create any type of GSSException.
Parameters:
majorCode The GSS error code causing this exception to be
thrown.
majorString The textual explanation of the GSS error code.
If null is provided, a default explanation that
matches the majorCode will be set.
Upadhyay, et al. Expires February 5, 2018 [Page 79]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
minorCode The mechanism error code causing this exception
to be thrown. Can be 0 if no mechanism error
code is available.
minorString The textual explanation of the mechanism error
code. Can be null if no textual explanation is
available.
outputToken The output token that should be sent to the peer.
Can be null if no such token is available. It
must not be an empty array. When provided, the
array will be cloned to protect against
subsequent modifications.
6.8.3. getMajor
public int getMajor()
Returns the major code representing the GSS error code that caused
this exception to be thrown.
6.8.4. getMinor
public int getMinor()
Returns the mechanism error code that caused this exception. The
minor code is set by the underlying mechanism. Value of 0 indicates
that mechanism error code is not set.
6.8.5. getMajorString
public String getMajorString()
Returns a string explaining the GSS major error code causing this
exception to be thrown.
6.8.6. getMinorString
public String getMinorString()
Returns a string explaining the mechanism-specific error code. "null"
will be returned when no string explaining the mechanism error code
has been set.
Upadhyay, et al. Expires February 5, 2018 [Page 80]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
6.8.7. getOutputToken
public byte[] getOutputToken
Returns the output token in a new byte array.
If the method (For example, GSSContext#initSecContext) that throws
this GSSException needs to generate an output token that should be
sent to the peer, that token will be stored in this GSSException and
can be retrieved with this method.
The return value must be null if no such token is generated. It must
not be an empty byte array.
6.8.8. setMinor
public void setMinor(int minorCode, String message)
Used internally by the GSS-API implementation and the underlying
mechanisms to set the minor code and its textual representation.
Parameters:
minorCode The mechanism-specific error code.
message A textual explanation of the mechanism error
code.
6.8.9. toString
public String toString()
Returns a textual representation of both the major and minor status
codes.
6.8.10. getMessage
public String getMessage()
Returns a detailed message of this exception. Overrides
Throwable.getMessage. It is customary in Java to use this method to
obtain exception information.
7. Sample Applications
Upadhyay, et al. Expires February 5, 2018 [Page 81]
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
3. 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 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.
Trammell Expires August 20, 2012 [Page 3]
Internet-Draft IODEF Extension Guidelines February 2012
2. 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:
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 additional semantic or metadata labeling of IODEF
Documents (e.g., for handling or disposition instructions, or
compliance with data protection and data retention regulations)
4. 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. 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 in this way are defined in Section
Trammell Expires August 20, 2012 [Page 4]
Internet-Draft IODEF Extension Guidelines February 2012
5.1 of [RFC5070], and limited to the following:
o Incident@purpose
o Contact@role
o Contact@type
o RegistryHandle@registry
o Impact@type
o TimeImpact@metric
o TimeImpact@duration
o HistoryItem@action
o Expectation@action
o System@category
o Counter@type
o Counter@duration
o Address@category
o NodeRole@category
o RecordPattern@type
o RecordPattern@offsetunit
o AdditionalData@dtype
o RecordItem@dtype
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, and SHOULD define the use the "meaning"
and "formatid" attributes to explain the content of the element.
Trammell Expires August 20, 2012 [Page 5]
Internet-Draft IODEF Extension Guidelines February 2012
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 Appendix C.
5. Security Considerations
This document defines a template for extensions to IODEF; the
security considerations for IODEF [RFC5070] apply.
6. IANA Considerations
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 [RFC5226]. 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 [RFC5226]," and naming the designated expert.]
7. Acknowledgments
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).
8. References
8.1. Normative References
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
[RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident
Object Description Exchange Format", RFC 5070,
December 2007.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
Trammell Expires August 20, 2012 [Page 6]
Internet-Draft IODEF Extension Guidelines February 2012
[I-D.ietf-mile-rfc6045-bis]
Moriarty, K., "Real-time Inter-network Defense (RID)",
draft-ietf-mile-rfc6045-bis-11 (work in progress),
January 2012.
8.2. Informative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing
Architecture", RFC 4291, February 2006.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[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, "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.
[RFC6116] Bradner, S., Conroy, L., and K. Fujiwara, "The E.164 to
Uniform Resource Identifiers (URI) Dynamic Delegation
Discovery System (DDDS) Application (ENUM)", RFC 6116,
March 2011.
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.
A.1. Introduction
The introduction section introduces the problem being solved by the
extension, and motivates the development and deployment of the
extension.
Trammell Expires August 20, 2012 [Page 7]
Internet-Draft IODEF Extension Guidelines February 2012
A.2. Terminology
The terminology section introduces and defines terms specific to the
document. Terminology from [RFC5070] or [I-D.ietf-mile-rfc6045-bis]
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 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.
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 the 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 MILE
extension document.
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
7.1. Simple GSS Context Initiator
<CODE BEGINS>
import org.ietf.jgss.*;
/**
* This is a partial sketch for a simple client program that acts
* as a GSS context initiator. It illustrates how to use the Java
* bindings for the GSS-API specified in
* Generic Security Service API Version 2 : Java bindings
*
*
* This code sketch assumes the existence of a GSS-API
* implementation that supports the mechanism that it will need
* and is present as a library package (org.ietf.jgss) either as
* part of the standard JRE or in the CLASSPATH the application
* specifies.
*/
public class SimpleClient {
private String serviceName; // name of peer (i.e., server)
private GSSCredential clientCred = null;
private GSSContext context = null;
private Oid mech; // underlying mechanism to use
private GSSManager mgr = GSSManager.getInstance();
...
...
private void clientActions() {
initializeGSS();
establishContext();
doCommunication();
}
/**
* Acquire credentials for the client.
*/
private void initializeGSS() {
try {
clientCred = mgr.createCredential(null /*default princ*/,
GSSCredential.INDEFINITE_LIFETIME /* max lifetime */,
mech /* mechanism to use */,
GSSCredential.INITIATE_ONLY /* init context */);
Upadhyay, et al. Expires February 5, 2018 [Page 82]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
print("GSSCredential created for " +
cred.getName().toString());
print("Credential lifetime (sec)=" +
cred.getRemainingLifetime());
} catch (GSSException e) {
print("GSS-API error in credential acquisition: "
+ e.getMessage());
...
...
}
...
...
}
/**
* Does the security context establishment with the
* server.
*/
private void establishContext() {
byte[] inToken = new byte[0];
byte[] outToken = null;
try {
GSSName peer = mgr.createName(serviceName,
GSSName.NT_HOSTBASED_SERVICE);
context = mgr.createContext(peer, mech, gssCred,
GSSContext.INDEFINITE_LIFETIME/*lifetime*/);
// Will need to support confidentiality
context.requestConf(true);
while (!context.isEstablished()) {
outToken = context.initSecContext(inToken, 0,
inToken.length);
if (outToken != null)
writeGSSToken(outToken);
if (!context.isEstablished())
inToken = readGSSToken();
}
GSSName peer = context.getSrcName();
print("Security context established with " + peer +
" using underlying mechanism " + mech.toString());
Upadhyay, et al. Expires February 5, 2018 [Page 83]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
} catch (GSSException e) {
print("GSS-API error during context establishment: "
+ e.getMessage());
// If the exception contains an output token,
// it should be sent to the acceptor.
byte[] outTok = e.getOutputToken();
if (outTok != null) {
writeGSSToken(outTok);
}
...
...
}
...
...
}
/**
* Sends some data to the server and reads back the
* response.
*/
private void doCommunication() {
byte[] inToken = null;
byte[] outToken = null;
byte[] buffer;
// Container for multiple input-output arguments to and
// from the per-message routines (e.g., wrap/unwrap).
MessageProp messgInfo = new MessageProp();
try {
/*
* Now send some bytes to the server to be
* processed. They will be integrity protected
* but not encrypted for privacy.
*/
buffer = readFromFile();
// Set privacy to "false" and use the default QOP
messgInfo.setPrivacy(false);
outToken = context.wrap(buffer, 0, buffer.length,
messgInfo);
writeGSSToken(outToken);
Upadhyay, et al. Expires February 5, 2018 [Page 84]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
/*
* Now read the response from the server.
*/
inToken = readGSSToken();
buffer = context.unwrap(inToken, 0,
inToken.length, messgInfo);
// All ok if no exception was thrown!
GSSName peer = context.getSrcName();
print("Message from " + peer.toString()
+ " arrived.");
print("Was it encrypted? " +
messgInfo.getPrivacy());
print("Duplicate Token? " +
messgInfo.isDuplicateToken());
print("Old Token? " +
messgInfo.isOldToken());
print("Unsequenced Token? " +
messgInfo.isUnseqToken());
print("Gap Token? " +
messgInfo.isGapToken());
...
...
} catch (GSSException e) {
print("GSS-API error in per-message calls: "
+ e.getMessage());
...
...
}
...
...
} // end of doCommunication method
...
...
} // end of class SimpleClient
<CODE ENDS>
7.2. Simple GSS Context Acceptor
<CODE BEGINS>
import org.ietf.jgss.*;
/**
* This is a partial sketch for a simple server program that acts
Upadhyay, et al. Expires February 5, 2018 [Page 85]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
* as a GSS context acceptor. It illustrates how to use the Java
* bindings for the GSS-API specified in
* Generic Security Service API Version 2 : Java bindings.
*
* This code sketch assumes the existence of a GSS-API
* implementation that supports the mechanisms that it will need
* and is present as a library package (org.ietf.jgss) either as
* part of the standard JRE or in the CLASSPATH the application
* specifies.
*/
import org.ietf.jgss.*;
public class SimpleServer {
private String serviceName;
private GSSName name;
private GSSCredential cred;
private GSSManager mgr;
...
...
/**
* Wait for client connections, establish security contexts
* and provide service.
*/
private void loop() {
...
...
mgr = GSSManager.getInstance();
name = mgr.createName(serviceName,
GSSName.NT_HOSTBASED_SERVICE);
cred = mgr.createCredential(name,
GSSCredential.INDEFINITE_LIFETIME,
null,
GSSCredential.ACCEPT_ONLY);
// Loop infinitely
while (true) {
Socket s = serverSock.accept();
// Start a new thread to serve this connection
Thread serverThread = new ServerThread(s);
serverThread.start();
Upadhyay, et al. Expires February 5, 2018 [Page 86]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
}
}
/**
* Inner class ServerThread whose run() method provides the
* secure service to a connection.
*/
private class ServerThread extends Thread {
...
...
/**
* Deals with the connection from one client. It also
* handles all GSSException's thrown while talking to
* this client.
*/
public void run() {
byte[] inToken = null;
byte[] outToken = null;
byte[] buffer;
GSSName peer;
// Container for multiple input-output arguments to
// and from the per-message routines
// (i.e., wrap/unwrap).
MessageProp supplInfo = new MessageProp();
GSSContext secContext = null;
try {
// Now do the context establishment loop
GSSContext context = mgr.createContext(cred);
while (!context.isEstablished()) {
inToken = readGSSToken();
outToken = context.acceptSecContext(inToken,
0, inToken.length);
if (outToken != null)
writeGSSToken(outToken);
}
// SimpleServer wants confidentiality to be
// available. Check for it.
if (!context.getConfState()){
Upadhyay, et al. Expires February 5, 2018 [Page 87]
Internet-Draft draft-ietf-kitten-rfc5653bis-05 August 2017
...
...
}
GSSName peer = context.getSrcName();
Oid mech = context.getMech();
print("Security context established with " +
peer.toString() +
" using underlying mechanism " +
mech.toString() +
" from Provider " +
context.getProvider().getName());
// Now read the bytes sent by the client to be
// processed.
inToken = readGSSToken();
// Unwrap the message
buffer = context.unwrap(inToken, 0,
inToken.length, supplInfo);
// All ok if no exception was thrown!
// Print other supplementary per-message status
// information.
print("Message from " +
peer.toString() + " arrived.");
print("Was it encrypted? " +
supplInfo.getPrivacy());
print("Duplicate Token? " +
supplInfo.isDuplicateToken());
print(&Trammell Expires August 20, 2012 [Page 8]
Internet-Draft IODEF Extension Guidelines February 2012
+---------------------+
| 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 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 August 20, 2012 [Page 9]
Internet-Draft IODEF Extension Guidelines February 2012
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
[RFC5322].
o URL for URLs 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
[RFC4291] 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.
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 5 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 an extension.
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 6 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 which represent an enumeration should reference an
Trammell Expires August 20, 2012 [Page 10]
Internet-Draft IODEF Extension Guidelines February 2012
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.
A.7. 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.8 should be verified to validate against this schema by
automated tools.
A.8. 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 should be
tested to validate against the schema given in the appendix.
Trammell Expires August 20, 2012 [Page 11]
Internet-Draft IODEF Extension Guidelines February 2012
Appendix B. Example Enumerated Type Extension Definition: E.164 Address
This example extends the IODEF Address element to support the
encoding of ENUM-mapped telephone numbers [RFC6116].
Attribute: Address@category
Extended value(s): enum-e164
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.int." for +1 212 555 1212, as per section
3.2 of [RFC6116].
Additional considerations: none.
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 reference
to a real incident.
The Test class contains information about how the test data was
generated.
+---------------------+
| 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
"unspecified".
1. unspecified. The document contains test data, but no further
information is available.
Trammell Expires August 20, 2012 [Page 12]
Internet-Draft IODEF Extension Guidelines February 2012
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
Switzerland
Phone: +41 44 632 70 13
Email: trammell@tik.ee.ethz.ch
Trammell Expires August 20, 2012 [Page 13]