AAA Working Group David Frascone Internet-Draft Sun Microsystems, Inc. Category: Informational Mark Jones Bridgewater Systems Erik Guttman Sun Microsystems, Inc. February 2002 Diameter XML Dictionary Status of this Memo This document is an Internet-Draft and is subject to 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/1id-abstracts.html 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 of Diameter dictionaries in XML. This coding is intended for use by Diameter implementations to represent Applications, Commands, Vendors, and AVPs. Frascone et al. expires June 2002 [Page 1] Internet-Draft February 2002 Discussion of this document Send comments to the AAA Working Group mailing list . To subscribe to the list, send a message with the body 'subscribe aaa-wg' to Table of Contents 1.0 Introduction 2.0 Specifications and Requirements 3.0 Dictionary Layout 3.1 Vendor Element 3.1.1 "id" Attribute 3.1.2 "name" Attribute 3.2 Base Element 3.3 Application Element 3.4 Base Protocol and Application Elements 3.4.1 "id" Attribute 3.4.2 "name" Attribute 3.4.3 "uri" Attribute 3.5 Command Element 3.5.1 "name" Attribute 3.5.2 "code" Attribute 3.5.3 "vendor-id" Attribute 3.6 AVP Rule Element 3.6.1 "name" Attribute 3.6.2 "position" Attribute 3.6.3 "maximum" Attribute 3.6.4 "minimum" Attribute 3.7 Type Definition Element 3.7.1 "type-name" Attribute 3.7.2 "type-parent" Attribute 3.7.3 "description" Attribute 3.8 Attribute Value Pair Element 3.8.1 "name" Attribute 3.8.2 "description" Attribute 3.8.3 "code" Attribute 3.8.4 "may-encrypt" Attribute 3.8.5 "mandatory" Attribute 3.8.6 "protected" Attribute 3.8.7 "vendor-id" Attribute 3.9 Type Element 3.9.1 "type-name" attribute 3.10 Grouped AVPs Element 3.10.1 "name" Attribute 3.10.2 "vendor-id" Attribute 3.11 Enumerated Element 3.11.1 "name" Attribute Frascone et al. expires June 2002 [Page 2] Internet-Draft February 2002 3.11.3 "code" Attribute 4.0 References 5.0 Acknowledgments 6.0 Authors' Addresses Appendix A. Document Type Definition Appendix B. DTD & Dictionary Links Frascone et al. expires June 2002 [Page 3] Internet-Draft February 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 root or top-level element of a Diameter dictionary is the "dic- tionary" element. The dictionary element contains zero or more "ven- dor" elements, the "base" element and zero or more "application" ele- ments. The top-level XML file containing the "dictionary" element SHOULD be named "dictionary.xml". Each "application" element SHOULD be defined in a separate XML file and referenced from the top-level XML file using an external entity declaration. Syntax: +------------+----------------+ | Element | Classification | +------------+----------------+ |vendor | Zero or More | +------------+----------------+ |base | Required | +------------+----------------+ |application | Zero or More | +------------+----------------+ 3.1 Vendor Element Frascone et al. expires June 2002 [Page 4] Internet-Draft February 2002 The Vendor element defines a vendor by a name and associated IANA assigned "SMI Network Management Private Enterprise Codes" [4]. Syntax: +----------+----------+-------------+---------+ |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 Base Element The base element defines the commands, data types and AVPs that are part of the Diameter Base Protocol [1]. 3.3 Application Element One of the ways in which the Diameter protocol can be extended is through the addition of new applications. The application element defines the new Commands, Types or AVPs needed to support a new Diam- eter application. It may also reference elements defined in the base protocol. 3.4 Base Protocol and Application Elements The base commands, and application specific commands have identical Frascone et al. expires June 2002 [Page 5] Internet-Draft February 2002 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: +----------+--------------------+-------------+--------+ |Attribute | Presence | Constraints | Values | +----------+--------------------+-------------+--------+ | uri | Optional | None | String | +----------+--------------------+-------------+--------+ | name | Optional | None | String | | | (application only) | | | +----------+--------------------+-------------+--------+ | id | Required | None | String | | | (application only) | | | +----------+--------------------+-------------+--------+ 3.4.1 "id" Attribute The "id" attribute is the IANA assigned Application Identifier for this application. 3.4.2 "name" Attribute The "name" attribute is the human readable name of this application. Frascone et al. expires June 2002 [Page 6] Internet-Draft February 2002 3.4.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. 3.5 Command Element A command element defines the attributes for a command, and contains any rules to be applied to it. (Note: See Section 3.6 AVP Rule Ele- ment) Syntax: +----------+----------+-------------+---------+ |Attribute | Presence | Constraints | Values | +----------+----------+-------------+---------+ | name | Required | None | String | +----------+----------+-------------+---------+ | code | Required | None | Integer | +----------+----------+-------------+---------+ |vendor-id | Optional | Reference | Integer | +----------+----------+-------------+---------+ 3.5.1 "name" Attribute The "name" attribute defines the name of the command. Only one com- mand is defined for both "Request" and "Answer" portions. So, the "Capabilities-Exchange" command defines the messages, "Capabilities- Exchange-Request", and "Capabilities-Exchange-Answer". 3.5.2 "code" Attribute The "code" attribute defines the command code used to transmit this command. 3.5.3 "vendor-id" Attribute Frascone et al. expires June 2002 [Page 7] Internet-Draft February 2002 If this is a vendor specific command, then the "vendor-id" attribute MUST correspond to a vendor element's "id" field. 3.6 AVP Rule Element AVP rules elements define the placement of key AVPs within commands. They are used to do some semantic 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. The requestrules and answerrules elements define the placement of key AVPs within request and answer commands respectively. These elements may be used to perform syntax checking at the protocol layer. 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: +----------+----------+-------------+-------------------+ |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 | +----------+----------+-------------+-------------------+ Frascone et al. expires June 2002 [Page 8] Internet-Draft February 2002 3.6.1 "name" Attribute This rule applies to the previously defined AVP with the matching "name" attribute. 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 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: Frascone et al. expires June 2002 [Page 9] Internet-Draft February 2002 +------------+----------+-------------+--------+ | Attribute | Presence | Constraints | Values | +------------+----------+-------------+--------+ | type-name | Required | UniqueKey | String | +------------+----------+-------------+--------+ |type-parent | Optional | Reference | String | +------------+----------+-------------+--------+ |description | Optional | None | String | +------------+----------+-------------+--------+ 3.7.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.7.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.7.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.8 Attribute Value Pair Element The avp element completely defines one Attribute Value Pair and is the most frequently used element in the dictionary. The avp element contains either a type element, or a grouped element, and zero or more enum elements together with attributes that completely define the AVP including format and flags. An AVP should only contain enumerations if the type is Unsigned32. Syntax: Frascone et al. expires June 2002 [Page 10] Internet-Draft February 2002 +------------+----------+-------------+--------------------+ | Attribute | Presence | Constraints | Values | +------------+----------+-------------+--------------------+ | name | 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.8.1 "name" Attribute The "name" attribute is the mnemonic describing this attribute, for example, "User-Name" 3.8.2 "description" Attribute The "description" attribute is an optional attribute used to describe the use of the AVP. 3.8.3 "code" Attribute The "code" attribute defines the integer value used to encode the AVP for transmission on the network. Frascone et al. expires June 2002 [Page 11] Internet-Draft February 2002 3.8.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.8.5 "mandatory" Attribute The "mandatory" attribute defines whether the mandatory bit of this AVP should or should not be set. 3.8.6 "protected" Attribute The "protected" attribute defines whether the protected bit of this AVP should or should not be set. 3.8.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.9 Type Element The type element defines the data type of the AVP in which it appears. This element MUST appear in all non-grouped AVP definitions. Syntax: +----------+----------+-------------+--------+ |Attribute | Presence | Constraints | Values | +----------+----------+-------------+--------+ |type-name | Required | UniqueKey | String | +----------+----------+-------------+--------+ 3.9.1 "type-name" attribute The "type-name" attribute contains the data type name. This attribute is of type IDREF and MUST refer to the "type-name" value of a previ- ously defined "typedefn" element. 3.10 Grouped AVPs Element Frascone et al. expires June 2002 [Page 12] Internet-Draft February 2002 The grouped element is used define an AVP which encapsulates a sequence of AVPs together as a single payload. 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: +----------+----------+-------------+---------+ |Attribute | Presence | Constraints | Values | +----------+----------+-------------+---------+ | name | Required | UniqueKey | String | +----------+----------+-------------+---------+ |vendor-id | Optional | Reference | Integer | +----------+----------+-------------+---------+ 3.10.1 "name" Attribute The "name" attribute MUST correspond to some existing AVP's "name" attribute. 3.10.2 "vendor-id" Attribute If this "gavp" element refers to a vendor specific AVP, then the "vendor-id" attribute MUST correspond to a Vendor's "id" attribute. 3.11 Enumerated Element The enum element defines a name to value mapping for use in encoding and decoding AVPs of type Unsigned32. For example, if a particular AVP had two values, Yes and No corre- sponding to 1 and 0, then the entry would look like this: Frascone et al. expires June 2002 [Page 13] Internet-Draft February 2002 Enumerated elements should only be used with Unsigned32 typed AVPs. Syntax: +----------+----------+-------------+---------+ |Attribute | Presence | Constraints | Values | +----------+----------+-------------+---------+ | name | Required | None | String | +----------+----------+-------------+---------+ | code | Required | None | Integer | +----------+----------+-------------+---------+ 3.11.1 "name" Attribute The "name" attribute is the text corresponding to a particular value for the attribute. 3.11.3 "code" Attribute The "code" attribute is the Unsigned32 value corresponding to this enumerated value. 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 The authors would like to thank Brian Cain for his proposal for the Frascone et al. expires June 2002 [Page 14] Internet-Draft February 2002 command element definition. 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@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@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@sun.com Frascone et al. expires June 2002 [Page 15] Internet-Draft February 2002 Appendix A. Document Type Definition Frascone et al. expires June 2002 [Page 16] Internet-Draft February 2002 Frascone et al. expires June 2002 [Page 18] Internet-Draft February 2002 Frascone et al. expires June 2002 [Page 19] Internet-Draft February 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 20]