| New Draft, updated with Mark's Edits | <– Date –> <– Thread –> |
From: David Frascone (dave frascone.com)
|
|
| Date: 6 Feb 2002 16:15:57 -0000 | |
Text attached. Nroff available via cvs. PS or PDF available upon request.
AAA Working Group David Frascone
Internet-Draft Sun Microsystems, Inc.
Category: Informational Mark Jones
Bridgewater Systems
Erik Guttman
Sun Microsystems, Inc.
January 2002
Diameter XML Dictionary
<draft-ietf-aaa-xml-dictionary-00.txt>
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
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."
The list of current Internet-Drafts can be accessed at:
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at:
http://www.ietf.org/shadow.html.
Copyright Notice
Copyright (C) The Internet Society 2002. All Rights Reserved.
Abstract
This document describes a coding Diameter dictionaries in XML. This
coding is intended for use by Diameter implementations to represent
Applications, Comands, Vendors, and AVPs.
Frascone et al. expires June 2002 [Page 1]
Internet-Draft January 2002
Discussion of this document
Send comments to the AAA Working Group mailing list <aaa-
wg [at] merit.edu>. To subscribe to the list, send a message with the
body 'subscribe aaa-wg' to <majordomo [at] merit.edu>
Table of Contents
1.0 Introduction
2.0 Specifications and Requirements
3.0 Dictionary Layout
3.1 Vendors Element
3.1.1 "id" Attribute
3.1.2 "name" Attribute
3.2 Type Definition Element
3.2.1 "type-name" Attribute
3.2.2 "type-parent" Attribute
3.2.3 "description" Attribute
3.3 Enumerated Types Element
3.3.1 "name" Attribute
3.3.3 "code" Attribute
3.4 Attribute Value Pairs
3.4.1 "name" Attribute
3.4.2 "description" Attribute
3.4.3 "code" Attribute
3.4.4 "may-encrypt" Attribute
3.4.5 "mandatory" Attribute
3.4.6 "protected" Attribute
3.4.7 "vendor-id" Attribute
3.5 Grouped AVPs
3.5.1 "name" Attribute
3.5.2 "vendor-id" Attribute
3.6 AVP Rules
3.6.1 "name" Attribute
3.6.2 "position" Attribute
3.6.3 "maximum" Attribute
3.6.4 "minimum" Attribute
3.7 Commands
3.7.1 "name" Attribute
3.7.2 "code" Attribute
3.7.3 "vendor-id" Attribute
3.8 Applications and Base Protocol
3.8.1 "id" Attribute
3.8.2 "name" Attribute
3.8.3 "uri" Attribute
4.0 References
5.0 Acknowledgments
6.0 Authors' Addresses
Frascone et al. expires June 2002 [Page 2]
Internet-Draft January 2002
Appendix A. Document Type Definition
Appendix B. DTD & Dictionary Links
Frascone et al. expires June 2002 [Page 3]
Internet-Draft January 2002
1.0 Introduction
Diameter [1] is an extensible protocol used to provide AAA services
to different access technologies. To maintain extensibility, Diame-
ter uses a dictionary to provide it with the format of commands and
AVPs.
This document describes the representation of the Diameter dictionary
using XML [2].
2.0 Specifications and Requirements
In this document, the key words "MAY", "MUST, "MUST NOT", "optional",
"recommended", "SHOULD", and "SHOULD NOT", are to be interpreted as
described in [3].
3.0 Dictionary Layout
The dictionary is composed of several XML files, liked together with
external entity tags. In the top level file (which SHOULD be called
"dictionary.xml"), Vendors, types, and the base protocol are defined.
Other applications SHOULD be defined in other external entity files.
Syntax:
<!ELEMENT dictionary (
vendor*,
base,
application*)>
+------------+----------------+
| Element | Classification |
+------------+----------------+
|vendor | Zero or More |
+------------+----------------+
|base | Required |
+------------+----------------+
|application | Zero or More |
+------------+----------------+
3.1 Vendors Element
The Vendor element defines a vendor by a name and associated IANA
assigned "SMI Network Management Private Enterprise Codes" [4].
Syntax:
Frascone et al. expires June 2002 [Page 4]
Internet-Draft January 2002
<!ELEMENT vendor EMPTY>
<!ATTLIST vendor
id CDATA #REQUIRED,
name CDATA #REQUIRED>
+----------+----------+-------------+---------+
|Attribute | Presence | Constraints | Values |
+----------+----------+-------------+---------+
| id | Required | UniqueKey | Integer |
+----------+----------+-------------+---------+
| name | Required | None | String |
+----------+----------+-------------+---------+
3.1.1 "id" Attribute
The "id" attribute is the vendor code assigned by IANA [4]. The "id"
MUST be unique across all Vendor element definitions although this
constraint can not be enforced by the DTD.
3.1.2 "name" Attribute
The "name" attribute is some text describing the vendor. Although
the Diameter protocol only requires the vendor code for encoding and
decoding messages, the vendor name MAY be used in trace utilities to
facilitate debugging.
3.2 Type Definition Element
The Type Definition element defines a valid Diameter data type.
Every attribute value pair definition MUST refer to a type defini-
tion. The most common use of this container is to indicate which base
type a derived type derives from. This helps the server to know how
(and if) an AVP should be displayed.
Syntax:
<!ELEMENT typedefn EMPTY>
<!ATTLIST typedefn
type-name ID #REQUIRED,
type-parent IDREF #IMPLIED,
description CDATA #IMPLIED>
Frascone et al. expires June 2002 [Page 5]
Internet-Draft January 2002
+------------+----------+-------------+--------+
| Attribute | Presence | Constraints | Values |
+------------+----------+-------------+--------+
| type-name | Required | UniqueKey | String |
+------------+----------+-------------+--------+
|type-parent | Optional | Reference | String |
+------------+----------+-------------+--------+
|description | Optional | None | String |
+------------+----------+-------------+--------+
3.2.1 "type-name" Attribute
The attribute, "type-name" contains an ascii representation of the
type. This attribute is of type ID allowing the DTD to enforce its
uniqueness across all typedefn elements. This also permits other
attributes of type IDREF to refer to the type-name value and have the
DTD enforce the referential integrity.
3.2.2 "type-parent" Attribute
The "type-parent" attribute is required for all derived types. This
attribute is of type IDREF ensuring that its value MUST correspond to
the value of a type-name attribute of a pre-defined typedefn element.
3.2.3 "description" Attribute
The "description" attribute is an optional attribute describing the
type. Typically a human readable description of what the type is
used for would be included here.
3.3 Enumerated Types Element
Enumerated elements define values for an Enumerated AVP. You will
have one or more Enumerated elements for any AVP requiring defined
values.
For example, if a particular AVP had two values, Yes and No corre-
sponding to 1 and 0, then the entry would looklike this:
<enum name="Yes" code="1">
<enum name="No" code="0">
Enumerated elements should only be used with Unsigned32 typed AVPs.
Syntax:
<!ELEMENT enum EMPTY>
Frascone et al. expires June 2002 [Page 6]
Internet-Draft January 2002
<!ATTLIST enum
name CDATA #REQUIRED,
code CDATA #REQUIRED>
+----------+----------+-------------+---------+
|Attribute | Presence | Constraints | Values |
+----------+----------+-------------+---------+
| name | Required | None | String |
+----------+----------+-------------+---------+
| code | Required | None | Integer |
+----------+----------+-------------+---------+
3.3.1 "name" Attribute
The "name" attribute is the text corresponding to a particular value
for the attribute.
3.3.3 "code" Attribute
The "code" attribute is the Unsigned32 value corresponding to this
enumerated value.
3.4 Attribute Value Pairs
AVPs are the most frequent element used in Dictionaries. It contains
a Type element, or a grouped element, and, possibly, some enumera-
tions. The AVP element completely defines one Attribute Value Pair,
including flags and format.
An AVP should only contain enumerations if the type is Unsigned32.
Syntax:
<!ELEMENT avp (
(type | grouped),
(enum *)>
<!ATTLIST avp
name ID #REQUIRED
description CDATA #IMPLIED
code CDATA #REQUIRED
may-encrypt (yes | no) "yes"
mandatory (must | may | mustnot | shouldnot) "may"
protected (must | may | mustnot | shouldnot) "may"
vendor-id CDATA #IMPLIED>
Frascone et al. expires June 2002 [Page 7]
Internet-Draft January 2002
+------------+----------+-------------+--------------------+
| Attribute | Presence | Constraints | Values |
+------------+----------+-------------+--------------------+
| xname | Required | UniqueKey | String |
+------------+----------+-------------+--------------------+
|description | Optional | None | String |
+------------+----------+-------------+--------------------+
| code | Required | UniqueKey | Integer |
+------------+----------+-------------+--------------------+
|may-encrypt | Optional | None | yes or no |
| | | | (default is yes) |
+------------+----------+-------------+--------------------+
| | | | must, may, |
| mandatory | Optional | None | mustnot, shouldnot |
| | | | (default is may) |
+------------+----------+-------------+--------------------+
| | | | must, may, |
| protected | Optional | None | mustnot, shouldnot |
| | | | (default is may) |
+------------+----------+-------------+--------------------+
| vendor-id | Optional | Reference | Integer |
+------------+----------+-------------+--------------------+
3.4.1 "name" Attribute
The "name" attribute is the mnemonic describing this attribute, for
example, "User-Name"
3.4.2 "description" Attribute
The "description" attribute is an optional attribute used to describe
the use of the AVP.
3.4.3 "code" Attribute
The "code" attribute defines the integer value used to transmit the
AVP on the network.
3.4.4 "may-encrypt" Attribute
If the "may-encrypt" attribute is "yes", then this AVP will be sent
encrypted if the connection uses CMS security.
3.4.5 "mandatory" Attribute
The "mandatory" attribute defines whether the mandatory bit of this
AVP should or should not be set.
Frascone et al. expires June 2002 [Page 8]
Internet-Draft January 2002
3.4.6 "protected" Attribute
The "protected" attribute defines whether the protected bit of this
AVP should or should not be set.
3.4.7 "vendor-id" Attribute
The "vendor-id" attribute should be set to the "id" attribute of a
"vendor" element, if this is a vendor specific AVP.
3.5 Grouped AVPs
Grouped AVPs are used to send multiple data objects together as a
single payload. The "grouped" element defines such an object.
A "grouped" element consists of one or more "gavp" elements. Each
"gavp" element holds an avp "name" and "vendor-id". This way, a sin-
gle "grouped" element can contain references to multiple AVPs.
Syntax:
<!ELEMENT grouped (
gavp+)>
<!ELEMENT gavp EMPTY>
<!ATTLIST gavp
name IDREF #REQUIRED
vendor-id CDATA #IMPLIED>
+----------+----------+-------------+---------+
|Attribute | Presence | Constraints | Values |
+----------+----------+-------------+---------+
| name | Required | UniqueKey | String |
+----------+----------+-------------+---------+
|vendor-id | Optional | Reference | Integer |
+----------+----------+-------------+---------+
3.5.1 "name" Attribute
The "name" attribute MUST correspond to some existing AVP's "name"
attribute.
3.5.2 "vendor-id" Attribute
If this "gavp" element reffers to a vendor specific AVP, then the
Frascone et al. expires June 2002 [Page 9]
Internet-Draft January 2002
"vendor-id" attribute MUST correspond to a Vendor's "id" attribute.
3.6 AVP Rules
AVP rules elements define the placement of key AVPs withing commands.
They are used to do some symmantic checking at the protocol layer.
For example, a particular AVP might be required to be first in a par-
ticular message. This element can define those rules.
Since a command might have different rules for requests and
responses, both requestrules and answerrules may be defined. Both
elements must have at least one rule if they are defined.
Syntax:
<!ELEMENT requestrules (
avprule+)>
<!ELEMENT answerrules (
avprule+)>
<!ELEMENT avprule EMPTY>
<!ATTLIST avprule
name IDREF #REQUIRED
position (first | last | unspecified) "unspecified"
maximum CDATA "none"
minimum CDATA "0">
+----------+----------+-------------+-------------------+
|Attribute | Presence | Constraints | Values |
+----------+----------+-------------+-------------------+
| name | Required | Reference | String |
+----------+----------+-------------+-------------------+
| | | | first, last, |
|position | Required | None | or unspecified |
| | | | (default is |
| | | | unspecified) |
+----------+----------+-------------+-------------------+
| maximum | Required | None | Integer or "none" |
+----------+----------+-------------+-------------------+
| minimum | Required | None | Integer |
+----------+----------+-------------+-------------------+
3.6.1 "name" Attribute
This rule applies to the AVP named "name".
Frascone et al. expires June 2002 [Page 10]
Internet-Draft January 2002
3.6.2 "position" Attribute
The named AVP must be either "first" in the command, "last" in the
command, or its position does not matter ("unspecified").
3.6.3 "maximum" Attribute
The "maximum" attribute defines the maximum number of times this AVP
can occur in the command. 0 means the AVP MUST not occur in the com-
mand. "none" means that there is no limit to the number of times this
AVP may be present.
3.6.4 "minimum" Attribute
The "minimum" attribute defines the maximum number of times this AVP
can occur in the command. 0 means the AVP is optional.
3.7 Commands
A command element defines the attributes for a command, and contains
any rules to be applied to it. (Note: See Section 3.6 AVP Rules)
Syntax:
<!ELEMENT command (
requestrules*,
answerrules*)>
<!ATTLIST command
name CDATA #REQUIRED
code CDATA #REQUIRED
vendor-id CDATA #IMPLIED>
+----------+----------+-------------+---------+
|Attribute | Presence | Constraints | Values |
+----------+----------+-------------+---------+
| name | Required | None | String |
+----------+----------+-------------+---------+
| code | Required | None | Integer |
+----------+----------+-------------+---------+
|vendor-id | Optional | Reference | Integer |
+----------+----------+-------------+---------+
3.7.1 "name" Attribute
The "name" attribute defines the name of the command. Only one
Frascone et al. expires June 2002 [Page 11]
Internet-Draft January 2002
command is defined for both "Request" and "Answer" portions. So, the
"Capabilities-Exchange" command defines the messages, "Capabilities-
Exchange-Request", and "Capabilities-Exchange-Answer".
3.7.2 "code" Attribute
The "code" attribute defines the command code used to transmit this
command.
3.7.3 "vendor-id" Attribute
If this is a vendor specific command, then the "vendor-id" attribute
MUST correspond to a vendor element's "id" field.
3.8 Applications and Base Protocol
The base commands, and application specific commands have identical
syntax, with the exception that the base protocol requires at least
one type, avp, and command be defined. So, they are being described
together.
Applications must define any Commands, Types, or AVPs that they cre-
ate. The application (or base) element holds those definitions.
Syntax:
<!ELEMENT base (
command+,
typedefn+,
avp+)>
<!ATTLIST base
uri CDATA #IMPLIED>
<!ELEMENT application (
command*,
typedefn*,
avp*)>
<!ATTLIST application
id CDATA #REQUIRED
name CDATA #IMPLIED
uri CDATA #IMPLIED>
Frascone et al. expires June 2002 [Page 12]
Internet-Draft January 2002
+----------+--------------------+-------------+--------+
|Attribute | Presence | Constraints | Values |
+----------+--------------------+-------------+--------+
| uri | Optional | None | String |
+----------+--------------------+-------------+--------+
| name | Optional | None | String |
| | (application only) | | |
+----------+--------------------+-------------+--------+
| id | Required | None | String |
| | (application only) | | |
+----------+--------------------+-------------+--------+
3.8.1 "id" Attribute
The "id" attribute is the IANA assigned Application Identifier for
this application.
3.8.2 "name" Attribute
The "name" attribute is the human readable name of this application.
3.8.3 "uri" Attribute
The "uri" attribute is an optional reference used to provide useful
information about this application. For example, the base protocol
has a URI that points to the most recent Diameter Base Protocol
draft.
4.0 References
[1] Calhoun, P., et. al., "The DIAMETER Base Protocol," draft-
ietf- aaa-diameter-08.txt, a work in progress.
[2] "Extensible Markup Language (XML) 1.0" W3C Recommendation
10-February-1998 http://www.w3.org/TR/1998/REC-xml-19980210
[3] Bradner, S., "Key words for use in RFCs to Indicate Require-
ment Levels", BCP 14, RFC 2119, March 1997.
[4] Reynolds, J. and J. Postel, "ASSIGNED NUMBERS", STD 2, RFC
1700, October 1994.
5.0 Acknowledgments
I'd like to thank yatta yatta yatta
Frascone et al. expires June 2002 [Page 13]
Internet-Draft January 2002
6.0 Authors' Addresses
Questions about this memo can be directed to:
David Frascone
Sun Microsystems, Inc.
Sun Labs
605 N. Frances Street
Terrell, Texas 75160
USA
Phone: +1 972-386-1283
Fax: +1 978-334-0249
E-mail: codemonkey [at] sun.com
Mark Jones
Bridgewater Systems
303 Terry Fox Drive, Suite 100,
Kanata, Ontario. K2K 3J1
Canada
Phone: +1 613-591-6655
Fax: +1 613-591-6656
E-mail: mjones [at] bridgewatersystems.com
Erik Guttman
Sun Microsystems, Inc.
Eichhoelzelstr. 7
74914 Waibstadt Germany
Phone: +49 6227 356 202
Fax: +49 7263 911 701
E-mail: Erik.Guttman [at] sun.com
Frascone et al. expires June 2002 [Page 14]
Internet-Draft January 2002
Appendix A. Document Type Definition
Frascone et al. expires June 2002 [Page 15]
Internet-Draft January 2002
<?xml version="1.0" encoding="UTF-8"?>
<!--
$Log: dictionary.dtd,v $
Revision 1.7 2002/02/06 15:39:22 dave
Vendor name changed from #IMPLIED to #REQUIRED
Revision 1.6 2001/12/13 23:07:26 dave
Updated DTD and dictionary files with new changes. Please review
and send me e-mail with any comments.
Revision 1.5 2001/09/27 16:50:44 dave
Testing CVS to mailing list. Nothing changed in file.
Revision 1.4 2001/09/27 16:44:19 dave
Test for cvs
Revision 1.3 2001/09/19 21:38:57 mjones
Removed #PCDATA from command element.
Revision 1.2 2001/09/19 19:46:38 mjones
Moved the vendor element to be the same level as base and application.
Modified vendor-id to be SMI Private Enterprise Code instead of a label.
Removed vendor-id="None" since vendor-id was IMPLIED.
Added type attribute to command (request or answer).
Removed duplicate AVPs from nasreq.xml (Acct-Session-Id,
Acct-Multi-Session-Id)
Corrected typos in enum codes for Auth-Session-State and
Disconnect-Cause.
Revision 1.1 2001/08/24 18:04:44 chaos
Added per Mark's request
Revision 1.3 2001/07/31 17:43:36 chaos
Oops, forgot to turn on validity checking. Fixed some errors found
with validity checking turned on
Revision 1.2 2001/07/31 16:56:15 chaos
Lots of changes to support flags like in the draft, and to support
commands
-->
<!ELEMENT dictionary (vendor*, base, application*)>
<!ELEMENT vendor EMPTY>
<!ATTLIST vendor
id CDATA #REQUIRED
name CDATA #REQUIRED
>
<!ELEMENT base (command*, typedefn+, avp+)>
<!ATTLIST base
uri CDATA #IMPLIED
Frascone et al. expires June 2002 [Page 16]
Internet-Draft January 2002
>
<!ELEMENT application (command*, typedefn*, avp*)>
<!ATTLIST application
id CDATA #REQUIRED
name CDATA #IMPLIED
uri CDATA #IMPLIED
>
<!ELEMENT command (requestrules*, answerrules*)>
<!ATTLIST command
name CDATA #REQUIRED
code CDATA #REQUIRED
vendor-id CDATA #IMPLIED
>
<!ELEMENT typedefn EMPTY>
<!ATTLIST typedefn
type-name ID #REQUIRED
type-parent IDREF #IMPLIED
description CDATA #IMPLIED
>
<!ELEMENT avp ((type | grouped), (enum*))>
<!ATTLIST avp
name ID #REQUIRED
description CDATA #IMPLIED
code CDATA #REQUIRED
may-encrypt (yes | no) "yes"
mandatory (must | may | mustnot | shouldnot) "may"
protected (must | may | mustnot | shouldnot) "may"
vendor-id CDATA #IMPLIED
>
<!ELEMENT type EMPTY>
<!ATTLIST type
type-name IDREF #REQUIRED
>
<!ELEMENT grouped (gavp+)>
<!ELEMENT gavp EMPTY>
<!ATTLIST gavp
name IDREF #REQUIRED
vendor-id CDATA #IMPLIED
>
<!ELEMENT enum EMPTY>
<!ATTLIST enum
name CDATA #REQUIRED
code CDATA #REQUIRED
>
<!ELEMENT requestrules (avprule+)>
Frascone et al. expires June 2002 [Page 17]
Internet-Draft January 2002
<!ELEMENT answerrules (avprule+)>
<!ELEMENT avprule EMPTY>
<!ATTLIST avprule
name IDREF #REQUIRED
position (first | last | unspecified) "unspecified"
maximum CDATA "none"
minimum CDATA "0"
>
Frascone et al. expires June 2002 [Page 18]
Internet-Draft January 2002
Appendix B. DTD & Dictionary Links
DTD:
http://www.diameter.org/diameter/dictionary.dtd
dictionary:
http://www.diameter.org/diameter/dictionary.xml
http://www.diameter.org/diameter/nasreq.xml
http://www.diameter.org/diameter/mobileipv4.xml
http://www.diameter.org/diameter/sunping.xml
Mirror:
DTD:
http://diameter.frascone.com/diameter/dictionary.dtd
dictionary:
http://diameter.frascone.com/diameter/dictionary.xml
http://diameter.frascone.com/diameter/nasreq.xml
http://diameter.frascone.com/diameter/mobileipv4.xml
http://diameter.frascone.com/diameter/sunping.xml
Frascone et al. expires June 2002 [Page 19]
- (no other messages in thread)
Results generated by Tiger Technologies using MHonArc.