diff options
Diffstat (limited to 'lib/diameter/doc')
35 files changed, 42604 insertions, 0 deletions
diff --git a/lib/diameter/doc/html/.gitignore b/lib/diameter/doc/html/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/diameter/doc/html/.gitignore diff --git a/lib/diameter/doc/man1/.gitignore b/lib/diameter/doc/man1/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/diameter/doc/man1/.gitignore diff --git a/lib/diameter/doc/man3/.gitignore b/lib/diameter/doc/man3/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/diameter/doc/man3/.gitignore diff --git a/lib/diameter/doc/man4/.gitignore b/lib/diameter/doc/man4/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/diameter/doc/man4/.gitignore diff --git a/lib/diameter/doc/pdf/.gitignore b/lib/diameter/doc/pdf/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/diameter/doc/pdf/.gitignore diff --git a/lib/diameter/doc/src/.gitignore b/lib/diameter/doc/src/.gitignore new file mode 100644 index 0000000000..feeb378fd8 --- /dev/null +++ b/lib/diameter/doc/src/.gitignore @@ -0,0 +1,2 @@ + +/depend.mk diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile new file mode 100644 index 0000000000..1453138cb6 --- /dev/null +++ b/lib/diameter/doc/src/Makefile @@ -0,0 +1,198 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 2010-2011. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% + +ifneq ($(ERL_TOP),) +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk +else +include $(DIAMETER_TOP)/make/target.mk +include $(DIAMETER_TOP)/make/$(TARGET)/rules.mk +endif + +include ../../vsn.mk + +VSN = $(DIAMETER_VSN) + +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +include files.mk + +XML_REF_FILES = $(XML_REF1_FILES) $(XML_REF3_FILES) $(XML_REF4_FILES) + +XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) \ + $(XML_REF_FILES) \ + $(XML_PART_FILES) $(XML_CHAPTER_FILES) + +INTERNAL_HTML_FILES = $(TECHNICAL_DESCR_FILES:%.xml=$(HTMLDIR)/%.html) + +HTML_APP_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) +HTML_EXTRA_FILES = $(XML_EXTRA_FILES:%.xml=$(HTMLDIR)/%.html) +HTML_PART_FILES = $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +HTML_FILES = $(HTML_APP_FILES) $(HTML_EXTRA_FILES) $(HTML_PART_FILES) + +INFO_FILE = ../../info + +HTML_REF_FILES = $(XML_REF_FILES:%.xml=$(HTMLDIR)/%.html) + +HTML_CHAPTER_FILES = $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html) + +EXTRA_FILES = \ + $(DEFAULT_GIF_FILES) \ + $(DEFAULT_HTML_FILES) \ + $(HTML_REF_FILES) \ + $(HTML_CHAPTER_FILES) + +MAN1_FILES = $(XML_REF1_FILES:%.xml=$(MAN1DIR)/%.1) +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) +MAN4_FILES = $(XML_REF4_FILES:%.xml=$(MAN4DIR)/%.4) + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +STANDARD_DIR = ../standard +STANDARDS = + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- + +XML_FLAGS += +DVIPS_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- + +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +docs: pdf html man + +ldocs: local_docs $(INDEX_TARGET) + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +clean clean_docs: clean_pdf clean_html clean_man + rm -f errs core *~ + rm -f depend.mk + +clean_pdf: + rm -f $(PDFDIR)/* + +clean_man: + rm -f $(MAN1DIR)/* $(MAN3DIR)/* $(MAN4DIR)/* + +clean_html: + rm -rf $(HTMLDIR)/* + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +man: $(MAN1_FILES) $(MAN3_FILES) $(MAN4_FILES) + +$(INDEX_TARGET): $(INDEX_SRC) $(APP_FILE) + sed -e 's/%VSN%/$(VSN)/; \ + s/%ERLANG_SITE%/www\.erlang\.se\//; \ + s/%UP_ONE_LEVEL%/..\/..\/..\/doc\/index.html/; \ + s/%OFF_PRINT%/pdf\/diameter-$(VSN).pdf/' $< > $@ + +depend: depend.mk + +debug opt: + +info: + @echo "->Makefile<-" + @echo "" + @echo "DOCSUPPORT = $(DOCSUPPORT)" + @echo "" + @echo "INDEX_FILE = $(INDEX_FILE)" + @echo "INDEX_SRC = $(INDEX_SRC)" + @echo "INDEX_TARGET = $(INDEX_TARGET)" + @echo "" + @echo "XML_APPLICATION_FILES = $(XML_APPLICATION_FILES)" + @echo "XML_PART_FILES = $(XML_PART_FILES)" + @echo "XML_REF1_FILES = $(XML_REF1_FILES)" + @echo "XML_REF3_FILES = $(XML_REF3_FILES)" + @echo "XML_REF4_FILES = $(XML_REF4_FILES)" + @echo "XML_CHAPTER_FILES = $(XML_CHAPTER_FILES)" + @echo "" + @echo "GIF_FILES = $(GIF_FILES)" + @echo "" + @echo "TEX_FILES_USERS_GUIDE = $(TEX_FILES_USERS_GUIDE)" + @echo "TEX_FILES_REF_MAN = $(TEX_FILES_REF_MAN)" + @echo "TEX_FILES_BOOK = $(TEX_FILES_BOOK)" + @echo "" + @echo "MAN1_FILES = $(MAN1_FILES)" + @echo "MAN3_FILES = $(MAN3_FILES)" + @echo "MAN4_FILES = $(MAN4_FILES)" + @echo "" + @echo "HTML_FILES = $(HTML_FILES)" + @echo "TOP_HTML_FILES = $(TOP_HTML_FILES)" + @echo "" + @echo "DEFAULT_HTML_FILES = $(DEFAULT_HTML_FILES)" + @echo "DEFAULT_GIF_FILES = $(DEFAULT_GIF_FILES)" + @echo "" + @echo "" + + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +ifneq ($(ERL_TOP),) +include $(ERL_TOP)/make/otp_release_targets.mk +else +include $(DIAMETER_TOP)/make/release_targets.mk +endif + +release_docs_spec: $(LOCAL)docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DIR) $(RELEASE_PATH)/man/man1 + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DIR) $(RELEASE_PATH)/man/man4 + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(HTMLDIR)/*.* $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DATA) $(MAN1_FILES) $(RELEASE_PATH)/man/man1 + $(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN4_FILES) $(RELEASE_PATH)/man/man4 + [ -z "$(LOCAL)" ] || cp -r $(HTMLDIR)/js $(RELSYSDIR)/doc/html + echo $(LOCAL) + +release_spec: + +depend.mk: depend.sed $(XML_REF_FILES) $(XML_CHAPTER_FILES) Makefile + (for f in $(XML_REF_FILES) $(XML_CHAPTER_FILES); do \ + sed -f $< $$f | sed "s@%FILE%@`basename $$f .xml`@g"; \ + done) \ + > $@ + +-include depend.mk + +.PHONY: clean clean_html clean_man clean_pdf \ + depend debug opt info \ + docs gifs html ldocs man pdf \ + release_docs_spec release_spec diff --git a/lib/diameter/doc/src/book.xml b/lib/diameter/doc/src/book.xml new file mode 100644 index 0000000000..960296528b --- /dev/null +++ b/lib/diameter/doc/src/book.xml @@ -0,0 +1,56 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE book SYSTEM "book.dtd"> + +<book xmlns:xi="http://www.w3.org/2001/XInclude"> + +<header titlestyle="normal"> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Diameter</title> +<prepared></prepared> +<docno></docno> +<date></date> +<rev></rev> +<file>book.xml</file> +</header> + +<insidecover> +</insidecover> + +<pagetext>Diameter</pagetext> + +<preamble> +<contents level="2"></contents> +</preamble> + +<parts lift="no"> +<xi:include href="user_man.xml"/> +</parts> + +<applications> +<xi:include href="ref_man.xml"/> +</applications> + +<releasenotes> +<xi:include href="notes.xml"/> +</releasenotes> + +<index></index> + +</book> diff --git a/lib/diameter/doc/src/depend.sed b/lib/diameter/doc/src/depend.sed new file mode 100644 index 0000000000..5973c4586e --- /dev/null +++ b/lib/diameter/doc/src/depend.sed @@ -0,0 +1,34 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 2011. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% + +# +# Generate dependencies for html output. The output is further +# massaged in Makefile. +# + +/^<com>\([^<]*\)<\/com>/b rf +/^<module>\([^<]*\)<\/module>/b rf + +/^<chapter>/!d + +s@@$(HTMLDIR)/%FILE%.html: %FILE%.xml@ +q + +:rf +s@@$(HTMLDIR)/\1.html: %FILE%.xml@ +q diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml new file mode 100644 index 0000000000..36b6cbf0cf --- /dev/null +++ b/lib/diameter/doc/src/diameter.xml @@ -0,0 +1,1154 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> +<header> + +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter(3)</title> + +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev>%VSN%</rev> +<file>diameter.xml</file> + +</header> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<module>diameter</module> +<modulesummary>Main API of the diameter application.</modulesummary> + +<description> +<p> +This module provides the interface with which a user +creates a service that sends and receives messages using the +Diameter protocol as defined in RFC 3588.</p> + +<p> +Basic usage consists of creating a representation of a +locally implemented Diameter peer and its capabilities with <seealso +marker="#start_service">start_service/2</seealso>, adding transport +capability using <seealso +marker="#add_transport">add_transport/2</seealso> and sending Diameter +requests and receiving Diameter answers with <seealso +marker="#call">call/4</seealso>. +Incoming Diameter requests are communicated as callbacks to a +<seealso +marker="diameter_app">diameter_app(3)</seealso> callback modules as +specified in the service configuration.</p> + +<p> +Beware the difference between <em>diameter application</em> and +<em>Diameter application</em>. +The former refers to the Erlang application named diameter whose main +api is defined here, the latter to an application of the Diameter +protocol in the sense of RFC 3588. +More generally, capitalized Diameter refers to the RFC +and diameter to this implementation.</p> + +<p> +The diameter application must be started before calling functions in +this module.</p> + +</description> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> +<section> +<title>DATA TYPES</title> + +<taglist> + +<tag><c>Address()</c></tag> +<tag><c>DiameterIdentity()</c></tag> +<tag><c>Time()</c></tag> +<tag><c>Unsigned32()</c></tag> +<tag><c>UTF8String()</c></tag> +<item> +<p> +Types corresponding to RFC 3588 AVP Data Formats. +Defined in <seealso marker="diameter_dict">diameter_dict(4)</seealso>.</p> + +<marker id="application_alias"/> +</item> + +<tag><c>application_alias() = term()</c></tag> +<item> +<p> +A name identifying a Diameter application in +service configuration passed to <seealso +marker="#start_service">start_service/2</seealso> and passed to +<seealso marker="#call">call/4</seealso> when sending requests +belonging to the application.</p> + +<marker id="application_module"/> +</item> + +<tag><c>application_module() = Mod | [Mod | ExtraArgs]</c></tag> +<item> +<code> +Mod = atom() +ExtraArgs = list() +</code> + +<p> +A module implementing the callback interface defined in <seealso +marker="diameter_app">diameter_app(3)</seealso>, along with any +extra arguments to be appended to those documented for the interface. +Any extra arguments are appended to the documented list of arguments for +each function. +Note that additional arguments specific to an outgoing request be +specified to <seealso marker="#call">call/4</seealso>, in which case +the call-specific arguments are appended to any specified with the +callback module.</p> + +<marker id="application_opt"/> +</item> + +<tag><c>application_opt()</c></tag> +<item> + +<p> +Options defining a Diameter application as configured in an +<c>application</c> option passed to +<seealso marker="#start_service">start_service/2</seealso>.</p> + +<taglist> + +<tag><c>{alias, application_alias()}</c></tag> +<item> +<p> +An unique identifier for the application in the scope of the +service. +Optional, defaults to the value of the <c>dictionary</c> option.</p> +</item> + +<tag><c>{dictionary, atom()}</c></tag> +<item> +<p> +The name of an encode/decode module for the Diameter +messages defined by the application. +These modules are generated from a specification file whose format is +documented in <seealso +marker="diameter_dict">diameter_dict(4)</seealso>.</p> +</item> + +<tag><c>{module, application_module()}</c></tag> +<item> +<p> +A callback module with which messages of the Diameter application are +handled. +See <seealso marker="diameter_app">diameter_app(3)</seealso> for +information on the required interface and semantics.</p> +</item> + +<tag><c>{state, term()}</c></tag> +<item> +<p> +The initial callback state. +Defaults to the value of the <c>alias</c> option if unspecified. +The prevailing state is passed to certain +<seealso marker="diameter_app">diameter_app(3)</seealso> +callbacks, which can then return a new state.</p> +</item> + +<tag><c>{call_mutates_state, true|false}</c></tag> +<item> +<p> +Specifies whether or not the <seealso +marker="diameter_app#pick_peer">pick_peer/4</seealso> +application callback (following from a call to +<seealso marker="#call">call/4</seealso>) +can modifiy state, +Defaults to <c>false</c> if unspecified.</p> + +<p> +Note that <seealso +marker="diameter_app#pick_peer">pick_peer</seealso> callbacks are +serialized when these are allowed to modify state, which is a +potential performance bottleneck. +A simple Diameter client may suffer no ill effects from using mutable +state but a server or agent that responds to incoming request but +sending its own requests should probably avoid it.</p> +</item> + +<tag><c>{answer_errors, callback|report|discard}</c></tag> +<item> +<p> +Determines the manner in which incoming answer messages containing +decode errors are handled. +If <c>callback</c> then errors result in a <seealso +marker="diameter_app#handle_answer">handle_answer/4</seealso> +callback in the same fashion as for <seealso +marker="diameter_app#handle_request">handle_request/3</seealso>, in the +<c>errors</c> field of the <c>diameter_packet</c> record passed into +the callback. +If <c>report</c> then an answer containing errors is discarded +without a callback and a warning report is written to the log. +If <c>discard</c> then an answer containing errors is silently +discarded without a callback. +In both the <c>report</c> and <c>discard</c> cases the return value +for the <seealso marker="#call">call/4</seealso> invocation in +question is as if a callback had taken place and returned +<c>{error, failure}</c>.</p> + +<p> +Defaults to <c>report</c> if unspecified.</p> +</item> + +</taglist> + +<marker id="call_opt"/> +</item> + +<tag><c>call_opt()</c></tag> +<item> + +<p> +Options available to <seealso marker="#call">call/4</seealso> when +sending an outgoing Diameter request.</p> + +<taglist> + +<tag><c>{extra, list()}</c></tag> +<item> +<p> +Extra arguments to append to callbacks to the callback +module in question. +These are appended to any extra arguments configured with the callback +itself. +Multiple options append to the argument list.</p> +</item> + +<tag><c>{filter, peer_filter()}</c></tag> +<item> +<p> +A filter to apply to the list of available peers before passing them to +the <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> +callback for the application in question. +Multiple options are equivalent a single <c>all</c> filter on the +corresponding list of filters. +Defaults to <c>none</c>.</p> +</item> + +<tag><c>{timeout, Unsigned32()}</c></tag> +<item> +<p> +The number of milliseconds after which the request should +timeout. +Defaults to 5000.</p> +</item> + +<tag><c>detach</c></tag> +<item> +<p> +Causes <seealso marker="#call">call/4</seealso> to return <c>ok</c> as +soon as the request in +question has been encoded instead of waiting for and returning +the result from a subsequent +<seealso marker="diameter_app#handle_answer">handle_answer/4</seealso> +or <seealso +marker="diameter_app#handle_error">handle_error/4</seealso> +callback.</p> +</item> + +</taglist> + +<marker id="capability"/> +</item> + +<tag><c>capability()</c></tag> +<item> + +<p> +AVP values used in outgoing CER/CEA messages during capabilities exchange. +Can be configured both on a service and a transport, the latter taking +precedence over the former.</p> + +<taglist> + +<tag><c>{'Origin-Host', DiameterIdentity()}</c></tag> +<item> +<p> +Value of the Origin-Host AVP in outgoing messages.</p> +</item> + +<tag><c>{'Origin-Realm', DiameterIdentity()}</c></tag> +<item> +<p> +Value of the Origin-Realm AVP in outgoing messages.</p> +</item> + +<tag><c>{'Host-IP-Address', [Address()]}</c></tag> +<item> +<p> +Values of Host-IP-Address AVPs. +Optional.</p> + +<p> +The list of addresses is available to the start function of a +transport module, which either uses them as is or returns a new list +(typically as configured as <c>transport_config()</c> on the +transport module in question) in order for the correct list of +addresses to be sent in capabilities exchange messages.</p> +</item> + +<tag><c>{'Vendor-Id', Unsigned32()}</c></tag> +<item> +<p> +Value of the Vendor-Id AVP sent in an outgoing capabilities +exchange message.</p> +</item> + +<tag><c>{'Product-Name', UTF8String()}</c></tag> +<item> +<p> +Value of the Product-Name AVP sent in an outgoing capabilities +exchange message.</p> +</item> + +<tag><c>{'Origin-State-Id', Unsigned32()}</c></tag> +<item> +<p> +Value of Origin-State-Id to be included in outgoing messages sent by +diameter itself. +In particular, the AVP will be included in CER/CEA and DWR/DWA messages. +Optional.</p> + +<p> +Setting a value of <c>0</c> (zero) is equivalent to not setting a +value as documented in RFC 3588. +The function <seealso +marker="#origin_state_id">origin_state_id/0</seealso> +can be used as to retrieve a value that is set when the diameter +application is started.</p> +</item> + +<tag><c>{'Supported-Vendor-Id', [Unsigned32()]}</c></tag> +<item> +<p> +Values of Supported-Vendor-Id AVPs sent in an outgoing +capabilities exchange message. +Optional, defaults to the empty list.</p> +</item> + +<tag><c>{'Auth-Application-Id', [Unsigned32()]}</c></tag> +<item> +<p> +Values of Auth-Application-Id AVPs sent in an outgoing +capabilities exchange message. +Optional, defaults to the empty list.</p> +</item> + +<tag><c>{'Acct-Application-Id', [Unsigned32()]}</c></tag> +<item> +<p> +Values of Acct-Application-Id AVPs sent in an outgoing +capabilities exchange message. +Optional, defaults to the empty list.</p> +</item> + +<tag><c>{'Vendor-Specific-Application-Id', [Grouped()]}</c></tag> +<item> +<p> +Values of Vendor-Specific-Application-Id AVPs sent in +an outgoing capabilities exchange message. +Optional, defaults to the empty list.</p> +</item> + +<tag><c>{'Firmware-Revision', Unsigned32()}</c></tag> +<item> +<p> +Value of the Firmware-Revision AVP sent in an outgoing capabilities +exchange message. +Optional.</p> +</item> + +</taglist> + +<p> +Note that each tuple communicates one or more AVP values. +It is an error to specify duplicate tuples.</p> + +<marker id="evaluable"/> +</item> + +<tag><c>evaluable() = {M,F,A} | fun() | [evaluable() | A]</c></tag> +<item> +<p> +An expression that can be evaluated as a function in the following +sense.</p> + +<code> +eval([{M,F,A} | T]) -> + apply(M, F, T ++ A); +eval([F|A]) -> + apply(F, A); +eval(F) -> + eval([F]). +</code> + +<p> +Evaluating an evaluable() <c>E</c> on an argument list <c>A</c> +is meant in the sense of <c>eval([E|A])</c>.</p> + +<p> +Beware of using local funs (that is, fun expressions not of the +form <c>fun Module:Name/Arity</c>) in situations in which the fun is +not short-lived and code is to be upgraded at runtime since any +processes retaining such a fun will have a reference to old code.</p> + +<marker id="peer_filter"/> +</item> + +<tag><c>peer_filter() = term()</c></tag> +<item> +<p> +A filter passed to <seealso marker="#call">call/4</seealso> +in order to select candidate peers for a +<seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> +callback. +Has one of the following types.</p> + +<taglist> + +<tag><c>none</c></tag> +<item> +<p> +Matches any peer. +This is a convenience that provides a filter equivalent to no +filter at all.</p> +</item> + +<tag><c>host</c></tag> +<item> +<p> +Matches only those peers whose <c>Origin-Host</c> has the same value +as <c>Destination-Host</c> in the outgoing request in question, +or any peer if the request does not contain +a <c>Destination-Host</c> AVP.</p> +</item> + +<tag><c>realm</c></tag> +<item> +<p> +Matches only those peers whose <c>Origin-Realm</c> has the same value +as <c>Destination-Realm</c> in the outgoing request in question, +or any peer if the request does not contain +a <c>Destination-Realm</c> AVP.</p> +</item> + +<tag><c>{host, any|UTF8String()}</c></tag> +<item> +<p> +Matches only those peers whose <c>Origin-Host</c> has the +specified value, or all peers if the atom <c>any</c>.</p> +</item> + +<tag><c>{realm, any|UTF8String()</c></tag> +<item> +<p> +Matches only those peers whose <c>Origin-Realm</c> has the +value, or all peers if the atom <c>any</c>.</p> +</item> + +<tag><c>{eval, evaluable()}</c></tag> +<item> +<p> +Matches only those peers for which the specified evaluable() evaluates +to true on the peer's <c>diameter_caps</c> record.</p> +</item> + +<tag><c>{neg, peer_filter()}</c></tag> +<item> +<p> +Matches only those peers not matched by the specified filter.</p> +</item> + +<tag><c>{all, [peer_filter()]}</c></tag> +<item> +<p> +Matches only those peers matched by each filter of the specified list.</p> +</item> + +<tag><c>{any, [peer_filter()]}</c></tag> +<item> +<p> +Matches only those peers matched by at least one filter of the +specified list.</p> +</item> + +</taglist> + +<marker id="service_event"/> +</item> + +<tag><c>service_event() = #diameter_event{}</c></tag> +<item> +<p> +Event message sent to processes that have subscribed using <seealso +marker="#subscribe">subscribe/1</seealso>.</p> + +<p> +The <c>info</c> field of the event record can be one of the +following.</p> + +<taglist> + +<tag><c>{up, Ref, Peer, Config, Pkt}</c></tag> +<tag><c>{up, Ref, Peer, Config}</c></tag> +<tag><c>{down, Ref, Peer, Config}</c></tag> +<item> +<code> +Ref = transport_ref() +Peer = diameter_app:peer() +Config = {connect|listen, [transport_opt()]} +Pkt = #diameter_packet{} +</code> + +<p> +Reports that the RFC 3539 watchdog state machine has +transitioned into (<c>up</c>) or out of (<c>down</c>) the open +state. +If a <c>diameter_packet</c> record is present in an <c>up</c> tuple +then there has been an exchange of capabilities exchange messages and +the record contains the received CER or CEA, otherwise the +connection has reestablished without the loss or transport +connectivity.</p> + +<p> +Note that a single up/down event for a given peer corresponds to +as many peer_up/down callbacks as there are Diameter +applications shared by the peer, as determined during capablilities +exchange. +That is, the event communicates connectivity with the +peer as a whole while the callbacks communicate connectivity with +respect to individual Diameter applications.</p> +</item> + +<tag><c>{reconnect, Ref, Opts}</c></tag> +<item> +<code> +Ref = transport_ref() +Opts = [transport_opt()] +</code> + +<p> +A connecting transport is attempting to establish/reestablish a +transport connection with a peer following <c>reconnect_timer</c> or +<c>watchdog_timer</c> expiry.</p> +</item> + +</taglist> + +<p> +For forward compatibility, a subscriber should be prepared to receive +<c>diameter_event.info</c> of forms other than those documented +above.</p> + +<marker id="service_name"/> +</item> + +<tag><c>service_name() = term()</c></tag> +<item> +<p> +The name of a service as passed to <seealso +marker="#start_service">start_service/2</seealso> and with which the +service is identified. +There can be at most one service with a given name on a given node. +Note that <c>erlang:make_ref/0</c> can be used to generate a service name +that is somewhat unique.</p> + +<marker id="service_opt"/> +</item> + +<tag><c>service_opt()</c></tag> +<item> +<p> +Options accepted by <seealso +marker="#start_service">start_service/2</seealso>. +Can be any <c>capability()</c> tuple as +well as the following.</p> + +<taglist> + +<tag><c>{application, [application_opt()]}</c></tag> +<item> +<p> +Defines a Diameter application supported by the service.</p> + +<p> +A service must define one application for each Diameter application it +intends to support. +For an outgoing Diameter request, the application is specified by +passing the desired application's <c>application_alias()</c> to +<seealso marker="#call">call/4</seealso>, while for an +incoming request the application identifier in the message +header determines the application (and callback module), the +application identifier being specified in the <seealso +marker="diameter_dict">dictionary</seealso> file defining the +application.</p> +</item> + +</taglist> + +<marker id="transport_opt"/> +</item> + +<tag><c>transport_opt()</c></tag> +<item> +<p> +Options accepted by <seealso +marker="#add_transport">add_transport/2</seealso>.</p> + +<taglist> +<tag><c>{transport_module, atom()}</c></tag> +<item> +<p> +A module implementing a transport process as defined in <seealso +marker="diameter_transport">diameter_transport(3)</seealso>. +Defaults to <c>diameter_tcp</c> if unspecified.</p> + +<p> +The interface required of a transport module is documented in <seealso +marker="diameter_transport">diameter_transport(3)</seealso>.</p> +</item> + +<tag><c>{transport_config, term()}</c></tag> +<item> +<p> +A term passed as the third argument to the <seealso +marker="diameter_transport#start">start/3</seealso> function of +the relevant <c>transport_module</c> in order to start a transport process. +Defaults to the empty list if unspecified.</p> +</item> + +<tag><c>{applications, [application_alias()]}</c></tag> +<item> +<p> +The list of Diameter applications to which usage of the transport +should be restricted. +Defaults to all applications configured on the service +in question.</p> +</item> + +<tag><c>{capabilities, [capability()]}</c></tag> +<item> +<p> +AVP's used to construct outgoing CER/CEA messages. +Any AVP specified takes precedence over a corresponding value specified +for the service in question.</p> +</item> + +<tag><c>{watchdog_timer, TwInit}</c></tag> +<item> +<code> +TwInit = Unsigned32() + | {M,F,A} +</code> + +<p> +The RFC 3539 watchdog timer. +An integer value is interpreted as the RFC's TwInit in milliseconds, +a jitter of ± 2 seconds being added at each rearming of the +timer to compute the RFC's Tw. +An MFA is expected to return the RFC's Tw directly, with jitter +applied, allowing the jitter calculation to be performed by +the callback.</p> + +<p> +An integer value must be at least 6000 as required by RFC 3539. +Defaults to 30000 if unspecified.</p> +</item> + +<tag><c>{reconnect_timer, Tc}</c></tag> +<item> +<code> +Tc = Unsigned32() +</code> + +<p> +For a connecting transport, the RFC 3588 Tc timer, in milliseconds. +Note that this timer determines the frequency with which the transport +will attempt to establish a connection with its peer only <em>before</em> +an initial connection is established: once there is an initial +connection it's watchdog_timer that determines the frequency of +reconnection attempts, as required by RFC 3539.</p> + +<p> +For a listening transport, the timer specifies the time after which a +previously connected peer will be forgotten: a connection after this time is +regarded as an initial connection rather than a reestablishment, +causing the RFC 3539 state machine to pass to state OPEN rather than +REOPEN. +Note that these semantics are not goverened by the RFC and +that a listening transport's reconnect_timer should be greater than its +peers's Tc plus jitter.</p> + +<p> +Defaults to 30000 for a connecting transport and 60000 for a listening +transport.</p> +</item> + +</taglist> + +<p> +Unrecognized options are silently ignored but are returned unmodified +by <seealso +marker="#service_info">service_info/2</seealso> and can be referred to +in predicate functions passed to <seealso +marker="#remove_transport">remove_transport/2</seealso>.</p> + +</item> + +</taglist> + +</section> + +<marker id="add_transport"/> +<funcs> + +<!-- ===================================================================== --> + +<func> +<name>add_transport(SvcName, {connect|listen, Options}) + -> {ok, Ref} | {error, Reason}</name> +<fsummary>Add transport capability to a service.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Options = [transport_opt()]</v> +<v>Ref = ref()</v> +<v>Reason = term()</v> +</type> +<desc> +<p> +Add transport capability to a service.</p> + +<p> +The service will start a transport process(es) in order to establish a +connection with the peer, either by connecting to the peer +(<c>connect</c>) or by accepting incoming connection requests +(<c>listen</c>). +A connecting transport establishes transport connections with at most +one peer, an listening transport potentially with many.</p> + +<p> +The diameter application takes responsibility for exchanging +CER/CEA with the peer. +Upon successful completion of capabilities exchange the service +calls each relevant application module's <seealso +marker="diameter_app#peer_up">peer_up/3</seealso> callback +after which the caller can exchange Diameter messages with the peer over +the transport. +In addition to CER/CEA, the service takes responsibility for the +handling of DWR/DWA and required by RFC 3539 as well as for DPR/DPA.</p> + +<p> +The returned reference uniquely identifies the transport within the +scope of the service. +Note that the function returns before a transport connection has been +established. +It is not an error to add a transport to a service that has not yet +been configured: a service can be started after configuring +transports.</p> + +<marker id="call"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>call(SvcName, App, Request, Options) -> ok | Answer | {error, Reason}</name> +<fsummary>Send a Diameter request message.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>App = application_alias()</v> +<v>Request = diameter_app:message()</v> +<v>Answer = term()</v> +<v>Options = [call_opt()]</v> +</type> +<desc> +<p> +Send a Diameter request message and possibly return the answer or error.</p> + +<p> +<c>App</c> identifies the Diameter application in which the request is +defined and callbacks to the corresponding callback module +will follow as described below and in <seealso +marker="diameter_app">diameter_app(3)</seealso>. +Unless the <c>detach</c> option has been specified to cause an earlier +return, the call returns either when an answer message is received +from the peer or an error occurs. +In the case of an answer, the return value is as returned by a +<seealso +marker="diameter_app#handle_answer">handle_answer/4</seealso> +callback. +In the case of an error, whether or not the error is returned directly +by diameter or from a <seealso +marker="diameter_app#handle_error">handle_error/4</seealso> +callback depends on whether or not the outgoing request is +successfully encoded for transmission from the peer, the cases being +documented below.</p> + +<p> +If there are no suitable peers, or if +<seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> +rejects them by returning 'false', then <c>{error, no_connection}</c> +is returned. +If <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> +selects a candidate peer then a request process is spawned for the +outgoing request, in which there is a +<seealso +marker="diameter_app#prepare_request">prepare_request/3</seealso> +callback, the message is encoded and sent.</p> + +<p> +There are several error cases which may prevent an +answer from being received and passed to a +<seealso marker="diameter_app#handle_answer">handle_answer/4</seealso> +callback:</p> + +<list> + +<item> +<p> +If the initial encode of the outgoing request +fails, then the request process fails and <c>{error, encode}</c> +is returned.</p> +</item> + +<item> +<p> +If the request is successfully encoded and sent but +the answer times out then a +<seealso marker="diameter_app#handle_error">handle_error/4</seealso> +callback takes place with <c>Reason = timeout</c>.</p> +</item> + +<item> +<p> +If the request is successfully encoded and sent but the service in +question is stopped before an answer is received then a +<seealso marker="diameter_app#handle_error">handle_error/4</seealso> +callback takes place <c>Reason = cancel</c>.</p> +</item> + +<item> +<p> +If the transport connection with the peer goes down after the request +has been sent but before an answer has been received then an attempt +is made to resend the request to an alternate peer. +If no such peer is available, or if the subsequent +<seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> +callback rejects the candidates, then a +<seealso marker="diameter_app#handle_error">handle_error/4</seealso> +callback takes place with <c>Reason = failover</c>. +If a peer is selected then a +<seealso +marker="diameter_app#prepare_retransmit">prepare_retransmit/3</seealso> +callback takes place, after which the semantics are the same as +following an initial +<seealso marker="diameter_app#prepare_request"> +prepare_request/3</seealso> +callback.</p> +</item> + +<item> +<p> +If an encode error takes place during +retransmission then the request process fails and +<c>{error, failure}</c> is returned.</p> +</item> + +<item> +<p> +If an application callback made in processing the request fails +(pick_peer, prepare_request, prepare_retransmit, +handle_answer or handle_error) then either +<c>{error, encode}</c> or <c>{error, failure}</c> +is returned depending on whether or not there has been an +attempt to send the request over the transport.</p> +</item> + +</list> + +<p> +Note that <c>{error, encode}</c> is the only return value which +guarantees that the request has <em>not</em> been sent over the +transport.</p> + +<marker id="origin_state_id"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>origin_state_id() -> Unsigned32()</name> +<fsummary>Returns a reasonable Origin-State-Id.</fsummary> +<desc> +<p> +Return a reasonable value for use as Origin-State-Id in +outgoing messages.</p> + +<p> +The value returned is the number of seconds since 19680120T031408Z, +the first value that can be encoded as a Diameter Time(), +at the time the diameter application was started.</p> + +<marker id="remove_transport"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>remove_transport(SvcName, Pred) -> ok</name> +<fsummary>Remove previously added transports.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Pred = Fun | MFA | ref() | list() | true | false</v> +<v></v> +<v>Fun = fun((reference(), connect|listen, list()) -> boolean())</v> +<v> | fun((reference(), list()) -> boolean())</v> +<v> | fun((list()) -> boolean())</v> +<v>MFA = {atom(), atom(), list()}</v> +</type> +<desc> +<p> +Remove previously added transports.</p> + +<p> +<c>Pred</c> determines which transports to remove. +An arity-3-valued <c>Pred</c> removes all transports for which +<c>Pred(Ref, Type, Opts)</c> returns <c>true</c>, where <c>Type</c> and +<c>Opts</c> are as passed to <seealso +marker="#add_transport">add_transport/2</seealso> and <c>Ref</c> is +as returned by the corresponding call. +The remaining forms are equivalent to an arity-3 fun as follows.</p> + +<code> +Pred = fun(reference(), list()): fun(Ref, _, Opts) -> Pred(Ref, Opts) end +Pred = fun(list()): fun(_, _, Opts) -> Pred(Opts) end +Pred = reference(): fun(Ref, _, _) -> Pred == Ref end +Pred = list(): fun(_, _, Opts) -> [] == Pred -- Opts end +Pred = true: fun(_, _, _) -> true end +Pred = false: fun(_, _, _) -> false end +Pred = {M,F,A}: fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end +</code> + +<p> +Removing a transport causes all associated transport connections to +be broken. +A base application DPR message with +Disconnect-Cause <c>DO_NOT_WANT_TO_TALK_TO_YOU</c> will be sent +to each connected peer before disassociating the transport configuration +from the service and terminating the transport upon reception of +DPA or timeout.</p> + +<!-- TODO: document the timeout value, possibly make configurable. --> + +<marker id="service_info"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>service_info(SvcName, Item) -> Value</name> +<fsummary>Return specific information about a started service.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Value = term()</v> +</type> +<desc> +<p> +Return information about a started service.</p> + +<marker id="services"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>services() -> [SvcName]</name> +<fsummary>Return the list of started services.</fsummary> +<type> +<v>SvcName = service_name()</v> +</type> +<desc> +<p> +Return the list of started services.</p> + +<marker id="session_id"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>session_id(Ident) -> OctetString()</name> +<fsummary>Return a value for a Session-Id AVP.</fsummary> +<type> +<v>Ident = DiameterIdentity()</v> +</type> +<desc> +<p> +Return a value for a Session-Id AVP.</p> + +<p> +The value has the form required by section 8.8 of RFC 3588. +Ident should be the Origin-Host of the peer from which +the message containing the returned value will be sent.</p> + +<marker id="start"/> +</desc> +</func> + +<!-- ===================================================================== --> +<func> +<name>start() -> ok | {error, Reason}</name> +<fsummary>Start the diameter application.</fsummary> +<desc> +<p> +Start the diameter application.</p> + +<p> +The diameter application must be started before starting a service. +In a production system this will typically be accomplished by a boot +file, not by calling <c>start/0</c> explicitly.</p> + +<marker id="start_service"/> +</desc> +</func> + +<!-- ===================================================================== --> +<func> +<name>start_service(SvcName, Options) -> ok | {error, Reason}</name> +<fsummary>Start a Diameter service.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Options = [service_opt()]</v> +<v>Reason = term()</v> +</type> +<desc> +<p> +Start a diameter service.</p> + +<p> +A service defines a locally-implemented Diameter peer, specifying the +capabilities of the peer to be used during capabilities exchange and +the Diameter applications that it supports. +Transports are added to a service using <seealso +marker="#add_transport">add_transport/2</seealso>.</p> + +<marker id="stop_service"/> +</desc> +</func> + +<!-- ===================================================================== --> +<func> +<name>stop() -> ok | {error, Reason}</name> +<fsummary>Stop the diameter application.</fsummary> +<desc> +<p> +Stop the diameter application.</p> + +<p> +</p> + +<marker id="stop_service"/> +</desc> +</func> + +<!-- ===================================================================== --> +<func> +<name>stop_service(SvcName) -> ok | {error, Reason}</name> +<fsummary>Stop a Diameter service.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Reason = term()</v> +</type> +<desc> +<p> +Stop a diameter service.</p> + +<marker id="subscribe"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>subscribe(SvcName) -> true</name> +<fsummary>Subscribe to event messages.</fsummary> +<type> +<v>SvcName = service_name()</v> +</type> +<desc> +<p> +Subscribe to <c>service_event()</c> messages from a service.</p> + +<p> +It is not an error to subscribe to events from a service +that does not yet exist.</p> + +<marker id="unsubscribe"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>unsubscribe(SvcName) -> true</name> +<fsummary>Unsubscribe to event messages.</fsummary> +<type> +<v>SvcName = service_name()</v> +</type> +<desc> +<p> +Unsubscribe to event messages from a service.</p> + +</desc> +</func> + +</funcs> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameter_app">diameter_app(3)</seealso>, +<seealso marker="diameter_transport">diameter_transport(3)</seealso>, +<seealso marker="diameter_dict">diameter_dict(4)</seealso></p> + +</section> + +</erlref> diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml new file mode 100644 index 0000000000..fc359b9d1d --- /dev/null +++ b/lib/diameter/doc/src/diameter_app.xml @@ -0,0 +1,608 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> +<header> + +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter_app(3)</title> +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev>%REV%</rev> +<file>diameter_app.xml</file> + +</header> + +<module>diameter_app</module> +<modulesummary> +Callback module of a Diameter application.</modulesummary> + +<description> + +<p> +A diameter service as started by <seealso +marker="diameter#start_service">diameter:start_service/2</seealso> +configures one of more Diameter applications, each of whose +configuration specifies a callback that handles messages specific to +its application. +The messages and AVPs of the Diameter application are defined in a +dictionary file whose format is documented in +<seealso marker="diameter_dict">diameter_dict(4)</seealso> +while the callback module is documented here. +The callback module implements the Diameter application-specific +functionality of a service.</p> + +<p> +A callback module must export all of the functions documented below. +The functions themselves are of three distinct flavours:</p> + +<list> +<item> +<p> +<seealso marker="#peer_up">peer_up/3</seealso> and +<seealso marker="#peer_down">peer_down/3</seealso> signal the +attainment or loss of connectivity with a Diameter peer.</p> +</item> + +<item> +<p> +<seealso marker="#pick_peer">pick_peer/4</seealso>, +<seealso marker="#prepare_request">prepare_request/3</seealso>, +<seealso marker="#prepare_retransmit">prepare_retransmit/3</seealso>, +<seealso marker="#handle_answer">handle_answer/4</seealso> +and <seealso marker="#handle_error">handle_error/4</seealso> are (or may +be) called as a consequence of a call to <seealso +marker="diameter#call">diameter:call/4</seealso> to send an outgoing +Diameter request message.</p> +</item> + +<item> +<p> +<seealso marker="#handle_request">handle_request/3</seealso> +is called in response to an incoming Diameter request message.</p> +</item> + +</list> + +</description> + +<note> +<p> +The arities given for the the callback functions here assume no extra +arguments. +All functions will also be passed any extra arguments configured with +the callback module itself when calling <seealso +marker="diameter#start_service">diameter:start_service/2</seealso> +and, for the call-specific callbacks, any extra arguments passed to +<seealso marker="diameter#call">diameter:call/4</seealso>.</p> +</note> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<section> +<title>DATA TYPES</title> + +<taglist> + +<tag><c>capabilities() = #diameter_caps{}</c></tag> +<item> +<p> +A record containing the identities of +the local and remote Diameter peers having an established transport +connection, as well as the capabilities as +determined by capabilities exchange. +Each field of the record is a 2-tuple consisting of +values for the (local) host and (remote) peer. +Optional or possibly multiple values are encoded as lists of values, +mandatory values as the bare value.</p> +</item> + +<tag><c>message() = record() | list()</c></tag> +<item> +<p> +The representation of a Diameter message as passed to +<seealso marker="diameter#call">diameter:call/4</seealso>. +The record representation is as outlined in +<seealso +marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>: +a message as defined in a dictionary file is encoded as a record with +one field for each component AVP. +Equivalently, a message can also be encoded as a list whose head is +the atom-valued message name (the record name minus any +prefix specified in the relevant dictionary file) and whose tail is a +list of <c>{FieldName, FieldValue}</c> pairs.</p> + +<p> +A third representation allows a message to be specified as a list +whose head is a <c>diameter_header</c> record and whose tail is a list +of <c>diameter_avp</c> records. +This representation is used by diameter itself when relaying requests +as directed by the return value of a +<seealso marker="#handle_request">handle_request/3</seealso> +callback. +It differs from the other other two in that it bypasses the checks for +messages that do not agree with their definitions in the dictionary in +question (since relays agents must handle arbitrary request): messages +are sent exactly as specified.</p> + +</item> + +<tag><c>packet() = #diameter_packet{}</c></tag> +<item> +<p> +A container for incoming and outgoing Diameters message that's passed +through encode/decode and transport. +Fields of a packet() record should not be set in return values except +as documented.</p> +</item> + +<tag><c>peer_ref() = term()</c></tag> +<item> +<p> +A term identifying a transport connection with a Diameter peer. +Should be treated opaquely.</p> +</item> + +<tag><c>peer() = {peer_ref(), capabilities()}</c></tag> +<item> +<p> +A tuple representing a Diameter peer connection.</p> +</item> + +<tag><c>service_name() = term()</c></tag> +<item> +<p> +The service supporting the Diameter application. +Specified to <seealso +marker="diameter#start_service">diameter:start_service/2</seealso> +when starting the service.</p> +</item> + +<tag><c>state() = term()</c></tag> +<item> +<p> +The state maintained by the application callback functions +<seealso marker="#peer_up">peer_up/3</seealso>, +<seealso marker="#peer_down">peer_down/3</seealso> and (optionally) +<seealso marker="#pick_peer">pick_peer/4</seealso>. +The initial state is configured in the call to +<seealso +marker="diameter#start_service">diameter:start_service/2</seealso> +that configures the application on a service. +Callback functions returning a state are evaluated in a common +service-specific process while +those not returning state are evaluated in a request-specific +process.</p> +</item> + +</taglist> + +<marker id="peer_up"/> +</section> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<funcs> + +<func> +<name>Mod:peer_up(SvcName, Peer, State) -> NewState</name> +<fsummary>Invoked when a transport connection has been established</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>State = NewState = state()</v> +</type> +<desc> +<p> +Invoked when a transport connection has been established +and a successful capabilities exchange has indicated that the peer +supports the Diameter application of the application on which +the callback module in question has been configured.</p> + +<marker id="peer_down"/> +</desc> +</func> + +<func> +<name>Mod:peer_down(SvcName, Peer, State) -> NewState</name> +<fsummary>Invoked when a transport connection has been lost.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>State = NewState = state()</v> +</type> +<desc> +<p> +Invoked when a transport connection has been lost following a previous +call to <seealso marker="#peer_up">peer_up/3</seealso>.</p> + +<marker id="pick_peer"/> +</desc> +</func> + +<func> +<name>Mod:pick_peer(Candidates, Reserved, SvcName, State) + -> {ok, Peer} | {Peer, NewState} | false</name> +<fsummary>Select a target peer for an outgoing request.</fsummary> +<type> +<v>Candidates = [peer()]</v> +<v>Peer = peer() | false</v> +<v>SvcName = service_name()</v> +<v>State = NewState = state()</v> +</type> +<desc> +<p> +Invoked as a consequence of a call to <seealso +marker="diameter#call">diameter:call/4</seealso> to select a destination +peer for an outgoing request, the return value indicating the selected peer. +A new application state can also be returned but only if the Diameter +application in question was +configured with the option <c>call_mutates_state</c> set to +<c>true</c>, as documented for <seealso +marker="diameter#start_service">diameter:start_service/2</seealso>.</p> + +<p> +The candidate peers list will only include those +which are selected by any <c>filter</c> option specified in the call to +<seealso marker="diameter#call">diameter:call/4</seealso>, and only +those which have indicated support for the Diameter application in +question.</p> + +<p> +The return values <c>false</c> and <c>{false, State}</c> are +equivalent when callback state is mutable, as are +<c>{ok, Peer}</c> and <c>{Peer, State}</c>. +Returning a peer as <c>false</c> causes <c>{error, no_connection}</c> +to be returned from <seealso marker="diameter#call">diameter:call/4</seealso>. +Returning a peer() from an initial pick_peer/4 callback will result in a +<seealso marker="#prepare_request">prepare_request/3</seealso> callback +followed by either <seealso +marker="#handle_answer">handle_answer/4</seealso> +or <seealso marker="#handle_error">handle_error/4</seealso> depending +on whether or not an answer message is received from the peer. +If transport with the peer is lost before this then a new <seealso +marker="#pick_peer">pick_peer/4</seealso> callback takes place to +select an alternate peer.</p> + +<p> +Note that there is no guarantee that a <seealso +marker="#pick_peer">pick_peer/4</seealso> callback to select +an alternate peer will be followed by any additional callbacks, only +that the initial <seealso +marker="#pick_peer">pick_peer/4</seealso> will be, since a +retransmission to an alternate peer is abandoned if an answer is +received from a previously selected peer.</p> + +<marker id="prepare_request"/> +</desc> + +</func> + +<func> +<name>Mod:prepare_request(Packet, SvcName, Peer) -> Action</name> +<fsummary>Return a request for encoding and transport.</fsummary> +<type> +<v>Packet = packet()</v> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>Action = {send, packet() | message()} | {discard, Reason} | discard</v> +</type> +<desc> +<p> +Invoked to return a request for encoding and transport. +Allows the sender to access the selected peer's capabilities +in order to set (for example) <c>Destination-Host</c> and/or +<c>Destination-Realm</c> in the outgoing request, although the +callback need not be limited to this usage. +Many implementations may simply want to return <c>{send, Packet}</c></p> + +<p> +A returned packet() should set the request to be encoded in its +<c>msg</c> field and can set the <c>transport_data</c> field in order +to pass information to the transport module. +Extra arguments passed to <seealso +marker="diameter#call">diameter:call/4</seealso> can be used to +communicate transport data to the callback. +A returned packet() can also set the <c>header</c> field to a +<c>diameter_header</c> record in order to specify values that should +be preserved in the outgoing request, although this should typically +not be necessary and allows the callback to set header values +inappropriately. +A returned <c>length</c>, <c>cmd_code</c> or <c>application_id</c> is +ignored.</p> + +<p> +Returning <c>{discard, Reason}</c> causes the request to be aborted +and the <seealso +marker="diameter#call">diameter:call/4</seealso> for which the +callback has taken place to return <c>{error, Reason}</c>. +Returning <c>discard</c> is equivalent to returning <c>{discard, +discarded}</c>.</p> + +<marker id="prepare_retransmit"/> +</desc> +</func> + +<func> +<name>Mod:prepare_retransmit(Packet, SvcName, Peer) -> Result</name> +<fsummary>Return a request for encoding and retransmission.</fsummary> +<type> +<v>Packet = packet()</v> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>Result = {send, packet() | message()} | {discard, Reason} | discard</v> +</type> +<desc> +<p> +Invoked to return a request for encoding and retransmission. +Has the same role as <seealso +marker="#prepare_request">prepare_request/3</seealso> in the case that +a peer connection is lost an an alternate peer selected but the +argument packet() is as returned by the initial +<c>prepare_request/3</c>.</p> + +<p> +Returning <c>{discard, Reason}</c> causes the request to be aborted +and a <seealso +marker="#handle_error">handle_error/4</seealso> callback to +take place with <c>Reason</c> as initial argument. +Returning <c>discard</c> is equivalent to returning <c>{discard, +discarded}</c>.</p> + +<marker id="handle_answer"/> +</desc> +</func> + +<func> +<name>Mod:handle_answer(Packet, Request, SvcName, Peer) -> Result</name> +<fsummary>Receive an answer message from a peer.</fsummary> +<type> +<v>Packet = packet()</v> +<v>Request = message()</v> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>Result = term()</v> +</type> +<desc> +<p> +Invoked when an answer message is received from a peer. +The return value is returned from the call to <seealso +marker="diameter#call">diameter:call/4</seealso> for which the +callback takes place unless the <c>detach</c> option was +specified.</p> + +<p> +The decoded answer record is in the <c>msg</c> field of the argument +packet(), +the undecoded binary in the <c>packet</c> field. +<c>Request</c> is the outgoing request message as was returned from +<seealso marker="#prepare_request">prepare_request/3</seealso> or +<seealso marker="#prepare_retransmit">prepare_retransmit/3</seealso> +before the request was passed to the transport.</p> + +<p> +For any given call to <seealso +marker="diameter#call">diameter:call/4</seealso> there is at most one +call to the handle_answer callback of the application in question: any +duplicate answer (due to retransmission or otherwise) is discarded. +Similarly, only one of <c>handle_answer/4</c> or <c>handle_error/4</c> is +called for any given request.</p> + +<p> +By default, an incoming answer message that cannot be successfully +decoded causes the request process in question to fail, causing the +relevant call to <seealso +marker="diameter#call">diameter:call/4</seealso> +to return <c>{error, failure} (unless the <c>detach</c> option was +specified)</c>. +In particular, there is no <c>handle_error/4</c> callback in this +case. +Application configuration may change this behaviour as described for +<seealso +marker="diameter#start_service">diameter:start_service/2</seealso>.</p> + +<marker id="handle_error"/> +</desc> +</func> + +<func> +<name>Mod:handle_error(Reason, Request, SvcName, Peer) -> Result</name> +<fsummary>Return an error from a outgoing request.</fsummary> +<type> +<v>Reason = timeout | failover | term()</v> +<v>Request = message()</v> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>Result = term()</v> +</type> +<desc> +<p> +Invoked when an error occurs before an answer message is received from +a peer in response to an outgoing request. +The return value is returned from the call to <seealso +marker="diameter#call">diameter:call/4</seealso> for which the +callback takes place (unless the <c>detach</c> option was +specified).</p> + +<p> +Reason <c>timeout</c> indicates that an answer message has not been +received within the required time. +Reason <c>failover</c> indicates +that the transport connection to the peer to which the request has +been sent has been lost but that not alternate node was available, +possibly because a <seealso marker="#pick_peer">pick_peer/4</seealso> +callback returned false.</p> + +<marker id="handle_request"/> +</desc> +</func> + +<func> +<name>Mod:handle_request(Packet, SvcName, Peer) -> Action</name> +<fsummary>Receive an incoming request.</fsummary> +<type> +<v>Packet = packet()</v> +<v>SvcName = term()</v> +<v>Peer = peer()</v> +<v>Action = Reply | {relay, Opts} | discard | {eval, Action, ContF}</v> +<v>Reply = {reply, message()} + | {protocol_error, 3000..3999}</v> +<v>Opts = diameter:call_opts()</v> +<v>ContF = diameter:evaluable()</v> +</type> +<desc> +<p> +Invoked when a request message is received from a peer. +The application in which the callback takes place (that is, the +callback module as configured with <seealso +marker="diameter#start_service">diameter:start_service/2</seealso>) +is determined by the Application Identifier in the header of the +incoming request message, the selected module being the one +whose corresponding <seealso +marker="diameter_dict#MESSAGE_RECORDS">dictionary</seealso> declares +itself as defining either the application in question or the Relay +application.</p> + +<p> +The argument packet() has the following signature.</p> + +<code> +#diameter_packet{header = #diameter_header{}, + avps = [#diameter_avp{}], + msg = record() | undefined, + errors = ['Unsigned32'() | {'Unsigned32'(), #diameter_avp{}}], + bin = binary(), + transport_data = term()} +</code> + +<p> +The <c>msg</c> field will be <c>undefined</c> only in case the request has +been received in the relay application. +Otherwise it contains the record representing the request as outlined +in <seealso +marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>.</p> + +<p> +The <c>errors</c> field specifies any Result-Code's identifying errors +that were encountered in decoding the request. +In this case diameter will set both Result-Code and +Failed-AVP AVP's in a returned +answer message() before sending it to the peer: +the returned message() need only set any other required AVP's. +Note that the errors detected by diameter are all of the 5xxx series +(Permanent Failures). +The <c>errors</c> list is empty if the request has been received in +the relay application.</p> + +<p> +The <c>transport_data</c> field contains an arbitrary term passed into +diameter from the transport module in question, or the atom +<c>undefined</c> if the transport specified no data. +The term is preserved in the packet() containing any answer message +sent back to the transport process unless another value is explicitly +specified.</p> + +<p> +The semantics of each of the possible return values are as follows.</p> + +<taglist> + +<tag><c>{reply, message()}</c></tag> +<item> +<p> +Send the specified answer message to the peer.</p> +</item> + +<tag><c>{protocol_error, 3000..3999}</c></tag> +<item> +<p> +Send an answer message to the peer containing the specified +protocol error. +Equivalent to</p> +<code> +{reply, ['answer-message' | Avps] +</code> +<p> +where <c>Avps</c> sets the Origin-Host, Origin-Realm, the specified +Result-Code and (if the request sent one) Session-Id AVP's.</p> + +<p> +Note that RFC 3588 mandates that only answers with a 3xxx series +Result-Code (protocol errors) may set the E bit. +Returning a non-3xxx value in a <c>protocol_error</c> tuple +will cause the request process in question to fail.</p> +</item> + +<tag><c>{relay, Opts}</c></tag> +<item> +<p> +Relay a request to another peer. +The appropriate Route-Record AVP will be added to the relayed request +by diameter and <seealso marker="#pick_peer">pick_peer/4</seealso> +and <seealso marker="#prepare_request">prepare_request/3</seealso> +callback will take place just as if <seealso +marker="diameter#call">diameter:call/4</seealso> had been called +explicitly. +However, returning a <c>relay</c> tuple also causes the End-to-End +Identifier to be preserved in the header of the relayed request as +required by RFC 3588.</p> + +<p> +The returned <c>Opts</c> should not specify <c>detach</c> and +the <seealso marker="#handle_answer">handle_answer/4</seealso> +callback following from a relayed request must return its first +argument, the <c>diameter_packet</c> record containing the answer +message. +Note that the <c>extra</c> option can be specified to supply arguments +that can distinguish the relay case from others if so desired, +although the form of the request message may be sufficient.</p> +</item> + +<tag><c>discard</c></tag> +<item> +<p> +Discard the request.</p> +</item> + +<tag><c>{eval, Action, ContF}</c></tag> +<item> +<p> +Handle the request as if <c>Action</c> has been returned and then +evaluate <c>ContF</c> in the request process.</p> +</item> + +</taglist> + +<p> +Note that diameter will respond to protocol errors in an incoming +request without invoking <c>handle_request/3</c>.</p> + +</desc> +</func> + +</funcs> + +</erlref> diff --git a/lib/diameter/doc/src/diameter_compile.xml b/lib/diameter/doc/src/diameter_compile.xml new file mode 100644 index 0000000000..72bac30709 --- /dev/null +++ b/lib/diameter/doc/src/diameter_compile.xml @@ -0,0 +1,124 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE comref SYSTEM "comref.dtd"> + +<comref> +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> + +The program may be used and/or copied only with the written permission +from Ericsson AB, or in accordance with the terms and conditions +stipulated in the agreement/contract under which the program has been +supplied. + +</legalnotice> + +<title>diameterc(1)</title> + +<prepared></prepared> +<docno></docno> +<date></date> +<rev></rev> +<file>diameter_compile.xml</file> +</header> + +<com>diameterc</com> +<comsummary><![CDATA[diameterc [<options>] <file>]]></comsummary> + +<description> + +<p> +The diameterc utility is used to transform diameter +<seealso marker="diameter_dict">dictionary files</seealso> +into Erlang source. +The resulting source implements the interface diameter requires +to encode and decode the dictionary's messages and AVP's.</p> + +</description> + +<section> +<title>USAGE</title> + +<taglist> + +<tag><![CDATA[diameterc [<options>] <file>]]></tag> +<item> +<p> +Transforms a single dictionary file. Valid options are as follows.</p> + +<!-- Leave -h/d/v undocumented, except for the usage message from the + utility itself. --> + +<taglist> +<tag><![CDATA[-o <dir>]]></tag> +<item> +<p> +Specifies the directory into which the generated source should be written. +Defaults to the current working directory.</p> +</item> + +<tag><![CDATA[-i <dir>]]></tag> +<item> +<p> +Specifies a directory to add to the code path. +Typically used to point at beam files corresponding to dictionaries +included by the one being compiled (using the <c>@includes</c> directive): +inclusion is a beam dependency, not an erl/hrl dependency.</p> + +<p> +Multiple <c>-i</c> options can be specified.</p> +</item> + +<tag><![CDATA[-E]]></tag> +<item> +<p> +Supresses erl generation.</p> +</item> + +<tag><![CDATA[-H]]></tag> +<item> +<p> +Supresses hrl generation.</p> +</item> + +</taglist> + +</item> +</taglist> + +</section> + +<!-- ===================================================================== --> + +<section> +<title>EXIT STATUS</title> + +<p> +Returns 0 on success, non-zero on failure.</p> + +</section> + +<!-- ===================================================================== --> + +<section> +<title>BUGS</title> + +<p> +The identification of errors in the source file is poor.</p> + +</section> + +<!-- ===================================================================== --> + +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameter_dict">diameter_dict(4)</seealso></p> + +</section> + +</comref> diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml new file mode 100644 index 0000000000..a87f59bad5 --- /dev/null +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -0,0 +1,608 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "fileref.dtd"> + +<fileref> +<header> + +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter_dict(4)</title> +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev>%VSN%</rev> +<file>diameter_dict.xml</file> +</header> + +<!-- ===================================================================== --> + +<file>diameter_dict</file> +<filesummary>Dictionary inteface of the diameter application.</filesummary> + +<description> +<p> +A diameter service as configured with <seealso +marker="diameter#start_service">diameter:start_service/2</seealso> +specifies one or more supported Diameter applications. +Each Diameter application specifies a dictionary module that knows how +to encode and decode its messages and AVP's. +The dictionary module is in turn generated from a file that defines +these messages and AVP's. +The format of such a file is defined in +<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso> below. +Users add support for their specific applications by creating +dictionary files, compiling them to Erlang modules using +<seealso marker="diameterc">diameterc</seealso> and configuring the +resulting dictionaries modules on a service.</p> + +<p> +The codec generation also results in a hrl file that defines records +for the messages and grouped AVP's defined for the application, these +records being what a user of the diameter application sends and receives. +(Modulo other available formats as discussed in <seealso +marker="diameter_app">diameter_app(3)</seealso>.) +These records and the underlying Erlang data types corresponding to +Diameter data formats are discussed in <seealso +marker="#MESSAGE_RECORDS">MESSAGE RECORDS</seealso> and <seealso +marker="#DATA_TYPES">DATA TYPES</seealso> respectively. +The generated hrl also contains defines for the possible values of +AVPs of type Enumerated.</p> + +<p> +The diameter application includes three dictionary modules +corresponding to applications defined in section 2.4 of RFC 3588: +<c>diameter_gen_base_rfc3588</c> for the Diameter Common Messages +application with application identifier 0, +<c>diameter_gen_accounting</c> for the Diameter Base Accounting +application with application identifier 3 and +<c>diameter_gen_relay</c>the Relay application with application +identifier 0xFFFFFFFF. +The Common Message and Relay applications are the only applications +that diameter itself has any specific knowledge of. +The Common Message application is used for messages that diameter +itself handles: CER/CEA, DWR/DWA and DPR/DPA. +The Relay application is given special treatment with regard to +encode/decode since the messages and AVP's it handles are not specifically +defined.</p> + +<marker id="FILE_FORMAT"/> +</description> + +<!-- ===================================================================== --> + +<section> +<title>FILE FORMAT</title> + +<p> +A dictionary file consists of distinct sections. +Each section starts with a line consisting of a tag +followed by zero or more arguments. +Each section ends at the the start of the next section or end of file. +Tags consist of an ampersand character followed by a keyword and are +separated from their arguments by whitespace. +Whitespace within a section separates individual tokens but its +quantity is insignificant.</p> + +<p> +The tags, their arguments and the contents of each corresponding +section are as follows. +Each section can occur only once unless otherwise specified. +The order in which sections are specified is unimportant.</p> + +<taglist> + +<tag><c>@id Number</c></tag> +<item> +<p> +Defines the integer Number as the Diameter Application Id of the +application in question. +The section has empty content.</p> + +<p> +The Application Id is set in the Diameter Header of outgoing messages +of the application, and the value in the header of an incoming message +is used to identify the relevant dictionary module.</p> + +<p> +Example:</p> + +<code> +@id 16777231 +</code> + +</item> + +<tag><c>@name Mod</c></tag> +<item> +<p> +Defines the name of the generated dictionary module. +The section has empty content. +Mod must match the regular expression '^[a-zA-Z0-9][-_a-zA-Z0-9]*$'; +that is, contains only alphanumerics, hyphens and underscores begin with an +alphanumeric.</p> + +<p> +A name is optional and defaults to the name of the dictionary file +minus any extension. +Note that a generated module must have a unique name an not colide +with another module in the system.</p> + +<p> +Example:</p> + +<code> +@name etsi_e2 +</code> + +</item> + +<tag><c>@prefix Name</c></tag> +<item> +<p> +Defines Name as the prefix to be added to record and constant names in +the generated dictionary module and hrl. +The section has empty content. +Name must be of the same form as a @name.</p> + +<p> +A prefix is optional but can +be used to disambiguate record and constant names +resulting from similarly named messages and AVP's in different +Diameter applications.</p> + +<p> +Example:</p> + +<code> +@prefix etsi_e2_ +</code> + +</item> + +<tag><c>@vendor Number Name</c></tag> +<item> +<p> +Defines the integer Number as the the default Vendor-ID of AVP's for +which the V flag is set. +Name documents the owner of the application +but is otherwise unused. +The section has empty content.</p> + +<p> +Example:</p> + +<code> +@vendor 13019 ETSI +</code> + +</item> + +<tag><c>@avp_vendor_id Number</c></tag> +<item> +<p> +Defines the integer Number as the Vendor-ID of the AVP's listed in the +section content, overriding the <c>@vendor</c> default. +The section content consists of AVP names. +Can occur zero or more times (with different values of Number).</p> + +<p> +Example:</p> + +<code> +@avp_vendor_id 2937 + +WWW-Auth +Domain-Index +Region-Set +</code> + +</item> + +<tag><c>@inherits Mod</c></tag> +<item> +<p> +Defines the name of a generated dictionary module containing AVP +definitions referenced by the dictionary but not defined by it. +The section content is empty.</p> + +<p> +Can occur 0 or more times (with different values of Mod) but all +dictionaries should typically inherit RFC3588 AVPs from +<c>diameter_gen_base_rfc3588</c>.</p> + +<p> +Example:</p> + +<code> +@inherits diameter_gen_base_rfc3588 +</code> + +</item> + +<tag><c>@avp_types</c></tag> +<item> +<p> +Defines the name, code, type and flags of individual AVPs. +The section consists of definitions of the form</p> + +<p><c>Name Code Type Flags</c></p> + +<p> +where Code is the integer AVP code, Flags is a string of V, +M and P characters indicating the flags to be +set on an outgoing AVP or a single - (minus) character if none are to +be set. +Type identifies either an AVP Data Format as defined in <seealso +marker="#DATA_TYPES">DATA TYPES</seealso> below or a +type as defined by a <c>@custom_types</c> tag.</p> + +<p> +Example:</p> + +<code> +@avp_types + +Location-Information 350 Grouped VM +Requested-Information 353 Enumerated V +</code> + +<p> +Note that the P flag has been deprecated by the Diameter Maintenance +and Extensions Working Group of the IETF: diameter will set the P flag +to 0 as mandated by the current draft standard.</p> + +</item> + +<tag><c>@custom_types Mod</c></tag> +<item> +<p> +Defines AVPs for which module Mod provides encode/decode. +The section contents consists of type names. +For each AVP Name defined with custom type Type, Mod should export the +function Name/3 with arguments encode|decode, Type and Data, +the latter being the term to be encoded/decoded. +The function returns the encoded/decoded value.</p> + +<p> +Can occur 0 or more times (with different values of Mod).</p> + +<p> +Example:</p> + +<code> +@custom_types rfc4005_types + +Framed-IP-Address +</code> +</item> + +<tag><c>@messages</c></tag> +<item> +<p> +Defines the messages of the application. +The section content consists of definitions of the form specified in +section 3.2 of RFC 3588, "Command Code ABNF specification".</p> + +<!-- RFC 4740 RTR/RTA --> +<code> +@messages + +RTR ::= < Diameter Header: 287, REQ, PXY > + < Session-Id > + { Auth-Application-Id } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + { Destination-Host } + { SIP-Deregistration-Reason } + [ Destination-Realm ] + [ User-Name ] + * [ SIP-AOR ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +RTA ::= < Diameter Header: 287, PXY > + < Session-Id > + { Auth-Application-Id } + { Result-Code } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + [ Authorization-Lifetime ] + [ Auth-Grace-Period ] + [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] +</code> + +</item> + +<tag><c>@grouped</c></tag> +<item> +<p> +Defines the contents of the AVPs of the application having type +Grouped. +The section content consists of definitions of the form specified in +section 4.4 of RFC 3588, "Grouped AVP Values".</p> + +<p> +Example:</p> + +<code> +@grouped + +SIP-Deregistration-Reason ::= < AVP Header: 383 > + { SIP-Reason-Code } + [ SIP-Reason-Info ] + * [ AVP ] +</code> +</item> + +<tag><c>@enum Name</c></tag> +<item> +<p> +Defines values of AVP Name having type Enumerated. +Section content consists of names and corresponding integer values. +Integer values can be prefixed with 0x to be interpreted as +hexidecimal.</p> + +<p> +Can occur 0 or more times (with different values of Name).</p> + +<p> +Example:</p> + +<code> +@enum SIP-Reason-Code + +PERMANENT_TERMINATION 0 +NEW_SIP_SERVER_ASSIGNED 1 +SIP_SERVER_CHANGE 2 +REMOVE_SIP_SERVER 3 +</code> +</item> + +</taglist> + +<p> +Comments can be included in a dictionary file using semicolon: +text from a semicolon to end of line is ignored.</p> + +<marker id="MESSAGE_RECORDS"/> +</section> + +<!-- ===================================================================== --> + +<section> +<title>MESSAGE RECORDS</title> + +<p> +The hrl generated from a dictionary specification defines records for the +messages and grouped AVPs defined in <c>@messages</c> and +<c>@grouped</c> sections. +For each message or grouped AVP definition, a record is defined whose +name is the message or AVP name prefixed with any dictionary prefix +defined with <c>@prefix</c> and whose fields are the names of the AVPs +contained in the message or grouped AVP in the order specified in the +definition in question. +For example, the grouped AVP</p> + +<code> +SIP-Deregistration-Reason ::= < AVP Header: 383 > + { SIP-Reason-Code } + [ SIP-Reason-Info ] + * [ AVP ] +</code> + +<p> +will result in the following record definition given an empty +prefix.</p> + +<code> +-record('SIP-Deregistration-Reason' {'SIP-Reason-Code', + 'SIP-Reason-Info', + 'AVP'}). +</code> + +<p> +The values encoded in the fields of generated records depends on the +type and number of times the AVP can occur. +In particular, an AVP which is specified as occurring exactly once is +encoded as a value of the AVP's type while an AVP with any other +specification is encoded as a list of values of the AVP's type. +The AVP's type is as specified in the AVP definition, the RFC 3588 +types being described below.</p> + +<marker id="DATA_TYPES"/> +</section> + +<!-- ===================================================================== --> + +<section> +<title>DATA TYPES</title> + +<p> +The data formats defined in sections 4.2 ("Basic AVP Data +Formats") and 4.3 ("Derived AVP Data Formats") of RFC 3588 are encoded +as values of the types defined here. +Values are passed to <seealso +marker="diameter#call">diameter:call/4</seealso> +in a request record when sending a request, returned in a resulting +answer record and passed to a <seealso +marker="diameter_app#handle_request">handle_request</seealso> +callback upon reception of an incoming request.</p> + +<p> +<em>Basic AVP Data Formats</em></p> + +<marker id="OctetString"/> +<marker id="Integer32"/> +<marker id="Integer64"/> +<marker id="Unsigned32"/> +<marker id="Unsigned64"/> +<marker id="Float32"/> +<marker id="Float64"/> +<marker id="Grouped"/> + +<code> +OctetString() = [0..255] +Integer32() = -2147483647..2147483647 +Integer64() = -9223372036854775807..9223372036854775807 +Unsigned32() = 0..4294967295 +Unsigned64() = 0..18446744073709551615 +Float32() = '-infinity' | float() | infinity +Float64() = '-infinity' | float() | infinity +Grouped() = record() +</code> + +<p> +On encode, an OctetString() can be specified as an iolist(), +excessively large floats (in absolute value) are equivalent to +<c>infinity</c> or <c>'-infinity'</c> and excessively large integers +result in encode failure. +The records for grouped AVPs are as discussed in the previous +section.</p> + +<p> +<em>Derived AVP Data Formats</em></p> + +<marker id="Address"/> +<code> +Address() = OctetString() + | tuple() +</code> + +<p> +On encode, an OctetString() IPv4 address is parsed in the usual +x.x.x.x format while an IPv6 address is parsed in any of the formats +specified by section 2.2 of RFC 2373, "Text Representation of +Addresses". +An IPv4 tuple() has length 4 and contains values of type 0..255. +An IPv6 tuple() has length 8 and contains values of type 0..65535. +The tuple representation is used on decode.</p> + +<marker id="Time"/> +<code> +Time() = {date(), time()} + +where + + date() = {Year, Month, Day} + time() = {Hour, Minute, Second} + + Year = integer() + Month = 1..12 + Day = 1..31 + Hour = 0..23 + Minute = 0..59 + Second = 0..59 +</code> + +<p> +Additionally, values that can be encoded are +limited by way of their encoding as four octets as required by RFC +3588 with the required extension from RFC 2030. +In particular, only values between <c>{{1968,1,20},{3,14,8}}</c> +and <c>{{2104,2,26},{9,42,23}}</c> (both inclusive) can be encoded.</p> + +<marker id="UTF8String"/> +<code> +UTF8String() = [integer()] +</code> + +<p> +List elements are the UTF-8 encodings of the individual characters +in the string. +Invalid codepoints will result in encode/decode failure.</p> + +<marker id="DiameterIdentity"/> +<code> +DiameterIdentity() = OctetString() +</code> + +<p> +A value must have length at least 1.</p> + +<marker id="DiameterURI"/> +<code> +DiameterURI() = OctetString() + | #diameter_URI{type = Type, + fqdn = FQDN, + port = Port, + transport = Transport, + protocol = Protocol} + +where + + Type = aaa | aaas + FQDN = OctetString() + Port = integer() + Transport = sctp | tcp + Protocol = diameter | radius | 'tacacs+' +</code> + +<p> +On encode, fields port, transport and protocol default to 3868, sctp +and diameter respectively. +The grammar of an OctetString-valued DiameterURI() is as specified in +section 4.3 of RFC 3588. +The record representation is used on decode.</p> + +<marker id="Enumerated"/> +<code> +Enumerated() = Integer32() +</code> + +<p> +On encode, values can be specified using the macros defined in a +dictionary's hrl file.</p> + +<marker id="IPFilterRule"/> +<marker id="QoSFilterRule"/> +<code> +IPFilterRule() = OctetString() +QoSFilterRule() = OctetString() +</code> + +<p> +Values of these types are not currently parsed by diameter.</p> + +</section> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameterc">diameterc(1)</seealso>, +<seealso marker="diameter">diameter(3)</seealso>, +<seealso marker="diameter_app">diameter_app(3)</seealso></p> + +</section> + +</fileref> diff --git a/lib/diameter/doc/src/diameter_examples.xml b/lib/diameter/doc/src/diameter_examples.xml new file mode 100644 index 0000000000..966d1f1eee --- /dev/null +++ b/lib/diameter/doc/src/diameter_examples.xml @@ -0,0 +1,45 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> +<header> + +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> + +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Examples</title> +<prepared></prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_examples.xml</file> +</header> + +<!-- ===================================================================== --> + +<p> +To be written. +Example code can be found in the diameter application's +<c>examples</c> subdirectory.</p> + +</chapter> + diff --git a/lib/diameter/doc/src/diameter_intro.xml b/lib/diameter/doc/src/diameter_intro.xml new file mode 100644 index 0000000000..ef08002a8b --- /dev/null +++ b/lib/diameter/doc/src/diameter_intro.xml @@ -0,0 +1,95 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> + +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Introduction</title> +<prepared></prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_intro.xml</file> +</header> + +<p> +The diameter application is an implementation of the Diameter protocol +as defined by RFC 3588. +It supports arbitrary Diameter applications by way of a +<em>dictionary</em> interface that allows messages and AVP's to be +defined and input into diameter as configuration. +It has support for all roles defined in the RFC: client, server and +agent. +This chapter provides a short overview of the application.</p> + +<p> +A Diameter peer is implemented by configuring a <em>service</em> and +one or more <em>transports</em> using the interface module +<seealso marker="diameter">diameter</seealso>. +The service configuration defines the Diameter applications to be +supported by the peer and, typically, the capabilities that it should +send to remote peers at capabilities exchange upon the establishment +of transport connections. +A transport is configured on a service and provides protocol-specific +send/receive functionality by way of a transport interface defined by +diameter and implemented by a transport module. +The diameter application provides two transport modules: <seealso +marker="diameter_tcp">diameter_tcp</seealso> and <seealso +marker="diameter_sctp">diameter_sctp</seealso> for transport over TCP +(using <c>gen_tcp</c>) and SCTP (using <c>gen_sctp</c>) respectively. +Other transports can be provided by any module that implements +diameter's <seealso marker="diameter_transport">transport +interface</seealso>.</p> + +<p> +While a service typically implements a single Diameter peer (as +identified by an Origin-Host AVP), transports can themselves be +associated with capabilities AVP's so that a single service be used to +implement more than one Diameter peer.</p> + +<p> +Each Diameter application defined on a service is configured with a +callback module that implements the <seealso +marker="diameter_app">application interface</seealso> through which +diameter communicates the connectivity of remote peers, requests peer +selection for outgoing requests, and communicates the reception of +incoming Diameter request and answer messages. +An application using diameter implements these application callback +modules to provide the functionality of the Diameter peer(s) it +implements.</p> + +<p> +Each Diameter application is also configured with one or more +dictionary modules +that provide encode/decode functionality for outgoing/incoming +Diameter messages. +A module is generated from a <seealso +marker="diameter_dict">specification file</seealso> using the <seealso +marker="diameterc">diameterc</seealso> utility. +Dictionaries for the RFC 3588 Diameter Common Messages, Base +Accounting and Relay applications are provided by the diameter +application.</p> + +</chapter> + diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml new file mode 100644 index 0000000000..d0377f4b38 --- /dev/null +++ b/lib/diameter/doc/src/diameter_sctp.xml @@ -0,0 +1,133 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter_sctp(3)</title> +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_sctp.xml</file> +</header> + +<module>diameter_sctp</module> +<modulesummary>Diameter transport over SCTP.</modulesummary> + +<description> + +<p> +This module implements diameter transport over SCTP using gen_sctp. +It can be specified as the value of a transport_module option to +<seealso +marker="diameter#add_transport">diameter:add_transport/2</seealso> +and implements the behaviour documented in +<seealso marker="diameter_transport">diameter_transport(3)</seealso>.</p> + +<marker id="start"/> +</description> + +<!-- ===================================================================== --> + +<funcs> + +<func> +<name>start({Type, Ref}, Svc, [Opt]) + -> {ok, Pid, [LAddr]} | {error, Reason}</name> +<fsummary>Start a transport process.</fsummary> +<type> +<v>Type = connect | accept</v> +<v>Ref = reference()</v> +<v>Svc = #diameter_service{}</v> +<v>Opt = {raddr, ip_address()} | {rport, integer()} | term()</v> +<v>Pid = pid()</v> +<v>LAddr = ip_address()</v> +<v>Reason = term()</v> +</type> +<desc> + +<p> +The start function required by <seealso +marker="diameter_transport#start">diameter_transport(3)</seealso>.</p> + +<p> +The only diameter_sctp-specific argument is the options list. +Options <c>raddr</c> and <c>rport</c> specify the remote address +and port for a connector and not valid for a listener. +The former is required while latter defaults to 3868 if unspecified. +More than one <c>raddr</c> option can be specified, in which case the +connector in question attempts each in sequence until an association +is established. +Remaining options are any accepted by gen_sctp:open/1, with the exception +of options <c>mode</c>, <c>binary</c>, <c>list</c>, <c>active</c> +and <c>sctp_events</c>. +Note that options <c>ip</c> and <c>port</c> specify the local address +and port respectively.</p> + +<p> +Multiple <c>ip</c> options can be specified for a multihomed peer. +If none are specified then the values of Host-IP-Address +on the service are used. (In particular, one of these must be specified.) +Option <c>port</c> defaults to 3868 for a listener and 0 for a connector.</p> + +<p> +diameter_sctp uses the <c>transport_data</c> field of +the <c>diameter_packet</c> record to communicate the stream on which an +inbound message has been received, or on which an outbound message +should be sent: the value will be of the form <c>{stream, Id}</c> +on an inbound message passed to a <seealso +marker="diameter_app#handle_request">handle_request</seealso> or <seealso +marker="diameter_app#handle_answer">handle_answer</seealso> callback. +For an outbound message, either <c>undefined</c> (explicitly of +by specifying the outbound message as a <c>binary()</c>) or a tuple +should be set in the return value of <seealso +marker="diameter_app#handle_request">handle_request</seealso> +(typically by retaining the value passed into this function) +or <seealso +marker="diameter_app#prepare_request">prepare_request</seealso>. +The value <c>undefined</c> uses a "next outbound stream" id and then +increments this modulo the total number outbound streams. That +is, successive values of <c>undefined</c> cycle through all outbound +streams.</p> + +<!-- TODO: Some way of getting at the number of available outbound --> +<!-- streams. --> + +</desc> +</func> + +</funcs> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameter_transport">diameter_transport(3)</seealso></p> + +</section> + +</erlref> diff --git a/lib/diameter/doc/src/diameter_soc.xml b/lib/diameter/doc/src/diameter_soc.xml new file mode 100644 index 0000000000..4f8581a904 --- /dev/null +++ b/lib/diameter/doc/src/diameter_soc.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> + +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Standards Compliance</title> +<prepared></prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_soc.xml</file> + +</header> + +<p> +Known points of questionable or non-compliance.</p> + +<!-- ===================================================================== --> + +<section> +<title>RFC 3588</title> + +<list> + +<item> +<p> +The End-to-End Security framework (section 2.9) isn't implemented +since it is largely unspecified. +The document that was to describe it +(reference [AAACMS]) was abandoned in an uncompleted state several +years ago and the current draft RFC deprecates the framework, +including the P Flag in the AVP header.</p> +</item> + +<item> +<p> +There is no TLS support. +It's unclear (aka uninvestigated) how TLS would impact +diameter but IPsec can be used without it needing to know.</p> +</item> + +<item> +<p> +There is no explicit support for peer discovery (section 5.2). +It can possibly be implemented on top of diameter as is but this is +probably something that diameter should do. +The current draft deprecates portions of the original RFC's mechanisms +however.</p> +</item> + +<item> +<p> +The peer state machine's election process (section 5.6.4) isn't +implemented as specified since it assumes knowledge of a +peer's Origin-Host before sending it a CER. (The identity becoming known +upon reception of CEA.) +The possibility of configuring +the peer's Origin-Host could be added, along with handling of the case +that it sends something else, but for many applications this will +just be unnecessary configuration of a value that it has no control over.</p> +</item> +<!-- Transport protocol plus address/port, which we do know when + sending and receiving CER, is enough to definitely identify + the peer. However, there's nothing stopping a peer from using + different identities on different transport protocols, even + if it's maybe a bit far-fetched. --> + +</list> + +</section> + +<!-- ===================================================================== --> + +<section> +<title>RFC 3539</title> + +<p> +RFC 3539 is more difficult to comply to since it discusses +problems as much as it requires functionality but all the MUST's are +covered, the watchdog state machine being the primary one. +Of the optional functionality, load balancing is left to the +diameter user (since it's the one deciding who to send to) and +there is no Congestion Manager.</p> + +</section> + +</chapter> diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml new file mode 100644 index 0000000000..5d6e07b1b8 --- /dev/null +++ b/lib/diameter/doc/src/diameter_tcp.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter_tcp(3)</title> +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_tcp.xml</file> +</header> + +<module>diameter_tcp</module> +<modulesummary>Diameter transport over TCP.</modulesummary> + +<description> + +<p> +This module implements diameter transport over TCP using gen_tcp. +It can be specified as the value of a transport_module option to +<seealso +marker="diameter#add_transport">diameter:add_transport/2</seealso> +and implements the behaviour documented in +<seealso marker="diameter_transport">diameter_transport(3)</seealso>.</p> + +<marker id="start"/> +</description> + +<!-- ===================================================================== --> + +<funcs> + +<func> +<name>start({Type, Ref}, Svc, [Opt]) + -> {ok, Pid, [LAddr]} | {error, Reason}</name> +<fsummary>Start a transport process.</fsummary> +<type> +<v>Type = connect | accept</v> +<v>Ref = reference()</v> +<v>Svc = #diameter_service{}</v> +<v>Opt = {raddr, ip_address()} | {rport, integer()} | term()</v> +<v>Pid = pid()</v> +<v>LAddr = ip_address()</v> +<v>Reason = term()</v> +</type> +<desc> + +<p> +The start function required by <seealso +marker="diameter_transport#start">diameter_transport(3)</seealso>.</p> + +<p> +The only diameter_tcp-specific argument is the options list. +Options <c>raddr</c> and <c>rport</c> specify the remote address +and port for a connector and not valid for a listener. +Remaining options are any accepted by gen_tcp:connect/3 for +a connector, or gen_tcp:listen/2 for a listener, with the exception +of <c>binary</c>, <c>packet</c> and <c>active</c>. +Also, option <c>port</c> can be specified for a listener to specify the +local listening port, the default being the standardized 3868 if +unspecified. +Note that option <c>ip</c> specifies the local address.</p> + +<p> +If the service specifies more than one Host-IP-Address and +option <c>ip</c> is unspecified then then the +first of the service's addresses is used as the local address.</p> + +<p> +The returned local address list has length one.</p> + +</desc> +</func> + +</funcs> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameter_transport">diameter_transport(3)</seealso></p> + +</section> + +</erlref> diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml new file mode 100644 index 0000000000..37cc871e75 --- /dev/null +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -0,0 +1,203 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter_transport(3)</title> +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_transport.xml</file> +</header> + +<module>diameter_transport</module> +<modulesummary>Diameter transport interface.</modulesummary> + +<description> + +<p> +A module specified as a <c>transport_module</c> to <seealso +marker="diameter#add_transport">diameter:add_transport/2</seealso> +must implement the interface documented here. +The interface consists of a function with which +diameter starts a transport process and a message interface with which +the transport process communicates with the process that starts it (aka its +parent).</p> + +<marker id="start"/> +</description> + +<!-- ===================================================================== --> + +<funcs> + +<func> +<name>Mod:start({Type, Ref}, Svc, Opts) + -> {ok, Pid} | {ok, Pid, LAddrs} | {error, Reason}</name> +<fsummary>Start a transport process.</fsummary> +<type> +<v>Type = connect | accept</v> +<v>Ref = reference()</v> +<v>Svc = #diameter_service{}</v> +<v>Opts = term()</v> +<v>Pid = pid()</v> +<v>LAddrs = [ip_address()]</v> +<v>Reason = term()</v> +</type> +<desc> +<p> +Start a transport process. +Called by diameter as a consequence of a call to <seealso +marker="diameter#add_transport">diameter:add_transport/2</seealso> in +order to establish or accept a transport connection respectively. +A transport process maintains a connection with a single remote peer.</p> + +<p> +The first argument indicates whether the transport process in question +is being started for a connecting (<c>connect</c>) or listening +(<c>accept</c>) transport. +In the latter case, transport processes are started as required to +accept connections from multiple peers. +Ref is in each case the same value that was returned from the +call to <seealso +marker="diameter#add_transport">diameter:add_transport/2</seealso> +that has lead to starting of a transport process.</p> + +<p> +A transport process must implement the message interface documented below. +It should retain the pid of its parent, monitor the parent and terminate if +it dies. +It should not link to the parent. +It should exit if its transport connection with its peer is lost.</p> + +<p> +Transport processes for a given service are started sequentially.</p> + +<p> +The start function should use the 'Host-IP-Address' list on the service, +namely <c>Svc#diameter_service.host_ip_address</c>, and/or +<c>Opts</c> to select an appropriate list of local IP addresses, +and should return this list if different from the service addresses. +The returned list is used to populate 'Host-IP-Address' AVPs in outgoing +capabilities exchange messages, the service addresses being used +otherwise.</p> + +<marker id="MESSAGES"/> +</desc> +</func> + +</funcs> + +<!-- ===================================================================== --> + +<section> +<title>MESSAGES</title> + +<p> +All messages sent over the transport interface are of the +form <c>{diameter, term()}</c>.</p> + +<p> +A transport process can expect the following messages from +diameter.</p> + +<taglist> + +<tag><c>{diameter, {send, Packet}}</c></tag> +<item> +<p> +An outbound Diameter message. +Packet can be either <c>binary()</c> (the message to be sent) +or a <c>#diameter_packet{}</c> whose <c>transport_data</c> field +containes a value other than undefined.</p> +</item> + +<tag><c>{diameter, {close, Pid}}</c></tag> +<item> +<p> +A request to close the transport connection. +The transport process should terminate after closing the +connection. +Pid is the pid() of the parent process.</p> +</item> + +</taglist> + +<p> +A transport process should send the following messages +to its parent.</p> + +<taglist> + +<tag><c>{diameter, {self(), connected}}</c></tag> +<item> +<p> +Inform the parent that the transport process with Type = accept has +established a connection with the peer. +Not sent if the transport process has Type = connect.</p> +</item> + +<tag><c>{diameter, {self(), connected, Remote}}</c></tag> +<item> +<p> +Inform the parent that the transport process with Type = connect +has established a connection with a peer. +Not sent if the transport process has Type = accept. +Remote is an arbitrary term that uniquely identifies the remote +endpoint to which the transport has connected.</p> +</item> + +<tag><c>{diameter, {recv, Packet}}</c></tag> +<item> +<p> +An inbound Diameter message. +Packet can be either <c>binary()</c> (the message to be sent) +or <c>#diameter_packet{}</c> +whose <c>packet</c> field contains a <c>binary()</c>. +Any value (other than undefined) set in +the <c>transport_data</c> field will be passed back with a +corresponding answer message in the case that the inbound message is a +request unless the sender sets another value. +How the <c>transport_data</c> is used/interpreted is up to the +transport module.</p> +</item> + +</taglist> + +</section> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameter_tcp">diameter_tcp(3)</seealso>, +<seealso marker="diameter_sctp">diameter_sctp(3)</seealso></p> + +</section> + +</erlref> diff --git a/lib/diameter/doc/src/diameter_using.xml b/lib/diameter/doc/src/diameter_using.xml new file mode 100644 index 0000000000..809b76bdf3 --- /dev/null +++ b/lib/diameter/doc/src/diameter_using.xml @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> + +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Using the stack</title> +<prepared></prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_using.xml</file> + +</header> + +<p> +To be written.</p> + +<!-- ===================================================================== --> + +</chapter> diff --git a/lib/diameter/doc/src/files.mk b/lib/diameter/doc/src/files.mk new file mode 100644 index 0000000000..79d53abceb --- /dev/null +++ b/lib/diameter/doc/src/files.mk @@ -0,0 +1,52 @@ +#-*-makefile-*- ; force emacs to enter makefile-mode + +# %CopyrightBegin% +# +# Copyright Ericsson AB 2010-2011. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% + +XML_APPLICATION_FILES = \ + ref_man.xml + +XML_REF1_FILES = \ + diameter_compile.xml + +XML_REF3_FILES = \ + diameter.xml \ + diameter_app.xml \ + diameter_transport.xml \ + diameter_tcp.xml \ + diameter_sctp.xml + +XML_REF4_FILES = \ + diameter_dict.xml + +XML_PART_FILES = \ + user_man.xml + +XML_EXTRA_FILES = + +XML_CHAPTER_FILES = \ + diameter_intro.xml \ + diameter_using.xml \ + diameter_examples.xml \ + diameter_soc.xml \ + notes.xml + +BOOK_FILES = \ + book.xml + +GIF_FILES = \ + notes.gif diff --git a/lib/diameter/doc/src/notes.gif b/lib/diameter/doc/src/notes.gif Binary files differnew file mode 100644 index 0000000000..e000cca26a --- /dev/null +++ b/lib/diameter/doc/src/notes.gif diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml new file mode 100644 index 0000000000..eafddd7d1e --- /dev/null +++ b/lib/diameter/doc/src/notes.xml @@ -0,0 +1,104 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Release Notes</title> +<prepared></prepared> +<docno></docno> +<date></date> +<rev></rev> +<file>notes.xml</file> +</header> + +<p> +Releases are listed in reverse chronological order, most recent +first.</p> + +<!-- ===================================================================== --> + +<section> +<title>diameter 0.9</title> + +<p> +Initial release of the diameter application.</p> + +<p> +Known issues or limitations:</p> + +<list> + +<item> +<p> +Some agent-related functionality is not entirely complete. +In particular, support for proxy agents, that advertise specific +Diameter applications but otherwise relay messages in much the same +way as relay agents (for which a <seealso +marker="diameter_app#handle_request">handle_request/3</seealso> +callback can return a <c>relay</c> tuple), will be completed in an +upcoming release. +There may also be more explicit support for redirect agents, although +redirect behaviour can be implemented with the current +functionality.</p> + +</item> + +<item> +<p> +There is some asymmetry in the treatment of messages sent as +<c>diameter_header/avp</c> records and those sent in the "normal" +fashion, and not all of this is documented. +This is related to the previous point since this form of sending a +message was introduced specifically to handle relay agent behaviour +using the same callback interface as for client/server behaviour.</p> +</item> + +<item> +<p> +The User's Guide is currently quite thin. +The introductory chapter followed by the examples (in the application +<c>examples</c> subdirectory) may be sufficient +for those having some familiarity with the Diameter protocol but the +intention is to provide more introductory text. +The reference documentation is quite complete, although some points +could likely be expanded upon.</p> +</item> + +<item> +<p> +The function <seealso +marker="diameter#service_info">diameter:service_info/2</seealso> +can be used to retrieve information about a started service +(statistics, information about connected peers, etc) but +this is not yet documented and both the input and output may change +in the next release.</p> +</item> + + +</list> + +<p> +See <seealso marker="diameter_soc">Standards Compliance</seealso> for +standards-related issues.</p> +</section> + +</chapter> diff --git a/lib/diameter/doc/src/ref_man.xml b/lib/diameter/doc/src/ref_man.xml new file mode 100644 index 0000000000..137ce79094 --- /dev/null +++ b/lib/diameter/doc/src/ref_man.xml @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE application SYSTEM "application.dtd"> + +<application xmlns:xi="http://www.w3.org/2001/XInclude"> + +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Diameter Reference Manual</title> +<prepared></prepared> +<docno></docno> +<date></date> +<rev></rev> +<file>ref_man.xml</file> +</header> + +<description> +<p> +The Diameter application is a framework for building +applications on top of the Diameter protocol. </p> + +</description> + +<xi:include href="diameter.xml"/> +<xi:include href="diameter_compile.xml"/> +<xi:include href="diameter_app.xml"/> +<xi:include href="diameter_dict.xml"/> +<xi:include href="diameter_transport.xml"/> +<xi:include href="diameter_tcp.xml"/> +<xi:include href="diameter_sctp.xml"/> + +</application> diff --git a/lib/diameter/doc/src/user_man.xml b/lib/diameter/doc/src/user_man.xml new file mode 100644 index 0000000000..a6416c7e23 --- /dev/null +++ b/lib/diameter/doc/src/user_man.xml @@ -0,0 +1,44 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Diameter Users Guide</title> +<prepared></prepared> +<docno></docno> +<date></date> +<rev></rev> +<file>user_man.xml</file> +</header> +<description> + +<p> +The diameter application is a framework for building +applications on top of the Diameter protocol. </p> +</description> + +<xi:include href="diameter_intro.xml"/> +<xi:include href="diameter_using.xml"/> +<xi:include href="diameter_examples.xml"/> +<xi:include href="diameter_soc.xml"/> + +</part> diff --git a/lib/diameter/doc/standard/draft-ietf-dime-capablities-update-07.txt b/lib/diameter/doc/standard/draft-ietf-dime-capablities-update-07.txt new file mode 100644 index 0000000000..bb7ec2d08c --- /dev/null +++ b/lib/diameter/doc/standard/draft-ietf-dime-capablities-update-07.txt @@ -0,0 +1,392 @@ +
+
+
+Network Working Group K. Jiao
+Internet-Draft Huawei
+Intended status: Standards Track G. Zorn
+Expires: April 27, 2011 Network Zen
+ October 24, 2010
+
+
+ The Diameter Capabilities Update Application
+ draft-ietf-dime-capablities-update-07
+
+Abstract
+
+ This document defines a new Diameter application and associated
+ command codes. The Capabilities Update application is intended to
+ allow the dynamic update of certain Diameter peer capabilities while
+ the peer-to-peer connection is in the open state.
+
+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 April 27, 2011.
+
+Copyright Notice
+
+ Copyright (c) 2010 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
+ described in the Simplified BSD License.
+
+
+
+Jiao & Zorn Expires April 27, 2011 [Page 1]
+
+Internet-Draft Diameter Capabilities Update October 2010
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2. Specification of Requirements . . . . . . . . . . . . . . . . . 3
+ 3. Diameter Protocol Considerations . . . . . . . . . . . . . . . 3
+ 4. Capabilities Update . . . . . . . . . . . . . . . . . . . . . . 3
+ 4.1. Command-Code Values . . . . . . . . . . . . . . . . . . . . 4
+ 4.1.1. Capabilities-Update-Request . . . . . . . . . . . . . . 5
+ 4.1.2. Capabilities-Update-Answer . . . . . . . . . . . . . . 5
+ 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
+ 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6
+ 6.1. Application Identifier . . . . . . . . . . . . . . . . . . 6
+ 6.2. Command Codes . . . . . . . . . . . . . . . . . . . . . . . 6
+ 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 6
+ 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6
+ 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6
+ 9.1. Normative References . . . . . . . . . . . . . . . . . . . 6
+ 9.2. Informative References . . . . . . . . . . . . . . . . . . 7
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jiao & Zorn Expires April 27, 2011 [Page 2]
+
+Internet-Draft Diameter Capabilities Update October 2010
+
+
+1. Introduction
+
+ Capabilities exchange is an important component of the Diameter Base
+ Protocol [I-D.ietf-dime-rfc3588bis], allowing peers to exchange
+ identities and Diameter capabilities (protocol version number,
+ supported Diameter applications, security mechanisms, etc.). As
+ defined in RFC 3588, however, the capabilities exchange process takes
+ place only once, at the inception of a transport connection between a
+ given pair of peers. Therefore, if a peer's capabilities change (due
+ to software update, for example), the existing connection(s) must be
+ torn down (along with all of the associated user sessions) and
+ restarted before the modified capabilities can be advertised.
+
+ This document defines a new Diameter application intended to allow
+ the dynamic update of a subset of Diameter peer capabilities over an
+ existing connection. Because the Capabilities Update application
+ specified herein operates over an existing transport connection,
+ modification of certain capabilities is prohibited. Specifically,
+ modifying the security mechanism in use is not allowed; if the
+ security method used between a pair of peers is changed the affected
+ connection MUST be restarted.
+
+
+2. Specification of Requirements
+
+ 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 RFC 2119 [RFC2119].
+
+
+3. Diameter Protocol Considerations
+
+ This section details the relationship of the Diameter Capabilities
+ Update application to the Diameter Base Protocol.
+
+ This document specifies Diameter Application-ID <TBD1>. Diameter
+ nodes conforming to this specification MUST advertise support by
+ including the value <TBD1> in the Auth-Application-Id of the
+ Capabilities-Exchange-Request (CER) and Capabilities-Exchange-Answer
+ (CEA) commands [I-D.ietf-dime-rfc3588bis].
+
+
+4. Capabilities Update
+
+ When the capabilities of a Diameter node conforming to this
+ specification change, it MUST notify all of the nodes with which it
+ has an open transport connection and which have also advertised
+ support for the Capabilities Update application using the
+
+
+
+Jiao & Zorn Expires April 27, 2011 [Page 3]
+
+Internet-Draft Diameter Capabilities Update October 2010
+
+
+ Capabilities-Update-Request (CUR) message (Section 4.1.1). This
+ message allows the update of a peer's capabilities (supported
+ Diameter applications, etc.).
+
+ A Diameter node only issues a given command to those peers that have
+ advertised support for the Diameter application that defines the
+ command; a Diameter node must cache the supported applications in
+ order to ensure that unrecognized commands and/or Attribute-Value
+ Pairs (AVPs) are not unnecessarily sent to a peer.
+
+ The receiver of the CUR MUST determine common applications by
+ computing the intersection of its own set of supported Application Id
+ against all of the application identifier AVPs (Auth-Application-Id,
+ Acct-Application-Id and Vendor-Specific- Application-Id) present in
+ the CUR. The value of the Vendor-Id AVP in the Vendor-Specific-
+ Application-Id MUST NOT be used during computation.
+
+ If the receiver of a CUR does not have any applications in common
+ with the sender then it MUST return a Capabilities-Update-Answer
+ (CUA) (Section 4.1.2) with the Result-Code AVP set to
+ DIAMETER_NO_COMMON_APPLICATION [I-D.ietf-dime-rfc3588bis], and SHOULD
+ disconnect the transport layer connection; however, if active
+ sessions are using the connection, peers MAY delay disconnection
+ until the sessions can be redirected or gracefully terminated. Note
+ that receiving a CUA from a peer advertising itself as a Relay (see
+ [I-D.ietf-dime-rfc3588bis], Section 2.4) MUST be interpreted as
+ having common applications with the peer.
+
+ As for CER/CEA messages, the CUR and CUA messages MUST NOT be
+ proxied, redirected or relayed.
+
+ Even though the CUR/CUA messages cannot be proxied, it is still
+ possible for an upstream agent to receive a message for which there
+ are no peers available to handle the application that corresponds to
+ the Command-Code. This could happen if, for example, the peers are
+ too busy or down. In such instances, the 'E' bit MUST be set in the
+ answer message with the Result-Code AVP set to
+ DIAMETER_UNABLE_TO_DELIVER to inform the downstream peer to take
+ action (e.g., re-routing requests to an alternate peer).
+
+4.1. Command-Code Values
+
+ This section defines Command-Code [I-D.ietf-dime-rfc3588bis] values
+ that MUST be supported by all Diameter implementations conforming to
+ this specification. The following Command Codes are defined (using
+ modified ABNF [I-D.ietf-dime-rfc3588bis]) in this document:
+ Capabilities-Update-Request (CUR, Section 4.1.1) and Capabilities-
+ Update-Answer (CUA, Section 4.1.2).
+
+
+
+Jiao & Zorn Expires April 27, 2011 [Page 4]
+
+Internet-Draft Diameter Capabilities Update October 2010
+
+
+4.1.1. Capabilities-Update-Request
+
+ The Capabilities-Update-Request (CUR), indicated by the Command-Code
+ set to <CUCC> and the Command Flags' 'R' bit set, is sent to update
+ local capabilities. Upon detection of a transport failure, this
+ message MUST NOT be sent to an alternate peer.
+
+ When Diameter is run over the Stream Control Transmission Protocol
+ [RFC4960], which allows connections to span multiple interfaces and
+ multiple IP addresses, the Capabilities-Update-Request message MUST
+ contain one Host-IP-Address AVP for each potential IP address that
+ may be locally used when transmitting Diameter messages.
+
+ Message Format
+
+ <CUR> ::= < Diameter Header: <CUCC>, REQ >
+ { Origin-Host }
+ { Origin-Realm }
+ 1* { Host-IP-Address }
+ { Vendor-Id }
+ { Product-Name }
+ [ Origin-State-Id ]
+ * [ Supported-Vendor-Id ]
+ * [ Auth-Application-Id ]
+ * [ Acct-Application-Id ]
+ * [ Vendor-Specific-Application-Id ]
+ [ Firmware-Revision ]
+ * [ AVP ]
+
+4.1.2. Capabilities-Update-Answer
+
+ The Capabilities-Update-Answer, indicated by the Command-Code set to
+ <CUCC> and the Command Flags' 'R' bit cleared, is sent in response to
+ a CUR message.
+
+ Message Format
+
+ <CUA> ::= < Diameter Header: <CUCC> >
+ { Origin-Host }
+ { Origin-Realm }
+ { Result-Code }
+ [ Error-Message ]
+ * [ AVP ]
+
+
+
+
+
+
+
+
+Jiao & Zorn Expires April 27, 2011 [Page 5]
+
+Internet-Draft Diameter Capabilities Update October 2010
+
+
+5. Security Considerations
+
+ The security considerations applicable to the Diameter Base Protocol
+ [I-D.ietf-dime-rfc3588bis] are also applicable to this document.
+
+
+6. IANA Considerations
+
+ This section explains the criteria to be used by the IANA for
+ assignment of numbers within namespaces used within this document.
+
+6.1. Application Identifier
+
+ This specification assigns the value <TBD1> from the Application
+ Identifiers namespace [I-D.ietf-dime-rfc3588bis]. See Section 3 for
+ the assignment of the namespace in this specification.
+
+6.2. Command Codes
+
+ This specification assigns the value <CUCC> from the Command Codes
+ namespace [I-D.ietf-dime-rfc3588bis]. See Section 4.1 for the
+ assignment of the namespace in this specification.
+
+
+7. Contributors
+
+ This document is based upon work done by Tina Tsou.
+
+
+8. Acknowledgements
+
+ Thanks to Sebastien Decugis, Niklas Neumann, Subash Comerica, Lionel
+ Morand, Dan Romascanu, Dan Harkins and Ravi for helpful review and
+ discussion.
+
+
+9. References
+
+9.1. Normative References
+
+ [I-D.ietf-dime-rfc3588bis]
+ Fajardo, V., Arkko, J., Loughney, J., and G. Zorn,
+ "Diameter Base Protocol", draft-ietf-dime-rfc3588bis-25
+ (work in progress), September 2010.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+
+
+
+Jiao & Zorn Expires April 27, 2011 [Page 6]
+
+Internet-Draft Diameter Capabilities Update October 2010
+
+
+9.2. Informative References
+
+ [RFC4960] Stewart, R., "Stream Control Transmission Protocol",
+ RFC 4960, September 2007.
+
+
+Authors' Addresses
+
+ Jiao Kang
+ Huawei Technologies
+ Section B1, Huawei Industrial Base
+ Bantian, Longgang District
+ Shenzhen 518129
+ P.R. China
+
+ Phone: +86 755 2878-6690
+ Email: [email protected]
+
+
+ Glen Zorn
+ Network Zen
+ 227/358 Thanon Sanphawut
+ Bang Na, Bangkok 10260
+ Thailand
+
+ Phone: +66 (0) 87-040-4617
+ Email: [email protected]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jiao & Zorn Expires April 27, 2011 [Page 7]
+
diff --git a/lib/diameter/doc/standard/draft-ietf-dime-rfc3588bis-26.txt b/lib/diameter/doc/standard/draft-ietf-dime-rfc3588bis-26.txt new file mode 100644 index 0000000000..87b9562f93 --- /dev/null +++ b/lib/diameter/doc/standard/draft-ietf-dime-rfc3588bis-26.txt @@ -0,0 +1,8681 @@ + + + +DIME V. Fajardo, Ed. +Internet-Draft Telcordia Technologies +Obsoletes: 3588 (if approved) J. Arkko +Intended status: Standards Track Ericsson Research +Expires: July 24, 2011 J. Loughney + Nokia Research Center + G. Zorn + Network Zen + January 20, 2011 + + + Diameter Base Protocol + draft-ietf-dime-rfc3588bis-26.txt + +Abstract + + The Diameter base protocol is intended to provide an Authentication, + Authorization and Accounting (AAA) framework for applications such as + network access or IP mobility in both local and roaming situations. + This document specifies the message format, transport, error + reporting, accounting and security services used by all Diameter + applications. The Diameter base protocol as defined in this document + must be supported by all Diameter implementations. + +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 July 24, 2011. + +Copyright Notice + + Copyright (c) 2011 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 + + + +Fajardo, et al. Expires July 24, 2011 [Page 1] + +Internet-Draft Diameter Base Protocol January 2011 + + + (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 + described in the Simplified BSD License. + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 + 1.1. Diameter Protocol . . . . . . . . . . . . . . . . . . . . 8 + 1.1.1. Description of the Document Set . . . . . . . . . . . 9 + 1.1.2. Conventions Used in This Document . . . . . . . . . . 10 + 1.1.3. Changes from RFC3588 . . . . . . . . . . . . . . . . 10 + 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 12 + 1.3. Approach to Extensibility . . . . . . . . . . . . . . . . 17 + 1.3.1. Defining New AVP Values . . . . . . . . . . . . . . . 18 + 1.3.2. Creating New AVPs . . . . . . . . . . . . . . . . . . 18 + 1.3.3. Creating New Commands . . . . . . . . . . . . . . . . 18 + 1.3.4. Creating New Diameter Applications . . . . . . . . . 19 + 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 21 + 2.1. Transport . . . . . . . . . . . . . . . . . . . . . . . . 22 + 2.1.1. SCTP Guidelines . . . . . . . . . . . . . . . . . . . 23 + 2.2. Securing Diameter Messages . . . . . . . . . . . . . . . 24 + 2.3. Diameter Application Compliance . . . . . . . . . . . . . 24 + 2.4. Application Identifiers . . . . . . . . . . . . . . . . . 24 + 2.5. Connections vs. Sessions . . . . . . . . . . . . . . . . 25 + 2.6. Peer Table . . . . . . . . . . . . . . . . . . . . . . . 26 + 2.7. Routing Table . . . . . . . . . . . . . . . . . . . . . . 27 + 2.8. Role of Diameter Agents . . . . . . . . . . . . . . . . . 28 + 2.8.1. Relay Agents . . . . . . . . . . . . . . . . . . . . 29 + 2.8.2. Proxy Agents . . . . . . . . . . . . . . . . . . . . 30 + 2.8.3. Redirect Agents . . . . . . . . . . . . . . . . . . . 31 + 2.8.4. Translation Agents . . . . . . . . . . . . . . . . . 32 + 2.9. Diameter Path Authorization . . . . . . . . . . . . . . . 33 + 3. Diameter Header . . . . . . . . . . . . . . . . . . . . . . . 35 + 3.1. Command Codes . . . . . . . . . . . . . . . . . . . . . . 38 + 3.2. Command Code ABNF specification . . . . . . . . . . . . . 38 + 3.3. Diameter Command Naming Conventions . . . . . . . . . . . 41 + 4. Diameter AVPs . . . . . . . . . . . . . . . . . . . . . . . . 42 + 4.1. AVP Header . . . . . . . . . . . . . . . . . . . . . . . 42 + 4.1.1. Optional Header Elements . . . . . . . . . . . . . . 43 + 4.2. Basic AVP Data Formats . . . . . . . . . . . . . . . . . 44 + 4.3. Derived AVP Data Formats . . . . . . . . . . . . . . . . 45 + 4.3.1. Common Derived AVPs . . . . . . . . . . . . . . . . . 45 + 4.4. Grouped AVP Values . . . . . . . . . . . . . . . . . . . 52 + + + +Fajardo, et al. Expires July 24, 2011 [Page 2] + +Internet-Draft Diameter Base Protocol January 2011 + + + 4.4.1. Example AVP with a Grouped Data type . . . . . . . . 53 + 4.5. Diameter Base Protocol AVPs . . . . . . . . . . . . . . . 56 + 5. Diameter Peers . . . . . . . . . . . . . . . . . . . . . . . 59 + 5.1. Peer Connections . . . . . . . . . . . . . . . . . . . . 59 + 5.2. Diameter Peer Discovery . . . . . . . . . . . . . . . . . 60 + 5.3. Capabilities Exchange . . . . . . . . . . . . . . . . . . 61 + 5.3.1. Capabilities-Exchange-Request . . . . . . . . . . . . 63 + 5.3.2. Capabilities-Exchange-Answer . . . . . . . . . . . . 63 + 5.3.3. Vendor-Id AVP . . . . . . . . . . . . . . . . . . . . 64 + 5.3.4. Firmware-Revision AVP . . . . . . . . . . . . . . . . 64 + 5.3.5. Host-IP-Address AVP . . . . . . . . . . . . . . . . . 64 + 5.3.6. Supported-Vendor-Id AVP . . . . . . . . . . . . . . . 65 + 5.3.7. Product-Name AVP . . . . . . . . . . . . . . . . . . 65 + 5.4. Disconnecting Peer connections . . . . . . . . . . . . . 65 + 5.4.1. Disconnect-Peer-Request . . . . . . . . . . . . . . . 66 + 5.4.2. Disconnect-Peer-Answer . . . . . . . . . . . . . . . 66 + 5.4.3. Disconnect-Cause AVP . . . . . . . . . . . . . . . . 66 + 5.5. Transport Failure Detection . . . . . . . . . . . . . . . 67 + 5.5.1. Device-Watchdog-Request . . . . . . . . . . . . . . . 67 + 5.5.2. Device-Watchdog-Answer . . . . . . . . . . . . . . . 67 + 5.5.3. Transport Failure Algorithm . . . . . . . . . . . . . 68 + 5.5.4. Failover and Failback Procedures . . . . . . . . . . 68 + 5.6. Peer State Machine . . . . . . . . . . . . . . . . . . . 69 + 5.6.1. Incoming connections . . . . . . . . . . . . . . . . 71 + 5.6.2. Events . . . . . . . . . . . . . . . . . . . . . . . 72 + 5.6.3. Actions . . . . . . . . . . . . . . . . . . . . . . . 73 + 5.6.4. The Election Process . . . . . . . . . . . . . . . . 75 + 6. Diameter message processing . . . . . . . . . . . . . . . . . 76 + 6.1. Diameter Request Routing Overview . . . . . . . . . . . . 76 + 6.1.1. Originating a Request . . . . . . . . . . . . . . . . 77 + 6.1.2. Sending a Request . . . . . . . . . . . . . . . . . . 77 + 6.1.3. Receiving Requests . . . . . . . . . . . . . . . . . 78 + 6.1.4. Processing Local Requests . . . . . . . . . . . . . . 78 + 6.1.5. Request Forwarding . . . . . . . . . . . . . . . . . 78 + 6.1.6. Request Routing . . . . . . . . . . . . . . . . . . . 78 + 6.1.7. Predictive Loop Avoidance . . . . . . . . . . . . . . 79 + 6.1.8. Redirecting Requests . . . . . . . . . . . . . . . . 79 + 6.1.9. Relaying and Proxying Requests . . . . . . . . . . . 80 + 6.2. Diameter Answer Processing . . . . . . . . . . . . . . . 82 + 6.2.1. Processing received Answers . . . . . . . . . . . . . 82 + 6.2.2. Relaying and Proxying Answers . . . . . . . . . . . . 82 + 6.3. Origin-Host AVP . . . . . . . . . . . . . . . . . . . . . 83 + 6.4. Origin-Realm AVP . . . . . . . . . . . . . . . . . . . . 83 + 6.5. Destination-Host AVP . . . . . . . . . . . . . . . . . . 83 + 6.6. Destination-Realm AVP . . . . . . . . . . . . . . . . . . 84 + 6.7. Routing AVPs . . . . . . . . . . . . . . . . . . . . . . 84 + 6.7.1. Route-Record AVP . . . . . . . . . . . . . . . . . . 84 + 6.7.2. Proxy-Info AVP . . . . . . . . . . . . . . . . . . . 84 + + + +Fajardo, et al. Expires July 24, 2011 [Page 3] + +Internet-Draft Diameter Base Protocol January 2011 + + + 6.7.3. Proxy-Host AVP . . . . . . . . . . . . . . . . . . . 85 + 6.7.4. Proxy-State AVP . . . . . . . . . . . . . . . . . . . 85 + 6.8. Auth-Application-Id AVP . . . . . . . . . . . . . . . . . 85 + 6.9. Acct-Application-Id AVP . . . . . . . . . . . . . . . . . 85 + 6.10. Inband-Security-Id AVP . . . . . . . . . . . . . . . . . 85 + 6.11. Vendor-Specific-Application-Id AVP . . . . . . . . . . . 86 + 6.12. Redirect-Host AVP . . . . . . . . . . . . . . . . . . . . 87 + 6.13. Redirect-Host-Usage AVP . . . . . . . . . . . . . . . . . 87 + 6.14. Redirect-Max-Cache-Time AVP . . . . . . . . . . . . . . . 88 + 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 90 + 7.1. Result-Code AVP . . . . . . . . . . . . . . . . . . . . . 92 + 7.1.1. Informational . . . . . . . . . . . . . . . . . . . . 92 + 7.1.2. Success . . . . . . . . . . . . . . . . . . . . . . . 93 + 7.1.3. Protocol Errors . . . . . . . . . . . . . . . . . . . 93 + 7.1.4. Transient Failures . . . . . . . . . . . . . . . . . 94 + 7.1.5. Permanent Failures . . . . . . . . . . . . . . . . . 95 + 7.2. Error Bit . . . . . . . . . . . . . . . . . . . . . . . . 98 + 7.3. Error-Message AVP . . . . . . . . . . . . . . . . . . . . 99 + 7.4. Error-Reporting-Host AVP . . . . . . . . . . . . . . . . 99 + 7.5. Failed-AVP AVP . . . . . . . . . . . . . . . . . . . . . 99 + 7.6. Experimental-Result AVP . . . . . . . . . . . . . . . . . 100 + 7.7. Experimental-Result-Code AVP . . . . . . . . . . . . . . 100 + 8. Diameter User Sessions . . . . . . . . . . . . . . . . . . . 101 + 8.1. Authorization Session State Machine . . . . . . . . . . . 102 + 8.2. Accounting Session State Machine . . . . . . . . . . . . 107 + 8.3. Server-Initiated Re-Auth . . . . . . . . . . . . . . . . 112 + 8.3.1. Re-Auth-Request . . . . . . . . . . . . . . . . . . . 112 + 8.3.2. Re-Auth-Answer . . . . . . . . . . . . . . . . . . . 113 + 8.4. Session Termination . . . . . . . . . . . . . . . . . . . 114 + 8.4.1. Session-Termination-Request . . . . . . . . . . . . . 115 + 8.4.2. Session-Termination-Answer . . . . . . . . . . . . . 115 + 8.5. Aborting a Session . . . . . . . . . . . . . . . . . . . 116 + 8.5.1. Abort-Session-Request . . . . . . . . . . . . . . . . 116 + 8.5.2. Abort-Session-Answer . . . . . . . . . . . . . . . . 117 + 8.6. Inferring Session Termination from Origin-State-Id . . . 118 + 8.7. Auth-Request-Type AVP . . . . . . . . . . . . . . . . . . 118 + 8.8. Session-Id AVP . . . . . . . . . . . . . . . . . . . . . 119 + 8.9. Authorization-Lifetime AVP . . . . . . . . . . . . . . . 120 + 8.10. Auth-Grace-Period AVP . . . . . . . . . . . . . . . . . . 121 + 8.11. Auth-Session-State AVP . . . . . . . . . . . . . . . . . 121 + 8.12. Re-Auth-Request-Type AVP . . . . . . . . . . . . . . . . 121 + 8.13. Session-Timeout AVP . . . . . . . . . . . . . . . . . . . 122 + 8.14. User-Name AVP . . . . . . . . . . . . . . . . . . . . . . 122 + 8.15. Termination-Cause AVP . . . . . . . . . . . . . . . . . . 122 + 8.16. Origin-State-Id AVP . . . . . . . . . . . . . . . . . . . 124 + 8.17. Session-Binding AVP . . . . . . . . . . . . . . . . . . . 124 + 8.18. Session-Server-Failover AVP . . . . . . . . . . . . . . . 125 + 8.19. Multi-Round-Time-Out AVP . . . . . . . . . . . . . . . . 126 + + + +Fajardo, et al. Expires July 24, 2011 [Page 4] + +Internet-Draft Diameter Base Protocol January 2011 + + + 8.20. Class AVP . . . . . . . . . . . . . . . . . . . . . . . . 126 + 8.21. Event-Timestamp AVP . . . . . . . . . . . . . . . . . . . 126 + 9. Accounting . . . . . . . . . . . . . . . . . . . . . . . . . 127 + 9.1. Server Directed Model . . . . . . . . . . . . . . . . . . 127 + 9.2. Protocol Messages . . . . . . . . . . . . . . . . . . . . 128 + 9.3. Accounting Application Extension and Requirements . . . . 128 + 9.4. Fault Resilience . . . . . . . . . . . . . . . . . . . . 129 + 9.5. Accounting Records . . . . . . . . . . . . . . . . . . . 129 + 9.6. Correlation of Accounting Records . . . . . . . . . . . . 130 + 9.7. Accounting Command-Codes . . . . . . . . . . . . . . . . 131 + 9.7.1. Accounting-Request . . . . . . . . . . . . . . . . . 131 + 9.7.2. Accounting-Answer . . . . . . . . . . . . . . . . . . 132 + 9.8. Accounting AVPs . . . . . . . . . . . . . . . . . . . . . 133 + 9.8.1. Accounting-Record-Type AVP . . . . . . . . . . . . . 133 + 9.8.2. Acct-Interim-Interval AVP . . . . . . . . . . . . . . 134 + 9.8.3. Accounting-Record-Number AVP . . . . . . . . . . . . 135 + 9.8.4. Acct-Session-Id AVP . . . . . . . . . . . . . . . . . 135 + 9.8.5. Acct-Multi-Session-Id AVP . . . . . . . . . . . . . . 135 + 9.8.6. Accounting-Sub-Session-Id AVP . . . . . . . . . . . . 135 + 9.8.7. Accounting-Realtime-Required AVP . . . . . . . . . . 136 + 10. AVP Occurrence Table . . . . . . . . . . . . . . . . . . . . 137 + 10.1. Base Protocol Command AVP Table . . . . . . . . . . . . . 137 + 10.2. Accounting AVP Table . . . . . . . . . . . . . . . . . . 138 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 140 + 11.1. Changes to AVP Header Allocation . . . . . . . . . . . . 140 + 11.2. Diameter Header . . . . . . . . . . . . . . . . . . . . . 140 + 11.3. AVP Values . . . . . . . . . . . . . . . . . . . . . . . 140 + 11.3.1. Experimental-Result-Code AVP . . . . . . . . . . . . 140 + 11.4. Diameter TCP, SCTP, TLS/TCP and DTLS/SCTP Port Numbers . 141 + 11.5. S-NAPTR Parameters . . . . . . . . . . . . . . . . . . . 141 + 12. Diameter protocol related configurable parameters . . . . . . 142 + 13. Security Considerations . . . . . . . . . . . . . . . . . . . 143 + 13.1. TLS/TCP and DTLS/SCTP Usage . . . . . . . . . . . . . . . 143 + 13.2. Peer-to-Peer Considerations . . . . . . . . . . . . . . . 144 + 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 145 + 14.1. Normative References . . . . . . . . . . . . . . . . . . 145 + 14.2. Informational References . . . . . . . . . . . . . . . . 147 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 149 + A.1. RFC3588bis . . . . . . . . . . . . . . . . . . . . . . . 149 + A.2. RFC3588 . . . . . . . . . . . . . . . . . . . . . . . . . 150 + Appendix B. S-NAPTR Example . . . . . . . . . . . . . . . . . . 151 + Appendix C. Duplicate Detection . . . . . . . . . . . . . . . . 152 + Appendix D. Internationalized Domain Names . . . . . . . . . . . 154 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 155 + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 5] + +Internet-Draft Diameter Base Protocol January 2011 + + +1. Introduction + + Authentication, Authorization and Accounting (AAA) protocols such as + TACACS [RFC1492] and RADIUS [RFC2865] were initially deployed to + provide dial-up PPP [RFC1661] and terminal server access. Over time, + AAA support was needed on many new access technologies, the scale and + complexity of AAA networks grew, and AAA was also used on new + applications (such as voice over IP). This lead to new demands on + AAA protocols. + + Network access requirements for AAA protocols are summarized in + [RFC2989]. These include: + + + Failover + + [RFC2865] does not define failover mechanisms, and as a result, + failover behavior differs between implementations. In order to + provide well-defined failover behavior, Diameter supports + application-layer acknowledgements, and defines failover + algorithms and the associated state machine. This is described in + Section 5.5 and [RFC3539]. + + Transmission-level security + + [RFC2865] defines an application-layer authentication and + integrity scheme that is required only for use with Response + packets. While [RFC2869] defines an additional authentication and + integrity mechanism, use is only required during Extensible + Authentication Protocol (EAP) sessions. While attribute-hiding is + supported, [RFC2865] does not provide support for per-packet + confidentiality. In accounting, [RFC2866] assumes that replay + protection is provided by the backend billing server, rather than + within the protocol itself. + + While [RFC3162] defines the use of IPsec with RADIUS, support for + IPsec is not required. In order to provide universal support for + transmission-level security, and enable both intra- and inter- + domain AAA deployments, Diameter provides support for TLS/TCP and + DTLS/SCTP. Security is discussed in Section 13. + + + Reliable transport + + + RADIUS runs over UDP, and does not define retransmission behavior; + as a result, reliability varies between implementations. As + described in [RFC2975], this is a major issue in accounting, where + + + +Fajardo, et al. Expires July 24, 2011 [Page 6] + +Internet-Draft Diameter Base Protocol January 2011 + + + packet loss may translate directly into revenue loss. In order to + provide well defined transport behavior, Diameter runs over + reliable transport mechanisms (TCP, SCTP) as defined in [RFC3539]. + + + Agent support + + [RFC2865] does not provide for explicit support for agents, + including Proxies, Redirects and Relays. Since the expected + behavior is not defined, it varies between implementations. + Diameter defines agent behavior explicitly; this is described in + Section 2.8. + + + Server-initiated messages + + While RADIUS server-initiated messages are defined in [RFC5176], + support is optional. This makes it difficult to implement + features such as unsolicited disconnect or re-authentication/ + re-authorization on demand across a heterogeneous deployment. To + tackle this issue, support for server-initiated messages is + mandatory in Diameter. + + + Transition support + + While Diameter does not share a common protocol data unit (PDU) + with RADIUS, considerable effort has been expended in enabling + backward compatibility with RADIUS, so that the two protocols may + be deployed in the same network. Initially, it is expected that + Diameter will be deployed within new network devices, as well as + within gateways enabling communication between legacy RADIUS + devices and Diameter agents. This capability enables Diameter + support to be added to legacy networks, by addition of a gateway + or server speaking both RADIUS and Diameter. + + In addition to addressing the above requirements, Diameter also + provides support for the following: + + + Capability negotiation + + RADIUS does not support error messages, capability negotiation, or + a mandatory/non-mandatory flag for attributes. Since RADIUS + clients and servers are not aware of each other's capabilities, + they may not be able to successfully negotiate a mutually + acceptable service, or in some cases, even be aware of what + service has been implemented. Diameter includes support for error + + + +Fajardo, et al. Expires July 24, 2011 [Page 7] + +Internet-Draft Diameter Base Protocol January 2011 + + + handling (Section 7), capability negotiation (Section 5.3), and + mandatory/non-mandatory Attribute-Value Pairs (AVPs) (Section + 4.1). + + + Peer discovery and configuration + + RADIUS implementations typically require that the name or address + of servers or clients be manually configured, along with the + corresponding shared secrets. This results in a large + administrative burden, and creates the temptation to reuse the + RADIUS shared secret, which can result in major security + vulnerabilities if the Request Authenticator is not globally and + temporally unique as required in [RFC2865]. Through DNS, Diameter + enables dynamic discovery of peers (see Section 5.2). Derivation + of dynamic session keys is enabled via transmission-level + security. + + + Over time, the capabilities of Network Access Server (NAS) devices + have increased substantially. As a result, while Diameter is a + considerably more sophisticated protocol than RADIUS, it remains + feasible to implement it within embedded devices. + +1.1. Diameter Protocol + + The Diameter base protocol provides the following facilities: + + o Ability to exchange messages and deliver AVPs + + o Capabilities negotiation + + o Error notification + + o Extensibility, through addition of new applications, commands and + AVPs (required in [RFC2989]). + + o Basic services necessary for applications, such as handling of + user sessions or accounting + + All data delivered by the protocol is in the form of AVPs. Some of + these AVP values are used by the Diameter protocol itself, while + others deliver data associated with particular applications that + employ Diameter. AVPs may be arbitrarily added to Diameter messages, + the only restriction being that the Augmented Backus-Naur Form (ABNF, + [RFC5234]) Command Code syntax specification (Section 3.2) is + satisfied. AVPs are used by the base Diameter protocol to support + the following required features: + + + +Fajardo, et al. Expires July 24, 2011 [Page 8] + +Internet-Draft Diameter Base Protocol January 2011 + + + o Transporting of user authentication information, for the purposes + of enabling the Diameter server to authenticate the user. + + o Transporting of service-specific authorization information, + between client and servers, allowing the peers to decide whether a + user's access request should be granted. + + o Exchanging resource usage information, which may be used for + accounting purposes, capacity planning, etc. + + o Routing, relaying, proxying and redirecting of Diameter messages + through a server hierarchy. + + The Diameter base protocol satisfies the minimum requirements for an + AAA protocol, as specified by [RFC2989]. The base protocol may be + used by itself for accounting purposes only, or it may be used with a + Diameter application, such as Mobile IPv4 [RFC4004], or network + access [RFC4005]. It is also possible for the base protocol to be + extended for use in new applications, via the addition of new + commands or AVPs. The initial focus of Diameter was network access + and accounting applications. A truly generic AAA protocol used by + many applications might provide functionality not provided by + Diameter. Therefore, it is imperative that the designers of new + applications understand their requirements before using Diameter. + See Section 2.4 for more information on Diameter applications. + + Any node can initiate a request. In that sense, Diameter is a peer- + to-peer protocol. In this document, a Diameter Client is a device at + the edge of the network that performs access control, such as a + Network Access Server (NAS) or a Foreign Agent (FA). A Diameter + client generates Diameter messages to request authentication, + authorization, and accounting services for the user. A Diameter + agent is a node that does not provide local user authentication or + authorization services; agents include proxies, redirects and relay + agents. A Diameter server performs authentication and/or + authorization of the user. A Diameter node may act as an agent for + certain requests while acting as a server for others. + + The Diameter protocol also supports server-initiated messages, such + as a request to abort service to a particular user. + +1.1.1. Description of the Document Set + + The Diameter specification consists of an updated version of the base + protocol specification (this document) and the Transport Profile + [RFC3539]. This document obsoletes RFC 3588. A summary of the base + protocol updates included in this document can be found in + Section 1.1.3. + + + +Fajardo, et al. Expires July 24, 2011 [Page 9] + +Internet-Draft Diameter Base Protocol January 2011 + + + This document defines the base protocol specification for AAA, which + includes support for accounting. There are also a myriad of + applications documents describing applications that use this base + specification for Authentication, Authorization and Accounting. + These application documents specify how to use the Diameter protocol + within the context of their application. + + The Transport Profile document [RFC3539] discusses transport layer + issues that arise with AAA protocols and recommendations on how to + overcome these issues. This document also defines the Diameter + failover algorithm and state machine. + + Clarifications on the Routing of Diameter Request based on Username + and the Realm [RFC5729] defines specific behavior on how to route + request based on the content of the User-Name AVP (Attribute Value + Pair). + +1.1.2. Conventions Used in This Document + + 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 [RFC2119]. + +1.1.3. Changes from RFC3588 + + This document obsoletes RFC 3588 but is fully backward compatible + with that document. The changes introduced in this document focus on + fixing issues that have surfaced during implementation of [RFC3588]. + An overview of some the major changes are given below. + + o Deprecated the use of Inband-Security AVP for negotiating + transport layer security. It has been generally considered that + bootstrapping of TLS via Inband-Security AVP creates certain + security risk because it does not completely protect the + information carried in the CER (Capabilities Exchange Request)/CEA + (Capabilities Exchange Answer). This version of Diameter adopted + a common approach of defining a well-known secured port that peers + should use when communicating via TLS/TCP and DTLS/SCTP. This new + approach augments the existing Inband-Security negotiation but + does not completely replace it. The old method is kept for + backwards compatibility reasons. + + o Deprecated the exchange of CER/CEA messages in the open state. + This feature was implied in the peer state machine table of + [RFC3588] but it was not clearly defined anywhere else in that + document. As work on this document progressed, it became clear + that the multiplicity of meaning and use of Application Id AVPs in + the CER/CEA messages (and the messages themselves) is seen as an + + + +Fajardo, et al. Expires July 24, 2011 [Page 10] + +Internet-Draft Diameter Base Protocol January 2011 + + + abuse of the Diameter extensibility rules and thus required + simplification. It is assumed that the capabilities exchange in + the open state will be re-introduced in a separate specification + which clearly defines new commands for this feature. + + o Simplified Security Requirements. The use of a secured transport + for exchanging Diameter messages remains mandatory. However, TLS/ + TCP and DTLS/SCTP has become the primary method of securing + Diameter and IPsec is a secondary alternative. See Section 13 for + details. The support for the End-to-End security framework + (E2ESequence AVP and 'P'-bit in the AVP header) has also been + deprecated. + + o Diameter Extensibility Changes. This includes fixes to the + Diameter extensibility description (Section 1.3 and others) to + better aid Diameter application designers; in addition, the new + specification relaxes the policy with respect to the allocation of + command codes for vendor-specific uses. + + o Application Id Usage. Clarify the proper use of Application Id + information which can be found in multiple places within a + Diameter message. This includes correlating Application Ids found + in the message headers and AVPs. These changes also clearly + specify the proper Application Id value to use for specific base + protocol messages (ASR/ASA, STR/STA) as well as clarifying the + content and use of Vendor-Specific-Application-Id. + + o Routing Fixes. This document more clearly specifies what + information (AVPs and Application Id) can be used for making + general routing decisions. A rule for the prioritization of + redirect routing criteria when multiple route entries are found + via redirects has also been added (See Section 6.13 for details). + + o Simplification of Diameter Peer Discovery. The Diameter discovery + process now supports only widely used discovery schemes; the rest + have been deprecated (see Section 5.2 for details). + + There are many other many miscellaneous fixes that have been + introduced in this document that may not be considered significant + but they are important nonetheless. Examples are removal of obsolete + types, fixes to command ABNFs, fixes to the state machine, + clarification of the election process, message validation, fixes to + Failed-AVP and Result-Code AVP values, etc. A comprehensive list of + changes is not shown here for practical reasons. + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 11] + +Internet-Draft Diameter Base Protocol January 2011 + + +1.2. Terminology + + AAA + + Authentication, Authorization and Accounting. + + + ABNF + + Augmented Backus-Naur Form [RFC5234]. A metalanguage with its own + formal syntax and rules. It is based on the Backus-Naur Form and + is used to define message exchanges in a bi-directional + communications protocol. + + + Accounting + + The act of collecting information on resource usage for the + purpose of capacity planning, auditing, billing or cost + allocation. + + + Accounting Record + + An accounting record represents a summary of the resource + consumption of a user over the entire session. Accounting servers + creating the accounting record may do so by processing interim + accounting events or accounting events from several devices + serving the same user. + + + Authentication + + The act of verifying the identity of an entity (subject). + + + Authorization + + The act of determining whether a requesting entity (subject) will + be allowed access to a resource (object). + + + AVP + + The Diameter protocol consists of a header followed by one or more + Attribute-Value-Pairs (AVPs). An AVP includes a header and is + used to encapsulate protocol-specific data (e.g., routing + information) as well as authentication, authorization or + + + +Fajardo, et al. Expires July 24, 2011 [Page 12] + +Internet-Draft Diameter Base Protocol January 2011 + + + accounting information. + + + Diameter Agent + + A Diameter Agent is a Diameter Node that provides either relay, + proxy, redirect or translation services. + + + Diameter Client + + A Diameter Client is a Diameter Node that supports Diameter client + applications as well as the base protocol. Diameter Clients are + often implemented in devices situated at the edge of a network and + provide access control services for that network. Typical + examples of Diameter Clients include the Network Access Server + (NAS) and the Mobile IP Foreign Agent (FA). + + + Diameter Node + + A Diameter Node is a host process that implements the Diameter + protocol, and acts either as a Client, Agent or Server. + + + Diameter Peer + + If a Diameter Node shares a direct transport connection with + another Diameter Node, it is a Diameter Peer to that Diameter + Node. + + + Diameter Server + + A Diameter Server is a Diameter Node that handles authentication, + authorization and accounting requests for a particular realm. By + its very nature, a Diameter Server must support Diameter server + applications in addition to the base protocol. + + + Downstream + + Downstream is used to identify the direction of a particular + Diameter message from the Home Server towards the Diameter Client. + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 13] + +Internet-Draft Diameter Base Protocol January 2011 + + + Home Realm + + A Home Realm is the administrative domain with which the user + maintains an account relationship. + + + Home Server + + A Diameter Server which serves the Home Realm. + + + Interim accounting + + An interim accounting message provides a snapshot of usage during + a user's session. It is typically implemented in order to provide + for partial accounting of a user's session in the case a device + reboot or other network problem prevents the delivery of a session + summary message or session record. + + + Local Realm + + A local realm is the administrative domain providing services to a + user. An administrative domain may act as a local realm for + certain users, while being a home realm for others. + + + Multi-session + + A multi-session represents a logical linking of several sessions. + Multi-sessions are tracked by using the Acct-Multi-Session-Id. An + example of a multi-session would be a Multi-link PPP bundle. Each + leg of the bundle would be a session while the entire bundle would + be a multi-session. + + + Network Access Identifier + + The Network Access Identifier, or NAI [RFC4282], is used in the + Diameter protocol to extract a user's identity and realm. The + identity is used to identify the user during authentication and/or + authorization, while the realm is used for message routing + purposes. + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 14] + +Internet-Draft Diameter Base Protocol January 2011 + + + Proxy Agent or Proxy + + In addition to forwarding requests and responses, proxies make + policy decisions relating to resource usage and provisioning. + This is typically accomplished by tracking the state of NAS + devices. While proxies typically do not respond to client + Requests prior to receiving a Response from the server, they may + originate Reject messages in cases where policies are violated. + As a result, proxies need to understand the semantics of the + messages passing through them, and may not support all Diameter + applications. + + + Realm + + The string in the NAI that immediately follows the '@' character. + NAI realm names are required to be unique, and are piggybacked on + the administration of the DNS namespace. Diameter makes use of + the realm, also loosely referred to as domain, to determine + whether messages can be satisfied locally, or whether they must be + routed or redirected. In RADIUS, realm names are not necessarily + piggybacked on the DNS namespace but may be independent of it. + + + Real-time Accounting + + Real-time accounting involves the processing of information on + resource usage within a defined time window. Time constraints are + typically imposed in order to limit financial risk. The Diameter + Credit Control Application [RFC4006] is an example of an + application that defines real-time accounting functionality. + + + Relay Agent or Relay + + Relays forward requests and responses based on routing-related + AVPs and routing table entries. Since relays do not make policy + decisions, they do not examine or alter non-routing AVPs. As a + result, relays never originate messages, do not need to understand + the semantics of messages or non-routing AVPs, and are capable of + handling any Diameter application or message type. Since relays + make decisions based on information in routing AVPs and realm + forwarding tables they do not keep state on NAS resource usage or + sessions in progress. + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 15] + +Internet-Draft Diameter Base Protocol January 2011 + + + Redirect Agent + + Rather than forwarding requests and responses between clients and + servers, redirect agents refer clients to servers and allow them + to communicate directly. Since redirect agents do not sit in the + forwarding path, they do not alter any AVPs transiting between + client and server. Redirect agents do not originate messages and + are capable of handling any message type, although they may be + configured only to redirect messages of certain types, while + acting as relay or proxy agents for other types. As with proxy + agents, redirect agents do not keep state with respect to sessions + or NAS resources. + + + Session + + A session is a related progression of events devoted to a + particular activity. Diameter application documents provide + guidelines as to when a session begins and ends. All Diameter + packets with the same Session-Id are considered to be part of the + same session. + + + Stateful Agent + + A stateful agent is one that maintains session state information, + by keeping track of all authorized active sessions. Each + authorized session is bound to a particular service, and its state + is considered active either until it is notified otherwise, or by + expiration. + + + Sub-session + + A sub-session represents a distinct service (e.g., QoS or data + characteristics) provided to a given session. These services may + happen concurrently (e.g., simultaneous voice and data transfer + during the same session) or serially. These changes in sessions + are tracked with the Accounting-Sub-Session-Id. + + + Transaction state + + The Diameter protocol requires that agents maintain transaction + state, which is used for failover purposes. Transaction state + implies that upon forwarding a request, the Hop-by-Hop identifier + is saved; the field is replaced with a locally unique identifier, + which is restored to its original value when the corresponding + + + +Fajardo, et al. Expires July 24, 2011 [Page 16] + +Internet-Draft Diameter Base Protocol January 2011 + + + answer is received. The request's state is released upon receipt + of the answer. A stateless agent is one that only maintains + transaction state. + + + Translation Agent + + A translation agent is a stateful Diameter node that performs + protocol translation between Diameter and another AAA protocol, + such as RADIUS. + + + Transport Connection + + A transport connection is a TCP or SCTP connection existing + directly between two Diameter peers, otherwise known as a Peer-to- + Peer Connection. + + + Upstream + + Upstream is used to identify the direction of a particular + Diameter message from the Diameter Client towards the Home Server. + + + User + + The entity or device requesting or using some resource, in support + of which a Diameter client has generated a request. + + +1.3. Approach to Extensibility + + The Diameter protocol is designed to be extensible, using several + mechanisms, including: + + o Defining new AVP values + + o Creating new AVPs + + o Creating new commands + + o Creating new applications + + From the point of view of extensibility Diameter authentication, + authorization and accounting applications are treated in the same + way. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 17] + +Internet-Draft Diameter Base Protocol January 2011 + + + Note: Protocol designers should try to re-use existing functionality, + namely AVP values, AVPs, commands, and Diameter applications. Reuse + simplifies standardization and implementation. To avoid potential + interoperability issues it is important to ensure that the semantics + of the re-used features are well understood. Given that Diameter can + also carry RADIUS attributes as Diameter AVPs, such re-use + considerations apply also to existing RADIUS attributes that may be + useful in a Diameter application. + +1.3.1. Defining New AVP Values + + In order to allocate a new AVP value for AVPs defined in the Diameter + Base protocol, the IETF needs to approve a new RFC that describes the + AVP value. IANA considerations for these AVP values are discussed in + Section 11.4. + + The allocation of AVP values for other AVPs is guided by the IANA + considerations of the document that defines those AVPs. Typically, + allocation of new values for an AVP defined in an IETF RFC should + require IETF Review [RFC5226], whereas values for vendor-specific + AVPs can be allocated by the vendor. + +1.3.2. Creating New AVPs + + A new AVP being defined MUST use one of the data types listed in + Section 4.2 or Section 4.3. If an appropriate derived data type is + already defined, it SHOULD be used instead of a base data type to + encourage reusability and good design practice. + + In the event that a logical grouping of AVPs is necessary, and + multiple "groups" are possible in a given command, it is recommended + that a Grouped AVP be used (see Section 4.4). + + The creation of new AVPs can happen in various ways. The recommended + approach is to define a new general-purpose AVP in a standards track + RFC approved by the IETF. However, as described in Section 11.1.1 + there are also other mechanisms. + +1.3.3. Creating New Commands + + A new Command Code MUST be allocated when required AVPs (those + indicated as {AVP} in the ABNF definition) are added to, deleted from + or redefined in (for example, by changing a required AVP into an + optional one) an existing command. + + Furthermore, if the transport characteristics of a command are + changed (for example, with respect to the number of round trips + required) a new Command Code MUST be registered. + + + +Fajardo, et al. Expires July 24, 2011 [Page 18] + +Internet-Draft Diameter Base Protocol January 2011 + + + A change to the ABNF of a command, such as described above, MUST + result in the definition of a new Command Code. This subsequently + leads to the need to define a new Diameter Application for any + application that will use that new Command. + + The IANA considerations for commands are discussed in Section 11.2.1. + +1.3.4. Creating New Diameter Applications + + Every Diameter application specification MUST have an IANA assigned + Application Id (see Section 2.4 and Section 11.3). The managed + Application Id space is flat and there is no relationship between + different Diameter applications with respect to their Application + Ids. As such, there is no versioning support provided by these + application Ids itself; every Diameter application is a standalone + application. If the application has a relationship with other + Diameter applications, such a relationship is not known to Diameter. + + Before describing the rules for creating new Diameter applications it + is important to discuss the semantics of the AVPs occurrences as + stated in the ABNF and the M-bit flag (Section 4.1) for an AVP. + There is no relationship imposed between the two; they are set + independently. + + o The ABNF indicates what AVPs are placed into a Diameter Command by + the sender of that Command. Often, since there are multiple modes + of protocol interactions many of the AVPs are indicated as + optional. + + o The M-bit allows the sender to indicate to the receiver whether or + not understanding the semantics of an AVP and its content is + mandatory. If the M-bit is set by the sender and the receiver + does not understand the AVP or the values carried within that AVP + then a failure is generated (see Section 7). + + It is the decision of the protocol designer when to develop a new + Diameter application rather than extending Diameter in other ways. + However, a new Diameter application MUST be created when one or more + of the following criteria are met: + + + M-bit Setting + + An AVP with the M-bit in the MUST column of the AVP flag table is + added to an existing Command/Application. + + An AVP with the M-bit in the MAY column of the AVP flag table is + added to an existing Command/Application. + + + +Fajardo, et al. Expires July 24, 2011 [Page 19] + +Internet-Draft Diameter Base Protocol January 2011 + + + Note: The M-bit setting for a given AVP is relevant to an + Application and each command within that application which + includes the AVP. That is, if an AVP appears in two commands for + application Foo and the M-bit settings are different in each + command, then there should be two AVP flag tables describing when + to set the M-bit. + + Commands + + A new command is used within the existing application either + because an additional command is added, an existing command has + been modified so that a new Command Code had to be registered, or + a command has been deleted. + + If the ABNF definition of a command allows it, an implementation may + add arbitrary optional AVPs with the M-bit cleared (including vendor- + specific AVPs) to that command without needing to define a new + application. Please refer to Section 11.1.1 for details. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 20] + +Internet-Draft Diameter Base Protocol January 2011 + + +2. Protocol Overview + + The base Diameter protocol concerns itself with establishing + connections to peers, capabilities negotiation, how messages are sent + and routed through peers, and how the connections are eventually torn + down. The base protocol also defines certain rules that apply to all + message exchanges between Diameter nodes. + + Communication between Diameter peers begins with one peer sending a + message to another Diameter peer. The set of AVPs included in the + message is determined by a particular Diameter application. One AVP + that is included to reference a user's session is the Session-Id. + + The initial request for authentication and/or authorization of a user + would include the Session-Id AVP. The Session-Id is then used in all + subsequent messages to identify the user's session (see Section 8 for + more information). The communicating party may accept the request, + or reject it by returning an answer message with the Result-Code AVP + set to indicate an error occurred. The specific behavior of the + Diameter server or client receiving a request depends on the Diameter + application employed. + + Session state (associated with a Session-Id) MUST be freed upon + receipt of the Session-Termination-Request, Session-Termination- + Answer, expiration of authorized service time in the Session-Timeout + AVP, and according to rules established in a particular Diameter + application. + + The base Diameter protocol may be used by itself for accounting + applications. For authentication and authorization, it is always + extended for a particular application. + + Diameter Clients MUST support the base protocol, which includes + accounting. In addition, they MUST fully support each Diameter + application that is needed to implement the client's service, e.g., + NASREQ and/or Mobile IPv4. A Diameter Client MUST be referred to as + "Diameter X Client" where X is the application which it supports, and + not a "Diameter Client". + + Diameter Servers MUST support the base protocol, which includes + accounting. In addition, they MUST fully support each Diameter + application that is needed to implement the intended service, e.g., + NASREQ and/or Mobile IPv4. A Diameter Server MUST be referred to as + "Diameter X Server" where X is the application which it supports, and + not a "Diameter Server". + + Diameter Relays and redirect agents are transparent to the Diameter + applications but they MUST support the Diameter base protocol, which + + + +Fajardo, et al. Expires July 24, 2011 [Page 21] + +Internet-Draft Diameter Base Protocol January 2011 + + + includes accounting, and all Diameter applications. + + Diameter proxies MUST support the base protocol, which includes + accounting. In addition, they MUST fully support each Diameter + application that is needed to implement proxied services, e.g., + NASREQ and/or Mobile IPv4. A Diameter proxy MUST be referred to as + "Diameter X Proxy" where X is the application which it supports, and + not a "Diameter Proxy". + +2.1. Transport + + The Diameter Transport profile is defined in [RFC3539]. + + The base Diameter protocol is run on port 3868 for both TCP [RFC793] + and SCTP [RFC4960]. For TLS [RFC5246] and DTLS [RFC4347], a Diameter + node that initiate a connection prior to any message exchanges MUST + run on port [TBD]. It is assumed that TLS is run on top of TCP when + it is used and DTLS is run on top of SCTP when it is used. + + If the Diameter peer does not support receiving TLS/TCP and DTLS/SCTP + connections on port [TBD], i.e. the peer complies only with + [RFC3588], then the initiator MAY revert to using TCP or SCTP and on + port 3868. Note that this scheme is kept for the purpose of + backwards compatibility only and that there are inherent security + vulnerabilities when the initial CER/CEA messages are sent un- + protected (see Section 5.6). + + Diameter clients MUST support either TCP or SCTP, while agents and + servers SHOULD support both. + + A Diameter node MAY initiate connections from a source port other + than the one that it declares it accepts incoming connections on, and + MUST be prepared to receive connections on port 3868 for TCP or SCTP + and port [TBD] for TLS/TCP and DTLS/SCTP connections. A given + Diameter instance of the peer state machine MUST NOT use more than + one transport connection to communicate with a given peer, unless + multiple instances exist on the peer in which case a separate + connection per process is allowed. + + When no transport connection exists with a peer, an attempt to + connect SHOULD be periodically made. This behavior is handled via + the Tc timer (see Section 12 for details), whose recommended value is + 30 seconds. There are certain exceptions to this rule, such as when + a peer has terminated the transport connection stating that it does + not wish to communicate. + + When connecting to a peer and either zero or more transports are + specified, TLS SHOULD be tried first, followed by DTLS, then by TCP + + + +Fajardo, et al. Expires July 24, 2011 [Page 22] + +Internet-Draft Diameter Base Protocol January 2011 + + + and finally by SCTP. See Section 5.2 for more information on peer + discovery. + + Diameter implementations SHOULD be able to interpret ICMP protocol + port unreachable messages as explicit indications that the server is + not reachable, subject to security policy on trusting such messages. + Further guidance regarding the treatment of ICMP errors can be found + in [RFC5927] and [RFC5461]. Diameter implementations SHOULD also be + able to interpret a reset from the transport and timed-out connection + attempts. If Diameter receives data from the lower layer that cannot + be parsed or identified as a Diameter error made by the peer, the + stream is compromised and cannot be recovered. The transport + connection MUST be closed using a RESET call (send a TCP RST bit) or + an SCTP ABORT message (graceful closure is compromised). + +2.1.1. SCTP Guidelines + + Diameter messages SHOULD be mapped into SCTP streams in a way that + avoids head-of-the-line (HOL) blocking. Among different ways of + performing the mapping that fulfill this requirement it is + RECOMMENDED that a Diameter node sends every Diameter message + (request or response) over the stream zero with the unordered flag + set. However, Diameter nodes MAY select and implement other design + alternatives for avoiding HOL blocking such as using multiple streams + with the unordered flag cleared (as originally instructed in + RFC3588). On the receiving side, a Diameter entity MUST be ready to + receive Diameter messages over any stream and it is free to return + responses over a different stream. This way, both sides manage the + available streams in the sending direction, independently of the + streams chosen by the other side to send a particular Diameter + message. These messages can be out-of-order and belong to different + Diameter sessions. + + Out-of-order delivery has special concerns during a connection + establishment and termination. When a connection is established, the + responder side sends a CEA message and moves to R-Open state as + specified in Section 5.6. If an application message is sent shortly + after the CEA and delivered out-of-order, the initiator side, still + in Wait-I-CEA state, will discard the application message and close + the connection. In order to avoid this race condition, the receiver + side SHOULD NOT use out-of-order delivery methods until the first + message has been received from the initiator, proving that it has + moved to I-Open state. To trigger such message, the receiver side + could send a DWR immediatly after sending CEA. Upon reception of the + corresponding DWA, the receiver side should start using out-of-order + delivery methods to counter the HOL blocking. + + Another race condition may occur when DPR and DPA messages are used. + + + +Fajardo, et al. Expires July 24, 2011 [Page 23] + +Internet-Draft Diameter Base Protocol January 2011 + + + Both DPR and DPA are small in size, thus they may be delivered faster + to the peer than application messages when out-of-order delivery + mechanism is used. Therefore, it is possible that a DPR/DPA exchange + completes while application messages are still in transit, resulting + to a loss of these messages. An implementation could mitigate this + race condition, for example, using timers and wait for a short period + of time for pending application level messages to arrive before + proceeding to disconnect the transport connection. Eventually, lost + messages are handled by the retransmission mechanism described in + Section 5.5.4. + +2.2. Securing Diameter Messages + + Connections between Diameter peers SHOULD be protected by TLS/TCP and + DTLS/SCTP. All Diameter base protocol implementations MUST support + the use of TLS/TCP and DTLS/SCTP. If desired, alternative security + mechanisms that are independent of Diameter, such as IPsec [RFC4301], + can be deployed to secure connections between peers. The Diameter + protocol MUST NOT be used without any security mechanism. + +2.3. Diameter Application Compliance + + Application Ids are advertised during the capabilities exchange phase + (see Section 5.3). Advertising support of an application implies + that the sender supports the functionality specified in the + respective Diameter application specification. + + Implementations MAY add arbitrary optional AVPs with the M-bit + cleared (including vendor-specific AVPs) to a command defined in an + application, but only if the command's ABNF syntax specification + allows for it. Please refer to Section 11.1.1 for details. + +2.4. Application Identifiers + + Each Diameter application MUST have an IANA assigned Application Id + (see Section 11.3). The base protocol does not require an + Application Id since its support is mandatory. During the + capabilities exchange, Diameter nodes inform their peers of locally + supported applications. Furthermore, all Diameter messages contain + an Application Id, which is used in the message forwarding process. + + The following Application Id values are defined: + + Diameter Common Messages 0 + Diameter Base Accounting 3 + Relay 0xffffffff + + Relay and redirect agents MUST advertise the Relay Application + + + +Fajardo, et al. Expires July 24, 2011 [Page 24] + +Internet-Draft Diameter Base Protocol January 2011 + + + Identifier, while all other Diameter nodes MUST advertise locally + supported applications. The receiver of a Capabilities Exchange + message advertising Relay service MUST assume that the sender + supports all current and future applications. + + Diameter relay and proxy agents are responsible for finding an + upstream server that supports the application of a particular + message. If none can be found, an error message is returned with the + Result-Code AVP set to DIAMETER_UNABLE_TO_DELIVER. + +2.5. Connections vs. Sessions + + This section attempts to provide the reader with an understanding of + the difference between connection and session, which are terms used + extensively throughout this document. + + A connection refers to a transport level connection between two peers + that is used to send and receive Diameter messages. A session is a + logical concept at the application layer existing between the + Diameter client and the Diameter server; it is identified via the + Session-Id AVP. + + + +--------+ +-------+ +--------+ + | Client | | Relay | | Server | + +--------+ +-------+ +--------+ + <----------> <----------> + peer connection A peer connection B + + <-----------------------------> + User session x + + Figure 1: Diameter connections and sessions + + In the example provided in Figure 1, peer connection A is established + between the Client and the Relay. Peer connection B is established + between the Relay and the Server. User session X spans from the + Client via the Relay to the Server. Each "user" of a service causes + an auth request to be sent, with a unique session identifier. Once + accepted by the server, both the client and the server are aware of + the session. + + It is important to note that there is no relationship between a + connection and a session, and that Diameter messages for multiple + sessions are all multiplexed through a single connection. Also note + that Diameter messages pertaining to the session, both application + specific and those that are defined in this document such as ASR/ASA, + RAR/RAA and STR/STA MUST carry the Application Id of the application. + + + +Fajardo, et al. Expires July 24, 2011 [Page 25] + +Internet-Draft Diameter Base Protocol January 2011 + + + Diameter messages pertaining to peer connection establishment and + maintenance such as CER/CEA, DWR/DWA and DPR/DPA MUST carry an + Application Id of zero (0). + +2.6. Peer Table + + The Diameter Peer Table is used in message forwarding, and referenced + by the Routing Table. A Peer Table entry contains the following + fields: + + Host identity + + Following the conventions described for the DiameterIdentity + derived AVP data format in Section 4.3. This field contains the + contents of the Origin-Host (Section 6.3) AVP found in the CER or + CEA message. + + + StatusT + + This is the state of the peer entry, and MUST match one of the + values listed in Section 5.6. + + + Static or Dynamic + + Specifies whether a peer entry was statically configured or + dynamically discovered. + + + Expiration time + + Specifies the time at which dynamically discovered peer table + entries are to be either refreshed, or expired. + + + TLS/TCP and DTLS/SCTP Enabled + + Specifies whether TLS/TCP and DTLS/SCTP is to be used when + communicating with the peer. + + + Additional security information, when needed (e.g., keys, + certificates) + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 26] + +Internet-Draft Diameter Base Protocol January 2011 + + +2.7. Routing Table + + All Realm-Based routing lookups are performed against what is + commonly known as the Routing Table (see Section 12). A Routing + Table Entry contains the following fields: + + Realm Name + + This is the field that is MUST be used as a primary key in the + routing table lookups. Note that some implementations perform + their lookups based on longest-match-from-the-right on the realm + rather than requiring an exact match. + + + Application Identifier + + An application is identified by an Application Id. A route entry + can have a different destination based on the Application Id in + the message header. This field MUST be used as a secondary key + field in routing table lookups. + + + Local Action + + The Local Action field is used to identify how a message should be + treated. The following actions are supported: + + + 1. LOCAL - Diameter messages that can be satisfied locally, and + do not need to be routed to another Diameter entity. + + 2. RELAY - All Diameter messages that fall within this category + MUST be routed to a next hop Diameter entity that is indicated + by the identifier described below. Routing is done without + modifying any non-routing AVPs. See Section 6.1.9 for + relaying guidelines + + 3. PROXY - All Diameter messages that fall within this category + MUST be routed to a next Diameter entity that is indicated by + the identifier described below. The local server MAY apply + its local policies to the message by including new AVPs to the + message prior to routing. See Section 6.1.9 for proxying + guidelines. + + 4. REDIRECT - Diameter messages that fall within this category + MUST have the identity of the home Diameter server(s) + appended, and returned to the sender of the message. See + Section 6.1.8 for redirect guidelines. + + + +Fajardo, et al. Expires July 24, 2011 [Page 27] + +Internet-Draft Diameter Base Protocol January 2011 + + + Server Identifier + + One or more servers to which the message is to be routed. These + servers MUST also be present in the Peer table. When the Local + Action is set to RELAY or PROXY, this field contains the identity + of the server(s) the message MUST be routed to. When the Local + Action field is set to REDIRECT, this field contains the identity + of one or more servers the message MUST be redirected to. + + Static or Dynamic + + Specifies whether a route entry was statically configured or + dynamically discovered. + + Expiration time + + Specifies the time at which a dynamically discovered route table + entry expires. + + It is important to note that Diameter agents MUST support at least + one of the LOCAL, RELAY, PROXY or REDIRECT modes of operation. + Agents do not need to support all modes of operation in order to + conform with the protocol specification, but MUST follow the protocol + compliance guidelines in Section 2. Relay agents and proxies MUST + NOT reorder AVPs. + + The routing table MAY include a default entry that MUST be used for + any requests not matching any of the other entries. The routing + table MAY consist of only such an entry. + + When a request is routed, the target server MUST have advertised the + Application Id (see Section 2.4) for the given message, or have + advertised itself as a relay or proxy agent. Otherwise, an error is + returned with the Result-Code AVP set to DIAMETER_UNABLE_TO_DELIVER. + +2.8. Role of Diameter Agents + + In addition to clients and servers, the Diameter protocol introduces + relay, proxy, redirect, and translation agents, each of which is + defined in Section 1.3. These Diameter agents are useful for several + reasons: + + o They can distribute administration of systems to a configurable + grouping, including the maintenance of security associations. + + o They can be used for concentration of requests from an number of + co-located or distributed NAS equipment sets to a set of like user + groups. + + + +Fajardo, et al. Expires July 24, 2011 [Page 28] + +Internet-Draft Diameter Base Protocol January 2011 + + + o They can do value-added processing to the requests or responses. + + o They can be used for load balancing. + + o A complex network will have multiple authentication sources, they + can sort requests and forward towards the correct target. + + The Diameter protocol requires that agents maintain transaction + state, which is used for failover purposes. Transaction state + implies that upon forwarding a request, its Hop-by-Hop identifier is + saved; the field is replaced with a locally unique identifier, which + is restored to its original value when the corresponding answer is + received. The request's state is released upon receipt of the + answer. A stateless agent is one that only maintains transaction + state. + + The Proxy-Info AVP allows stateless agents to add local state to a + Diameter request, with the guarantee that the same state will be + present in the answer. However, the protocol's failover procedures + require that agents maintain a copy of pending requests. + + A stateful agent is one that maintains session state information by + keeping track of all authorized active sessions. Each authorized + session is bound to a particular service, and its state is considered + active either until the agent is notified otherwise, or the session + expires. Each authorized session has an expiration, which is + communicated by Diameter servers via the Session-Timeout AVP. + + Maintaining session state may be useful in certain applications, such + as: + + o Protocol translation (e.g., RADIUS <-> Diameter) + + o Limiting resources authorized to a particular user + + o Per user or transaction auditing + + A Diameter agent MAY act in a stateful manner for some requests and + be stateless for others. A Diameter implementation MAY act as one + type of agent for some requests, and as another type of agent for + others. + +2.8.1. Relay Agents + + Relay Agents are Diameter agents that accept requests and route + messages to other Diameter nodes based on information found in the + messages (e.g., Destination-Realm). This routing decision is + performed using a list of supported realms, and known peers. This is + + + +Fajardo, et al. Expires July 24, 2011 [Page 29] + +Internet-Draft Diameter Base Protocol January 2011 + + + known as the Routing Table, as is defined further in Section 2.7. + + Relays may, for example, be used to aggregate requests from multiple + Network Access Servers (NASes) within a common geographical area + (POP). The use of Relays is advantageous since it eliminates the + need for NASes to be configured with the necessary security + information they would otherwise require to communicate with Diameter + servers in other realms. Likewise, this reduces the configuration + load on Diameter servers that would otherwise be necessary when NASes + are added, changed or deleted. + + Relays modify Diameter messages by inserting and removing routing + information, but do not modify any other portion of a message. + Relays SHOULD NOT maintain session state but MUST maintain + transaction state. + + +------+ ---------> +------+ ---------> +------+ + | | 1. Request | | 2. Request | | + | NAS | | DRL | | HMS | + | | 4. Answer | | 3. Answer | | + +------+ <--------- +------+ <--------- +------+ + example.net example.net example.com + + Figure 2: Relaying of Diameter messages + + The example provided in Figure 2 depicts a request issued from NAS, + which is an access device, for the user [email protected]. Prior to + issuing the request, NAS performs a Diameter route lookup, using + "example.com" as the key, and determines that the message is to be + relayed to DRL, which is a Diameter Relay. DRL performs the same + route lookup as NAS, and relays the message to HMS, which is + example.com's Home Diameter Server. HMS identifies that the request + can be locally supported (via the realm), processes the + authentication and/or authorization request, and replies with an + answer, which is routed back to NAS using saved transaction state. + + Since Relays do not perform any application level processing, they + provide relaying services for all Diameter applications, and + therefore MUST advertise the Relay Application Id. + +2.8.2. Proxy Agents + + Similarly to relays, proxy agents route Diameter messages using the + Diameter Routing Table. However, they differ since they modify + messages to implement policy enforcement. This requires that proxies + maintain the state of their downstream peers (e.g., access devices) + to enforce resource usage, provide admission control, and + provisioning. + + + +Fajardo, et al. Expires July 24, 2011 [Page 30] + +Internet-Draft Diameter Base Protocol January 2011 + + + Proxies may, for example, be used in call control centers or access + ISPs that provide outsourced connections, they can monitor the number + and types of ports in use, and make allocation and admission + decisions according to their configuration. + + Since enforcing policies requires an understanding of the service + being provided, Proxies MUST only advertise the Diameter applications + they support. + +2.8.3. Redirect Agents + + Redirect agents are useful in scenarios where the Diameter routing + configuration needs to be centralized. An example is a redirect + agent that provides services to all members of a consortium, but does + not wish to be burdened with relaying all messages between realms. + This scenario is advantageous since it does not require that the + consortium provide routing updates to its members when changes are + made to a member's infrastructure. + + Since redirect agents do not relay messages, and only return an + answer with the information necessary for Diameter agents to + communicate directly, they do not modify messages. Since redirect + agents do not receive answer messages, they cannot maintain session + state. + + The example provided in Figure 3 depicts a request issued from the + access device, NAS, for the user [email protected]. The message is + forwarded by the NAS to its relay, DRL, which does not have a routing + entry in its Diameter Routing Table for example.com. DRL has a + default route configured to DRD, which is a redirect agent that + returns a redirect notification to DRL, as well as HMS' contact + information. Upon receipt of the redirect notification, DRL + establishes a transport connection with HMS, if one doesn't already + exist, and forwards the request to it. + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 31] + +Internet-Draft Diameter Base Protocol January 2011 + + + +------+ + | | + | DRD | + | | + +------+ + ^ | + 2. Request | | 3. Redirection + | | Notification + | v + +------+ ---------> +------+ ---------> +------+ + | | 1. Request | | 4. Request | | + | NAS | | DRL | | HMS | + | | 6. Answer | | 5. Answer | | + +------+ <--------- +------+ <--------- +------+ + example.net example.net example.com + + Figure 3: Redirecting a Diameter Message + + Since redirect agents do not perform any application level + processing, they provide relaying services for all Diameter + applications, and therefore MUST advertise the Relay Application + Identifier. + +2.8.4. Translation Agents + + A translation agent is a device that provides translation between two + protocols (e.g., RADIUS<->Diameter, TACACS+<->Diameter). Translation + agents are likely to be used as aggregation servers to communicate + with a Diameter infrastructure, while allowing for the embedded + systems to be migrated at a slower pace. + + Given that the Diameter protocol introduces the concept of long-lived + authorized sessions, translation agents MUST be session stateful and + MUST maintain transaction state. + + Translation of messages can only occur if the agent recognizes the + application of a particular request, and therefore translation agents + MUST only advertise their locally supported applications. + + +------+ ---------> +------+ ---------> +------+ + | | RADIUS Request | | Diameter Request | | + | NAS | | TLA | | HMS | + | | RADIUS Answer | | Diameter Answer | | + +------+ <--------- +------+ <--------- +------+ + example.net example.net example.com + + Figure 4: Translation of RADIUS to Diameter + + + + +Fajardo, et al. Expires July 24, 2011 [Page 32] + +Internet-Draft Diameter Base Protocol January 2011 + + +2.9. Diameter Path Authorization + + As noted in Section 2.2, Diameter provides transmission level + security for each connection using TLS/TCP and DTLS/SCTP. Therefore, + each connection can be authenticated, replay and integrity protected. + + In addition to authenticating each connection, each connection as + well as the entire session MUST also be authorized. Before + initiating a connection, a Diameter Peer MUST check that its peers + are authorized to act in their roles. For example, a Diameter peer + may be authentic, but that does not mean that it is authorized to act + as a Diameter Server advertising a set of Diameter applications. + + Prior to bringing up a connection, authorization checks are performed + at each connection along the path. Diameter capabilities negotiation + (CER/CEA) also MUST be carried out, in order to determine what + Diameter applications are supported by each peer. Diameter sessions + MUST be routed only through authorized nodes that have advertised + support for the Diameter application required by the session. + + As noted in Section 6.1.9, a relay or proxy agent MUST append a + Route-Record AVP to all requests forwarded. The AVP contains the + identity of the peer the request was received from. + + The home Diameter server, prior to authorizing a session, MUST check + the Route-Record AVPs to make sure that the route traversed by the + request is acceptable. For example, administrators within the home + realm may not wish to honor requests that have been routed through an + untrusted realm. By authorizing a request, the home Diameter server + is implicitly indicating its willingness to engage in the business + transaction as specified by the contractual relationship between the + server and the previous hop. A DIAMETER_AUTHORIZATION_REJECTED error + message (see Section 7.1.5) is sent if the route traversed by the + request is unacceptable. + + A home realm may also wish to check that each accounting request + message corresponds to a Diameter response authorizing the session. + Accounting requests without corresponding authorization responses + SHOULD be subjected to further scrutiny, as should accounting + requests indicating a difference between the requested and provided + service. + + Forwarding of an authorization response is considered evidence of a + willingness to take on financial risk relative to the session. A + local realm may wish to limit this exposure, for example, by + establishing credit limits for intermediate realms and refusing to + accept responses which would violate those limits. By issuing an + accounting request corresponding to the authorization response, the + + + +Fajardo, et al. Expires July 24, 2011 [Page 33] + +Internet-Draft Diameter Base Protocol January 2011 + + + local realm implicitly indicates its agreement to provide the service + indicated in the authorization response. If the service cannot be + provided by the local realm, then a DIAMETER_UNABLE_TO_COMPLY error + message MUST be sent within the accounting request; a Diameter client + receiving an authorization response for a service that it cannot + perform MUST NOT substitute an alternate service, and then send + accounting requests for the alternate service instead. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 34] + +Internet-Draft Diameter Base Protocol January 2011 + + +3. Diameter Header + + A summary of the Diameter header format is shown below. The fields + are transmitted in network byte order. + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Version | Message Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | command flags | Command-Code | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Application-ID | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Hop-by-Hop Identifier | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | End-to-End Identifier | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | AVPs ... + +-+-+-+-+-+-+-+-+-+-+-+-+- + + Version + + This Version field MUST be set to 1 to indicate Diameter Version + 1. + + Message Length + + The Message Length field is three octets and indicates the length + of the Diameter message including the header fields and the padded + AVPs. Thus the message length field is always a multiple of 4. + + Command Flags + + The Command Flags field is eight bits. The following bits are + assigned: + + 0 1 2 3 4 5 6 7 + +-+-+-+-+-+-+-+-+ + |R P E T r r r r| + +-+-+-+-+-+-+-+-+ + + R(equest) + + If set, the message is a request. If cleared, the message is + an answer. + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 35] + +Internet-Draft Diameter Base Protocol January 2011 + + + P(roxiable) + + If set, the message MAY be proxied, relayed or redirected. If + cleared, the message MUST be locally processed. + + + E(rror) + + If set, the message contains a protocol error, and the message + will not conform to the ABNF described for this command. + Messages with the 'E' bit set are commonly referred to as error + messages. This bit MUST NOT be set in request messages. See + Section 7.2. + + + T(Potentially re-transmitted message) + + This flag is set after a link failover procedure, to aid the + removal of duplicate requests. It is set when resending + requests not yet acknowledged, as an indication of a possible + duplicate due to a link failure. This bit MUST be cleared when + sending a request for the first time, otherwise the sender MUST + set this flag. Diameter agents only need to be concerned about + the number of requests they send based on a single received + request; retransmissions by other entities need not be tracked. + Diameter agents that receive a request with the T flag set, + MUST keep the T flag set in the forwarded request. This flag + MUST NOT be set if an error answer message (e.g., a protocol + error) has been received for the earlier message. It can be + set only in cases where no answer has been received from the + server for a request and the request is sent again. This flag + MUST NOT be set in answer messages. + + + r(eserved) + + These flag bits are reserved for future use, and MUST be set to + zero, and ignored by the receiver. + + Command-Code + + The Command-Code field is three octets, and is used in order to + communicate the command associated with the message. The 24-bit + address space is managed by IANA (see Section 11.2.1). + + Command-Code values 16,777,214 and 16,777,215 (hexadecimal values + FFFFFE -FFFFFF) are reserved for experimental use (See Section + 11.3). + + + +Fajardo, et al. Expires July 24, 2011 [Page 36] + +Internet-Draft Diameter Base Protocol January 2011 + + + Application-ID + + Application-ID is four octets and is used to identify to which + application the message is applicable for. The application can be + an authentication application, an accounting application or a + vendor specific application. See Section 11.3 for the possible + values that the application-id may use. + + The value of the application-id field in the header MUST be the + same as any relevant application-id AVPs contained in the message. + + Hop-by-Hop Identifier + + The Hop-by-Hop Identifier is an unsigned 32-bit integer field (in + network byte order) and aids in matching requests and replies. + The sender MUST ensure that the Hop-by-Hop identifier in a request + is unique on a given connection at any given time, and MAY attempt + to ensure that the number is unique across reboots. The sender of + an Answer message MUST ensure that the Hop-by-Hop Identifier field + contains the same value that was found in the corresponding + request. The Hop-by-Hop identifier is normally a monotonically + increasing number, whose start value was randomly generated. An + answer message that is received with an unknown Hop-by-Hop + Identifier MUST be discarded. + + + End-to-End Identifier + + The End-to-End Identifier is an unsigned 32-bit integer field (in + network byte order) and is used to detect duplicate messages. + Upon reboot implementations MAY set the high order 12 bits to + contain the low order 12 bits of current time, and the low order + 20 bits to a random value. Senders of request messages MUST + insert a unique identifier on each message. The identifier MUST + remain locally unique for a period of at least 4 minutes, even + across reboots. The originator of an Answer message MUST ensure + that the End-to-End Identifier field contains the same value that + was found in the corresponding request. The End-to-End Identifier + MUST NOT be modified by Diameter agents of any kind. The + combination of the Origin-Host (see Section 6.3) and this field is + used to detect duplicates. Duplicate requests SHOULD cause the + same answer to be transmitted (modulo the hop-by-hop Identifier + field and any routing AVPs that may be present), and MUST NOT + affect any state that was set when the original request was + processed. Duplicate answer messages that are to be locally + consumed (see Section 6.2) SHOULD be silently discarded. + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 37] + +Internet-Draft Diameter Base Protocol January 2011 + + + AVPs + + AVPs are a method of encapsulating information relevant to the + Diameter message. See Section 4 for more information on AVPs. + +3.1. Command Codes + + Each command Request/Answer pair is assigned a command code, and the + sub-type (i.e., request or answer) is identified via the 'R' bit in + the Command Flags field of the Diameter header. + + + Every Diameter message MUST contain a command code in its header's + Command-Code field, which is used to determine the action that is to + be taken for a particular message. The following Command Codes are + defined in the Diameter base protocol: + + Command-Name Abbrev. Code Reference + -------------------------------------------------------- + Abort-Session-Request ASR 274 8.5.1 + Abort-Session-Answer ASA 274 8.5.2 + Accounting-Request ACR 271 9.7.1 + Accounting-Answer ACA 271 9.7.2 + Capabilities-Exchange- CER 257 5.3.1 + Request + Capabilities-Exchange- CEA 257 5.3.2 + Answer + Device-Watchdog-Request DWR 280 5.5.1 + Device-Watchdog-Answer DWA 280 5.5.2 + Disconnect-Peer-Request DPR 282 5.4.1 + Disconnect-Peer-Answer DPA 282 5.4.2 + Re-Auth-Request RAR 258 8.3.1 + Re-Auth-Answer RAA 258 8.3.2 + Session-Termination- STR 275 8.4.1 + Request + Session-Termination- STA 275 8.4.2 + Answer + +3.2. Command Code ABNF specification + + Every Command Code defined MUST include a corresponding ABNF + specification, which is used to define the AVPs that MUST or MAY be + present when sending the message. The following format is used in + the definition: + + command-def = <command-name> "::=" diameter-message + + command-name = diameter-name + + + +Fajardo, et al. Expires July 24, 2011 [Page 38] + +Internet-Draft Diameter Base Protocol January 2011 + + + diameter-name = ALPHA *(ALPHA / DIGIT / "-") + + diameter-message = header [ *fixed] [ *required] [ *optional] + + header = "<" "Diameter Header:" command-id + [r-bit] [p-bit] [e-bit] [application-id] ">" + + application-id = 1*DIGIT + + command-id = 1*DIGIT + ; The Command Code assigned to the command + + r-bit = ", REQ" + ; If present, the 'R' bit in the Command + ; Flags is set, indicating that the message + ; is a request, as opposed to an answer. + + p-bit = ", PXY" + ; If present, the 'P' bit in the Command + ; Flags is set, indicating that the message + ; is proxiable. + + e-bit = ", ERR" + ; If present, the 'E' bit in the Command + ; Flags is set, indicating that the answer + ; message contains a Result-Code AVP in + ; the "protocol error" class. + + fixed = [qual] "<" avp-spec ">" + ; Defines the fixed position of an AVP + + required = [qual] "{" avp-spec "}" + ; The AVP MUST be present and can appear + ; anywhere in the message. + + + optional = [qual] "[" avp-name "]" + ; The avp-name in the 'optional' rule cannot + ; evaluate to any AVP Name which is included + ; in a fixed or required rule. The AVP can + ; appear anywhere in the message. + ; + ; NOTE: "[" and "]" have a slightly different + ; meaning than in ABNF (RFC 5234]). These braces + ; cannot be used to express optional fixed rules + ; (such as an optional ICV at the end). To do this, + ; the convention is '0*1fixed'. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 39] + +Internet-Draft Diameter Base Protocol January 2011 + + + qual = [min] "*" [max] + ; See ABNF conventions, RFC 5234 Section 4. + ; The absence of any qualifiers depends on + ; whether it precedes a fixed, required, or + ; optional rule. If a fixed or required rule has + ; no qualifier, then exactly one such AVP MUST + ; be present. If an optional rule has no + ; qualifier, then 0 or 1 such AVP may be + ; present. If an optional rule has a qualifier, + ; then the value of min MUST be 0 if present. + + min = 1*DIGIT + ; The minimum number of times the element may + ; be present. If absent, the default value is zero + ; for fixed and optional rules and one for required + ; rules. The value MUST be at least one for for + ; required rules. + + max = 1*DIGIT + ; The maximum number of times the element may + ; be present. If absent, the default value is + ; infinity. A value of zero implies the AVP MUST + ; NOT be present. + + avp-spec = diameter-name + ; The avp-spec has to be an AVP Name, defined + ; in the base or extended Diameter + ; specifications. + + avp-name = avp-spec / "AVP" + ; The string "AVP" stands for *any* arbitrary AVP + ; Name, not otherwise listed in that command code + ; definition. Addition this AVP is recommended for + ; all command ABNFs to allow for extensibility. + + + + The following is a definition of a fictitious command code: + + Example-Request ::= < Diameter Header: 9999999, REQ, PXY > + { User-Name } + * { Origin-Host } + * [ AVP ] + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 40] + +Internet-Draft Diameter Base Protocol January 2011 + + +3.3. Diameter Command Naming Conventions + + Diameter command names typically includes one or more English words + followed by the verb Request or Answer. Each English word is + delimited by a hyphen. A three-letter acronym for both the request + and answer is also normally provided. + + An example is a message set used to terminate a session. The command + name is Session-Terminate-Request and Session-Terminate-Answer, while + the acronyms are STR and STA, respectively. + + Both the request and the answer for a given command share the same + command code. The request is identified by the R(equest) bit in the + Diameter header set to one (1), to ask that a particular action be + performed, such as authorizing a user or terminating a session. Once + the receiver has completed the request it issues the corresponding + answer, which includes a result code that communicates one of the + following: + + o The request was successful + + o The request failed + + o An additional request has to be sent to provide information the + peer requires prior to returning a successful or failed answer. + + o The receiver could not process the request, but provides + information about a Diameter peer that is able to satisfy the + request, known as redirect. + + Additional information, encoded within AVPs, may also be included in + answer messages. + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 41] + +Internet-Draft Diameter Base Protocol January 2011 + + +4. Diameter AVPs + + Diameter AVPs carry specific authentication, accounting, + authorization and routing information as well as configuration + details for the request and reply. + + Each AVP of type OctetString MUST be padded to align on a 32-bit + boundary, while other AVP types align naturally. A number of zero- + valued bytes are added to the end of the AVP Data field till a word + boundary is reached. The length of the padding is not reflected in + the AVP Length field. + +4.1. AVP Header + + The fields in the AVP header MUST be sent in network byte order. The + format of the header is: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | AVP Code | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |V M P r r r r r| AVP Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Vendor-ID (opt) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Data ... + +-+-+-+-+-+-+-+-+ + + AVP Code + + The AVP Code, combined with the Vendor-Id field, identifies the + attribute uniquely. AVP numbers 1 through 255 are reserved for + re-use of RADIUS attributes, without setting the Vendor-Id field. + AVP numbers 256 and above are used for Diameter, which are + allocated by IANA (see Section 11.1). + + + AVP Flags + + The AVP Flags field informs the receiver how each attribute must + be handled. The 'r' (reserved) bits are unused and SHOULD be set + to 0. Note that subsequent Diameter applications MAY define + additional bits within the AVP Header, and an unrecognized bit + SHOULD be considered an error. The 'P' bit has been reserved for + future usage of end-to-end security. At the time of writing there + are no end-to-end security mechanisms specified therefore the 'P' + bit SHOULD be set to 0. + + + +Fajardo, et al. Expires July 24, 2011 [Page 42] + +Internet-Draft Diameter Base Protocol January 2011 + + + The 'M' Bit, known as the Mandatory bit, indicates whether the + receiver of the AVP MUST parse and understand the semantic of the + AVP including its content. The receiving entity MUST return an + appropriate error message if it receives an AVP that has the M-bit + set but does not understand it. An exception applies when the AVP + is embedded within a Grouped AVP. See Section 4.4 for details. + Diameter Relay and redirect agents MUST NOT reject messages with + unrecognized AVPs. + + The 'M' bit MUST be set according to the rules defined in the + application specification which introduces or re-uses this AVP. + Within a given application, the M-bit setting for an AVP is either + defined for all command types or for each command type. + + AVPs with the 'M' bit cleared are informational only and a + receiver that receives a message with such an AVP that is not + supported, or whose value is not supported, MAY simply ignore the + AVP. + + The 'V' bit, known as the Vendor-Specific bit, indicates whether + the optional Vendor-ID field is present in the AVP header. When + set the AVP Code belongs to the specific vendor code address + space. + + AVP Length + + The AVP Length field is three octets, and indicates the number of + octets in this AVP including the AVP Code, AVP Length, AVP Flags, + Vendor-ID field (if present) and the AVP data. If a message is + received with an invalid attribute length, the message MUST be + rejected. + +4.1.1. Optional Header Elements + + The AVP Header contains one optional field. This field is only + present if the respective bit-flag is enabled. + + + Vendor-ID + + The Vendor-ID field is present if the 'V' bit is set in the AVP + Flags field. The optional four-octet Vendor-ID field contains the + IANA assigned "SMI Network Management Private Enterprise Codes" + [RFC3232] value, encoded in network byte order. Any vendor or + standardization organization that are also treated like vendors in + the IANA managed "SMI Network Management Private Enterprise Codes" + space wishing to implement a vendor-specific Diameter AVP MUST use + their own Vendor-ID along with their privately managed AVP address + + + +Fajardo, et al. Expires July 24, 2011 [Page 43] + +Internet-Draft Diameter Base Protocol January 2011 + + + space, guaranteeing that they will not collide with any other + vendor's vendor-specific AVP(s), nor with future IETF AVPs. + + A vendor ID value of zero (0) corresponds to the IETF adopted AVP + values, as managed by the IANA. Since the absence of the vendor + ID field implies that the AVP in question is not vendor specific, + implementations MUST NOT use the zero (0) vendor ID. + +4.2. Basic AVP Data Formats + + The Data field is zero or more octets and contains information + specific to the Attribute. The format and length of the Data field + is determined by the AVP Code and AVP Length fields. The format of + the Data field MUST be one of the following base data types or a data + type derived from the base data types. In the event that a new Basic + AVP Data Format is needed, a new version of this RFC MUST be created. + + + OctetString + + The data contains arbitrary data of variable length. Unless + otherwise noted, the AVP Length field MUST be set to at least 8 + (12 if the 'V' bit is enabled). AVP Values of this type that are + not a multiple of four-octets in length is followed by the + necessary padding so that the next AVP (if any) will start on a + 32-bit boundary. + + + Integer32 + + 32 bit signed value, in network byte order. The AVP Length field + MUST be set to 12 (16 if the 'V' bit is enabled). + + + Integer64 + + 64 bit signed value, in network byte order. The AVP Length field + MUST be set to 16 (20 if the 'V' bit is enabled). + + + Unsigned32 + + 32 bit unsigned value, in network byte order. The AVP Length + field MUST be set to 12 (16 if the 'V' bit is enabled). + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 44] + +Internet-Draft Diameter Base Protocol January 2011 + + + Unsigned64 + + 64 bit unsigned value, in network byte order. The AVP Length + field MUST be set to 16 (20 if the 'V' bit is enabled). + + + Float32 + + This represents floating point values of single precision as + described by [FLOATPOINT]. The 32-bit value is transmitted in + network byte order. The AVP Length field MUST be set to 12 (16 if + the 'V' bit is enabled). + + + Float64 + + This represents floating point values of double precision as + described by [FLOATPOINT]. The 64-bit value is transmitted in + network byte order. The AVP Length field MUST be set to 16 (20 if + the 'V' bit is enabled). + + + Grouped + + The Data field is specified as a sequence of AVPs. Each of these + AVPs follows - in the order in which they are specified - + including their headers and padding. The AVP Length field is set + to 8 (12 if the 'V' bit is enabled) plus the total length of all + included AVPs, including their headers and padding. Thus the AVP + length field of an AVP of type Grouped is always a multiple of 4. + + +4.3. Derived AVP Data Formats + + In addition to using the Basic AVP Data Formats, applications may + define data formats derived from the Basic AVP Data Formats. An + application that defines new Derived AVP Data Formats MUST include + them in a section entitled "Derived AVP Data Formats", using the same + format as the definitions below. Each new definition MUST be either + defined or listed with a reference to the RFC that defines the + format. + +4.3.1. Common Derived AVPs + + The following are commonly used Derived AVP Data Formats. + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 45] + +Internet-Draft Diameter Base Protocol January 2011 + + + Address + + The Address format is derived from the OctetString AVP Base + Format. It is a discriminated union, representing, for example a + 32-bit (IPv4) [RFC791] or 128-bit (IPv6) [RFC4291] address, most + significant octet first. The first two octets of the Address AVP + represents the AddressType, which contains an Address Family + defined in [IANAADFAM]. The AddressType is used to discriminate + the content and format of the remaining octets. + + + Time + + The Time format is derived from the OctetString AVP Base Format. + The string MUST contain four octets, in the same format as the + first four bytes are in the NTP timestamp format. The NTP + Timestamp format is defined in Chapter 3 of [RFC5905]. + + This represents the number of seconds since 0h on 1 January 1900 + with respect to the Coordinated Universal Time (UTC). + + On 6h 28m 16s UTC, 7 February 2036 the time value will overflow. + SNTP [RFC5905] describes a procedure to extend the time to 2104. + This procedure MUST be supported by all Diameter nodes. + + + UTF8String + + The UTF8String format is derived from the OctetString AVP Base + Format. This is a human readable string represented using the + ISO/IEC IS 10646-1 character set, encoded as an OctetString using + the UTF-8 [RFC3629] transformation format described in RFC 3629. + + Since additional code points are added by amendments to the 10646 + standard from time to time, implementations MUST be prepared to + encounter any code point from 0x00000001 to 0x7fffffff. Byte + sequences that do not correspond to the valid encoding of a code + point into UTF-8 charset or are outside this range are prohibited. + + The use of control codes SHOULD be avoided. When it is necessary + to represent a new line, the control code sequence CR LF SHOULD be + used. + + The use of leading or trailing white space SHOULD be avoided. + + For code points not directly supported by user interface hardware + or software, an alternative means of entry and display, such as + hexadecimal, MAY be provided. + + + +Fajardo, et al. Expires July 24, 2011 [Page 46] + +Internet-Draft Diameter Base Protocol January 2011 + + + For information encoded in 7-bit US-ASCII, the UTF-8 charset is + identical to the US-ASCII charset. + + UTF-8 may require multiple bytes to represent a single character / + code point; thus the length of an UTF8String in octets may be + different from the number of characters encoded. + + Note that the AVP Length field of an UTF8String is measured in + octets, not characters. + + DiameterIdentity + + The DiameterIdentity format is derived from the OctetString AVP + Base Format. + + DiameterIdentity = FQDN/Realm + + + DiameterIdentity value is used to uniquely identify either: + + * A Diameter node for purposes of duplicate connection and + routing loop detection. + + * A Realm to determine whether messages can be satisfied locally, + or whether they must be routed or redirected. + + + When a DiameterIdentity is used to identify a Diameter node the + contents of the string MUST be the FQDN of the Diameter node. If + multiple Diameter nodes run on the same host, each Diameter node + MUST be assigned a unique DiameterIdentity. If a Diameter node + can be identified by several FQDNs, a single FQDN should be picked + at startup, and used as the only DiameterIdentity for that node, + whatever the connection it is sent on. Note that in this + document, DiameterIdentity is in ASCII form in order to be + compatible with existing DNS infrastructure. See Appendix D for + interactions between the Diameter protocol and Internationalized + Domain Name (IDNs). + + + DiameterURI + + The DiameterURI MUST follow the Uniform Resource Identifiers (URI) + syntax [RFC3986] rules specified below: + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 47] + +Internet-Draft Diameter Base Protocol January 2011 + + + "aaa://" FQDN [ port ] [ transport ] [ protocol ] + + ; No transport security + + "aaas://" FQDN [ port ] [ transport ] [ protocol ] + + ; Transport security used + + FQDN = Fully Qualified Host Name + + port = ":" 1*DIGIT + + ; One of the ports used to listen for + ; incoming connections. + ; If absent, the default Diameter port + ; (3868) is assumed if no transport + ; security is used and port (TBD) when + ; transport security (TLS/TCP and DTLS/SCTP) is used. + + transport = ";transport=" transport-protocol + + ; One of the transports used to listen + ; for incoming connections. If absent, + ; the default protocol is assumed to be TCP. + ; UDP MUST NOT be used when the aaa-protocol + ; field is set to diameter. + + transport-protocol = ( "tcp" / "sctp" / "udp" ) + + protocol = ";protocol=" aaa-protocol + + ; If absent, the default AAA protocol + ; is Diameter. + + aaa-protocol = ( "diameter" / "radius" / "tacacs+" ) + + The following are examples of valid Diameter host identities: + + aaa://host.example.com;transport=tcp + aaa://host.example.com:6666;transport=tcp + aaa://host.example.com;protocol=diameter + aaa://host.example.com:6666;protocol=diameter + aaa://host.example.com:6666;transport=tcp;protocol=diameter + aaa://host.example.com:1813;transport=udp;protocol=radius + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 48] + +Internet-Draft Diameter Base Protocol January 2011 + + + Enumerated + + Enumerated is derived from the Integer32 AVP Base Format. The + definition contains a list of valid values and their + interpretation and is described in the Diameter application + introducing the AVP. + + + IPFilterRule + + The IPFilterRule format is derived from the OctetString AVP Base + Format and uses the ASCII charset. The rule syntax is a modified + subset of ipfw(8) from FreeBSD. Packets may be filtered based on + the following information that is associated with it: + + Direction (in or out) + Source and destination IP address (possibly masked) + Protocol + Source and destination port (lists or ranges) + TCP flags + IP fragment flag + IP options + ICMP types + + Rules for the appropriate direction are evaluated in order, with + the first matched rule terminating the evaluation. Each packet is + evaluated once. If no rule matches, the packet is dropped if the + last rule evaluated was a permit, and passed if the last rule was + a deny. + + IPFilterRule filters MUST follow the format: + + action dir proto from src to dst [options] + + action permit - Allow packets that match the rule. + deny - Drop packets that match the rule. + + dir "in" is from the terminal, "out" is to the + terminal. + + proto An IP protocol specified by number. The "ip" + keyword means any protocol will match. + + src and dst <address/mask> [ports] + + The <address/mask> may be specified as: + ipno An IPv4 or IPv6 number in dotted- + quad or canonical IPv6 form. Only + + + +Fajardo, et al. Expires July 24, 2011 [Page 49] + +Internet-Draft Diameter Base Protocol January 2011 + + + this exact IP number will match the + rule. + ipno/bits An IP number as above with a mask + width of the form 192.0.2.10/24. In + this case, all IP numbers from + 192.0.2.0 to 192.0.2.255 will match. + The bit width MUST be valid for the + IP version and the IP number MUST + NOT have bits set beyond the mask. + For a match to occur, the same IP + version must be present in the + packet that was used in describing + the IP address. To test for a + particular IP version, the bits part + can be set to zero. The keyword + "any" is 0.0.0.0/0 or the IPv6 + equivalent. The keyword "assigned" + is the address or set of addresses + assigned to the terminal. For IPv4, + a typical first rule is often "deny + in ip! assigned" + + The sense of the match can be inverted by + preceding an address with the not modifier (!), + causing all other addresses to be matched + instead. This does not affect the selection of + port numbers. + + With the TCP, UDP and SCTP protocols, optional + ports may be specified as: + + {port/port-port}[,ports[,...]] + + The '-' notation specifies a range of ports + (including boundaries). + + Fragmented packets that have a non-zero offset + (i.e., not the first fragment) will never match + a rule that has one or more port + specifications. See the frag option for + details on matching fragmented packets. + + options: + frag Match if the packet is a fragment and this is not + the first fragment of the datagram. frag may not + be used in conjunction with either tcpflags or + TCP/UDP port specifications. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 50] + +Internet-Draft Diameter Base Protocol January 2011 + + + ipoptions spec + Match if the IP header contains the comma + separated list of options specified in spec. The + supported IP options are: + + ssrr (strict source route), lsrr (loose source + route), rr (record packet route) and ts + (timestamp). The absence of a particular option + may be denoted with a '!'. + + tcpoptions spec + Match if the TCP header contains the comma + separated list of options specified in spec. The + supported TCP options are: + + mss (maximum segment size), window (tcp window + advertisement), sack (selective ack), ts (rfc1323 + timestamp) and cc (rfc1644 t/tcp connection + count). The absence of a particular option may + be denoted with a '!'. + + established + TCP packets only. Match packets that have the RST + or ACK bits set. + + setup TCP packets only. Match packets that have the SYN + bit set but no ACK bit. + + + tcpflags spec + TCP packets only. Match if the TCP header + contains the comma separated list of flags + specified in spec. The supported TCP flags are: + + fin, syn, rst, psh, ack and urg. The absence of a + particular flag may be denoted with a '!'. A rule + that contains a tcpflags specification can never + match a fragmented packet that has a non-zero + offset. See the frag option for details on + matching fragmented packets. + + icmptypes types + ICMP packets only. Match if the ICMP type is in + the list types. The list may be specified as any + combination of ranges or individual types + separated by commas. Both the numeric values and + the symbolic values listed below can be used. The + supported ICMP types are: + + + +Fajardo, et al. Expires July 24, 2011 [Page 51] + +Internet-Draft Diameter Base Protocol January 2011 + + + echo reply (0), destination unreachable (3), + source quench (4), redirect (5), echo request + (8), router advertisement (9), router + solicitation (10), time-to-live exceeded (11), IP + header bad (12), timestamp request (13), + timestamp reply (14), information request (15), + information reply (16), address mask request (17) + and address mask reply (18). + + There is one kind of packet that the access device MUST always + discard, that is an IP fragment with a fragment offset of one. + This is a valid packet, but it only has one use, to try to + circumvent firewalls. + + An access device that is unable to interpret or apply a deny rule + MUST terminate the session. An access device that is unable to + interpret or apply a permit rule MAY apply a more restrictive + rule. An access device MAY apply deny rules of its own before the + supplied rules, for example to protect the access device owner's + infrastructure. + + +4.4. Grouped AVP Values + + The Diameter protocol allows AVP values of type 'Grouped'. This + implies that the Data field is actually a sequence of AVPs. It is + possible to include an AVP with a Grouped type within a Grouped type, + that is, to nest them. AVPs within an AVP of type Grouped have the + same padding requirements as non-Grouped AVPs, as defined in Section + 4. + + The AVP Code numbering space of all AVPs included in a Grouped AVP is + the same as for non-grouped AVPs. Receivers of a Grouped AVP that + does not have the 'M' (mandatory) bit set and one or more of the + encapsulated AVPs within the group has the 'M' (mandatory) bit set + MAY simply be ignored if the Grouped AVP itself is unrecognized. The + rule applies even if the encapsulated AVP with its 'M' (mandatory) + bit set is further encapsulated within other sub-groups; i.e. other + Grouped AVPs embedded within the Grouped AVP. + + Every Grouped AVP defined MUST include a corresponding grammar, using + ABNF [RFC5234] (with modifications), as defined below. + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 52] + +Internet-Draft Diameter Base Protocol January 2011 + + + grouped-avp-def = <name> "::=" avp + + name-fmt = ALPHA *(ALPHA / DIGIT / "-") + + name = name-fmt + ; The name has to be the name of an AVP, + ; defined in the base or extended Diameter + ; specifications. + + avp = header [ *fixed] [ *required] [ *optional] + + header = "<" "AVP-Header:" avpcode [vendor] ">" + + avpcode = 1*DIGIT + ; The AVP Code assigned to the Grouped AVP + + vendor = 1*DIGIT + ; The Vendor-ID assigned to the Grouped AVP. + ; If absent, the default value of zero is + ; used. + +4.4.1. Example AVP with a Grouped Data type + + The Example-AVP (AVP Code 999999) is of type Grouped and is used to + clarify how Grouped AVP values work. The Grouped Data field has the + following ABNF grammar: + + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 53] + +Internet-Draft Diameter Base Protocol January 2011 + + + Example-AVP ::= < AVP Header: 999999 > + { Origin-Host } + 1*{ Session-Id } + *[ AVP ] + + An Example-AVP with Grouped Data follows. + + The Origin-Host AVP is required (Section 6.3). In this case: + + Origin-Host = "example.com". + + + One or more Session-Ids must follow. Here there are two: + + Session-Id = + "grump.example.com:33041;23432;893;0AF3B81" + + Session-Id = + "grump.example.com:33054;23561;2358;0AF3B82" + + optional AVPs included are + + Recovery-Policy = <binary> + 2163bc1d0ad82371f6bc09484133c3f09ad74a0dd5346d54195a7cf0b35 + 2cabc881839a4fdcfbc1769e2677a4c1fb499284c5f70b48f58503a45c5 + c2d6943f82d5930f2b7c1da640f476f0e9c9572a50db8ea6e51e1c2c7bd + f8bb43dc995144b8dbe297ac739493946803e1cee3e15d9b765008a1b2a + cf4ac777c80041d72c01e691cf751dbf86e85f509f3988e5875dc905119 + 26841f00f0e29a6d1ddc1a842289d440268681e052b30fb638045f7779c + 1d873c784f054f688f5001559ecff64865ef975f3e60d2fd7966b8c7f92 + + Futuristic-Acct-Record = <binary> + fe19da5802acd98b07a5b86cb4d5d03f0314ab9ef1ad0b67111ff3b90a0 + 57fe29620bf3585fd2dd9fcc38ce62f6cc208c6163c008f4258d1bc88b8 + 17694a74ccad3ec69269461b14b2e7a4c111fb239e33714da207983f58c + 41d018d56fe938f3cbf089aac12a912a2f0d1923a9390e5f789cb2e5067 + d3427475e49968f841 + + The data for the optional AVPs is represented in hex since the format + of these AVPs is neither known at the time of definition of the + Example-AVP group, nor (likely) at the time when the example instance + of this AVP is interpreted - except by Diameter implementations which + support the same set of AVPs. The encoding example illustrates how + padding is used and how length fields are calculated. Also note that + AVPs may be present in the Grouped AVP value which the receiver + cannot interpret (here, the Recover-Policy and Futuristic-Acct-Record + AVPs). The length of the Example-AVP is the sum of all the length of + the member AVPs including their padding plus the Example-AVP header + + + +Fajardo, et al. Expires July 24, 2011 [Page 54] + +Internet-Draft Diameter Base Protocol January 2011 + + + size. + + + This AVP would be encoded as follows: + + 0 1 2 3 4 5 6 7 + +-------+-------+-------+-------+-------+-------+-------+-------+ + 0 | Example AVP Header (AVP Code = 999999), Length = 496 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 8 | Origin-Host AVP Header (AVP Code = 264), Length = 19 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 16 | 'e' | 'x' | 'a' | 'm' | 'p' | 'l' | 'e' | '.' | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 24 | 'c' | 'o' | 'm' |Padding| Session-Id AVP Header | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 32 | (AVP Code = 263), Length = 49 | 'g' | 'r' | 'u' | 'm' | + +-------+-------+-------+-------+-------+-------+-------+-------+ + . . . + +-------+-------+-------+-------+-------+-------+-------+-------+ + 72 | 'F' | '3' | 'B' | '8' | '1' |Padding|Padding|Padding| + +-------+-------+-------+-------+-------+-------+-------+-------+ + 80 | Session-Id AVP Header (AVP Code = 263), Length = 50 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 88 | 'g' | 'r' | 'u' | 'm' | 'p' | '.' | 'e' | 'x' | + +-------+-------+-------+-------+-------+-------+-------+-------+ + . . . + +-------+-------+-------+-------+-------+-------+-------+-------+ + 120| '5' | '8' | ';' | '0' | 'A' | 'F' | '3' | 'B' | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 128| '8' | '2' |Padding|Padding| Recovery-Policy Header (AVP | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 136| Code = 8341), Length = 223 | 0x21 | 0x63 | 0xbc | 0x1d | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 144| 0x0a | 0xd8 | 0x23 | 0x71 | 0xf6 | 0xbc | 0x09 | 0x48 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + . . . + +-------+-------+-------+-------+-------+-------+-------+-------+ + 352| 0x8c | 0x7f | 0x92 |Padding| Futuristic-Acct-Record Header | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 328|(AVP Code = 15930),Length = 137| 0xfe | 0x19 | 0xda | 0x58 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 336| 0x02 | 0xac | 0xd9 | 0x8b | 0x07 | 0xa5 | 0xb8 | 0xc6 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + . . . + +-------+-------+-------+-------+-------+-------+-------+-------+ + 488| 0xe4 | 0x99 | 0x68 | 0xf8 | 0x41 |Padding|Padding|Padding| + +-------+-------+-------+-------+-------+-------+-------+-------+ + + + + +Fajardo, et al. Expires July 24, 2011 [Page 55] + +Internet-Draft Diameter Base Protocol January 2011 + + +4.5. Diameter Base Protocol AVPs + + The following table describes the Diameter AVPs defined in the base + protocol, their AVP Code values, types, possible flag values. + + Due to space constraints, the short form DiamIdent is used to + represent DiameterIdentity. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 56] + +Internet-Draft Diameter Base Protocol January 2011 + + + +----------+ + | AVP Flag | + | rules | + |----+-----| + AVP Section | |MUST | + Attribute Name Code Defined Data Type |MUST| NOT | + -----------------------------------------|----+-----| + Acct- 85 9.8.2 Unsigned32 | M | V | + Interim-Interval | | | + Accounting- 483 9.8.7 Enumerated | M | V | + Realtime-Required | | | + Acct- 50 9.8.5 UTF8String | M | V | + Multi-Session-Id | | | + Accounting- 485 9.8.3 Unsigned32 | M | V | + Record-Number | | | + Accounting- 480 9.8.1 Enumerated | M | V | + Record-Type | | | + Accounting- 44 9.8.4 OctetString| M | V | + Session-Id | | | + Accounting- 287 9.8.6 Unsigned64 | M | V | + Sub-Session-Id | | | + Acct- 259 6.9 Unsigned32 | M | V | + Application-Id | | | + Auth- 258 6.8 Unsigned32 | M | V | + Application-Id | | | + Auth-Request- 274 8.7 Enumerated | M | V | + Type | | | + Authorization- 291 8.9 Unsigned32 | M | V | + Lifetime | | | + Auth-Grace- 276 8.10 Unsigned32 | M | V | + Period | | | + Auth-Session- 277 8.11 Enumerated | M | V | + State | | | + Re-Auth-Request- 285 8.12 Enumerated | M | V | + Type | | | + Class 25 8.20 OctetString| M | V | + Destination-Host 293 6.5 DiamIdent | M | V | + Destination- 283 6.6 DiamIdent | M | V | + Realm | | | + Disconnect-Cause 273 5.4.3 Enumerated | M | V | + Error-Message 281 7.3 UTF8String | | V,M | + Error-Reporting- 294 7.4 DiamIdent | | V,M | + Host | | | + Event-Timestamp 55 8.21 Time | M | V | + Experimental- 297 7.6 Grouped | M | V | + Result | | | + -----------------------------------------|----+-----| + + + + +Fajardo, et al. Expires July 24, 2011 [Page 57] + +Internet-Draft Diameter Base Protocol January 2011 + + + +----------+ + | AVP Flag | + | rules | + |----+-----| + AVP Section | |MUST | + Attribute Name Code Defined Data Type |MUST| NOT | + -----------------------------------------|----+-----| + Experimental- 298 7.7 Unsigned32 | M | V | + Result-Code | | | + Failed-AVP 279 7.5 Grouped | M | V | + Firmware- 267 5.3.4 Unsigned32 | | V,M | + Revision | | | + Host-IP-Address 257 5.3.5 Address | M | V | + Inband-Security | M | V | + -Id 299 6.10 Unsigned32 | | | + Multi-Round- 272 8.19 Unsigned32 | M | V | + Time-Out | | | + Origin-Host 264 6.3 DiamIdent | M | V | + Origin-Realm 296 6.4 DiamIdent | M | V | + Origin-State-Id 278 8.16 Unsigned32 | M | V | + Product-Name 269 5.3.7 UTF8String | | V,M | + Proxy-Host 280 6.7.3 DiamIdent | M | V | + Proxy-Info 284 6.7.2 Grouped | M | V | + Proxy-State 33 6.7.4 OctetString| M | V | + Redirect-Host 292 6.12 DiamURI | M | V | + Redirect-Host- 261 6.13 Enumerated | M | V | + Usage | | | + Redirect-Max- 262 6.14 Unsigned32 | M | V | + Cache-Time | | | + Result-Code 268 7.1 Unsigned32 | M | V | + Route-Record 282 6.7.1 DiamIdent | M | V | + Session-Id 263 8.8 UTF8String | M | V | + Session-Timeout 27 8.13 Unsigned32 | M | V | + Session-Binding 270 8.17 Unsigned32 | M | V | + Session-Server- 271 8.18 Enumerated | M | V | + Failover | | | + Supported- 265 5.3.6 Unsigned32 | M | V | + Vendor-Id | | | + Termination- 295 8.15 Enumerated | M | V | + Cause | | | + User-Name 1 8.14 UTF8String | M | V | + Vendor-Id 266 5.3.3 Unsigned32 | M | V | + Vendor-Specific- 260 6.11 Grouped | M | V | + Application-Id | | | + -----------------------------------------|----+-----| + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 58] + +Internet-Draft Diameter Base Protocol January 2011 + + +5. Diameter Peers + + This section describes how Diameter nodes establish connections and + communicate with peers. + +5.1. Peer Connections + + Connections between diameter peers are established using their valid + DiameterIdentity. A Diameter node initiating a connection to a peer + MUST know the peers DiameterIdentity. Methods for discovering a + Diameter peer can be found in Section 5.2. + + Although a Diameter node may have many possible peers that it is able + to communicate with, it may not be economical to have an established + connection to all of them. At a minimum, a Diameter node SHOULD have + an established connection with two peers per realm, known as the + primary and secondary peers. Of course, a node MAY have additional + connections, if it is deemed necessary. Typically, all messages for + a realm are sent to the primary peer, but in the event that failover + procedures are invoked, any pending requests are sent to the + secondary peer. However, implementations are free to load balance + requests between a set of peers. + + Note that a given peer MAY act as a primary for a given realm, while + acting as a secondary for another realm. + + When a peer is deemed suspect, which could occur for various reasons, + including not receiving a DWA within an allotted timeframe, no new + requests should be forwarded to the peer, but failover procedures are + invoked. When an active peer is moved to this mode, additional + connections SHOULD be established to ensure that the necessary number + of active connections exists. + + There are two ways that a peer is removed from the suspect peer list: + + + 1. The peer is no longer reachable, causing the transport connection + to be shutdown. The peer is moved to the closed state. + + 2. Three watchdog messages are exchanged with accepted round trip + times, and the connection to the peer is considered stabilized. + + In the event the peer being removed is either the primary or + secondary, an alternate peer SHOULD replace the deleted peer, and + assume the role of either primary or secondary. + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 59] + +Internet-Draft Diameter Base Protocol January 2011 + + +5.2. Diameter Peer Discovery + + Allowing for dynamic Diameter agent discovery will make it possible + for simpler and more robust deployment of Diameter services. In + order to promote interoperable implementations of Diameter peer + discovery, the following mechanisms are described. These are based + on existing IETF standards. The first option (manual configuration) + MUST be supported by all Diameter nodes, while the latter option + (DNS) MAY be supported. + + There are two cases where Diameter peer discovery may be performed. + The first is when a Diameter client needs to discover a first-hop + Diameter agent. The second case is when a Diameter agent needs to + discover another agent - for further handling of a Diameter + operation. In both cases, the following 'search order' is + recommended: + + + 1. The Diameter implementation consults its list of static + (manually) configured Diameter agent locations. These will be + used if they exist and respond. + + + 2. The Diameter implementation performs a NAPTR query for a server + in a particular realm. The Diameter implementation has to know + in advance which realm to look for a Diameter agent. This could + be deduced, for example, from the 'realm' in a NAI that a + Diameter implementation needed to perform a Diameter operation + on. + + The NAPTR usage in Diameter follows the S-NAPTR DDDS application + [RFC3958] in which the SERVICE field includes tags for the + desired application and supported application protocol. The + application service tag for a Diameter application is 'aaa' and + the supported application protocol tags are 'diameter.tcp', + 'diameter.sctp', 'diameter.dtls' or 'diameter.tls.tcp'. + + The client can follow the resolution process defined by the + S-NAPTR DDDS [RFC3958] application to find a matching SRV, A or + AAAA record of a suitable peer. The domain suffixes in the NAPTR + replacement field SHOULD match the domain of the original query. + An example can be found in Appendix B. + + 3. If no NAPTR records are found, the requester directly queries for + SRV records '_diameter._sctp'.realm, '_diameter._dtls'.realm, + '_diameter._tcp'.realm and '_diameter._tls'.realm depending on + the requesters network protocol capabilities. If SRV records are + found then the requester can perform address record query (A RR's + + + +Fajardo, et al. Expires July 24, 2011 [Page 60] + +Internet-Draft Diameter Base Protocol January 2011 + + + and/or AAAA RR's) for the target hostname specified in the SRV + records. If no SRV records are found, the requester gives up. + + If the server is using a site certificate, the domain name in the + NAPTR query and the domain name in the replacement field MUST both be + valid based on the site certificate handed out by the server in the + TLS/TCP and DTLS/SCTP or IKE exchange. Similarly, the domain name in + the SRV query and the domain name in the target in the SRV record + MUST both be valid based on the same site certificate. Otherwise, an + attacker could modify the DNS records to contain replacement values + in a different domain, and the client could not validate that this + was the desired behavior, or the result of an attack. + + Also, the Diameter Peer MUST check to make sure that the discovered + peers are authorized to act in its role. Authentication via IKE or + TLS/TCP and DTLS/SCTP, or validation of DNS RRs via DNSSEC is not + sufficient to conclude this. For example, a web server may have + obtained a valid TLS/TCP and DTLS/SCTP certificate, and secured RRs + may be included in the DNS, but this does not imply that it is + authorized to act as a Diameter Server. + + Authorization can be achieved for example, by configuration of a + Diameter Server CA. Alternatively this can be achieved by definition + of OIDs within TLS/TCP and DTLS/SCTP or IKE certificates so as to + signify Diameter Server authorization. + + A dynamically discovered peer causes an entry in the Peer Table (see + Section 2.6) to be created. Note that entries created via DNS MUST + expire (or be refreshed) within the DNS TTL. If a peer is discovered + outside of the local realm, a routing table entry (see Section 2.7) + for the peer's realm is created. The routing table entry's + expiration MUST match the peer's expiration value. + +5.3. Capabilities Exchange + + When two Diameter peers establish a transport connection, they MUST + exchange the Capabilities Exchange messages, as specified in the peer + state machine (see Section 5.6). This message allows the discovery + of a peer's identity and its capabilities (protocol version number, + supported Diameter applications, security mechanisms, etc.) + + The receiver only issues commands to its peers that have advertised + support for the Diameter application that defines the command. A + Diameter node MUST cache the supported applications in order to + ensure that unrecognized commands and/or AVPs are not unnecessarily + sent to a peer. + + A receiver of a Capabilities-Exchange-Req (CER) message that does not + + + +Fajardo, et al. Expires July 24, 2011 [Page 61] + +Internet-Draft Diameter Base Protocol January 2011 + + + have any applications in common with the sender MUST return a + Capabilities-Exchange-Answer (CEA) with the Result-Code AVP set to + DIAMETER_NO_COMMON_APPLICATION, and SHOULD disconnect the transport + layer connection. Note that receiving a CER or CEA from a peer + advertising itself as a Relay (see Section 2.4) MUST be interpreted + as having common applications with the peer. + + The receiver of the Capabilities-Exchange-Request (CER) MUST + determine common applications by computing the intersection of its + own set of supported Application Id against all of the application + identifier AVPs (Auth-Application-Id, Acct-Application-Id and Vendor- + Specific-Application-Id) present in the CER. The value of the + Vendor-Id AVP in the Vendor-Specific-Application-Id MUST NOT be used + during computation. The sender of the Capabilities-Exchange-Answer + (CEA) SHOULD include all of its supported applications as a hint to + the receiver regarding all of its application capabilities. + + Diameter implementations SHOULD first attempt to establish a TLS/TCP + and DTLS/SCTP connection prior to the CER/CEA exchange. This + protects the capabilities information of both peers. To support + older Diameter implementations that do not fully conform to this + document, the transport security MAY still be negotiated via Inband- + Security AVP. In this case, the receiver of a Capabilities-Exchange- + Req (CER) message that does not have any security mechanisms in + common with the sender MUST return a Capabilities-Exchange-Answer + (CEA) with the Result-Code AVP set to DIAMETER_NO_COMMON_SECURITY, + and SHOULD disconnect the transport layer connection. + + CERs received from unknown peers MAY be silently discarded, or a CEA + MAY be issued with the Result-Code AVP set to DIAMETER_UNKNOWN_PEER. + In both cases, the transport connection is closed. If the local + policy permits receiving CERs from unknown hosts, a successful CEA + MAY be returned. If a CER from an unknown peer is answered with a + successful CEA, the lifetime of the peer entry is equal to the + lifetime of the transport connection. In case of a transport + failure, all the pending transactions destined to the unknown peer + can be discarded. + + The CER and CEA messages MUST NOT be proxied, redirected or relayed. + + Since the CER/CEA messages cannot be proxied, it is still possible + that an upstream agent receives a message for which it has no + available peers to handle the application that corresponds to the + Command-Code. In such instances, the 'E' bit is set in the answer + message (see Section 7.) with the Result-Code AVP set to + DIAMETER_UNABLE_TO_DELIVER to inform the downstream to take action + (e.g., re-routing request to an alternate peer). + + + + +Fajardo, et al. Expires July 24, 2011 [Page 62] + +Internet-Draft Diameter Base Protocol January 2011 + + + With the exception of the Capabilities-Exchange-Request message, a + message of type Request that includes the Auth-Application-Id or + Acct-Application-Id AVPs, or a message with an application-specific + command code, MAY only be forwarded to a host that has explicitly + advertised support for the application (or has advertised the Relay + Application Id). + +5.3.1. Capabilities-Exchange-Request + + The Capabilities-Exchange-Request (CER), indicated by the Command- + Code set to 257 and the Command Flags' 'R' bit set, is sent to + exchange local capabilities. Upon detection of a transport failure, + this message MUST NOT be sent to an alternate peer. + + When Diameter is run over SCTP [RFC4960] or DTLS/SCTP [RFC6083], + which allow for connections to span multiple interfaces and multiple + IP addresses, the Capabilities-Exchange-Request message MUST contain + one Host-IP- Address AVP for each potential IP address that MAY be + locally used when transmitting Diameter messages. + + Message Format + + <CER> ::= < Diameter Header: 257, REQ > + { Origin-Host } + { Origin-Realm } + 1* { Host-IP-Address } + { Vendor-Id } + { Product-Name } + [ Origin-State-Id ] + * [ Supported-Vendor-Id ] + * [ Auth-Application-Id ] + * [ Inband-Security-Id ] + * [ Acct-Application-Id ] + * [ Vendor-Specific-Application-Id ] + [ Firmware-Revision ] + * [ AVP ] + +5.3.2. Capabilities-Exchange-Answer + + The Capabilities-Exchange-Answer (CEA), indicated by the Command-Code + set to 257 and the Command Flags' 'R' bit cleared, is sent in + response to a CER message. + + When Diameter is run over SCTP [RFC4960] or DTLS/SCTP [RFC6083], + which allow connections to span multiple interfaces, hence, multiple + IP addresses, the Capabilities-Exchange-Answer message MUST contain + one Host-IP-Address AVP for each potential IP address that MAY be + locally used when transmitting Diameter messages. + + + +Fajardo, et al. Expires July 24, 2011 [Page 63] + +Internet-Draft Diameter Base Protocol January 2011 + + + Message Format + + <CEA> ::= < Diameter Header: 257 > + { Result-Code } + { Origin-Host } + { Origin-Realm } + 1* { Host-IP-Address } + { Vendor-Id } + { Product-Name } + [ Origin-State-Id ] + [ Error-Message ] + [ Failed-AVP ] + * [ Supported-Vendor-Id ] + * [ Auth-Application-Id ] + * [ Inband-Security-Id ] + * [ Acct-Application-Id ] + * [ Vendor-Specific-Application-Id ] + [ Firmware-Revision ] + * [ AVP ] + +5.3.3. Vendor-Id AVP + + The Vendor-Id AVP (AVP Code 266) is of type Unsigned32 and contains + the IANA "SMI Network Management Private Enterprise Codes" [RFC3232] + value assigned to the vendor of the Diameter device. It is + envisioned that the combination of the Vendor-Id, Product-Name + (Section 5.3.7) and the Firmware-Revision (Section 5.3.4) AVPs may + provide useful debugging information. + + A Vendor-Id value of zero in the CER or CEA messages is reserved and + indicates that this field is ignored. + +5.3.4. Firmware-Revision AVP + + The Firmware-Revision AVP (AVP Code 267) is of type Unsigned32 and is + used to inform a Diameter peer of the firmware revision of the + issuing device. + + For devices that do not have a firmware revision (general purpose + computers running Diameter software modules, for instance), the + revision of the Diameter software module may be reported instead. + +5.3.5. Host-IP-Address AVP + + The Host-IP-Address AVP (AVP Code 257) is of type Address and is used + to inform a Diameter peer of the sender's IP address. All source + addresses that a Diameter node expects to use with SCTP [RFC4960] or + DTLS/SCTP [RFC6083] MUST be advertised in the CER and CEA messages by + + + +Fajardo, et al. Expires July 24, 2011 [Page 64] + +Internet-Draft Diameter Base Protocol January 2011 + + + including a Host-IP-Address AVP for each address. + +5.3.6. Supported-Vendor-Id AVP + + The Supported-Vendor-Id AVP (AVP Code 265) is of type Unsigned32 and + contains the IANA "SMI Network Management Private Enterprise Codes" + [RFC3232] value assigned to a vendor other than the device vendor but + including the application vendor. This is used in the CER and CEA + messages in order to inform the peer that the sender supports (a + subset of) the vendor-specific AVPs defined by the vendor identified + in this AVP. The value of this AVP MUST NOT be set to zero. + Multiple instances of this AVP containing the same value SHOULD NOT + be sent. + +5.3.7. Product-Name AVP + + The Product-Name AVP (AVP Code 269) is of type UTF8String, and + contains the vendor assigned name for the product. The Product-Name + AVP SHOULD remain constant across firmware revisions for the same + product. + +5.4. Disconnecting Peer connections + + When a Diameter node disconnects one of its transport connections, + its peer cannot know the reason for the disconnect, and will most + likely assume that a connectivity problem occurred, or that the peer + has rebooted. In these cases, the peer may periodically attempt to + reconnect, as stated in Section 2.1. In the event that the + disconnect was a result of either a shortage of internal resources, + or simply that the node in question has no intentions of forwarding + any Diameter messages to the peer in the foreseeable future, a + periodic connection request would not be welcomed. The + Disconnection-Reason AVP contains the reason the Diameter node issued + the Disconnect-Peer-Request message. + + The Disconnect-Peer-Request message is used by a Diameter node to + inform its peer of its intent to disconnect the transport layer, and + that the peer shouldn't reconnect unless it has a valid reason to do + so (e.g., message to be forwarded). Upon receipt of the message, the + Disconnect-Peer-Answer is returned, which SHOULD contain an error if + messages have recently been forwarded, and are likely in flight, + which would otherwise cause a race condition. + + The receiver of the Disconnect-Peer-Answer initiates the transport + disconnect. The sender of the Disconnect-Peer-Answer should be able + to detect the transport closure and cleanup the connection. + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 65] + +Internet-Draft Diameter Base Protocol January 2011 + + +5.4.1. Disconnect-Peer-Request + + The Disconnect-Peer-Request (DPR), indicated by the Command-Code set + to 282 and the Command Flags' 'R' bit set, is sent to a peer to + inform its intentions to shutdown the transport connection. Upon + detection of a transport failure, this message MUST NOT be sent to an + alternate peer. + + Message Format + + <DPR> ::= < Diameter Header: 282, REQ > + { Origin-Host } + { Origin-Realm } + { Disconnect-Cause } + * [ AVP ] + +5.4.2. Disconnect-Peer-Answer + + The Disconnect-Peer-Answer (DPA), indicated by the Command-Code set + to 282 and the Command Flags' 'R' bit cleared, is sent as a response + to the Disconnect-Peer-Request message. Upon receipt of this + message, the transport connection is shutdown. + + Message Format + + <DPA> ::= < Diameter Header: 282 > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ Error-Message ] + [ Failed-AVP ] + * [ AVP ] + +5.4.3. Disconnect-Cause AVP + + The Disconnect-Cause AVP (AVP Code 273) is of type Enumerated. A + Diameter node MUST include this AVP in the Disconnect-Peer-Request + message to inform the peer of the reason for its intention to + shutdown the transport connection. The following values are + supported: + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 66] + +Internet-Draft Diameter Base Protocol January 2011 + + + REBOOTING 0 + A scheduled reboot is imminent. Receiver of DPR with above result + code MAY attempt reconnection. + + BUSY 1 + The peer's internal resources are constrained, and it has + determined that the transport connection needs to be closed. + Receiver of DPR with above result code SHOULD NOT attempt + reconnection. + + DO_NOT_WANT_TO_TALK_TO_YOU 2 + The peer has determined that it does not see a need for the + transport connection to exist, since it does not expect any + messages to be exchanged in the near future. Receiver of DPR + with above result code SHOULD NOT attempt reconnection. + +5.5. Transport Failure Detection + + Given the nature of the Diameter protocol, it is recommended that + transport failures be detected as soon as possible. Detecting such + failures will minimize the occurrence of messages sent to unavailable + agents, resulting in unnecessary delays, and will provide better + failover performance. The Device-Watchdog-Request and Device- + Watchdog-Answer messages, defined in this section, are used to pro- + actively detect transport failures. + +5.5.1. Device-Watchdog-Request + + The Device-Watchdog-Request (DWR), indicated by the Command-Code set + to 280 and the Command Flags' 'R' bit set, is sent to a peer when no + traffic has been exchanged between two peers (see Section 5.5.3). + Upon detection of a transport failure, this message MUST NOT be sent + to an alternate peer. + + Message Format + + <DWR> ::= < Diameter Header: 280, REQ > + { Origin-Host } + { Origin-Realm } + [ Origin-State-Id ] + * [ AVP ] + +5.5.2. Device-Watchdog-Answer + + The Device-Watchdog-Answer (DWA), indicated by the Command-Code set + to 280 and the Command Flags' 'R' bit cleared, is sent as a response + to the Device-Watchdog-Request message. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 67] + +Internet-Draft Diameter Base Protocol January 2011 + + + Message Format + + <DWA> ::= < Diameter Header: 280 > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ Error-Message ] + [ Failed-AVP ] + [ Origin-State-Id ] + * [ AVP ] + +5.5.3. Transport Failure Algorithm + + The transport failure algorithm is defined in [RFC3539]. All + Diameter implementations MUST support the algorithm defined in the + specification in order to be compliant to the Diameter base protocol. + +5.5.4. Failover and Failback Procedures + + In the event that a transport failure is detected with a peer, it is + necessary for all pending request messages to be forwarded to an + alternate agent, if possible. This is commonly referred to as + failover. + + In order for a Diameter node to perform failover procedures, it is + necessary for the node to maintain a pending message queue for a + given peer. When an answer message is received, the corresponding + request is removed from the queue. The Hop-by-Hop Identifier field + is used to match the answer with the queued request. + + When a transport failure is detected, if possible all messages in the + queue are sent to an alternate agent with the T flag set. On booting + a Diameter client or agent, the T flag is also set on any records + still remaining to be transmitted in non-volatile storage. An + example of a case where it is not possible to forward the message to + an alternate server is when the message has a fixed destination, and + the unavailable peer is the message's final destination (see + Destination-Host AVP). Such an error requires that the agent return + an answer message with the 'E' bit set and the Result-Code AVP set to + DIAMETER_UNABLE_TO_DELIVER. + + It is important to note that multiple identical requests or answers + MAY be received as a result of a failover. The End-to-End Identifier + field in the Diameter header along with the Origin-Host AVP MUST be + used to identify duplicate messages. + + As described in Section 2.1, a connection request should be + periodically attempted with the failed peer in order to re-establish + + + +Fajardo, et al. Expires July 24, 2011 [Page 68] + +Internet-Draft Diameter Base Protocol January 2011 + + + the transport connection. Once a connection has been successfully + established, messages can once again be forwarded to the peer. This + is commonly referred to as failback. + +5.6. Peer State Machine + + This section contains a finite state machine that MUST be observed by + all Diameter implementations. Each Diameter node MUST follow the + state machine described below when communicating with each peer. + Multiple actions are separated by commas, and may continue on + succeeding lines, as space requires. Similarly, state and next state + may also span multiple lines, as space requires. + + This state machine is closely coupled with the state machine + described in [RFC3539], which is used to open, close, failover, + probe, and reopen transport connections. Note in particular that + [RFC3539] requires the use of watchdog messages to probe connections. + For Diameter, DWR and DWA messages are to be used. + + I- is used to represent the initiator (connecting) connection, while + the R- is used to represent the responder (listening) connection. + The lack of a prefix indicates that the event or action is the same + regardless of the connection on which the event occurred. + + The stable states that a state machine may be in are Closed, I-Open + and R-Open; all other states are intermediate. Note that I-Open and + R-Open are equivalent except for whether the initiator or responder + transport connection is used for communication. + + A CER message is always sent on the initiating connection immediately + after the connection request is successfully completed. In the case + of an election, one of the two connections will shut down. The + responder connection will survive if the Origin-Host of the local + Diameter entity is higher than that of the peer; the initiator + connection will survive if the peer's Origin-Host is higher. All + subsequent messages are sent on the surviving connection. Note that + the results of an election on one peer are guaranteed to be the + inverse of the results on the other. + + For TLS/TCP and DTLS/SCTP usage, TLS/TCP and DTLS/SCTP handshake + SHOULD begin when both ends are in the closed state prior to any + Diameter message exchanges. The TLS/TCP and DTLS/SCTP connection + SHOULD be established before sending any CER or CEA message to secure + and protect the capabilities information of both peers. The TLS/TCP + and DTLS/SCTP connection SHOULD be disconnected when the state + machine moves to the closed state. When connecting to responders + that do not conform to this document (i.e. older Diameter + implementations that are not prepared to received TLS/TCP and DTLS/ + + + +Fajardo, et al. Expires July 24, 2011 [Page 69] + +Internet-Draft Diameter Base Protocol January 2011 + + + SCTP connections in the closed state), the initial TLS/TCP and DTLS/ + SCTP connection attempt will fail. The initiator MAY then attempt to + connect via TCP or SCTP and initiate the TLS/TCP and DTLS/SCTP + handshake when both ends are in the open state. If the handshake is + successful, all further messages will be sent via TLS/TCP and DTLS/ + SCTP. If the handshake fails, both ends move to the closed state. + + The state machine constrains only the behavior of a Diameter + implementation as seen by Diameter peers through events on the wire. + + Any implementation that produces equivalent results is considered + compliant. + + state event action next state + ----------------------------------------------------------------- + Closed Start I-Snd-Conn-Req Wait-Conn-Ack + R-Conn-CER R-Accept, R-Open + Process-CER, + R-Snd-CEA + + Wait-Conn-Ack I-Rcv-Conn-Ack I-Snd-CER Wait-I-CEA + I-Rcv-Conn-Nack Cleanup Closed + R-Conn-CER R-Accept, Wait-Conn-Ack/ + Process-CER Elect + Timeout Error Closed + + Wait-I-CEA I-Rcv-CEA Process-CEA I-Open + R-Conn-CER R-Accept, Wait-Returns + Process-CER, + Elect + I-Peer-Disc I-Disc Closed + I-Rcv-Non-CEA Error Closed + Timeout Error Closed + + Wait-Conn-Ack/ I-Rcv-Conn-Ack I-Snd-CER,Elect Wait-Returns + Elect I-Rcv-Conn-Nack R-Snd-CEA R-Open + R-Peer-Disc R-Disc Wait-Conn-Ack + R-Conn-CER R-Reject Wait-Conn-Ack/ + Elect + Timeout Error Closed + + Wait-Returns Win-Election I-Disc,R-Snd-CEA R-Open + I-Peer-Disc I-Disc, R-Open + R-Snd-CEA + I-Rcv-CEA R-Disc I-Open + R-Peer-Disc R-Disc Wait-I-CEA + R-Conn-CER R-Reject Wait-Returns + Timeout Error Closed + + + +Fajardo, et al. Expires July 24, 2011 [Page 70] + +Internet-Draft Diameter Base Protocol January 2011 + + + R-Open Send-Message R-Snd-Message R-Open + R-Rcv-Message Process R-Open + R-Rcv-DWR Process-DWR, R-Open + R-Snd-DWA + R-Rcv-DWA Process-DWA R-Open + R-Conn-CER R-Reject R-Open + Stop R-Snd-DPR Closing + R-Rcv-DPR R-Snd-DPA, Closed + R-Disc + R-Peer-Disc R-Disc Closed + + I-Open Send-Message I-Snd-Message I-Open + I-Rcv-Message Process I-Open + I-Rcv-DWR Process-DWR, I-Open + I-Snd-DWA + I-Rcv-DWA Process-DWA I-Open + R-Conn-CER R-Reject I-Open + Stop I-Snd-DPR Closing + I-Rcv-DPR I-Snd-DPA, Closed + I-Disc + I-Peer-Disc I-Disc Closed + + Closing I-Rcv-DPA I-Disc Closed + R-Rcv-DPA R-Disc Closed + Timeout Error Closed + I-Peer-Disc I-Disc Closed + R-Peer-Disc R-Disc Closed + +5.6.1. Incoming connections + + When a connection request is received from a Diameter peer, it is + not, in the general case, possible to know the identity of that peer + until a CER is received from it. This is because host and port + determine the identity of a Diameter peer; and the source port of an + incoming connection is arbitrary. Upon receipt of CER, the identity + of the connecting peer can be uniquely determined from Origin-Host. + + For this reason, a Diameter peer must employ logic separate from the + state machine to receive connection requests, accept them, and await + CER. Once CER arrives on a new connection, the Origin-Host that + identifies the peer is used to locate the state machine associated + with that peer, and the new connection and CER are passed to the + state machine as an R-Conn-CER event. + + The logic that handles incoming connections SHOULD close and discard + the connection if any message other than CER arrives, or if an + implementation-defined timeout occurs prior to receipt of CER. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 71] + +Internet-Draft Diameter Base Protocol January 2011 + + + Because handling of incoming connections up to and including receipt + of CER requires logic, separate from that of any individual state + machine associated with a particular peer, it is described separately + in this section rather than in the state machine above. + +5.6.2. Events + + Transitions and actions in the automaton are caused by events. In + this section, we will ignore the -I and -R prefix, since the actual + event would be identical, but would occur on one of two possible + connections. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 72] + +Internet-Draft Diameter Base Protocol January 2011 + + + Start The Diameter application has signaled that a + connection should be initiated with the peer. + + R-Conn-CER An acknowledgement is received stating that the + transport connection has been established, and the + associated CER has arrived. + + Rcv-Conn-Ack A positive acknowledgement is received confirming that + the transport connection is established. + + Rcv-Conn-Nack A negative acknowledgement was received stating that + the transport connection was not established. + + Timeout An application-defined timer has expired while waiting + for some event. + + Rcv-CER A CER message from the peer was received. + + Rcv-CEA A CEA message from the peer was received. + + Rcv-Non-CEA A message other than CEA from the peer was received. + + Peer-Disc A disconnection indication from the peer was received. + + Rcv-DPR A DPR message from the peer was received. + + Rcv-DPA A DPA message from the peer was received. + + Win-Election An election was held, and the local node was the + winner. + + Send-Message A message is to be sent. + + Rcv-Message A message other than CER, CEA, DPR, DPA, DWR or DWA + was received. + + Stop The Diameter application has signaled that a + connection should be terminated (e.g., on system + shutdown). + +5.6.3. Actions + + Actions in the automaton are caused by events and typically indicate + the transmission of packets and/or an action to be taken on the + connection. In this section we will ignore the I- and R-prefix, + since the actual action would be identical, but would occur on one of + two possible connections. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 73] + +Internet-Draft Diameter Base Protocol January 2011 + + + Snd-Conn-Req A transport connection is initiated with the peer. + + Accept The incoming connection associated with the R-Conn-CER + is accepted as the responder connection. + + Reject The incoming connection associated with the R-Conn-CER + is disconnected. + + Process-CER The CER associated with the R-Conn-CER is processed. + Snd-CER A CER message is sent to the peer. + + Snd-CEA A CEA message is sent to the peer. + + Cleanup If necessary, the connection is shutdown, and any + local resources are freed. + + Error The transport layer connection is disconnected, + either politely or abortively, in response to + an error condition. Local resources are freed. + + Process-CEA A received CEA is processed. + + Snd-DPR A DPR message is sent to the peer. + + Snd-DPA A DPA message is sent to the peer. + + Disc The transport layer connection is disconnected, + and local resources are freed. + + Elect An election occurs (see Section 5.6.4 for more + information). + + Snd-Message A message is sent. + + Snd-DWR A DWR message is sent. + + Snd-DWA A DWA message is sent. + + Process-DWR The DWR message is serviced. + + Process-DWA The DWA message is serviced. + + Process A message is serviced. + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 74] + +Internet-Draft Diameter Base Protocol January 2011 + + +5.6.4. The Election Process + + The election is performed on the responder. The responder compares + the Origin-Host received in the CER with its own Origin-Host as two + streams of octets. If the local Origin-Host lexicographically + succeeds the received Origin-Host a Win-Election event is issued + locally. Diameter identities are in ASCII form therefore the lexical + comparison is consistent with DNS case insensitivity where octets + that fall in the ASCII range 'a' through 'z' MUST compare equally to + their upper-case counterparts between 'A' and 'Z'. See Appendix D + for interactions between the Diameter protocol and Internationalized + Domain Name (IDNs). + + The winner of the election MUST close the connection it initiated. + Historically, maintaining the responder side of a connection was more + efficient than maintaining the initiator side. However, current + practices makes this distinction irrelevant. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 75] + +Internet-Draft Diameter Base Protocol January 2011 + + +6. Diameter message processing + + This section describes how Diameter requests and answers are created + and processed. + +6.1. Diameter Request Routing Overview + + A request is sent towards its final destination using a combination + of the Destination-Realm and Destination-Host AVPs, in one of these + three combinations: + + o a request that is not able to be proxied (such as CER) MUST NOT + contain either Destination-Realm or Destination-Host AVPs. + + o a request that needs to be sent to a home server serving a + specific realm, but not to a specific server (such as the first + request of a series of round-trips), MUST contain a Destination- + Realm AVP, but MUST NOT contain a Destination-Host AVP. For + Diameter clients, the value of the Destination-Realm AVP MAY be + extracted from the User-Name AVP, or other methods. + + o otherwise, a request that needs to be sent to a specific home + server among those serving a given realm, MUST contain both the + Destination-Realm and Destination-Host AVPs. + + The Destination-Host AVP is used as described above when the + destination of the request is fixed, which includes: + + o Authentication requests that span multiple round trips + + o A Diameter message that uses a security mechanism that makes use + of a pre-established session key shared between the source and the + final destination of the message. + + o Server initiated messages that MUST be received by a specific + Diameter client (e.g., access device), such as the Abort-Session- + Request message, which is used to request that a particular user's + session be terminated. + + Note that an agent can forward a request to a host described in the + Destination-Host AVP only if the host in question is included in its + peer table (see Section 2.7). Otherwise, the request is routed based + on the Destination-Realm only (see Sections 6.1.6). + + When a message is received, the message is processed in the following + order: + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 76] + +Internet-Draft Diameter Base Protocol January 2011 + + + o If the message is destined for the local host, the procedures + listed in Section 6.1.4 are followed. + + o If the message is intended for a Diameter peer with whom the local + host is able to directly communicate, the procedures listed in + Section 6.1.5 are followed. This is known as Request Forwarding. + + o The procedures listed in Section 6.1.6 are followed, which is + known as Request Routing. + + o If none of the above is successful, an answer is returned with the + Result-Code set to DIAMETER_UNABLE_TO_DELIVER, with the E-bit set. + + For routing of Diameter messages to work within an administrative + domain, all Diameter nodes within the realm MUST be peers. + + Note the processing rules contained in this section are intended to + be used as general guidelines to Diameter developers. Certain + implementations MAY use different methods than the ones described + here, and still comply with the protocol specification. See Section + 7 for more detail on error handling. + +6.1.1. Originating a Request + + When creating a request, in addition to any other procedures + described in the application definition for that specific request, + the following procedures MUST be followed: + + o the Command-Code is set to the appropriate value + + o the 'R' bit is set + + o the End-to-End Identifier is set to a locally unique value + + o the Origin-Host and Origin-Realm AVPs MUST be set to the + appropriate values, used to identify the source of the message + + o the Destination-Host and Destination-Realm AVPs MUST be set to the + appropriate values as described in Section 6.1. + +6.1.2. Sending a Request + + When sending a request, originated either locally, or as the result + of a forwarding or routing operation, the following procedures SHOULD + be followed: + + o The Hop-by-Hop Identifier SHOULD be set to a locally unique value. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 77] + +Internet-Draft Diameter Base Protocol January 2011 + + + o The message SHOULD be saved in the list of pending requests. + + Other actions to perform on the message based on the particular role + the agent is playing are described in the following sections. + +6.1.3. Receiving Requests + + A relay or proxy agent MUST check for forwarding loops when receiving + requests. A loop is detected if the server finds its own identity in + a Route-Record AVP. When such an event occurs, the agent MUST answer + with the Result-Code AVP set to DIAMETER_LOOP_DETECTED. + +6.1.4. Processing Local Requests + + A request is known to be for local consumption when one of the + following conditions occur: + + o The Destination-Host AVP contains the local host's identity, + + o The Destination-Host AVP is not present, the Destination-Realm AVP + contains a realm the server is configured to process locally, and + the Diameter application is locally supported, or + + o Both the Destination-Host and the Destination-Realm are not + present. + + When a request is locally processed, the rules in Section 6.2 should + be used to generate the corresponding answer. + +6.1.5. Request Forwarding + + Request forwarding is done using the Diameter Peer Table. The + Diameter peer table contains all of the peers that the local node is + able to directly communicate with. + + When a request is received, and the host encoded in the Destination- + Host AVP is one that is present in the peer table, the message SHOULD + be forwarded to the peer. + +6.1.6. Request Routing + + Diameter request message routing is done via realms and application + identifiers. A Diameter message that may be forwarded by Diameter + agents (proxies, redirect or relay agents) MUST include the target + realm in the Destination-Realm AVP. Request routing SHOULD rely on + the Destination-Realm AVP and the Application Id present in the + request message header to aid in the routing decision. The realm MAY + be retrieved from the User-Name AVP, which is in the form of a + + + +Fajardo, et al. Expires July 24, 2011 [Page 78] + +Internet-Draft Diameter Base Protocol January 2011 + + + Network Access Identifier (NAI). The realm portion of the NAI is + inserted in the Destination-Realm AVP. + + Diameter agents MAY have a list of locally supported realms and + applications, and MAY have a list of externally supported realms and + applications. When a request is received that includes a realm + and/or application that is not locally supported, the message is + routed to the peer configured in the Routing Table (see Section 2.7). + + Realm names and Application Ids are the minimum supported routing + criteria, additional information may be needed to support redirect + semantics. + +6.1.7. Predictive Loop Avoidance + + Before forwarding or routing a request, Diameter agents, in addition + to processing done in Section 6.1.3, SHOULD check for the presence of + candidate route's peer identity in any of the Route-Record AVPs. In + an event of the agent detecting the presence of a candidate route's + peer identity in a Route-Record AVP, the agent MUST ignore such route + for the Diameter request message and attempt alternate routes if any. + In case all the candidate routes are eliminated by the above + criteria, the agent SHOULD return DIAMETER_UNABLE_TO_DELIVER message. + +6.1.8. Redirecting Requests + + When a redirect agent receives a request whose routing entry is set + to REDIRECT, it MUST reply with an answer message with the 'E' bit + set, while maintaining the Hop-by-Hop Identifier in the header, and + include the Result-Code AVP to DIAMETER_REDIRECT_INDICATION. Each of + the servers associated with the routing entry are added in separate + Redirect-Host AVP. + + +------------------+ + | Diameter | + | Redirect Agent | + +------------------+ + ^ | 2. command + 'E' bit + 1. Request | | Result-Code = + [email protected] | | DIAMETER_REDIRECT_INDICATION + + | | Redirect-Host AVP(s) + | v + +-------------+ 3. Request +-------------+ + | example.com |------------->| example.net | + | Relay | | Diameter | + | Agent |<-------------| Server | + +-------------+ 4. Answer +-------------+ + + + + +Fajardo, et al. Expires July 24, 2011 [Page 79] + +Internet-Draft Diameter Base Protocol January 2011 + + + Figure 5: Diameter Redirect Agent + + The receiver of the answer message with the 'E' bit set, and the + Result-Code AVP set to DIAMETER_REDIRECT_INDICATION uses the hop-by- + hop field in the Diameter header to identify the request in the + pending message queue (see Section 5.3) that is to be redirected. If + no transport connection exists with the new agent, one is created, + and the request is sent directly to it. + + Multiple Redirect-Host AVPs are allowed. The receiver of the answer + message with the 'E' bit set selects exactly one of these hosts as + the destination of the redirected message. + + When the Redirect-Host-Usage AVP included in the answer message has a + non-zero value, a route entry for the redirect indications is created + and cached by the receiver. The redirect usage for such route entry + is set by the value of Redirect-Host-Usage AVP and the lifetime of + the cached route entry is set by Redirect-Max-Cache-Time AVP value. + + It is possible that multiple redirect indications can create multiple + cached route entries differing only in their redirect usage and the + peer to forward messages to. As an example, two(2) route entries + that are created by two(2) redirect indications results in two(2) + cached routes for the same realm and Application Id. However, one + has a redirect usage of ALL_SESSION where matching request will be + forwarded to one peer and the other has a redirect usage of ALL_REALM + where request are forwarded to another peer. Therefore, an incoming + request that matches the realm and Application Id of both routes will + need additional resolution. In such a case, a routing precedence + rule MUST be used against the redirect usage value to resolve the + contention. The precedence rule can be found in Section 6.13. + +6.1.9. Relaying and Proxying Requests + + A relay or proxy agent MUST append a Route-Record AVP to all requests + forwarded. The AVP contains the identity of the peer the request was + received from. + + The Hop-by-Hop identifier in the request is saved, and replaced with + a locally unique value. The source of the request is also saved, + which includes the IP address, port and protocol. + + A relay or proxy agent MAY include the Proxy-Info AVP in requests if + it requires access to any local state information when the + corresponding response is received. The Proxy-Info AVP has security + implications as state information is distribute to other entities. + As such, it is RECOMMMENDED to protect the content of the Proxy-Info + AVP with cryptographic mechanisms, for example by using a keyed + + + +Fajardo, et al. Expires July 24, 2011 [Page 80] + +Internet-Draft Diameter Base Protocol January 2011 + + + message digest. Such a mechanism, however, requires the management + of keys, although only locally at the Diameter server. Still, a full + description of the management of the keys used to protect the Proxy- + Info AVP is beyond the scope of this document. Below is a list of + commonly recommended: + + o The keys should be generated securely following the randomness + recommendations in [RFC4086]. + + o The keys and cryptographic protection algorithms should be at + least 128 bits in strength. + + o The keys should not be used for any other purpose than generating + and verifying tickets. + + o The keys should be changed regularly. + + o The keys should be changed if the ticket format or cryptographic + protection algorithms change. + + The message is then forwarded to the next hop, as identified in the + Routing Table. + + Figure 6 provides an example of message routing using the procedures + listed in these sections. + + (Origin-Host=nas.example.net) (Origin-Host=nas.example.net) + (Origin-Realm=example.net) (Origin-Realm=example.net) + (Destination-Realm=example.com) (Destination- + Realm=example.com) + (Route-Record=nas.example.net) + +------+ ------> +------+ ------> +------+ + | | (Request) | | (Request) | | + | NAS +-------------------+ DRL +-------------------+ HMS | + | | | | | | + +------+ <------ +------+ <------ +------+ + example.net (Answer) example.net (Answer) example.com + (Origin-Host=hms.example.com) (Origin-Host=hms.example.com) + (Origin-Realm=example.com) (Origin-Realm=example.com) + + Figure 6: Routing of Diameter messages + + Relay and proxy agents are not required to perform full inspection of + incoming messages. At a minimum, validation of the message header + and relevant routing AVPs has to be done when relaying messages. + Proxy agents may optionally perform more in-depth message validation + for applications it is interested in. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 81] + +Internet-Draft Diameter Base Protocol January 2011 + + +6.2. Diameter Answer Processing + + When a request is locally processed, the following procedures MUST be + applied to create the associated answer, in addition to any + additional procedures that MAY be discussed in the Diameter + application defining the command: + + o The same Hop-by-Hop identifier in the request is used in the + answer. + + o The local host's identity is encoded in the Origin-Host AVP. + + o The Destination-Host and Destination-Realm AVPs MUST NOT be + present in the answer message. + + o The Result-Code AVP is added with its value indicating success or + failure. + + o If the Session-Id is present in the request, it MUST be included + in the answer. + + o Any Proxy-Info AVPs in the request MUST be added to the answer + message, in the same order they were present in the request. + + o The 'P' bit is set to the same value as the one in the request. + + o The same End-to-End identifier in the request is used in the + answer. + + Note that the error messages (see Section 7.3) are also subjected to + the above processing rules. + +6.2.1. Processing received Answers + + A Diameter client or proxy MUST match the Hop-by-Hop Identifier in an + answer received against the list of pending requests. The + corresponding message should be removed from the list of pending + requests. It SHOULD ignore answers received that do not match a + known Hop-by-Hop Identifier. + +6.2.2. Relaying and Proxying Answers + + If the answer is for a request which was proxied or relayed, the + agent MUST restore the original value of the Diameter header's Hop- + by-Hop Identifier field. + + If the last Proxy-Info AVP in the message is targeted to the local + Diameter server, the AVP MUST be removed before the answer is + + + +Fajardo, et al. Expires July 24, 2011 [Page 82] + +Internet-Draft Diameter Base Protocol January 2011 + + + forwarded. + + If a relay or proxy agent receives an answer with a Result-Code AVP + indicating a failure, it MUST NOT modify the contents of the AVP. + Any additional local errors detected SHOULD be logged, but not + reflected in the Result-Code AVP. If the agent receives an answer + message with a Result-Code AVP indicating success, and it wishes to + modify the AVP to indicate an error, it MUST modify the Result-Code + AVP to contain the appropriate error in the message destined towards + the access device as well as include the Error-Reporting-Host AVP and + it MUST issue an STR on behalf of the access device towards the + Diameter server. + + The agent MUST then send the answer to the host that it received the + original request from. + +6.3. Origin-Host AVP + + The Origin-Host AVP (AVP Code 264) is of type DiameterIdentity, and + MUST be present in all Diameter messages. This AVP identifies the + endpoint that originated the Diameter message. Relay agents MUST NOT + modify this AVP. + + The value of the Origin-Host AVP is guaranteed to be unique within a + single host. + + Note that the Origin-Host AVP may resolve to more than one address as + the Diameter peer may support more than one address. + + This AVP SHOULD be placed as close to the Diameter header as + possible. + +6.4. Origin-Realm AVP + + The Origin-Realm AVP (AVP Code 296) is of type DiameterIdentity. + This AVP contains the Realm of the originator of any Diameter message + and MUST be present in all messages. + + This AVP SHOULD be placed as close to the Diameter header as + possible. + +6.5. Destination-Host AVP + + The Destination-Host AVP (AVP Code 293) is of type DiameterIdentity. + This AVP MUST be present in all unsolicited agent initiated messages, + MAY be present in request messages, and MUST NOT be present in Answer + messages. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 83] + +Internet-Draft Diameter Base Protocol January 2011 + + + The absence of the Destination-Host AVP will cause a message to be + sent to any Diameter server supporting the application within the + realm specified in Destination-Realm AVP. + + This AVP SHOULD be placed as close to the Diameter header as + possible. + +6.6. Destination-Realm AVP + + The Destination-Realm AVP (AVP Code 283) is of type DiameterIdentity, + and contains the realm the message is to be routed to. The + Destination-Realm AVP MUST NOT be present in Answer messages. + Diameter Clients insert the realm portion of the User-Name AVP. + Diameter servers initiating a request message use the value of the + Origin-Realm AVP from a previous message received from the intended + target host (unless it is known a priori). When present, the + Destination-Realm AVP is used to perform message routing decisions. + + An ABNF for a request message that includes the Destination-Realm AVP + SHOULD list the Destination-Realm AVP as a required AVP (an AVP + indicated as {AVP}) otherwise the message is inherently a non- + routable message. + + This AVP SHOULD be placed as close to the Diameter header as + possible. + +6.7. Routing AVPs + + The AVPs defined in this section are Diameter AVPs used for routing + purposes. These AVPs change as Diameter messages are processed by + agents. + +6.7.1. Route-Record AVP + + The Route-Record AVP (AVP Code 282) is of type DiameterIdentity. The + identity added in this AVP MUST be the same as the one received in + the Origin-Host of the Capabilities Exchange message. + +6.7.2. Proxy-Info AVP + + The Proxy-Info AVP (AVP Code 284) is of type Grouped. This AVP + contains the identity and local state information of the Diameter + node that creates and adds it to a message. The Grouped Data field + has the following ABNF grammar: + + Proxy-Info ::= < AVP Header: 284 > + { Proxy-Host } + { Proxy-State } + + + +Fajardo, et al. Expires July 24, 2011 [Page 84] + +Internet-Draft Diameter Base Protocol January 2011 + + + * [ AVP ] + +6.7.3. Proxy-Host AVP + + The Proxy-Host AVP (AVP Code 280) is of type DiameterIdentity. This + AVP contains the identity of the host that added the Proxy-Info AVP. + +6.7.4. Proxy-State AVP + + The Proxy-State AVP (AVP Code 33) is of type OctetString. It + contains state information that would otherwise be stored at the + Diameter entity that created it. As such, this AVP MUST be treated + as opaque data by other Diameter entities. + +6.8. Auth-Application-Id AVP + + The Auth-Application-Id AVP (AVP Code 258) is of type Unsigned32 and + is used in order to advertise support of the Authentication and + Authorization portion of an application (see Section 2.4). If + present in a message other than CER and CEA, the value of the Auth- + Application-Id AVP MUST match the Application Id present in the + Diameter message header. + +6.9. Acct-Application-Id AVP + + The Acct-Application-Id AVP (AVP Code 259) is of type Unsigned32 and + is used in order to advertise support of the Accounting portion of an + application (see Section 2.4). If present in a message other than + CER and CEA, the value of the Acct-Application-Id AVP MUST match the + Application Id present in the Diameter message header. + +6.10. Inband-Security-Id AVP + + The Inband-Security-Id AVP (AVP Code 299) is of type Unsigned32 and + is used in order to advertise support of the security portion of the + application. The use of this AVP in CER and CEA messages is no + longer recommended. Instead, discovery of a Diameter entities + security capabilities can be done either through static configuration + or via Diameter Peer Discovery described in Section 5.2. + + The following values are supported: + + + NO_INBAND_SECURITY 0 + + This peer does not support TLS/TCP and DTLS/SCTP. This is the + default value, if the AVP is omitted. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 85] + +Internet-Draft Diameter Base Protocol January 2011 + + + TLS 1 + + This node supports TLS/TCP and DTLS/SCTP security, as defined by + [RFC5246]. + +6.11. Vendor-Specific-Application-Id AVP + + The Vendor-Specific-Application-Id AVP (AVP Code 260) is of type + Grouped and is used to advertise support of a vendor-specific + Diameter Application. Exactly one instance of either Auth- + Application-Id or Acct-Application-Id AVP MUST be present. The + Application Id carried by either Auth-Application-Id or Acct- + Application-Id AVP MUST comply with vendor specific Application Id + assignment described in Sec 11.3. It MUST also match the Application + Id present in the Diameter header except when used in a CER or CEA + message. + + The Vendor-Id AVP is an informational AVP pertaining to the vendor + who may have authorship of the vendor-specific Diameter application. + It MUST NOT be used as a means of defining a completely separate + vendor-specific Application Id space. + + The Vendor-Specific-Application-Id AVP SHOULD be placed as close to + the Diameter header as possible. + + AVP Format + + <Vendor-Specific-Application-Id> ::= < AVP Header: 260 > + { Vendor-Id } + [ Auth-Application-Id ] + [ Acct-Application-Id ] + + A Vendor-Specific-Application-Id AVP MUST contain exactly one of + either Auth-Application-Id or Acct-Application-Id. If a Vendor- + Specific-Application-Id is received without any of these two AVPs, + then the recipient SHOULD issue an answer with a Result-Code set to + DIAMETER_MISSING_AVP. The answer SHOULD also include a Failed-AVP + which MUST contain an example of an Auth-Application-Id AVP and an + Acct-Application-Id AVP. + + If a Vendor-Specific-Application-Id is received that contains both + Auth-Application-Id and Acct-Application-Id, then the recipient MUST + issue an answer with Result-Code set to + DIAMETER_AVP_OCCURS_TOO_MANY_TIMES. The answer MUST also include a + Failed-AVP which MUST contain the received Auth-Application-Id AVP + and Acct-Application-Id AVP. + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 86] + +Internet-Draft Diameter Base Protocol January 2011 + + +6.12. Redirect-Host AVP + + The Redirect-Host AVP (AVP Code 292) is of type DiameterURI. One or + more of instances of this AVP MUST be present if the answer message's + 'E' bit is set and the Result-Code AVP is set to + DIAMETER_REDIRECT_INDICATION. + + Upon receiving the above, the receiving Diameter node SHOULD forward + the request directly to one of the hosts identified in these AVPs. + The server contained in the selected Redirect-Host AVP SHOULD be used + for all messages matching the criteria set by the Redirect-Host-Usage + AVP. + +6.13. Redirect-Host-Usage AVP + + The Redirect-Host-Usage AVP (AVP Code 261) is of type Enumerated. + This AVP MAY be present in answer messages whose 'E' bit is set and + the Result-Code AVP is set to DIAMETER_REDIRECT_INDICATION. + + When present, this AVP provides a hints about how the routing entry + resulting from the Redirect-Host is to be used. The following values + are supported: + + + DONT_CACHE 0 + + The host specified in the Redirect-Host AVP SHOULD NOT be cached. + This is the default value. + + + ALL_SESSION 1 + + All messages within the same session, as defined by the same value + of the Session-ID AVP SHOULD be sent to the host specified in the + Redirect-Host AVP. + + + ALL_REALM 2 + + All messages destined for the realm requested SHOULD be sent to + the host specified in the Redirect-Host AVP. + + + REALM_AND_APPLICATION 3 + + All messages for the application requested to the realm specified + SHOULD be sent to the host specified in the Redirect-Host AVP. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 87] + +Internet-Draft Diameter Base Protocol January 2011 + + + ALL_APPLICATION 4 + + All messages for the application requested SHOULD be sent to the + host specified in the Redirect-Host AVP. + + + ALL_HOST 5 + + All messages that would be sent to the host that generated the + Redirect-Host SHOULD be sent to the host specified in the + Redirect- Host AVP. + + + ALL_USER 6 + + All messages for the user requested SHOULD be sent to the host + specified in the Redirect-Host AVP. + + + + When multiple cached routes are created by redirect indications and + they differ only in redirect usage and peers to forward requests to + (see Section 6.1.8), a precedence rule MUST be applied to the + redirect usage values of the cached routes during normal routing to + resolve contentions that may occur. The precedence rule is the order + that dictate which redirect usage should be considered before any + other as they appear. The order is as follows: + + + 1. ALL_SESSION + + 2. ALL_USER + + 3. REALM_AND_APPLICATION + + 4. ALL_REALM + + 5. ALL_APPLICATION + + 6. ALL_HOST + +6.14. Redirect-Max-Cache-Time AVP + + The Redirect-Max-Cache-Time AVP (AVP Code 262) is of type Unsigned32. + This AVP MUST be present in answer messages whose 'E' bit is set, the + Result-Code AVP is set to DIAMETER_REDIRECT_INDICATION and the + Redirect-Host-Usage AVP set to a non-zero value. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 88] + +Internet-Draft Diameter Base Protocol January 2011 + + + This AVP contains the maximum number of seconds the peer and route + table entries, created as a result of the Redirect-Host, SHOULD be + cached. Note that once a host is no longer reachable, any associated + cache, peer and routing table entries MUST be deleted. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 89] + +Internet-Draft Diameter Base Protocol January 2011 + + +7. Error Handling + + There are two different types of errors in Diameter; protocol and + application errors. A protocol error is one that occurs at the base + protocol level, and MAY require per hop attention (e.g., message + routing error). Application errors, on the other hand, generally + occur due to a problem with a function specified in a Diameter + application (e.g., user authentication, missing AVP). + + Result-Code AVP values that are used to report protocol errors MUST + only be present in answer messages whose 'E' bit is set. When a + request message is received that causes a protocol error, an answer + message is returned with the 'E' bit set, and the Result-Code AVP is + set to the appropriate protocol error value. As the answer is sent + back towards the originator of the request, each proxy or relay agent + MAY take action on the message. + + 1. Request +---------+ Link Broken + +-------------------------->|Diameter |----///----+ + | +---------------------| | v + +------+--+ | 2. answer + 'E' set | Relay 2 | +--------+ + |Diameter |<-+ (Unable to Forward) +---------+ |Diameter| + | | | Home | + | Relay 1 |--+ +---------+ | Server | + +---------+ | 3. Request |Diameter | +--------+ + +-------------------->| | ^ + | Relay 3 |-----------+ + +---------+ + + Figure 7: Example of Protocol Error causing answer message + + Figure 7 provides an example of a message forwarded upstream by a + Diameter relay. When the message is received by Relay 2, and it + detects that it cannot forward the request to the home server, an + answer message is returned with the 'E' bit set and the Result-Code + AVP set to DIAMETER_UNABLE_TO_DELIVER. Given that this error falls + within the protocol error category, Relay 1 would take special + action, and given the error, attempt to route the message through its + alternate Relay 3. + + +---------+ 1. Request +---------+ 2. Request +---------+ + | Access |------------>|Diameter |------------>|Diameter | + | | | | | Home | + | Device |<------------| Relay |<------------| Server | + +---------+ 4. Answer +---------+ 3. Answer +---------+ + (Missing AVP) (Missing AVP) + + Figure 8: Example of Application Error Answer message + + + +Fajardo, et al. Expires July 24, 2011 [Page 90] + +Internet-Draft Diameter Base Protocol January 2011 + + + Figure 8 provides an example of a Diameter message that caused an + application error. When application errors occur, the Diameter + entity reporting the error clears the 'R' bit in the Command Flags, + and adds the Result-Code AVP with the proper value. Application + errors do not require any proxy or relay agent involvement, and + therefore the message would be forwarded back to the originator of + the request. + + In the case where the answer message itself contains errors, any + related session SHOULD be terminated by sending an STR or ASR + message. The Termination-Cause AVP in the STR MAY be filled with the + appropriate value to indicate the cause of the error. An application + MAY also send an application-specific request instead of STR or ASR + to signal the error in the case where no state is maintained or to + allow for some form of error recovery with the corresponding Diameter + entity. + + There are certain Result-Code AVP application errors that require + additional AVPs to be present in the answer. In these cases, the + Diameter node that sets the Result-Code AVP to indicate the error + MUST add the AVPs. Examples are: + + o A request with an unrecognized AVP is received with the 'M' bit + (Mandatory bit) set, causes an answer to be sent with the Result- + Code AVP set to DIAMETER_AVP_UNSUPPORTED, and the Failed-AVP AVP + containing the offending AVP. + + o A request with an AVP that is received with an unrecognized value + causes an answer to be returned with the Result-Code AVP set to + DIAMETER_INVALID_AVP_VALUE, with the Failed-AVP AVP containing the + AVP causing the error. + + o A received command which is missing AVP(s) that are defined as + required in the commands ABNF; examples are AVPs indicated as + {AVP}. The receiver issues an answer with the Result-Code set to + DIAMETER_MISSING_AVP, and creates an AVP with the AVP Code and + other fields set as expected in the missing AVP. The created AVP + is then added to the Failed- AVP AVP. + + The Result-Code AVP describes the error that the Diameter node + encountered in its processing. In case there are multiple errors, + the Diameter node MUST report only the first error it encountered + (detected possibly in some implementation dependent order). The + specific errors that can be described by this AVP are described in + the following section. + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 91] + +Internet-Draft Diameter Base Protocol January 2011 + + +7.1. Result-Code AVP + + The Result-Code AVP (AVP Code 268) is of type Unsigned32 and + indicates whether a particular request was completed successfully or + whether an error occurred. All Diameter answer messages in IETF + defined Diameter application specification MUST include one Result- + Code AVP. A non-successful Result-Code AVP (one containing a non + 2xxx value other than DIAMETER_REDIRECT_INDICATION) MUST include the + Error-Reporting-Host AVP if the host setting the Result-Code AVP is + different from the identity encoded in the Origin-Host AVP. + + + The Result-Code data field contains an IANA-managed 32-bit address + space representing errors (see Section 11.4). Diameter provides the + following classes of errors, all identified by the thousands digit in + the decimal notation: + + o 1xxx (Informational) + + o 2xxx (Success) + + o 3xxx (Protocol Errors) + + o 4xxx (Transient Failures) + + o 5xxx (Permanent Failure) + + A non-recognized class (one whose first digit is not defined in this + section) MUST be handled as a permanent failure. + +7.1.1. Informational + + Errors that fall within this category are used to inform the + requester that a request could not be satisfied, and additional + action is required on its part before access is granted. + + + DIAMETER_MULTI_ROUND_AUTH 1001 + + This informational error is returned by a Diameter server to + inform the access device that the authentication mechanism being + used requires multiple round trips, and a subsequent request needs + to be issued in order for access to be granted. + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 92] + +Internet-Draft Diameter Base Protocol January 2011 + + +7.1.2. Success + + Errors that fall within the Success category are used to inform a + peer that a request has been successfully completed. + + + DIAMETER_SUCCESS 2001 + + The request was successfully completed. + + DIAMETER_LIMITED_SUCCESS 2002 + + When returned, the request was successfully completed, but + additional processing is required by the application in order to + provide service to the user. + +7.1.3. Protocol Errors + + Errors that fall within the Protocol Error category SHOULD be treated + on a per-hop basis, and Diameter proxies MAY attempt to correct the + error, if it is possible. Note that these errors MUST only be used + in answer messages whose 'E' bit is set. This document omits some + error codes defined in [RFC3588]. To provide backward compatibility + with [RFC3588] implementations these error code values are not re- + used and hence the error codes values enumerated below are non- + sequential. + + + DIAMETER_UNABLE_TO_DELIVER 3002 + + This error is given when Diameter can not deliver the message to + the destination, either because no host within the realm + supporting the required application was available to process the + request, or because Destination-Host AVP was given without the + associated Destination-Realm AVP. + + + DIAMETER_REALM_NOT_SERVED 3003 + + The intended realm of the request is not recognized. + + + DIAMETER_TOO_BUSY 3004 + + When returned, a Diameter node SHOULD attempt to send the message + to an alternate peer. This error MUST only be used when a + specific server is requested, and it cannot provide the requested + service. + + + +Fajardo, et al. Expires July 24, 2011 [Page 93] + +Internet-Draft Diameter Base Protocol January 2011 + + + DIAMETER_LOOP_DETECTED 3005 + + An agent detected a loop while trying to get the message to the + intended recipient. The message MAY be sent to an alternate peer, + if one is available, but the peer reporting the error has + identified a configuration problem. + + + DIAMETER_REDIRECT_INDICATION 3006 + + A redirect agent has determined that the request could not be + satisfied locally and the initiator of the request SHOULD direct + the request directly to the server, whose contact information has + been added to the response. When set, the Redirect-Host AVP MUST + be present. + + + DIAMETER_APPLICATION_UNSUPPORTED 3007 + + A request was sent for an application that is not supported. + + + DIAMETER_INVALID_BIT_IN_HEADER 3011 + + This error is returned when a reserved bit in the Diameter header + is set to one (1) or the bits in the Diameter header defined in + Section 3 are set incorrectly. + + + DIAMETER_INVALID_MESSAGE_LENGTH 3012 + + This error is returned when a request is received with an invalid + message length. + + +7.1.4. Transient Failures + + Errors that fall within the transient failures category are used to + inform a peer that the request could not be satisfied at the time it + was received, but MAY be able to satisfy the request in the future. + Note that these errors MUST be used in answer messages whose 'E' bit + is not set. + + + DIAMETER_AUTHENTICATION_REJECTED 4001 + + The authentication process for the user failed, most likely due to + an invalid password used by the user. Further attempts MUST only + + + +Fajardo, et al. Expires July 24, 2011 [Page 94] + +Internet-Draft Diameter Base Protocol January 2011 + + + be tried after prompting the user for a new password. + + + DIAMETER_OUT_OF_SPACE 4002 + + A Diameter node received the accounting request but was unable to + commit it to stable storage due to a temporary lack of space. + + + ELECTION_LOST 4003 + + The peer has determined that it has lost the election process and + has therefore disconnected the transport connection. + + +7.1.5. Permanent Failures + + Errors that fall within the permanent failures category are used to + inform the peer that the request failed, and should not be attempted + again. Note that these errors SHOULD be used in answer messages + whose 'E' bit is not set. In error conditions where it is not + possible or efficient to compose application-specific answer grammar + then answer messages with E-bit set and complying to the grammar + described in 7.2 MAY also be used for permanent errors. + + To provide backward compatibility with existing implementations that + follow [RFC3588], some of the error values that have previously been + used in this category by [RFC3588] will not be re-used. Therefore + the error values enumerated here may be non-sequential. + + + DIAMETER_AVP_UNSUPPORTED 5001 + + The peer received a message that contained an AVP that is not + recognized or supported and was marked with the Mandatory bit. A + Diameter message with this error MUST contain one or more Failed- + AVP AVP containing the AVPs that caused the failure. + + + DIAMETER_UNKNOWN_SESSION_ID 5002 + + The request contained an unknown Session-Id. + + + DIAMETER_AUTHORIZATION_REJECTED 5003 + + A request was received for which the user could not be authorized. + This error could occur if the service requested is not permitted + + + +Fajardo, et al. Expires July 24, 2011 [Page 95] + +Internet-Draft Diameter Base Protocol January 2011 + + + to the user. + + + DIAMETER_INVALID_AVP_VALUE 5004 + + The request contained an AVP with an invalid value in its data + portion. A Diameter message indicating this error MUST include + the offending AVPs within a Failed-AVP AVP. + + + DIAMETER_MISSING_AVP 5005 + + The request did not contain an AVP that is required by the Command + Code definition. If this value is sent in the Result-Code AVP, a + Failed-AVP AVP SHOULD be included in the message. The Failed-AVP + AVP MUST contain an example of the missing AVP complete with the + Vendor-Id if applicable. The value field of the missing AVP + should be of correct minimum length and contain zeroes. + + + DIAMETER_RESOURCES_EXCEEDED 5006 + + A request was received that cannot be authorized because the user + has already expended allowed resources. An example of this error + condition is a user that is restricted to one dial-up PPP port, + attempts to establish a second PPP connection. + + + DIAMETER_CONTRADICTING_AVPS 5007 + + The Home Diameter server has detected AVPs in the request that + contradicted each other, and is not willing to provide service to + the user. The Failed-AVP AVPs MUST be present which contains the + AVPs that contradicted each other. + + + DIAMETER_AVP_NOT_ALLOWED 5008 + + A message was received with an AVP that MUST NOT be present. The + Failed-AVP AVP MUST be included and contain a copy of the + offending AVP. + + + DIAMETER_AVP_OCCURS_TOO_MANY_TIMES 5009 + + A message was received that included an AVP that appeared more + often than permitted in the message definition. The Failed-AVP + AVP MUST be included and contain a copy of the first instance of + + + +Fajardo, et al. Expires July 24, 2011 [Page 96] + +Internet-Draft Diameter Base Protocol January 2011 + + + the offending AVP that exceeded the maximum number of occurrences + + + DIAMETER_NO_COMMON_APPLICATION 5010 + + This error is returned by a Diameter node that receives a CER + whereby no applications are common between the CER sending peer + and the CER receiving peer. + + + DIAMETER_UNSUPPORTED_VERSION 5011 + + This error is returned when a request was received, whose version + number is unsupported. + + + DIAMETER_UNABLE_TO_COMPLY 5012 + + This error is returned when a request is rejected for unspecified + reasons. + + + DIAMETER_INVALID_AVP_LENGTH 5014 + + The request contained an AVP with an invalid length. A Diameter + message indicating this error MUST include the offending AVPs + within a Failed-AVP AVP. In cases where the erroneous AVP length + value exceeds the message length or is less than the minimum AVP + header length, it is sufficient to include the offending AVP + header and a zero filled payload of the minimum required length + for the payloads data type. If the AVP is a grouped AVP, the + grouped AVP header with an empty payload would be sufficient to + indicate the offending AVP. In the case where the offending AVP + header cannot be fully decoded when the AVP length is less than + the minimum AVP header length, it is sufficient to include an + offending AVP header that is formulated by padding the incomplete + AVP header with zero up to the minimum AVP header length. + + + DIAMETER_NO_COMMON_SECURITY 5017 + + This error is returned when a CER message is received, and there + are no common security mechanisms supported between the peers. A + Capabilities-Exchange-Answer (CEA) MUST be returned with the + Result-Code AVP set to DIAMETER_NO_COMMON_SECURITY. + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 97] + +Internet-Draft Diameter Base Protocol January 2011 + + + DIAMETER_UNKNOWN_PEER 5018 + + A CER was received from an unknown peer. + + + DIAMETER_COMMAND_UNSUPPORTED 5019 + + This error code is used when a Diameter entity receives a message + with a Command Code that it does not support. + + + DIAMETER_INVALID_HDR_BITS 5020 + + A request was received whose bits in the Diameter header were + either set to an invalid combination, or to a value that is + inconsistent with the command code's definition. + + + DIAMETER_INVALID_AVP_BITS 5021 + + A request was received that included an AVP whose flag bits are + set to an unrecognized value, or that is inconsistent with the + AVP's definition. + + +7.2. Error Bit + + The 'E' (Error Bit) in the Diameter header is set when the request + caused a protocol-related error (see Section 7.1.3). A message with + the 'E' bit MUST NOT be sent as a response to an answer message. + Note that a message with the 'E' bit set is still subjected to the + processing rules defined in Section 6.2. When set, the answer + message will not conform to the ABNF specification for the command, + and will instead conform to the following ABNF: + + Message Format + + <answer-message> ::= < Diameter Header: code, ERR [PXY] > + 0*1< Session-Id > + { Origin-Host } + { Origin-Realm } + { Result-Code } + [ Origin-State-Id ] + [ Error-Message ] + [ Error-Reporting-Host ] + [ Failed-AVP ] + [ Experimental-Result ] + * [ Proxy-Info ] + + + +Fajardo, et al. Expires July 24, 2011 [Page 98] + +Internet-Draft Diameter Base Protocol January 2011 + + + * [ AVP ] + + Note that the code used in the header is the same than the one found + in the request message, but with the 'R' bit cleared and the 'E' bit + set. The 'P' bit in the header is set to the same value as the one + found in the request message. + +7.3. Error-Message AVP + + The Error-Message AVP (AVP Code 281) is of type UTF8String. It MAY + accompany a Result-Code AVP as a human readable error message. The + Error-Message AVP is not intended to be useful in an environment + where error messages are processed automatically. It SHOULD NOT be + expected that the content of this AVP is parsed by network entities. + +7.4. Error-Reporting-Host AVP + + The Error-Reporting-Host AVP (AVP Code 294) is of type + DiameterIdentity. This AVP contains the identity of the Diameter + host that sent the Result-Code AVP to a value other than 2001 + (Success), only if the host setting the Result-Code is different from + the one encoded in the Origin-Host AVP. This AVP is intended to be + used for troubleshooting purposes, and MUST be set when the Result- + Code AVP indicates a failure. + +7.5. Failed-AVP AVP + + The Failed-AVP AVP (AVP Code 279) is of type Grouped and provides + debugging information in cases where a request is rejected or not + fully processed due to erroneous information in a specific AVP. The + value of the Result-Code AVP will provide information on the reason + for the Failed-AVP AVP. A Diameter message SHOULD contain only one + Failed-AVP that corresponds to the error indicated by the Result-Code + AVP. For practical purposes, this Failed-AVP would typically refer + to the first AVP processing error that a Diameter node encounters. + + The possible reasons for this AVP are the presence of an improperly + constructed AVP, an unsupported or unrecognized AVP, an invalid AVP + value, the omission of a required AVP, the presence of an explicitly + excluded AVP (see tables in Section 10), or the presence of two or + more occurrences of an AVP which is restricted to 0, 1, or 0-1 + occurrences. + + A Diameter message SHOULD contain one Failed-AVP AVP, containing the + entire AVP that could not be processed successfully. If the failure + reason is omission of a required AVP, an AVP with the missing AVP + code, the missing vendor id, and a zero filled payload of the minimum + required length for the omitted AVP will be added. If the failure + + + +Fajardo, et al. Expires July 24, 2011 [Page 99] + +Internet-Draft Diameter Base Protocol January 2011 + + + reason is an invalid AVP length where the reported length is less + than the minimum AVP header length or greater than the reported + message length, a copy of the offending AVP header and a zero filled + payload of the minimum required length SHOULD be added. + + In the case where the offending AVP is embedded within a grouped AVP, + the Failed-AVP MAY contain the grouped AVP which in turn contains the + single offending AVP. The same method MAY be employed if the grouped + AVP itself is embedded in yet another grouped AVP and so on. In this + case, the Failed-AVP MAY contain the grouped AVP hierarchy up to the + single offending AVP. This enables the recipient to detect the + location of the offending AVP when embedded in a group. + + AVP Format + + <Failed-AVP> ::= < AVP Header: 279 > + 1* {AVP} + +7.6. Experimental-Result AVP + + The Experimental-Result AVP (AVP Code 297) is of type Grouped, and + indicates whether a particular vendor-specific request was completed + successfully or whether an error occurred. This AVP has the + following structure: + + AVP Format + + Experimental-Result ::= < AVP Header: 297 > + { Vendor-Id } + { Experimental-Result-Code } + + The Vendor-Id AVP (see Section 5.3.3) in this grouped AVP identifies + the vendor responsible for the assignment of the result code which + follows. All Diameter answer messages defined in vendor-specific + applications MUST include either one Result-Code AVP or one + Experimental-Result AVP. + +7.7. Experimental-Result-Code AVP + + The Experimental-Result-Code AVP (AVP Code 298) is of type Unsigned32 + and contains a vendor-assigned value representing the result of + processing the request. + + It is recommended that vendor-specific result codes follow the same + conventions given for the Result-Code AVP regarding the different + types of result codes and the handling of errors (for non 2xxx + values). + + + + +Fajardo, et al. Expires July 24, 2011 [Page 100] + +Internet-Draft Diameter Base Protocol January 2011 + + +8. Diameter User Sessions + + In general, Diameter can provide two different types of services to + applications. The first involves authentication and authorization, + and can optionally make use of accounting. The second only makes use + of accounting. + + When a service makes use of the authentication and/or authorization + portion of an application, and a user requests access to the network, + the Diameter client issues an auth request to its local server. The + auth request is defined in a service-specific Diameter application + (e.g., NASREQ). The request contains a Session-Id AVP, which is used + in subsequent messages (e.g., subsequent authorization, accounting, + etc) relating to the user's session. The Session-Id AVP is a means + for the client and servers to correlate a Diameter message with a + user session. + + When a Diameter server authorizes a user to use network resources for + a finite amount of time, and it is willing to extend the + authorization via a future request, it MUST add the Authorization- + Lifetime AVP to the answer message. The Authorization-Lifetime AVP + defines the maximum number of seconds a user MAY make use of the + resources before another authorization request is expected by the + server. The Auth-Grace-Period AVP contains the number of seconds + following the expiration of the Authorization-Lifetime, after which + the server will release all state information related to the user's + session. Note that if payment for services is expected by the + serving realm from the user's home realm, the Authorization-Lifetime + AVP, combined with the Auth-Grace-Period AVP, implies the maximum + length of the session the home realm is willing to be fiscally + responsible for. Services provided past the expiration of the + Authorization-Lifetime and Auth-Grace-Period AVPs are the + responsibility of the access device. Of course, the actual cost of + services rendered is clearly outside the scope of the protocol. + + An access device that does not expect to send a re-authorization or a + session termination request to the server MAY include the Auth- + Session-State AVP with the value set to NO_STATE_MAINTAINED as a hint + to the server. If the server accepts the hint, it agrees that since + no session termination message will be received once service to the + user is terminated, it cannot maintain state for the session. If the + answer message from the server contains a different value in the + Auth-Session-State AVP (or the default value if the AVP is absent), + the access device MUST follow the server's directives. Note that the + value NO_STATE_MAINTAINED MUST NOT be set in subsequent re- + authorization requests and answers. + + The base protocol does not include any authorization request + + + +Fajardo, et al. Expires July 24, 2011 [Page 101] + +Internet-Draft Diameter Base Protocol January 2011 + + + messages, since these are largely application-specific and are + defined in a Diameter application document. However, the base + protocol does define a set of messages that are used to terminate + user sessions. These are used to allow servers that maintain state + information to free resources. + + When a service only makes use of the Accounting portion of the + Diameter protocol, even in combination with an application, the + Session-Id is still used to identify user sessions. However, the + session termination messages are not used, since a session is + signaled as being terminated by issuing an accounting stop message. + + Diameter may also be used for services that cannot be easily + categorized as authentication, authorization or accounting (e.g., + certain 3GPP IMS interfaces). In such cases, the finite state + machine defined in subsequent sections may not be applicable. + Therefore, the applications itself MAY need to define its own finite + state machine. However, such application-specific state machines + SHOULD follow the general state machine framework outlined in this + document such as the use of Session-Id AVPs and the use of STR/STA, + ASR/ASA messages for stateful sessions. + +8.1. Authorization Session State Machine + + This section contains a set of finite state machines, representing + the life cycle of Diameter sessions, and which MUST be observed by + all Diameter implementations that make use of the authentication + and/or authorization portion of a Diameter application. The term + Service-Specific below refers to a message defined in a Diameter + application (e.g., Mobile IPv4, NASREQ). + + There are four different authorization session state machines + supported in the Diameter base protocol. The first two describe a + session in which the server is maintaining session state, indicated + by the value of the Auth-Session-State AVP (or its absence). One + describes the session from a client perspective, the other from a + server perspective. The second two state machines are used when the + server does not maintain session state. Here again, one describes + the session from a client perspective, the other from a server + perspective. + + When a session is moved to the Idle state, any resources that were + allocated for the particular session must be released. Any event not + listed in the state machines MUST be considered as an error + condition, and an answer, if applicable, MUST be returned to the + originator of the message. + + In the case that an application does not support re-auth, the state + + + +Fajardo, et al. Expires July 24, 2011 [Page 102] + +Internet-Draft Diameter Base Protocol January 2011 + + + transitions related to server-initiated re-auth when both client and + server session maintains state (e.g., Send RAR, Pending, Receive RAA) + MAY be ignored. + + In the state table, the event 'Failure to send X' means that the + Diameter agent is unable to send command X to the desired + destination. This could be due to the peer being down, or due to the + peer sending back a transient failure or temporary protocol error + notification DIAMETER_TOO_BUSY or DIAMETER_LOOP_DETECTED in the + Result-Code AVP of the corresponding Answer command. The event 'X + successfully sent' is the complement of 'Failure to send X'. + + The following state machine is observed by a client when state is + maintained on the server: + + CLIENT, STATEFUL + State Event Action New State + --------------------------------------------------------------- + Idle Client or Device Requests Send Pending + access service + specific + auth req + + Idle ASR Received Send ASA Idle + for unknown session with + Result-Code = + UNKNOWN_ + SESSION_ID + + Idle RAR Received Send RAA Idle + for unknown session with + Result-Code = + UNKNOWN_ + SESSION_ID + + Pending Successful Service-specific Grant Open + authorization answer Access + received with default + Auth-Session-State value + + Pending Successful Service-specific Sent STR Discon + authorization answer received + but service not provided + + Pending Error processing successful Sent STR Discon + Service-specific authorization + answer + + + + +Fajardo, et al. Expires July 24, 2011 [Page 103] + +Internet-Draft Diameter Base Protocol January 2011 + + + Pending Failed Service-specific Cleanup Idle + authorization answer received + + Open User or client device Send Open + requests access to service service + specific + auth req + + Open Successful Service-specific Provide Open + authorization answer received Service + + Open Failed Service-specific Discon. Idle + authorization answer user/device + received. + + Open RAR received and client will Send RAA Open + perform subsequent re-auth with + Result-Code = + SUCCESS + + Open RAR received and client will Send RAA Idle + not perform subsequent with + re-auth Result-Code != + SUCCESS, + Discon. + user/device + + Open Session-Timeout Expires on Send STR Discon + Access Device + + Open ASR Received, Send ASA Discon + client will comply with + with request to end the Result-Code = + session = SUCCESS, + Send STR. + + Open ASR Received, Send ASA Open + client will not comply with + with request to end the Result-Code != + session != SUCCESS + + Open Authorization-Lifetime + Send STR Discon + Auth-Grace-Period expires on + access device + + Discon ASR Received Send ASA Discon + + Discon STA Received Discon. Idle + + + +Fajardo, et al. Expires July 24, 2011 [Page 104] + +Internet-Draft Diameter Base Protocol January 2011 + + + user/device + + The following state machine is observed by a server when it is + maintaining state for the session: + + SERVER, STATEFUL + State Event Action New State + --------------------------------------------------------------- + Idle Service-specific authorization Send Open + request received, and successful + user is authorized serv. + specific + answer + + Idle Service-specific authorization Send Idle + request received, and failed serv. + user is not authorized specific + answer + + Open Service-specific authorization Send Open + request received, and user successful + is authorized serv. specific + answer + + Open Service-specific authorization Send Idle + request received, and user failed serv. + is not authorized specific + answer, + Cleanup + + Open Home server wants to confirm Send RAR Pending + authentication and/or + authorization of the user + + Pending Received RAA with a failed Cleanup Idle + Result-Code + + Pending Received RAA with Result-Code Update Open + = SUCCESS session + + Open Home server wants to Send ASR Discon + terminate the service + + Open Authorization-Lifetime (and Cleanup Idle + Auth-Grace-Period) expires + on home server. + + Open Session-Timeout expires on Cleanup Idle + + + +Fajardo, et al. Expires July 24, 2011 [Page 105] + +Internet-Draft Diameter Base Protocol January 2011 + + + home server + + Discon Failure to send ASR Wait, Discon + resend ASR + + Discon ASR successfully sent and Cleanup Idle + ASA Received with Result-Code + + Not ASA Received None No Change. + Discon + + Any STR Received Send STA, Idle + Cleanup. + + The following state machine is observed by a client when state is not + maintained on the server: + + CLIENT, STATELESS + State Event Action New State + --------------------------------------------------------------- + Idle Client or Device Requests Send Pending + access service + specific + auth req + + Pending Successful Service-specific Grant Open + authorization answer Access + received with Auth-Session- + State set to + NO_STATE_MAINTAINED + + Pending Failed Service-specific Cleanup Idle + authorization answer + received + + Open Session-Timeout Expires on Discon. Idle + Access Device user/device + + Open Service to user is terminated Discon. Idle + user/device + + The following state machine is observed by a server when it is not + maintaining state for the session: + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 106] + +Internet-Draft Diameter Base Protocol January 2011 + + + SERVER, STATELESS + State Event Action New State + --------------------------------------------------------------- + Idle Service-specific authorization Send serv. Idle + request received, and specific + successfully processed answer + +8.2. Accounting Session State Machine + + The following state machines MUST be supported for applications that + have an accounting portion or that require only accounting services. + The first state machine is to be observed by clients. + + See Section 9.7 for Accounting Command Codes and Section 9.8 for + Accounting AVPs. + + The server side in the accounting state machine depends in some cases + on the particular application. The Diameter base protocol defines a + default state machine that MUST be followed by all applications that + have not specified other state machines. This is the second state + machine in this section described below. + + The default server side state machine requires the reception of + accounting records in any order and at any time, and does not place + any standards requirement on the processing of these records. + Implementations of Diameter may perform checking, ordering, + correlation, fraud detection, and other tasks based on these records. + AVPs may need to be inspected as a part of these tasks. The tasks + can happen either immediately after record reception or in a post- + processing phase. However, as these tasks are typically application + or even policy dependent, they are not standardized by the Diameter + specifications. Applications MAY define requirements on when to + accept accounting records based on the used value of Accounting- + Realtime-Required AVP, credit limits checks, and so on. + + However, the Diameter base protocol defines one optional server side + state machine that MAY be followed by applications that require + keeping track of the session state at the accounting server. Note + that such tracking is incompatible with the ability to sustain long + duration connectivity problems. Therefore, the use of this state + machine is recommended only in applications where the value of the + Accounting-Realtime-Required AVP is DELIVER_AND_GRANT, and hence + accounting connectivity problems are required to cause the serviced + user to be disconnected. Otherwise, records produced by the client + may be lost by the server which no longer accepts them after the + connectivity is re-established. This state machine is the third + state machine in this section. The state machine is supervised by a + supervision session timer Ts, which the value should be reasonably + + + +Fajardo, et al. Expires July 24, 2011 [Page 107] + +Internet-Draft Diameter Base Protocol January 2011 + + + higher than the Acct_Interim_Interval value. Ts MAY be set to two + times the value of the Acct_Interim_Interval so as to avoid the + accounting session in the Diameter server to change to Idle state in + case of short transient network failure. + + Any event not listed in the state machines MUST be considered as an + error condition, and a corresponding answer, if applicable, MUST be + returned to the originator of the message. + + In the state table, the event 'Failure to send' means that the + Diameter client is unable to communicate with the desired + destination. This could be due to the peer being down, or due to the + peer sending back a transient failure or temporary protocol error + notification DIAMETER_OUT_OF_SPACE, DIAMETER_TOO_BUSY, or + DIAMETER_LOOP_DETECTED in the Result-Code AVP of the Accounting + Answer command. + + The event 'Failed answer' means that the Diameter client received a + non-transient failure notification in the Accounting Answer command. + + Note that the action 'Disconnect user/dev' MUST have an effect also + to the authorization session state table, e.g., cause the STR message + to be sent, if the given application has both authentication/ + authorization and accounting portions. + + The states PendingS, PendingI, PendingL, PendingE and PendingB stand + for pending states to wait for an answer to an accounting request + related to a Start, Interim, Stop, Event or buffered record, + respectively. + + CLIENT, ACCOUNTING + State Event Action New State + --------------------------------------------------------------- + Idle Client or device requests Send PendingS + access accounting + start req. + + Idle Client or device requests Send PendingE + a one-time service accounting + event req + + Idle Records in storage Send PendingB + record + + PendingS Successful accounting Open + start answer received + + PendingS Failure to send and buffer Store Open + + + +Fajardo, et al. Expires July 24, 2011 [Page 108] + +Internet-Draft Diameter Base Protocol January 2011 + + + space available and realtime Start + not equal to DELIVER_AND_GRANT Record + + PendingS Failure to send and no buffer Open + space available and realtime + equal to GRANT_AND_LOSE + + PendingS Failure to send and no Disconnect Idle + buffer space available and user/dev + realtime not equal to + GRANT_AND_LOSE + + PendingS Failed accounting start answer Open + received and realtime equal + to GRANT_AND_LOSE + + PendingS Failed accounting start answer Disconnect Idle + received and realtime not user/dev + equal to GRANT_AND_LOSE + + PendingS User service terminated Store PendingS + stop + record + + Open Interim interval elapses Send PendingI + accounting + interim + record + Open User service terminated Send PendingL + accounting + stop req. + + PendingI Successful accounting interim Open + answer received + + PendingI Failure to send and (buffer Store Open + space available or old interim + record can be overwritten) record + and realtime not equal to + DELIVER_AND_GRANT + + PendingI Failure to send and no buffer Open + space available and realtime + equal to GRANT_AND_LOSE + + + PendingI Failure to send and no Disconnect Idle + buffer space available and user/dev + + + +Fajardo, et al. Expires July 24, 2011 [Page 109] + +Internet-Draft Diameter Base Protocol January 2011 + + + realtime not equal to + GRANT_AND_LOSE + + PendingI Failed accounting interim Open + answer received and realtime + equal to GRANT_AND_LOSE + + PendingI Failed accounting interim Disconnect Idle + answer received and user/dev + realtime not equal to + GRANT_AND_LOSE + + PendingI User service terminated Store PendingI + stop + record + PendingE Successful accounting Idle + event answer received + + PendingE Failure to send and buffer Store Idle + space available event + record + + PendingE Failure to send and no buffer Idle + space available + + PendingE Failed accounting event answer Idle + received + + PendingB Successful accounting answer Delete Idle + received record + + PendingB Failure to send Idle + + PendingB Failed accounting answer Delete Idle + received record + + PendingL Successful accounting Idle + stop answer received + + PendingL Failure to send and buffer Store Idle + space available stop + record + + PendingL Failure to send and no buffer Idle + space available + + PendingL Failed accounting stop answer Idle + received + + + +Fajardo, et al. Expires July 24, 2011 [Page 110] + +Internet-Draft Diameter Base Protocol January 2011 + + + SERVER, STATELESS ACCOUNTING + State Event Action New State + --------------------------------------------------------------- + + Idle Accounting start request Send Idle + received, and successfully accounting + processed. start + answer + + Idle Accounting event request Send Idle + received, and successfully accounting + processed. event + answer + + Idle Interim record received, Send Idle + and successfully processed. accounting + interim + answer + + Idle Accounting stop request Send Idle + received, and successfully accounting + processed stop answer + + Idle Accounting request received, Send Idle + no space left to store accounting + records answer, + Result-Code = + OUT_OF_ + SPACE + + SERVER, STATEFUL ACCOUNTING + State Event Action New State + --------------------------------------------------------------- + + Idle Accounting start request Send Open + received, and successfully accounting + processed. start + answer, + Start Ts + + Idle Accounting event request Send Idle + received, and successfully accounting + processed. event + answer + + Idle Accounting request received, Send Idle + no space left to store accounting + records answer, + + + +Fajardo, et al. Expires July 24, 2011 [Page 111] + +Internet-Draft Diameter Base Protocol January 2011 + + + Result-Code = + OUT_OF_ + SPACE + + Open Interim record received, Send Open + and successfully processed. accounting + interim + answer, + Restart Ts + + Open Accounting stop request Send Idle + received, and successfully accounting + processed stop answer, + Stop Ts + + Open Accounting request received, Send Idle + no space left to store accounting + records answer, + Result-Code = + OUT_OF_ + SPACE, + Stop Ts + + Open Session supervision timer Ts Stop Ts Idle + expired + +8.3. Server-Initiated Re-Auth + + A Diameter server may initiate a re-authentication and/or re- + authorization service for a particular session by issuing a Re-Auth- + Request (RAR). + + For example, for pre-paid services, the Diameter server that + originally authorized a session may need some confirmation that the + user is still using the services. + + An access device that receives a RAR message with Session-Id equal to + a currently active session MUST initiate a re-auth towards the user, + if the service supports this particular feature. Each Diameter + application MUST state whether server-initiated re-auth is supported, + since some applications do not allow access devices to prompt the + user for re-auth. + +8.3.1. Re-Auth-Request + + The Re-Auth-Request (RAR), indicated by the Command-Code set to 258 + and the message flags' 'R' bit set, may be sent by any server to the + access device that is providing session service, to request that the + + + +Fajardo, et al. Expires July 24, 2011 [Page 112] + +Internet-Draft Diameter Base Protocol January 2011 + + + user be re-authenticated and/or re-authorized. + + + Message Format + + <RAR> ::= < Diameter Header: 258, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Destination-Host } + { Auth-Application-Id } + { Re-Auth-Request-Type } + [ User-Name ] + [ Origin-State-Id ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.3.2. Re-Auth-Answer + + The Re-Auth-Answer (RAA), indicated by the Command-Code set to 258 + and the message flags' 'R' bit clear, is sent in response to the RAR. + The Result-Code AVP MUST be present, and indicates the disposition of + the request. + + A successful RAA message MUST be followed by an application-specific + authentication and/or authorization message. + + + Message Format + + <RAA> ::= < Diameter Header: 258, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + [ Origin-State-Id ] + [ Error-Message ] + [ Error-Reporting-Host ] + [ Failed-AVP ] + * [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ AVP ] + + + + +Fajardo, et al. Expires July 24, 2011 [Page 113] + +Internet-Draft Diameter Base Protocol January 2011 + + +8.4. Session Termination + + It is necessary for a Diameter server that authorized a session, for + which it is maintaining state, to be notified when that session is no + longer active, both for tracking purposes as well as to allow + stateful agents to release any resources that they may have provided + for the user's session. For sessions whose state is not being + maintained, this section is not used. + + When a user session that required Diameter authorization terminates, + the access device that provided the service MUST issue a Session- + Termination-Request (STR) message to the Diameter server that + authorized the service, to notify it that the session is no longer + active. An STR MUST be issued when a user session terminates for any + reason, including user logoff, expiration of Session-Timeout, + administrative action, termination upon receipt of an Abort-Session- + Request (see below), orderly shutdown of the access device, etc. + + The access device also MUST issue an STR for a session that was + authorized but never actually started. This could occur, for + example, due to a sudden resource shortage in the access device, or + because the access device is unwilling to provide the type of service + requested in the authorization, or because the access device does not + support a mandatory AVP returned in the authorization, etc. + + It is also possible that a session that was authorized is never + actually started due to action of a proxy. For example, a proxy may + modify an authorization answer, converting the result from success to + failure, prior to forwarding the message to the access device. If + the answer did not contain an Auth-Session-State AVP with the value + NO_STATE_MAINTAINED, a proxy that causes an authorized session not to + be started MUST issue an STR to the Diameter server that authorized + the session, since the access device has no way of knowing that the + session had been authorized. + + A Diameter server that receives an STR message MUST clean up + resources (e.g., session state) associated with the Session-Id + specified in the STR, and return a Session-Termination-Answer. + + A Diameter server also MUST clean up resources when the Session- + Timeout expires, or when the Authorization-Lifetime and the Auth- + Grace-Period AVPs expires without receipt of a re-authorization + request, regardless of whether an STR for that session is received. + The access device is not expected to provide service beyond the + expiration of these timers; thus, expiration of either of these + timers implies that the access device may have unexpectedly shut + down. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 114] + +Internet-Draft Diameter Base Protocol January 2011 + + +8.4.1. Session-Termination-Request + + The Session-Termination-Request (STR), indicated by the Command-Code + set to 275 and the Command Flags' 'R' bit set, is sent by a Diameter + client or by a Diameter proxy to inform the Diameter Server that an + authenticated and/or authorized session is being terminated. + + + Message Format + + <STR> ::= < Diameter Header: 275, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Auth-Application-Id } + { Termination-Cause } + [ User-Name ] + [ Destination-Host ] + * [ Class ] + [ Origin-State-Id ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.4.2. Session-Termination-Answer + + The Session-Termination-Answer (STA), indicated by the Command-Code + set to 275 and the message flags' 'R' bit clear, is sent by the + Diameter Server to acknowledge the notification that the session has + been terminated. The Result-Code AVP MUST be present, and MAY + contain an indication that an error occurred while servicing the STR. + + Upon sending or receipt of the STA, the Diameter Server MUST release + all resources for the session indicated by the Session-Id AVP. Any + intermediate server in the Proxy-Chain MAY also release any + resources, if necessary. + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 115] + +Internet-Draft Diameter Base Protocol January 2011 + + + Message Format + + <STA> ::= < Diameter Header: 275, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + * [ Class ] + [ Error-Message ] + [ Error-Reporting-Host ] + [ Failed-AVP ] + [ Origin-State-Id ] + * [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ AVP ] + +8.5. Aborting a Session + + A Diameter server may request that the access device stop providing + service for a particular session by issuing an Abort-Session-Request + (ASR). + + For example, the Diameter server that originally authorized the + session may be required to cause that session to be stopped for lack + of credit or other reasons that were not anticipated when the session + was first authorized. + + An access device that receives an ASR with Session-ID equal to a + currently active session MAY stop the session. Whether the access + device stops the session or not is implementation- and/or + configuration-dependent. For example, an access device may honor + ASRs from certain agents only. In any case, the access device MUST + respond with an Abort-Session-Answer, including a Result-Code AVP to + indicate what action it took. + +8.5.1. Abort-Session-Request + + The Abort-Session-Request (ASR), indicated by the Command-Code set to + 274 and the message flags' 'R' bit set, may be sent by any Diameter + server or any Diameter proxy to the access device that is providing + session service, to request that the session identified by the + Session-Id be stopped. + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 116] + +Internet-Draft Diameter Base Protocol January 2011 + + + Message Format + + <ASR> ::= < Diameter Header: 274, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Destination-Host } + { Auth-Application-Id } + [ User-Name ] + [ Origin-State-Id ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.5.2. Abort-Session-Answer + + The Abort-Session-Answer (ASA), indicated by the Command-Code set to + 274 and the message flags' 'R' bit clear, is sent in response to the + ASR. The Result-Code AVP MUST be present, and indicates the + disposition of the request. + + If the session identified by Session-Id in the ASR was successfully + terminated, Result-Code is set to DIAMETER_SUCCESS. If the session + is not currently active, Result-Code is set to + DIAMETER_UNKNOWN_SESSION_ID. If the access device does not stop the + session for any other reason, Result-Code is set to + DIAMETER_UNABLE_TO_COMPLY. + + + Message Format + + <ASA> ::= < Diameter Header: 274, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + [ Origin-State-Id ] + [ Error-Message ] + [ Error-Reporting-Host ] + [ Failed-AVP ] + * [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ AVP ] + + + + +Fajardo, et al. Expires July 24, 2011 [Page 117] + +Internet-Draft Diameter Base Protocol January 2011 + + +8.6. Inferring Session Termination from Origin-State-Id + + The Origin-State-Id is used to allow detection of terminated sessions + for which no STR would have been issued, due to unanticipated + shutdown of an access device. + + A Diameter client or access device increments the value of the + Origin-State-Id every time it is started or powered-up. The new + Origin-State-Id is then sent in the CER/CEA message immediately upon + connection to the server. The Diameter server receiving the new + Origin-State-Id can determine whether the sending Diameter client had + abruptly shutdown by comparing the old value of the Origin-State-Id + it has kept for that specific client is less than the new value and + whether it has un-terminated sessions originating from that client. + + An access device can also include the Origin-State-Id in request + messages other than CER if there are relays or proxies in between the + access device and the server. In this case, however, the server + cannot discover that the access device has been restarted unless and + until it receives a new request from it. Therefore this mechanism is + more opportunistic across proxies and relays. + + The Diameter server may assume that all sessions that were active + prior to detection of a client restart have been terminated. The + Diameter server MAY clean up all session state associated with such + lost sessions, and MAY also issues STRs for all such lost sessions + that were authorized on upstream servers, to allow session state to + be cleaned up globally. + +8.7. Auth-Request-Type AVP + + The Auth-Request-Type AVP (AVP Code 274) is of type Enumerated and is + included in application-specific auth requests to inform the peers + whether a user is to be authenticated only, authorized only or both. + Note any value other than both MAY cause RADIUS interoperability + issues. The following values are defined: + + + AUTHENTICATE_ONLY 1 + + The request being sent is for authentication only, and MUST + contain the relevant application specific authentication AVPs that + are needed by the Diameter server to authenticate the user. + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 118] + +Internet-Draft Diameter Base Protocol January 2011 + + + AUTHORIZE_ONLY 2 + + The request being sent is for authorization only, and MUST contain + the application-specific authorization AVPs that are necessary to + identify the service being requested/offered. + + + AUTHORIZE_AUTHENTICATE 3 + + The request contains a request for both authentication and + authorization. The request MUST include both the relevant + application-specific authentication information, and authorization + information necessary to identify the service being requested/ + offered. + + +8.8. Session-Id AVP + + The Session-Id AVP (AVP Code 263) is of type UTF8String and is used + to identify a specific session (see Section 8). All messages + pertaining to a specific session MUST include only one Session-Id AVP + and the same value MUST be used throughout the life of a session. + When present, the Session-Id SHOULD appear immediately following the + Diameter Header (see Section 3). + + The Session-Id MUST be globally and eternally unique, as it is meant + to uniquely identify a user session without reference to any other + information, and may be needed to correlate historical authentication + information with accounting information. The Session-Id includes a + mandatory portion and an implementation-defined portion; a + recommended format for the implementation-defined portion is outlined + below. + + The Session-Id MUST begin with the sender's identity encoded in the + DiameterIdentity type (see Section 4.4). The remainder of the + Session-Id is delimited by a ";" character, and MAY be any sequence + that the client can guarantee to be eternally unique; however, the + following format is recommended, (square brackets [] indicate an + optional element): + + <DiameterIdentity>;<high 32 bits>;<low 32 bits>[;<optional value>] + + <high 32 bits> and <low 32 bits> are decimal representations of the + high and low 32 bits of a monotonically increasing 64-bit value. The + 64-bit value is rendered in two part to simplify formatting by 32-bit + processors. At startup, the high 32 bits of the 64-bit value MAY be + initialized to the time in NTP format [RFC5905], and the low 32 bits + MAY be initialized to zero. This will for practical purposes + + + +Fajardo, et al. Expires July 24, 2011 [Page 119] + +Internet-Draft Diameter Base Protocol January 2011 + + + eliminate the possibility of overlapping Session-Ids after a reboot, + assuming the reboot process takes longer than a second. + Alternatively, an implementation MAY keep track of the increasing + value in non-volatile memory. + + + <optional value> is implementation specific but may include a modem's + device Id, a layer 2 address, timestamp, etc. + + Example, in which there is no optional value: + + accesspoint7.example.com;1876543210;523 + + Example, in which there is an optional value: + + accesspoint7.example.com;1876543210;523;[email protected] + + The Session-Id is created by the Diameter application initiating the + session, which in most cases is done by the client. Note that a + Session-Id MAY be used for both the authentication, authorization and + accounting commands of a given application. + +8.9. Authorization-Lifetime AVP + + The Authorization-Lifetime AVP (AVP Code 291) is of type Unsigned32 + and contains the maximum number of seconds of service to be provided + to the user before the user is to be re-authenticated and/or re- + authorized. Care should be taken when the Authorization- Lifetime + value is determined, since a low, non-zero, value could create + significant Diameter traffic, which could congest both the network + and the agents. + + A value of zero (0) means that immediate re-auth is necessary by the + access device. The absence of this AVP, or a value of all ones + (meaning all bits in the 32 bit field are set to one) means no re- + auth is expected. + + If both this AVP and the Session-Timeout AVP are present in a + message, the value of the latter MUST NOT be smaller than the + Authorization-Lifetime AVP. + + An Authorization-Lifetime AVP MAY be present in re-authorization + messages, and contains the number of seconds the user is authorized + to receive service from the time the re-auth answer message is + received by the access device. + + This AVP MAY be provided by the client as a hint of the maximum + lifetime that it is willing to accept. The server MUST return a + + + +Fajardo, et al. Expires July 24, 2011 [Page 120] + +Internet-Draft Diameter Base Protocol January 2011 + + + value that is equal to, or smaller, than the one provided by the + client. + +8.10. Auth-Grace-Period AVP + + The Auth-Grace-Period AVP (AVP Code 276) is of type Unsigned32 and + contains the number of seconds the Diameter server will wait + following the expiration of the Authorization-Lifetime AVP before + cleaning up resources for the session. + +8.11. Auth-Session-State AVP + + The Auth-Session-State AVP (AVP Code 277) is of type Enumerated and + specifies whether state is maintained for a particular session. The + client MAY include this AVP in requests as a hint to the server, but + the value in the server's answer message is binding. The following + values are supported: + + + STATE_MAINTAINED 0 + + This value is used to specify that session state is being + maintained, and the access device MUST issue a session termination + message when service to the user is terminated. This is the + default value. + + + NO_STATE_MAINTAINED 1 + + This value is used to specify that no session termination messages + will be sent by the access device upon expiration of the + Authorization-Lifetime. + + +8.12. Re-Auth-Request-Type AVP + + The Re-Auth-Request-Type AVP (AVP Code 285) is of type Enumerated and + is included in application-specific auth answers to inform the client + of the action expected upon expiration of the Authorization-Lifetime. + If the answer message contains an Authorization-Lifetime AVP with a + positive value, the Re-Auth-Request-Type AVP MUST be present in an + answer message. The following values are defined: + + + AUTHORIZE_ONLY 0 + + An authorization only re-auth is expected upon expiration of the + Authorization-Lifetime. This is the default value if the AVP is + + + +Fajardo, et al. Expires July 24, 2011 [Page 121] + +Internet-Draft Diameter Base Protocol January 2011 + + + not present in answer messages that include the Authorization- + Lifetime. + + + AUTHORIZE_AUTHENTICATE 1 + + An authentication and authorization re-auth is expected upon + expiration of the Authorization-Lifetime. + + +8.13. Session-Timeout AVP + + The Session-Timeout AVP (AVP Code 27) [RFC2865] is of type Unsigned32 + and contains the maximum number of seconds of service to be provided + to the user before termination of the session. When both the + Session-Timeout and the Authorization-Lifetime AVPs are present in an + answer message, the former MUST be equal to or greater than the value + of the latter. + + A session that terminates on an access device due to the expiration + of the Session-Timeout MUST cause an STR to be issued, unless both + the access device and the home server had previously agreed that no + session termination messages would be sent (see Section 8.11). + + A Session-Timeout AVP MAY be present in a re-authorization answer + message, and contains the remaining number of seconds from the + beginning of the re-auth. + + A value of zero, or the absence of this AVP, means that this session + has an unlimited number of seconds before termination. + + This AVP MAY be provided by the client as a hint of the maximum + timeout that it is willing to accept. However, the server MAY return + a value that is equal to, or smaller, than the one provided by the + client. + +8.14. User-Name AVP + + The User-Name AVP (AVP Code 1) [RFC2865] is of type UTF8String, which + contains the User-Name, in a format consistent with the NAI + specification [RFC4282]. + +8.15. Termination-Cause AVP + + The Termination-Cause AVP (AVP Code 295) is of type Enumerated, and + is used to indicate the reason why a session was terminated on the + access device. The following values are defined: + + + + +Fajardo, et al. Expires July 24, 2011 [Page 122] + +Internet-Draft Diameter Base Protocol January 2011 + + + DIAMETER_LOGOUT 1 + + The user initiated a disconnect + + + DIAMETER_SERVICE_NOT_PROVIDED 2 + + This value is used when the user disconnected prior to the receipt + of the authorization answer message. + + + DIAMETER_BAD_ANSWER 3 + + This value indicates that the authorization answer received by the + access device was not processed successfully. + + + DIAMETER_ADMINISTRATIVE 4 + + The user was not granted access, or was disconnected, due to + administrative reasons, such as the receipt of a Abort-Session- + Request message. + + + DIAMETER_LINK_BROKEN 5 + + The communication to the user was abruptly disconnected. + + + DIAMETER_AUTH_EXPIRED 6 + + The user's access was terminated since its authorized session time + has expired. + + + DIAMETER_USER_MOVED 7 + + The user is receiving services from another access device. + + + DIAMETER_SESSION_TIMEOUT 8 + + The user's session has timed out, and service has been terminated. + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 123] + +Internet-Draft Diameter Base Protocol January 2011 + + +8.16. Origin-State-Id AVP + + The Origin-State-Id AVP (AVP Code 278), of type Unsigned32, is a + monotonically increasing value that is advanced whenever a Diameter + entity restarts with loss of previous state, for example upon reboot. + Origin-State-Id MAY be included in any Diameter message, including + CER. + + A Diameter entity issuing this AVP MUST create a higher value for + this AVP each time its state is reset. A Diameter entity MAY set + Origin-State-Id to the time of startup, or it MAY use an incrementing + counter retained in non-volatile memory across restarts. + + The Origin-State-Id, if present, MUST reflect the state of the entity + indicated by Origin-Host. If a proxy modifies Origin-Host, it MUST + either remove Origin-State-Id or modify it appropriately as well. + Typically, Origin-State-Id is used by an access device that always + starts up with no active sessions; that is, any session active prior + to restart will have been lost. By including Origin-State-Id in a + message, it allows other Diameter entities to infer that sessions + associated with a lower Origin-State-Id are no longer active. If an + access device does not intend for such inferences to be made, it MUST + either not include Origin-State-Id in any message, or set its value + to 0. + +8.17. Session-Binding AVP + + The Session-Binding AVP (AVP Code 270) is of type Unsigned32, and MAY + be present in application-specific authorization answer messages. If + present, this AVP MAY inform the Diameter client that all future + application-specific re-auth and Session-Termination-Request messages + for this session MUST be sent to the same authorization server. + + This field is a bit mask, and the following bits have been defined: + + + RE_AUTH 1 + + When set, future re-auth messages for this session MUST NOT + include the Destination-Host AVP. When cleared, the default + value, the Destination-Host AVP MUST be present in all re-auth + messages for this session. + + + STR 2 + + When set, the STR message for this session MUST NOT include the + Destination-Host AVP. When cleared, the default value, the + + + +Fajardo, et al. Expires July 24, 2011 [Page 124] + +Internet-Draft Diameter Base Protocol January 2011 + + + Destination-Host AVP MUST be present in the STR message for this + session. + + + ACCOUNTING 4 + + When set, all accounting messages for this session MUST NOT + include the Destination-Host AVP. When cleared, the default + value, the Destination-Host AVP, if known, MUST be present in all + accounting messages for this session. + + +8.18. Session-Server-Failover AVP + + The Session-Server-Failover AVP (AVP Code 271) is of type Enumerated, + and MAY be present in application-specific authorization answer + messages that either do not include the Session-Binding AVP or + include the Session-Binding AVP with any of the bits set to a zero + value. If present, this AVP MAY inform the Diameter client that if a + re-auth or STR message fails due to a delivery problem, the Diameter + client SHOULD issue a subsequent message without the Destination-Host + AVP. When absent, the default value is REFUSE_SERVICE. + + The following values are supported: + + + REFUSE_SERVICE 0 + + If either the re-auth or the STR message delivery fails, terminate + service with the user, and do not attempt any subsequent attempts. + + + TRY_AGAIN 1 + + If either the re-auth or the STR message delivery fails, resend + the failed message without the Destination-Host AVP present. + + + ALLOW_SERVICE 2 + + If re-auth message delivery fails, assume that re-authorization + succeeded. If STR message delivery fails, terminate the session. + + + TRY_AGAIN_ALLOW_SERVICE 3 + + If either the re-auth or the STR message delivery fails, resend + the failed message without the Destination-Host AVP present. If + + + +Fajardo, et al. Expires July 24, 2011 [Page 125] + +Internet-Draft Diameter Base Protocol January 2011 + + + the second delivery fails for re-auth, assume re-authorization + succeeded. If the second delivery fails for STR, terminate the + session. + + +8.19. Multi-Round-Time-Out AVP + + The Multi-Round-Time-Out AVP (AVP Code 272) is of type Unsigned32, + and SHOULD be present in application-specific authorization answer + messages whose Result-Code AVP is set to DIAMETER_MULTI_ROUND_AUTH. + This AVP contains the maximum number of seconds that the access + device MUST provide the user in responding to an authentication + request. + +8.20. Class AVP + + The Class AVP (AVP Code 25) is of type OctetString and is used by + Diameter servers to return state information to the access device. + When one or more Class AVPs are present in application-specific + authorization answer messages, they MUST be present in subsequent re- + authorization, session termination and accounting messages. Class + AVPs found in a re-authorization answer message override the ones + found in any previous authorization answer message. Diameter server + implementations SHOULD NOT return Class AVPs that require more than + 4096 bytes of storage on the Diameter client. A Diameter client that + receives Class AVPs whose size exceeds local available storage MUST + terminate the session. + +8.21. Event-Timestamp AVP + + The Event-Timestamp (AVP Code 55) is of type Time, and MAY be + included in an Accounting-Request and Accounting-Answer messages to + record the time that the reported event occurred, in seconds since + January 1, 1900 00:00 UTC. + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 126] + +Internet-Draft Diameter Base Protocol January 2011 + + +9. Accounting + + This accounting protocol is based on a server directed model with + capabilities for real-time delivery of accounting information. + Several fault resilience methods [RFC2975] have been built in to the + protocol in order minimize loss of accounting data in various fault + situations and under different assumptions about the capabilities of + the used devices. + +9.1. Server Directed Model + + The server directed model means that the device generating the + accounting data gets information from either the authorization server + (if contacted) or the accounting server regarding the way accounting + data shall be forwarded. This information includes accounting record + timeliness requirements. + + As discussed in [RFC2975], real-time transfer of accounting records + is a requirement, such as the need to perform credit limit checks and + fraud detection. Note that batch accounting is not a requirement, + and is therefore not supported by Diameter. Should batched + accounting be required in the future, a new Diameter application will + need to be created, or it could be handled using another protocol. + Note, however, that even if at the Diameter layer accounting requests + are processed one by one, transport protocols used under Diameter + typically batch several requests in the same packet under heavy + traffic conditions. This may be sufficient for many applications. + + The authorization server (chain) directs the selection of proper + transfer strategy, based on its knowledge of the user and + relationships of roaming partnerships. The server (or agents) uses + the Acct-Interim-Interval and Accounting-Realtime-Required AVPs to + control the operation of the Diameter peer operating as a client. + The Acct-Interim-Interval AVP, when present, instructs the Diameter + node acting as a client to produce accounting records continuously + even during a session. Accounting-Realtime-Required AVP is used to + control the behavior of the client when the transfer of accounting + records from the Diameter client is delayed or unsuccessful. + + The Diameter accounting server MAY override the interim interval or + the realtime requirements by including the Acct-Interim-Interval or + Accounting-Realtime-Required AVP in the Accounting-Answer message. + When one of these AVPs is present, the latest value received SHOULD + be used in further accounting activities for the same session. + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 127] + +Internet-Draft Diameter Base Protocol January 2011 + + +9.2. Protocol Messages + + A Diameter node that receives a successful authentication and/or + authorization messages from the Diameter server SHOULD collect + accounting information for the session. The Accounting-Request + message is used to transmit the accounting information to the + Diameter server, which MUST reply with the Accounting-Answer message + to confirm reception. The Accounting-Answer message includes the + Result-Code AVP, which MAY indicate that an error was present in the + accounting message. The value of the Accounting-Realtime-Required + AVP received earlier for the session in question may indicate that + the user's session has to be terminated when a rejected Accounting- + Request message was received. + +9.3. Accounting Application Extension and Requirements + + Each Diameter application (e.g., NASREQ, MobileIP), SHOULD define + their Service-Specific AVPs that MUST be present in the Accounting- + Request message in a section entitled "Accounting AVPs". The + application MUST assume that the AVPs described in this document will + be present in all Accounting messages, so only their respective + service-specific AVPs need to be defined in that section. + + Applications have the option of using one or both of the following + accounting application extension models: + + Split Accounting Service + + The accounting message will carry the Application Id of the + Diameter base accounting application (see Section 2.4). + Accounting messages may be routed to Diameter nodes other than the + corresponding Diameter application. These nodes might be + centralized accounting servers that provide accounting service for + multiple different Diameter applications. These nodes MUST + advertise the Diameter base accounting Application Id during + capabilities exchange. + + + Coupled Accounting Service + + The accounting messages will carry the Application Id of the + application that is using it. The application itself will process + the received accounting records or forward them to an accounting + server. There is no accounting application advertisement required + during capabilities exchange and the accounting messages will be + routed the same as any of the other application messages. + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 128] + +Internet-Draft Diameter Base Protocol January 2011 + + + In cases where an application does not define its own accounting + service, it is preferred that the split accounting model be used. + +9.4. Fault Resilience + + Diameter Base protocol mechanisms are used to overcome small message + loss and network faults of temporary nature. + + Diameter peers acting as clients MUST implement the use of failover + to guard against server failures and certain network failures. + Diameter peers acting as agents or related off-line processing + systems MUST detect duplicate accounting records caused by the + sending of same record to several servers and duplication of messages + in transit. This detection MUST be based on the inspection of the + Session-Id and Accounting-Record-Number AVP pairs. Appendix C + discusses duplicate detection needs and implementation issues. + + Diameter clients MAY have non-volatile memory for the safe storage of + accounting records over reboots or extended network failures, network + partitions, and server failures. If such memory is available, the + client SHOULD store new accounting records there as soon as the + records are created and until a positive acknowledgement of their + reception from the Diameter Server has been received. Upon a reboot, + the client MUST starting sending the records in the non-volatile + memory to the accounting server with appropriate modifications in + termination cause, session length, and other relevant information in + the records. + + A further application of this protocol may include AVPs to control + how many accounting records may at most be stored in the Diameter + client without committing them to the non-volatile memory or + transferring them to the Diameter server. + + The client SHOULD NOT remove the accounting data from any of its + memory areas before the correct Accounting-Answer has been received. + The client MAY remove oldest, undelivered or yet unacknowledged + accounting data if it runs out of resources such as memory. It is an + implementation dependent matter for the client to accept new sessions + under this condition. + +9.5. Accounting Records + + In all accounting records, the Session-Id AVP MUST be present; the + User-Name AVP MUST be present if it is available to the Diameter + client. + + Different types of accounting records are sent depending on the + actual type of accounted service and the authorization server's + + + +Fajardo, et al. Expires July 24, 2011 [Page 129] + +Internet-Draft Diameter Base Protocol January 2011 + + + directions for interim accounting. If the accounted service is a + one-time event, meaning that the start and stop of the event are + simultaneous, then the Accounting-Record-Type AVP MUST be present and + set to the value EVENT_RECORD. + + If the accounted service is of a measurable length, then the AVP MUST + use the values START_RECORD, STOP_RECORD, and possibly, + INTERIM_RECORD. If the authorization server has not directed interim + accounting to be enabled for the session, two accounting records MUST + be generated for each service of type session. When the initial + Accounting-Request for a given session is sent, the Accounting- + Record-Type AVP MUST be set to the value START_RECORD. When the last + Accounting-Request is sent, the value MUST be STOP_RECORD. + + If the authorization server has directed interim accounting to be + enabled, the Diameter client MUST produce additional records between + the START_RECORD and STOP_RECORD, marked INTERIM_RECORD. The + production of these records is directed by Acct-Interim-Interval as + well as any re-authentication or re-authorization of the session. + The Diameter client MUST overwrite any previous interim accounting + records that are locally stored for delivery, if a new record is + being generated for the same session. This ensures that only one + pending interim record can exist on an access device for any given + session. + + A particular value of Accounting-Sub-Session-Id MUST appear only in + one sequence of accounting records from a DIAMETER client, except for + the purposes of retransmission. The one sequence that is sent MUST + be either one record with Accounting-Record-Type AVP set to the value + EVENT_RECORD, or several records starting with one having the value + START_RECORD, followed by zero or more INTERIM_RECORD and a single + STOP_RECORD. A particular Diameter application specification MUST + define the type of sequences that MUST be used. + +9.6. Correlation of Accounting Records + + If an application uses accounting messages, it can correlate + accounting records with a specific application session by using the + Session-Id of the particular application session in the accounting + messages. Accounting messages MAY also use a different Session-Id + from that of the application sessions in which case other session + related information is needed to perform correlation. + + In cases where an application requires multiple accounting sub- + session, an Accounting-Sub-Session-Id AVP is used to differentiate + each sub-session. The Session-Id would remain constant for all sub- + sessions and is be used to correlate all the sub-sessions to a + particular application session. Note that receiving a STOP_RECORD + + + +Fajardo, et al. Expires July 24, 2011 [Page 130] + +Internet-Draft Diameter Base Protocol January 2011 + + + with no Accounting-Sub-Session-Id AVP when sub-sessions were + originally used in the START_RECORD messages implies that all sub- + sessions are terminated. + + There are also cases where an application needs to correlate multiple + application sessions into a single accounting record; the accounting + record may span multiple different Diameter applications and sessions + used by the same user at a given time. In such cases, the Acct- + Multi-Session-Id AVP is used. The Acct-Multi-Session-Id AVP SHOULD + be signaled by the server to the access device (typically during + authorization) when it determines that a request belongs to an + existing session. The access device MUST then include the Acct- + Multi-Session-Id AVP in all subsequent accounting messages. + + The Acct-Multi-Session-Id AVP MAY include the value of the original + Session-Id. It's contents are implementation specific, but MUST be + globally unique across other Acct-Multi-Session-Id, and MUST NOT + change during the life of a session. + + A Diameter application document MUST define the exact concept of a + session that is being accounted, and MAY define the concept of a + multi-session. For instance, the NASREQ DIAMETER application treats + a single PPP connection to a Network Access Server as one session, + and a set of Multilink PPP sessions as one multi-session. + +9.7. Accounting Command-Codes + + This section defines Command-Code values that MUST be supported by + all Diameter implementations that provide Accounting services. + +9.7.1. Accounting-Request + + The Accounting-Request (ACR) command, indicated by the Command-Code + field set to 271 and the Command Flags' 'R' bit set, is sent by a + Diameter node, acting as a client, in order to exchange accounting + information with a peer. + + The AVP listed below SHOULD include service-specific accounting AVPs, + as described in Section 9.3. + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 131] + +Internet-Draft Diameter Base Protocol January 2011 + + + Message Format + + <ACR> ::= < Diameter Header: 271, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Accounting-Record-Type } + { Accounting-Record-Number } + [ Acct-Application-Id ] + [ Vendor-Specific-Application-Id ] + [ User-Name ] + [ Destination-Host ] + [ Accounting-Sub-Session-Id ] + [ Acct-Session-Id ] + [ Acct-Multi-Session-Id ] + [ Acct-Interim-Interval ] + [ Accounting-Realtime-Required ] + [ Origin-State-Id ] + [ Event-Timestamp ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +9.7.2. Accounting-Answer + + The Accounting-Answer (ACA) command, indicated by the Command-Code + field set to 271 and the Command Flags' 'R' bit cleared, is used to + acknowledge an Accounting-Request command. The Accounting-Answer + command contains the same Session-Id as the corresponding request. + + Only the target Diameter Server, known as the home Diameter Server, + SHOULD respond with the Accounting-Answer command. + + The AVP listed below SHOULD include service-specific accounting AVPs, + as described in Section 9.3. + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 132] + +Internet-Draft Diameter Base Protocol January 2011 + + + Message Format + + <ACA> ::= < Diameter Header: 271, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + { Accounting-Record-Type } + { Accounting-Record-Number } + [ Acct-Application-Id ] + [ Vendor-Specific-Application-Id ] + [ User-Name ] + [ Accounting-Sub-Session-Id ] + [ Acct-Session-Id ] + [ Acct-Multi-Session-Id ] + [ Error-Message ] + [ Error-Reporting-Host ] + [ Failed-AVP ] + [ Acct-Interim-Interval ] + [ Accounting-Realtime-Required ] + [ Origin-State-Id ] + [ Event-Timestamp ] + * [ Proxy-Info ] + * [ AVP ] + +9.8. Accounting AVPs + + This section contains AVPs that describe accounting usage information + related to a specific session. + +9.8.1. Accounting-Record-Type AVP + + The Accounting-Record-Type AVP (AVP Code 480) is of type Enumerated + and contains the type of accounting record being sent. The following + values are currently defined for the Accounting-Record-Type AVP: + + + EVENT_RECORD 1 + + An Accounting Event Record is used to indicate that a one-time + event has occurred (meaning that the start and end of the event + are simultaneous). This record contains all information relevant + to the service, and is the only record of the service. + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 133] + +Internet-Draft Diameter Base Protocol January 2011 + + + START_RECORD 2 + + An Accounting Start, Interim, and Stop Records are used to + indicate that a service of a measurable length has been given. An + Accounting Start Record is used to initiate an accounting session, + and contains accounting information that is relevant to the + initiation of the session. + + + INTERIM_RECORD 3 + + An Interim Accounting Record contains cumulative accounting + information for an existing accounting session. Interim + Accounting Records SHOULD be sent every time a re-authentication + or re-authorization occurs. Further, additional interim record + triggers MAY be defined by application-specific Diameter + applications. The selection of whether to use INTERIM_RECORD + records is done by the Acct-Interim-Interval AVP. + + + STOP_RECORD 4 + + An Accounting Stop Record is sent to terminate an accounting + session and contains cumulative accounting information relevant to + the existing session. + + +9.8.2. Acct-Interim-Interval AVP + + The Acct-Interim-Interval AVP (AVP Code 85) is of type Unsigned32 and + is sent from the Diameter home authorization server to the Diameter + client. The client uses information in this AVP to decide how and + when to produce accounting records. With different values in this + AVP, service sessions can result in one, two, or two+N accounting + records, based on the needs of the home-organization. The following + accounting record production behavior is directed by the inclusion of + this AVP: + + + 1. The omission of the Acct-Interim-Interval AVP or its inclusion + with Value field set to 0 means that EVENT_RECORD, START_RECORD, + and STOP_RECORD are produced, as appropriate for the service. + + + 2. The inclusion of the AVP with Value field set to a non-zero value + means that INTERIM_RECORD records MUST be produced between the + START_RECORD and STOP_RECORD records. The Value field of this + AVP is the nominal interval between these records in seconds. + + + +Fajardo, et al. Expires July 24, 2011 [Page 134] + +Internet-Draft Diameter Base Protocol January 2011 + + + The Diameter node that originates the accounting information, + known as the client, MUST produce the first INTERIM_RECORD record + roughly at the time when this nominal interval has elapsed from + the START_RECORD, the next one again as the interval has elapsed + once more, and so on until the session ends and a STOP_RECORD + record is produced. + + The client MUST ensure that the interim record production times + are randomized so that large accounting message storms are not + created either among records or around a common service start + time. + +9.8.3. Accounting-Record-Number AVP + + The Accounting-Record-Number AVP (AVP Code 485) is of type Unsigned32 + and identifies this record within one session. As Session-Id AVPs + are globally unique, the combination of Session-Id and Accounting- + Record-Number AVPs is also globally unique, and can be used in + matching accounting records with confirmations. An easy way to + produce unique numbers is to set the value to 0 for records of type + EVENT_RECORD and START_RECORD, and set the value to 1 for the first + INTERIM_RECORD, 2 for the second, and so on until the value for + STOP_RECORD is one more than for the last INTERIM_RECORD. + +9.8.4. Acct-Session-Id AVP + + The Acct-Session-Id AVP (AVP Code 44) is of type OctetString is only + used when RADIUS/Diameter translation occurs. This AVP contains the + contents of the RADIUS Acct-Session-Id attribute. + +9.8.5. Acct-Multi-Session-Id AVP + + The Acct-Multi-Session-Id AVP (AVP Code 50) is of type UTF8String, + following the format specified in Section 8.8. The Acct-Multi- + Session-Id AVP is used to link together multiple related accounting + sessions, where each session would have a unique Session-Id, but the + same Acct-Multi-Session-Id AVP. This AVP MAY be returned by the + Diameter server in an authorization answer, and MUST be used in all + accounting messages for the given session. + +9.8.6. Accounting-Sub-Session-Id AVP + + The Accounting-Sub-Session-Id AVP (AVP Code 287) is of type + Unsigned64 and contains the accounting sub-session identifier. The + combination of the Session-Id and this AVP MUST be unique per sub- + session, and the value of this AVP MUST be monotonically increased by + one for all new sub-sessions. The absence of this AVP implies no + sub-sessions are in use, with the exception of an Accounting-Request + + + +Fajardo, et al. Expires July 24, 2011 [Page 135] + +Internet-Draft Diameter Base Protocol January 2011 + + + whose Accounting-Record-Type is set to STOP_RECORD. A STOP_RECORD + message with no Accounting-Sub-Session-Id AVP present will signal the + termination of all sub-sessions for a given Session-Id. + +9.8.7. Accounting-Realtime-Required AVP + + The Accounting-Realtime-Required AVP (AVP Code 483) is of type + Enumerated and is sent from the Diameter home authorization server to + the Diameter client or in the Accounting-Answer from the accounting + server. The client uses information in this AVP to decide what to do + if the sending of accounting records to the accounting server has + been temporarily prevented due to, for instance, a network problem. + + + DELIVER_AND_GRANT 1 + + The AVP with Value field set to DELIVER_AND_GRANT means that the + service MUST only be granted as long as there is a connection to + an accounting server. Note that the set of alternative accounting + servers are treated as one server in this sense. Having to move + the accounting record stream to a backup server is not a reason to + discontinue the service to the user. + + + GRANT_AND_STORE 2 + + The AVP with Value field set to GRANT_AND_STORE means that service + SHOULD be granted if there is a connection, or as long as records + can still be stored as described in Section 9.4. + + This is the default behavior if the AVP isn't included in the + reply from the authorization server. + + + GRANT_AND_LOSE 3 + + The AVP with Value field set to GRANT_AND_LOSE means that service + SHOULD be granted even if the records cannot be delivered or + stored. + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 136] + +Internet-Draft Diameter Base Protocol January 2011 + + +10. AVP Occurrence Table + + The following tables presents the AVPs defined in this document, and + specifies in which Diameter messages they MAY be present or not. + AVPs that occur only inside a Grouped AVP are not shown in this + table. + + The table uses the following symbols: + + + 0 The AVP MUST NOT be present in the message. + + 0+ Zero or more instances of the AVP MAY be present in the + message. + + 0-1 Zero or one instance of the AVP MAY be present in the message. + It is considered an error if there are more than one instance of + the AVP. + + 1 One instance of the AVP MUST be present in the message. + + 1+ At least one instance of the AVP MUST be present in the + message. + +10.1. Base Protocol Command AVP Table + + The table in this section is limited to the non-accounting Command + Codes defined in this specification. + + +-----------------------------------------------+ + | Command-Code | + +---+---+---+---+---+---+---+---+---+---+---+---+ + Attribute Name |CER|CEA|DPR|DPA|DWR|DWA|RAR|RAA|ASR|ASA|STR|STA| + --------------------+---+---+---+---+---+---+---+---+---+---+---+---+ + Acct-Interim- |0 |0 |0 |0 |0 |0 |0-1|0 |0 |0 |0 |0 | + Interval | | | | | | | | | | | | | + Accounting-Realtime-|0 |0 |0 |0 |0 |0 |0-1|0 |0 |0 |0 |0 | + Required | | | | | | | | | | | | | + Acct-Application-Id |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Auth-Application-Id |0+ |0+ |0 |0 |0 |0 |1 |0 |1 |0 |1 |0 | + Auth-Grace-Period |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Auth-Request-Type |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Auth-Session-State |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Authorization- |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Lifetime | | | | | | | | | | | | | + Class |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0+ |0+ | + Destination-Host |0 |0 |0 |0 |0 |0 |1 |0 |1 |0 |0-1|0 | + Destination-Realm |0 |0 |0 |0 |0 |0 |1 |0 |1 |0 |1 |0 | + + + +Fajardo, et al. Expires July 24, 2011 [Page 137] + +Internet-Draft Diameter Base Protocol January 2011 + + + Disconnect-Cause |0 |0 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Error-Message |0 |0-1|0 |0-1|0 |0-1|0 |0-1|0 |0-1|0 |0-1| + Error-Reporting-Host|0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1| + Failed-AVP |0 |0+ |0 |0+ |0 |0+ |0 |0+ |0 |0+ |0 |0+ | + Firmware-Revision |0-1|0-1|0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Host-IP-Address |1+ |1+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Inband-Security-Id |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Multi-Round-Time-Out|0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Origin-Host |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 | + Origin-Realm |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 | + Origin-State-Id |0-1|0-1|0 |0 |0-1|0-1|0-1|0-1|0-1|0-1|0-1|0-1| + Product-Name |1 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Proxy-Info |0 |0 |0 |0 |0 |0 |0+ |0+ |0+ |0+ |0+ |0+ | + Redirect-Host |0 |0 |0 |0 |0 |0 |0 |0+ |0 |0+ |0 |0+ | + Redirect-Host-Usage |0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1| + Redirect-Max-Cache- |0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1| + Time | | | | | | | | | | | | | + Result-Code |0 |1 |0 |1 |0 |1 |0 |1 |0 |1 |0 |1 | + Re-Auth-Request-Type|0 |0 |0 |0 |0 |0 |1 |0 |0 |0 |0 |0 | + Route-Record |0 |0 |0 |0 |0 |0 |0+ |0 |0+ |0 |0+ |0 | + Session-Binding |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Session-Id |0 |0 |0 |0 |0 |0 |1 |1 |1 |1 |1 |1 | + Session-Server- |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Failover | | | | | | | | | | | | | + Session-Timeout |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Supported-Vendor-Id |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Termination-Cause |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |1 |0 | + User-Name |0 |0 |0 |0 |0 |0 |0-1|0-1|0-1|0-1|0-1|0-1| + Vendor-Id |1 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Vendor-Specific- |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Application-Id | | | | | | | | | | | | | + --------------------+---+---+---+---+---+---+---+---+---+---+---+---+ + +10.2. Accounting AVP Table + + The table in this section is used to represent which AVPs defined in + this document are to be present in the Accounting messages. These + AVP occurrence requirements are guidelines, which may be expanded, + and/or overridden by application-specific requirements in the + Diameter applications documents. + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 138] + +Internet-Draft Diameter Base Protocol January 2011 + + + +-----------+ + | Command | + | Code | + +-----+-----+ + Attribute Name | ACR | ACA | + ------------------------------+-----+-----+ + Acct-Interim-Interval | 0-1 | 0-1 | + Acct-Multi-Session-Id | 0-1 | 0-1 | + Accounting-Record-Number | 1 | 1 | + Accounting-Record-Type | 1 | 1 | + Acct-Session-Id | 0-1 | 0-1 | + Accounting-Sub-Session-Id | 0-1 | 0-1 | + Accounting-Realtime-Required | 0-1 | 0-1 | + Acct-Application-Id | 0-1 | 0-1 | + Auth-Application-Id | 0 | 0 | + Class | 0+ | 0+ | + Destination-Host | 0-1 | 0 | + Destination-Realm | 1 | 0 | + Error-Reporting-Host | 0 | 0+ | + Event-Timestamp | 0-1 | 0-1 | + Origin-Host | 1 | 1 | + Origin-Realm | 1 | 1 | + Proxy-Info | 0+ | 0+ | + Route-Record | 0+ | 0 | + Result-Code | 0 | 1 | + Session-Id | 1 | 1 | + Termination-Cause | 0 | 0 | + User-Name | 0-1 | 0-1 | + Vendor-Specific-Application-Id| 0-1 | 0-1 | + ------------------------------+-----+-----+ + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 139] + +Internet-Draft Diameter Base Protocol January 2011 + + +11. IANA Considerations + + This section provides guidance to the Internet Assigned Numbers + Authority (IANA) regarding registration of values related to the + Diameter protocol, in accordance with BCP 26 [RFC5226]. The policies + and procedures for the IANA put in place by [RFC3588] applies here. + The criteria used by the IANA for assignment of numbers within this + namespace remains the same unless otherwise stated in this section. + Existing assignments remains the same unless explicitly updated or + deprecated in this secion. + +11.1. Changes to AVP Header Allocation + + For AVP Headers, the only change is the AVP code block allocations. + Block allocation (release of more than 3 at a time for a given + purpose) now only require IETF Review as opposed to an IETF + Consensus. + +11.2. Diameter Header + + For the Diameter Header, the command code namespace allocation has + changed. The new allocation rules are as follows: + + The command code values 256 - 8,388,607 (0x100 to 0x7fffff) are + for permanent, standard commands, allocated by IETF Review + [RFC5226]. + + The values 8,388,608 - 16,777,213 (0x800000 - 0xfffffd) are + reserved for vendor-specific command codes, to be allocated on a + First Come, First Served basis by IANA [RFC5226]. The request to + IANA for a Vendor-Specific Command Code SHOULD include a reference + to a publicly available specification which documents the command + in sufficient detail to aid in interoperability between + independent implementations. If the specification cannot be made + publicly available, the request for a vendor-specific command code + MUST include the contact information of persons and/or entities + responsible for authoring and maintaining the command. + +11.3. AVP Values + + For AVP values, the Experimental-Result-Code AVP value allocation has + been added. The new rule is as follows: + +11.3.1. Experimental-Result-Code AVP + + Values for this AVP are purely local to the indicated vendor, and no + IANA registry is maintained for them. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 140] + +Internet-Draft Diameter Base Protocol January 2011 + + +11.4. Diameter TCP, SCTP, TLS/TCP and DTLS/SCTP Port Numbers + + Updated port number assignments are described in this section. The + IANA has assigned port number 3868 for TCP and SCTP. The port number + [TBD] has been assigned for TLS/TCP and DTLS/SCTP. + +11.5. S-NAPTR Parameters + + This document registers a new S-NAPTR Application Service Tag value + of "aaa". + + This document also registers the following S-NAPTR Application + Protocol Tags: + + Tag | Protocol + -------------------|--------- + diameter.tcp | TCP + diameter.sctp | SCTP + diameter.tls.tcp | TLS/TCP + diameter.dtls.sctp | DTLS/SCTP + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 141] + +Internet-Draft Diameter Base Protocol January 2011 + + +12. Diameter protocol related configurable parameters + + This section contains the configurable parameters that are found + throughout this document: + + Diameter Peer + + A Diameter entity MAY communicate with peers that are statically + configured. A statically configured Diameter peer would require + that either the IP address or the fully qualified domain name + (FQDN) be supplied, which would then be used to resolve through + DNS. + + Routing Table + + A Diameter proxy server routes messages based on the realm portion + of a Network Access Identifier (NAI). The server MUST have a + table of Realm Names, and the address of the peer to which the + message must be forwarded to. The routing table MAY also include + a "default route", which is typically used for all messages that + cannot be locally processed. + + Tc timer + + The Tc timer controls the frequency that transport connection + attempts are done to a peer with whom no active transport + connection exists. The recommended value is 30 seconds. + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 142] + +Internet-Draft Diameter Base Protocol January 2011 + + +13. Security Considerations + + The Diameter base protocol messages SHOULD be secured by using TLS + [RFC5246] or DTLS/SCTP [RFC6083]. Additional security mechanisms + such as IPsec [RFC4301] MAY also be deployed to secure connections + between peers. However, all Diameter base protocol implementations + MUST support the use of TLS/TCP and DTLS/SCTP and the Diameter + protocol MUST NOT be used without any security mechanism. + + If a Diameter connection is to be protected via TLS/TCP and DTLS/SCTP + or IPsec, then TLS/TCP and DTLS/SCTP or IPsec/IKE SHOULD begin prior + to any Diameter message exchange. All security parameters for TLS/ + TCP and DTLS/SCTP or IPsec are configured independent of the Diameter + protocol. All Diameter message will be sent through the TLS/TCP and + DTLS/SCTP or IPsec connection after a successful setup. + + For TLS/TCP and DTLS/SCTP connections to be established in the open + state, the CER/CEA exchange MUST include an Inband-Security-ID AVP + with a value of TLS/TCP and DTLS/SCTP. The TLS/TCP and DTLS/SCTP + handshake will begin when both ends successfully reached the open + state, after completion of the CER/CEA exchange. If the TLS/TCP and + DTLS/SCTP handshake is successful, all further messages will be sent + via TLS/TCP and DTLS/SCTP. If the handshake fails, both ends move to + the closed state. See Sections 13.1 for more details. + +13.1. TLS/TCP and DTLS/SCTP Usage + + Diameter nodes using TLS/TCP and DTLS/SCTP for security MUST mutually + authenticate as part of TLS/TCP and DTLS/SCTP session establishment. + In order to ensure mutual authentication, the Diameter node acting as + TLS/TCP and DTLS/SCTP server MUST request a certificate from the + Diameter node acting as TLS/TCP and DTLS/SCTP client, and the + Diameter node acting as TLS/TCP and DTLS/SCTP client MUST be prepared + to supply a certificate on request. + + Diameter nodes MUST be able to negotiate the following TLS/TCP and + DTLS/SCTP cipher suites: + + TLS_RSA_WITH_RC4_128_MD5 + TLS_RSA_WITH_RC4_128_SHA + TLS_RSA_WITH_3DES_EDE_CBC_SHA + + Diameter nodes SHOULD be able to negotiate the following TLS/TCP and + DTLS/SCTP cipher suite: + + TLS_RSA_WITH_AES_128_CBC_SHA + + Diameter nodes MAY negotiate other TLS/TCP and DTLS/SCTP cipher + + + +Fajardo, et al. Expires July 24, 2011 [Page 143] + +Internet-Draft Diameter Base Protocol January 2011 + + + suites. + +13.2. Peer-to-Peer Considerations + + As with any peer-to-peer protocol, proper configuration of the trust + model within a Diameter peer is essential to security. When + certificates are used, it is necessary to configure the root + certificate authorities trusted by the Diameter peer. These root CAs + are likely to be unique to Diameter usage and distinct from the root + CAs that might be trusted for other purposes such as Web browsing. + In general, it is expected that those root CAs will be configured so + as to reflect the business relationships between the organization + hosting the Diameter peer and other organizations. As a result, a + Diameter peer will typically not be configured to allow connectivity + with any arbitrary peer. With certificate authentication, Diameter + peers may not be known beforehand and therefore peer discovery may be + required. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 144] + +Internet-Draft Diameter Base Protocol January 2011 + + +14. References + +14.1. Normative References + + [FLOATPOINT] + Institute of Electrical and Electronics Engineers, "IEEE + Standard for Binary Floating-Point Arithmetic, ANSI/IEEE + Standard 754-1985", August 1985. + + [IANAADFAM] + IANA,, "Address Family Numbers", + http://www.iana.org/assignments/address-family-numbers. + + [RADTYPE] IANA,, "RADIUS Types", + http://www.iana.org/assignments/radius-types. + + [RFC791] Postel, J., "Internet Protocol", RFC 791, September 1981. + + [RFC793] Postel, J., "Transmission Control Protocol", RFC 793, + January 1981. + + [RFC3539] Aboba, B. and J. Wood, "Authentication, Authorization and + Accounting (AAA) Transport Profile", RFC 3539, June 2003. + + [RFC4004] Calhoun, P., Johansson, T., Perkins, C., Hiller, T., and + P. McCann, "Diameter Mobile IPv4 Application", RFC 4004, + August 2005. + + [RFC4005] Calhoun, P., Zorn, G., Spence, D., and D. Mitton, + "Diameter Network Access Server Application", RFC 4005, + August 2005. + + [RFC4006] Hakala, H., Mattila, L., Koskinen, J-P., Stura, M., and J. + Loughney, "Diameter Credit-Control Application", RFC 4006, + August 2005. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC3588] Calhoun, P., Loughney, J., Guttman, E., Zorn, G., and J. + Arkko, "Diameter Base Protocol", RFC 3588, September 2003. + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing + Architecture", RFC 4291, February 2006. + + + +Fajardo, et al. Expires July 24, 2011 [Page 145] + +Internet-Draft Diameter Base Protocol January 2011 + + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC4282] Aboba, B., Beadles, M., Arkko, J., and P. Eronen, "The + Network Access Identifier", RFC 4282, December 2005. + + [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness + Requirements for Security", BCP 106, RFC 4086, June 2005. + + [RFC4960] Stewart, R., "Stream Control Transmission Protocol", + RFC 4960, September 2007. + + [RFC3958] Daigle, L. and A. Newton, "Domain-Based Application + Service Location Using SRV RRs and the Dynamic Delegation + Discovery Service (DDDS)", RFC 3958, January 2005. + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, August 2008. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC5890] Klensin, J., "Internationalized Domain Names for + Applications (IDNA): Definitions and Document Framework", + RFC 5890, August 2010. + + [RFC5891] Klensin, J., "Internationalized Domain Names in + Applications (IDNA): Protocol", RFC 5891, August 2010. + + [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode + for Internationalized Domain Names in Applications + (IDNA)", RFC 3492, March 2003. + + [RFC5729] Korhonen, J., Jones, M., Morand, L., and T. Tsou, + "Clarifications on the Routing of Diameter Requests Based + on the Username and the Realm", RFC 5729, December 2009. + + [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer + Security", RFC 4347, April 2006. + + [RFC6083] Tuexen, M., Seggelmann, R., and E. Rescorla, "Datagram + Transport Layer Security (DTLS) for Stream Control + Transmission Protocol (SCTP)", RFC 6083, January 2011. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 146] + +Internet-Draft Diameter Base Protocol January 2011 + + +14.2. Informational References + + [RFC2989] Aboba, B., Calhoun, P., Glass, S., Hiller, T., McCann, P., + Shiino, H., Walsh, P., Zorn, G., Dommety, G., Perkins, C., + Patil, B., Mitton, D., Manning, S., Beadles, M., Chen, X., + Sivalingham, S., Hameed, A., Munson, M., Jacobs, S., Lim, + B., Hirschman, B., Hsu, R., Koo, H., Lipford, M., + Campbell, E., Xu, Y., Baba, S., and E. Jaques, "Criteria + for Evaluating AAA Protocols for Network Access", + RFC 2989, November 2000. + + [RFC2975] Aboba, B., Arkko, J., and D. Harrington, "Introduction to + Accounting Management", RFC 2975, October 2000. + + [RFC3232] Reynolds, J., "Assigned Numbers: RFC 1700 is Replaced by + an On-line Database", RFC 3232, January 2002. + + [RFC5176] Chiba, M., Dommety, G., Eklund, M., Mitton, D., and B. + Aboba, "Dynamic Authorization Extensions to Remote + Authentication Dial In User Service (RADIUS)", RFC 5176, + January 2008. + + [RFC1661] Simpson, W., "The Point-to-Point Protocol (PPP)", STD 51, + RFC 1661, July 1994. + + [RFC2866] Rigney, C., "RADIUS Accounting", RFC 2866, June 2000. + + [RFC2869] Rigney, C., Willats, W., and P. Calhoun, "RADIUS + Extensions", RFC 2869, June 2000. + + [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, + "Remote Authentication Dial In User Service (RADIUS)", + RFC 2865, June 2000. + + [RFC3162] Aboba, B., Zorn, G., and D. Mitton, "RADIUS and IPv6", + RFC 3162, August 2001. + + [RFC4301] Kent, S. and K. Seo, "Security Architecture for the + Internet Protocol", RFC 4301, December 2005. + + [RFC5905] Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network + Time Protocol Version 4: Protocol and Algorithms + Specification", RFC 5905, June 2010. + + [RFC1492] Finseth, C., "An Access Control Protocol, Sometimes Called + TACACS", RFC 1492, July 1993. + + [RFC4690] Klensin, J., Faltstrom, P., Karp, C., and IAB, "Review and + + + +Fajardo, et al. Expires July 24, 2011 [Page 147] + +Internet-Draft Diameter Base Protocol January 2011 + + + Recommendations for Internationalized Domain Names + (IDNs)", RFC 4690, September 2006. + + [RFC5461] Gont, F., "TCP's Reaction to Soft Errors", RFC 5461, + February 2009. + + [RFC5927] Gont, F., "ICMP Attacks against TCP", RFC 5927, July 2010. + + [RFC3692] Narten, T., "Assigning Experimental and Testing Numbers + Considered Useful", BCP 82, RFC 3692, January 2004. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 148] + +Internet-Draft Diameter Base Protocol January 2011 + + +Appendix A. Acknowledgements + +A.1. RFC3588bis + + The authors would like to thank the following people that have + provided proposals and contributions to this document: + + To Vishnu Ram and Satendra Gera for their contributions on + Capabilities Updates, Predictive Loop Avoidance as well as many other + technical proposals. To Tolga Asveren for his insights and + contributions on almost all of the proposed solutions incorporated + into this document. To Timothy Smith for helping on the Capabilities + Updates and other topics. To Tony Zhang for providing fixes to loop + holes on composing Failed-AVPs as well as many other issues and + topics. To Jan Nordqvist for clearly stating the usage of + Application Ids. To Anders Kristensen for providing needed technical + opinions. To David Frascone for providing invaluable review of the + document. To Mark Jones for providing clarifying text on vendor + command codes and other vendor specific indicators. + + Special thanks to the Diameter extensibility design team which helped + resolve the tricky question of mandatory AVPs and ABNF semantics. + The members of this team are as follows: + + Avi Lior, Jari Arkko, Glen Zorn, Lionel Morand, Mark Jones, Tolga + Asveren Jouni Korhonen, Glenn McGregor. + + Special thanks also to people who have provided invaluable comments + and inputs especially in resolving controversial issues: + + Glen Zorn, Yoshihiro Ohba, Marco Stura, and Pasi Eronen. + + Finally, we would like to thank the original authors of this + document: + + Pat Calhoun, John Loughney, Jari Arkko, Erik Guttman and Glen Zorn. + + Their invaluable knowledge and experience has given us a robust and + flexible AAA protocol that many people have seen great value in + adopting. We greatly appreciate their support and stewardship for + the continued improvements of Diameter as a protocol. We would also + like to extend our gratitude to folks aside from the authors who have + assisted and contributed to the original version of this document. + Their efforts significantly contributed to the success of Diameter. + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 149] + +Internet-Draft Diameter Base Protocol January 2011 + + +A.2. RFC3588 + + The authors would like to thank Nenad Trifunovic, Tony Johansson and + Pankaj Patel for their participation in the pre-IETF Document Reading + Party. Allison Mankin, Jonathan Wood and Bernard Aboba provided + invaluable assistance in working out transport issues, and similarly + with Steven Bellovin in the security area. + + Paul Funk and David Mitton were instrumental in getting the Peer + State Machine correct, and our deep thanks go to them for their time. + + Text in this document was also provided by Paul Funk, Mark Eklund, + Mark Jones and Dave Spence. Jacques Caron provided many great + comments as a result of a thorough review of the spec. + + The authors would also like to acknowledge the following people for + their contribution in the development of the Diameter protocol: + + Allan C. Rubens, Haseeb Akhtar, William Bulley, Stephen Farrell, + David Frascone, Daniel C. Fox, Lol Grant, Ignacio Goyret, Nancy + Greene, Peter Heitman, Fredrik Johansson, Mark Jones, Martin Julien, + Bob Kopacz, Paul Krumviede, Fergal Ladley, Ryan Moats, Victor Muslin, + Kenneth Peirce, John Schnizlein, Sumit Vakil, John R. Vollbrecht and + Jeff Weisberg. + + Finally, Pat Calhoun would like to thank Sun Microsystems since most + of the effort put into this document was done while he was in their + employ. + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 150] + +Internet-Draft Diameter Base Protocol January 2011 + + +Appendix B. S-NAPTR Example + + As an example, consider a client that wishes to resolve aaa: + example1.com. The client performs a NAPTR query for that domain, and + the following NAPTR records are returned: + + ;; order pref flags service regexp replacement + IN NAPTR 50 50 "s" "aaa:diameter.tls.tcp" "" + _diameter._tls.example1.com + IN NAPTR 100 50 "s" "aaa:diameter.tcp" "" + _aaa._tcp.example1.com + IN NAPTR 150 50 "s" "aaa:diameter.sctp" "" + _diameter._sctp.example1.com + + This indicates that the server supports TLS, TCP and SCTP in that + order. If the client supports TLS, TLS will be used, targeted to a + host determined by an SRV lookup of _diameter._tls.example1.com. + That lookup would return: + + ;; Priority Weight Port Target + IN SRV 0 1 5060 server1.example1.com + IN SRV 0 2 5060 server2.example1.com + + As an alternative example, a client that wishes to resolve aaa: + example2.com. The client performs a NAPTR query for that domain, and + the following NAPTR records are returned: + + ;; order pref flags service regexp replacement + IN NAPTR 150 50 "a" "aaa:diameter.tls.tcp" "" + server1.example2.com + IN NAPTR 150 50 "a" "aaa:diameter.tls.tcp" "" + server2.example2.com + + This indicates that the server supports TCP available at the returned + host names. + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 151] + +Internet-Draft Diameter Base Protocol January 2011 + + +Appendix C. Duplicate Detection + + As described in Section 9.4, accounting record duplicate detection is + based on session identifiers. Duplicates can appear for various + reasons: + + o Failover to an alternate server. Where close to real-time + performance is required, failover thresholds need to be kept low + and this may lead to an increased likelihood of duplicates. + Failover can occur at the client or within Diameter agents. + + o Failure of a client or agent after sending of a record from non- + volatile memory, but prior to receipt of an application layer ACK + and deletion of the record. record to be sent. This will result + in retransmission of the record soon after the client or agent has + rebooted. + + o Duplicates received from RADIUS gateways. Since the + retransmission behavior of RADIUS is not defined within [RFC2865], + the likelihood of duplication will vary according to the + implementation. + + o Implementation problems and misconfiguration. + + The T flag is used as an indication of an application layer + retransmission event, e.g., due to failover to an alternate server. + It is defined only for request messages sent by Diameter clients or + agents. For instance, after a reboot, a client may not know whether + it has already tried to send the accounting records in its non- + volatile memory before the reboot occurred. Diameter servers MAY use + the T flag as an aid when processing requests and detecting duplicate + messages. However, servers that do this MUST ensure that duplicates + are found even when the first transmitted request arrives at the + server after the retransmitted request. It can be used only in cases + where no answer has been received from the Server for a request and + the request is sent again, (e.g., due to a failover to an alternate + peer, due to a recovered primary peer or due to a client re-sending a + stored record from non-volatile memory such as after reboot of a + client or agent). + + In some cases the Diameter accounting server can delay the duplicate + detection and accounting record processing until a post-processing + phase takes place. At that time records are likely to be sorted + according to the included User-Name and duplicate elimination is easy + in this case. In other situations it may be necessary to perform + real-time duplicate detection, such as when credit limits are imposed + or real-time fraud detection is desired. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 152] + +Internet-Draft Diameter Base Protocol January 2011 + + + In general, only generation of duplicates due to failover or re- + sending of records in non-volatile storage can be reliably detected + by Diameter clients or agents. In such cases the Diameter client or + agents can mark the message as possible duplicate by setting the T + flag. Since the Diameter server is responsible for duplicate + detection, it can choose to make use of the T flag or not, in order + to optimize duplicate detection. Since the T flag does not affect + interoperability, and may not be needed by some servers, generation + of the T flag is REQUIRED for Diameter clients and agents, but MAY be + implemented by Diameter servers. + + As an example, it can be usually be assumed that duplicates appear + within a time window of longest recorded network partition or device + fault, perhaps a day. So only records within this time window need + to be looked at in the backward direction. Secondly, hashing + techniques or other schemes, such as the use of the T flag in the + received messages, may be used to eliminate the need to do a full + search even in this set except for rare cases. + + The following is an example of how the T flag may be used by the + server to detect duplicate requests. + + + A Diameter server MAY check the T flag of the received message to + determine if the record is a possible duplicate. If the T flag is + set in the request message, the server searches for a duplicate + within a configurable duplication time window backward and + forward. This limits database searching to those records where + the T flag is set. In a well run network, network partitions and + device faults will presumably be rare events, so this approach + represents a substantial optimization of the duplicate detection + process. During failover, it is possible for the original record + to be received after the T flag marked record, due to differences + in network delays experienced along the path by the original and + duplicate transmissions. The likelihood of this occurring + increases as the failover interval is decreased. In order to be + able to detect out of order duplicates, the Diameter server should + use backward and forward time windows when performing duplicate + checking for the T flag marked request. For example, in order to + allow time for the original record to exit the network and be + recorded by the accounting server, the Diameter server can delay + processing records with the T flag set until a time period + TIME_WAIT + RECORD_PROCESSING_TIME has elapsed after the closing + of the original transport connection. After this time period has + expired, then it may check the T flag marked records against the + database with relative assurance that the original records, if + sent, have been received and recorded. + + + + +Fajardo, et al. Expires July 24, 2011 [Page 153] + +Internet-Draft Diameter Base Protocol January 2011 + + +Appendix D. Internationalized Domain Names + + To be compatible with the existing DNS infrastructure and simplify + host and domain name comparison, Diameter identities (FQDNs) are + represented in ASCII form. This allows the Diameter protocol to fall + in-line with the DNS strategy of being transparent from the effects + of Internationalized Domain Names (IDNs) by following the + recommendations in [RFC4690] and [RFC5890]. Applications that + provide support for IDNs outside of the Diameter protocol but + interacting with it SHOULD use the representation and conversion + framework described in [RFC5890], [RFC5891] and [RFC3492]. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 154] + +Internet-Draft Diameter Base Protocol January 2011 + + +Authors' Addresses + + Victor Fajardo (editor) + Telcordia Technologies + One Telcordia Drive, 1S-222 + Piscataway, NJ 08854 + USA + + Phone: +1-908-421-1845 + Email: [email protected] + + + Jari Arkko + Ericsson Research + 02420 Jorvas + Finland + + Phone: +358 40 5079256 + Email: [email protected] + + + John Loughney + Nokia Research Center + 955 Page Mill Road + Palo Alto, CA 94304 + US + + Phone: +1-650-283-8068 + Email: [email protected] + + + Glenn Zorn + Network Zen + 1310 East Thomas Street + Seattle, WA 98102 + US + + Phone: + Email: [email protected] + + + + + + + + + + + + +Fajardo, et al. Expires July 24, 2011 [Page 155] + + diff --git a/lib/diameter/doc/standard/rfc3124.txt b/lib/diameter/doc/standard/rfc3124.txt new file mode 100644 index 0000000000..db57bc370f --- /dev/null +++ b/lib/diameter/doc/standard/rfc3124.txt @@ -0,0 +1,1235 @@ + + + + + + +Network Working Group H. Balakrishnan +Request for Comments: 3124 MIT LCS +Category: Standards Track S. Seshan + CMU + June 2001 + + + The Congestion Manager + + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2001). All Rights Reserved. + +Abstract + + This document describes the Congestion Manager (CM), an end-system + module that: + + (i) Enables an ensemble of multiple concurrent streams from a sender + destined to the same receiver and sharing the same congestion + properties to perform proper congestion avoidance and control, and + + (ii) Allows applications to easily adapt to network congestion. + +1. Conventions used in this document: + + 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 RFC-2119 [Bradner97]. + + STREAM + + A group of packets that all share the same source and destination + IP address, IP type-of-service, transport protocol, and source and + destination transport-layer port numbers. + + + + + + + +Balakrishnan, et. al. Standards Track [Page 1] + +RFC 3124 The Congestion Manager June 2001 + + + MACROFLOW + + A group of CM-enabled streams that all use the same congestion + management and scheduling algorithms, and share congestion state + information. Currently, streams destined to different receivers + belong to different macroflows. Streams destined to the same + receiver MAY belong to different macroflows. When the Congestion + Manager is in use, streams that experience identical congestion + behavior and use the same congestion control algorithm SHOULD + belong to the same macroflow. + + APPLICATION + + Any software module that uses the CM. This includes user-level + applications such as Web servers or audio/video servers, as well + as in-kernel protocols such as TCP [Postel81] that use the CM for + congestion control. + + WELL-BEHAVED APPLICATION + + An application that only transmits when allowed by the CM and + accurately accounts for all data that it has sent to the receiver + by informing the CM using the CM API. + + PATH MAXIMUM TRANSMISSION UNIT (PMTU) + + The size of the largest packet that the sender can transmit + without it being fragmented en route to the receiver. It includes + the sizes of all headers and data except the IP header. + + CONGESTION WINDOW (cwnd) + + A CM state variable that modulates the amount of outstanding data + between sender and receiver. + + OUTSTANDING WINDOW (ownd) + + The number of bytes that has been transmitted by the source, but + not known to have been either received by the destination or lost + in the network. + + INITIAL WINDOW (IW) + + The size of the sender's congestion window at the beginning of a + macroflow. + + + + + + +Balakrishnan, et. al. Standards Track [Page 2] + +RFC 3124 The Congestion Manager June 2001 + + + DATA TYPE SYNTAX + + We use "u64" for unsigned 64-bit, "u32" for unsigned 32-bit, "u16" + for unsigned 16-bit, "u8" for unsigned 8-bit, "i32" for signed + 32-bit, "i16" for signed 16-bit quantities, "float" for IEEE + floating point values. The type "void" is used to indicate that + no return value is expected from a call. Pointers are referred to + using "*" syntax, following C language convention. + + We emphasize that all the API functions described in this document + are "abstract" calls and that conformant CM implementations may + differ in specific implementation details. + +2. Introduction + + The framework described in this document integrates congestion + management across all applications and transport protocols. The CM + maintains congestion parameters (available aggregate and per-stream + bandwidth, per-receiver round-trip times, etc.) and exports an API + that enables applications to learn about network characteristics, + pass information to the CM, share congestion information with each + other, and schedule data transmissions. This document focuses on + applications and transport protocols with their own independent per- + byte or per-packet sequence number information, and does not require + modifications to the receiver protocol stack. However, the receiving + application must provide feedback to the sending application about + received packets and losses, and the latter is expected to use the CM + API to update CM state. This document does not address networks with + reservations or service differentiation. + + The CM is an end-system module that enables an ensemble of multiple + concurrent streams to perform stable congestion avoidance and + control, and allows applications to easily adapt their transmissions + to prevailing network conditions. It integrates congestion + management across all applications and transport protocols. It + maintains congestion parameters (available aggregate and per-stream + bandwidth, per-receiver round-trip times, etc.) and exports an API + that enables applications to learn about network characteristics, + pass information to the CM, share congestion information with each + other, and schedule data transmissions. When the CM is used, all + data transmissions subject to the CM must be done with the explicit + consent of the CM via this API to ensure proper congestion behavior. + + Systems MAY choose to use CM, and if so they MUST follow this + specification. + + This document focuses on applications and networks where the + following conditions hold: + + + +Balakrishnan, et. al. Standards Track [Page 3] + +RFC 3124 The Congestion Manager June 2001 + + + 1. Applications are well-behaved with their own independent + per-byte or per-packet sequence number information, and use the + CM API to update internal state in the CM. + + 2. Networks are best-effort without service discrimination or + reservations. In particular, it does not address situations + where different streams between the same pair of hosts traverse + paths with differing characteristics. + + The Congestion Manager framework can be extended to support + applications that do not provide their own feedback and to + differentially-served networks. These extensions will be addressed + in later documents. + + The CM is motivated by two main goals: + + (i) Enable efficient multiplexing. Increasingly, the trend on the + Internet is for unicast data senders (e.g., Web servers) to transmit + heterogeneous types of data to receivers, ranging from unreliable + real-time streaming content to reliable Web pages and applets. As a + result, many logically different streams share the same path between + sender and receiver. For the Internet to remain stable, each of + these streams must incorporate control protocols that safely probe + for spare bandwidth and react to congestion. Unfortunately, these + concurrent streams typically compete with each other for network + resources, rather than share them effectively. Furthermore, they do + not learn from each other about the state of the network. Even if + they each independently implement congestion control (e.g., a group + of TCP connections each implementing the algorithms in [Jacobson88, + Allman99]), the ensemble of streams tends to be more aggressive in + the face of congestion than a single TCP connection implementing + standard TCP congestion control and avoidance [Balakrishnan98]. + + (ii) Enable application adaptation to congestion. Increasingly, + popular real-time streaming applications run over UDP using their own + user-level transport protocols for good application performance, but + in most cases today do not adapt or react properly to network + congestion. By implementing a stable control algorithm and exposing + an adaptation API, the CM enables easy application adaptation to + congestion. Applications adapt the data they transmit to the current + network conditions. + + The CM framework builds on recent work on TCP control block sharing + [Touch97], integrated TCP congestion control (TCP-Int) + [Balakrishnan98] and TCP sessions [Padmanabhan98]. [Touch97] + advocates the sharing of some of the state in the TCP control block + to improve transient transport performance and describes sharing + across an ensemble of TCP connections. [Balakrishnan98], + + + +Balakrishnan, et. al. Standards Track [Page 4] + +RFC 3124 The Congestion Manager June 2001 + + + [Padmanabhan98], and [Eggert00] describe several experiments that + quantify the benefits of sharing congestion state, including improved + stability in the face of congestion and better loss recovery. + Integrating loss recovery across concurrent connections significantly + improves performance because losses on one connection can be detected + by noticing that later data sent on another connection has been + received and acknowledged. The CM framework extends these ideas in + two significant ways: (i) it extends congestion management to non-TCP + streams, which are becoming increasingly common and often do not + implement proper congestion management, and (ii) it provides an API + for applications to adapt their transmissions to current network + conditions. For an extended discussion of the motivation for the CM, + its architecture, API, and algorithms, see [Balakrishnan99]; for a + description of an implementation and performance results, see + [Andersen00]. + + The resulting end-host protocol architecture at the sender is shown + in Figure 1. The CM helps achieve network stability by implementing + stable congestion avoidance and control algorithms that are "TCP- + friendly" [Mahdavi98] based on algorithms described in [Allman99]. + However, it does not attempt to enforce proper congestion behavior + for all applications (but it does not preclude a policer on the host + that performs this task). Note that while the policer at the end- + host can use CM, the network has to be protected against compromises + to the CM and the policer at the end hosts, a task that requires + router machinery [Floyd99a]. We do not address this issue further in + this document. + + + + + + + + + + + + + + + + + + + + + + + + +Balakrishnan, et. al. Standards Track [Page 5] + +RFC 3124 The Congestion Manager June 2001 + + + |--------| |--------| |--------| |--------| |--------------| + | HTTP | | FTP | | RTP 1 | | RTP 2 | | | + |--------| |--------| |--------| |--------| | | + | | | ^ | ^ | | + | | | | | | | Scheduler | + | | | | | | |---| | | + | | | |-------|--+->| | | | + | | | | | |<--| | + v v v v | | |--------------| + |--------| |--------| |-------------| | | ^ + | TCP 1 | | TCP 2 | | UDP 1 | | A | | + |--------| |--------| |-------------| | | | + ^ | ^ | | | | |--------------| + | | | | | | P |-->| | + | | | | | | | | | + |---|------+---|--------------|------->| | | Congestion | + | | | | I | | | + v v v | | | Controller | + |-----------------------------------| | | | | + | IP |-->| | | | + |-----------------------------------| | | |--------------| + |---| + + Figure 1 + + The key components of the CM framework are (i) the API, (ii) the + congestion controller, and (iii) the scheduler. The API is (in part) + motivated by the requirements of application-level framing (ALF) + [Clark90], and is described in Section 4. The CM internals (Section + 5) include a congestion controller (Section 5.1) and a scheduler to + orchestrate data transmissions between concurrent streams in a + macroflow (Section 5.2). The congestion controller adjusts the + aggregate transmission rate between sender and receiver based on its + estimate of congestion in the network. It obtains feedback about its + past transmissions from applications themselves via the API. The + scheduler apportions available bandwidth amongst the different + streams within each macroflow and notifies applications when they are + permitted to send data. This document focuses on well-behaved + applications; a future one will describe the sender-receiver protocol + and header formats that will handle applications that do not + incorporate their own feedback to the CM. + +3. CM API + + By convention, the IETF does not treat Application Programming + Interfaces as standards track. However, it is considered important + to have the CM API and CM algorithm requirements in one coherent + document. The following section on the CM API uses the terms MUST, + + + +Balakrishnan, et. al. Standards Track [Page 6] + +RFC 3124 The Congestion Manager June 2001 + + + SHOULD, etc., but the terms are meant to apply within the context of + an implementation of the CM API. The section does not apply to + congestion control implementations in general, only to those + implementations offering the CM API. + + Using the CM API, streams can determine their share of the available + bandwidth, request and have their data transmissions scheduled, + inform the CM about successful transmissions, and be informed when + the CM's estimate of path bandwidth changes. Thus, the CM frees + applications from having to maintain information about the state of + congestion and available bandwidth along any path. + + The function prototypes below follow standard C language convention. + We emphasize that these API functions are abstract calls and + conformant CM implementations may differ in specific details, as long + as equivalent functionality is provided. + + When a new stream is created by an application, it passes some + information to the CM via the cm_open(stream_info) API call. + Currently, stream_info consists of the following information: (i) the + source IP address, (ii) the source port, (iii) the destination IP + address, (iv) the destination port, and (v) the IP protocol number. + +3.1 State maintenance + + 1. Open: All applications MUST call cm_open(stream_info) before + using the CM API. This returns a handle, cm_streamid, for the + application to use for all further CM API invocations for that + stream. If the returned cm_streamid is -1, then the cm_open() + failed and that stream cannot use the CM. + + All other calls to the CM for a stream use the cm_streamid + returned from the cm_open() call. + + 2. Close: When a stream terminates, the application SHOULD invoke + cm_close(cm_streamid) to inform the CM about the termination + of the stream. + + 3. Packet size: cm_mtu(cm_streamid) returns the estimated PMTU of + the path between sender and receiver. Internally, this + information SHOULD be obtained via path MTU discovery + [Mogul90]. It MAY be statically configured in the absence of + such a mechanism. + + + + + + + + +Balakrishnan, et. al. Standards Track [Page 7] + +RFC 3124 The Congestion Manager June 2001 + + +3.2 Data transmission + + The CM accommodates two types of adaptive senders, enabling + applications to dynamically adapt their content based on prevailing + network conditions, and supporting ALF-based applications. + + 1. Callback-based transmission. The callback-based transmission API + puts the stream in firm control of deciding what to transmit at each + point in time. To achieve this, the CM does not buffer any data; + instead, it allows streams the opportunity to adapt to unexpected + network changes at the last possible instant. Thus, this enables + streams to "pull out" and repacketize data upon learning about any + rate change, which is hard to do once the data has been buffered. + The CM must implement a cm_request(i32 cm_streamid) call for streams + wishing to send data in this style. After some time, depending on + the rate, the CM MUST invoke a callback using cmapp_send(), which is + a grant for the stream to send up to PMTU bytes. The callback-style + API is the recommended choice for ALF-based streams. Note that + cm_request() does not take the number of bytes or MTU-sized units as + an argument; each call to cm_request() is an implicit request for + sending up to PMTU bytes. The CM MAY provide an alternate interface, + cm_request(int k). The cmapp_send callback for this request is + granted the right to send up to k PMTU sized segments. Section 4.3 + discusses the time duration for which the transmission grant is + valid, while Section 5.2 describes how these requests are scheduled + and callbacks made. + + 2. Synchronous-style. The above callback-based API accommodates a + class of ALF streams that are "asynchronous." Asynchronous + transmitters do not transmit based on a periodic clock, but do so + triggered by asynchronous events like file reads or captured frames. + On the other hand, there are many streams that are "synchronous" + transmitters, which transmit periodically based on their own internal + timers (e.g., an audio senders that sends at a constant sampling + rate). While CM callbacks could be configured to periodically + interrupt such transmitters, the transmit loop of such applications + is less affected if they retain their original timer-based loop. In + addition, it complicates the CM API to have a stream express the + periodicity and granularity of its callbacks. Thus, the CM MUST + export an API that allows such streams to be informed of changes in + rates using the cmapp_update(u64 newrate, u32 srtt, u32 rttdev) + callback function, where newrate is the new rate in bits per second + for this stream, srtt is the current smoothed round trip time + estimate in microseconds, and rttdev is the smoothed linear deviation + in the round-trip time estimate calculated using the same algorithm + as in TCP [Paxson00]. The newrate value reports an instantaneous + rate calculated, for example, by taking the ratio of cwnd and srtt, + and dividing by the fraction of that ratio allocated to the stream. + + + +Balakrishnan, et. al. Standards Track [Page 8] + +RFC 3124 The Congestion Manager June 2001 + + + In response, the stream MUST adapt its packet size or change its + timer interval to conform to (i.e., not exceed) the allowed rate. Of + course, it may choose not to use all of this rate. Note that the CM + is not on the data path of the actual transmission. + + To avoid unnecessary cmapp_update() callbacks that the application + will only ignore, the CM MUST provide a cm_thresh(float + rate_downthresh, float rate_upthresh, float rtt_downthresh, float + rtt_upthresh) function that a stream can use at any stage in its + execution. In response, the CM SHOULD invoke the callback only when + the rate decreases to less than (rate_downthresh * lastrate) or + increases to more than (rate_upthresh * lastrate), where lastrate is + the rate last notified to the stream, or when the round-trip time + changes correspondingly by the requisite thresholds. This + information is used as a hint by the CM, in the sense the + cmapp_update() can be called even if these conditions are not met. + + The CM MUST implement a cm_query(i32 cm_streamid, u64* rate, u32* + srtt, u32* rttdev) to allow an application to query the current CM + state. This sets the rate variable to the current rate estimate in + bits per second, the srtt variable to the current smoothed round-trip + time estimate in microseconds, and rttdev to the mean linear + deviation. If the CM does not have valid estimates for the + macroflow, it fills in negative values for the rate, srtt, and + rttdev. + + Note that a stream can use more than one of the above transmission + APIs at the same time. In particular, the knowledge of sustainable + rate is useful for asynchronous streams as well as synchronous ones; + e.g., an asynchronous Web server disseminating images using TCP may + use cmapp_send() to schedule its transmissions and cmapp_update() to + decide whether to send a low-resolution or high-resolution image. A + TCP implementation using the CM is described in Section 6.1.1, where + the benefit of the cm_request() callback API for TCP will become + apparent. + + The reader will notice that the basic CM API does not provide an + interface for buffered congestion-controlled transmissions. This is + intentional, since this transmission mode can be implemented using + the callback-based primitive. Section 6.1.2 describes how + congestion-controlled UDP sockets may be implemented using the CM + API. + +3.3 Application notification + + When a stream receives feedback from receivers, it MUST use + cm_update(i32 cm_streamid, u32 nrecd, u32 nlost, u8 lossmode, i32 + rtt) to inform the CM about events such as congestion losses, + + + +Balakrishnan, et. al. Standards Track [Page 9] + +RFC 3124 The Congestion Manager June 2001 + + + successful receptions, type of loss (timeout event, Explicit + Congestion Notification [Ramakrishnan99], etc.) and round-trip time + samples. The nrecd parameter indicates how many bytes were + successfully received by the receiver since the last cm_update call, + while the nrecd parameter identifies how many bytes were received + were lost during the same time period. The rtt value indicates the + round-trip time measured during the transmission of these bytes. The + rtt value must be set to -1 if no valid round-trip sample was + obtained by the application. The lossmode parameter provides an + indicator of how a loss was detected. A value of CM_NO_FEEDBACK + indicates that the application has received no feedback for all its + outstanding data, and is reporting this to the CM. For example, a + TCP that has experienced a timeout would use this parameter to inform + the CM of this. A value of CM_LOSS_FEEDBACK indicates that the + application has experienced some loss, which it believes to be due to + congestion, but not all outstanding data has been lost. For example, + a TCP segment loss detected using duplicate (selective) + acknowledgments or other data-driven techniques fits this category. + A value of CM_EXPLICIT_CONGESTION indicates that the receiver echoed + an explicit congestion notification message. Finally, a value of + CM_NO_CONGESTION indicates that no congestion-related loss has + occurred. The lossmode parameter MUST be reported as a bit-vector + where the bits correspond to CM_NO_FEEDBACK, CM_LOSS_FEEDBACK, + CM_EXPLICIT_CONGESTION, and CM_NO_CONGESTION. Note that over links + (paths) that experience losses for reasons other than congestion, an + application SHOULD inform the CM of losses, with the CM_NO_CONGESTION + field set. + + cm_notify(i32 cm_streamid, u32 nsent) MUST be called when data is + transmitted from the host (e.g., in the IP output routine) to inform + the CM that nsent bytes were just transmitted on a given stream. + This allows the CM to update its estimate of the number of + outstanding bytes for the macroflow and for the stream. + + A cmapp_send() grant from the CM to an application is valid only for + an expiration time, equal to the larger of the round-trip time and an + implementation-dependent threshold communicated as an argument to the + cmapp_send() callback function. The application MUST NOT send data + based on this callback after this time has expired. Furthermore, if + the application decides not to send data after receiving this + callback, it SHOULD call cm_notify(stream_info, 0) to allow the CM to + permit other streams in the macroflow to transmit data. The CM + congestion controller MUST be robust to applications forgetting to + invoke cm_notify(stream_info, 0) correctly, or applications that + crash or disappear after having made a cm_request() call. + + + + + + +Balakrishnan, et. al. Standards Track [Page 10] + +RFC 3124 The Congestion Manager June 2001 + + +3.4 Querying + + If applications wish to learn about per-stream available bandwidth + and round-trip time, they can use the CM's cm_query(i32 cm_streamid, + i64* rate, i32* srtt, i32* rttdev) call, which fills in the desired + quantities. If the CM does not have valid estimates for the + macroflow, it fills in negative values for the rate, srtt, and + rttdev. + +3.5 Sharing granularity + + One of the decisions the CM needs to make is the granularity at which + a macroflow is constructed, by deciding which streams belong to the + same macroflow and share congestion information. The API provides + two functions that allow applications to decide which of their + streams ought to belong to the same macroflow. + + cm_getmacroflow(i32 cm_streamid) returns a unique i32 macroflow + identifier. cm_setmacroflow(i32 cm_macroflowid, i32 cm_streamid) + sets the macroflow of the stream cm_streamid to cm_macroflowid. If + the cm_macroflowid that is passed to cm_setmacroflow() is -1, then a + new macroflow is constructed and this is returned to the caller. + Each call to cm_setmacroflow() overrides the previous macroflow + association for the stream, should one exist. + + The default suggested aggregation method is to aggregate by + destination IP address; i.e., all streams to the same destination + address are aggregated to a single macroflow by default. The + cm_getmacroflow() and cm_setmacroflow() calls can then be used to + change this as needed. We do note that there are some cases where + this may not be optimal, even over best-effort networks. For + example, when a group of receivers are behind a NAT device, the + sender will see them all as one address. If the hosts behind the NAT + are in fact connected over different bottleneck links, some of those + hosts could see worse performance than before. It is possible to + detect such hosts when using delay and loss estimates, although the + specific mechanisms for doing so are beyond the scope of this + document. + + The objective of this interface is to set up sharing of groups not + sharing policy of relative weights of streams in a macroflow. The + latter requires the scheduler to provide an interface to set sharing + policy. However, because we want to support many different + schedulers (each of which may need different information to set + policy), we do not specify a complete API to the scheduler (but see + + + + + + +Balakrishnan, et. al. Standards Track [Page 11] + +RFC 3124 The Congestion Manager June 2001 + + + Section 5.2). A later guideline document is expected to describe a + few simple schedulers (e.g., weighted round-robin, hierarchical + scheduling) and the API they export to provide relative + prioritization. + +4. CM internals + + This section describes the internal components of the CM. It + includes a Congestion Controller and a Scheduler, with well-defined, + abstract interfaces exported by them. + +4.1 Congestion controller + + Associated with each macroflow is a congestion control algorithm; the + collection of all these algorithms comprises the congestion + controller of the CM. The control algorithm decides when and how + much data can be transmitted by a macroflow. It uses application + notifications (Section 4.3) from concurrent streams on the same + macroflow to build up information about the congestion state of the + network path used by the macroflow. + + The congestion controller MUST implement a "TCP-friendly" [Mahdavi98] + congestion control algorithm. Several macroflows MAY (and indeed, + often will) use the same congestion control algorithm but each + macroflow maintains state about the network used by its streams. + + The congestion control module MUST implement the following abstract + interfaces. We emphasize that these are not directly visible to + applications; they are within the context of a macroflow, and are + different from the CM API functions of Section 4. + + - void query(u64 *rate, u32 *srtt, u32 *rttdev): This function + returns the estimated rate (in bits per second) and smoothed + round trip time (in microseconds) for the macroflow. + + - void notify(u32 nsent): This function MUST be used to notify the + congestion control module whenever data is sent by an + application. The nsent parameter indicates the number of bytes + just sent by the application. + + - void update(u32 nsent, u32 nrecd, u32 rtt, u32 lossmode): This + function is called whenever any of the CM streams associated with + a macroflow identifies that data has reached the receiver or has + been lost en route. The nrecd parameter indicates the number of + bytes that have just arrived at the receiver. The nsent + parameter is the sum of the number of bytes just received and the + + + + + +Balakrishnan, et. al. Standards Track [Page 12] + +RFC 3124 The Congestion Manager June 2001 + + + number of bytes identified as lost en route. The rtt parameter is + the estimated round trip time in microseconds during the + transfer. The lossmode parameter provides an indicator of how a + loss was detected (section 4.3). + + Although these interfaces are not visible to applications, the + congestion controller MUST implement these abstract interfaces to + provide for modular inter-operability with different separately- + developed schedulers. + + The congestion control module MUST also call the associated + scheduler's schedule function (section 5.2) when it believes that the + current congestion state allows an MTU-sized packet to be sent. + +4.2 Scheduler + + While it is the responsibility of the congestion control module to + determine when and how much data can be transmitted, it is the + responsibility of a macroflow's scheduler module to determine which + of the streams should get the opportunity to transmit data. + + The Scheduler MUST implement the following interfaces: + + - void schedule(u32 num_bytes): When the congestion control module + determines that data can be sent, the schedule() routine MUST be + called with no more than the number of bytes that can be sent. + In turn, the scheduler MAY call the cmapp_send() function that CM + applications must provide. + + - float query_share(i32 cm_streamid): This call returns the + described stream's share of the total bandwidth available to the + macroflow. This call combined with the query call of the + congestion controller provides the information to satisfy an + application's cm_query() request. + + - void notify(i32 cm_streamid, u32 nsent): This interface is used + to notify the scheduler module whenever data is sent by a CM + application. The nsent parameter indicates the number of bytes + just sent by the application. + + The Scheduler MAY implement many additional interfaces. As + experience with CM schedulers increases, future documents may + make additions and/or changes to some parts of the scheduler + API. + + + + + + + +Balakrishnan, et. al. Standards Track [Page 13] + +RFC 3124 The Congestion Manager June 2001 + + +5. Examples + +5.1 Example applications + + This section describes three possible uses of the CM API by + applications. We describe two asynchronous applications---an + implementation of a TCP sender and an implementation of congestion- + controlled UDP sockets, and a synchronous application---a streaming + audio server. More details of these applications and CM + implementation optimizations for efficient operation are described in + [Andersen00]. + + All applications that use the CM MUST incorporate feedback from the + receiver. For example, it must periodically (typically once or twice + per round trip time) determine how many of its packets arrived at the + receiver. When the source gets this feedback, it MUST use + cm_update() to inform the CM of this new information. This results + in the CM updating ownd and may result in the CM changing its + estimates and calling cmapp_update() of the streams of the macroflow. + + The protocols in this section are examples and suggestions for + implementation, rather than requirements for any conformant + implementation. + +5.1.1 TCP + + A TCP implementation that uses CM should use the cmapp_send() + callback API. TCP only identifies which data it should send upon the + arrival of an acknowledgement or expiration of a timer. As a result, + it requires tight control over when and if new data or + retransmissions are sent. + + When TCP either connects to or accepts a connection from another + host, it performs a cm_open() call to associate the TCP connection + with a cm_streamid. + + Once a connection is established, the CM is used to control the + transmission of outgoing data. The CM eliminates the need for + tracking and reacting to congestion in TCP, because the CM and its + transmission API ensure proper congestion behavior. Loss recovery is + still performed by TCP based on fast retransmissions and recovery as + well as timeouts. In addition, TCP is also modified to have its own + outstanding window (tcp_ownd) estimate. Whenever data segments are + sent from its cmapp_send() callback, TCP updates its tcp_ownd value. + The ownd variable is also updated after each cm_update() call. TCP + also maintains a count of the number of outstanding segments + (pkt_cnt). At any time, TCP can calculate the average packet size + (avg_pkt_size) as tcp_ownd/pkt_cnt. The avg_pkt_size is used by TCP + + + +Balakrishnan, et. al. Standards Track [Page 14] + +RFC 3124 The Congestion Manager June 2001 + + + to help estimate the amount of outstanding data. Note that this is + not needed if the SACK option is used on the connection, since this + information is explicitly available. + + The TCP output routines are modified as follows: + + 1. All congestion window (cwnd) checks are removed. + + 2. When application data is available. The TCP output routines + perform all non-congestion checks (Nagle algorithm, receiver- + advertised window check, etc). If these checks pass, the output + routine queues the data and calls cm_request() for the stream. + + 3. If incoming data or timers result in a loss being detected, the + retransmission is also placed in a queue and cm_request() is + called for the stream. + + 4. The cmapp_send() callback for TCP is set to an output routine. + If any retransmission is enqueued, the routine outputs the + retransmission. Otherwise, the routine outputs as much new data + as the TCP connection state allows. However, the cmapp_send() + never sends more than a single segment per call. This routine + arranges for the other output computations to be done, such as + header and options computations. + + The IP output routine on the host calls cm_notify() when the packets + are actually sent out. Because it does not know which cm_streamid is + responsible for the packet, cm_notify() takes the stream_info as + argument (see Section 4 for what the stream_info should contain). + Because cm_notify() reports the IP payload size, TCP keeps track of + the total header size and incorporates these updates. + + The TCP input routines are modified as follows: + + 1. RTT estimation is done as normal using either timestamps or + Karn's algorithm. Any rtt estimate that is generated is passed to + CM via the cm_update call. + + 2. All cwnd and slow start threshold (ssthresh) updates are + removed. + + 3. Upon the arrival of an ack for new data, TCP computes the value + of in_flight (the amount of data in flight) as snd_max-ack-1 + (i.e., MAX Sequence Sent - Current Ack - 1). TCP then calls + cm_update(streamid, tcp_ownd - in_flight, 0, CM_NO_CONGESTION, + rtt). + + + + + +Balakrishnan, et. al. Standards Track [Page 15] + +RFC 3124 The Congestion Manager June 2001 + + + 4. Upon the arrival of a duplicate acknowledgement, TCP must check + its dupack count (dup_acks) to determine its action. If dup_acks + < 3, the TCP does nothing. If dup_acks == 3, TCP assumes that a + packet was lost and that at least 3 packets arrived to generate + these duplicate acks. Therefore, it calls cm_update(streamid, 4 * + avg_pkt_size, 3 * avg_pkt_size, CM_LOSS_FEEDBACK, rtt). The + average packet size is used since the acknowledgments do not + indicate exactly how much data has reached the other end. Most + TCP implementations interpret a duplicate ACK as an indication + that a full MSS has reached its destination. Once a new ACK is + received, these TCP sender implementations may resynchronize with + TCP receiver. The CM API does not provide a mechanism for TCP to + pass information from this resynchronization. Therefore, TCP can + only infer the arrival of an avg_pkt_size amount of data from each + duplicate ack. TCP also enqueues a retransmission of the lost + segment and calls cm_request(). If dup_acks > 3, TCP assumes that + a packet has reached the other end and caused this ack to be sent. + As a result, it calls cm_update(streamid, avg_pkt_size, + avg_pkt_size, CM_NO_CONGESTION, rtt). + + 5. Upon the arrival of a partial acknowledgment (one that does not + exceed the highest segment transmitted at the time the loss + occurred, as defined in [Floyd99b]), TCP assumes that a packet was + lost and that the retransmitted packet has reached the recipient. + Therefore, it calls cm_update(streamid, 2 * avg_pkt_size, + avg_pkt_size, CM_NO_CONGESTION, rtt). CM_NO_CONGESTION is used + since the loss period has already been reported. TCP also + enqueues a retransmission of the lost segment and calls + cm_request(). + + When the TCP retransmission timer expires, the sender identifies that + a segment has been lost and calls cm_update(streamid, avg_pkt_size, + 0, CM_NO_FEEDBACK, 0) to signify that no feedback has been received + from the receiver and that one segment is sure to have "left the + pipe." TCP also enqueues a retransmission of the lost segment and + calls cm_request(). + +5.1.2 Congestion-controlled UDP + + Congestion-controlled UDP is a useful CM application, which we + describe in the context of Berkeley sockets [Stevens94]. They + provide the same functionality as standard Berkeley UDP sockets, but + instead of immediately sending the data from the kernel packet queue + to lower layers for transmission, the buffered socket implementation + makes calls to the API exported by the CM inside the kernel and gets + callbacks from the CM. When a CM UDP socket is created, it is bound + to a particular stream. Later, when data is added to the packet + queue, cm_request() is called on the stream associated with the + + + +Balakrishnan, et. al. Standards Track [Page 16] + +RFC 3124 The Congestion Manager June 2001 + + + socket. When the CM schedules this stream for transmission, it calls + udp_ccappsend() in the UDP module. This function transmits one MTU + from the packet queue, and schedules the transmission of any + remaining packets. The in-kernel implementation of the CM UDP API + should not require any additional data copies and should support all + standard UDP options. Modifying existing applications to use + congestion-controlled UDP requires the implementation of a new socket + option on the socket. To work correctly, the sender must obtain + feedback about congestion. This can be done in at least two ways: + (i) the UDP receiver application can provide feedback to the sender + application, which will inform the CM of network conditions using + cm_update(); (ii) the UDP receiver implementation can provide + feedback to the sending UDP. Note that this latter alternative + requires changes to the receiver's network stack and the sender UDP + cannot assume that all receivers support this option without explicit + negotiation. + +5.1.3 Audio server + + A typical audio application often has access to the sample in a + multitude of data rates and qualities. The objective of the + application is then to deliver the highest possible quality of audio + (typically the highest data rate) its clients. The selection of + which version of audio to transmit should be based on the current + congestion state of the network. In addition, the source will want + audio delivered to its users at a consistent sampling rate. As a + result, it must send data a regular rate, minimizing delaying + transmissions and reducing buffering before playback. To meet these + requirements, this application can use the synchronous sender API + (Section 4.2). + + When the source first starts, it uses the cm_query() call to get an + initial estimate of network bandwidth and delay. If some other + streams on that macroflow have already been active, then it gets an + initial estimate that is valid; otherwise, it gets negative values, + which it ignores. It then chooses an encoding that does not exceed + these estimates (or, in the case of an invalid estimate, uses + application-specific initial values) and begins transmitting data. + The application also implements the cmapp_update() callback. When + the CM determines that network characteristics have changed, it calls + the application's cmapp_update() function and passes it a new rate + and round-trip time estimate. The application must change its choice + of audio encoding to ensure that it does not exceed these new + estimates. + + + + + + + +Balakrishnan, et. al. Standards Track [Page 17] + +RFC 3124 The Congestion Manager June 2001 + + +5.2 Example congestion control module + + To illustrate the responsibilities of a congestion control module, + the following describes some of the actions of a simple TCP-like + congestion control module that implements Additive Increase + Multiplicative Decrease congestion control (AIMD_CC): + + - query(): AIMD_CC returns the current congestion window (cwnd) + divided by the smoothed rtt (srtt) as its bandwidth estimate. It + returns the smoothed rtt estimate as srtt. + + - notify(): AIMD_CC adds the number of bytes sent to its + outstanding data window (ownd). + + - update(): AIMD_CC subtracts nsent from ownd. If the value of rtt + is non-zero, AIMD_CC updates srtt using the TCP srtt calculation. + If the update indicates that data has been lost, AIMD_CC sets + cwnd to 1 MTU if the loss_mode is CM_NO_FEEDBACK and to cwnd/2 + (with a minimum of 1 MTU) if the loss_mode is CM_LOSS_FEEDBACK or + CM_EXPLICIT_CONGESTION. AIMD_CC also sets its internal ssthresh + variable to cwnd/2. If no loss had occurred, AIMD_CC mimics TCP + slow start and linear growth modes. It increments cwnd by nsent + when cwnd < ssthresh (bounded by a maximum of ssthresh-cwnd) and + by nsent * MTU/cwnd when cwnd > ssthresh. + + - When cwnd or ownd are updated and indicate that at least one MTU + may be transmitted, AIMD_CC calls the CM to schedule a + transmission. + +5.3 Example Scheduler Module + + To clarify the responsibilities of a scheduler module, the following + describes some of the actions of a simple round robin scheduler + module (RR_sched): + + - schedule(): RR_sched schedules as many streams as possible in round + robin fashion. + + - query_share(): RR_sched returns 1/(number of streams in macroflow). + + - notify(): RR_sched does nothing. Round robin scheduling is not + affected by the amount of data sent. + +6. Security Considerations + + The CM provides many of the same services that the congestion control + in TCP provides. As such, it is vulnerable to many of the same + security problems. For example, incorrect reports of losses and + + + +Balakrishnan, et. al. Standards Track [Page 18] + +RFC 3124 The Congestion Manager June 2001 + + + transmissions will give the CM an inaccurate picture of the network's + congestion state. By giving CM a high estimate of congestion, an + attacker can degrade the performance observed by applications. For + example, a stream on a host can arbitrarily slow down any other + stream on the same macroflow, a form of denial of service. + + The more dangerous form of attack occurs when an application gives + the CM a low estimate of congestion. This would cause CM to be + overly aggressive and allow data to be sent much more quickly than + sound congestion control policies would allow. + + [Touch97] describes a number of the security problems that arise with + congestion information sharing. An additional vulnerability (not + covered by [Touch97])) occurs because applications have access + through the CM API to control shared state that will affect other + applications on the same computer. For instance, a poorly designed, + possibly a compromised, or intentionally malicious UDP application + could misuse cm_update() to cause starvation and/or too-aggressive + behavior of others in the macroflow. + +7. References + + [Allman99] Allman, M. and Paxson, V., "TCP Congestion + Control", RFC 2581, April 1999. + + [Andersen00] Balakrishnan, H., System Support for Bandwidth + Management and Content Adaptation in Internet + Applications, Proc. 4th Symp. on Operating Systems + Design and Implementation, San Diego, CA, October + 2000. Available from + http://nms.lcs.mit.edu/papers/cm-osdi2000.html + + [Balakrishnan98] Balakrishnan, H., Padmanabhan, V., Seshan, S., + Stemm, M., and Katz, R., "TCP Behavior of a Busy + Web Server: Analysis and Improvements," Proc. IEEE + INFOCOM, San Francisco, CA, March 1998. + + [Balakrishnan99] Balakrishnan, H., Rahul, H., and Seshan, S., "An + Integrated Congestion Management Architecture for + Internet Hosts," Proc. ACM SIGCOMM, Cambridge, MA, + September 1999. + + [Bradner96] Bradner, S., "The Internet Standards Process --- + Revision 3", BCP 9, RFC 2026, October 1996. + + [Bradner97] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + + + +Balakrishnan, et. al. Standards Track [Page 19] + +RFC 3124 The Congestion Manager June 2001 + + + [Clark90] Clark, D. and Tennenhouse, D., "Architectural + Consideration for a New Generation of Protocols", + Proc. ACM SIGCOMM, Philadelphia, PA, September + 1990. + + [Eggert00] Eggert, L., Heidemann, J., and Touch, J., "Effects + of Ensemble TCP," ACM Computer Comm. Review, + January 2000. + + [Floyd99a] Floyd, S. and Fall, K.," Promoting the Use of End- + to-End Congestion Control in the Internet," + IEEE/ACM Trans. on Networking, 7(4), August 1999, + pp. 458-472. + + [Floyd99b] Floyd, S. and T. Henderson,"The New Reno + Modification to TCP's Fast Recovery Algorithm," RFC + 2582, April 1999. + + [Jacobson88] Jacobson, V., "Congestion Avoidance and Control," + Proc. ACM SIGCOMM, Stanford, CA, August 1988. + + [Mahdavi98] Mahdavi, J. and Floyd, S., "The TCP Friendly + Website," + http://www.psc.edu/networking/tcp_friendly.html + + [Mogul90] Mogul, J. and S. Deering, "Path MTU Discovery," RFC + 1191, November 1990. + + [Padmanabhan98] Padmanabhan, V., "Addressing the Challenges of Web + Data Transport," PhD thesis, Univ. of California, + Berkeley, December 1998. + + [Paxson00] Paxson, V. and M. Allman, "Computing TCP's + Retransmission Timer", RFC 2988, November 2000. + + [Postel81] Postel, J., Editor, "Transmission Control + Protocol", STD 7, RFC 793, September 1981. + + [Ramakrishnan99] Ramakrishnan, K. and Floyd, S., "A Proposal to Add + Explicit Congestion Notification (ECN) to IP," RFC + 2481, January 1999. + + + [Stevens94] Stevens, W., TCP/IP Illustrated, Volume 1. + Addison-Wesley, Reading, MA, 1994. + + [Touch97] Touch, J., "TCP Control Block Interdependence", RFC + 2140, April 1997. + + + +Balakrishnan, et. al. Standards Track [Page 20] + +RFC 3124 The Congestion Manager June 2001 + + +8. Acknowledgments + + We thank David Andersen, Deepak Bansal, and Dorothy Curtis for their + work on the CM design and implementation. We thank Vern Paxson for + his detailed comments, feedback, and patience, and Sally Floyd, Mark + Handley, and Steven McCanne for useful feedback on the CM + architecture. Allison Mankin and Joe Touch provided several useful + comments on previous drafts of this document. + +9. Authors' Addresses + + Hari Balakrishnan + Laboratory for Computer Science + 200 Technology Square + Massachusetts Institute of Technology + Cambridge, MA 02139 + + EMail: [email protected] + Web: http://nms.lcs.mit.edu/~hari/ + + + Srinivasan Seshan + School of Computer Science + Carnegie Mellon University + 5000 Forbes Ave. + Pittsburgh, PA 15213 + + EMail: [email protected] + Web: http://www.cs.cmu.edu/~srini/ + + + + + + + + + + + + + + + + + + + + + + +Balakrishnan, et. al. Standards Track [Page 21] + +RFC 3124 The Congestion Manager June 2001 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2001). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Balakrishnan, et. al. Standards Track [Page 22] + diff --git a/lib/diameter/doc/standard/rfc3539.txt b/lib/diameter/doc/standard/rfc3539.txt new file mode 100644 index 0000000000..0b18625cc5 --- /dev/null +++ b/lib/diameter/doc/standard/rfc3539.txt @@ -0,0 +1,2299 @@ + + + + + + +Network Working Group B. Aboba +Request for Comments: 3539 Microsoft +Category: Standards Track J. Wood + Sun Microsystems, Inc. + June 2003 + + + Authentication, Authorization and Accounting (AAA) Transport Profile + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2003). All Rights Reserved. + +Abstract + + This document discusses transport issues that arise within protocols + for Authentication, Authorization and Accounting (AAA). It also + provides recommendations on the use of transport by AAA protocols. + This includes usage of standards-track RFCs as well as experimental + proposals. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 1.1. Requirements Language. . . . . . . . . . . . . . . . . . 2 + 1.2. Terminology. . . . . . . . . . . . . . . . . . . . . . . 2 + 2. Issues in Transport Usage. . . . . . . . . . . . . . . . . . . 5 + 2.1. Application-driven Versus Network-driven . . . . . . . . 5 + 2.2. Slow Failover. . . . . . . . . . . . . . . . . . . . . . 6 + 2.3. Use of Nagle Algorithm . . . . . . . . . . . . . . . . . 7 + 2.4. Multiple Connections . . . . . . . . . . . . . . . . . . 7 + 2.5. Duplicate Detection. . . . . . . . . . . . . . . . . . . 8 + 2.6. Invalidation of Transport Parameter Estimates. . . . . . 8 + 2.7. Inability to use Fast Re-Transmit. . . . . . . . . . . . 9 + 2.8. Congestion Avoidance . . . . . . . . . . . . . . . . . . 9 + 2.9. Delayed Acknowledgments. . . . . . . . . . . . . . . . . 11 + 2.10. Premature Failover . . . . . . . . . . . . . . . . . . . 11 + 2.11. Head of Line Blocking. . . . . . . . . . . . . . . . . . 11 + 2.12. Connection Load Balancing. . . . . . . . . . . . . . . . 12 + + + + +Aboba & Wood Standards Track [Page 1] + +RFC 3539 AAA Transport Profile June 2003 + + + 3. AAA Transport Profile. . . . . . . . . . . . . . . . . . . . . 12 + 3.1. Transport Mappings . . . . . . . . . . . . . . . . . . . 12 + 3.2. Use of Nagle Algorithm . . . . . . . . . . . . . . . . . 12 + 3.3. Multiple Connections . . . . . . . . . . . . . . . . . . 13 + 3.4. Application Layer Watchdog . . . . . . . . . . . . . . . 13 + 3.5. Duplicate Detection. . . . . . . . . . . . . . . . . . . 19 + 3.6. Invalidation of Transport Parameter Estimates. . . . . . 20 + 3.7. Inability to use Fast Re-Transmit. . . . . . . . . . . . 21 + 3.8. Head of Line Blocking. . . . . . . . . . . . . . . . . . 22 + 3.9. Congestion Avoidance . . . . . . . . . . . . . . . . . . 23 + 3.10. Premature Failover . . . . . . . . . . . . . . . . . . . 24 + 4. Security Considerations. . . . . . . . . . . . . . . . . . . . 24 + 5. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 25 + 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 + 6.1. Normative References . . . . . . . . . . . . . . . . . . 25 + 6.2. Informative References . . . . . . . . . . . . . . . . . 26 + Appendix A - Detailed Watchdog Algorithm Description . . . . . . . 28 + Appendix B - AAA Agents. . . . . . . . . . . . . . . . . . . . . . 33 + B.1. Relays and Proxies . . . . . . . . . . . . . . . . . . . 33 + B.2. Re-directs . . . . . . . . . . . . . . . . . . . . . . . 35 + B.3. Store and Forward Proxies. . . . . . . . . . . . . . . . 36 + B.4. Transport Layer Proxies. . . . . . . . . . . . . . . . . 38 + Intellectual Property Statement. . . . . . . . . . . . . . . . . . 39 + Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . . . 39 + Author Addresses . . . . . . . . . . . . . . . . . . . . . . . . . 40 + Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 41 + +1. Introduction + + This document discusses transport issues that arise within protocols + for Authentication, Authorization and Accounting (AAA). It also + provides recommendations on the use of transport by AAA protocols. + This includes usage of standards-track RFCs as well as experimental + proposals. + +1.1. Requirements Language + + In this document, the key words "MAY", "MUST, "MUST NOT", "optional", + "recommended", "SHOULD", and "SHOULD NOT", are to be interpreted as + described in [RFC2119]. + +1.2. Terminology + + Accounting + The act of collecting information on resource usage for the + purpose of trend analysis, auditing, billing, or cost + allocation. + + + + +Aboba & Wood Standards Track [Page 2] + +RFC 3539 AAA Transport Profile June 2003 + + + Administrative Domain + An internet, or a collection of networks, computers, and + databases under a common administration. + + Agent A AAA agent is an intermediary that communicates with AAA + clients and servers. Several types of AAA agents exist, + including Relays, Re-directs, and Proxies. + + Application-driven transport + Transport behavior is said to be "application-driven" when + the rate at which messages are sent is limited by the rate + at which the application generates data, rather than by the + size of the congestion window. In the most extreme case, + the time between transactions exceeds the round-trip time + between sender and receiver, implying that the application + operates with an effective congestion window of one. AAA + transport is typically application driven. + + Attribute Value Pair (AVP) + The variable length concatenation of a unique Attribute + (represented by an integer) and a Value containing the + actual value identified by the attribute. + + Authentication + The act of verifying a claimed identity, in the form of a + pre-existing label from a mutually known name space, as the + originator of a message (message authentication) or as the + end-point of a channel (entity authentication). + + Authorization + The act of determining if a particular right, such as + access to some resource, can be granted to the presenter of + a particular credential. + + Billing The act of preparing an invoice. + + Network Access Identifier + The Network Access Identifier (NAI) is the userID submitted + by the host during network access authentication. In + roaming, the purpose of the NAI is to identify the user as + well as to assist in the routing of the authentication + request. The NAI may not necessarily be the same as the + user's e-mail address or the user-ID submitted in an + application layer authentication. + + + + + + + +Aboba & Wood Standards Track [Page 3] + +RFC 3539 AAA Transport Profile June 2003 + + + Network Access Server (NAS) + A Network Access Server (NAS) is a device that hosts + connect to in order to get access to the network. + + Proxy In addition to forwarding requests and responses, proxies + enforce policies relating to resource usage and + provisioning. This is typically accomplished by tracking + the state of NAS devices. While proxies typically do not + respond to client Requests prior to receiving a Response + from the server, they may originate Reject messages in + cases where policies are violated. As a result, proxies + need to understand the semantics of the messages passing + through them, and may not support all extensions. + + Local Proxy + A Local Proxy is a proxy that exists within the same + administrative domain as the network device (e.g. NAS) that + issued the AAA request. Typically a local proxy is used to + multiplex AAA messages to and from a large number of + network devices, and may implement policy. + + Store and forward proxy + Store and forward proxies distinguish themselves from other + proxy species by sending a reply to the NAS prior to + proxying the request to the server. As a result, store and + forward proxies need to implement AAA client and server + functionality for the messages that they handle. Store and + Forward proxies also typically keep state on conversations + in progress in order to assure delivery of proxied Requests + and Responses. While store and forward proxies are most + frequently deployed for accounting, they also can be used + to implement authentication/authorization policy. + + Network-driven transport + Transport behavior is said to be "network driven" when the + rate at which messages are sent is limited by the + congestion window, not by the rate at which the application + can generate data. File transfer is an example of an + application where transport is network driven. + + Re-direct Rather than forwarding Requests and Responses between + clients and servers, Re-directs refer clients to servers + and allow them to communicate directly. Since Re-directs + do not sit in the forwarding path, they do not alter any + AVPs transitting between client and server. Re-directs do + not originate messages and are capable of handling any + message type. A Re-direct may be configured only to re- + direct messages of certain types, while acting as a Relay + + + +Aboba & Wood Standards Track [Page 4] + +RFC 3539 AAA Transport Profile June 2003 + + + or Proxy for other types. As with Relays, re-directs do + not keep state with respect to conversations or NAS + resources. + + Relay Relays forward requests and responses based on routing- + related AVPs and domain forwarding table entries. Since + relays do not enforce policies, they do not examine or + alter non-routing AVPs. As a result, relays never + originate messages, do not need to understand the semantics + of messages or non-routing AVPs, and are capable of + handling any extension or message type. Since relays make + decisions based on information in routing AVPs and domain + forwarding tables they do not keep state on NAS resource + usage or conversations in progress. + +2. Issues in AAA Transport Usage + + Issues that arise in AAA transport usage include: + + Application-driven versus network-driven + Slow failover + Use of Nagle Algorithm + Multiple connections + Duplicate detection + Invalidation of transport parameter estimates + Inability to use fast re-transmit + Congestion avoidance + Delayed acknowledgments + Premature Failover + Head of line blocking + Connection load balancing + + We discuss each of these issues in turn. + +2.1. Application-driven versus Network-driven + + AAA transport behavior is typically application rather than network + driven. This means that the rate at which messages are sent is + typically limited by how quickly they are generated by the + application, rather than by the size of the congestion window. + + For example, let us assume a 48-port NAS with an average session time + of 20 minutes. This device will, on average, send only 144 + authentication/authorization requests/hour, and an equivalent number + of accounting requests. This represents an average inter-packet + spacing of 25 seconds, which is much larger than the Round Trip Time + (RTT) in most networks. + + + + +Aboba & Wood Standards Track [Page 5] + +RFC 3539 AAA Transport Profile June 2003 + + + Even on much larger NAS devices, the inter-packet spacing is often + larger than the RTT. For example, consider a 2048-port NAS with an + average session time of 10 minutes. It will on average send 3.4 + authentication/authorization requests/second, and an equivalent + number of accounting requests. This translates to an average inter- + packet spacing of 293 ms. + + However, even where transport behavior is largely application-driven, + periods of network-driven behavior can occur. For example, after a + NAS reboot, previously stored accounting records may be sent to the + accounting server in rapid succession. Similarly, after recovery + from a power failure, users may respond with a large number of + simultaneous logins. In both cases, AAA messages may be generated + more quickly than the network will allow them to be sent, and a queue + will build up. + + Network congestion can occur when transport behavior is network- + driven or application-driven. For example, while a single NAS may + not send substantial AAA traffic, many NASes may communicate with a + single AAA proxy or server. As a result, routers close to a heavily + loaded proxy or server may experience congestion, even though traffic + from each individual NAS is light. Such "convergent congestion" can + result in dropped packets in routers near the AAA server, or even + within the AAA server itself. + + Let us consider what happens when 10,000 48-ports NASes, each with an + average session time of 20 minutes, are configured with the same AAA + agent or server. The unfortunate proxy or server would receive 400 + authentication/authorization requests/second and an equivalent number + of accounting requests. For 1000 octet requests, this would generate + 6.4 Mbps of incoming traffic at the AAA agent or server. + + While this transaction load is within the capabilities of the fastest + AAA agents and servers, implementations exist that cannot handle such + a high load. Thus high queuing delays and/or dropped packets may be + experienced at the agent or server, even if routers on the path are + not congested. Thus, a well designed AAA protocol needs to be able + to handle congestion occurring at the AAA server, as well as + congestion experienced within the network. + +2.2. Slow Failover + + Where TCP [RFC793] is used as the transport, AAA implementations will + experience very slow fail over times if they wait until a TCP + connection times out before resending on another connection. This is + not an issue for SCTP [RFC2960], which supports endpoint and path + failure detection. As described in section 8 of [RFC2960], when the + number of retransmissions exceeds the maximum + + + +Aboba & Wood Standards Track [Page 6] + +RFC 3539 AAA Transport Profile June 2003 + + + ("Association.Max.Retrans"), the peer endpoint is considered + unreachable, the association enters the CLOSED state, and the failure + is reported to the application. This enables more rapid failure + detection. + +2.3. Use of Nagle Algorithm + + AAA protocol messages are often smaller than the maximum segment size + (MSS). While exceptions occur when certificate-based authentication + messages are issued or where a low path MTU is found, typically AAA + protocol messages are less than 1000 octets. Therefore, when using + TCP [RFC793], the total packet count and associated network overhead + can be reduced by combining multiple AAA messages within a single + packet. + + Where AAA runs over TCP and transport behavior is network-driven, + such as after a reboot when many users login simultaneously, or many + stored accounting records need to be sent, the Nagle algorithm will + result in "transport layer batching" of AAA messages. While this + does not reduce the work required by the application in parsing + packets and responding to the messages, it does reduce the number of + packets processed by routers along the path. The Nagle algorithm is + not used with SCTP. + + Where AAA transport is application-driven, the NAS will typically + receive a reply from the home server prior to having another request + to send. This implies, for example, that accounting requests will + typically be sent individually rather than being batched by the + transport layer. As a result, within the application-driven regime, + the Nagle algorithm [RFC896] is ineffective. + +2.4. Multiple Connections + + Since the RADIUS [RFC2865] Identifier field is a single octet, a + maximum of 256 requests can be in progress between two endpoints + described by a 5-tuple: (Client IP address, Client port, UDP, Server + IP address, Server port). In order to get around this limitation, + RADIUS clients have utilized more than one sending port, sometimes + even going to the extreme of using a different UDP source port for + each NAS port. + + Were this behavior to be extended to AAA protocols operating over + reliable transport, the result would be multiplication of the + effective slow-start ramp-up by the number of connections. For + example, if a AAA client had ten connections open to a AAA agent, and + used a per-connection initial window [RFC3390] of 2, then the + + + + + +Aboba & Wood Standards Track [Page 7] + +RFC 3539 AAA Transport Profile June 2003 + + + effective initial window would be 20. This is inappropriate, since + it would permit the AAA client to send a large burst of packets into + the network. + +2.5. Duplicate Detection + + Where a AAA client maintains connections to multiple AAA agents or + servers, and where failover/failback or connection load balancing is + supported, it is possible for multiple agents or servers to receive + duplicate copies of the same transaction. A transaction may be sent + on another connection before expiration of the "time wait" interval + necessary to guarantee that all packets sent on the original + connection have left the network. Therefore it is conceivable that + transactions sent on the alternate connection will arrive before + those sent on the failed connection. As a result, AAA agents and + servers MUST be prepared to handle duplicates, and MUST assume that + duplicates can arrive on any connection. + + For example, in billing, it is necessary to be able to weed out + duplicate accounting records, based on the accounting session-id, + event-timestamp and NAS identification information. Where + authentication requests are always idempotent, the resultant + duplicate responses from multiple servers will presumably be + identical, so that little harm will result. + + However, there are situations where the response to an authentication + request will depend on a previously established state, such as when + simultaneous usage restrictions are being enforced. In such cases, + authentication requests will not be idempotent. For example, while + an initial request might elicit an Accept response, a duplicate + request might elicit a Reject response from another server, if the + user were already presumed to be logged in, and only one simultaneous + session were permitted. In these situations, the AAA client might + receive both Accept and Reject responses to the same duplicate + request, and the outcome will depend on which response arrives first. + +2.6. Invalidation of Transport Parameter Estimates + + Congestion control principles [Congest],[RFC2914] require the ability + of a transport protocol to respond effectively to congestion, as + sensed via increasing delays, packet loss, or explicit congestion + notification. + + With network-driven applications, it is possible to respond to + congestion on a timescale comparable to the round-trip time (RTT). + + However, with AAA protocols, the time between sends may be longer + than the RTT, so that the network conditions can not be assumed to + + + +Aboba & Wood Standards Track [Page 8] + +RFC 3539 AAA Transport Profile June 2003 + + + persist between sends. For example, the congestion window may grow + during a period in which congestion is being experienced because few + packets are sent, limiting the opportunity for feedback. Similarly, + after congestion is detected, the congestion window may remain small, + even though the network conditions that existed at the time of + congestion no longer apply by the time when the next packets are + sent. In addition, due to the low sampling interval, estimates of + RTT and RTO made via the procedure described in [RFC2988] may become + invalid. + +2.7. Inability to Use Fast Re-transmit + + When congestion window validation [RFC2861] is implemented, the + result is that AAA protocols operate much of the time in slow-start + with an initial congestion window set to 1 or 2, depending on the + implementation [RFC3390]. This implies that AAA protocols gain + little benefit from the windowing features of reliable transport. + + Since the congestion window is so small, it is generally not possible + to receive enough duplicate ACKs (3) to trigger fast re-transmit. In + addition, since AAA traffic is two-way, ACKs including data will not + count as part of the duplicate ACKs necessary to trigger fast re- + transmit. As a result, dropped packets will require a retransmission + timeout (RTO). + +2.8. Congestion Avoidance + + The law of conservation of packets [Congest] suggests that a client + should not send another packet into the network until it can be + reasonably sure that a packet has exited the network on the same + path. In the case of a AAA client, the law suggests that it should + not retransmit to the same server or choose another server until it + can be reasonably sure that a packet has exited the network on the + same path. If the client advances the window as responses arrive, + then the client will "self clock", adjusting its transmission rate to + the available bandwidth. + + While a AAA client using a reliable transport such as TCP [RFC793] or + SCTP [RFC2960] will self-clock when communicating directly with a + AAA-server, end-to-end self-clocking is not assured when AAA agents + are present. + + As described in the Appendix, AAA agents include Relays, Proxies, + Re-directs, Store and Forward proxies, and Transport proxies. Of + these agents, only Transport proxies and Re-directs provide a direct + transport connection between the AAA client and server, allowing + end-to-end self-clocking to occur. + + + + +Aboba & Wood Standards Track [Page 9] + +RFC 3539 AAA Transport Profile June 2003 + + + With Relays, Proxies or Store and Forward proxies, two separate and + de-coupled transport connections are used. One connection operates + between the AAA client and agent, and another between the agent and + server. Since the two transport connections are de-coupled, + transport layer ACKs do not flow end-to-end, and self-clocking does + not occur. + + For example, consider what happens when the bottleneck exists between + a AAA Relay and a AAA server. Self-clocking will occur between the + AAA client and AAA Relay, causing the AAA client to adjust its + sending rate to the rate at which transport ACKs flow back from the + AAA Relay. However, since this rate is higher than the bottleneck + bandwidth, the overall system will not self-clock. + + Since there is no direct transport connection between the AAA client + and AAA server, the AAA client does not have the ability to estimate + end-to-end transport parameters and adjust its sending rate to the + bottleneck bandwidth between the Relay and server. As a result, the + incoming rate at the AAA Relay can be higher than the rate at which + packets can be sent to the AAA server. + + In this case, the end-to-end performance will be determined by + details of the agent implementation. In general, the end-to-end + transport performance in the presence of Relays, Proxies or Store and + Forward proxies will always be worse in terms of delay and packet + loss than if the AAA client and server were communicating directly. + + For example, if the agent operates with a large receive buffer, it is + possible that a large queue will develop on the receiving side, since + the AAA client is able to send packets to the AAA agent more rapidly + than the agent can send them to the AAA server. Eventually, the + buffer will overflow, causing wholesale packet loss as well as high + delay. + + Methods to induce fine-grained coupling between the two transport + connections are difficult to implement. One possible solution is for + the AAA agent to operate with a receive buffer that is no larger than + its send buffer. If this is done, "back pressure" (closing of the + receive window) will cause the agent to reduce the AAA client sending + rate when the agent send buffer fills. However, unless multiple + connections exist between the AAA client and AAA agent, closing of + the receive window will affect all traffic sent by the AAA client, + even traffic destined to AAA servers where no bottleneck exists. + Since multiple connections between a AAA client and agent result in + multiplication of the effective slow-start ramp rate, this is not + recommended. As a result, use of "back pressure" cannot enable + individual AAA client-server conversations to self-clock, and this + technique appears impractical for use in AAA. + + + +Aboba & Wood Standards Track [Page 10] + +RFC 3539 AAA Transport Profile June 2003 + + +2.9. Delayed Acknowledgments + + As described in Appendix B, ACKs may comprise as much as half of the + traffic generated in a AAA exchange. This occurs because AAA + conversations are typically application-driven, and therefore there + is frequently not enough traffic to enable ACK piggybacking. As a + result, AAA protocols running over TCP or SCTP transport may + experience a doubling of traffic as compared with implementations + utilizing UDP transport. + + It is typically not possible to address this issue via the sockets + API. ACK parameters (such as the value of the delayed ACK timer) are + typically fixed by TCP and SCTP implementations and are therefore not + tunable by the application. + +2.10. Premature Failover + + RADIUS failover implementations are typically based on the concept of + primary and secondary servers, in which all traffic flows to the + primary server unless it is unavailable. However, the failover + algorithm was not specified in [RFC2865] or [RFC2866]. As a result, + RADIUS failover implementations vary in quality, with some failing + over prematurely, violating the law of "conservation of packets". + + Where a Relay, Proxy or Store and Forward proxy is present, the AAA + client has no direct connection to a AAA server, and is unable to + estimate the end-to-end transport parameters. As a result, a AAA + client awaiting an application-layer response from the server has no + transport-based mechanism for determining an appropriate failover + timer. + + For example, if the path between the AAA agent and server includes a + high delay link, or if the AAA server is very heavily loaded, it is + possible that the NAS will failover to another agent while packets + are still in flight. This violates the principle of "conservation of + packets", since the AAA client will inject additional packets into + the network before having evidence that a previously sent packet has + left the network. Such behavior can result in a worse situation on + an already congested link, resulting in congestive collapse + [Congest]. + +2.11. Head of Line Blocking + + Head of line blocking occurs during periods of packet loss where the + time between sends is shorter than the re-transmission timeout value + (RTO). In such situations, packets back up in the send queue until + + + + + +Aboba & Wood Standards Track [Page 11] + +RFC 3539 AAA Transport Profile June 2003 + + + the lost packet can be successfully re-transmitted. This can be an + issue for SCTP when using ordered delivery over a single stream, and + for TCP. + + Head of line blocking is typically an issue only on larger NASes. + For example, a 48-port NAS with an average inter-packet spacing of 25 + seconds is unlikely to have an RTO greater than this, unless severe + packet loss has been experienced. However, a 2048-port NAS with an + average inter-packet spacing of 293 ms may experience head-of-line + blocking since the inter-packet spacing is less than the minimum RTO + value of 1 second [RFC2988]. + +2.12. Connection Load Balancing + + In order to lessen queuing delays and address head of line blocking, + a AAA implementation may wish to load balance between connections to + multiple destinations. While it is possible to employ dynamic load + balancing techniques, this level of sophistication may not be + required. In many situations, adequate reliability and load + balancing can be achieved via static load balancing, where traffic is + distributed between destinations based on static "weights". + +3. AAA Transport Profile + + In order to address AAA transport issues, it is recommended that AAA + protocols make use of standards track as well as experimental + techniques. More details are provided in the sections that follow. + +3.1. Transport Mappings + + AAA Servers MUST support TCP and SCTP. AAA clients SHOULD support + SCTP, but MUST support TCP if SCTP is not available. As support for + SCTP improves, it is possible that SCTP support will be required on + clients at some point in the future. AAA agents inherit all the + obligations of Servers with respect to transport support. + +3.2. Use of Nagle Algorithm + + While AAA protocols typically operate in the application-driven + regime, there are circumstances in which they are network driven. + For example, where an NAS reboots, or where connectivity is restored + between an NAS and a AAA agent, it is possible that multiple packets + will be available for sending. + + As a result, there are circumstances where the transport-layer + batching provided by the Nagle Algorithm (12) is useful, and as a + result, AAA implementations running over TCP MUST enable the Nagle + algorithm, [RFC896]. The Nagle algorithm is not used with SCTP. + + + +Aboba & Wood Standards Track [Page 12] + +RFC 3539 AAA Transport Profile June 2003 + + +3.3. Multiple Connections + + AAA protocols SHOULD use only a single persistent connection between + a AAA client and a AAA agent or server. They SHOULD provide for + pipelining of requests, so that more than one request can be in + progress at a time. In order to minimize use of inactive connections + in roaming situations, a AAA client or agent MAY bring down a + connection to a AAA agent or server if the connection has been + unutilized (discounting the watchdog) for a certain period of time, + which MUST NOT be less than BRINGDOWN_INTERVAL (5 minutes). + + While a AAA client/agent SHOULD only use a single persistent + connection to a given AAA agent or server, it MAY have connections to + multiple AAA agents or servers. A AAA client/agent connected to + multiple agents/servers can treat them as primary/secondary or + balance load between them. + +3.4. Application Layer Watchdog + + In order to enable AAA implementations to more quickly detect + transport and application-layer failures, AAA protocols MUST support + an application layer watchdog message. + + The application layer watchdog message enables failover from a peer + that has failed, either because it is unreachable or because its + applications functions have failed. This is distinct from the + purpose of the SCTP heartbeat, which is to enable failover between + interfaces. The SCTP heartbeat may enable a failover to another path + to reach the same server, but does not address the situation where + the server system or the application service has failed. Therefore + both mechanisms MAY be used together. + + The watchdog is used in order to enable a AAA client or agent to + determine when to resend on another connection. It operates on all + open connections and is used to suspend and eventually close + connections that are experiencing difficulties. The watchdog is also + used to re-open and validate connections that have returned to + health. The watchdog may be utilized either within primary/secondary + or load balancing configurations. However, it is not intended as a + cluster heartbeat mechanism. + + The application layer watchdog is designed to detect failures of the + immediate peer, and not to be affected by failures of downstream + proxies or servers. This prevents instability in downstream AAA + components from propagating upstream. While the receipt of any AAA + Response from a peer is taken as evidence that the peer is up, lack + of a Response is insufficient to conclude that the peer is down. + Since the lack of Response may be the result of problems with a + + + +Aboba & Wood Standards Track [Page 13] + +RFC 3539 AAA Transport Profile June 2003 + + + downstream proxy or server, only after failure to respond to the + watchdog message can it be determined that the peer is down. + + Since the watchdog algorithm takes any AAA Response into account in + determining peer liveness, decreases in the watchdog timer interval + do not significantly increase the level of watchdog traffic on + heavily loaded networks. This is because watchdog messages do not + need to be sent where other AAA Response traffic serves as a constant + reminder of peer liveness. Watchdog traffic only increases when AAA + traffic is light, and therefore a AAA Response "signal" is not + present. Nevertheless, decreasing the timer interval TWINIT does + increase the probability of false failover significantly, and so this + decision should be made with care. + +3.4.1. Algorithm Overview + + The watchdog behavior is controlled by an algorithm defined in this + section. This algorithm is appropriate for use either within + primary/secondary or load balancing configurations. Implementations + SHOULD implement this algorithm, which operates as follows: + + [1] Watchdog behavior is controlled by a single timer (Tw). The + initial value of Tw, prior to jittering is Twinit. The default + value of Twinit is 30 seconds. This value was selected because + it minimizes the probability that failover will be initiated due + to a routing flap, as noted in [Paxson]. + + While Twinit MAY be set as low as 6 seconds (not including + jitter), it MUST NOT be set lower than this. Note that setting + such a low value for Twinit is likely to result in an increased + probability of duplicates, as well as an increase in spurious + failover and failback attempts. + + In order to avoid synchronization behaviors that can occur with + fixed timers among distributed systems, each time the watchdog + interval is calculated with a jitter by using the Twinit value + and randomly adding a value drawn between -2 and 2 seconds. + Alternative calculations to create jitter MAY be used. These + MUST be pseudo-random, generated by a PRNG seeded as per + [RFC1750]. + + [2] When any AAA message is received, Tw is reset. This need not be + a response to a watchdog request. Receiving a watchdog response + from a peer constitutes activity, and Tw should be reset. If the + watchdog timer expires and no watchdog response is pending, then + a watchdog message is sent. On sending a watchdog request, Tw is + reset. + + + + +Aboba & Wood Standards Track [Page 14] + +RFC 3539 AAA Transport Profile June 2003 + + + Watchdog packets are not retransmitted by the AAA protocol, since + AAA protocols run over reliable transports that will handle all + retransmissions internally. As a result, a watchdog request is + only sent when there is no watchdog response pending. + + [3] If the watchdog timer expires and a watchdog response is pending, + then failover is initiated. In order for a AAA client or agent + to perform failover procedures, it is necessary to maintain a + pending message queue for a given peer. When an answer message + is received, the corresponding request is removed from the queue. + The Hop-by-Hop Identifier field MAY be used to match the answer + with the queued request. + + When failover is initiated, all messages in the queue are sent to + an alternate agent, if available. Multiple identical requests or + answers may be received as a result of a failover. The + combination of an end-to-end identifier and the origin host MUST + be used to identify duplicate messages. + + Note that where traffic is heavy, the application layer watchdog + can take as long as 2Tw to determine that a peer has gone down. + For peers receiving a high volume of AAA Requests, AAA Responses + will continually reset the timer, so that after a failure it will + take Tw for the lack of traffic to be noticed, and for the + watchdog message to be sent. Another Tw will elapse before + failover is initiated. + + On a lightly loaded network without much AAA Response traffic, + the watchdog timer will typically expire without being reset, so + that a watchdog response will be outstanding and failover will be + initiated after only a single timer interval has expired. + + [4] The client MUST NOT close the primary connection until the + primary's watchdog timer has expired at least twice without a + response (note that the watchdog is not sent a second time, + however). Once this has occurred, the client SHOULD cause a + transport reset or close to be done on the connection. + + Once the primary connection has failed, subsequent requests are + sent to the alternate server until the watchdog timer on the + primary connection is reset. + + Suspension of the primary connection prevents flapping between + primary and alternate connections, and ensures that failover + behavior remains consistent. The application may not receive a + response to the watchdog request message due to a connectivity + problem, in which case a transport layer ACK will not have been + received, or the lack of response may be due to an application + + + +Aboba & Wood Standards Track [Page 15] + +RFC 3539 AAA Transport Profile June 2003 + + + problem. Without transport layer visibility, the application is + unable to tell the difference, and must behave conservatively. + + In situations where no transport layer ACK is received on the + primary connection after multiple re-transmissions, the RTO will + be exponentially backed off as described in [RFC2988]. Due to + Karn's algorithm as implemented in SCTP and TCP, the RTO + estimator will not be reset until another ACK is received in + response to a non-re-transmitted request. Thus, in cases where + the problem occurs at the transport layer, after the client fails + over to the alternate server, the RTO of the primary will remain + at a high value unless an ACK is received on the primary + connection. + + In the case where the problem occurs at the transport layer, + subsequent requests sent on the primary connection will not + receive the same service as was originally provided. For + example, instead of failover occurring after 3 retransmissions, + failover might occur without even a single retransmission if RTO + has been sufficiently backed off. Of course, if the lack of a + watchdog response was due to an application layer problem, then + RTO will not have been backed off. However, without transport + layer visibility, there is no way for the application to know + this. + + Suspending use of the primary connection until a response to a + watchdog message is received guarantees that the RTO timer will + have been reset before the primary connection is reused. If no + response is received after the second watchdog timer expiration, + then the primary connection is closed and the suspension becomes + permanent. + + [5] While the connection is in the closed state, the AAA client MUST + NOT attempt to send further watchdog messages on the connection. + However, after the connection is closed, the AAA client continues + to periodically attempt to reopen the connection. + + The AAA client SHOULD wait for the transport layer to report + connection failure before attempting again, but MAY choose to + bound this wait time by the watchdog interval, Tw. If the + connection is successfully opened, then the watchdog message is + sent. Once three watchdog messages have been sent and responded + to, the connection is returned to service, and transactions are + once again sent over it. Connection validation via receipt of + multiple watchdogs is not required when a connection is initially + brought up -- in this case, the connection can immediately be put + into service. + + + + +Aboba & Wood Standards Track [Page 16] + +RFC 3539 AAA Transport Profile June 2003 + + + [6] When using SCTP as a transport, it is not necessary to disable + SCTP's transport-layer heartbeats. However, if AAA + implementations have access to SCTP's heartbeat parameters, they + MAY chose to ensure that SCTP's heartbeat interval is longer than + the AAA watchdog interval, Tw. This will ensure that alternate + paths are still probed by SCTP, while the primary path has a + minimum of heartbeat redundancy. + +3.4.2. Primary/Secondary Failover Support + + The watchdog timer MAY be integrated with primary/secondary style + failover so as to provide improved reliability and basic load + balancing. In order to balance load among multiple AAA servers, each + AAA server is designated the primary for a portion of the clients, + and designated as secondaries of varying priority for the remainder. + In this way, load can be balanced among the AAA servers. + + Within primary/secondary configurations, the watchdog timer operates + as follows: + + [1] Assume that each client or agent is initially configured with a + single primary agent or server, and one or more secondary + connections. + + [2] The watchdog mechanism is used to suspend and eventually close + primary connections that are experiencing difficulties. It is + also used to re-open and validate connections that have returned + to health. + + [3] Once a secondary is promoted to primary status, either on a + temporary or permanent basis, the next server on the list of + secondaries is promoted to fill the open secondary slot. + + [4] The client or agent periodically attempts to re-open closed + connections, so that it is possible that a previously closed + connection can be returned to service and become eligible for use + again. Implementations will typically retain a limit on the + number of connections open at a time, so that once a previously + closed connection is brought online again, the lowest priority + secondary connection will be closed. In order to prevent + periodic closing and re-opening of secondary connections, it is + recommended that functioning connections remain open for a + minimum of 5 minutes. + + [5] In order to enable diagnosis of failover behavior, it is + recommended that a table of failover events be kept within the + MIB. These failover events SHOULD include appropriate + transaction identifiers so that client and server data can be + + + +Aboba & Wood Standards Track [Page 17] + +RFC 3539 AAA Transport Profile June 2003 + + + compared, providing insight into the cause of the problem + (transport or application layer). + +3.4.3. Connection Load Balancing + + Primary/secondary failover is capable of providing improved + resilience and basic load balancing. However, it does not address + TCP head of line blocking, since only a single connection is in use + at a time. + + A AAA client or agent maintaining connections to multiple agents or + servers MAY load balance between them. Establishing connections to + multiple agents or servers reduces, but does not eliminate, head of + line blocking issues experienced on TCP connections. This issue does + not exist with SCTP connections utilizing multiple streams. + + In connection load balancing configurations, the application watchdog + operates as follows: + + [1] Assume that each client or agent is initially configured with + connections to multiple AAA agents or servers, with one + connection between a given client/agent and an agent/server. + + [2] In static load balancing, transactions are apportioned among the + connections based on the total number of connections and a + "weight" assigned to each connection. Pearson's hash [RFC3074] + applied to the NAI [RFC2486] can be used to determine which + connection will handle a given transaction. Hashing on the NAI + provides highly granular load balancing, while ensuring that all + traffic for a given conversation will be sent to the same agent + or server. In dynamic load balancing, the value of the "weight" + can vary based on conditions such as AAA server load. Such + techniques, while sophisticated, are beyond the scope of this + document. + + [3] Transactions are distributed to connections based on the total + number of available connections and their weights. A change in + the number of available connections forces recomputation of the + hash table. In order not to cause conversations in progress to + be switched to new destinations, on recomputation, a transitional + period is required in which both old and new hash tables are + needed in order to permit aging out of conversations in progress. + Note that this requires a way to easily determine whether a + Request represents a new conversation or the continuation of an + existing conversation. As a result, removing and adding of + connections is an expensive operation, and it is recommended that + the hash table only be recomputed once a connection is closed or + returned to service. + + + +Aboba & Wood Standards Track [Page 18] + +RFC 3539 AAA Transport Profile June 2003 + + + Suspended connections, although they are not used, do not force + hash table reconfiguration until they are closed. Similarly, + re-opened connections not accumulating sufficient watchdog + responses do not force a reconfiguration until they are returned + to service. + + While a connection is suspended, transactions that were to have + been assigned to it are instead assigned to the next available + server. While this results in a momentary imbalance, it is felt + that this is a relatively small price to pay in order to reduce + hash table thrashing. + + [4] In order to enable diagnosis of load balancing behavior, it is + recommended that in addition to a table of failover events, a + table of statistics be kept on each client, indexed by a AAA + server. That way, the effectiveness of the load balancing + algorithm can be evaluated. + +3.5. Duplicate Detection + + Multiple facilities are required to enable duplicate detection. + These include session identifiers as well as hop-by-hop and end-to- + end message identifiers. Hop-by-hop identifiers whose value may + change at each hop are not sufficient, since a AAA server may receive + the same message from multiple agents. For example, a AAA client can + send a request to Agent1, then failover and resend the request to + Agent2; both agents forward the request to the home AAA server, with + different hop-by-hop identifiers. A Session Identifier is + insufficient as it does not distinguish different messages for the + the same session. + + Proper treatment of the end-to-end message identifier ensures that + AAA operations are idempotent. For example, without an end-to-end + identifier, a AAA server keeping track of simultaneous logins might + send an Accept in response to an initial Request, and then a Reject + in response to a duplicate Request (where the user was allowed only + one simultaneous login). Depending on which Response arrived first, + the user might be allowed access or not. + + However, if the server were to store the end-to-end message + identifier along with the simultaneous login information, then the + duplicate Request (which utilizes the same end-to-end message + identifier) could be identified and the correct response could be + returned. + + + + + + + +Aboba & Wood Standards Track [Page 19] + +RFC 3539 AAA Transport Profile June 2003 + + +3.6. Invalidation of Transport Parameter Estimates + + In order to address invalidation of transport parameter estimates, + AAA protocol implementations MAY utilize Congestion Window Validation + [RFC2861] and RTO validation when using TCP. This specification also + recommends a procedure for RTO validation. + + [RFC2581] and [RFC2861] both recommend that a connection go into + slow-start after a period where no traffic has been sent within the + RTO interval. [RFC2861] recommends only increasing the congestion + window if it was full when the ACK arrived. The congestion window is + reduced by half once every RTO interval if no traffic is received. + + When Congestion Window Validation is used, the congestion window will + not build during application-driven periods, and instead will be + decayed. As a result, AAA applications operating within the + application-driven regime will typically run with a congestion window + equal to the initial window much of the time, operating in "perpetual + slowstart". + + During periods in which AAA behavior is application-driven this will + have no effect. Since the time between packets will be larger than + RTT, AAA will operate with an effective congestion window equal to + the initial window. However, during network-driven periods, the + effect will be to space out sending of AAA packets. Thus instead of + being able to send a large burst of packets into the network, a + client will need to wait several RTTs as the congestion window builds + during slow-start. + + For example, a client operating over TCP with an initial window of 2, + with 35 AAA requests to send would take approximately 6 RTTs to send + them, as the congestion window builds during slow start: 2, 3, 3, 6, + 9, 12. After the backlog is cleared, the implementation will once + again be application-driven and the congestion window size will + decay. If the client were using SCTP, the number of RTTs needed to + transmit all requests would usually be less, and would depend on the + size of the requests, since SCTP tracks the progress for the opening + of the congestion window by bytes, not segments. + + Note that [RFC2861] and [RFC2988] do not address the issue of RTO + validation. This is also a problem, particularly when the Congestion + Manager [RFC3124] is implemented. During periods of high packet + loss, the RTO may be repeatedly increased via exponential back-off, + and may attain a high value. Due to lack of timely feedback on RTT + and RTO during application-driven periods, the high RTO estimate may + persist long after the conditions that generated it have dissipated. + + + + + +Aboba & Wood Standards Track [Page 20] + +RFC 3539 AAA Transport Profile June 2003 + + + RTO validation MAY be used to address this issue for TCP, via the + following procedure: + + After the congestion window is decayed according to [RFC2861], + reset the estimated RTO to 3 seconds. After the next packet comes + in, re-calculate RTTavg, RTTdev, and RTO according to the method + described in [RFC2581]. + + To address this issue for SCTP, AAA implementations SHOULD use SCTP + heartbeats. [RFC2960] states that heartbeats should be enabled by + default, with an interval of 30 seconds. If this interval proves to + be too long to resolve this issue, AAA implementations MAY reduce the + heartbeat interval. + +3.7. Inability to Use Fast Re-Transmit + + When Congestion Window Validation [RFC2861] is used, AAA + implementations will operate with a congestion window equal to the + initial window much of the time. As a result, the window size will + often not be large enough to enable use of fast re-transmit for TCP. + In addition, since AAA traffic is two-way, ACKs carrying data will + not count towards triggering fast re-transmit. SCTP is less likely + to encounter this issue, so the measures described below apply to + TCP. + + To address this issue, AAA implementations SHOULD support selective + acknowledgement as described in [RFC2018] and [RFC2883]. AAA + implementations SHOULD also implement Limited Transmit for TCP, as + described in [RFC3042]. Rather than reducing the number of duplicate + ACKs required for triggering fast recovery, which would increase the + number of inappropriate re-transmissions, Limited Transmit enables + the window size be increased, thus enabling the sending of additional + packets which in turn may trigger fast re-transmit without a change + to the algorithm. + + However, if congestion window validation [RFC2861] is implemented, + this proposal will only have an effect in situations where the time + between packets is less than the estimated retransmission timeout + (RTO). If the time between packets is greater than RTO, additional + packets will typically not be available for sending so as to take + advantage of the increased window size. As a result, AAA protocols + will typically operate with the lowest possible congestion window + size, resulting in a re-transmission timeout for every lost packet. + + + + + + + + +Aboba & Wood Standards Track [Page 21] + +RFC 3539 AAA Transport Profile June 2003 + + +3.8. Head of Line Blocking + + TCP inherently does not provide a solution to the head-of-line + blocking problem, although its effects can be lessened by + implementation of Limited Transmit [RFC3042], and connection load + balancing. + +3.8.1. Using SCTP Streams to Prevent Head of Line Blocking + + Each AAA node SHOULD distribute its messages evenly across the range + of SCTP streams that it and its peer have agreed upon. (A lost + message in one stream will not cause any other streams to block.) A + trivial and effective implementation of this simply increments a + counter for the stream ID to send on. When the counter reaches the + maximum number of streams for the association, it resets to 0. + + AAA peers MUST be able to accept messages on any stream. Note that + streams are used *solely* to prevent head-of-the-line blocking. All + identifying information is carried within the Diameter payload. + Messages distributed across multiple streams may not be received in + the order they are sent. + + SCTP peers can allocate up to 65535 streams for an association. The + cost for idle streams may or may not be zero, depending on the + implementation, and the cost for non-idle streams is always greater + than 0. So administrators may wish to limit the number of possible + streams on their diameter nodes according to the resources (i.e. + memory, CPU power, etc.) of a particular node. + + On a Diameter client, the number of streams may be determined by the + maximum number of peak users on the NAS. If a stream is available + per user, then this should be sufficient to prevent head-of-line + blocking. On a Diameter proxy, the number of streams may be + determined by the maximum number of peak sessions in progress from + that proxy to each downstream AAA server. + + Stream IDs do not need to be preserved by relay agents. This + simplifies implementation, as agents can easily handle forwarding + between two associations with different numbers of streams. For + example, consider the following case, where a relay server DRL + forwards messages between a NAS and a home server, HMS. The NAS and + DRL have agreed upon 1000 streams for their association, and DRL and + HMS have agreed upon 2000 streams for their association. The + following figure shows the message flow from NAS to HMS via DRL, and + the stream ID assignments for each message: + + + + + + +Aboba & Wood Standards Track [Page 22] + +RFC 3539 AAA Transport Profile June 2003 + + + +------+ +------+ +------+ + | | | | | | + | NAS | ---------> | DRL | ---------> | HMS | + | | | | | | + +------+ 1000 streams +------+ 2000 streams +------+ + + msg 1: str id 0 msg 1: str id 0 + msg 2: str id 1 msg 2: str id 1 + ... + msg 1000: str id 999 msg 1000: str id 999 + msg 1001: str id 0 msg 1001: str id 1000 + + DRL can forward messages 1 through 1000 to HMS using the same stream + ID that NAS used to send to DRL. However, since the NAS / DRL + association has only 1000 streams, NAS wraps around to stream ID 0 + when sending message 1001. The DRL / HMS association, on the other + hand, has 2000 streams, so DRL can reassign message 1001 to stream ID + 1000 when forwarding it on to HMS. + + This distribution scheme acts like a hash table. It is possible, yet + unlikely, that two messages will end up in the same stream, and even + less likely that there will be message loss resulting in blocking + when this happens. If it does turn out to be a problem, local + administrators can increase the number of streams on their nodes to + improve performance. + +3.9. Congestion Avoidance + + In order to improve upon default timer estimates, AAA implementations + MAY implement the Congestion Manager (CM) [RFC3124]. CM is an end- + system module that: + + (i) Enables an ensemble of multiple concurrent streams from a + sender destined to the same receiver and sharing the same + congestion properties to perform proper congestion avoidance + and control, and + + (ii) Allows applications to easily adapt to network congestion. + + The CM helps integrate congestion management across all applications + and transport protocols. The CM maintains congestion parameters + (available aggregate and per-stream bandwidth, per-receiver round- + trip times, etc.) and exports an API that enables applications to + learn about network characteristics, pass information to the CM, + share congestion information with each other, and schedule data + transmissions. + + + + + +Aboba & Wood Standards Track [Page 23] + +RFC 3539 AAA Transport Profile June 2003 + + + The CM enables the AAA application to access transport parameters + (RTTavg, RTTdev) via callbacks. RTO estimates are currently not + available via the callback interface, though they probably should be. + Where available, transport parameters SHOULD be used to improve upon + default timer values. + +3.10. Premature Failover + + Premature failover is prevented by the watchdog functionality + described above. If the next hop does not return a reply, the AAA + client will send a watchdog message to it to verify liveness. If a + watchdog reply is received, then the AAA client will know that the + next hop server is functioning at the application layer. As a + result, it is only necessary to provide terminal error messages, such + as the following: + + "Busy": agent/Server too busy to handle additional requests, NAS + should failover all requests to another agent/server. + + "Can't Locate": agent can't locate the AAA server for the + indicated realm; NAS should failover that request to another + proxy. + + "Can't Forward": agent has tried both primary and secondary AAA + servers with no response; NAS should failover the request to + another agent. + + Note that these messages differ in their scope. The "Busy" message + tells the NAS that the agent/server is too busy for ANY request. The + "Can't Locate" and "Can't Forward" messages indicate that the + ultimate destination cannot be reached or isn't responding, implying + per-request failover. + +4. Security Considerations + + Since AAA clients, agents and servers serve as network access + gatekeepers, they are tempting targets for attackers. General + security considerations concerning TCP congestion control are + discussed in [RFC2581]. However, there are some additional + considerations that apply to this specification. + + By enabling failover between AAA agents, this specification improves + the resilience of AAA applications. However, it may also open + avenues for denial of service attacks. + + The failover algorithm is driven by lack of response to AAA requests + and watchdog packets. On a lightly loaded network where AAA + responses would not be received prior to expiration of the watchdog + + + +Aboba & Wood Standards Track [Page 24] + +RFC 3539 AAA Transport Profile June 2003 + + + timer, an attacker can swamp the network, causing watchdog packets to + be dropped. This will cause the AAA client to switch to another AAA + agent, where the attack can be repeated. By causing the AAA client + to cycle between AAA agents, service can be denied to users desiring + network access. + + Where TLS [RFC2246] is being used to provide AAA security, there will + be a vulnerability to spoofed reset packets, as well as other + transport layer denial of service attacks (e.g. SYN flooding). Since + SCTP offers improved denial of service resilience compared with TCP, + where AAA applications run over SCTP, this can be mitigated to some + extent. + + Where IPsec [RFC2401] is used to provide security, it is important + that IPsec policy require IPsec on incoming packets. In order to + enable a AAA client to determine what security mechanisms are in use + on an agent or server without prior knowledge, it may be tempting to + initiate a connection in the clear, and then to have the AAA agent + respond with IKE [RFC2409]. While this approach minimizes required + client configuration, it increases the vulnerability to denial of + service attack, since a connection request can now not only tie up + transport resources, but also resources within the IKE + implementation. + +5. IANA Considerations + + This document does not create any new number spaces for IANA + administration. + +References + +6.1. Normative References + + [RFC793] Postel, J., "Transmission Control Protocol", STD 7, RFC + 793, September 1981. + + [RFC896] Nagle, J., "Congestion Control in IP/TCP internetworks", + RFC 896, January 1984. + + [RFC1750] Eastlake, D., Crocker, S. and J. Schiller, "Randomness + Recommendations for Security", RFC 1750, December 1994. + + [RFC2018] Mathis, M., Mahdavi, J., Floyd, S. and A. Romanow, "TCP + Selective Acknowledgment Options", RFC 2018, October 1996. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + + + +Aboba & Wood Standards Track [Page 25] + +RFC 3539 AAA Transport Profile June 2003 + + + [RFC2486] Aboba, B. and M. Beadles, "The Network Access Identifier", + RFC 2486, January 1999. + + [RFC2581] Allman, M., Paxson, V. and W. Stevens, "TCP Congestion + Control", RFC 2581, April 1999. + + [RFC2883] Floyd, S., Mahdavi, J., Mathis, M., Podolsky, M. and A. + Romanow, "An Extension to the Selective Acknowledgment + (SACK) Option for TCP", RFC 2883, July 2000. + + [RFC2960] Stewart, R., Xie, Q., Morneault, K., Sharp, C., + Schwarzbauer, H., Taylor, T., Rytina, I., Kalla, M., Zhang, + L. and V. Paxson, "Stream Control Transmission Protocol", + RFC 2960, October 2000. + + [RFC2988] Paxson, V. and M. Allman, "Computing TCP's Retransmission + Timer", RFC 2988, November 2000. + + [RFC3042] Allman, M., Balakrishnan H. and S. Floyd, "Enhancing TCP's + Loss Recovery Using Limited Transmit", RFC 3042, January + 2001. + + [RFC3074] Volz, B., Gonczi, S., Lemon, T. and R. Stevens, "DHC Load + Balancing Algorithm", RFC 3074, February 2001. + + [RFC3124] Balakrishnan, H. and S. Seshan, "The Congestion Manager", + RFC 3124, June 2001. + +6.2. Informative References + + [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", + RFC 2246, January 1999. + + [RFC2401] Atkinson, R. and S. Kent, "Security Architecture for the + Internet Protocol", RFC 2401, November 1998. + + [RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange + (IKE)", RFC 2409, November 1998. + + [RFC2607] Aboba, B. and J. Vollbrecht, "Proxy Chaining and Policy + Implementation in Roaming", RFC 2607, June 1999. + + [RFC2861] Handley, M., Padhye, J. and S. Floyd, "TCP Congestion + Window Validation", RFC 2861, June 2000. + + [RFC2865] Rigney, C., Willens, S., Rubens, A. and W. Simpson, "Remote + Authentication Dial In User Service (RADIUS)", RFC 2865, + June 2000. + + + +Aboba & Wood Standards Track [Page 26] + +RFC 3539 AAA Transport Profile June 2003 + + + [RFC2866] Rigney, C., "RADIUS Accounting", RFC 2866, June 2000. + + [RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, RFC + 2914, September 2000. + + [RFC2975] Aboba, B., Arkko, J. and D. Harrington, "Introduction to + Accounting Management", RFC 2975, June 2000. + + [RFC3390] Allman, M., Floyd, S. and C. Partridge, "Increasing TCP's + Initial Window", RFC 3390, October 2002. + + [Congest] Jacobson, V., "Congestion Avoidance and Control", Computer + Communication Review, vol. 18, no. 4, pp. 314-329, Aug. + 1988. ftp://ftp.ee.lbl.gov/papers/congavoid.ps.Z + + [Paxson] Paxson, V., "Measurement and Analysis of End-to-End + Internet Dynamics", Ph.D. Thesis, Computer Science + Division, University of California, Berkeley, April 1997. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Aboba & Wood Standards Track [Page 27] + +RFC 3539 AAA Transport Profile June 2003 + + +Appendix A - Detailed Watchdog Algorithm + + In this Appendix, the memory control structure that contains all + information regarding a specific peer is referred to as a Peer + Control Block, or PCB. The PCB contains the following fields: + + Status: + OKAY: The connection is up + SUSPECT: Failover has been initiated on the connection. + DOWN: Connection has been closed. + REOPEN: Attempting to reopen a closed connection + INITIAL: The initial state of the pcb when it is first created. + The pcb has never been opened. + + Variables: + Pending: Set to TRUE if there is an outstanding unanswered + watchdog request + Tw: Watchdog timer value + NumDWA: Number of DWAs received during REOPEN + + Tw is the watchdog timer, measured in seconds. Every second, Tw is + decremented. When it reaches 0, the OnTimerElapsed event (see below) + is invoked. Pseudo-code for the algorithm is included on the + following pages. + + SetWatchdog() + { + /* + SetWatchdog() is called whenever it is necessary + to reset the watchdog timer Tw. The value of the + watchdog timer is calculated based on the default + initial value TWINIT and a jitter ranging from + -2 to 2 seconds. The default for TWINIT is 30 seconds, + and MUST NOT be set lower than 6 seconds. + */ + Tw=TWINIT -2.0 + 4.0 * random() ; + SetTimer(Tw) ; + return ; + } + + /* + OnReceive() is called whenever a message + is received from the peer. This message MAY + be a request or an answer, and can include + DWR and DWA messages. Pending is assumed to + be a global variable. + */ + OnReceive(pcb, msgType) + + + +Aboba & Wood Standards Track [Page 28] + +RFC 3539 AAA Transport Profile June 2003 + + + { + if (msgType == DWA) { + Pending = FALSE; + } + switch (pcb->Status){ + case OKAY: + SetWatchdog(); + break; + case SUSPECT: + pcb->Status = OKAY; + Failback(pcb); + SetWatchdog(); + break; + case REOPEN: + if (msgType == DWA) { + NumDWA++; + if (NumDWA == 3) { + pcb->status = OKAY; + Failback(); + } + } else { + Throwaway(received packet); + } + break; + case INITIAL: + case DOWN: + Throwaway(received packet); + break; + default: + Error("Shouldn't be here!"); + break; + } + } + + /* + OnTimerElapsed() is called whenever Tw reaches zero (0). + */ + OnTimerElapsed(pcb) + { + switch (pcb->status){ + case OKAY: + if (!Pending) { + SendWatchdog(pcb); + SetWatchdog(); + Pending = TRUE; + break; + } + pcb->status = SUSPECT; + + + +Aboba & Wood Standards Track [Page 29] + +RFC 3539 AAA Transport Profile June 2003 + + + FailOver(pcb); + SetWatchdog(); + break ; + case SUSPECT: + pcb->status = DOWN; + CloseConnection(pcb); + SetWatchdog(); + break; + case INITIAL: + case DOWN: + AttemptOpen(pcb); + SetWatchdog(); + break; + case REOPEN: + if (!Pending) { + SendWatchdog(pbc); + SetWatchdog(); + Pending = TRUE; + break; + } + if (NumDWA < 0) { + pcb->status = DOWN; + CloseConnection(pcb); + } else { + NumDWA = -1; + } + SetWatchdog(); + break; + default: + error("Shouldn't be here!); + break; + } + } + + /* + OnConnectionUp() is called whenever a connection comes up + */ + OnConnectionUp(pcb) + { + switch (pcb->status){ + case INITIAL: + pcb->status = OKAY; + SetWatchdog(); + break; + case DOWN: + pcb->status = REOPEN; + NumDWA = 0; + SendWatchdog(pcb); + + + +Aboba & Wood Standards Track [Page 30] + +RFC 3539 AAA Transport Profile June 2003 + + + SetWatchdog(); + Pending = TRUE; + break; + default: + error("Shouldn't be here!); + break; + } + } + + /* + OnConnectionDown() is called whenever a connection goes down + */ + OnConnectionDown(pcb) + { + pcb->status = DOWN; + CloseConnection(); + switch (pcb->status){ + case OKAY: + Failover(pcb); + SetWatchdog(); + break; + case SUSPECT: + case REOPEN: + SetWatchdog(); + break; + default: + error("Shouldn't be here!); + break; + } + } + + /* Here is the state machine equivalent to the above code: + + STATE Event Actions New State + ===== ------ ------- ---------- + OKAY Receive DWA Pending = FALSE + SetWatchdog() OKAY + OKAY Receive non-DWA SetWatchdog() OKAY + SUSPECT Receive DWA Pending = FALSE + Failback() + SetWatchdog() OKAY + SUSPECT Receive non-DWA Failback() + SetWatchdog() OKAY + REOPEN Receive DWA & Pending = FALSE + NumDWA == 2 NumDWA++ + Failback() OKAY + REOPEN Receive DWA & Pending = FALSE + NumDWA < 2 NumDWA++ REOPEN + + + +Aboba & Wood Standards Track [Page 31] + +RFC 3539 AAA Transport Profile June 2003 + + + STATE Event Actions New State + ===== ------ ------- ---------- + REOPEN Receive non-DWA Throwaway() REOPEN + INITIAL Receive DWA Pending = FALSE + Throwaway() INITIAL + INITIAL Receive non-DWA Throwaway() INITIAL + DOWN Receive DWA Pending = FALSE + Throwaway() DOWN + DOWN Receive non-DWA Throwaway() DOWN + OKAY Timer expires & SendWatchdog() + !Pending SetWatchdog() + Pending = TRUE OKAY + OKAY Timer expires & Failover() + Pending SetWatchdog() SUSPECT + SUSPECT Timer expires CloseConnection() + SetWatchdog() DOWN + INITIAL Timer expires AttemptOpen() + SetWatchdog() INITIAL + DOWN Timer expires AttemptOpen() + SetWatchdog() DOWN + REOPEN Timer expires & SendWatchdog() + !Pending SetWatchdog() + Pending = TRUE REOPEN + REOPEN Timer expires & CloseConnection() + Pending & SetWatchdog() + NumDWA < 0 DOWN + REOPEN Timer expires & NumDWA = -1 + Pending & SetWatchdog() + NumDWA >= 0 REOPEN + INITIAL Connection up SetWatchdog() OKAY + DOWN Connection up NumDWA = 0 + SendWatchdog() + SetWatchdog() + Pending = TRUE REOPEN + OKAY Connection down CloseConnection() + Failover() + SetWatchdog() DOWN + SUSPECT Connection down CloseConnection() + SetWatchdog() DOWN + REOPEN Connection down CloseConnection() + SetWatchdog() DOWN + */ + + + + + + + + + +Aboba & Wood Standards Track [Page 32] + +RFC 3539 AAA Transport Profile June 2003 + + +Appendix B - AAA Agents + + As described in [RFC2865] and [RFC2607], AAA agents have become + popular in order to support services such as roaming and shared use + networks. Such agents are used both for + authentication/authorization, as well as accounting [RFC2975]. + + AAA agents include: + + Relays + Proxies + Re-directs + Store and Forward proxies + Transport layer proxies + + The transport layer behavior of each of these agents is described + below. + +B.1 Relays and Proxies + + While the application-layer behavior of relays and proxies are + different, at the transport layer the behavior is similar. In both + cases, two connections are established: one from the AAA client (NAS) + to the relay/proxy, and another from the relay/proxy to the AAA + server. The relay/proxy does not respond to a client request until + it receives a response from the server. Since the two connections + are de-coupled, the end-to-end conversation between the client and + server may not self clock. + + Since AAA transport is typically application-driven, there is + frequently not enough traffic to enable ACK piggybacking. As a + result, the Nagle algorithm is rarely triggered, and delayed ACKs may + comprise nearly half the traffic. Thus AAA protocols running over + reliable transport will see packet traffic nearly double that + experienced with UDP transport. Since ACK parameters (such as the + value of the delayed ACK timer) are typically fixed by the TCP + implementation and are not tunable by the application, there is + little that can be done about this. + + + + + + + + + + + + + +Aboba & Wood Standards Track [Page 33] + +RFC 3539 AAA Transport Profile June 2003 + + + A typical trace of a conversation between a NAS, proxy and server is + shown below: + + Time NAS Relay/Proxy Server + ------ --- ----------- ------ + + 0 Request + -------> + OTTnp + Tpr Request + -------> + + OTTnp + TdA Delayed ACK + <------- + + OTTnp + OTTps + Reply/ACK + Tpr + Tsr <------- + + OTTnp + OTTps + + Tpr + Tsr + Reply + OTTsp + TpR <------- + + OTTnp + OTTps + + Tpr + Tsr + Delayed ACK + OTTsp + TdA -------> + + OTTnp + OTTps + + OTTsp + OTTpn + + Tpr + Tsr + Delayed ACK + TpR + TdA -------> + + Key + --- + OTT = One-way Trip Time + OTTnp = One-way trip time (NAS to Relay/Proxy) + OTTpn = One-way trip time (Relay/Proxy to NAS) + OTTps = One-way trip time (Relay/Proxy to Server) + OTTsp = One-way trip time (Server to Relay/Proxy) + TdA = Delayed ACK timer + Tpr = Relay/Proxy request processing time + TpR = Relay/Proxy reply processing time + Tsr = Server request processing time + + At time 0, the NAS sends a request to the relay/proxy. Ignoring the + serialization time, the request arrives at the relay/proxy at time + OTTnp, and the relay/proxy takes an additional Tpr in order to + forward the request toward the home server. At time TdA after + + + + + +Aboba & Wood Standards Track [Page 34] + +RFC 3539 AAA Transport Profile June 2003 + + + receiving the request, the relay/proxy sends a delayed ACK. The + delayed ACK is sent, rather than being piggybacked on the reply, as + long as TdA < OTTps + OTTsp + Tpr + Tsr + TpR. + + Typically Tpr < TdA, so that the delayed ACK is sent after the + relay/proxy forwards the request toward the server, but before the + relay/proxy receives the reply from the server. However, depending + on the TCP implementation on the relay/proxy and when the request is + received, it is also possible for the delayed ACK to be sent prior to + forwarding the request. + + At time OTTnp + OTTps + Tpr, the server receives the request, and Tsr + later, it generates the reply. Where Tsr < TdA, the reply will + contain a piggybacked ACK. However, depending on the server + responsiveness and TCP implementation, the ACK and reply may be sent + separately. This can occur, for example, where a slow database or + storage system must be accessed prior to sending the reply. + + At time OTTnp + OTTps + OTTsp + Tpr + Tsr the reply/ACK reaches the + relay/proxy, which then takes TpR additional time to forward the + reply to the NAS. At TdA after receiving the reply, the relay/proxy + generates a delayed ACK. Typically TpR < TdA so that the delayed ACK + is sent to the server after the relay/proxy forwards the reply to the + NAS. However, depending on the circumstances and the relay/proxy TCP + implementation, the delayed ACK may be sent first. + + As with a delayed ACK sent in response to a request, which may be + piggybacked if the reply can be received quickly enough, piggybacking + of the ACK sent in response to a reply from the server is only + possible if additional request traffic is available. However, due to + the high inter-packet spacings in typical AAA scenarios, this is + unlikely unless the AAA protocol supports a reply ACK. + + At time OTTnp + OTTps + OTTsp + OTTpn + Tpr + Tsr + TpR the NAS + receives the reply. TdA later, a delayed ACK is generated. + +B.2 Re-directs + + Re-directs operate by referring a NAS to the AAA server, enabling the + NAS to talk to the AAA server directly. Since a direct transport + connection is established, the end-to-end connection will self-clock. + + With re-directs, delayed ACKs are less frequent than with + application-layer proxies since the Re-direct and Server will + typically piggyback replies with ACKs. + + + + + + +Aboba & Wood Standards Track [Page 35] + +RFC 3539 AAA Transport Profile June 2003 + + + The sequence of events is as follows: + + Time NAS Re-direct Server + ------ --- --------- ------ + + 0 Request + -------> + OTTnp + Tpr Redirect/ACK + <------- + + OTTnp + Tpr + Request + OTTpn + Tnr -------> + + OTTnp + OTTpn + + Tpr + Tsr + Reply/ACK + OTTns <------- + + OTTnp + OTTpn + + OTTns + OTTsn + + Tpr + Tsr + Delayed ACK + TdA -------> + + Key + --- + OTT = One-way Trip Time + OTTnp = One-way trip time (NAS to Re-direct) + OTTpn = One-way trip time (Re-direct to NAS) + OTTns = One-way trip time (NAS to Server) + OTTsn = One-way trip time (Server to NAS) + TdA = Delayed ACK timer + Tpr = Re-direct processing time + Tnr = NAS re-direct processing time + Tsr = Server request processing time + +B.3 Store and Forward Proxies + + With a store and forward proxy, the proxy may send a reply to the NAS + prior to forwarding the request to the server. While store and + forward proxies are most frequently deployed for accounting + [RFC2975], they also can be used to implement + authentication/authorization policy, as described in [RFC2607]. + + As noted in [RFC2975], store and forward proxies can have a negative + effect on accounting reliability. By sending a reply to the NAS + without receiving one from the accounting server, store and forward + proxies fool the NAS into thinking that the accounting request had + been accepted by the accounting server when this is not the case. As + a result, the NAS can delete the accounting packet from non-volatile + + + +Aboba & Wood Standards Track [Page 36] + +RFC 3539 AAA Transport Profile June 2003 + + + storage before it has been accepted by the accounting server. That + leaves the proxy responsible for delivering accounting packets. If + the proxy involves moving parts (e.g. a disk drive) while the NAS + does not, overall system reliability can be reduced. As a result, + store and forward proxies SHOULD NOT be used. + + The sequence of events is as follows: + + Time NAS Proxy Server + ------ --- ----- ------ + + 0 Request + -------> + OTTnp + TpR Reply/ACK + <------- + + OTTnp + Tpr Request + -------> + + OTTnp + OTTph + Reply/ACK + Tpr + Tsr <------- + + OTTnp + OTTph + + Tpr + Tsr + Reply + OTThp + TpR <------- + + OTTnp + OTTph + + Tpr + Tsr + Delayed ACK + OTThp + TdA -------> + + OTTnp + OTTph + + OTThp + OTTpn + + Tpr + Tsr + Delayed ACK + TpR + TdA -------> + + Key + --- + OTT = One-way Trip Time + OTTnp = One-way trip time (NAS to Proxy) + OTTpn = One-way trip time (Proxy to NAS) + OTTph = One-way trip time (Proxy to Home server) + OTThp = One-way trip time (Home Server to Proxy) + TdA = Delayed ACK timer + Tpr = Proxy request processing time + TpR = Proxy reply processing time + Tsr = Server request processing time + + + + + +Aboba & Wood Standards Track [Page 37] + +RFC 3539 AAA Transport Profile June 2003 + + +B.4 Transport Layer Proxies + + In addition to acting as proxies at the application layer, transport + layer proxies forward transport ACKs between the AAA client and + server. This splices together the client-proxy and proxy-server + connections into a single connection that behaves as though it + operates end-to-end, exhibiting self-clocking. However, since + transport proxies operate at the transport layer, they cannot be + implemented purely as applications and they are rarely deployed. + + With a transport proxy, the sequence of events is as follows: + + Time NAS Proxy Home Server + ------ --- ----- ----------- + + 0 Request + -------> + OTTnp + Tpr Request + -------> + + OTTnp + OTTph + Reply/ACK + Tpr + Tsr <------- + + OTTnp + OTTph + + Tpr + Tsr + Reply/ACK + OTThp + TpR <------- + + OTTnp + OTTph + + OTThp + OTTpn + + Tpr + Tsr + Delayed ACK + TpR + TdA -------> + + + OTTnp + OTTph + + OTThp + OTTpn + + Tpr + Tsr + Delayed ACK + TpR + TpD -------> + + Key + --- + OTT = One-way Trip Time + OTTnp = One-way trip time (NAS to Proxy) + OTTpn = One-way trip time (Proxy to NAS) + OTTph = One-way trip time (Proxy to Home server) + OTThp = One-way trip time (Home Server to Proxy) + TdA = Delayed ACK timer + Tpr = Proxy request processing time + TpR = Proxy reply processing time + + + +Aboba & Wood Standards Track [Page 38] + +RFC 3539 AAA Transport Profile June 2003 + + + Tsr = Server request processing time + TpD = Proxy delayed ack processing time + +Intellectual Property Statement + + The IETF takes no position regarding the validity or scope of any + intellectual property or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; neither does it represent that it + has made any effort to identify any such rights. Information on the + IETF's procedures with respect to rights in standards-track and + standards-related documentation can be found in BCP-11. Copies of + claims of rights made available for publication and any assurances of + licenses to be made available, or the result of an attempt made to + obtain a general license or permission for the use of such + proprietary rights by implementors or users of this specification can + be obtained from the IETF Secretariat. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights which may cover technology that may be required to practice + this standard. Please address the information to the IETF Executive + Director. + +Acknowledgments + + Thanks to Allison Mankin of AT&T, Barney Wolff of Databus, Steve Rich + of Cisco, Randy Bush of AT&T, Bo Landarv of IP Unplugged, Jari Arkko + of Ericsson, and Pat Calhoun of Blackstorm Networks for fruitful + discussions relating to AAA transport. + + + + + + + + + + + + + + + + + + + + +Aboba & Wood Standards Track [Page 39] + +RFC 3539 AAA Transport Profile June 2003 + + +Authors' Addresses + + Bernard Aboba + Microsoft Corporation + One Microsoft Way + Redmond, WA 98052 + + Phone: +1 425 706 6605 + Fax: +1 425 936 7329 + EMail: [email protected] + + + Jonathan Wood + Sun Microsystems, Inc. + 901 San Antonio Road + Palo Alto, CA 94303 + + EMail: [email protected] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Aboba & Wood Standards Track [Page 40] + +RFC 3539 AAA Transport Profile June 2003 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2003). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Aboba & Wood Standards Track [Page 41] + diff --git a/lib/diameter/doc/standard/rfc3588.txt b/lib/diameter/doc/standard/rfc3588.txt new file mode 100644 index 0000000000..fe4ff08c81 --- /dev/null +++ b/lib/diameter/doc/standard/rfc3588.txt @@ -0,0 +1,8235 @@ + + + + + + +Network Working Group P. Calhoun +Request for Comments: 3588 Airespace, Inc. +Category: Standards Track J. Loughney + Nokia + E. Guttman + Sun Microsystems, Inc. + G. Zorn + Cisco Systems, Inc. + J. Arkko + Ericsson + September 2003 + + + Diameter Base Protocol + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2003). All Rights Reserved. + +Abstract + + The Diameter base protocol is intended to provide an Authentication, + Authorization and Accounting (AAA) framework for applications such as + network access or IP mobility. Diameter is also intended to work in + both local Authentication, Authorization & Accounting and roaming + situations. This document specifies the message format, transport, + error reporting, accounting and security services to be used by all + Diameter applications. The Diameter base application needs to be + supported by all Diameter implementations. + +Conventions Used In This Document + + 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 BCP 14, RFC 2119 + [KEYWORD]. + + + + + + + +Calhoun, et al. Standards Track [Page 1] + +RFC 3588 Diameter Based Protocol September 2003 + + +Table of Contents + + 1. Introduction................................................. 6 + 1.1. Diameter Protocol..................................... 9 + 1.1.1. Description of the Document Set.............. 10 + 1.2. Approach to Extensibility............................. 11 + 1.2.1. Defining New AVP Values...................... 11 + 1.2.2. Creating New AVPs............................ 11 + 1.2.3. Creating New Authentication Applications..... 11 + 1.2.4. Creating New Accounting Applications......... 12 + 1.2.5. Application Authentication Procedures........ 14 + 1.3. Terminology........................................... 14 + 2. Protocol Overview............................................ 18 + 2.1. Transport............................................. 20 + 2.1.1. SCTP Guidelines.............................. 21 + 2.2. Securing Diameter Messages............................ 21 + 2.3. Diameter Application Compliance....................... 21 + 2.4. Application Identifiers............................... 22 + 2.5. Connections vs. Sessions.............................. 22 + 2.6. Peer Table............................................ 23 + 2.7. Realm-Based Routing Table............................. 24 + 2.8. Role of Diameter Agents............................... 25 + 2.8.1. Relay Agents................................. 26 + 2.8.2. Proxy Agents................................. 27 + 2.8.3. Redirect Agents.............................. 28 + 2.8.4. Translation Agents........................... 29 + 2.9. End-to-End Security Framework......................... 30 + 2.10. Diameter Path Authorization........................... 30 + 3. Diameter Header.............................................. 32 + 3.1. Command Codes......................................... 35 + 3.2. Command Code ABNF specification....................... 36 + 3.3. Diameter Command Naming Conventions................... 38 + 4. Diameter AVPs................................................ 38 + 4.1. AVP Header............................................ 39 + 4.1.1. Optional Header Elements..................... 41 + 4.2. Basic AVP Data Formats................................ 41 + 4.3. Derived AVP Data Formats.............................. 42 + 4.4. Grouped AVP Values.................................... 49 + 4.4.1. Example AVP with a Grouped Data Type......... 50 + 4.5. Diameter Base Protocol AVPs........................... 53 + 5. Diameter Peers............................................... 56 + 5.1. Peer Connections...................................... 56 + 5.2. Diameter Peer Discovery............................... 56 + 5.3. Capabilities Exchange................................. 59 + 5.3.1. Capabilities-Exchange-Request................ 60 + 5.3.2. Capabilities-Exchange-Answer................. 60 + 5.3.3. Vendor-Id AVP................................ 61 + 5.3.4. Firmware-Revision AVP........................ 61 + + + +Calhoun, et al. Standards Track [Page 2] + +RFC 3588 Diameter Based Protocol September 2003 + + + 5.3.5. Host-IP-Address AVP.......................... 62 + 5.3.6. Supported-Vendor-Id AVP...................... 62 + 5.3.7. Product-Name AVP............................. 62 + 5.4. Disconnecting Peer Connections........................ 62 + 5.4.1. Disconnect-Peer-Request...................... 63 + 5.4.2. Disconnect-Peer-Answer....................... 63 + 5.4.3. Disconnect-Cause AVP......................... 63 + 5.5. Transport Failure Detection........................... 64 + 5.5.1. Device-Watchdog-Request...................... 64 + 5.5.2. Device-Watchdog-Answer....................... 64 + 5.5.3. Transport Failure Algorithm.................. 65 + 5.5.4. Failover and Failback Procedures............. 65 + 5.6. Peer State Machine.................................... 66 + 5.6.1. Incoming connections......................... 68 + 5.6.2. Events....................................... 69 + 5.6.3. Actions...................................... 70 + 5.6.4. The Election Process......................... 71 + 6. Diameter Message Processing.................................. 71 + 6.1. Diameter Request Routing Overview..................... 71 + 6.1.1. Originating a Request........................ 73 + 6.1.2. Sending a Request............................ 73 + 6.1.3. Receiving Requests........................... 73 + 6.1.4. Processing Local Requests.................... 73 + 6.1.5. Request Forwarding........................... 74 + 6.1.6. Request Routing.............................. 74 + 6.1.7. Redirecting Requests......................... 74 + 6.1.8. Relaying and Proxying Requests............... 75 + 6.2. Diameter Answer Processing............................ 76 + 6.2.1. Processing Received Answers.................. 77 + 6.2.2. Relaying and Proxying Answers................ 77 + 6.3. Origin-Host AVP....................................... 77 + 6.4. Origin-Realm AVP...................................... 78 + 6.5. Destination-Host AVP.................................. 78 + 6.6. Destination-Realm AVP................................. 78 + 6.7. Routing AVPs.......................................... 78 + 6.7.1. Route-Record AVP............................. 79 + 6.7.2. Proxy-Info AVP............................... 79 + 6.7.3. Proxy-Host AVP............................... 79 + 6.7.4. Proxy-State AVP.............................. 79 + 6.8. Auth-Application-Id AVP............................... 79 + 6.9. Acct-Application-Id AVP............................... 79 + 6.10. Inband-Security-Id AVP................................ 79 + 6.11. Vendor-Specific-Application-Id AVP.................... 80 + 6.12. Redirect-Host AVP..................................... 80 + 6.13. Redirect-Host-Usage AVP............................... 80 + 6.14. Redirect-Max-Cache-Time AVP........................... 81 + 6.15. E2E-Sequence AVP...................................... 82 + + + + +Calhoun, et al. Standards Track [Page 3] + +RFC 3588 Diameter Based Protocol September 2003 + + + 7. Error Handling............................................... 82 + 7.1. Result-Code AVP....................................... 84 + 7.1.1. Informational................................ 84 + 7.1.2. Success...................................... 84 + 7.1.3. Protocol Errors.............................. 85 + 7.1.4. Transient Failures........................... 86 + 7.1.5. Permanent Failures........................... 86 + 7.2. Error Bit............................................. 88 + 7.3. Error-Message AVP..................................... 89 + 7.4. Error-Reporting-Host AVP.............................. 89 + 7.5. Failed-AVP AVP........................................ 89 + 7.6. Experimental-Result AVP............................... 90 + 7.7. Experimental-Result-Code AVP.......................... 90 + 8. Diameter User Sessions....................................... 90 + 8.1. Authorization Session State Machine................... 92 + 8.2. Accounting Session State Machine...................... 96 + 8.3. Server-Initiated Re-Auth.............................. 101 + 8.3.1. Re-Auth-Request.............................. 102 + 8.3.2. Re-Auth-Answer............................... 102 + 8.4. Session Termination................................... 103 + 8.4.1. Session-Termination-Request.................. 104 + 8.4.2. Session-Termination-Answer................... 105 + 8.5. Aborting a Session.................................... 105 + 8.5.1. Abort-Session-Request........................ 106 + 8.5.2. Abort-Session-Answer......................... 106 + 8.6. Inferring Session Termination from Origin-State-Id.... 107 + 8.7. Auth-Request-Type AVP................................. 108 + 8.8. Session-Id AVP........................................ 108 + 8.9. Authorization-Lifetime AVP............................ 109 + 8.10. Auth-Grace-Period AVP................................. 110 + 8.11. Auth-Session-State AVP................................ 110 + 8.12. Re-Auth-Request-Type AVP.............................. 110 + 8.13. Session-Timeout AVP................................... 111 + 8.14. User-Name AVP......................................... 111 + 8.15. Termination-Cause AVP................................. 111 + 8.16. Origin-State-Id AVP................................... 112 + 8.17. Session-Binding AVP................................... 113 + 8.18. Session-Server-Failover AVP........................... 113 + 8.19. Multi-Round-Time-Out AVP.............................. 114 + 8.20. Class AVP............................................. 114 + 8.21. Event-Timestamp AVP................................... 115 + 9. Accounting................................................... 115 + 9.1. Server Directed Model................................. 115 + 9.2. Protocol Messages..................................... 116 + 9.3. Application Document Requirements..................... 116 + 9.4. Fault Resilience...................................... 116 + 9.5. Accounting Records.................................... 117 + 9.6. Correlation of Accounting Records..................... 118 + + + +Calhoun, et al. Standards Track [Page 4] + +RFC 3588 Diameter Based Protocol September 2003 + + + 9.7. Accounting Command-Codes.............................. 119 + 9.7.1. Accounting-Request........................... 119 + 9.7.2. Accounting-Answer............................ 120 + 9.8. Accounting AVPs....................................... 121 + 9.8.1. Accounting-Record-Type AVP................... 121 + 9.8.2. Acct-Interim-Interval AVP.................... 122 + 9.8.3. Accounting-Record-Number AVP................. 123 + 9.8.4. Acct-Session-Id AVP.......................... 123 + 9.8.5. Acct-Multi-Session-Id AVP.................... 123 + 9.8.6. Accounting-Sub-Session-Id AVP................ 123 + 9.8.7. Accounting-Realtime-Required AVP............. 123 + 10. AVP Occurrence Table......................................... 124 + 10.1. Base Protocol Command AVP Table....................... 124 + 10.2. Accounting AVP Table.................................. 126 + 11. IANA Considerations.......................................... 127 + 11.1. AVP Header............................................ 127 + 11.1.1. AVP Code..................................... 127 + 11.1.2. AVP Flags.................................... 128 + 11.2. Diameter Header....................................... 128 + 11.2.1. Command Codes................................ 128 + 11.2.2. Command Flags................................ 129 + 11.3. Application Identifiers............................... 129 + 11.4. AVP Values............................................ 129 + 11.4.1. Result-Code AVP Values....................... 129 + 11.4.2. Accounting-Record-Type AVP Values............ 130 + 11.4.3. Termination-Cause AVP Values................. 130 + 11.4.4. Redirect-Host-Usage AVP Values............... 130 + 11.4.5. Session-Server-Failover AVP Values........... 130 + 11.4.6. Session-Binding AVP Values................... 130 + 11.4.7. Disconnect-Cause AVP Values.................. 130 + 11.4.8. Auth-Request-Type AVP Values................. 130 + 11.4.9. Auth-Session-State AVP Values................ 130 + 11.4.10. Re-Auth-Request-Type AVP Values.............. 131 + 11.4.11. Accounting-Realtime-Required AVP Values...... 131 + 11.5. Diameter TCP/SCTP Port Numbers........................ 131 + 11.6. NAPTR Service Fields.................................. 131 + 12. Diameter Protocol Related Configurable Parameters............ 131 + 13. Security Considerations...................................... 132 + 13.1. IPsec Usage........................................... 133 + 13.2. TLS Usage............................................. 134 + 13.3. Peer-to-Peer Considerations........................... 134 + 14. References................................................... 136 + 14.1. Normative References.................................. 136 + 14.2. Informative References................................ 138 + 15. Acknowledgements............................................. 140 + Appendix A. Diameter Service Template........................... 141 + Appendix B. NAPTR Example....................................... 142 + Appendix C. Duplicate Detection................................. 143 + + + +Calhoun, et al. Standards Track [Page 5] + +RFC 3588 Diameter Based Protocol September 2003 + + + Appendix D. Intellectual Property Statement..................... 145 + Authors' Addresses............................................... 146 + Full Copyright Statement......................................... 147 + +1. Introduction + + Authentication, Authorization and Accounting (AAA) protocols such as + TACACS [TACACS] and RADIUS [RADIUS] were initially deployed to + provide dial-up PPP [PPP] and terminal server access. Over time, + with the growth of the Internet and the introduction of new access + technologies, including wireless, DSL, Mobile IP and Ethernet, + routers and network access servers (NAS) have increased in complexity + and density, putting new demands on AAA protocols. + + Network access requirements for AAA protocols are summarized in + [AAAREQ]. These include: + + Failover + [RADIUS] does not define failover mechanisms, and as a result, + failover behavior differs between implementations. In order to + provide well defined failover behavior, Diameter supports + application-layer acknowledgements, and defines failover + algorithms and the associated state machine. This is described in + Section 5.5 and [AAATRANS]. + + Transmission-level security + [RADIUS] defines an application-layer authentication and integrity + scheme that is required only for use with Response packets. While + [RADEXT] defines an additional authentication and integrity + mechanism, use is only required during Extensible Authentication + Protocol (EAP) sessions. While attribute-hiding is supported, + [RADIUS] does not provide support for per-packet confidentiality. + In accounting, [RADACCT] assumes that replay protection is + provided by the backend billing server, rather than within the + protocol itself. + + While [RFC3162] defines the use of IPsec with RADIUS, support for + IPsec is not required. Since within [IKE] authentication occurs + only within Phase 1 prior to the establishment of IPsec SAs in + Phase 2, it is typically not possible to define separate trust or + authorization schemes for each application. This limits the + usefulness of IPsec in inter-domain AAA applications (such as + roaming) where it may be desirable to define a distinct + certificate hierarchy for use in a AAA deployment. In order to + provide universal support for transmission-level security, and + enable both intra- and inter-domain AAA deployments, IPsec support + is mandatory in Diameter, and TLS support is optional. Security + is discussed in Section 13. + + + +Calhoun, et al. Standards Track [Page 6] + +RFC 3588 Diameter Based Protocol September 2003 + + + Reliable transport + RADIUS runs over UDP, and does not define retransmission behavior; + as a result, reliability varies between implementations. As + described in [ACCMGMT], this is a major issue in accounting, where + packet loss may translate directly into revenue loss. In order to + provide well defined transport behavior, Diameter runs over + reliable transport mechanisms (TCP, SCTP) as defined in + [AAATRANS]. + + Agent support + [RADIUS] does not provide for explicit support for agents, + including Proxies, Redirects and Relays. Since the expected + behavior is not defined, it varies between implementations. + Diameter defines agent behavior explicitly; this is described in + Section 2.8. + + Server-initiated messages + While RADIUS server-initiated messages are defined in [DYNAUTH], + support is optional. This makes it difficult to implement + features such as unsolicited disconnect or + reauthentication/reauthorization on demand across a heterogeneous + deployment. Support for server-initiated messages is mandatory in + Diameter, and is described in Section 8. + + Auditability + RADIUS does not define data-object security mechanisms, and as a + result, untrusted proxies may modify attributes or even packet + headers without being detected. Combined with lack of support for + capabilities negotiation, this makes it very difficult to + determine what occurred in the event of a dispute. While + implementation of data object security is not mandatory within + Diameter, these capabilities are supported, and are described in + [AAACMS]. + + Transition support + While Diameter does not share a common protocol data unit (PDU) + with RADIUS, considerable effort has been expended in enabling + backward compatibility with RADIUS, so that the two protocols may + be deployed in the same network. Initially, it is expected that + Diameter will be deployed within new network devices, as well as + within gateways enabling communication between legacy RADIUS + devices and Diameter agents. This capability, described in + [NASREQ], enables Diameter support to be added to legacy networks, + by addition of a gateway or server speaking both RADIUS and + Diameter. + + + + + + +Calhoun, et al. Standards Track [Page 7] + +RFC 3588 Diameter Based Protocol September 2003 + + + In addition to addressing the above requirements, Diameter also + provides support for the following: + + Capability negotiation + RADIUS does not support error messages, capability negotiation, or + a mandatory/non-mandatory flag for attributes. Since RADIUS + clients and servers are not aware of each other's capabilities, + they may not be able to successfully negotiate a mutually + acceptable service, or in some cases, even be aware of what + service has been implemented. Diameter includes support for error + handling (Section 7), capability negotiation (Section 5.3), and + mandatory/non-mandatory attribute-value pairs (AVPs) (Section + 4.1). + + Peer discovery and configuration + RADIUS implementations typically require that the name or address + of servers or clients be manually configured, along with the + corresponding shared secrets. This results in a large + administrative burden, and creates the temptation to reuse the + RADIUS shared secret, which can result in major security + vulnerabilities if the Request Authenticator is not globally and + temporally unique as required in [RADIUS]. Through DNS, Diameter + enables dynamic discovery of peers. Derivation of dynamic session + keys is enabled via transmission-level security. + + Roaming support + The ROAMOPS WG provided a survey of roaming implementations + [ROAMREV], detailed roaming requirements [ROAMCRIT], defined the + Network Access Identifier (NAI) [NAI], and documented existing + implementations (and imitations) of RADIUS-based roaming + [PROXYCHAIN]. In order to improve scalability, [PROXYCHAIN] + introduced the concept of proxy chaining via an intermediate + server, facilitating roaming between providers. However, since + RADIUS does not provide explicit support for proxies, and lacks + auditability and transmission-level security features, RADIUS- + based roaming is vulnerable to attack from external parties as + well as susceptible to fraud perpetrated by the roaming partners + themselves. As a result, it is not suitable for wide-scale + deployment on the Internet [PROXYCHAIN]. By providing explicit + support for inter-domain roaming and message routing (Sections 2.7 + and 6), auditability [AAACMS], and transmission-layer security + (Section 13) features, Diameter addresses these limitations and + provides for secure and scalable roaming. + + In the decade since AAA protocols were first introduced, the + capabilities of Network Access Server (NAS) devices have increased + substantially. As a result, while Diameter is a considerably more + sophisticated protocol than RADIUS, it remains feasible to implement + + + +Calhoun, et al. Standards Track [Page 8] + +RFC 3588 Diameter Based Protocol September 2003 + + + within embedded devices, given improvements in processor speeds and + the widespread availability of embedded IPsec and TLS + implementations. + +1.1. Diameter Protocol + + The Diameter base protocol provides the following facilities: + + - Delivery of AVPs (attribute value pairs) + - Capabilities negotiation + - Error notification + - Extensibility, through addition of new commands and AVPs (required + in [AAAREQ]). + - Basic services necessary for applications, such as handling of + user sessions or accounting + + All data delivered by the protocol is in the form of an AVP. Some of + these AVP values are used by the Diameter protocol itself, while + others deliver data associated with particular applications that + employ Diameter. AVPs may be added arbitrarily to Diameter messages, + so long as the required AVPs are included and AVPs that are + explicitly excluded are not included. AVPs are used by the base + Diameter protocol to support the following required features: + + - Transporting of user authentication information, for the purposes + of enabling the Diameter server to authenticate the user. + + - Transporting of service specific authorization information, + between client and servers, allowing the peers to decide whether a + user's access request should be granted. + + - Exchanging resource usage information, which MAY be used for + accounting purposes, capacity planning, etc. + + - Relaying, proxying and redirecting of Diameter messages through a + server hierarchy. + + The Diameter base protocol provides the minimum requirements needed + for a AAA protocol, as required by [AAAREQ]. The base protocol may + be used by itself for accounting purposes only, or it may be used + with a Diameter application, such as Mobile IPv4 [DIAMMIP], or + network access [NASREQ]. It is also possible for the base protocol + to be extended for use in new applications, via the addition of new + commands or AVPs. At this time the focus of Diameter is network + access and accounting applications. A truly generic AAA protocol + used by many applications might provide functionality not provided by + Diameter. Therefore, it is imperative that the designers of new + applications understand their requirements before using Diameter. + + + +Calhoun, et al. Standards Track [Page 9] + +RFC 3588 Diameter Based Protocol September 2003 + + + See Section 2.4 for more information on Diameter applications. + + Any node can initiate a request. In that sense, Diameter is a peer- + to-peer protocol. In this document, a Diameter Client is a device at + the edge of the network that performs access control, such as a + Network Access Server (NAS) or a Foreign Agent (FA). A Diameter + client generates Diameter messages to request authentication, + authorization, and accounting services for the user. A Diameter + agent is a node that does not authenticate and/or authorize messages + locally; agents include proxies, redirects and relay agents. A + Diameter server performs authentication and/or authorization of the + user. A Diameter node MAY act as an agent for certain requests while + acting as a server for others. + + The Diameter protocol also supports server-initiated messages, such + as a request to abort service to a particular user. + +1.1.1. Description of the Document Set + + Currently, the Diameter specification consists of a base + specification (this document), Transport Profile [AAATRANS] and + applications: Mobile IPv4 [DIAMMIP], and NASREQ [NASREQ]. + + The Transport Profile document [AAATRANS] discusses transport layer + issues that arise with AAA protocols and recommendations on how to + overcome these issues. This document also defines the Diameter + failover algorithm and state machine. + + The Mobile IPv4 [DIAMMIP] application defines a Diameter application + that allows a Diameter server to perform AAA functions for Mobile + IPv4 services to a mobile node. + + The NASREQ [NASREQ] application defines a Diameter Application that + allows a Diameter server to be used in a PPP/SLIP Dial-Up and + Terminal Server Access environment. Consideration was given for + servers that need to perform protocol conversion between Diameter and + RADIUS. + + In summary, this document defines the base protocol specification for + AAA, which includes support for accounting. The Mobile IPv4 and the + NASREQ documents describe applications that use this base + specification for Authentication, Authorization and Accounting. + + + + + + + + + +Calhoun, et al. Standards Track [Page 10] + +RFC 3588 Diameter Based Protocol September 2003 + + +1.2. Approach to Extensibility + + The Diameter protocol is designed to be extensible, using several + mechanisms, including: + + - Defining new AVP values + - Creating new AVPs + - Creating new authentication/authorization applications + - Creating new accounting applications + - Application authentication procedures + + Reuse of existing AVP values, AVPs and Diameter applications are + strongly recommended. Reuse simplifies standardization and + implementation and avoids potential interoperability issues. It is + expected that command codes are reused; new command codes can only be + created by IETF Consensus (see Section 11.2.1). + +1.2.1. Defining New AVP Values + + New applications should attempt to reuse AVPs defined in existing + applications when possible, as opposed to creating new AVPs. For + AVPs of type Enumerated, an application may require a new value to + communicate some service-specific information. + + In order to allocate a new AVP value, a request MUST be sent to IANA + [IANA], along with an explanation of the new AVP value. IANA + considerations for Diameter are discussed in Section 11. + +1.2.2. Creating New AVPs + + When no existing AVP can be used, a new AVP should be created. The + new AVP being defined MUST use one of the data types listed in + Section 4.2. + + In the event that a logical grouping of AVPs is necessary, and + multiple "groups" are possible in a given command, it is recommended + that a Grouped AVP be used (see Section 4.4). + + In order to create a new AVP, a request MUST be sent to IANA, with a + specification for the AVP. The request MUST include the commands + that would make use of the AVP. + +1.2.3. Creating New Authentication Applications + + Every Diameter application specification MUST have an IANA assigned + Application Identifier (see Section 2.4) or a vendor specific + Application Identifier. + + + + +Calhoun, et al. Standards Track [Page 11] + +RFC 3588 Diameter Based Protocol September 2003 + + + Should a new Diameter usage scenario find itself unable to fit within + an existing application without requiring major changes to the + specification, it may be desirable to create a new Diameter + application. Major changes to an application include: + + - Adding new AVPs to the command, which have the "M" bit set. + + - Requiring a command that has a different number of round trips to + satisfy a request (e.g., application foo has a command that + requires one round trip, but new application bar has a command + that requires two round trips to complete). + + - Adding support for an authentication method requiring definition + of new AVPs for use with the application. Since a new EAP + authentication method can be supported within Diameter without + requiring new AVPs, addition of EAP methods does not require the + creation of a new authentication application. + + Creation of a new application should be viewed as a last resort. An + implementation MAY add arbitrary non-mandatory AVPs to any command + defined in an application, including vendor-specific AVPs without + needing to define a new application. Please refer to Section 11.1.1 + for details. + + In order to justify allocation of a new application identifier, + Diameter applications MUST define one Command Code, or add new + mandatory AVPs to the ABNF. + + The expected AVPs MUST be defined in an ABNF [ABNF] grammar (see + Section 3.2). If the Diameter application has accounting + requirements, it MUST also specify the AVPs that are to be present in + the Diameter Accounting messages (see Section 9.3). However, just + because a new authentication application id is required, does not + imply that a new accounting application id is required. + + When possible, a new Diameter application SHOULD reuse existing + Diameter AVPs, in order to avoid defining multiple AVPs that carry + similar information. + +1.2.4. Creating New Accounting Applications + + There are services that only require Diameter accounting. Such + services need to define the AVPs carried in the Accounting-Request + (ACR)/ Accounting-Answer (ACA) messages, but do not need to define + new command codes. An implementation MAY add arbitrary non-mandatory + AVPs (AVPs with the "M" bit not set) to any command defined in an + + + + + +Calhoun, et al. Standards Track [Page 12] + +RFC 3588 Diameter Based Protocol September 2003 + + + application, including vendor-specific AVPs, without needing to + define a new accounting application. Please refer to Section 11.1.1 + for details. + + Application Identifiers are still required for Diameter capability + exchange. Every Diameter accounting application specification MUST + have an IANA assigned Application Identifier (see Section 2.4) or a + vendor specific Application Identifier. + + Every Diameter implementation MUST support accounting. Basic + accounting support is sufficient to handle any application that uses + the ACR/ACA commands defined in this document, as long as no new + mandatory AVPs are added. A mandatory AVP is defined as one which + has the "M" bit set when sent within an accounting command, + regardless of whether it is required or optional within the ABNF for + the accounting application. + + The creation of a new accounting application should be viewed as a + last resort and MUST NOT be used unless a new command or additional + mechanisms (e.g., application defined state machine) is defined + within the application, or new mandatory AVPs are added to the ABNF. + + Within an accounting command, setting the "M" bit implies that a + backend server (e.g., billing server) or the accounting server itself + MUST understand the AVP in order to compute a correct bill. If the + AVP is not relevant to the billing process, when the AVP is included + within an accounting command, it MUST NOT have the "M" bit set, even + if the "M" bit is set when the same AVP is used within other Diameter + commands (i.e., authentication/authorization commands). + + A DIAMETER base accounting implementation MUST be configurable to + advertise supported accounting applications in order to prevent the + accounting server from accepting accounting requests for unbillable + services. The combination of the home domain and the accounting + application Id can be used in order to route the request to the + appropriate accounting server. + + When possible, a new Diameter accounting application SHOULD attempt + to reuse existing AVPs, in order to avoid defining multiple AVPs that + carry similar information. + + If the base accounting is used without any mandatory AVPs, new + commands or additional mechanisms (e.g., application defined state + machine), then the base protocol defined standard accounting + application Id (Section 2.4) MUST be used in ACR/ACA commands. + + + + + + +Calhoun, et al. Standards Track [Page 13] + +RFC 3588 Diameter Based Protocol September 2003 + + +1.2.5. Application Authentication Procedures + + When possible, applications SHOULD be designed such that new + authentication methods MAY be added without requiring changes to the + application. This MAY require that new AVP values be assigned to + represent the new authentication transform, or any other scheme that + produces similar results. When possible, authentication frameworks, + such as Extensible Authentication Protocol [EAP], SHOULD be used. + +1.3. Terminology + + AAA + Authentication, Authorization and Accounting. + + Accounting + The act of collecting information on resource usage for the + purpose of capacity planning, auditing, billing or cost + allocation. + + Accounting Record + An accounting record represents a summary of the resource + consumption of a user over the entire session. Accounting servers + creating the accounting record may do so by processing interim + accounting events or accounting events from several devices + serving the same user. + + Authentication + The act of verifying the identity of an entity (subject). + + Authorization + The act of determining whether a requesting entity (subject) will + be allowed access to a resource (object). + + AVP + The Diameter protocol consists of a header followed by one or more + Attribute-Value-Pairs (AVPs). An AVP includes a header and is + used to encapsulate protocol-specific data (e.g., routing + information) as well as authentication, authorization or + accounting information. + + Broker + A broker is a business term commonly used in AAA infrastructures. + A broker is either a relay, proxy or redirect agent, and MAY be + operated by roaming consortiums. Depending on the business model, + a broker may either choose to deploy relay agents or proxy + agents. + + + + + +Calhoun, et al. Standards Track [Page 14] + +RFC 3588 Diameter Based Protocol September 2003 + + + Diameter Agent + A Diameter Agent is a Diameter node that provides either relay, + proxy, redirect or translation services. + + Diameter Client + A Diameter Client is a device at the edge of the network that + performs access control. An example of a Diameter client is a + Network Access Server (NAS) or a Foreign Agent (FA). + + Diameter Node + A Diameter node is a host process that implements the Diameter + protocol, and acts either as a Client, Agent or Server. + + Diameter Peer + A Diameter Peer is a Diameter Node to which a given Diameter Node + has a direct transport connection. + + Diameter Security Exchange + A Diameter Security Exchange is a process through which two + Diameter nodes establish end-to-end security. + + Diameter Server + A Diameter Server is one that handles authentication, + authorization and accounting requests for a particular realm. By + its very nature, a Diameter Server MUST support Diameter + applications in addition to the base protocol. + + Downstream + Downstream is used to identify the direction of a particular + Diameter message from the home server towards the access device. + + End-to-End Security + TLS and IPsec provide hop-by-hop security, or security across a + transport connection. When relays or proxy are involved, this + hop-by-hop security does not protect the entire Diameter user + session. End-to-end security is security between two Diameter + nodes, possibly communicating through Diameter Agents. This + security protects the entire Diameter communications path from the + originating Diameter node to the terminating Diameter node. + + Home Realm + A Home Realm is the administrative domain with which the user + maintains an account relationship. + + Home Server + See Diameter Server. + + + + + +Calhoun, et al. Standards Track [Page 15] + +RFC 3588 Diameter Based Protocol September 2003 + + + Interim accounting + An interim accounting message provides a snapshot of usage during + a user's session. It is typically implemented in order to provide + for partial accounting of a user's session in the case of a device + reboot or other network problem prevents the reception of a + session summary message or session record. + + Local Realm + A local realm is the administrative domain providing services to a + user. An administrative domain MAY act as a local realm for + certain users, while being a home realm for others. + + Multi-session + A multi-session represents a logical linking of several sessions. + Multi-sessions are tracked by using the Acct-Multi-Session-Id. An + example of a multi-session would be a Multi-link PPP bundle. Each + leg of the bundle would be a session while the entire bundle would + be a multi-session. + + Network Access Identifier + The Network Access Identifier, or NAI [NAI], is used in the + Diameter protocol to extract a user's identity and realm. The + identity is used to identify the user during authentication and/or + authorization, while the realm is used for message routing + purposes. + + Proxy Agent or Proxy + In addition to forwarding requests and responses, proxies make + policy decisions relating to resource usage and provisioning. + This is typically accomplished by tracking the state of NAS + devices. While proxies typically do not respond to client + Requests prior to receiving a Response from the server, they may + originate Reject messages in cases where policies are violated. + As a result, proxies need to understand the semantics of the + messages passing through them, and may not support all Diameter + applications. + + Realm + The string in the NAI that immediately follows the '@' character. + NAI realm names are required to be unique, and are piggybacked on + the administration of the DNS namespace. Diameter makes use of + the realm, also loosely referred to as domain, to determine + whether messages can be satisfied locally, or whether they must be + routed or redirected. In RADIUS, realm names are not necessarily + piggybacked on the DNS namespace but may be independent of it. + + + + + + +Calhoun, et al. Standards Track [Page 16] + +RFC 3588 Diameter Based Protocol September 2003 + + + Real-time Accounting + Real-time accounting involves the processing of information on + resource usage within a defined time window. Time constraints are + typically imposed in order to limit financial risk. + + Relay Agent or Relay + Relays forward requests and responses based on routing-related + AVPs and realm routing table entries. Since relays do not make + policy decisions, they do not examine or alter non-routing AVPs. + As a result, relays never originate messages, do not need to + understand the semantics of messages or non-routing AVPs, and are + capable of handling any Diameter application or message type. + Since relays make decisions based on information in routing AVPs + and realm forwarding tables they do not keep state on NAS resource + usage or sessions in progress. + + Redirect Agent + Rather than forwarding requests and responses between clients and + servers, redirect agents refer clients to servers and allow them + to communicate directly. Since redirect agents do not sit in the + forwarding path, they do not alter any AVPs transiting between + client and server. Redirect agents do not originate messages and + are capable of handling any message type, although they may be + configured only to redirect messages of certain types, while + acting as relay or proxy agents for other types. As with proxy + agents, redirect agents do not keep state with respect to sessions + or NAS resources. + + Roaming Relationships + Roaming relationships include relationships between companies and + ISPs, relationships among peer ISPs within a roaming consortium, + and relationships between an ISP and a roaming consortium. + + Security Association + A security association is an association between two endpoints in + a Diameter session which allows the endpoints to communicate with + integrity and confidentially, even in the presence of relays + and/or proxies. + + Session + A session is a related progression of events devoted to a + particular activity. Each application SHOULD provide guidelines + as to when a session begins and ends. All Diameter packets with + the same Session-Identifier are considered to be part of the same + session. + + + + + + +Calhoun, et al. Standards Track [Page 17] + +RFC 3588 Diameter Based Protocol September 2003 + + + Session state + A stateful agent is one that maintains session state information, + by keeping track of all authorized active sessions. Each + authorized session is bound to a particular service, and its state + is considered active either until it is notified otherwise, or by + expiration. + + Sub-session + A sub-session represents a distinct service (e.g., QoS or data + characteristics) provided to a given session. These services may + happen concurrently (e.g., simultaneous voice and data transfer + during the same session) or serially. These changes in sessions + are tracked with the Accounting-Sub-Session-Id. + + Transaction state + The Diameter protocol requires that agents maintain transaction + state, which is used for failover purposes. Transaction state + implies that upon forwarding a request, the Hop-by-Hop identifier + is saved; the field is replaced with a locally unique identifier, + which is restored to its original value when the corresponding + answer is received. The request's state is released upon receipt + of the answer. A stateless agent is one that only maintains + transaction state. + + Translation Agent + A translation agent is a stateful Diameter node that performs + protocol translation between Diameter and another AAA protocol, + such as RADIUS. + + Transport Connection + A transport connection is a TCP or SCTP connection existing + directly between two Diameter peers, otherwise known as a Peer- + to-Peer Connection. + + Upstream + Upstream is used to identify the direction of a particular + Diameter message from the access device towards the home server. + + User + The entity requesting or using some resource, in support of which + a Diameter client has generated a request. + +2. Protocol Overview + + The base Diameter protocol may be used by itself for accounting + applications, but for use in authentication and authorization it is + always extended for a particular application. Two Diameter + applications are defined by companion documents: NASREQ [NASREQ], + + + +Calhoun, et al. Standards Track [Page 18] + +RFC 3588 Diameter Based Protocol September 2003 + + + Mobile IPv4 [DIAMMIP]. These applications are introduced in this + document but specified elsewhere. Additional Diameter applications + MAY be defined in the future (see Section 11.3). + + Diameter Clients MUST support the base protocol, which includes + accounting. In addition, they MUST fully support each Diameter + application that is needed to implement the client's service, e.g., + NASREQ and/or Mobile IPv4. A Diameter Client that does not support + both NASREQ and Mobile IPv4, MUST be referred to as "Diameter X + Client" where X is the application which it supports, and not a + "Diameter Client". + + Diameter Servers MUST support the base protocol, which includes + accounting. In addition, they MUST fully support each Diameter + application that is needed to implement the intended service, e.g., + NASREQ and/or Mobile IPv4. A Diameter Server that does not support + both NASREQ and Mobile IPv4, MUST be referred to as "Diameter X + Server" where X is the application which it supports, and not a + "Diameter Server". + + Diameter Relays and redirect agents are, by definition, protocol + transparent, and MUST transparently support the Diameter base + protocol, which includes accounting, and all Diameter applications. + + Diameter proxies MUST support the base protocol, which includes + accounting. In addition, they MUST fully support each Diameter + application that is needed to implement proxied services, e.g., + NASREQ and/or Mobile IPv4. A Diameter proxy which does not support + also both NASREQ and Mobile IPv4, MUST be referred to as "Diameter X + Proxy" where X is the application which it supports, and not a + "Diameter Proxy". + + The base Diameter protocol concerns itself with capabilities + negotiation, how messages are sent and how peers may eventually be + abandoned. The base protocol also defines certain rules that apply + to all exchanges of messages between Diameter nodes. + + Communication between Diameter peers begins with one peer sending a + message to another Diameter peer. The set of AVPs included in the + message is determined by a particular Diameter application. One AVP + that is included to reference a user's session is the Session-Id. + + The initial request for authentication and/or authorization of a user + would include the Session-Id. The Session-Id is then used in all + subsequent messages to identify the user's session (see Section 8 for + more information). The communicating party may accept the request, + or reject it by returning an answer message with the Result-Code AVP + + + + +Calhoun, et al. Standards Track [Page 19] + +RFC 3588 Diameter Based Protocol September 2003 + + + set to indicate an error occurred. The specific behavior of the + Diameter server or client receiving a request depends on the Diameter + application employed. + + Session state (associated with a Session-Id) MUST be freed upon + receipt of the Session-Termination-Request, Session-Termination- + Answer, expiration of authorized service time in the Session-Timeout + AVP, and according to rules established in a particular Diameter + application. + +2.1. Transport + + Transport profile is defined in [AAATRANS]. + + The base Diameter protocol is run on port 3868 of both TCP [TCP] and + SCTP [SCTP] transport protocols. + + Diameter clients MUST support either TCP or SCTP, while agents and + servers MUST support both. Future versions of this specification MAY + mandate that clients support SCTP. + + A Diameter node MAY initiate connections from a source port other + than the one that it declares it accepts incoming connections on, and + MUST be prepared to receive connections on port 3868. A given + Diameter instance of the peer state machine MUST NOT use more than + one transport connection to communicate with a given peer, unless + multiple instances exist on the peer in which case a separate + connection per process is allowed. + + When no transport connection exists with a peer, an attempt to + connect SHOULD be periodically made. This behavior is handled via + the Tc timer, whose recommended value is 30 seconds. There are + certain exceptions to this rule, such as when a peer has terminated + the transport connection stating that it does not wish to + communicate. + + When connecting to a peer and either zero or more transports are + specified, SCTP SHOULD be tried first, followed by TCP. See Section + 5.2 for more information on peer discovery. + + Diameter implementations SHOULD be able to interpret ICMP protocol + port unreachable messages as explicit indications that the server is + not reachable, subject to security policy on trusting such messages. + Diameter implementations SHOULD also be able to interpret a reset + from the transport and timed-out connection attempts. + + + + + + +Calhoun, et al. Standards Track [Page 20] + +RFC 3588 Diameter Based Protocol September 2003 + + + If Diameter receives data up from TCP that cannot be parsed or + identified as a Diameter error made by the peer, the stream is + compromised and cannot be recovered. The transport connection MUST + be closed using a RESET call (send a TCP RST bit) or an SCTP ABORT + message (graceful closure is compromised). + +2.1.1. SCTP Guidelines + + The following are guidelines for Diameter implementations that + support SCTP: + + 1. For interoperability: All Diameter nodes MUST be prepared to + receive Diameter messages on any SCTP stream in the association. + + 2. To prevent blocking: All Diameter nodes SHOULD utilize all SCTP + streams available to the association to prevent head-of-the-line + blocking. + +2.2. Securing Diameter Messages + + Diameter clients, such as Network Access Servers (NASes) and Mobility + Agents MUST support IP Security [SECARCH], and MAY support TLS [TLS]. + Diameter servers MUST support TLS and IPsec. The Diameter protocol + MUST NOT be used without any security mechanism (TLS or IPsec). + + It is suggested that IPsec can be used primarily at the edges and in + intra-domain traffic, such as using pre-shared keys between a NAS a + local AAA proxy. This also eases the requirements on the NAS to + support certificates. It is also suggested that inter-domain traffic + would primarily use TLS. See Sections 13.1 and 13.2 for more details + on IPsec and TLS usage. + +2.3. Diameter Application Compliance + + Application Identifiers are advertised during the capabilities + exchange phase (see Section 5.3). For a given application, + advertising support of an application implies that the sender + supports all command codes, and the AVPs specified in the associated + ABNFs, described in the specification. + + An implementation MAY add arbitrary non-mandatory AVPs to any command + defined in an application, including vendor-specific AVPs. Please + refer to Section 11.1.1 for details. + + + + + + + + +Calhoun, et al. Standards Track [Page 21] + +RFC 3588 Diameter Based Protocol September 2003 + + +2.4. Application Identifiers + + Each Diameter application MUST have an IANA assigned Application + Identifier (see Section 11.3). The base protocol does not require an + Application Identifier since its support is mandatory. During the + capabilities exchange, Diameter nodes inform their peers of locally + supported applications. Furthermore, all Diameter messages contain + an Application Identifier, which is used in the message forwarding + process. + + The following Application Identifier values are defined: + + Diameter Common Messages 0 + NASREQ 1 [NASREQ] + Mobile-IP 2 [DIAMMIP] + Diameter Base Accounting 3 + Relay 0xffffffff + + Relay and redirect agents MUST advertise the Relay Application + Identifier, while all other Diameter nodes MUST advertise locally + supported applications. The receiver of a Capabilities Exchange + message advertising Relay service MUST assume that the sender + supports all current and future applications. + + Diameter relay and proxy agents are responsible for finding an + upstream server that supports the application of a particular + message. If none can be found, an error message is returned with the + Result-Code AVP set to DIAMETER_UNABLE_TO_DELIVER. + +2.5. Connections vs. Sessions + + This section attempts to provide the reader with an understanding of + the difference between connection and session, which are terms used + extensively throughout this document. + + A connection is a transport level connection between two peers, used + to send and receive Diameter messages. A session is a logical + concept at the application layer, and is shared between an access + device and a server, and is identified via the Session-Id AVP + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 22] + +RFC 3588 Diameter Based Protocol September 2003 + + + +--------+ +-------+ +--------+ + | Client | | Relay | | Server | + +--------+ +-------+ +--------+ + <----------> <----------> + peer connection A peer connection B + + <-----------------------------> + User session x + + Figure 1: Diameter connections and sessions + + In the example provided in Figure 1, peer connection A is established + between the Client and its local Relay. Peer connection B is + established between the Relay and the Server. User session X spans + from the Client via the Relay to the Server. Each "user" of a + service causes an auth request to be sent, with a unique session + identifier. Once accepted by the server, both the client and the + server are aware of the session. It is important to note that there + is no relationship between a connection and a session, and that + Diameter messages for multiple sessions are all multiplexed through a + single connection. + +2.6. Peer Table + + The Diameter Peer Table is used in message forwarding, and referenced + by the Realm Routing Table. A Peer Table entry contains the + following fields: + + Host identity + Following the conventions described for the DiameterIdentity + derived AVP data format in Section 4.4. This field contains the + contents of the Origin-Host (Section 6.3) AVP found in the CER or + CEA message. + + StatusT + This is the state of the peer entry, and MUST match one of the + values listed in Section 5.6. + + Static or Dynamic + Specifies whether a peer entry was statically configured, or + dynamically discovered. + + Expiration time + Specifies the time at which dynamically discovered peer table + entries are to be either refreshed, or expired. + + + + + + +Calhoun, et al. Standards Track [Page 23] + +RFC 3588 Diameter Based Protocol September 2003 + + + TLS Enabled + Specifies whether TLS is to be used when communicating with the + peer. + + Additional security information, when needed (e.g., keys, + certificates) + +2.7. Realm-Based Routing Table + + All Realm-Based routing lookups are performed against what is + commonly known as the Realm Routing Table (see Section 12). A Realm + Routing Table Entry contains the following fields: + + Realm Name + This is the field that is typically used as a primary key in the + routing table lookups. Note that some implementations perform + their lookups based on longest-match-from-the-right on the realm + rather than requiring an exact match. + + Application Identifier + An application is identified by a vendor id and an application id. + For all IETF standards track Diameter applications, the vendor id + is zero. A route entry can have a different destination based on + the application identification AVP of the message. This field + MUST be used as a secondary key field in routing table lookups. + + Local Action + The Local Action field is used to identify how a message should be + treated. The following actions are supported: + + 1. LOCAL - Diameter messages that resolve to a route entry with + the Local Action set to Local can be satisfied locally, and do + not need to be routed to another server. + + 2. RELAY - All Diameter messages that fall within this category + MUST be routed to a next hop server, without modifying any + non-routing AVPs. See Section 6.1.8 for relaying guidelines + + 3. PROXY - All Diameter messages that fall within this category + MUST be routed to a next hop server. The local server MAY + apply its local policies to the message by including new AVPs + to the message prior to routing. See Section 6.1.8 for + proxying guidelines. + + 4. REDIRECT - Diameter messages that fall within this category + MUST have the identity of the home Diameter server(s) appended, + and returned to the sender of the message. See Section 6.1.7 + for redirect guidelines. + + + +Calhoun, et al. Standards Track [Page 24] + +RFC 3588 Diameter Based Protocol September 2003 + + + Server Identifier + One or more servers the message is to be routed to. These servers + MUST also be present in the Peer table. When the Local Action is + set to RELAY or PROXY, this field contains the identity of the + server(s) the message must be routed to. When the Local Action + field is set to REDIRECT, this field contains the identity of one + or more servers the message should be redirected to. + + Static or Dynamic + Specifies whether a route entry was statically configured, or + dynamically discovered. + + Expiration time + Specifies the time which a dynamically discovered route table + entry expires. + + It is important to note that Diameter agents MUST support at least + one of the LOCAL, RELAY, PROXY or REDIRECT modes of operation. + Agents do not need to support all modes of operation in order to + conform with the protocol specification, but MUST follow the protocol + compliance guidelines in Section 2. Relay agents MUST NOT reorder + AVPs, and proxies MUST NOT reorder AVPs. + + The routing table MAY include a default entry that MUST be used for + any requests not matching any of the other entries. The routing + table MAY consist of only such an entry. + + When a request is routed, the target server MUST have advertised the + Application Identifier (see Section 2.4) for the given message, or + have advertised itself as a relay or proxy agent. Otherwise, an + error is returned with the Result-Code AVP set to + DIAMETER_UNABLE_TO_DELIVER. + +2.8. Role of Diameter Agents + + In addition to client and servers, the Diameter protocol introduces + relay, proxy, redirect, and translation agents, each of which is + defined in Section 1.3. These Diameter agents are useful for several + reasons: + + - They can distribute administration of systems to a configurable + grouping, including the maintenance of security associations. + + - They can be used for concentration of requests from an number of + co-located or distributed NAS equipment sets to a set of like user + groups. + + - They can do value-added processing to the requests or responses. + + + +Calhoun, et al. Standards Track [Page 25] + +RFC 3588 Diameter Based Protocol September 2003 + + + - They can be used for load balancing. + + - A complex network will have multiple authentication sources, they + can sort requests and forward towards the correct target. + + The Diameter protocol requires that agents maintain transaction + state, which is used for failover purposes. Transaction state + implies that upon forwarding a request, its Hop-by-Hop identifier is + saved; the field is replaced with a locally unique identifier, which + is restored to its original value when the corresponding answer is + received. The request's state is released upon receipt of the + answer. A stateless agent is one that only maintains transaction + state. + + The Proxy-Info AVP allows stateless agents to add local state to a + Diameter request, with the guarantee that the same state will be + present in the answer. However, the protocol's failover procedures + require that agents maintain a copy of pending requests. + + A stateful agent is one that maintains session state information; by + keeping track of all authorized active sessions. Each authorized + session is bound to a particular service, and its state is considered + active either until it is notified otherwise, or by expiration. Each + authorized session has an expiration, which is communicated by + Diameter servers via the Session-Timeout AVP. + + Maintaining session state MAY be useful in certain applications, such + as: + + - Protocol translation (e.g., RADIUS <-> Diameter) + + - Limiting resources authorized to a particular user + + - Per user or transaction auditing + + A Diameter agent MAY act in a stateful manner for some requests and + be stateless for others. A Diameter implementation MAY act as one + type of agent for some requests, and as another type of agent for + others. + +2.8.1. Relay Agents + + Relay Agents are Diameter agents that accept requests and route + messages to other Diameter nodes based on information found in the + messages (e.g., Destination-Realm). This routing decision is + performed using a list of supported realms, and known peers. This is + known as the Realm Routing Table, as is defined further in Section + 2.7. + + + +Calhoun, et al. Standards Track [Page 26] + +RFC 3588 Diameter Based Protocol September 2003 + + + Relays MAY be used to aggregate requests from multiple Network Access + Servers (NASes) within a common geographical area (POP). The use of + Relays is advantageous since it eliminates the need for NASes to be + configured with the necessary security information they would + otherwise require to communicate with Diameter servers in other + realms. Likewise, this reduces the configuration load on Diameter + servers that would otherwise be necessary when NASes are added, + changed or deleted. + + Relays modify Diameter messages by inserting and removing routing + information, but do not modify any other portion of a message. + Relays SHOULD NOT maintain session state but MUST maintain + transaction state. + + +------+ ---------> +------+ ---------> +------+ + | | 1. Request | | 2. Request | | + | NAS | | DRL | | HMS | + | | 4. Answer | | 3. Answer | | + +------+ <--------- +------+ <--------- +------+ + example.net example.net example.com + + Figure 2: Relaying of Diameter messages + + The example provided in Figure 2 depicts a request issued from NAS, + which is an access device, for the user [email protected]. Prior to + issuing the request, NAS performs a Diameter route lookup, using + "example.com" as the key, and determines that the message is to be + relayed to DRL, which is a Diameter Relay. DRL performs the same + route lookup as NAS, and relays the message to HMS, which is + example.com's Home Diameter Server. HMS identifies that the request + can be locally supported (via the realm), processes the + authentication and/or authorization request, and replies with an + answer, which is routed back to NAS using saved transaction state. + + Since Relays do not perform any application level processing, they + provide relaying services for all Diameter applications, and + therefore MUST advertise the Relay Application Identifier. + +2.8.2. Proxy Agents + + Similarly to relays, proxy agents route Diameter messages using the + Diameter Routing Table. However, they differ since they modify + messages to implement policy enforcement. This requires that proxies + maintain the state of their downstream peers (e.g., access devices) + to enforce resource usage, provide admission control, and + provisioning. + + + + + +Calhoun, et al. Standards Track [Page 27] + +RFC 3588 Diameter Based Protocol September 2003 + + + It is important to note that although proxies MAY provide a value-add + function for NASes, they do not allow access devices to use end-to- + end security, since modifying messages breaks authentication. + + Proxies MAY be used in call control centers or access ISPs that + provide outsourced connections, they can monitor the number and types + of ports in use, and make allocation and admission decisions + according to their configuration. + + Proxies that wish to limit resources MUST maintain session state. + All proxies MUST maintain transaction state. + + Since enforcing policies requires an understanding of the service + being provided, Proxies MUST only advertise the Diameter applications + they support. + +2.8.3. Redirect Agents + + Redirect agents are useful in scenarios where the Diameter routing + configuration needs to be centralized. An example is a redirect + agent that provides services to all members of a consortium, but does + not wish to be burdened with relaying all messages between realms. + This scenario is advantageous since it does not require that the + consortium provide routing updates to its members when changes are + made to a member's infrastructure. + + Since redirect agents do not relay messages, and only return an + answer with the information necessary for Diameter agents to + communicate directly, they do not modify messages. Since redirect + agents do not receive answer messages, they cannot maintain session + state. Further, since redirect agents never relay requests, they are + not required to maintain transaction state. + + The example provided in Figure 3 depicts a request issued from the + access device, NAS, for the user [email protected]. The message is + forwarded by the NAS to its relay, DRL, which does not have a routing + entry in its Diameter Routing Table for example.com. DRL has a + default route configured to DRD, which is a redirect agent that + returns a redirect notification to DRL, as well as HMS' contact + information. Upon receipt of the redirect notification, DRL + establishes a transport connection with HMS, if one doesn't already + exist, and forwards the request to it. + + + + + + + + + +Calhoun, et al. Standards Track [Page 28] + +RFC 3588 Diameter Based Protocol September 2003 + + + +------+ + | | + | DRD | + | | + +------+ + ^ | + 2. Request | | 3. Redirection + | | Notification + | v + +------+ ---------> +------+ ---------> +------+ + | | 1. Request | | 4. Request | | + | NAS | | DRL | | HMS | + | | 6. Answer | | 5. Answer | | + +------+ <--------- +------+ <--------- +------+ + example.net example.net example.com + + Figure 3: Redirecting a Diameter Message + + Since redirect agents do not perform any application level + processing, they provide relaying services for all Diameter + applications, and therefore MUST advertise the Relay Application + Identifier. + +2.8.4. Translation Agents + + A translation agent is a device that provides translation between two + protocols (e.g., RADIUS<->Diameter, TACACS+<->Diameter). Translation + agents are likely to be used as aggregation servers to communicate + with a Diameter infrastructure, while allowing for the embedded + systems to be migrated at a slower pace. + + Given that the Diameter protocol introduces the concept of long-lived + authorized sessions, translation agents MUST be session stateful and + MUST maintain transaction state. + + Translation of messages can only occur if the agent recognizes the + application of a particular request, and therefore translation agents + MUST only advertise their locally supported applications. + + +------+ ---------> +------+ ---------> +------+ + | | RADIUS Request | | Diameter Request | | + | NAS | | TLA | | HMS | + | | RADIUS Answer | | Diameter Answer | | + +------+ <--------- +------+ <--------- +------+ + example.net example.net example.com + + Figure 4: Translation of RADIUS to Diameter + + + + +Calhoun, et al. Standards Track [Page 29] + +RFC 3588 Diameter Based Protocol September 2003 + + +2.9. End-to-End Security Framework + + End-to-end security services include confidentiality and message + origin authentication. These services are provided by supporting AVP + integrity and confidentiality between two peers, communicating + through agents. + + End-to-end security is provided via the End-to-End security + extension, described in [AAACMS]. The circumstances requiring the + use of end-to-end security are determined by policy on each of the + peers. Security policies, which are not the subject of + standardization, may be applied by next hop Diameter peer or by + destination realm. For example, where TLS or IPsec transmission- + level security is sufficient, there may be no need for end-to-end + security. + + End-to-end security policies include: + + - Never use end-to-end security. + + - Use end-to-end security on messages containing sensitive AVPs. + Which AVPs are sensitive is determined by service provider policy. + AVPs containing keys and passwords should be considered sensitive. + Accounting AVPs may be considered sensitive. Any AVP for which + the P bit may be set or which may be encrypted may be considered + sensitive. + + - Always use end-to-end security. + + It is strongly RECOMMENDED that all Diameter implementations support + end-to-end security. + +2.10. Diameter Path Authorization + + As noted in Section 2.2, Diameter requires transmission level + security to be used on each connection (TLS or IPsec). Therefore, + each connection is authenticated, replay and integrity protected and + confidential on a per-packet basis. + + In addition to authenticating each connection, each connection as + well as the entire session MUST also be authorized. Before + initiating a connection, a Diameter Peer MUST check that its peers + are authorized to act in their roles. For example, a Diameter peer + may be authentic, but that does not mean that it is authorized to act + as a Diameter Server advertising a set of Diameter applications. + + + + + + +Calhoun, et al. Standards Track [Page 30] + +RFC 3588 Diameter Based Protocol September 2003 + + + Prior to bringing up a connection, authorization checks are performed + at each connection along the path. Diameter capabilities negotiation + (CER/CEA) also MUST be carried out, in order to determine what + Diameter applications are supported by each peer. Diameter sessions + MUST be routed only through authorized nodes that have advertised + support for the Diameter application required by the session. + + As noted in Section 6.1.8, a relay or proxy agent MUST append a + Route-Record AVP to all requests forwarded. The AVP contains the + identity of the peer the request was received from. + + The home Diameter server, prior to authorizing a session, MUST check + the Route-Record AVPs to make sure that the route traversed by the + request is acceptable. For example, administrators within the home + realm may not wish to honor requests that have been routed through an + untrusted realm. By authorizing a request, the home Diameter server + is implicitly indicating its willingness to engage in the business + transaction as specified by the contractual relationship between the + server and the previous hop. A DIAMETER_AUTHORIZATION_REJECTED error + message (see Section 7.1.5) is sent if the route traversed by the + request is unacceptable. + + A home realm may also wish to check that each accounting request + message corresponds to a Diameter response authorizing the session. + Accounting requests without corresponding authorization responses + SHOULD be subjected to further scrutiny, as should accounting + requests indicating a difference between the requested and provided + service. + + Similarly, the local Diameter agent, on receiving a Diameter response + authorizing a session, MUST check the Route-Record AVPs to make sure + that the route traversed by the response is acceptable. At each + step, forwarding of an authorization response is considered evidence + of a willingness to take on financial risk relative to the session. + A local realm may wish to limit this exposure, for example, by + establishing credit limits for intermediate realms and refusing to + accept responses which would violate those limits. By issuing an + accounting request corresponding to the authorization response, the + local realm implicitly indicates its agreement to provide the service + indicated in the authorization response. If the service cannot be + provided by the local realm, then a DIAMETER_UNABLE_TO_COMPLY error + message MUST be sent within the accounting request; a Diameter client + receiving an authorization response for a service that it cannot + perform MUST NOT substitute an alternate service, and then send + accounting requests for the alternate service instead. + + + + + + +Calhoun, et al. Standards Track [Page 31] + +RFC 3588 Diameter Based Protocol September 2003 + + +3. Diameter Header + + A summary of the Diameter header format is shown below. The fields + are transmitted in network byte order. + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Version | Message Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | command flags | Command-Code | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Application-ID | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Hop-by-Hop Identifier | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | End-to-End Identifier | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | AVPs ... + +-+-+-+-+-+-+-+-+-+-+-+-+- + + Version + This Version field MUST be set to 1 to indicate Diameter Version + 1. + + Message Length + The Message Length field is three octets and indicates the length + of the Diameter message including the header fields. + + Command Flags + The Command Flags field is eight bits. The following bits are + assigned: + + 0 1 2 3 4 5 6 7 + +-+-+-+-+-+-+-+-+ + |R P E T r r r r| + +-+-+-+-+-+-+-+-+ + + R(equest) - If set, the message is a request. If cleared, the + message is an answer. + P(roxiable) - If set, the message MAY be proxied, relayed or + redirected. If cleared, the message MUST be + locally processed. + E(rror) - If set, the message contains a protocol error, + and the message will not conform to the ABNF + described for this command. Messages with the 'E' + + + + + +Calhoun, et al. Standards Track [Page 32] + +RFC 3588 Diameter Based Protocol September 2003 + + + bit set are commonly referred to as error + messages. This bit MUST NOT be set in request + messages. See Section 7.2. + T(Potentially re-transmitted message) + - This flag is set after a link failover procedure, + to aid the removal of duplicate requests. It is + set when resending requests not yet acknowledged, + as an indication of a possible duplicate due to a + link failure. This bit MUST be cleared when + sending a request for the first time, otherwise + the sender MUST set this flag. Diameter agents + only need to be concerned about the number of + requests they send based on a single received + request; retransmissions by other entities need + not be tracked. Diameter agents that receive a + request with the T flag set, MUST keep the T flag + set in the forwarded request. This flag MUST NOT + be set if an error answer message (e.g., a + protocol error) has been received for the earlier + message. It can be set only in cases where no + answer has been received from the server for a + request and the request is sent again. This flag + MUST NOT be set in answer messages. + + r(eserved) - these flag bits are reserved for future use, and + MUST be set to zero, and ignored by the receiver. + + Command-Code + The Command-Code field is three octets, and is used in order to + communicate the command associated with the message. The 24-bit + address space is managed by IANA (see Section 11.2.1). + + Command-Code values 16,777,214 and 16,777,215 (hexadecimal values + FFFFFE -FFFFFF) are reserved for experimental use (See Section + 11.3). + + Application-ID + Application-ID is four octets and is used to identify to which + application the message is applicable for. The application can be + an authentication application, an accounting application or a + vendor specific application. See Section 11.3 for the possible + values that the application-id may use. + + The application-id in the header MUST be the same as what is + contained in any relevant AVPs contained in the message. + + + + + + +Calhoun, et al. Standards Track [Page 33] + +RFC 3588 Diameter Based Protocol September 2003 + + + Hop-by-Hop Identifier + The Hop-by-Hop Identifier is an unsigned 32-bit integer field (in + network byte order) and aids in matching requests and replies. + The sender MUST ensure that the Hop-by-Hop identifier in a request + is unique on a given connection at any given time, and MAY attempt + to ensure that the number is unique across reboots. The sender of + an Answer message MUST ensure that the Hop-by-Hop Identifier field + contains the same value that was found in the corresponding + request. The Hop-by-Hop identifier is normally a monotonically + increasing number, whose start value was randomly generated. An + answer message that is received with an unknown Hop-by-Hop + Identifier MUST be discarded. + + End-to-End Identifier + The End-to-End Identifier is an unsigned 32-bit integer field (in + network byte order) and is used to detect duplicate messages. + Upon reboot implementations MAY set the high order 12 bits to + contain the low order 12 bits of current time, and the low order + 20 bits to a random value. Senders of request messages MUST + insert a unique identifier on each message. The identifier MUST + remain locally unique for a period of at least 4 minutes, even + across reboots. The originator of an Answer message MUST ensure + that the End-to-End Identifier field contains the same value that + was found in the corresponding request. The End-to-End Identifier + MUST NOT be modified by Diameter agents of any kind. The + combination of the Origin-Host (see Section 6.3) and this field is + used to detect duplicates. Duplicate requests SHOULD cause the + same answer to be transmitted (modulo the hop-by-hop Identifier + field and any routing AVPs that may be present), and MUST NOT + affect any state that was set when the original request was + processed. Duplicate answer messages that are to be locally + consumed (see Section 6.2) SHOULD be silently discarded. + + AVPs + AVPs are a method of encapsulating information relevant to the + Diameter message. See Section 4 for more information on AVPs. + + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 34] + +RFC 3588 Diameter Based Protocol September 2003 + + +3.1. Command Codes + + Each command Request/Answer pair is assigned a command code, and the + sub-type (i.e., request or answer) is identified via the 'R' bit in + the Command Flags field of the Diameter header. + + Every Diameter message MUST contain a command code in its header's + Command-Code field, which is used to determine the action that is to + be taken for a particular message. The following Command Codes are + defined in the Diameter base protocol: + + Command-Name Abbrev. Code Reference + -------------------------------------------------------- + Abort-Session-Request ASR 274 8.5.1 + Abort-Session-Answer ASA 274 8.5.2 + Accounting-Request ACR 271 9.7.1 + Accounting-Answer ACA 271 9.7.2 + Capabilities-Exchange- CER 257 5.3.1 + Request + Capabilities-Exchange- CEA 257 5.3.2 + Answer + Device-Watchdog-Request DWR 280 5.5.1 + Device-Watchdog-Answer DWA 280 5.5.2 + Disconnect-Peer-Request DPR 282 5.4.1 + Disconnect-Peer-Answer DPA 282 5.4.2 + Re-Auth-Request RAR 258 8.3.1 + Re-Auth-Answer RAA 258 8.3.2 + Session-Termination- STR 275 8.4.1 + Request + Session-Termination- STA 275 8.4.2 + Answer + + + + + + + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 35] + +RFC 3588 Diameter Based Protocol September 2003 + + +3.2. Command Code ABNF specification + + Every Command Code defined MUST include a corresponding ABNF + specification, which is used to define the AVPs that MUST or MAY be + present. The following format is used in the definition: + + command-def = command-name "::=" diameter-message + + command-name = diameter-name + + diameter-name = ALPHA *(ALPHA / DIGIT / "-") + + diameter-message = header [ *fixed] [ *required] [ *optional] + [ *fixed] + + header = "<" Diameter-Header:" command-id + [r-bit] [p-bit] [e-bit] [application-id]">" + + application-id = 1*DIGIT + + command-id = 1*DIGIT + ; The Command Code assigned to the command + + r-bit = ", REQ" + ; If present, the 'R' bit in the Command + ; Flags is set, indicating that the message + ; is a request, as opposed to an answer. + + p-bit = ", PXY" + ; If present, the 'P' bit in the Command + ; Flags is set, indicating that the message + ; is proxiable. + + e-bit = ", ERR" + ; If present, the 'E' bit in the Command + ; Flags is set, indicating that the answer + ; message contains a Result-Code AVP in + ; the "protocol error" class. + + fixed = [qual] "<" avp-spec ">" + ; Defines the fixed position of an AVP + + required = [qual] "{" avp-spec "}" + ; The AVP MUST be present and can appear + ; anywhere in the message. + + + + + + +Calhoun, et al. Standards Track [Page 36] + +RFC 3588 Diameter Based Protocol September 2003 + + + optional = [qual] "[" avp-name "]" + ; The avp-name in the 'optional' rule cannot + ; evaluate to any AVP Name which is included + ; in a fixed or required rule. The AVP can + ; appear anywhere in the message. + + qual = [min] "*" [max] + ; See ABNF conventions, RFC 2234 Section 6.6. + ; The absence of any qualifiers depends on whether + ; it precedes a fixed, required, or optional + ; rule. If a fixed or required rule has no + ; qualifier, then exactly one such AVP MUST + ; be present. If an optional rule has no + ; qualifier, then 0 or 1 such AVP may be + ; present. + ; + ; NOTE: "[" and "]" have a different meaning + ; than in ABNF (see the optional rule, above). + ; These braces cannot be used to express + ; optional fixed rules (such as an optional + ; ICV at the end). To do this, the convention + ; is '0*1fixed'. + + min = 1*DIGIT + ; The minimum number of times the element may + ; be present. The default value is zero. + + max = 1*DIGIT + ; The maximum number of times the element may + ; be present. The default value is infinity. A + ; value of zero implies the AVP MUST NOT be + ; present. + + avp-spec = diameter-name + ; The avp-spec has to be an AVP Name, defined + ; in the base or extended Diameter + ; specifications. + + avp-name = avp-spec / "AVP" + ; The string "AVP" stands for *any* arbitrary + ; AVP Name, which does not conflict with the + ; required or fixed position AVPs defined in + ; the command code definition. + + + + + + + + +Calhoun, et al. Standards Track [Page 37] + +RFC 3588 Diameter Based Protocol September 2003 + + + The following is a definition of a fictitious command code: + + Example-Request ::= < "Diameter-Header: 9999999, REQ, PXY > + { User-Name } + * { Origin-Host } + * [ AVP + +3.3. Diameter Command Naming Conventions + + Diameter command names typically includes one or more English words + followed by the verb Request or Answer. Each English word is + delimited by a hyphen. A three-letter acronym for both the request + and answer is also normally provided. + + An example is a message set used to terminate a session. The command + name is Session-Terminate-Request and Session-Terminate-Answer, while + the acronyms are STR and STA, respectively. + + Both the request and the answer for a given command share the same + command code. The request is identified by the R(equest) bit in the + Diameter header set to one (1), to ask that a particular action be + performed, such as authorizing a user or terminating a session. Once + the receiver has completed the request it issues the corresponding + answer, which includes a result code that communicates one of the + following: + + - The request was successful + + - The request failed + + - An additional request must be sent to provide information the peer + requires prior to returning a successful or failed answer. + + - The receiver could not process the request, but provides + information about a Diameter peer that is able to satisfy the + request, known as redirect. + + Additional information, encoded within AVPs, MAY also be included in + answer messages. + +4. Diameter AVPs + + Diameter AVPs carry specific authentication, accounting, + authorization, routing and security information as well as + configuration details for the request and reply. + + Some AVPs MAY be listed more than once. The effect of such an AVP is + specific, and is specified in each case by the AVP description. + + + +Calhoun, et al. Standards Track [Page 38] + +RFC 3588 Diameter Based Protocol September 2003 + + + Each AVP of type OctetString MUST be padded to align on a 32-bit + boundary, while other AVP types align naturally. A number of zero- + valued bytes are added to the end of the AVP Data field till a word + boundary is reached. The length of the padding is not reflected in + the AVP Length field. + +4.1. AVP Header + + The fields in the AVP header MUST be sent in network byte order. The + format of the header is: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | AVP Code | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |V M P r r r r r| AVP Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Vendor-ID (opt) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Data ... + +-+-+-+-+-+-+-+-+ + + AVP Code + The AVP Code, combined with the Vendor-Id field, identifies the + attribute uniquely. AVP numbers 1 through 255 are reserved for + backward compatibility with RADIUS, without setting the Vendor-Id + field. AVP numbers 256 and above are used for Diameter, which are + allocated by IANA (see Section 11.1). + + AVP Flags + The AVP Flags field informs the receiver how each attribute must + be handled. The 'r' (reserved) bits are unused and SHOULD be set + to 0. Note that subsequent Diameter applications MAY define + additional bits within the AVP Header, and an unrecognized bit + SHOULD be considered an error. The 'P' bit indicates the need for + encryption for end-to-end security. + + The 'M' Bit, known as the Mandatory bit, indicates whether support + of the AVP is required. If an AVP with the 'M' bit set is + received by a Diameter client, server, proxy, or translation agent + and either the AVP or its value is unrecognized, the message MUST + be rejected. Diameter Relay and redirect agents MUST NOT reject + messages with unrecognized AVPs. + + + + + + + +Calhoun, et al. Standards Track [Page 39] + +RFC 3588 Diameter Based Protocol September 2003 + + + The 'M' bit MUST be set according to the rules defined for the AVP + containing it. In order to preserve interoperability, a Diameter + implementation MUST be able to exclude from a Diameter message any + Mandatory AVP which is neither defined in the base Diameter + protocol nor in any of the Diameter Application specifications + governing the message in which it appears. It MAY do this in one + of the following ways: + + 1) If a message is rejected because it contains a Mandatory AVP + which is neither defined in the base Diameter standard nor in + any of the Diameter Application specifications governing the + message in which it appears, the implementation may resend the + message without the AVP, possibly inserting additional standard + AVPs instead. + + 2) A configuration option may be provided on a system wide, per + peer, or per realm basis that would allow/prevent particular + Mandatory AVPs to be sent. Thus an administrator could change + the configuration to avoid interoperability problems. + + Diameter implementations are required to support all Mandatory + AVPs which are allowed by the message's formal syntax and defined + either in the base Diameter standard or in one of the Diameter + Application specifications governing the message. + + AVPs with the 'M' bit cleared are informational only and a + receiver that receives a message with such an AVP that is not + supported, or whose value is not supported, MAY simply ignore the + AVP. + + The 'V' bit, known as the Vendor-Specific bit, indicates whether + the optional Vendor-ID field is present in the AVP header. When + set the AVP Code belongs to the specific vendor code address + space. + + Unless otherwise noted, AVPs will have the following default AVP + Flags field settings: + + The 'M' bit MUST be set. The 'V' bit MUST NOT be set. + + AVP Length + The AVP Length field is three octets, and indicates the number of + octets in this AVP including the AVP Code, AVP Length, AVP Flags, + Vendor-ID field (if present) and the AVP data. If a message is + received with an invalid attribute length, the message SHOULD be + rejected. + + + + + +Calhoun, et al. Standards Track [Page 40] + +RFC 3588 Diameter Based Protocol September 2003 + + +4.1.1. Optional Header Elements + + The AVP Header contains one optional field. This field is only + present if the respective bit-flag is enabled. + + Vendor-ID + The Vendor-ID field is present if the 'V' bit is set in the AVP + Flags field. The optional four-octet Vendor-ID field contains the + IANA assigned "SMI Network Management Private Enterprise Codes" + [ASSIGNNO] value, encoded in network byte order. Any vendor + wishing to implement a vendor-specific Diameter AVP MUST use their + own Vendor-ID along with their privately managed AVP address + space, guaranteeing that they will not collide with any other + vendor's vendor-specific AVP(s), nor with future IETF + applications. + + A vendor ID value of zero (0) corresponds to the IETF adopted AVP + values, as managed by the IANA. Since the absence of the vendor + ID field implies that the AVP in question is not vendor specific, + implementations MUST NOT use the zero (0) vendor ID. + +4.2. Basic AVP Data Formats + + The Data field is zero or more octets and contains information + specific to the Attribute. The format and length of the Data field + is determined by the AVP Code and AVP Length fields. The format of + the Data field MUST be one of the following base data types or a data + type derived from the base data types. In the event that a new Basic + AVP Data Format is needed, a new version of this RFC must be created. + + OctetString + The data contains arbitrary data of variable length. Unless + otherwise noted, the AVP Length field MUST be set to at least 8 + (12 if the 'V' bit is enabled). AVP Values of this type that are + not a multiple of four-octets in length is followed by the + necessary padding so that the next AVP (if any) will start on a + 32-bit boundary. + + Integer32 + 32 bit signed value, in network byte order. The AVP Length field + MUST be set to 12 (16 if the 'V' bit is enabled). + + Integer64 + 64 bit signed value, in network byte order. The AVP Length field + MUST be set to 16 (20 if the 'V' bit is enabled). + + + + + + +Calhoun, et al. Standards Track [Page 41] + +RFC 3588 Diameter Based Protocol September 2003 + + + Unsigned32 + 32 bit unsigned value, in network byte order. The AVP Length + field MUST be set to 12 (16 if the 'V' bit is enabled). + + Unsigned64 + 64 bit unsigned value, in network byte order. The AVP Length + field MUST be set to 16 (20 if the 'V' bit is enabled). + + Float32 + This represents floating point values of single precision as + described by [FLOATPOINT]. The 32-bit value is transmitted in + network byte order. The AVP Length field MUST be set to 12 (16 if + the 'V' bit is enabled). + + Float64 + This represents floating point values of double precision as + described by [FLOATPOINT]. The 64-bit value is transmitted in + network byte order. The AVP Length field MUST be set to 16 (20 if + the 'V' bit is enabled). + + Grouped + The Data field is specified as a sequence of AVPs. Each of these + AVPs follows - in the order in which they are specified - + including their headers and padding. The AVP Length field is set + to 8 (12 if the 'V' bit is enabled) plus the total length of all + included AVPs, including their headers and padding. Thus the AVP + length field of an AVP of type Grouped is always a multiple of 4. + +4.3. Derived AVP Data Formats + + In addition to using the Basic AVP Data Formats, applications may + define data formats derived from the Basic AVP Data Formats. An + application that defines new AVP Derived Data Formats MUST include + them in a section entitled "AVP Derived Data Formats", using the same + format as the definitions below. Each new definition must be either + defined or listed with a reference to the RFC that defines the + format. + + The below AVP Derived Data Formats are commonly used by applications. + + Address + The Address format is derived from the OctetString AVP Base + Format. It is a discriminated union, representing, for example a + 32-bit (IPv4) [IPV4] or 128-bit (IPv6) [IPV6] address, most + significant octet first. The first two octets of the Address + + + + + + +Calhoun, et al. Standards Track [Page 42] + +RFC 3588 Diameter Based Protocol September 2003 + + + AVP represents the AddressType, which contains an Address Family + defined in [IANAADFAM]. The AddressType is used to discriminate + the content and format of the remaining octets. + + Time + The Time format is derived from the OctetString AVP Base Format. + The string MUST contain four octets, in the same format as the + first four bytes are in the NTP timestamp format. The NTP + Timestamp format is defined in chapter 3 of [SNTP]. + + This represents the number of seconds since 0h on 1 January 1900 + with respect to the Coordinated Universal Time (UTC). + + On 6h 28m 16s UTC, 7 February 2036 the time value will overflow. + SNTP [SNTP] describes a procedure to extend the time to 2104. + This procedure MUST be supported by all DIAMETER nodes. + + UTF8String + The UTF8String format is derived from the OctetString AVP Base + Format. This is a human readable string represented using the + ISO/IEC IS 10646-1 character set, encoded as an OctetString using + the UTF-8 [UFT8] transformation format described in RFC 2279. + + Since additional code points are added by amendments to the 10646 + standard from time to time, implementations MUST be prepared to + encounter any code point from 0x00000001 to 0x7fffffff. Byte + sequences that do not correspond to the valid encoding of a code + point into UTF-8 charset or are outside this range are prohibited. + + The use of control codes SHOULD be avoided. When it is necessary + to represent a new line, the control code sequence CR LF SHOULD be + used. + + The use of leading or trailing white space SHOULD be avoided. + + For code points not directly supported by user interface hardware + or software, an alternative means of entry and display, such as + hexadecimal, MAY be provided. + + For information encoded in 7-bit US-ASCII, the UTF-8 charset is + identical to the US-ASCII charset. + + UTF-8 may require multiple bytes to represent a single character / + code point; thus the length of an UTF8String in octets may be + different from the number of characters encoded. + + Note that the AVP Length field of an UTF8String is measured in + octets, not characters. + + + +Calhoun, et al. Standards Track [Page 43] + +RFC 3588 Diameter Based Protocol September 2003 + + + DiameterIdentity + The DiameterIdentity format is derived from the OctetString AVP + Base Format. + + DiameterIdentity = FQDN + + DiameterIdentity value is used to uniquely identify a Diameter + node for purposes of duplicate connection and routing loop + detection. + + The contents of the string MUST be the FQDN of the Diameter node. + If multiple Diameter nodes run on the same host, each Diameter + node MUST be assigned a unique DiameterIdentity. If a Diameter + node can be identified by several FQDNs, a single FQDN should be + picked at startup, and used as the only DiameterIdentity for that + node, whatever the connection it is sent on. + + DiameterURI + + The DiameterURI MUST follow the Uniform Resource Identifiers (URI) + syntax [URI] rules specified below: + + "aaa://" FQDN [ port ] [ transport ] [ protocol ] + + ; No transport security + + "aaas://" FQDN [ port ] [ transport ] [ protocol ] + + ; Transport security used + + FQDN = Fully Qualified Host Name + + port = ":" 1*DIGIT + + ; One of the ports used to listen for + ; incoming connections. + ; If absent, + ; the default Diameter port (3868) is + ; assumed. + + transport = ";transport=" transport-protocol + + ; One of the transports used to listen + ; for incoming connections. If absent, + ; the default SCTP [SCTP] protocol is + ; assumed. UDP MUST NOT be used when + ; the aaa-protocol field is set to + ; diameter. + + + +Calhoun, et al. Standards Track [Page 44] + +RFC 3588 Diameter Based Protocol September 2003 + + + transport-protocol = ( "tcp" / "sctp" / "udp" ) + + protocol = ";protocol=" aaa-protocol + + ; If absent, the default AAA protocol + ; is diameter. + + aaa-protocol = ( "diameter" / "radius" / "tacacs+" ) + + The following are examples of valid Diameter host identities: + + aaa://host.example.com;transport=tcp + aaa://host.example.com:6666;transport=tcp + aaa://host.example.com;protocol=diameter + aaa://host.example.com:6666;protocol=diameter + aaa://host.example.com:6666;transport=tcp;protocol=diameter + aaa://host.example.com:1813;transport=udp;protocol=radius + + Enumerated + Enumerated is derived from the Integer32 AVP Base Format. The + definition contains a list of valid values and their + interpretation and is described in the Diameter application + introducing the AVP. + + IPFilterRule + The IPFilterRule format is derived from the OctetString AVP Base + Format. It uses the ASCII charset. Packets may be filtered based + on the following information that is associated with it: + + Direction (in or out) + Source and destination IP address (possibly masked) + Protocol + Source and destination port (lists or ranges) + TCP flags + IP fragment flag + IP options + ICMP types + + Rules for the appropriate direction are evaluated in order, with + the first matched rule terminating the evaluation. Each packet is + evaluated once. If no rule matches, the packet is dropped if the + last rule evaluated was a permit, and passed if the last rule was + a deny. + + + + + + + + +Calhoun, et al. Standards Track [Page 45] + +RFC 3588 Diameter Based Protocol September 2003 + + + IPFilterRule filters MUST follow the format: + + action dir proto from src to dst [options] + + action permit - Allow packets that match the rule. + deny - Drop packets that match the rule. + + dir "in" is from the terminal, "out" is to the + terminal. + + proto An IP protocol specified by number. The "ip" + keyword means any protocol will match. + + src and dst <address/mask> [ports] + + The <address/mask> may be specified as: + ipno An IPv4 or IPv6 number in dotted- + quad or canonical IPv6 form. Only + this exact IP number will match the + rule. + ipno/bits An IP number as above with a mask + width of the form 1.2.3.4/24. In + this case, all IP numbers from + 1.2.3.0 to 1.2.3.255 will match. + The bit width MUST be valid for the + IP version and the IP number MUST + NOT have bits set beyond the mask. + For a match to occur, the same IP + version must be present in the + packet that was used in describing + the IP address. To test for a + particular IP version, the bits part + can be set to zero. The keyword + "any" is 0.0.0.0/0 or the IPv6 + equivalent. The keyword "assigned" + is the address or set of addresses + assigned to the terminal. For IPv4, + a typical first rule is often "deny + in ip! assigned" + + The sense of the match can be inverted by + preceding an address with the not modifier (!), + causing all other addresses to be matched + instead. This does not affect the selection of + port numbers. + + + + + + +Calhoun, et al. Standards Track [Page 46] + +RFC 3588 Diameter Based Protocol September 2003 + + + With the TCP, UDP and SCTP protocols, optional + ports may be specified as: + + {port/port-port}[,ports[,...]] + + The '-' notation specifies a range of ports + (including boundaries). + + Fragmented packets that have a non-zero offset + (i.e., not the first fragment) will never match + a rule that has one or more port + specifications. See the frag option for + details on matching fragmented packets. + + options: + frag Match if the packet is a fragment and this is not + the first fragment of the datagram. frag may not + be used in conjunction with either tcpflags or + TCP/UDP port specifications. + + ipoptions spec + Match if the IP header contains the comma + separated list of options specified in spec. The + supported IP options are: + + ssrr (strict source route), lsrr (loose source + route), rr (record packet route) and ts + (timestamp). The absence of a particular option + may be denoted with a '!'. + + tcpoptions spec + Match if the TCP header contains the comma + separated list of options specified in spec. The + supported TCP options are: + + mss (maximum segment size), window (tcp window + advertisement), sack (selective ack), ts (rfc1323 + timestamp) and cc (rfc1644 t/tcp connection + count). The absence of a particular option may + be denoted with a '!'. + + established + TCP packets only. Match packets that have the RST + or ACK bits set. + + setup TCP packets only. Match packets that have the SYN + bit set but no ACK bit. + + + + +Calhoun, et al. Standards Track [Page 47] + +RFC 3588 Diameter Based Protocol September 2003 + + + tcpflags spec + TCP packets only. Match if the TCP header + contains the comma separated list of flags + specified in spec. The supported TCP flags are: + + fin, syn, rst, psh, ack and urg. The absence of a + particular flag may be denoted with a '!'. A rule + that contains a tcpflags specification can never + match a fragmented packet that has a non-zero + offset. See the frag option for details on + matching fragmented packets. + + icmptypes types + ICMP packets only. Match if the ICMP type is in + the list types. The list may be specified as any + combination of ranges or individual types + separated by commas. Both the numeric values and + the symbolic values listed below can be used. The + supported ICMP types are: + + echo reply (0), destination unreachable (3), + source quench (4), redirect (5), echo request + (8), router advertisement (9), router + solicitation (10), time-to-live exceeded (11), IP + header bad (12), timestamp request (13), + timestamp reply (14), information request (15), + information reply (16), address mask request (17) + and address mask reply (18). + + There is one kind of packet that the access device MUST always + discard, that is an IP fragment with a fragment offset of one. This + is a valid packet, but it only has one use, to try to circumvent + firewalls. + + An access device that is unable to interpret or apply a deny rule + MUST terminate the session. An access device that is unable to + interpret or apply a permit rule MAY apply a more restrictive + rule. An access device MAY apply deny rules of its own before the + supplied rules, for example to protect the access device owner's + infrastructure. + + The rule syntax is a modified subset of ipfw(8) from FreeBSD, and the + ipfw.c code may provide a useful base for implementations. + + + + + + + + +Calhoun, et al. Standards Track [Page 48] + +RFC 3588 Diameter Based Protocol September 2003 + + + QoSFilterRule + The QosFilterRule format is derived from the OctetString AVP Base + Format. It uses the ASCII charset. Packets may be marked or + metered based on the following information that is associated with + it: + + Direction (in or out) + Source and destination IP address (possibly masked) + Protocol + Source and destination port (lists or ranges) + DSCP values (no mask or range) + + Rules for the appropriate direction are evaluated in order, with + the first matched rule terminating the evaluation. Each packet is + evaluated once. If no rule matches, the packet is treated as best + effort. An access device that is unable to interpret or apply a + QoS rule SHOULD NOT terminate the session. + + QoSFilterRule filters MUST follow the format: + + action dir proto from src to dst [options] + + tag - Mark packet with a specific DSCP + [DIFFSERV]. The DSCP option MUST be + included. + meter - Meter traffic. The metering options + MUST be included. + + dir The format is as described under IPFilterRule. + + proto The format is as described under + IPFilterRule. + + src and dst The format is as described under + IPFilterRule. + +4.4. Grouped AVP Values + + The Diameter protocol allows AVP values of type 'Grouped.' This + implies that the Data field is actually a sequence of AVPs. It is + possible to include an AVP with a Grouped type within a Grouped type, + that is, to nest them. AVPs within an AVP of type Grouped have the + same padding requirements as non-Grouped AVPs, as defined in Section + 4. + + + + + + + +Calhoun, et al. Standards Track [Page 49] + +RFC 3588 Diameter Based Protocol September 2003 + + + The AVP Code numbering space of all AVPs included in a Grouped AVP is + the same as for non-grouped AVPs. Further, if any of the AVPs + encapsulated within a Grouped AVP has the 'M' (mandatory) bit set, + the Grouped AVP itself MUST also include the 'M' bit set. + + Every Grouped AVP defined MUST include a corresponding grammar, using + ABNF [ABNF] (with modifications), as defined below. + + grouped-avp-def = name "::=" avp + + name-fmt = ALPHA *(ALPHA / DIGIT / "-") + + name = name-fmt + ; The name has to be the name of an AVP, + ; defined in the base or extended Diameter + ; specifications. + + avp = header [ *fixed] [ *required] [ *optional] + [ *fixed] + + header = "<" "AVP-Header:" avpcode [vendor] ">" + + avpcode = 1*DIGIT + ; The AVP Code assigned to the Grouped AVP + + vendor = 1*DIGIT + ; The Vendor-ID assigned to the Grouped AVP. + ; If absent, the default value of zero is + ; used. + +4.4.1. Example AVP with a Grouped Data type + + The Example-AVP (AVP Code 999999) is of type Grouped and is used to + clarify how Grouped AVP values work. The Grouped Data field has the + following ABNF grammar: + + Example-AVP ::= < AVP Header: 999999 > + { Origin-Host } + 1*{ Session-Id } + *[ AVP ] + + An Example-AVP with Grouped Data follows. + + The Origin-Host AVP is required (Section 6.3). In this case: + + Origin-Host = "example.com". + + + + + +Calhoun, et al. Standards Track [Page 50] + +RFC 3588 Diameter Based Protocol September 2003 + + + One or more Session-Ids must follow. Here there are two: + + Session-Id = + "grump.example.com:33041;23432;893;0AF3B81" + + Session-Id = + "grump.example.com:33054;23561;2358;0AF3B82" + + optional AVPs included are + + Recovery-Policy = <binary> + 2163bc1d0ad82371f6bc09484133c3f09ad74a0dd5346d54195a7cf0b35 + 2cabc881839a4fdcfbc1769e2677a4c1fb499284c5f70b48f58503a45c5 + c2d6943f82d5930f2b7c1da640f476f0e9c9572a50db8ea6e51e1c2c7bd + f8bb43dc995144b8dbe297ac739493946803e1cee3e15d9b765008a1b2a + cf4ac777c80041d72c01e691cf751dbf86e85f509f3988e5875dc905119 + 26841f00f0e29a6d1ddc1a842289d440268681e052b30fb638045f7779c + 1d873c784f054f688f5001559ecff64865ef975f3e60d2fd7966b8c7f92 + + Futuristic-Acct-Record = <binary> + fe19da5802acd98b07a5b86cb4d5d03f0314ab9ef1ad0b67111ff3b90a0 + 57fe29620bf3585fd2dd9fcc38ce62f6cc208c6163c008f4258d1bc88b8 + 17694a74ccad3ec69269461b14b2e7a4c111fb239e33714da207983f58c + 41d018d56fe938f3cbf089aac12a912a2f0d1923a9390e5f789cb2e5067 + d3427475e49968f841 + + The data for the optional AVPs is represented in hex since the format + of these AVPs is neither known at the time of definition of the + Example-AVP group, nor (likely) at the time when the example instance + of this AVP is interpreted - except by Diameter implementations which + support the same set of AVPs. The encoding example illustrates how + padding is used and how length fields are calculated. Also note that + AVPs may be present in the Grouped AVP value which the receiver + cannot interpret (here, the Recover-Policy and Futuristic-Acct-Record + AVPs). + + + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 51] + +RFC 3588 Diameter Based Protocol September 2003 + + + This AVP would be encoded as follows: + + 0 1 2 3 4 5 6 7 + +-------+-------+-------+-------+-------+-------+-------+-------+ + 0 | Example AVP Header (AVP Code = 999999), Length = 468 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 8 | Origin-Host AVP Header (AVP Code = 264), Length = 19 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 16 | 'e' | 'x' | 'a' | 'm' | 'p' | 'l' | 'e' | '.' | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 24 | 'c' | 'o' | 'm' |Padding| Session-Id AVP Header | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 32 | (AVP Code = 263), Length = 50 | 'g' | 'r' | 'u' | 'm' | + +-------+-------+-------+-------+-------+-------+-------+-------+ + . . . + +-------+-------+-------+-------+-------+-------+-------+-------+ + 64 | 'A' | 'F' | '3' | 'B' | '8' | '1' |Padding|Padding| + +-------+-------+-------+-------+-------+-------+-------+-------+ + 72 | Session-Id AVP Header (AVP Code = 263), Length = 51 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 80 | 'g' | 'r' | 'u' | 'm' | 'p' | '.' | 'e' | 'x' | + +-------+-------+-------+-------+-------+-------+-------+-------+ + . . . + +-------+-------+-------+-------+-------+-------+-------+-------+ + 104 | '0' | 'A' | 'F' | '3' | 'B' | '8' | '2' |Padding| + +-------+-------+-------+-------+-------+-------+-------+-------+ + 112 | Recovery-Policy Header (AVP Code = 8341), Length = 223 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + 120 | 0x21 | 0x63 | 0xbc | 0x1d | 0x0a | 0xd8 | 0x23 | 0x71 | + +-------+-------+-------+-------+-------+-------+-------+-------+ + . . . + +-------+-------+-------+-------+-------+-------+-------+-------+ + 320 | 0x2f | 0xd7 | 0x96 | 0x6b | 0x8c | 0x7f | 0x92 |Padding| + +-------+-------+-------+-------+-------+-------+-------+-------+ + 328 | Futuristic-Acct-Record Header (AVP Code = 15930), Length = 137| + +-------+-------+-------+-------+-------+-------+-------+-------+ + 336 | 0xfe | 0x19 | 0xda | 0x58 | 0x02 | 0xac | 0xd9 | 0x8b | + +-------+-------+-------+-------+-------+-------+-------+-------+ + . . . + +-------+-------+-------+-------+-------+-------+-------+-------+ + 464 | 0x41 |Padding|Padding|Padding| + +-------+-------+-------+-------+ + + + + + + + + + +Calhoun, et al. Standards Track [Page 52] + +RFC 3588 Diameter Based Protocol September 2003 + + +4.5. Diameter Base Protocol AVPs + + The following table describes the Diameter AVPs defined in the base + protocol, their AVP Code values, types, possible flag values and + whether the AVP MAY be encrypted. For the originator of a Diameter + message, "Encr" (Encryption) means that if a message containing that + AVP is to be sent via a Diameter agent (proxy, redirect or relay) + then the message MUST NOT be sent unless there is end-to-end security + between the originator and the recipient and integrity / + confidentiality protection is offered for this AVP OR the originator + has locally trusted configuration that indicates that end-to-end + security is not needed. Similarly, for the originator of a Diameter + message, a "P" in the "MAY" column means that if a message containing + that AVP is to be sent via a Diameter agent (proxy, redirect or + relay) then the message MUST NOT be sent unless there is end-to-end + security between the originator and the recipient or the originator + has locally trusted configuration that indicates that end-to-end + security is not needed. + + Due to space constraints, the short form DiamIdent is used to + represent DiameterIdentity. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 53] + +RFC 3588 Diameter Based Protocol September 2003 + + + +---------------------+ + | AVP Flag rules | + |----+-----+----+-----|----+ + AVP Section | | |SHLD| MUST| | + Attribute Name Code Defined Data Type |MUST| MAY | NOT| NOT|Encr| + -----------------------------------------|----+-----+----+-----|----| + Acct- 85 9.8.2 Unsigned32 | M | P | | V | Y | + Interim-Interval | | | | | | + Accounting- 483 9.8.7 Enumerated | M | P | | V | Y | + Realtime-Required | | | | | | + Acct- 50 9.8.5 UTF8String | M | P | | V | Y | + Multi-Session-Id | | | | | | + Accounting- 485 9.8.3 Unsigned32 | M | P | | V | Y | + Record-Number | | | | | | + Accounting- 480 9.8.1 Enumerated | M | P | | V | Y | + Record-Type | | | | | | + Accounting- 44 9.8.4 OctetString| M | P | | V | Y | + Session-Id | | | | | | + Accounting- 287 9.8.6 Unsigned64 | M | P | | V | Y | + Sub-Session-Id | | | | | | + Acct- 259 6.9 Unsigned32 | M | P | | V | N | + Application-Id | | | | | | + Auth- 258 6.8 Unsigned32 | M | P | | V | N | + Application-Id | | | | | | + Auth-Request- 274 8.7 Enumerated | M | P | | V | N | + Type | | | | | | + Authorization- 291 8.9 Unsigned32 | M | P | | V | N | + Lifetime | | | | | | + Auth-Grace- 276 8.10 Unsigned32 | M | P | | V | N | + Period | | | | | | + Auth-Session- 277 8.11 Enumerated | M | P | | V | N | + State | | | | | | + Re-Auth-Request- 285 8.12 Enumerated | M | P | | V | N | + Type | | | | | | + Class 25 8.20 OctetString| M | P | | V | Y | + Destination-Host 293 6.5 DiamIdent | M | P | | V | N | + Destination- 283 6.6 DiamIdent | M | P | | V | N | + Realm | | | | | | + Disconnect-Cause 273 5.4.3 Enumerated | M | P | | V | N | + E2E-Sequence AVP 300 6.15 Grouped | M | P | | V | Y | + Error-Message 281 7.3 UTF8String | | P | | V,M | N | + Error-Reporting- 294 7.4 DiamIdent | | P | | V,M | N | + Host | | | | | | + Event-Timestamp 55 8.21 Time | M | P | | V | N | + Experimental- 297 7.6 Grouped | M | P | | V | N | + Result | | | | | | + -----------------------------------------|----+-----+----+-----|----| + + + + +Calhoun, et al. Standards Track [Page 54] + +RFC 3588 Diameter Based Protocol September 2003 + + + +---------------------+ + | AVP Flag rules | + |----+-----+----+-----|----+ + AVP Section | | |SHLD| MUST|MAY | + Attribute Name Code Defined Data Type |MUST| MAY | NOT| NOT|Encr| + -----------------------------------------|----+-----+----+-----|----| + Experimental- 298 7.7 Unsigned32 | M | P | | V | N | + Result-Code | | | | | | + Failed-AVP 279 7.5 Grouped | M | P | | V | N | + Firmware- 267 5.3.4 Unsigned32 | | | |P,V,M| N | + Revision | | | | | | + Host-IP-Address 257 5.3.5 Address | M | P | | V | N | + Inband-Security | M | P | | V | N | + -Id 299 6.10 Unsigned32 | | | | | | + Multi-Round- 272 8.19 Unsigned32 | M | P | | V | Y | + Time-Out | | | | | | + Origin-Host 264 6.3 DiamIdent | M | P | | V | N | + Origin-Realm 296 6.4 DiamIdent | M | P | | V | N | + Origin-State-Id 278 8.16 Unsigned32 | M | P | | V | N | + Product-Name 269 5.3.7 UTF8String | | | |P,V,M| N | + Proxy-Host 280 6.7.3 DiamIdent | M | | | P,V | N | + Proxy-Info 284 6.7.2 Grouped | M | | | P,V | N | + Proxy-State 33 6.7.4 OctetString| M | | | P,V | N | + Redirect-Host 292 6.12 DiamURI | M | P | | V | N | + Redirect-Host- 261 6.13 Enumerated | M | P | | V | N | + Usage | | | | | | + Redirect-Max- 262 6.14 Unsigned32 | M | P | | V | N | + Cache-Time | | | | | | + Result-Code 268 7.1 Unsigned32 | M | P | | V | N | + Route-Record 282 6.7.1 DiamIdent | M | | | P,V | N | + Session-Id 263 8.8 UTF8String | M | P | | V | Y | + Session-Timeout 27 8.13 Unsigned32 | M | P | | V | N | + Session-Binding 270 8.17 Unsigned32 | M | P | | V | Y | + Session-Server- 271 8.18 Enumerated | M | P | | V | Y | + Failover | | | | | | + Supported- 265 5.3.6 Unsigned32 | M | P | | V | N | + Vendor-Id | | | | | | + Termination- 295 8.15 Enumerated | M | P | | V | N | + Cause | | | | | | + User-Name 1 8.14 UTF8String | M | P | | V | Y | + Vendor-Id 266 5.3.3 Unsigned32 | M | P | | V | N | + Vendor-Specific- 260 6.11 Grouped | M | P | | V | N | + Application-Id | | | | | | + -----------------------------------------|----+-----+----+-----|----| + + + + + + + +Calhoun, et al. Standards Track [Page 55] + +RFC 3588 Diameter Based Protocol September 2003 + + +5. Diameter Peers + + This section describes how Diameter nodes establish connections and + communicate with peers. + +5.1. Peer Connections + + Although a Diameter node may have many possible peers that it is able + to communicate with, it may not be economical to have an established + connection to all of them. At a minimum, a Diameter node SHOULD have + an established connection with two peers per realm, known as the + primary and secondary peers. Of course, a node MAY have additional + connections, if it is deemed necessary. Typically, all messages for + a realm are sent to the primary peer, but in the event that failover + procedures are invoked, any pending requests are sent to the + secondary peer. However, implementations are free to load balance + requests between a set of peers. + + Note that a given peer MAY act as a primary for a given realm, while + acting as a secondary for another realm. + + When a peer is deemed suspect, which could occur for various reasons, + including not receiving a DWA within an allotted timeframe, no new + requests should be forwarded to the peer, but failover procedures are + invoked. When an active peer is moved to this mode, additional + connections SHOULD be established to ensure that the necessary number + of active connections exists. + + There are two ways that a peer is removed from the suspect peer list: + + 1. The peer is no longer reachable, causing the transport connection + to be shutdown. The peer is moved to the closed state. + + 2. Three watchdog messages are exchanged with accepted round trip + times, and the connection to the peer is considered stabilized. + + In the event the peer being removed is either the primary or + secondary, an alternate peer SHOULD replace the deleted peer, and + assume the role of either primary or secondary. + +5.2. Diameter Peer Discovery + + Allowing for dynamic Diameter agent discovery will make it possible + for simpler and more robust deployment of Diameter services. In + order to promote interoperable implementations of Diameter peer + discovery, the following mechanisms are described. These are based + + + + + +Calhoun, et al. Standards Track [Page 56] + +RFC 3588 Diameter Based Protocol September 2003 + + + on existing IETF standards. The first option (manual configuration) + MUST be supported by all DIAMETER nodes, while the latter two options + (SRVLOC and DNS) MAY be supported. + + There are two cases where Diameter peer discovery may be performed. + The first is when a Diameter client needs to discover a first-hop + Diameter agent. The second case is when a Diameter agent needs to + discover another agent - for further handling of a Diameter + operation. In both cases, the following 'search order' is + recommended: + + 1. The Diameter implementation consults its list of static (manually) + configured Diameter agent locations. These will be used if they + exist and respond. + + 2. The Diameter implementation uses SLPv2 [SLP] to discover Diameter + services. The Diameter service template [TEMPLATE] is included in + Appendix A. + + It is recommended that SLPv2 security be deployed (this requires + distributing keys to SLPv2 agents). This is discussed further in + Appendix A. SLPv2 security SHOULD be used (requiring distribution + of keys to SLPv2 agents) in order to ensure that discovered peers + are authorized for their roles. SLPv2 is discussed further in + Appendix A. + + 3. The Diameter implementation performs a NAPTR query for a server in + a particular realm. The Diameter implementation has to know in + advance which realm to look for a Diameter agent in. This could + be deduced, for example, from the 'realm' in a NAI that a Diameter + implementation needed to perform a Diameter operation on. + + 3.1 The services relevant for the task of transport protocol + selection are those with NAPTR service fields with values + "AAA+D2x", where x is a letter that corresponds to a transport + protocol supported by the domain. This specification defines + D2T for TCP and D2S for SCTP. We also establish an IANA + registry for NAPTR service name to transport protocol + mappings. + + These NAPTR records provide a mapping from a domain, to the + SRV record for contacting a server with the specific transport + protocol in the NAPTR services field. The resource record + will contain an empty regular expression and a replacement + value, which is the SRV record for that particular transport + protocol. If the server supports multiple transport + protocols, there will be multiple NAPTR records, each with a + different service value. As per RFC 2915 [NAPTR], the client + + + +Calhoun, et al. Standards Track [Page 57] + +RFC 3588 Diameter Based Protocol September 2003 + + + discards any records whose services fields are not applicable. + For the purposes of this specification, several rules are + defined. + + 3.2 A client MUST discard any service fields that identify a + resolution service whose value is not "D2X", for values of X + that indicate transport protocols supported by the client. + The NAPTR processing as described in RFC 2915 will result in + discovery of the most preferred transport protocol of the + server that is supported by the client, as well as an SRV + record for the server. + + The domain suffixes in the NAPTR replacement field SHOULD + match the domain of the original query. + + 4. If no NAPTR records are found, the requester queries for those + address records for the destination address, + '_diameter._sctp'.realm or '_diameter._tcp'.realm. Address + records include A RR's, AAAA RR's or other similar records, chosen + according to the requestor's network protocol capabilities. If + the DNS server returns no address records, the requestor gives up. + + If the server is using a site certificate, the domain name in the + query and the domain name in the replacement field MUST both be + valid based on the site certificate handed out by the server in + the TLS or IKE exchange. Similarly, the domain name in the SRV + query and the domain name in the target in the SRV record MUST + both be valid based on the same site certificate. Otherwise, an + attacker could modify the DNS records to contain replacement + values in a different domain, and the client could not validate + that this was the desired behavior, or the result of an attack + + Also, the Diameter Peer MUST check to make sure that the + discovered peers are authorized to act in its role. + Authentication via IKE or TLS, or validation of DNS RRs via DNSSEC + is not sufficient to conclude this. For example, a web server may + have obtained a valid TLS certificate, and secured RRs may be + included in the DNS, but this does not imply that it is authorized + to act as a Diameter Server. + + Authorization can be achieved for example, by configuration of a + Diameter Server CA. Alternatively this can be achieved by + definition of OIDs within TLS or IKE certificates so as to signify + Diameter Server authorization. + + A dynamically discovered peer causes an entry in the Peer Table (see + Section 2.6) to be created. Note that entries created via DNS MUST + expire (or be refreshed) within the DNS TTL. If a peer is discovered + + + +Calhoun, et al. Standards Track [Page 58] + +RFC 3588 Diameter Based Protocol September 2003 + + + outside of the local realm, a routing table entry (see Section 2.7) + for the peer's realm is created. The routing table entry's + expiration MUST match the peer's expiration value. + +5.3. Capabilities Exchange + + When two Diameter peers establish a transport connection, they MUST + exchange the Capabilities Exchange messages, as specified in the peer + state machine (see Section 5.6). This message allows the discovery + of a peer's identity and its capabilities (protocol version number, + supported Diameter applications, security mechanisms, etc.) + + The receiver only issues commands to its peers that have advertised + support for the Diameter application that defines the command. A + Diameter node MUST cache the supported applications in order to + ensure that unrecognized commands and/or AVPs are not unnecessarily + sent to a peer. + + A receiver of a Capabilities-Exchange-Req (CER) message that does not + have any applications in common with the sender MUST return a + Capabilities-Exchange-Answer (CEA) with the Result-Code AVP set to + DIAMETER_NO_COMMON_APPLICATION, and SHOULD disconnect the transport + layer connection. Note that receiving a CER or CEA from a peer + advertising itself as a Relay (see Section 2.4) MUST be interpreted + as having common applications with the peer. + + Similarly, a receiver of a Capabilities-Exchange-Req (CER) message + that does not have any security mechanisms in common with the sender + MUST return a Capabilities-Exchange-Answer (CEA) with the Result-Code + AVP set to DIAMETER_NO_COMMON_SECURITY, and SHOULD disconnect the + transport layer connection. + + CERs received from unknown peers MAY be silently discarded, or a CEA + MAY be issued with the Result-Code AVP set to DIAMETER_UNKNOWN_PEER. + In both cases, the transport connection is closed. If the local + policy permits receiving CERs from unknown hosts, a successful CEA + MAY be returned. If a CER from an unknown peer is answered with a + successful CEA, the lifetime of the peer entry is equal to the + lifetime of the transport connection. In case of a transport + failure, all the pending transactions destined to the unknown peer + can be discarded. + + The CER and CEA messages MUST NOT be proxied, redirected or relayed. + + Since the CER/CEA messages cannot be proxied, it is still possible + that an upstream agent receives a message for which it has no + available peers to handle the application that corresponds to the + Command-Code. In such instances, the 'E' bit is set in the answer + + + +Calhoun, et al. Standards Track [Page 59] + +RFC 3588 Diameter Based Protocol September 2003 + + + message (see Section 7.) with the Result-Code AVP set to + DIAMETER_UNABLE_TO_DELIVER to inform the downstream to take action + (e.g., re-routing request to an alternate peer). + + With the exception of the Capabilities-Exchange-Request message, a + message of type Request that includes the Auth-Application-Id or + Acct-Application-Id AVPs, or a message with an application-specific + command code, MAY only be forwarded to a host that has explicitly + advertised support for the application (or has advertised the Relay + Application Identifier). + +5.3.1. Capabilities-Exchange-Request + + The Capabilities-Exchange-Request (CER), indicated by the Command- + Code set to 257 and the Command Flags' 'R' bit set, is sent to + exchange local capabilities. Upon detection of a transport failure, + this message MUST NOT be sent to an alternate peer. + + When Diameter is run over SCTP [SCTP], which allows for connections + to span multiple interfaces and multiple IP addresses, the + Capabilities-Exchange-Request message MUST contain one Host-IP- + Address AVP for each potential IP address that MAY be locally used + when transmitting Diameter messages. + + Message Format + + <CER> ::= < Diameter Header: 257, REQ > + { Origin-Host } + { Origin-Realm } + 1* { Host-IP-Address } + { Vendor-Id } + { Product-Name } + [ Origin-State-Id ] + * [ Supported-Vendor-Id ] + * [ Auth-Application-Id ] + * [ Inband-Security-Id ] + * [ Acct-Application-Id ] + * [ Vendor-Specific-Application-Id ] + [ Firmware-Revision ] + * [ AVP ] + +5.3.2. Capabilities-Exchange-Answer + + The Capabilities-Exchange-Answer (CEA), indicated by the Command-Code + set to 257 and the Command Flags' 'R' bit cleared, is sent in + response to a CER message. + + + + + +Calhoun, et al. Standards Track [Page 60] + +RFC 3588 Diameter Based Protocol September 2003 + + + When Diameter is run over SCTP [SCTP], which allows connections to + span multiple interfaces, hence, multiple IP addresses, the + Capabilities-Exchange-Answer message MUST contain one Host-IP-Address + AVP for each potential IP address that MAY be locally used when + transmitting Diameter messages. + + Message Format + + <CEA> ::= < Diameter Header: 257 > + { Result-Code } + { Origin-Host } + { Origin-Realm } + 1* { Host-IP-Address } + { Vendor-Id } + { Product-Name } + [ Origin-State-Id ] + [ Error-Message ] + * [ Failed-AVP ] + * [ Supported-Vendor-Id ] + * [ Auth-Application-Id ] + * [ Inband-Security-Id ] + * [ Acct-Application-Id ] + * [ Vendor-Specific-Application-Id ] + [ Firmware-Revision ] + * [ AVP ] + +5.3.3. Vendor-Id AVP + + The Vendor-Id AVP (AVP Code 266) is of type Unsigned32 and contains + the IANA "SMI Network Management Private Enterprise Codes" [ASSIGNNO] + value assigned to the vendor of the Diameter application. In + combination with the Supported-Vendor-Id AVP (Section 5.3.6), this + MAY be used in order to know which vendor specific attributes may be + sent to the peer. It is also envisioned that the combination of the + Vendor-Id, Product-Name (Section 5.3.7) and the Firmware-Revision + (Section 5.3.4) AVPs MAY provide very useful debugging information. + + A Vendor-Id value of zero in the CER or CEA messages is reserved and + indicates that this field is ignored. + +5.3.4. Firmware-Revision AVP + + The Firmware-Revision AVP (AVP Code 267) is of type Unsigned32 and is + used to inform a Diameter peer of the firmware revision of the + issuing device. + + + + + + +Calhoun, et al. Standards Track [Page 61] + +RFC 3588 Diameter Based Protocol September 2003 + + + For devices that do not have a firmware revision (general purpose + computers running Diameter software modules, for instance), the + revision of the Diameter software module may be reported instead. + +5.3.5. Host-IP-Address AVP + + The Host-IP-Address AVP (AVP Code 257) is of type Address and is used + to inform a Diameter peer of the sender's IP address. All source + addresses that a Diameter node expects to use with SCTP [SCTP] MUST + be advertised in the CER and CEA messages by including a Host-IP- + Address AVP for each address. This AVP MUST ONLY be used in the CER + and CEA messages. + +5.3.6. Supported-Vendor-Id AVP + + The Supported-Vendor-Id AVP (AVP Code 265) is of type Unsigned32 and + contains the IANA "SMI Network Management Private Enterprise Codes" + [ASSIGNNO] value assigned to a vendor other than the device vendor. + This is used in the CER and CEA messages in order to inform the peer + that the sender supports (a subset of) the vendor-specific AVPs + defined by the vendor identified in this AVP. + +5.3.7. Product-Name AVP + + The Product-Name AVP (AVP Code 269) is of type UTF8String, and + contains the vendor assigned name for the product. The Product-Name + AVP SHOULD remain constant across firmware revisions for the same + product. + +5.4. Disconnecting Peer connections + + When a Diameter node disconnects one of its transport connections, + its peer cannot know the reason for the disconnect, and will most + likely assume that a connectivity problem occurred, or that the peer + has rebooted. In these cases, the peer may periodically attempt to + reconnect, as stated in Section 2.1. In the event that the + disconnect was a result of either a shortage of internal resources, + or simply that the node in question has no intentions of forwarding + any Diameter messages to the peer in the foreseeable future, a + periodic connection request would not be welcomed. The + Disconnection-Reason AVP contains the reason the Diameter node issued + the Disconnect-Peer-Request message. + + The Disconnect-Peer-Request message is used by a Diameter node to + inform its peer of its intent to disconnect the transport layer, and + that the peer shouldn't reconnect unless it has a valid reason to do + so (e.g., message to be forwarded). Upon receipt of the message, the + + + + +Calhoun, et al. Standards Track [Page 62] + +RFC 3588 Diameter Based Protocol September 2003 + + + Disconnect-Peer-Answer is returned, which SHOULD contain an error if + messages have recently been forwarded, and are likely in flight, + which would otherwise cause a race condition. + + The receiver of the Disconnect-Peer-Answer initiates the transport + disconnect. + +5.4.1. Disconnect-Peer-Request + + The Disconnect-Peer-Request (DPR), indicated by the Command-Code set + to 282 and the Command Flags' 'R' bit set, is sent to a peer to + inform its intentions to shutdown the transport connection. Upon + detection of a transport failure, this message MUST NOT be sent to an + alternate peer. + + Message Format + + <DPR> ::= < Diameter Header: 282, REQ > + { Origin-Host } + { Origin-Realm } + { Disconnect-Cause } + +5.4.2. Disconnect-Peer-Answer + + The Disconnect-Peer-Answer (DPA), indicated by the Command-Code set + to 282 and the Command Flags' 'R' bit cleared, is sent as a response + to the Disconnect-Peer-Request message. Upon receipt of this + message, the transport connection is shutdown. + + Message Format + + <DPA> ::= < Diameter Header: 282 > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ Error-Message ] + * [ Failed-AVP ] + +5.4.3. Disconnect-Cause AVP + + The Disconnect-Cause AVP (AVP Code 273) is of type Enumerated. A + Diameter node MUST include this AVP in the Disconnect-Peer-Request + message to inform the peer of the reason for its intention to + shutdown the transport connection. The following values are + supported: + + + + + + +Calhoun, et al. Standards Track [Page 63] + +RFC 3588 Diameter Based Protocol September 2003 + + + REBOOTING 0 + A scheduled reboot is imminent. + + BUSY 1 + The peer's internal resources are constrained, and it has + determined that the transport connection needs to be closed. + + DO_NOT_WANT_TO_TALK_TO_YOU 2 + The peer has determined that it does not see a need for the + transport connection to exist, since it does not expect any + messages to be exchanged in the near future. + +5.5. Transport Failure Detection + + Given the nature of the Diameter protocol, it is recommended that + transport failures be detected as soon as possible. Detecting such + failures will minimize the occurrence of messages sent to unavailable + agents, resulting in unnecessary delays, and will provide better + failover performance. The Device-Watchdog-Request and Device- + Watchdog-Answer messages, defined in this section, are used to pro- + actively detect transport failures. + +5.5.1. Device-Watchdog-Request + + The Device-Watchdog-Request (DWR), indicated by the Command-Code set + to 280 and the Command Flags' 'R' bit set, is sent to a peer when no + traffic has been exchanged between two peers (see Section 5.5.3). + Upon detection of a transport failure, this message MUST NOT be sent + to an alternate peer. + + Message Format + + <DWR> ::= < Diameter Header: 280, REQ > + { Origin-Host } + { Origin-Realm } + [ Origin-State-Id ] + +5.5.2. Device-Watchdog-Answer + + The Device-Watchdog-Answer (DWA), indicated by the Command-Code set + to 280 and the Command Flags' 'R' bit cleared, is sent as a response + to the Device-Watchdog-Request message. + + + + + + + + + +Calhoun, et al. Standards Track [Page 64] + +RFC 3588 Diameter Based Protocol September 2003 + + + Message Format + + <DWA> ::= < Diameter Header: 280 > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ Error-Message ] + * [ Failed-AVP ] + [ Original-State-Id ] + +5.5.3. Transport Failure Algorithm + + The transport failure algorithm is defined in [AAATRANS]. All + Diameter implementations MUST support the algorithm defined in the + specification in order to be compliant to the Diameter base protocol. + +5.5.4. Failover and Failback Procedures + + In the event that a transport failure is detected with a peer, it is + necessary for all pending request messages to be forwarded to an + alternate agent, if possible. This is commonly referred to as + failover. + + In order for a Diameter node to perform failover procedures, it is + necessary for the node to maintain a pending message queue for a + given peer. When an answer message is received, the corresponding + request is removed from the queue. The Hop-by-Hop Identifier field + is used to match the answer with the queued request. + + When a transport failure is detected, if possible all messages in the + queue are sent to an alternate agent with the T flag set. On booting + a Diameter client or agent, the T flag is also set on any records + still remaining to be transmitted in non-volatile storage. An + example of a case where it is not possible to forward the message to + an alternate server is when the message has a fixed destination, and + the unavailable peer is the message's final destination (see + Destination-Host AVP). Such an error requires that the agent return + an answer message with the 'E' bit set and the Result-Code AVP set to + DIAMETER_UNABLE_TO_DELIVER. + + It is important to note that multiple identical requests or answers + MAY be received as a result of a failover. The End-to-End Identifier + field in the Diameter header along with the Origin-Host AVP MUST be + used to identify duplicate messages. + + + + + + + +Calhoun, et al. Standards Track [Page 65] + +RFC 3588 Diameter Based Protocol September 2003 + + + As described in Section 2.1, a connection request should be + periodically attempted with the failed peer in order to re-establish + the transport connection. Once a connection has been successfully + established, messages can once again be forwarded to the peer. This + is commonly referred to as failback. + +5.6. Peer State Machine + + This section contains a finite state machine that MUST be observed by + all Diameter implementations. Each Diameter node MUST follow the + state machine described below when communicating with each peer. + Multiple actions are separated by commas, and may continue on + succeeding lines, as space requires. Similarly, state and next state + may also span multiple lines, as space requires. + + This state machine is closely coupled with the state machine + described in [AAATRANS], which is used to open, close, failover, + probe, and reopen transport connections. Note in particular that + [AAATRANS] requires the use of watchdog messages to probe + connections. For Diameter, DWR and DWA messages are to be used. + + I- is used to represent the initiator (connecting) connection, while + the R- is used to represent the responder (listening) connection. + The lack of a prefix indicates that the event or action is the same + regardless of the connection on which the event occurred. + + The stable states that a state machine may be in are Closed, I-Open + and R-Open; all other states are intermediate. Note that I-Open and + R-Open are equivalent except for whether the initiator or responder + transport connection is used for communication. + + A CER message is always sent on the initiating connection immediately + after the connection request is successfully completed. In the case + of an election, one of the two connections will shut down. The + responder connection will survive if the Origin-Host of the local + Diameter entity is higher than that of the peer; the initiator + connection will survive if the peer's Origin-Host is higher. All + subsequent messages are sent on the surviving connection. Note that + the results of an election on one peer are guaranteed to be the + inverse of the results on the other. + + For TLS usage, a TLS handshake will begin when both ends are in the + open state. If the TLS handshake is successful, all further messages + will be sent via TLS. If the handshake fails, both ends move to the + closed state. + + The state machine constrains only the behavior of a Diameter + implementation as seen by Diameter peers through events on the wire. + + + +Calhoun, et al. Standards Track [Page 66] + +RFC 3588 Diameter Based Protocol September 2003 + + + Any implementation that produces equivalent results is considered + compliant. + + state event action next state + ----------------------------------------------------------------- + Closed Start I-Snd-Conn-Req Wait-Conn-Ack + R-Conn-CER R-Accept, R-Open + Process-CER, + R-Snd-CEA + + Wait-Conn-Ack I-Rcv-Conn-Ack I-Snd-CER Wait-I-CEA + I-Rcv-Conn-Nack Cleanup Closed + R-Conn-CER R-Accept, Wait-Conn-Ack/ + Process-CER Elect + Timeout Error Closed + + Wait-I-CEA I-Rcv-CEA Process-CEA I-Open + R-Conn-CER R-Accept, Wait-Returns + Process-CER, + Elect + I-Peer-Disc I-Disc Closed + I-Rcv-Non-CEA Error Closed + Timeout Error Closed + + Wait-Conn-Ack/ I-Rcv-Conn-Ack I-Snd-CER,Elect Wait-Returns + Elect I-Rcv-Conn-Nack R-Snd-CEA R-Open + R-Peer-Disc R-Disc Wait-Conn-Ack + R-Conn-CER R-Reject Wait-Conn-Ack/ + Elect + Timeout Error Closed + + Wait-Returns Win-Election I-Disc,R-Snd-CEA R-Open + I-Peer-Disc I-Disc, R-Open + R-Snd-CEA + I-Rcv-CEA R-Disc I-Open + R-Peer-Disc R-Disc Wait-I-CEA + R-Conn-CER R-Reject Wait-Returns + Timeout Error Closed + + R-Open Send-Message R-Snd-Message R-Open + R-Rcv-Message Process R-Open + R-Rcv-DWR Process-DWR, R-Open + R-Snd-DWA + R-Rcv-DWA Process-DWA R-Open + R-Conn-CER R-Reject R-Open + Stop R-Snd-DPR Closing + R-Rcv-DPR R-Snd-DPA, Closed + R-Disc + + + +Calhoun, et al. Standards Track [Page 67] + +RFC 3588 Diameter Based Protocol September 2003 + + + R-Peer-Disc R-Disc Closed + R-Rcv-CER R-Snd-CEA R-Open + R-Rcv-CEA Process-CEA R-Open + + I-Open Send-Message I-Snd-Message I-Open + I-Rcv-Message Process I-Open + I-Rcv-DWR Process-DWR, I-Open + I-Snd-DWA + I-Rcv-DWA Process-DWA I-Open + R-Conn-CER R-Reject I-Open + Stop I-Snd-DPR Closing + I-Rcv-DPR I-Snd-DPA, Closed + I-Disc + I-Peer-Disc I-Disc Closed + I-Rcv-CER I-Snd-CEA I-Open + I-Rcv-CEA Process-CEA I-Open + + Closing I-Rcv-DPA I-Disc Closed + R-Rcv-DPA R-Disc Closed + Timeout Error Closed + I-Peer-Disc I-Disc Closed + R-Peer-Disc R-Disc Closed + +5.6.1. Incoming connections + + When a connection request is received from a Diameter peer, it is + not, in the general case, possible to know the identity of that peer + until a CER is received from it. This is because host and port + determine the identity of a Diameter peer; and the source port of an + incoming connection is arbitrary. Upon receipt of CER, the identity + of the connecting peer can be uniquely determined from Origin-Host. + + For this reason, a Diameter peer must employ logic separate from the + state machine to receive connection requests, accept them, and await + CER. Once CER arrives on a new connection, the Origin-Host that + identifies the peer is used to locate the state machine associated + with that peer, and the new connection and CER are passed to the + state machine as an R-Conn-CER event. + + The logic that handles incoming connections SHOULD close and discard + the connection if any message other than CER arrives, or if an + implementation-defined timeout occurs prior to receipt of CER. + + Because handling of incoming connections up to and including receipt + of CER requires logic, separate from that of any individual state + machine associated with a particular peer, it is described separately + in this section rather than in the state machine above. + + + + +Calhoun, et al. Standards Track [Page 68] + +RFC 3588 Diameter Based Protocol September 2003 + + +5.6.2. Events + + Transitions and actions in the automaton are caused by events. In + this section, we will ignore the -I and -R prefix, since the actual + event would be identical, but would occur on one of two possible + connections. + + Start The Diameter application has signaled that a + connection should be initiated with the peer. + + R-Conn-CER An acknowledgement is received stating that the + transport connection has been established, and the + associated CER has arrived. + + Rcv-Conn-Ack A positive acknowledgement is received confirming that + the transport connection is established. + + Rcv-Conn-Nack A negative acknowledgement was received stating that + the transport connection was not established. + + Timeout An application-defined timer has expired while waiting + for some event. + + Rcv-CER A CER message from the peer was received. + + Rcv-CEA A CEA message from the peer was received. + + Rcv-Non-CEA A message other than CEA from the peer was received. + + Peer-Disc A disconnection indication from the peer was received. + + Rcv-DPR A DPR message from the peer was received. + + Rcv-DPA A DPA message from the peer was received. + + Win-Election An election was held, and the local node was the + winner. + + Send-Message A message is to be sent. + + Rcv-Message A message other than CER, CEA, DPR, DPA, DWR or DWA + was received. + + Stop The Diameter application has signaled that a + connection should be terminated (e.g., on system + shutdown). + + + + + +Calhoun, et al. Standards Track [Page 69] + +RFC 3588 Diameter Based Protocol September 2003 + + +5.6.3. Actions + + Actions in the automaton are caused by events and typically indicate + the transmission of packets and/or an action to be taken on the + connection. In this section we will ignore the I- and R-prefix, + since the actual action would be identical, but would occur on one of + two possible connections. + + Snd-Conn-Req A transport connection is initiated with the peer. + + Accept The incoming connection associated with the R-Conn-CER + is accepted as the responder connection. + + Reject The incoming connection associated with the R-Conn-CER + is disconnected. + + Process-CER The CER associated with the R-Conn-CER is processed. + + Snd-CER A CER message is sent to the peer. + + Snd-CEA A CEA message is sent to the peer. + + Cleanup If necessary, the connection is shutdown, and any + local resources are freed. + + Error The transport layer connection is disconnected, either + politely or abortively, in response to an error + condition. Local resources are freed. + + Process-CEA A received CEA is processed. + + Snd-DPR A DPR message is sent to the peer. + + Snd-DPA A DPA message is sent to the peer. + + Disc The transport layer connection is disconnected, and + local resources are freed. + + Elect An election occurs (see Section 5.6.4 for more + information). + + Snd-Message A message is sent. + + Snd-DWR A DWR message is sent. + + Snd-DWA A DWA message is sent. + + Process-DWR The DWR message is serviced. + + + +Calhoun, et al. Standards Track [Page 70] + +RFC 3588 Diameter Based Protocol September 2003 + + + Process-DWA The DWA message is serviced. + + Process A message is serviced. + +5.6.4. The Election Process + + The election is performed on the responder. The responder compares + the Origin-Host received in the CER sent by its peer with its own + Origin-Host. If the local Diameter entity's Origin-Host is higher + than the peer's, a Win-Election event is issued locally. + + The comparison proceeds by considering the shorter OctetString to be + padded with zeros so that it length is the same as the length of the + longer, then performing an octet-by-octet unsigned comparison with + the first octet being most significant. Any remaining octets are + assumed to have value 0x80. + +6. Diameter message processing + + This section describes how Diameter requests and answers are created + and processed. + +6.1. Diameter Request Routing Overview + + A request is sent towards its final destination using a combination + of the Destination-Realm and Destination-Host AVPs, in one of these + three combinations: + + - a request that is not able to be proxied (such as CER) MUST NOT + contain either Destination-Realm or Destination-Host AVPs. + + - a request that needs to be sent to a home server serving a + specific realm, but not to a specific server (such as the first + request of a series of round-trips), MUST contain a Destination- + Realm AVP, but MUST NOT contain a Destination-Host AVP. + + - otherwise, a request that needs to be sent to a specific home + server among those serving a given realm, MUST contain both the + Destination-Realm and Destination-Host AVPs. + + The Destination-Host AVP is used as described above when the + destination of the request is fixed, which includes: + + - Authentication requests that span multiple round trips + + - A Diameter message that uses a security mechanism that makes use + of a pre-established session key shared between the source and the + final destination of the message. + + + +Calhoun, et al. Standards Track [Page 71] + +RFC 3588 Diameter Based Protocol September 2003 + + + - Server initiated messages that MUST be received by a specific + Diameter client (e.g., access device), such as the Abort-Session- + Request message, which is used to request that a particular user's + session be terminated. + + Note that an agent can forward a request to a host described in the + Destination-Host AVP only if the host in question is included in its + peer table (see Section 2.7). Otherwise, the request is routed based + on the Destination-Realm only (see Sections 6.1.6). + + The Destination-Realm AVP MUST be present if the message is + proxiable. Request messages that may be forwarded by Diameter agents + (proxies, redirects or relays) MUST also contain an Acct- + Application-Id AVP, an Auth-Application-Id AVP or a Vendor-Specific- + Application-Id AVP. A message that MUST NOT be forwarded by Diameter + agents (proxies, redirects or relays) MUST not include the + Destination-Realm in its ABNF. The value of the Destination-Realm + AVP MAY be extracted from the User-Name AVP, or other application- + specific methods. + + When a message is received, the message is processed in the following + order: + + 1. If the message is destined for the local host, the procedures + listed in Section 6.1.4 are followed. + + 2. If the message is intended for a Diameter peer with whom the local + host is able to directly communicate, the procedures listed in + Section 6.1.5 are followed. This is known as Request Forwarding. + + 3. The procedures listed in Section 6.1.6 are followed, which is + known as Request Routing. + + 4. If none of the above is successful, an answer is returned with the + Result-Code set to DIAMETER_UNABLE_TO_DELIVER, with the E-bit set. + + For routing of Diameter messages to work within an administrative + domain, all Diameter nodes within the realm MUST be peers. + + Note the processing rules contained in this section are intended to + be used as general guidelines to Diameter developers. Certain + implementations MAY use different methods than the ones described + here, and still comply with the protocol specification. See Section + 7 for more detail on error handling. + + + + + + + +Calhoun, et al. Standards Track [Page 72] + +RFC 3588 Diameter Based Protocol September 2003 + + +6.1.1. Originating a Request + + When creating a request, in addition to any other procedures + described in the application definition for that specific request, + the following procedures MUST be followed: + + - the Command-Code is set to the appropriate value + + - the 'R' bit is set + + - the End-to-End Identifier is set to a locally unique value + + - the Origin-Host and Origin-Realm AVPs MUST be set to the + appropriate values, used to identify the source of the message + + - the Destination-Host and Destination-Realm AVPs MUST be set to the + appropriate values as described in Section 6.1. + + - an Acct-Application-Id AVP, an Auth-Application-Id or a Vendor- + Specific-Application-Id AVP must be included if the request is + proxiable. + +6.1.2. Sending a Request + + When sending a request, originated either locally, or as the result + of a forwarding or routing operation, the following procedures MUST + be followed: + + - the Hop-by-Hop Identifier should be set to a locally unique value + + - The message should be saved in the list of pending requests. + + Other actions to perform on the message based on the particular role + the agent is playing are described in the following sections. + +6.1.3. Receiving Requests + + A relay or proxy agent MUST check for forwarding loops when receiving + requests. A loop is detected if the server finds its own identity in + a Route-Record AVP. When such an event occurs, the agent MUST answer + with the Result-Code AVP set to DIAMETER_LOOP_DETECTED. + +6.1.4. Processing Local Requests + + A request is known to be for local consumption when one of the + following conditions occur: + + - The Destination-Host AVP contains the local host's identity, + + + +Calhoun, et al. Standards Track [Page 73] + +RFC 3588 Diameter Based Protocol September 2003 + + + - The Destination-Host AVP is not present, the Destination-Realm AVP + contains a realm the server is configured to process locally, and + the Diameter application is locally supported, or + + - Both the Destination-Host and the Destination-Realm are not + present. + + When a request is locally processed, the rules in Section 6.2 should + be used to generate the corresponding answer. + +6.1.5. Request Forwarding + + Request forwarding is done using the Diameter Peer Table. The + Diameter peer table contains all of the peers that the local node is + able to directly communicate with. + + When a request is received, and the host encoded in the Destination- + Host AVP is one that is present in the peer table, the message SHOULD + be forwarded to the peer. + +6.1.6. Request Routing + + Diameter request message routing is done via realms and applications. + A Diameter message that may be forwarded by Diameter agents (proxies, + redirects or relays) MUST include the target realm in the + Destination-Realm AVP and one of the application identification AVPs + Auth-Application-Id, Acct-Application-Id or Vendor-Specific- + Application-Id. The realm MAY be retrieved from the User-Name AVP, + which is in the form of a Network Access Identifier (NAI). The realm + portion of the NAI is inserted in the Destination-Realm AVP. + + Diameter agents MAY have a list of locally supported realms and + applications, and MAY have a list of externally supported realms and + applications. When a request is received that includes a realm + and/or application that is not locally supported, the message is + routed to the peer configured in the Realm Routing Table (see Section + 2.7). + +6.1.7. Redirecting requests + + When a redirect agent receives a request whose routing entry is set + to REDIRECT, it MUST reply with an answer message with the 'E' bit + set, while maintaining the Hop-by-Hop Identifier in the header, and + include the Result-Code AVP to DIAMETER_REDIRECT_INDICATION. Each of + the servers associated with the routing entry are added in separate + Redirect-Host AVP. + + + + + +Calhoun, et al. Standards Track [Page 74] + +RFC 3588 Diameter Based Protocol September 2003 + + + +------------------+ + | Diameter | + | Redirect Agent | + +------------------+ + ^ | 2. command + 'E' bit + 1. Request | | Result-Code = + [email protected] | | DIAMETER_REDIRECT_INDICATION + + | | Redirect-Host AVP(s) + | v + +-------------+ 3. Request +-------------+ + | example.com |------------->| example.net | + | Relay | | Diameter | + | Agent |<-------------| Server | + +-------------+ 4. Answer +-------------+ + + Figure 5: Diameter Redirect Agent + + The receiver of the answer message with the 'E' bit set, and the + Result-Code AVP set to DIAMETER_REDIRECT_INDICATION uses the hop-by- + hop field in the Diameter header to identify the request in the + pending message queue (see Section 5.3) that is to be redirected. If + no transport connection exists with the new agent, one is created, + and the request is sent directly to it. + + Multiple Redirect-Host AVPs are allowed. The receiver of the answer + message with the 'E' bit set selects exactly one of these hosts as + the destination of the redirected message. + +6.1.8. Relaying and Proxying Requests + + A relay or proxy agent MUST append a Route-Record AVP to all requests + forwarded. The AVP contains the identity of the peer the request was + received from. + + The Hop-by-Hop identifier in the request is saved, and replaced with + a locally unique value. The source of the request is also saved, + which includes the IP address, port and protocol. + + A relay or proxy agent MAY include the Proxy-Info AVP in requests if + it requires access to any local state information when the + corresponding response is received. Proxy-Info AVP has certain + security implications and SHOULD contain an embedded HMAC with a + node-local key. Alternatively, it MAY simply use local storage to + store state information. + + The message is then forwarded to the next hop, as identified in the + Realm Routing Table. + + + + +Calhoun, et al. Standards Track [Page 75] + +RFC 3588 Diameter Based Protocol September 2003 + + + Figure 6 provides an example of message routing using the procedures + listed in these sections. + + (Origin-Host=nas.mno.net) (Origin-Host=nas.mno.net) + (Origin-Realm=mno.net) (Origin-Realm=mno.net) + (Destination-Realm=example.com) (Destination- + Realm=example.com) + (Route-Record=nas.example.net) + +------+ ------> +------+ ------> +------+ + | | (Request) | | (Request) | | + | NAS +-------------------+ DRL +-------------------+ HMS | + | | | | | | + +------+ <------ +------+ <------ +------+ + example.net (Answer) example.net (Answer) example.com + (Origin-Host=hms.example.com) (Origin-Host=hms.example.com) + (Origin-Realm=example.com) (Origin-Realm=example.com) + + Figure 6: Routing of Diameter messages + +6.2. Diameter Answer Processing + + When a request is locally processed, the following procedures MUST be + applied to create the associated answer, in addition to any + additional procedures that MAY be discussed in the Diameter + application defining the command: + + - The same Hop-by-Hop identifier in the request is used in the + answer. + + - The local host's identity is encoded in the Origin-Host AVP. + + - The Destination-Host and Destination-Realm AVPs MUST NOT be + present in the answer message. + + - The Result-Code AVP is added with its value indicating success or + failure. + + - If the Session-Id is present in the request, it MUST be included + in the answer. + + - Any Proxy-Info AVPs in the request MUST be added to the answer + message, in the same order they were present in the request. + + - The 'P' bit is set to the same value as the one in the request. + + - The same End-to-End identifier in the request is used in the + answer. + + + + +Calhoun, et al. Standards Track [Page 76] + +RFC 3588 Diameter Based Protocol September 2003 + + + Note that the error messages (see Section 7.3) are also subjected to + the above processing rules. + +6.2.1. Processing received Answers + + A Diameter client or proxy MUST match the Hop-by-Hop Identifier in an + answer received against the list of pending requests. The + corresponding message should be removed from the list of pending + requests. It SHOULD ignore answers received that do not match a + known Hop-by-Hop Identifier. + +6.2.2. Relaying and Proxying Answers + + If the answer is for a request which was proxied or relayed, the + agent MUST restore the original value of the Diameter header's Hop- + by-Hop Identifier field. + + If the last Proxy-Info AVP in the message is targeted to the local + Diameter server, the AVP MUST be removed before the answer is + forwarded. + + If a relay or proxy agent receives an answer with a Result-Code AVP + indicating a failure, it MUST NOT modify the contents of the AVP. + Any additional local errors detected SHOULD be logged, but not + reflected in the Result-Code AVP. If the agent receives an answer + message with a Result-Code AVP indicating success, and it wishes to + modify the AVP to indicate an error, it MUST modify the Result-Code + AVP to contain the appropriate error in the message destined towards + the access device as well as include the Error-Reporting-Host AVP and + it MUST issue an STR on behalf of the access device. + + The agent MUST then send the answer to the host that it received the + original request from. + +6.3. Origin-Host AVP + + The Origin-Host AVP (AVP Code 264) is of type DiameterIdentity, and + MUST be present in all Diameter messages. This AVP identifies the + endpoint that originated the Diameter message. Relay agents MUST NOT + modify this AVP. + + The value of the Origin-Host AVP is guaranteed to be unique within a + single host. + + Note that the Origin-Host AVP may resolve to more than one address as + the Diameter peer may support more than one address. + + + + + +Calhoun, et al. Standards Track [Page 77] + +RFC 3588 Diameter Based Protocol September 2003 + + + This AVP SHOULD be placed as close to the Diameter header as + possible. 6.10 + +6.4. Origin-Realm AVP + + The Origin-Realm AVP (AVP Code 296) is of type DiameterIdentity. + This AVP contains the Realm of the originator of any Diameter message + and MUST be present in all messages. + + This AVP SHOULD be placed as close to the Diameter header as + possible. + +6.5. Destination-Host AVP + + The Destination-Host AVP (AVP Code 293) is of type DiameterIdentity. + This AVP MUST be present in all unsolicited agent initiated messages, + MAY be present in request messages, and MUST NOT be present in Answer + messages. + + The absence of the Destination-Host AVP will cause a message to be + sent to any Diameter server supporting the application within the + realm specified in Destination-Realm AVP. + + This AVP SHOULD be placed as close to the Diameter header as + possible. + +6.6. Destination-Realm AVP + + The Destination-Realm AVP (AVP Code 283) is of type DiameterIdentity, + and contains the realm the message is to be routed to. The + Destination-Realm AVP MUST NOT be present in Answer messages. + Diameter Clients insert the realm portion of the User-Name AVP. + Diameter servers initiating a request message use the value of the + Origin-Realm AVP from a previous message received from the intended + target host (unless it is known a priori). When present, the + Destination-Realm AVP is used to perform message routing decisions. + + Request messages whose ABNF does not list the Destination-Realm AVP + as a mandatory AVP are inherently non-routable messages. + + This AVP SHOULD be placed as close to the Diameter header as + possible. + +6.7. Routing AVPs + + The AVPs defined in this section are Diameter AVPs used for routing + purposes. These AVPs change as Diameter messages are processed by + agents, and therefore MUST NOT be protected by end-to-end security. + + + +Calhoun, et al. Standards Track [Page 78] + +RFC 3588 Diameter Based Protocol September 2003 + + +6.7.1. Route-Record AVP + + The Route-Record AVP (AVP Code 282) is of type DiameterIdentity. The + identity added in this AVP MUST be the same as the one received in + the Origin-Host of the Capabilities Exchange message. + +6.7.2. Proxy-Info AVP + + The Proxy-Info AVP (AVP Code 284) is of type Grouped. The Grouped + Data field has the following ABNF grammar: + + Proxy-Info ::= < AVP Header: 284 > + { Proxy-Host } + { Proxy-State } + * [ AVP ] + +6.7.3. Proxy-Host AVP + + The Proxy-Host AVP (AVP Code 280) is of type DiameterIdentity. This + AVP contains the identity of the host that added the Proxy-Info AVP. + +6.7.4. Proxy-State AVP + + The Proxy-State AVP (AVP Code 33) is of type OctetString, and + contains state local information, and MUST be treated as opaque data. + +6.8. Auth-Application-Id AVP + + The Auth-Application-Id AVP (AVP Code 258) is of type Unsigned32 and + is used in order to advertise support of the Authentication and + Authorization portion of an application (see Section 2.4). The + Auth-Application-Id MUST also be present in all Authentication and/or + Authorization messages that are defined in a separate Diameter + specification and have an Application ID assigned. + +6.9. Acct-Application-Id AVP + + The Acct-Application-Id AVP (AVP Code 259) is of type Unsigned32 and + is used in order to advertise support of the Accounting portion of an + application (see Section 2.4). The Acct-Application-Id MUST also be + present in all Accounting messages. Exactly one of the Auth- + Application-Id and Acct-Application-Id AVPs MAY be present. + +6.10. Inband-Security-Id AVP + + The Inband-Security-Id AVP (AVP Code 299) is of type Unsigned32 and + is used in order to advertise support of the Security portion of the + application. + + + +Calhoun, et al. Standards Track [Page 79] + +RFC 3588 Diameter Based Protocol September 2003 + + + Currently, the following values are supported, but there is ample + room to add new security Ids. + + NO_INBAND_SECURITY 0 + This peer does not support TLS. This is the default value, if the + AVP is omitted. + + TLS 1 + This node supports TLS security, as defined by [TLS]. + +6.11. Vendor-Specific-Application-Id AVP + + The Vendor-Specific-Application-Id AVP (AVP Code 260) is of type + Grouped and is used to advertise support of a vendor-specific + Diameter Application. Exactly one of the Auth-Application-Id and + Acct-Application-Id AVPs MAY be present. + + This AVP MUST also be present as the first AVP in all experimental + commands defined in the vendor-specific application. + + This AVP SHOULD be placed as close to the Diameter header as + possible. + + AVP Format + + <Vendor-Specific-Application-Id> ::= < AVP Header: 260 > + 1* [ Vendor-Id ] + 0*1{ Auth-Application-Id } + 0*1{ Acct-Application-Id } + +6.12. Redirect-Host AVP + + One or more of instances of this AVP MUST be present if the answer + message's 'E' bit is set and the Result-Code AVP is set to + DIAMETER_REDIRECT_INDICATION. + + Upon receiving the above, the receiving Diameter node SHOULD forward + the request directly to one of the hosts identified in these AVPs. + The server contained in the selected Redirect-Host AVP SHOULD be used + for all messages pertaining to this session. + +6.13. Redirect-Host-Usage AVP + + The Redirect-Host-Usage AVP (AVP Code 261) is of type Enumerated. + This AVP MAY be present in answer messages whose 'E' bit is set and + the Result-Code AVP is set to DIAMETER_REDIRECT_INDICATION. + + + + + +Calhoun, et al. Standards Track [Page 80] + +RFC 3588 Diameter Based Protocol September 2003 + + + When present, this AVP dictates how the routing entry resulting from + the Redirect-Host is to be used. The following values are supported: + + DONT_CACHE 0 + The host specified in the Redirect-Host AVP should not be cached. + This is the default value. + + ALL_SESSION 1 + All messages within the same session, as defined by the same value + of the Session-ID AVP MAY be sent to the host specified in the + Redirect-Host AVP. + + ALL_REALM 2 + All messages destined for the realm requested MAY be sent to the + host specified in the Redirect-Host AVP. + + REALM_AND_APPLICATION 3 + All messages for the application requested to the realm specified + MAY be sent to the host specified in the Redirect-Host AVP. + + ALL_APPLICATION 4 + All messages for the application requested MAY be sent to the host + specified in the Redirect-Host AVP. + + ALL_HOST 5 + All messages that would be sent to the host that generated the + Redirect-Host MAY be sent to the host specified in the Redirect- + Host AVP. + + ALL_USER 6 + All messages for the user requested MAY be sent to the host + specified in the Redirect-Host AVP. + +6.14. Redirect-Max-Cache-Time AVP + + The Redirect-Max-Cache-Time AVP (AVP Code 262) is of type Unsigned32. + This AVP MUST be present in answer messages whose 'E' bit is set, the + Result-Code AVP is set to DIAMETER_REDIRECT_INDICATION and the + Redirect-Host-Usage AVP set to a non-zero value. + + This AVP contains the maximum number of seconds the peer and route + table entries, created as a result of the Redirect-Host, will be + cached. Note that once a host created due to a redirect indication + is no longer reachable, any associated peer and routing table entries + MUST be deleted. + + + + + + +Calhoun, et al. Standards Track [Page 81] + +RFC 3588 Diameter Based Protocol September 2003 + + +6.15. E2E-Sequence AVP + + The E2E-Sequence AVP (AVP Code 300) provides anti-replay protection + for end to end messages and is of type grouped. It contains a random + value (an OctetString with a nonce) and counter (an Integer). For + each end-to-end peer with which a node communicates (or remembers + communicating) a different nonce value MUST be used and the counter + is initiated at zero and increases by one each time this AVP is + emitted to that peer. This AVP MUST be included in all messages + which use end-to-end protection (e.g., CMS signing or encryption). + +7. Error Handling + + There are two different types of errors in Diameter; protocol and + application errors. A protocol error is one that occurs at the base + protocol level, and MAY require per hop attention (e.g., message + routing error). Application errors, on the other hand, generally + occur due to a problem with a function specified in a Diameter + application (e.g., user authentication, Missing AVP). + + Result-Code AVP values that are used to report protocol errors MUST + only be present in answer messages whose 'E' bit is set. When a + request message is received that causes a protocol error, an answer + message is returned with the 'E' bit set, and the Result-Code AVP is + set to the appropriate protocol error value. As the answer is sent + back towards the originator of the request, each proxy or relay agent + MAY take action on the message. + + 1. Request +---------+ Link Broken + +-------------------------->|Diameter |----///----+ + | +---------------------| | v + +------+--+ | 2. answer + 'E' set | Relay 2 | +--------+ + |Diameter |<-+ (Unable to Forward) +---------+ |Diameter| + | | | Home | + | Relay 1 |--+ +---------+ | Server | + +---------+ | 3. Request |Diameter | +--------+ + +-------------------->| | ^ + | Relay 3 |-----------+ + +---------+ + + Figure 7: Example of Protocol Error causing answer message + + Figure 7 provides an example of a message forwarded upstream by a + Diameter relay. When the message is received by Relay 2, and it + detects that it cannot forward the request to the home server, an + answer message is returned with the 'E' bit set and the Result-Code + AVP set to DIAMETER_UNABLE_TO_DELIVER. Given that this error falls + + + + +Calhoun, et al. Standards Track [Page 82] + +RFC 3588 Diameter Based Protocol September 2003 + + + within the protocol error category, Relay 1 would take special + action, and given the error, attempt to route the message through its + alternate Relay 3. + + +---------+ 1. Request +---------+ 2. Request +---------+ + | Access |------------>|Diameter |------------>|Diameter | + | | | | | Home | + | Device |<------------| Relay |<------------| Server | + +---------+ 4. Answer +---------+ 3. Answer +---------+ + (Missing AVP) (Missing AVP) + + Figure 8: Example of Application Error Answer message + + Figure 8 provides an example of a Diameter message that caused an + application error. When application errors occur, the Diameter + entity reporting the error clears the 'R' bit in the Command Flags, + and adds the Result-Code AVP with the proper value. Application + errors do not require any proxy or relay agent involvement, and + therefore the message would be forwarded back to the originator of + the request. + + There are certain Result-Code AVP application errors that require + additional AVPs to be present in the answer. In these cases, the + Diameter node that sets the Result-Code AVP to indicate the error + MUST add the AVPs. Examples are: + + - An unrecognized AVP is received with the 'M' bit (Mandatory bit) + set, causes an answer to be sent with the Result-Code AVP set to + DIAMETER_AVP_UNSUPPORTED, and the Failed-AVP AVP containing the + offending AVP. + + - An AVP that is received with an unrecognized value causes an + answer to be returned with the Result-Code AVP set to + DIAMETER_INVALID_AVP_VALUE, with the Failed-AVP AVP containing the + AVP causing the error. + + - A command is received with an AVP that is omitted, yet is + mandatory according to the command's ABNF. The receiver issues an + answer with the Result-Code set to DIAMETER_MISSING_AVP, and + creates an AVP with the AVP Code and other fields set as expected + in the missing AVP. The created AVP is then added to the Failed- + AVP AVP. + + The Result-Code AVP describes the error that the Diameter node + encountered in its processing. In case there are multiple errors, + the Diameter node MUST report only the first error it encountered + + + + + +Calhoun, et al. Standards Track [Page 83] + +RFC 3588 Diameter Based Protocol September 2003 + + + (detected possibly in some implementation dependent order). The + specific errors that can be described by this AVP are described in + the following section. + +7.1. Result-Code AVP + + The Result-Code AVP (AVP Code 268) is of type Unsigned32 and + indicates whether a particular request was completed successfully or + whether an error occurred. All Diameter answer messages defined in + IETF applications MUST include one Result-Code AVP. A non-successful + Result-Code AVP (one containing a non 2xxx value other than + DIAMETER_REDIRECT_INDICATION) MUST include the Error-Reporting-Host + AVP if the host setting the Result-Code AVP is different from the + identity encoded in the Origin-Host AVP. + + The Result-Code data field contains an IANA-managed 32-bit address + space representing errors (see Section 11.4). Diameter provides the + following classes of errors, all identified by the thousands digit in + the decimal notation: + + - 1xxx (Informational) + - 2xxx (Success) + - 3xxx (Protocol Errors) + - 4xxx (Transient Failures) + - 5xxx (Permanent Failure) + + A non-recognized class (one whose first digit is not defined in this + section) MUST be handled as a permanent failure. + +7.1.1. Informational + + Errors that fall within this category are used to inform the + requester that a request could not be satisfied, and additional + action is required on its part before access is granted. + + DIAMETER_MULTI_ROUND_AUTH 1001 + This informational error is returned by a Diameter server to + inform the access device that the authentication mechanism being + used requires multiple round trips, and a subsequent request needs + to be issued in order for access to be granted. + +7.1.2. Success + + Errors that fall within the Success category are used to inform a + peer that a request has been successfully completed. + + DIAMETER_SUCCESS 2001 + The Request was successfully completed. + + + +Calhoun, et al. Standards Track [Page 84] + +RFC 3588 Diameter Based Protocol September 2003 + + + DIAMETER_LIMITED_SUCCESS 2002 + When returned, the request was successfully completed, but + additional processing is required by the application in order to + provide service to the user. + +7.1.3. Protocol Errors + + Errors that fall within the Protocol Error category SHOULD be treated + on a per-hop basis, and Diameter proxies MAY attempt to correct the + error, if it is possible. Note that these and only these errors MUST + only be used in answer messages whose 'E' bit is set. + + DIAMETER_COMMAND_UNSUPPORTED 3001 + The Request contained a Command-Code that the receiver did not + recognize or support. This MUST be used when a Diameter node + receives an experimental command that it does not understand. + + DIAMETER_UNABLE_TO_DELIVER 3002 + This error is given when Diameter can not deliver the message to + the destination, either because no host within the realm + supporting the required application was available to process the + request, or because Destination-Host AVP was given without the + associated Destination-Realm AVP. + + DIAMETER_REALM_NOT_SERVED 3003 + The intended realm of the request is not recognized. + + DIAMETER_TOO_BUSY 3004 + When returned, a Diameter node SHOULD attempt to send the message + to an alternate peer. This error MUST only be used when a + specific server is requested, and it cannot provide the requested + service. + + DIAMETER_LOOP_DETECTED 3005 + An agent detected a loop while trying to get the message to the + intended recipient. The message MAY be sent to an alternate peer, + if one is available, but the peer reporting the error has + identified a configuration problem. + + DIAMETER_REDIRECT_INDICATION 3006 + A redirect agent has determined that the request could not be + satisfied locally and the initiator of the request should direct + the request directly to the server, whose contact information has + been added to the response. When set, the Redirect-Host AVP MUST + be present. + + DIAMETER_APPLICATION_UNSUPPORTED 3007 + A request was sent for an application that is not supported. + + + +Calhoun, et al. Standards Track [Page 85] + +RFC 3588 Diameter Based Protocol September 2003 + + + DIAMETER_INVALID_HDR_BITS 3008 + A request was received whose bits in the Diameter header were + either set to an invalid combination, or to a value that is + inconsistent with the command code's definition. + + DIAMETER_INVALID_AVP_BITS 3009 + A request was received that included an AVP whose flag bits are + set to an unrecognized value, or that is inconsistent with the + AVP's definition. + + DIAMETER_UNKNOWN_PEER 3010 + A CER was received from an unknown peer. + +7.1.4. Transient Failures + + Errors that fall within the transient failures category are used + to inform a peer that the request could not be satisfied at the + time it was received, but MAY be able to satisfy the request in + the future. + + DIAMETER_AUTHENTICATION_REJECTED 4001 + The authentication process for the user failed, most likely due to + an invalid password used by the user. Further attempts MUST only + be tried after prompting the user for a new password. + + DIAMETER_OUT_OF_SPACE 4002 + A Diameter node received the accounting request but was unable to + commit it to stable storage due to a temporary lack of space. + + ELECTION_LOST 4003 + The peer has determined that it has lost the election process and + has therefore disconnected the transport connection. + +7.1.5. Permanent Failures + + Errors that fall within the permanent failures category are used + to inform the peer that the request failed, and should not be + attempted again. + + DIAMETER_AVP_UNSUPPORTED 5001 + The peer received a message that contained an AVP that is not + recognized or supported and was marked with the Mandatory bit. A + Diameter message with this error MUST contain one or more Failed- + AVP AVP containing the AVPs that caused the failure. + + DIAMETER_UNKNOWN_SESSION_ID 5002 + The request contained an unknown Session-Id. + + + + +Calhoun, et al. Standards Track [Page 86] + +RFC 3588 Diameter Based Protocol September 2003 + + + DIAMETER_AUTHORIZATION_REJECTED 5003 + A request was received for which the user could not be authorized. + This error could occur if the service requested is not permitted + to the user. + + DIAMETER_INVALID_AVP_VALUE 5004 + The request contained an AVP with an invalid value in its data + portion. A Diameter message indicating this error MUST include + the offending AVPs within a Failed-AVP AVP. + + DIAMETER_MISSING_AVP 5005 + The request did not contain an AVP that is required by the Command + Code definition. If this value is sent in the Result-Code AVP, a + Failed-AVP AVP SHOULD be included in the message. The Failed-AVP + AVP MUST contain an example of the missing AVP complete with the + Vendor-Id if applicable. The value field of the missing AVP + should be of correct minimum length and contain zeroes. + + DIAMETER_RESOURCES_EXCEEDED 5006 + A request was received that cannot be authorized because the user + has already expended allowed resources. An example of this error + condition is a user that is restricted to one dial-up PPP port, + attempts to establish a second PPP connection. + + DIAMETER_CONTRADICTING_AVPS 5007 + The Home Diameter server has detected AVPs in the request that + contradicted each other, and is not willing to provide service to + the user. One or more Failed-AVP AVPs MUST be present, containing + the AVPs that contradicted each other. + + DIAMETER_AVP_NOT_ALLOWED 5008 + A message was received with an AVP that MUST NOT be present. The + Failed-AVP AVP MUST be included and contain a copy of the + offending AVP. + + DIAMETER_AVP_OCCURS_TOO_MANY_TIMES 5009 + A message was received that included an AVP that appeared more + often than permitted in the message definition. The Failed-AVP + AVP MUST be included and contain a copy of the first instance of + the offending AVP that exceeded the maximum number of occurrences + + DIAMETER_NO_COMMON_APPLICATION 5010 + This error is returned when a CER message is received, and there + are no common applications supported between the peers. + + DIAMETER_UNSUPPORTED_VERSION 5011 + This error is returned when a request was received, whose version + number is unsupported. + + + +Calhoun, et al. Standards Track [Page 87] + +RFC 3588 Diameter Based Protocol September 2003 + + + DIAMETER_UNABLE_TO_COMPLY 5012 + This error is returned when a request is rejected for unspecified + reasons. + + DIAMETER_INVALID_BIT_IN_HEADER 5013 + This error is returned when an unrecognized bit in the Diameter + header is set to one (1). + + DIAMETER_INVALID_AVP_LENGTH 5014 + The request contained an AVP with an invalid length. A Diameter + message indicating this error MUST include the offending AVPs + within a Failed-AVP AVP. + + DIAMETER_INVALID_MESSAGE_LENGTH 5015 + This error is returned when a request is received with an invalid + message length. + + DIAMETER_INVALID_AVP_BIT_COMBO 5016 + The request contained an AVP with which is not allowed to have the + given value in the AVP Flags field. A Diameter message indicating + this error MUST include the offending AVPs within a Failed-AVP + AVP. + + DIAMETER_NO_COMMON_SECURITY 5017 + This error is returned when a CER message is received, and there + are no common security mechanisms supported between the peers. A + Capabilities-Exchange-Answer (CEA) MUST be returned with the + Result-Code AVP set to DIAMETER_NO_COMMON_SECURITY. + +7.2. Error Bit + + The 'E' (Error Bit) in the Diameter header is set when the request + caused a protocol-related error (see Section 7.1.3). A message with + the 'E' bit MUST NOT be sent as a response to an answer message. + Note that a message with the 'E' bit set is still subjected to the + processing rules defined in Section 6.2. When set, the answer + message will not conform to the ABNF specification for the command, + and will instead conform to the following ABNF: + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 88] + +RFC 3588 Diameter Based Protocol September 2003 + + + Message Format + + <answer-message> ::= < Diameter Header: code, ERR [PXY] > + 0*1< Session-Id > + { Origin-Host } + { Origin-Realm } + { Result-Code } + [ Origin-State-Id ] + [ Error-Reporting-Host ] + [ Proxy-Info ] + * [ AVP ] + + Note that the code used in the header is the same than the one found + in the request message, but with the 'R' bit cleared and the 'E' bit + set. The 'P' bit in the header is set to the same value as the one + found in the request message. + +7.3. Error-Message AVP + + The Error-Message AVP (AVP Code 281) is of type UTF8String. It MAY + accompany a Result-Code AVP as a human readable error message. The + Error-Message AVP is not intended to be useful in real-time, and + SHOULD NOT be expected to be parsed by network entities. + +7.4. Error-Reporting-Host AVP + + The Error-Reporting-Host AVP (AVP Code 294) is of type + DiameterIdentity. This AVP contains the identity of the Diameter + host that sent the Result-Code AVP to a value other than 2001 + (Success), only if the host setting the Result-Code is different from + the one encoded in the Origin-Host AVP. This AVP is intended to be + used for troubleshooting purposes, and MUST be set when the Result- + Code AVP indicates a failure. + +7.5. Failed-AVP AVP + + The Failed-AVP AVP (AVP Code 279) is of type Grouped and provides + debugging information in cases where a request is rejected or not + fully processed due to erroneous information in a specific AVP. The + value of the Result-Code AVP will provide information on the reason + for the Failed-AVP AVP. + + The possible reasons for this AVP are the presence of an improperly + constructed AVP, an unsupported or unrecognized AVP, an invalid AVP + value, the omission of a required AVP, the presence of an explicitly + excluded AVP (see tables in Section 10), or the presence of two or + more occurrences of an AVP which is restricted to 0, 1, or 0-1 + occurrences. + + + +Calhoun, et al. Standards Track [Page 89] + +RFC 3588 Diameter Based Protocol September 2003 + + + A Diameter message MAY contain one Failed-AVP AVP, containing the + entire AVP that could not be processed successfully. If the failure + reason is omission of a required AVP, an AVP with the missing AVP + code, the missing vendor id, and a zero filled payload of the minimum + required length for the omitted AVP will be added. + + AVP Format + + <Failed-AVP> ::= < AVP Header: 279 > + 1* {AVP} + +7.6. Experimental-Result AVP + + The Experimental-Result AVP (AVP Code 297) is of type Grouped, and + indicates whether a particular vendor-specific request was completed + successfully or whether an error occurred. Its Data field has the + following ABNF grammar: + + AVP Format + + Experimental-Result ::= < AVP Header: 297 > + { Vendor-Id } + { Experimental-Result-Code } + + The Vendor-Id AVP (see Section 5.3.3) in this grouped AVP identifies + the vendor responsible for the assignment of the result code which + follows. All Diameter answer messages defined in vendor-specific + applications MUST include either one Result-Code AVP or one + Experimental-Result AVP. + +7.7. Experimental-Result-Code AVP + + The Experimental-Result-Code AVP (AVP Code 298) is of type Unsigned32 + and contains a vendor-assigned value representing the result of + processing the request. + + It is recommended that vendor-specific result codes follow the same + conventions given for the Result-Code AVP regarding the different + types of result codes and the handling of errors (for non 2xxx + values). + +8. Diameter User Sessions + + Diameter can provide two different types of services to applications. + The first involves authentication and authorization, and can + optionally make use of accounting. The second only makes use of + accounting. + + + + +Calhoun, et al. Standards Track [Page 90] + +RFC 3588 Diameter Based Protocol September 2003 + + + When a service makes use of the authentication and/or authorization + portion of an application, and a user requests access to the network, + the Diameter client issues an auth request to its local server. The + auth request is defined in a service specific Diameter application + (e.g., NASREQ). The request contains a Session-Id AVP, which is used + in subsequent messages (e.g., subsequent authorization, accounting, + etc) relating to the user's session. The Session-Id AVP is a means + for the client and servers to correlate a Diameter message with a + user session. + + When a Diameter server authorizes a user to use network resources for + a finite amount of time, and it is willing to extend the + authorization via a future request, it MUST add the Authorization- + Lifetime AVP to the answer message. The Authorization-Lifetime AVP + defines the maximum number of seconds a user MAY make use of the + resources before another authorization request is expected by the + server. The Auth-Grace-Period AVP contains the number of seconds + following the expiration of the Authorization-Lifetime, after which + the server will release all state information related to the user's + session. Note that if payment for services is expected by the + serving realm from the user's home realm, the Authorization-Lifetime + AVP, combined with the Auth-Grace-Period AVP, implies the maximum + length of the session the home realm is willing to be fiscally + responsible for. Services provided past the expiration of the + Authorization-Lifetime and Auth-Grace-Period AVPs are the + responsibility of the access device. Of course, the actual cost of + services rendered is clearly outside the scope of the protocol. + + An access device that does not expect to send a re-authorization or a + session termination request to the server MAY include the Auth- + Session-State AVP with the value set to NO_STATE_MAINTAINED as a hint + to the server. If the server accepts the hint, it agrees that since + no session termination message will be received once service to the + user is terminated, it cannot maintain state for the session. If the + answer message from the server contains a different value in the + Auth-Session-State AVP (or the default value if the AVP is absent), + the access device MUST follow the server's directives. Note that the + value NO_STATE_MAINTAINED MUST NOT be set in subsequent re- + authorization requests and answers. + + The base protocol does not include any authorization request + messages, since these are largely application-specific and are + defined in a Diameter application document. However, the base + protocol does define a set of messages that is used to terminate user + sessions. These are used to allow servers that maintain state + information to free resources. + + + + + +Calhoun, et al. Standards Track [Page 91] + +RFC 3588 Diameter Based Protocol September 2003 + + + When a service only makes use of the Accounting portion of the + Diameter protocol, even in combination with an application, the + Session-Id is still used to identify user sessions. However, the + session termination messages are not used, since a session is + signaled as being terminated by issuing an accounting stop message. + +8.1. Authorization Session State Machine + + This section contains a set of finite state machines, representing + the life cycle of Diameter sessions, and which MUST be observed by + all Diameter implementations that make use of the authentication + and/or authorization portion of a Diameter application. The term + Service-Specific below refers to a message defined in a Diameter + application (e.g., Mobile IPv4, NASREQ). + + There are four different authorization session state machines + supported in the Diameter base protocol. The first two describe a + session in which the server is maintaining session state, indicated + by the value of the Auth-Session-State AVP (or its absence). One + describes the session from a client perspective, the other from a + server perspective. The second two state machines are used when the + server does not maintain session state. Here again, one describes + the session from a client perspective, the other from a server + perspective. + + When a session is moved to the Idle state, any resources that were + allocated for the particular session must be released. Any event not + listed in the state machines MUST be considered as an error + condition, and an answer, if applicable, MUST be returned to the + originator of the message. + + In the state table, the event 'Failure to send X' means that the + Diameter agent is unable to send command X to the desired + destination. This could be due to the peer being down, or due to the + peer sending back a transient failure or temporary protocol error + notification DIAMETER_TOO_BUSY or DIAMETER_LOOP_DETECTED in the + Result-Code AVP of the corresponding Answer command. The event 'X + successfully sent' is the complement of 'Failure to send X'. + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 92] + +RFC 3588 Diameter Based Protocol September 2003 + + + The following state machine is observed by a client when state is + maintained on the server: + + CLIENT, STATEFUL + State Event Action New State + ------------------------------------------------------------- + Idle Client or Device Requests Send Pending + access service + specific + auth req + + Idle ASR Received Send ASA Idle + for unknown session with + Result-Code + = UNKNOWN_ + SESSION_ID + + Pending Successful Service-specific Grant Open + authorization answer Access + received with default + Auth-Session-State value + + Pending Successful Service-specific Sent STR Discon + authorization answer received + but service not provided + + Pending Error processing successful Sent STR Discon + Service-specific authorization + answer + + Pending Failed Service-specific Cleanup Idle + authorization answer received + + Open User or client device Send Open + requests access to service service + specific + auth req + + Open Successful Service-specific Provide Open + authorization answer received Service + + Open Failed Service-specific Discon. Idle + authorization answer user/device + received. + + Open Session-Timeout Expires on Send STR Discon + Access Device + + + + +Calhoun, et al. Standards Track [Page 93] + +RFC 3588 Diameter Based Protocol September 2003 + + + Open ASR Received, Send ASA Discon + client will comply with with + request to end the session Result-Code + = SUCCESS, + Send STR. + + Open ASR Received, Send ASA Open + client will not comply with with + request to end the session Result-Code + != SUCCESS + + Open Authorization-Lifetime + Send STR Discon + Auth-Grace-Period expires on + access device + + Discon ASR Received Send ASA Discon + + Discon STA Received Discon. Idle + user/device + + The following state machine is observed by a server when it is + maintaining state for the session: + + SERVER, STATEFUL + State Event Action New State + ------------------------------------------------------------- + Idle Service-specific authorization Send Open + request received, and successful + user is authorized serv. + specific answer + + Idle Service-specific authorization Send Idle + request received, and failed serv. + user is not authorized specific answer + + Open Service-specific authorization Send Open + request received, and user successful + is authorized serv. specific + answer + + Open Service-specific authorization Send Idle + request received, and user failed serv. + is not authorized specific + answer, + Cleanup + + Open Home server wants to Send ASR Discon + terminate the service + + + +Calhoun, et al. Standards Track [Page 94] + +RFC 3588 Diameter Based Protocol September 2003 + + + Open Authorization-Lifetime (and Cleanup Idle + Auth-Grace-Period) expires + on home server. + + Open Session-Timeout expires on Cleanup Idle + home server + + Discon Failure to send ASR Wait, Discon + resend ASR + + Discon ASR successfully sent and Cleanup Idle + ASA Received with Result-Code + + Not ASA Received None No Change. + Discon + + Any STR Received Send STA, Idle + Cleanup. + + The following state machine is observed by a client when state is not + maintained on the server: + + CLIENT, STATELESS + State Event Action New State + ------------------------------------------------------------- + Idle Client or Device Requests Send Pending + access service + specific + auth req + + Pending Successful Service-specific Grant Open + authorization answer Access + received with Auth-Session- + State set to + NO_STATE_MAINTAINED + + Pending Failed Service-specific Cleanup Idle + authorization answer + received + + Open Session-Timeout Expires on Discon. Idle + Access Device user/device + + Open Service to user is terminated Discon. Idle + user/device + + + + + + +Calhoun, et al. Standards Track [Page 95] + +RFC 3588 Diameter Based Protocol September 2003 + + + The following state machine is observed by a server when it is not + maintaining state for the session: + + SERVER, STATELESS + State Event Action New State + ------------------------------------------------------------- + Idle Service-specific authorization Send serv. Idle + request received, and specific + successfully processed answer + +8.2. Accounting Session State Machine + + The following state machines MUST be supported for applications that + have an accounting portion or that require only accounting services. + The first state machine is to be observed by clients. + + See Section 9.7 for Accounting Command Codes and Section 9.8 for + Accounting AVPs. + + The server side in the accounting state machine depends in some cases + on the particular application. The Diameter base protocol defines a + default state machine that MUST be followed by all applications that + have not specified other state machines. This is the second state + machine in this section described below. + + The default server side state machine requires the reception of + accounting records in any order and at any time, and does not place + any standards requirement on the processing of these records. + Implementations of Diameter MAY perform checking, ordering, + correlation, fraud detection, and other tasks based on these records. + Both base Diameter AVPs as well as application specific AVPs MAY be + inspected as a part of these tasks. The tasks can happen either + immediately after record reception or in a post-processing phase. + However, as these tasks are typically application or even policy + dependent, they are not standardized by the Diameter specifications. + Applications MAY define requirements on when to accept accounting + records based on the used value of Accounting-Realtime-Required AVP, + credit limits checks, and so on. + + However, the Diameter base protocol defines one optional server side + state machine that MAY be followed by applications that require + keeping track of the session state at the accounting server. Note + that such tracking is incompatible with the ability to sustain long + duration connectivity problems. Therefore, the use of this state + machine is recommended only in applications where the value of the + Accounting-Realtime-Required AVP is DELIVER_AND_GRANT, and hence + accounting connectivity problems are required to cause the serviced + user to be disconnected. Otherwise, records produced by the client + + + +Calhoun, et al. Standards Track [Page 96] + +RFC 3588 Diameter Based Protocol September 2003 + + + may be lost by the server which no longer accepts them after the + connectivity is re-established. This state machine is the third + state machine in this section. The state machine is supervised by a + supervision session timer Ts, which the value should be reasonably + higher than the Acct_Interim_Interval value. Ts MAY be set to two + times the value of the Acct_Interim_Interval so as to avoid the + accounting session in the Diameter server to change to Idle state in + case of short transient network failure. + + Any event not listed in the state machines MUST be considered as an + error condition, and a corresponding answer, if applicable, MUST be + returned to the originator of the message. + + In the state table, the event 'Failure to send' means that the + Diameter client is unable to communicate with the desired + destination. This could be due to the peer being down, or due to the + peer sending back a transient failure or temporary protocol error + notification DIAMETER_OUT_OF_SPACE, DIAMETER_TOO_BUSY, or + DIAMETER_LOOP_DETECTED in the Result-Code AVP of the Accounting + Answer command. + + The event 'Failed answer' means that the Diameter client received a + non-transient failure notification in the Accounting Answer command. + + Note that the action 'Disconnect user/dev' MUST have an effect also + to the authorization session state table, e.g., cause the STR message + to be sent, if the given application has both + authentication/authorization and accounting portions. + + The states PendingS, PendingI, PendingL, PendingE and PendingB stand + for pending states to wait for an answer to an accounting request + related to a Start, Interim, Stop, Event or buffered record, + respectively. + + CLIENT, ACCOUNTING + State Event Action New State + ------------------------------------------------------------- + Idle Client or device requests Send PendingS + access accounting + start req. + + Idle Client or device requests Send PendingE + a one-time service accounting + event req + + Idle Records in storage Send PendingB + record + + + + +Calhoun, et al. Standards Track [Page 97] + +RFC 3588 Diameter Based Protocol September 2003 + + + PendingS Successful accounting Open + start answer received + + PendingS Failure to send and buffer Store Open + space available and realtime Start + not equal to DELIVER_AND_GRANT Record + + PendingS Failure to send and no buffer Open + space available and realtime + equal to GRANT_AND_LOSE + + PendingS Failure to send and no buffer Disconnect Idle + space available and realtime user/dev + not equal to + GRANT_AND_LOSE + + PendingS Failed accounting start answer Open + received and realtime equal + to GRANT_AND_LOSE + + PendingS Failed accounting start answer Disconnect Idle + received and realtime not user/dev + equal to GRANT_AND_LOSE + + PendingS User service terminated Store PendingS + stop + record + + Open Interim interval elapses Send PendingI + accounting + interim + record + Open User service terminated Send PendingL + accounting + stop req. + + PendingI Successful accounting interim Open + answer received + + PendingI Failure to send and (buffer Store Open + space available or old record interim + can be overwritten) and record + realtime not equal to + DELIVER_AND_GRANT + + PendingI Failure to send and no buffer Open + space available and realtime + equal to GRANT_AND_LOSE + + + +Calhoun, et al. Standards Track [Page 98] + +RFC 3588 Diameter Based Protocol September 2003 + + + PendingI Failure to send and no buffer Disconnect Idle + space available and realtime user/dev + not equal to GRANT_AND_LOSE + + PendingI Failed accounting interim Open + answer received and realtime + equal to GRANT_AND_LOSE + + PendingI Failed accounting interim Disconnect Idle + answer received and realtime user/dev + not equal to GRANT_AND_LOSE + + PendingI User service terminated Store PendingI + stop + record + PendingE Successful accounting Idle + event answer received + + PendingE Failure to send and buffer Store Idle + space available event + record + + PendingE Failure to send and no buffer Idle + space available + + PendingE Failed accounting event answer Idle + received + + PendingB Successful accounting answer Delete Idle + received record + + PendingB Failure to send Idle + + PendingB Failed accounting answer Delete Idle + received record + + PendingL Successful accounting Idle + stop answer received + + PendingL Failure to send and buffer Store Idle + space available stop + record + + PendingL Failure to send and no buffer Idle + space available + + PendingL Failed accounting stop answer Idle + received + + + +Calhoun, et al. Standards Track [Page 99] + +RFC 3588 Diameter Based Protocol September 2003 + + + SERVER, STATELESS ACCOUNTING + State Event Action New State + ------------------------------------------------------------- + + Idle Accounting start request Send Idle + received, and successfully accounting + processed. start + answer + + Idle Accounting event request Send Idle + received, and successfully accounting + processed. event + answer + + Idle Interim record received, Send Idle + and successfully processed. accounting + interim + answer + + Idle Accounting stop request Send Idle + received, and successfully accounting + processed stop answer + + Idle Accounting request received, Send Idle + no space left to store accounting + records answer, + Result-Code + = OUT_OF_ + SPACE + + SERVER, STATEFUL ACCOUNTING + State Event Action New State + ------------------------------------------------------------- + + Idle Accounting start request Send Open + received, and successfully accounting + processed. start + answer, + Start Ts + + Idle Accounting event request Send Idle + received, and successfully accounting + processed. event + answer + + + + + + + +Calhoun, et al. Standards Track [Page 100] + +RFC 3588 Diameter Based Protocol September 2003 + + + Idle Accounting request received, Send Idle + no space left to store accounting + records answer, + Result-Code + = OUT_OF_ + SPACE + + Open Interim record received, Send Open + and successfully processed. accounting + interim + answer, + Restart Ts + + Open Accounting stop request Send Idle + received, and successfully accounting + processed stop answer, + Stop Ts + + Open Accounting request received, Send Idle + no space left to store accounting + records answer, + Result-Code + = OUT_OF_ + SPACE, + Stop Ts + + Open Session supervision timer Ts Stop Ts Idle + expired + +8.3. Server-Initiated Re-Auth + + A Diameter server may initiate a re-authentication and/or re- + authorization service for a particular session by issuing a Re-Auth- + Request (RAR). + + For example, for pre-paid services, the Diameter server that + originally authorized a session may need some confirmation that the + user is still using the services. + + An access device that receives a RAR message with Session-Id equal to + a currently active session MUST initiate a re-auth towards the user, + if the service supports this particular feature. Each Diameter + application MUST state whether service-initiated re-auth is + supported, since some applications do not allow access devices to + prompt the user for re-auth. + + + + + + +Calhoun, et al. Standards Track [Page 101] + +RFC 3588 Diameter Based Protocol September 2003 + + +8.3.1. Re-Auth-Request + + The Re-Auth-Request (RAR), indicated by the Command-Code set to 258 + and the message flags' 'R' bit set, may be sent by any server to the + access device that is providing session service, to request that the + user be re-authenticated and/or re-authorized. + + Message Format + + <RAR> ::= < Diameter Header: 258, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Destination-Host } + { Auth-Application-Id } + { Re-Auth-Request-Type } + [ User-Name ] + [ Origin-State-Id ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.3.2. Re-Auth-Answer + + The Re-Auth-Answer (RAA), indicated by the Command-Code set to 258 + and the message flags' 'R' bit clear, is sent in response to the RAR. + The Result-Code AVP MUST be present, and indicates the disposition of + the request. + + A successful RAA message MUST be followed by an application-specific + authentication and/or authorization message. + + + + + + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 102] + +RFC 3588 Diameter Based Protocol September 2003 + + + Message Format + + <RAA> ::= < Diameter Header: 258, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + [ Origin-State-Id ] + [ Error-Message ] + [ Error-Reporting-Host ] + * [ Failed-AVP ] + * [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Host-Cache-Time ] + * [ Proxy-Info ] + * [ AVP ] + +8.4. Session Termination + + It is necessary for a Diameter server that authorized a session, for + which it is maintaining state, to be notified when that session is no + longer active, both for tracking purposes as well as to allow + stateful agents to release any resources that they may have provided + for the user's session. For sessions whose state is not being + maintained, this section is not used. + + When a user session that required Diameter authorization terminates, + the access device that provided the service MUST issue a Session- + Termination-Request (STR) message to the Diameter server that + authorized the service, to notify it that the session is no longer + active. An STR MUST be issued when a user session terminates for any + reason, including user logoff, expiration of Session-Timeout, + administrative action, termination upon receipt of an Abort-Session- + Request (see below), orderly shutdown of the access device, etc. + + The access device also MUST issue an STR for a session that was + authorized but never actually started. This could occur, for + example, due to a sudden resource shortage in the access device, or + because the access device is unwilling to provide the type of service + requested in the authorization, or because the access device does not + support a mandatory AVP returned in the authorization, etc. + + It is also possible that a session that was authorized is never + actually started due to action of a proxy. For example, a proxy may + modify an authorization answer, converting the result from success to + failure, prior to forwarding the message to the access device. If + the answer did not contain an Auth-Session-State AVP with the value + + + +Calhoun, et al. Standards Track [Page 103] + +RFC 3588 Diameter Based Protocol September 2003 + + + NO_STATE_MAINTAINED, a proxy that causes an authorized session not to + be started MUST issue an STR to the Diameter server that authorized + the session, since the access device has no way of knowing that the + session had been authorized. + + A Diameter server that receives an STR message MUST clean up + resources (e.g., session state) associated with the Session-Id + specified in the STR, and return a Session-Termination-Answer. + + A Diameter server also MUST clean up resources when the Session- + Timeout expires, or when the Authorization-Lifetime and the Auth- + Grace-Period AVPs expires without receipt of a re-authorization + request, regardless of whether an STR for that session is received. + The access device is not expected to provide service beyond the + expiration of these timers; thus, expiration of either of these + timers implies that the access device may have unexpectedly shut + down. + +8.4.1. Session-Termination-Request + + The Session-Termination-Request (STR), indicated by the Command-Code + set to 275 and the Command Flags' 'R' bit set, is sent by the access + device to inform the Diameter Server that an authenticated and/or + authorized session is being terminated. + + Message Format + + <STR> ::= < Diameter Header: 275, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Auth-Application-Id } + { Termination-Cause } + [ User-Name ] + [ Destination-Host ] + * [ Class ] + [ Origin-State-Id ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + + + + + + + + + + +Calhoun, et al. Standards Track [Page 104] + +RFC 3588 Diameter Based Protocol September 2003 + + +8.4.2. Session-Termination-Answer + + The Session-Termination-Answer (STA), indicated by the Command-Code + set to 275 and the message flags' 'R' bit clear, is sent by the + Diameter Server to acknowledge the notification that the session has + been terminated. The Result-Code AVP MUST be present, and MAY + contain an indication that an error occurred while servicing the STR. + + Upon sending or receipt of the STA, the Diameter Server MUST release + all resources for the session indicated by the Session-Id AVP. Any + intermediate server in the Proxy-Chain MAY also release any + resources, if necessary. + + Message Format + + <STA> ::= < Diameter Header: 275, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + * [ Class ] + [ Error-Message ] + [ Error-Reporting-Host ] + * [ Failed-AVP ] + [ Origin-State-Id ] + * [ Redirect-Host ] + [ Redirect-Host-Usage ] + ^ + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ AVP ] + +8.5. Aborting a Session + + A Diameter server may request that the access device stop providing + service for a particular session by issuing an Abort-Session-Request + (ASR). + + For example, the Diameter server that originally authorized the + session may be required to cause that session to be stopped for + credit or other reasons that were not anticipated when the session + was first authorized. On the other hand, an operator may maintain a + management server for the purpose of issuing ASRs to administratively + remove users from the network. + + An access device that receives an ASR with Session-ID equal to a + currently active session MAY stop the session. Whether the access + + + +Calhoun, et al. Standards Track [Page 105] + +RFC 3588 Diameter Based Protocol September 2003 + + + device stops the session or not is implementation- and/or + configuration-dependent. For example, an access device may honor + ASRs from certain agents only. In any case, the access device MUST + respond with an Abort-Session-Answer, including a Result-Code AVP to + indicate what action it took. + + Note that if the access device does stop the session upon receipt of + an ASR, it issues an STR to the authorizing server (which may or may + not be the agent issuing the ASR) just as it would if the session + were terminated for any other reason. + +8.5.1. Abort-Session-Request + + The Abort-Session-Request (ASR), indicated by the Command-Code set to + 274 and the message flags' 'R' bit set, may be sent by any server to + the access device that is providing session service, to request that + the session identified by the Session-Id be stopped. + + Message Format + + <ASR> ::= < Diameter Header: 274, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Destination-Host } + { Auth-Application-Id } + [ User-Name ] + [ Origin-State-Id ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.5.2. Abort-Session-Answer + + The Abort-Session-Answer (ASA), indicated by the Command-Code set to + 274 and the message flags' 'R' bit clear, is sent in response to the + ASR. The Result-Code AVP MUST be present, and indicates the + disposition of the request. + + If the session identified by Session-Id in the ASR was successfully + terminated, Result-Code is set to DIAMETER_SUCCESS. If the session + is not currently active, Result-Code is set to + DIAMETER_UNKNOWN_SESSION_ID. If the access device does not stop the + session for any other reason, Result-Code is set to + DIAMETER_UNABLE_TO_COMPLY. + + + + + +Calhoun, et al. Standards Track [Page 106] + +RFC 3588 Diameter Based Protocol September 2003 + + + Message Format + + <ASA> ::= < Diameter Header: 274, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + [ Origin-State-Id ] + [ Error-Message ] + [ Error-Reporting-Host ] + * [ Failed-AVP ] + * [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ AVP ] + +8.6. Inferring Session Termination from Origin-State-Id + + Origin-State-Id is used to allow rapid detection of terminated + sessions for which no STR would have been issued, due to + unanticipated shutdown of an access device. + + By including Origin-State-Id in CER/CEA messages, an access device + allows a next-hop server to determine immediately upon connection + whether the device has lost its sessions since the last connection. + + By including Origin-State-Id in request messages, an access device + also allows a server with which it communicates via proxy to make + such a determination. However, a server that is not directly + connected with the access device will not discover that the access + device has been restarted unless and until it receives a new request + from the access device. Thus, use of this mechanism across proxies + is opportunistic rather than reliable, but useful nonetheless. + + When a Diameter server receives an Origin-State-Id that is greater + than the Origin-State-Id previously received from the same issuer, it + may assume that the issuer has lost state since the previous message + and that all sessions that were active under the lower Origin-State- + Id have been terminated. The Diameter server MAY clean up all + session state associated with such lost sessions, and MAY also issues + STRs for all such lost sessions that were authorized on upstream + servers, to allow session state to be cleaned up globally. + + + + + + + +Calhoun, et al. Standards Track [Page 107] + +RFC 3588 Diameter Based Protocol September 2003 + + +8.7. Auth-Request-Type AVP + + The Auth-Request-Type AVP (AVP Code 274) is of type Enumerated and is + included in application-specific auth requests to inform the peers + whether a user is to be authenticated only, authorized only or both. + Note any value other than both MAY cause RADIUS interoperability + issues. The following values are defined: + + AUTHENTICATE_ONLY 1 + The request being sent is for authentication only, and MUST + contain the relevant application specific authentication AVPs that + are needed by the Diameter server to authenticate the user. + + AUTHORIZE_ONLY 2 + The request being sent is for authorization only, and MUST contain + the application specific authorization AVPs that are necessary to + identify the service being requested/offered. + + AUTHORIZE_AUTHENTICATE 3 + The request contains a request for both authentication and + authorization. The request MUST include both the relevant + application specific authentication information, and authorization + information necessary to identify the service being + requested/offered. + +8.8. Session-Id AVP + + The Session-Id AVP (AVP Code 263) is of type UTF8String and is used + to identify a specific session (see Section 8). All messages + pertaining to a specific session MUST include only one Session-Id AVP + and the same value MUST be used throughout the life of a session. + When present, the Session-Id SHOULD appear immediately following the + Diameter Header (see Section 3). + + The Session-Id MUST be globally and eternally unique, as it is meant + to uniquely identify a user session without reference to any other + information, and may be needed to correlate historical authentication + information with accounting information. The Session-Id includes a + mandatory portion and an implementation-defined portion; a + recommended format for the implementation-defined portion is outlined + below. + + The Session-Id MUST begin with the sender's identity encoded in the + DiameterIdentity type (see Section 4.4). The remainder of the + Session-Id is delimited by a ";" character, and MAY be any sequence + that the client can guarantee to be eternally unique; however, the + following format is recommended, (square brackets [] indicate an + optional element): + + + +Calhoun, et al. Standards Track [Page 108] + +RFC 3588 Diameter Based Protocol September 2003 + + + <DiameterIdentity>;<high 32 bits>;<low 32 bits>[;<optional value>] + + <high 32 bits> and <low 32 bits> are decimal representations of the + high and low 32 bits of a monotonically increasing 64-bit value. The + 64-bit value is rendered in two part to simplify formatting by 32-bit + processors. At startup, the high 32 bits of the 64-bit value MAY be + initialized to the time, and the low 32 bits MAY be initialized to + zero. This will for practical purposes eliminate the possibility of + overlapping Session-Ids after a reboot, assuming the reboot process + takes longer than a second. Alternatively, an implementation MAY + keep track of the increasing value in non-volatile memory. + + <optional value> is implementation specific but may include a modem's + device Id, a layer 2 address, timestamp, etc. + + Example, in which there is no optional value: + accesspoint7.acme.com;1876543210;523 + + Example, in which there is an optional value: + accesspoint7.acme.com;1876543210;523;[email protected] + + The Session-Id is created by the Diameter application initiating the + session, which in most cases is done by the client. Note that a + Session-Id MAY be used for both the authorization and accounting + commands of a given application. + +8.9. Authorization-Lifetime AVP + + The Authorization-Lifetime AVP (AVP Code 291) is of type Unsigned32 + and contains the maximum number of seconds of service to be provided + to the user before the user is to be re-authenticated and/or re- + authorized. Great care should be taken when the Authorization- + Lifetime value is determined, since a low, non-zero, value could + create significant Diameter traffic, which could congest both the + network and the agents. + + A value of zero (0) means that immediate re-auth is necessary by the + access device. This is typically used in cases where multiple + authentication methods are used, and a successful auth response with + this AVP set to zero is used to signal that the next authentication + method is to be immediately initiated. The absence of this AVP, or a + value of all ones (meaning all bits in the 32 bit field are set to + one) means no re-auth is expected. + + If both this AVP and the Session-Timeout AVP are present in a + message, the value of the latter MUST NOT be smaller than the + Authorization-Lifetime AVP. + + + + +Calhoun, et al. Standards Track [Page 109] + +RFC 3588 Diameter Based Protocol September 2003 + + + An Authorization-Lifetime AVP MAY be present in re-authorization + messages, and contains the number of seconds the user is authorized + to receive service from the time the re-auth answer message is + received by the access device. + + This AVP MAY be provided by the client as a hint of the maximum + lifetime that it is willing to accept. However, the server MAY + return a value that is equal to, or smaller, than the one provided by + the client. + +8.10. Auth-Grace-Period AVP + + The Auth-Grace-Period AVP (AVP Code 276) is of type Unsigned32 and + contains the number of seconds the Diameter server will wait + following the expiration of the Authorization-Lifetime AVP before + cleaning up resources for the session. + +8.11. Auth-Session-State AVP + + The Auth-Session-State AVP (AVP Code 277) is of type Enumerated and + specifies whether state is maintained for a particular session. The + client MAY include this AVP in requests as a hint to the server, but + the value in the server's answer message is binding. The following + values are supported: + + STATE_MAINTAINED 0 + This value is used to specify that session state is being + maintained, and the access device MUST issue a session termination + message when service to the user is terminated. This is the + default value. + + NO_STATE_MAINTAINED 1 + This value is used to specify that no session termination messages + will be sent by the access device upon expiration of the + Authorization-Lifetime. + +8.12. Re-Auth-Request-Type AVP + + The Re-Auth-Request-Type AVP (AVP Code 285) is of type Enumerated and + is included in application-specific auth answers to inform the client + of the action expected upon expiration of the Authorization-Lifetime. + If the answer message contains an Authorization-Lifetime AVP with a + positive value, the Re-Auth-Request-Type AVP MUST be present in an + answer message. The following values are defined: + + + + + + + +Calhoun, et al. Standards Track [Page 110] + +RFC 3588 Diameter Based Protocol September 2003 + + + AUTHORIZE_ONLY 0 + An authorization only re-auth is expected upon expiration of the + Authorization-Lifetime. This is the default value if the AVP is + not present in answer messages that include the Authorization- + Lifetime. + + AUTHORIZE_AUTHENTICATE 1 + An authentication and authorization re-auth is expected upon + expiration of the Authorization-Lifetime. + +8.13. Session-Timeout AVP + + The Session-Timeout AVP (AVP Code 27) [RADIUS] is of type Unsigned32 + and contains the maximum number of seconds of service to be provided + to the user before termination of the session. When both the + Session-Timeout and the Authorization-Lifetime AVPs are present in an + answer message, the former MUST be equal to or greater than the value + of the latter. + + A session that terminates on an access device due to the expiration + of the Session-Timeout MUST cause an STR to be issued, unless both + the access device and the home server had previously agreed that no + session termination messages would be sent (see Section 8.9). + + A Session-Timeout AVP MAY be present in a re-authorization answer + message, and contains the remaining number of seconds from the + beginning of the re-auth. + + A value of zero, or the absence of this AVP, means that this session + has an unlimited number of seconds before termination. + + This AVP MAY be provided by the client as a hint of the maximum + timeout that it is willing to accept. However, the server MAY return + a value that is equal to, or smaller, than the one provided by the + client. + +8.14. User-Name AVP + + The User-Name AVP (AVP Code 1) [RADIUS] is of type UTF8String, which + contains the User-Name, in a format consistent with the NAI + specification [NAI]. + +8.15. Termination-Cause AVP + + The Termination-Cause AVP (AVP Code 295) is of type Enumerated, and + is used to indicate the reason why a session was terminated on the + access device. The following values are defined: + + + + +Calhoun, et al. Standards Track [Page 111] + +RFC 3588 Diameter Based Protocol September 2003 + + + DIAMETER_LOGOUT 1 + The user initiated a disconnect + + DIAMETER_SERVICE_NOT_PROVIDED 2 + This value is used when the user disconnected prior to the receipt + of the authorization answer message. + + DIAMETER_BAD_ANSWER 3 + This value indicates that the authorization answer received by the + access device was not processed successfully. + + DIAMETER_ADMINISTRATIVE 4 + The user was not granted access, or was disconnected, due to + administrative reasons, such as the receipt of a Abort-Session- + Request message. + + DIAMETER_LINK_BROKEN 5 + The communication to the user was abruptly disconnected. + + DIAMETER_AUTH_EXPIRED 6 + The user's access was terminated since its authorized session time + has expired. + + DIAMETER_USER_MOVED 7 + The user is receiving services from another access device. + + DIAMETER_SESSION_TIMEOUT 8 + The user's session has timed out, and service has been terminated. + +8.16. Origin-State-Id AVP + + The Origin-State-Id AVP (AVP Code 278), of type Unsigned32, is a + monotonically increasing value that is advanced whenever a Diameter + entity restarts with loss of previous state, for example upon reboot. + Origin-State-Id MAY be included in any Diameter message, including + CER. + + A Diameter entity issuing this AVP MUST create a higher value for + this AVP each time its state is reset. A Diameter entity MAY set + Origin-State-Id to the time of startup, or it MAY use an incrementing + counter retained in non-volatile memory across restarts. + + The Origin-State-Id, if present, MUST reflect the state of the entity + indicated by Origin-Host. If a proxy modifies Origin-Host, it MUST + either remove Origin-State-Id or modify it appropriately as well. + + + + + + +Calhoun, et al. Standards Track [Page 112] + +RFC 3588 Diameter Based Protocol September 2003 + + + Typically, Origin-State-Id is used by an access device that always + starts up with no active sessions; that is, any session active prior + to restart will have been lost. By including Origin-State-Id in a + message, it allows other Diameter entities to infer that sessions + associated with a lower Origin-State-Id are no longer active. If an + access device does not intend for such inferences to be made, it MUST + either not include Origin-State-Id in any message, or set its value + to 0. + +8.17. Session-Binding AVP + + The Session-Binding AVP (AVP Code 270) is of type Unsigned32, and MAY + be present in application-specific authorization answer messages. If + present, this AVP MAY inform the Diameter client that all future + application-specific re-auth messages for this session MUST be sent + to the same authorization server. This AVP MAY also specify that a + Session-Termination-Request message for this session MUST be sent to + the same authorizing server. + + This field is a bit mask, and the following bits have been defined: + + RE_AUTH 1 + When set, future re-auth messages for this session MUST NOT + include the Destination-Host AVP. When cleared, the default + value, the Destination-Host AVP MUST be present in all re-auth + messages for this session. + + STR 2 + When set, the STR message for this session MUST NOT include the + Destination-Host AVP. When cleared, the default value, the + Destination-Host AVP MUST be present in the STR message for this + session. + + ACCOUNTING 4 + When set, all accounting messages for this session MUST NOT + include the Destination-Host AVP. When cleared, the default + value, the Destination-Host AVP, if known, MUST be present in all + accounting messages for this session. + +8.18. Session-Server-Failover AVP + + The Session-Server-Failover AVP (AVP Code 271) is of type Enumerated, + and MAY be present in application-specific authorization answer + messages that either do not include the Session-Binding AVP or + include the Session-Binding AVP with any of the bits set to a zero + value. If present, this AVP MAY inform the Diameter client that if a + + + + + +Calhoun, et al. Standards Track [Page 113] + +RFC 3588 Diameter Based Protocol September 2003 + + + re-auth or STR message fails due to a delivery problem, the Diameter + client SHOULD issue a subsequent message without the Destination-Host + AVP. When absent, the default value is REFUSE_SERVICE. + + The following values are supported: + + REFUSE_SERVICE 0 + If either the re-auth or the STR message delivery fails, terminate + service with the user, and do not attempt any subsequent attempts. + + TRY_AGAIN 1 + If either the re-auth or the STR message delivery fails, resend + the failed message without the Destination-Host AVP present. + + ALLOW_SERVICE 2 + If re-auth message delivery fails, assume that re-authorization + succeeded. If STR message delivery fails, terminate the session. + + TRY_AGAIN_ALLOW_SERVICE 3 + If either the re-auth or the STR message delivery fails, resend + the failed message without the Destination-Host AVP present. If + the second delivery fails for re-auth, assume re-authorization + succeeded. If the second delivery fails for STR, terminate the + session. + +8.19. Multi-Round-Time-Out AVP + + The Multi-Round-Time-Out AVP (AVP Code 272) is of type Unsigned32, + and SHOULD be present in application-specific authorization answer + messages whose Result-Code AVP is set to DIAMETER_MULTI_ROUND_AUTH. + This AVP contains the maximum number of seconds that the access + device MUST provide the user in responding to an authentication + request. + +8.20. Class AVP + + The Class AVP (AVP Code 25) is of type OctetString and is used to by + Diameter servers to return state information to the access device. + When one or more Class AVPs are present in application-specific + authorization answer messages, they MUST be present in subsequent + re-authorization, session termination and accounting messages. Class + AVPs found in a re-authorization answer message override the ones + found in any previous authorization answer message. Diameter server + implementations SHOULD NOT return Class AVPs that require more than + 4096 bytes of storage on the Diameter client. A Diameter client that + receives Class AVPs whose size exceeds local available storage MUST + terminate the session. + + + + +Calhoun, et al. Standards Track [Page 114] + +RFC 3588 Diameter Based Protocol September 2003 + + +8.21. Event-Timestamp AVP + + The Event-Timestamp (AVP Code 55) is of type Time, and MAY be + included in an Accounting-Request and Accounting-Answer messages to + record the time that the reported event occurred, in seconds since + January 1, 1900 00:00 UTC. + +9. Accounting + + This accounting protocol is based on a server directed model with + capabilities for real-time delivery of accounting information. + Several fault resilience methods [ACCMGMT] have been built in to the + protocol in order minimize loss of accounting data in various fault + situations and under different assumptions about the capabilities of + the used devices. + +9.1. Server Directed Model + + The server directed model means that the device generating the + accounting data gets information from either the authorization server + (if contacted) or the accounting server regarding the way accounting + data shall be forwarded. This information includes accounting record + timeliness requirements. + + As discussed in [ACCMGMT], real-time transfer of accounting records + is a requirement, such as the need to perform credit limit checks and + fraud detection. Note that batch accounting is not a requirement, + and is therefore not supported by Diameter. Should batched + accounting be required in the future, a new Diameter application will + need to be created, or it could be handled using another protocol. + Note, however, that even if at the Diameter layer accounting requests + are processed one by one, transport protocols used under Diameter + typically batch several requests in the same packet under heavy + traffic conditions. This may be sufficient for many applications. + + The authorization server (chain) directs the selection of proper + transfer strategy, based on its knowledge of the user and + relationships of roaming partnerships. The server (or agents) uses + the Acct-Interim-Interval and Accounting-Realtime-Required AVPs to + control the operation of the Diameter peer operating as a client. + The Acct-Interim-Interval AVP, when present, instructs the Diameter + node acting as a client to produce accounting records continuously + even during a session. Accounting-Realtime-Required AVP is used to + control the behavior of the client when the transfer of accounting + records from the Diameter client is delayed or unsuccessful. + + + + + + +Calhoun, et al. Standards Track [Page 115] + +RFC 3588 Diameter Based Protocol September 2003 + + + The Diameter accounting server MAY override the interim interval or + the realtime requirements by including the Acct-Interim-Interval or + Accounting-Realtime-Required AVP in the Accounting-Answer message. + When one of these AVPs is present, the latest value received SHOULD + be used in further accounting activities for the same session. + +9.2. Protocol Messages + + A Diameter node that receives a successful authentication and/or + authorization messages from the Home AAA server MUST collect + accounting information for the session. The Accounting-Request + message is used to transmit the accounting information to the Home + AAA server, which MUST reply with the Accounting-Answer message to + confirm reception. The Accounting-Answer message includes the + Result-Code AVP, which MAY indicate that an error was present in the + accounting message. A rejected Accounting-Request message MAY cause + the user's session to be terminated, depending on the value of the + Accounting-Realtime-Required AVP received earlier for the session in + question. + + Each Diameter Accounting protocol message MAY be compressed, in order + to reduce network bandwidth usage. If IPsec and IKE are used to + secure the Diameter session, then IP compression [IPComp] MAY be used + and IKE [IKE] MAY be used to negotiate the compression parameters. + If TLS is used to secure the Diameter session, then TLS compression + [TLS] MAY be used. + +9.3. Application document requirements + + Each Diameter application (e.g., NASREQ, MobileIP), MUST define their + Service-Specific AVPs that MUST be present in the Accounting-Request + message in a section entitled "Accounting AVPs". The application + MUST assume that the AVPs described in this document will be present + in all Accounting messages, so only their respective service-specific + AVPs need to be defined in this section. + +9.4. Fault Resilience + + Diameter Base protocol mechanisms are used to overcome small message + loss and network faults of temporary nature. + + Diameter peers acting as clients MUST implement the use of failover + to guard against server failures and certain network failures. + Diameter peers acting as agents or related off-line processing + systems MUST detect duplicate accounting records caused by the + sending of same record to several servers and duplication of messages + + + + + +Calhoun, et al. Standards Track [Page 116] + +RFC 3588 Diameter Based Protocol September 2003 + + + in transit. This detection MUST be based on the inspection of the + Session-Id and Accounting-Record-Number AVP pairs. Appendix C + discusses duplicate detection needs and implementation issues. + + Diameter clients MAY have non-volatile memory for the safe storage of + accounting records over reboots or extended network failures, network + partitions, and server failures. If such memory is available, the + client SHOULD store new accounting records there as soon as the + records are created and until a positive acknowledgement of their + reception from the Diameter Server has been received. Upon a reboot, + the client MUST starting sending the records in the non-volatile + memory to the accounting server with appropriate modifications in + termination cause, session length, and other relevant information in + the records. + + A further application of this protocol may include AVPs to control + how many accounting records may at most be stored in the Diameter + client without committing them to the non-volatile memory or + transferring them to the Diameter server. + + The client SHOULD NOT remove the accounting data from any of its + memory areas before the correct Accounting-Answer has been received. + The client MAY remove oldest, undelivered or yet unacknowledged + accounting data if it runs out of resources such as memory. It is an + implementation dependent matter for the client to accept new sessions + under this condition. + +9.5. Accounting Records + + In all accounting records, the Session-Id AVP MUST be present; the + User-Name AVP MUST be present if it is available to the Diameter + client. If strong authentication across agents is required, end-to- + end security may be used for authentication purposes. + + Different types of accounting records are sent depending on the + actual type of accounted service and the authorization server's + directions for interim accounting. If the accounted service is a + one-time event, meaning that the start and stop of the event are + simultaneous, then the Accounting-Record-Type AVP MUST be present and + set to the value EVENT_RECORD. + + If the accounted service is of a measurable length, then the AVP MUST + use the values START_RECORD, STOP_RECORD, and possibly, + INTERIM_RECORD. If the authorization server has not directed interim + accounting to be enabled for the session, two accounting records MUST + be generated for each service of type session. When the initial + + + + + +Calhoun, et al. Standards Track [Page 117] + +RFC 3588 Diameter Based Protocol September 2003 + + + Accounting-Request for a given session is sent, the Accounting- + Record-Type AVP MUST be set to the value START_RECORD. When the last + Accounting-Request is sent, the value MUST be STOP_RECORD. + + If the authorization server has directed interim accounting to be + enabled, the Diameter client MUST produce additional records between + the START_RECORD and STOP_RECORD, marked INTERIM_RECORD. The + production of these records is directed by Acct-Interim-Interval as + well as any re-authentication or re-authorization of the session. The + Diameter client MUST overwrite any previous interim accounting + records that are locally stored for delivery, if a new record is + being generated for the same session. This ensures that only one + pending interim record can exist on an access device for any given + session. + + A particular value of Accounting-Sub-Session-Id MUST appear only in + one sequence of accounting records from a DIAMETER client, except for + the purposes of retransmission. The one sequence that is sent MUST + be either one record with Accounting-Record-Type AVP set to the value + EVENT_RECORD, or several records starting with one having the value + START_RECORD, followed by zero or more INTERIM_RECORD and a single + STOP_RECORD. A particular Diameter application specification MUST + define the type of sequences that MUST be used. + +9.6. Correlation of Accounting Records + + The Diameter protocol's Session-Id AVP, which is globally unique (see + Section 8.8), is used during the authorization phase to identify a + particular session. Services that do not require any authorization + still use the Session-Id AVP to identify sessions. Accounting + messages MAY use a different Session-Id from that sent in + authorization messages. Specific applications MAY require different + a Session-ID for accounting messages. + + However, there are certain applications that require multiple + accounting sub-sessions. Such applications would send messages with + a constant Session-Id AVP, but a different Accounting-Sub-Session-Id + AVP. In these cases, correlation is performed using the Session-Id. + It is important to note that receiving a STOP_RECORD with no + Accounting-Sub-Session-Id AVP when sub-sessions were originally used + in the START_RECORD messages implies that all sub-sessions are + terminated. + + Furthermore, there are certain applications where a user receives + service from different access devices (e.g., Mobile IPv4), each with + their own unique Session-Id. In such cases, the Acct-Multi-Session- + Id AVP is used for correlation. During authorization, a server that + + + + +Calhoun, et al. Standards Track [Page 118] + +RFC 3588 Diameter Based Protocol September 2003 + + + determines that a request is for an existing session SHOULD include + the Acct-Multi-Session-Id AVP, which the access device MUST include + in all subsequent accounting messages. + + The Acct-Multi-Session-Id AVP MAY include the value of the original + Session-Id. It's contents are implementation specific, but MUST be + globally unique across other Acct-Multi-Session-Id, and MUST NOT + change during the life of a session. + + A Diameter application document MUST define the exact concept of a + session that is being accounted, and MAY define the concept of a + multi-session. For instance, the NASREQ DIAMETER application treats + a single PPP connection to a Network Access Server as one session, + and a set of Multilink PPP sessions as one multi-session. + +9.7. Accounting Command-Codes + + This section defines Command-Code values that MUST be supported by + all Diameter implementations that provide Accounting services. + +9.7.1. Accounting-Request + + The Accounting-Request (ACR) command, indicated by the Command-Code + field set to 271 and the Command Flags' 'R' bit set, is sent by a + Diameter node, acting as a client, in order to exchange accounting + information with a peer. + + One of Acct-Application-Id and Vendor-Specific-Application-Id AVPs + MUST be present. If the Vendor-Specific-Application-Id grouped AVP + is present, it must have an Acct-Application-Id inside. + + The AVP listed below SHOULD include service specific accounting AVPs, + as described in Section 9.3. + + + + + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 119] + +RFC 3588 Diameter Based Protocol September 2003 + + + Message Format + + <ACR> ::= < Diameter Header: 271, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Accounting-Record-Type } + { Accounting-Record-Number } + [ Acct-Application-Id ] + [ Vendor-Specific-Application-Id ] + [ User-Name ] + [ Accounting-Sub-Session-Id ] + [ Acct-Session-Id ] + [ Acct-Multi-Session-Id ] + [ Acct-Interim-Interval ] + [ Accounting-Realtime-Required ] + [ Origin-State-Id ] + [ Event-Timestamp ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +9.7.2. Accounting-Answer + + The Accounting-Answer (ACA) command, indicated by the Command-Code + field set to 271 and the Command Flags' 'R' bit cleared, is used to + acknowledge an Accounting-Request command. The Accounting-Answer + command contains the same Session-Id and includes the usage AVPs only + if CMS is in use when sending this command. Note that the inclusion + of the usage AVPs when CMS is not being used leads to unnecessarily + large answer messages, and can not be used as a server's proof of the + receipt of these AVPs in an end-to-end fashion. If the Accounting- + Request was protected by end-to-end security, then the corresponding + ACA message MUST be protected by end-to-end security. + + Only the target Diameter Server, known as the home Diameter Server, + SHOULD respond with the Accounting-Answer command. + + One of Acct-Application-Id and Vendor-Specific-Application-Id AVPs + MUST be present. If the Vendor-Specific-Application-Id grouped AVP + is present, it must have an Acct-Application-Id inside. + + The AVP listed below SHOULD include service specific accounting AVPs, + as described in Section 9.3. + + + + + + +Calhoun, et al. Standards Track [Page 120] + +RFC 3588 Diameter Based Protocol September 2003 + + + Message Format + + <ACA> ::= < Diameter Header: 271, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + { Accounting-Record-Type } + { Accounting-Record-Number } + [ Acct-Application-Id ] + [ Vendor-Specific-Application-Id ] + [ User-Name ] + [ Accounting-Sub-Session-Id ] + [ Acct-Session-Id ] + [ Acct-Multi-Session-Id ] + [ Error-Reporting-Host ] + [ Acct-Interim-Interval ] + [ Accounting-Realtime-Required ] + [ Origin-State-Id ] + [ Event-Timestamp ] + * [ Proxy-Info ] + * [ AVP ] + +9.8. Accounting AVPs + + This section contains AVPs that describe accounting usage information + related to a specific session. + +9.8.1. Accounting-Record-Type AVP + + The Accounting-Record-Type AVP (AVP Code 480) is of type Enumerated + and contains the type of accounting record being sent. The following + values are currently defined for the Accounting-Record-Type AVP: + + EVENT_RECORD 1 + An Accounting Event Record is used to indicate that a one-time + event has occurred (meaning that the start and end of the event + are simultaneous). This record contains all information relevant + to the service, and is the only record of the service. + + START_RECORD 2 + An Accounting Start, Interim, and Stop Records are used to + indicate that a service of a measurable length has been given. An + Accounting Start Record is used to initiate an accounting session, + and contains accounting information that is relevant to the + initiation of the session. + + + + + +Calhoun, et al. Standards Track [Page 121] + +RFC 3588 Diameter Based Protocol September 2003 + + + INTERIM_RECORD 3 + An Interim Accounting Record contains cumulative accounting + information for an existing accounting session. Interim + Accounting Records SHOULD be sent every time a re-authentication + or re-authorization occurs. Further, additional interim record + triggers MAY be defined by application-specific Diameter + applications. The selection of whether to use INTERIM_RECORD + records is done by the Acct-Interim-Interval AVP. + + STOP_RECORD 4 + An Accounting Stop Record is sent to terminate an accounting + session and contains cumulative accounting information relevant to + the existing session. + +9.8.2. Acct-Interim-Interval + + The Acct-Interim-Interval AVP (AVP Code 85) is of type Unsigned32 and + is sent from the Diameter home authorization server to the Diameter + client. The client uses information in this AVP to decide how and + when to produce accounting records. With different values in this + AVP, service sessions can result in one, two, or two+N accounting + records, based on the needs of the home-organization. The following + accounting record production behavior is directed by the inclusion of + this AVP: + + 1. The omission of the Acct-Interim-Interval AVP or its inclusion + with Value field set to 0 means that EVENT_RECORD, START_RECORD, + and STOP_RECORD are produced, as appropriate for the service. + + 2. The inclusion of the AVP with Value field set to a non-zero value + means that INTERIM_RECORD records MUST be produced between the + START_RECORD and STOP_RECORD records. The Value field of this AVP + is the nominal interval between these records in seconds. The + Diameter node that originates the accounting information, known as + the client, MUST produce the first INTERIM_RECORD record roughly + at the time when this nominal interval has elapsed from the + START_RECORD, the next one again as the interval has elapsed once + more, and so on until the session ends and a STOP_RECORD record is + produced. + + The client MUST ensure that the interim record production times + are randomized so that large accounting message storms are not + created either among records or around a common service start + time. + + + + + + + +Calhoun, et al. Standards Track [Page 122] + +RFC 3588 Diameter Based Protocol September 2003 + + +9.8.3. Accounting-Record-Number AVP + + The Accounting-Record-Number AVP (AVP Code 485) is of type Unsigned32 + and identifies this record within one session. As Session-Id AVPs + are globally unique, the combination of Session-Id and Accounting- + Record-Number AVPs is also globally unique, and can be used in + matching accounting records with confirmations. An easy way to + produce unique numbers is to set the value to 0 for records of type + EVENT_RECORD and START_RECORD, and set the value to 1 for the first + INTERIM_RECORD, 2 for the second, and so on until the value for + STOP_RECORD is one more than for the last INTERIM_RECORD. + +9.8.4. Acct-Session-Id AVP + + The Acct-Session-Id AVP (AVP Code 44) is of type OctetString is only + used when RADIUS/Diameter translation occurs. This AVP contains the + contents of the RADIUS Acct-Session-Id attribute. + +9.8.5. Acct-Multi-Session-Id AVP + + The Acct-Multi-Session-Id AVP (AVP Code 50) is of type UTF8String, + following the format specified in Section 8.8. The Acct-Multi- + Session-Id AVP is used to link together multiple related accounting + sessions, where each session would have a unique Session-Id, but the + same Acct-Multi-Session-Id AVP. This AVP MAY be returned by the + Diameter server in an authorization answer, and MUST be used in all + accounting messages for the given session. + +9.8.6. Accounting-Sub-Session-Id AVP + + The Accounting-Sub-Session-Id AVP (AVP Code 287) is of type + Unsigned64 and contains the accounting sub-session identifier. The + combination of the Session-Id and this AVP MUST be unique per sub- + session, and the value of this AVP MUST be monotonically increased by + one for all new sub-sessions. The absence of this AVP implies no + sub-sessions are in use, with the exception of an Accounting-Request + whose Accounting-Record-Type is set to STOP_RECORD. A STOP_RECORD + message with no Accounting-Sub-Session-Id AVP present will signal the + termination of all sub-sessions for a given Session-Id. + +9.8.7. Accounting-Realtime-Required AVP + + The Accounting-Realtime-Required AVP (AVP Code 483) is of type + Enumerated and is sent from the Diameter home authorization server to + the Diameter client or in the Accounting-Answer from the accounting + server. The client uses information in this AVP to decide what to do + if the sending of accounting records to the accounting server has + been temporarily prevented due to, for instance, a network problem. + + + +Calhoun, et al. Standards Track [Page 123] + +RFC 3588 Diameter Based Protocol September 2003 + + + DELIVER_AND_GRANT 1 + The AVP with Value field set to DELIVER_AND_GRANT means that the + service MUST only be granted as long as there is a connection to + an accounting server. Note that the set of alternative accounting + servers are treated as one server in this sense. Having to move + the accounting record stream to a backup server is not a reason to + discontinue the service to the user. + + GRANT_AND_STORE 2 + The AVP with Value field set to GRANT_AND_STORE means that service + SHOULD be granted if there is a connection, or as long as records + can still be stored as described in Section 9.4. + + This is the default behavior if the AVP isn't included in the + reply from the authorization server. + + GRANT_AND_LOSE 3 + The AVP with Value field set to GRANT_AND_LOSE means that service + SHOULD be granted even if the records can not be delivered or + stored. + +10. AVP Occurrence Table + + The following tables presents the AVPs defined in this document, and + specifies in which Diameter messages they MAY, or MAY NOT be present. + Note that AVPs that can only be present within a Grouped AVP are not + represented in this table. + + The table uses the following symbols: + + 0 The AVP MUST NOT be present in the message. + 0+ Zero or more instances of the AVP MAY be present in the + message. + 0-1 Zero or one instance of the AVP MAY be present in the + message. It is considered an error if there are more than + one instance of the AVP. + 1 One instance of the AVP MUST be present in the message. + 1+ At least one instance of the AVP MUST be present in the + message. + +10.1. Base Protocol Command AVP Table + + The table in this section is limited to the non-accounting Command + Codes defined in this specification. + + + + + + + +Calhoun, et al. Standards Track [Page 124] + +RFC 3588 Diameter Based Protocol September 2003 + + + +-----------------------------------------------+ + | Command-Code | + +---+---+---+---+---+---+---+---+---+---+---+---+ + Attribute Name |CER|CEA|DPR|DPA|DWR|DWA|RAR|RAA|ASR|ASA|STR|STA| + --------------------+---+---+---+---+---+---+---+---+---+---+---+---+ + Acct-Interim- |0 |0 |0 |0 |0 |0 |0-1|0 |0 |0 |0 |0 | + Interval | | | | | | | | | | | | | + Accounting-Realtime-|0 |0 |0 |0 |0 |0 |0-1|0 |0 |0 |0 |0 | + Required | | | | | | | | | | | | | + Acct-Application-Id |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Auth-Application-Id |0+ |0+ |0 |0 |0 |0 |1 |0 |1 |0 |1 |0 | + Auth-Grace-Period |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Auth-Request-Type |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Auth-Session-State |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Authorization- |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Lifetime | | | | | | | | | | | | | + Class |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0+ |0+ | + Destination-Host |0 |0 |0 |0 |0 |0 |1 |0 |1 |0 |0-1|0 | + Destination-Realm |0 |0 |0 |0 |0 |0 |1 |0 |1 |0 |1 |0 | + Disconnect-Cause |0 |0 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Error-Message |0 |0-1|0 |0-1|0 |0-1|0 |0-1|0 |0-1|0 |0-1| + Error-Reporting-Host|0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1| + Failed-AVP |0 |0+ |0 |0+ |0 |0+ |0 |0+ |0 |0+ |0 |0+ | + Firmware-Revision |0-1|0-1|0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Host-IP-Address |1+ |1+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Inband-Security-Id |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Multi-Round-Time-Out|0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Origin-Host |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 | + Origin-Realm |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 |1 | + Origin-State-Id |0-1|0-1|0 |0 |0-1|0-1|0-1|0-1|0-1|0-1|0-1|0-1| + Product-Name |1 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Proxy-Info |0 |0 |0 |0 |0 |0 |0+ |0+ |0+ |0+ |0+ |0+ | + Redirect-Host |0 |0 |0 |0 |0 |0 |0 |0+ |0 |0+ |0 |0+ | + Redirect-Host-Usage |0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1| + Redirect-Max-Cache- |0 |0 |0 |0 |0 |0 |0 |0-1|0 |0-1|0 |0-1| + Time | | | | | | | | | | | | | + Result-Code |0 |1 |0 |1 |0 |1 |0 |1 |0 |0 |0 |1 | + Re-Auth-Request-Type|0 |0 |0 |0 |0 |0 |1 |0 |0 |0 |0 |0 | + Route-Record |0 |0 |0 |0 |0 |0 |0+ |0 |0+ |0 |0+ |0 | + Session-Binding |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Session-Id |0 |0 |0 |0 |0 |0 |1 |1 |1 |1 |1 |1 | + Session-Server- |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Failover | | | | | | | | | | | | | + Session-Timeout |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Supported-Vendor-Id |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Termination-Cause |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |1 |0 | + User-Name |0 |0 |0 |0 |0 |0 |0-1|0-1|0-1|0-1|0-1|0-1| + Vendor-Id |1 |1 |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + + + +Calhoun, et al. Standards Track [Page 125] + +RFC 3588 Diameter Based Protocol September 2003 + + + Vendor-Specific- |0+ |0+ |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | + Application-Id | | | | | | | | | | | | | + --------------------+---+---+---+---+---+---+---+---+---+---+---+---+ + +10.2. Accounting AVP Table + + The table in this section is used to represent which AVPs defined in + this document are to be present in the Accounting messages. These + AVP occurrence requirements are guidelines, which may be expanded, + and/or overridden by application-specific requirements in the + Diameter applications documents. + + +-----------+ + | Command | + | Code | + +-----+-----+ + Attribute Name | ACR | ACA | + ------------------------------+-----+-----+ + Acct-Interim-Interval | 0-1 | 0-1 | + Acct-Multi-Session-Id | 0-1 | 0-1 | + Accounting-Record-Number | 1 | 1 | + Accounting-Record-Type | 1 | 1 | + Acct-Session-Id | 0-1 | 0-1 | + Accounting-Sub-Session-Id | 0-1 | 0-1 | + Accounting-Realtime-Required | 0-1 | 0-1 | + Acct-Application-Id | 0-1 | 0-1 | + Auth-Application-Id | 0 | 0 | + Class | 0+ | 0+ | + Destination-Host | 0-1 | 0 | + Destination-Realm | 1 | 0 | + Error-Reporting-Host | 0 | 0+ | + Event-Timestamp | 0-1 | 0-1 | + Origin-Host | 1 | 1 | + Origin-Realm | 1 | 1 | + Proxy-Info | 0+ | 0+ | + Route-Record | 0+ | 0+ | + Result-Code | 0 | 1 | + Session-Id | 1 | 1 | + Termination-Cause | 0-1 | 0-1 | + User-Name | 0-1 | 0-1 | + Vendor-Specific-Application-Id| 0-1 | 0-1 | + ------------------------------+-----+-----+ + + + + + + + + + +Calhoun, et al. Standards Track [Page 126] + +RFC 3588 Diameter Based Protocol September 2003 + + +11. IANA Considerations + + This section provides guidance to the Internet Assigned Numbers + Authority (IANA) regarding registration of values related to the + Diameter protocol, in accordance with BCP 26 [IANA]. The following + policies are used here with the meanings defined in BCP 26: "Private + Use", "First Come First Served", "Expert Review", "Specification + Required", "IETF Consensus", "Standards Action". + + This section explains the criteria to be used by the IANA for + assignment of numbers within namespaces defined within this document. + + Diameter is not intended as a general purpose protocol, and + allocations SHOULD NOT be made for purposes unrelated to + authentication, authorization or accounting. + + For registration requests where a Designated Expert should be + consulted, the responsible IESG area director should appoint the + Designated Expert. For Designated Expert with Specification + Required, the request is posted to the AAA WG mailing list (or, if it + has been disbanded, a successor designated by the Area Director) for + comment and review, and MUST include a pointer to a public + specification. Before a period of 30 days has passed, the Designated + Expert will either approve or deny the registration request and + publish a notice of the decision to the AAA WG mailing list or its + successor. A denial notice must be justified by an explanation and, + in the cases where it is possible, concrete suggestions on how the + request can be modified so as to become acceptable. + +11.1. AVP Header + + As defined in Section 4, the AVP header contains three fields that + requires IANA namespace management; the AVP Code, Vendor-ID and Flags + field. + +11.1.1. AVP Codes + + The AVP Code namespace is used to identify attributes. There are + multiple namespaces. Vendors can have their own AVP Codes namespace + which will be identified by their Vendor-ID (also known as + Enterprise-Number) and they control the assignments of their vendor- + specific AVP codes within their own namespace. The absence of a + Vendor-ID or a Vendor-ID value of zero (0) identifies the IETF IANA + controlled AVP Codes namespace. The AVP Codes and sometimes also + possible values in an AVP are controlled and maintained by IANA. + + + + + + +Calhoun, et al. Standards Track [Page 127] + +RFC 3588 Diameter Based Protocol September 2003 + + + AVP Code 0 is not used. AVP Codes 1-255 are managed separately as + RADIUS Attribute Types [RADTYPE]. This document defines the AVP + Codes 257-274, 276-285, 287, 291-300, 480, 483 and 485-486. See + Section 4.5 for the assignment of the namespace in this + specification. + + AVPs may be allocated following Designated Expert with Specification + Required [IANA]. Release of blocks of AVPs (more than 3 at a time + for a given purpose) should require IETF Consensus. + + Note that Diameter defines a mechanism for Vendor-Specific AVPs, + where the Vendor-Id field in the AVP header is set to a non-zero + value. Vendor-Specific AVPs codes are for Private Use and should be + encouraged instead of allocation of global attribute types, for + functions specific only to one vendor's implementation of Diameter, + where no interoperability is deemed useful. Where a Vendor-Specific + AVP is implemented by more than one vendor, allocation of global AVPs + should be encouraged instead. + +11.1.2. AVP Flags + + There are 8 bits in the AVP Flags field of the AVP header, defined in + Section 4. This document assigns bit 0 ('V'endor Specific), bit 1 + ('M'andatory) and bit 2 ('P'rotected). The remaining bits should + only be assigned via a Standards Action [IANA]. + +11.2. Diameter Header + + As defined in Section 3, the Diameter header contains two fields that + require IANA namespace management; Command Code and Command Flags. + +11.2.1. Command Codes + + The Command Code namespace is used to identify Diameter commands. + The values 0-255 are reserved for RADIUS backward compatibility, and + are defined as "RADIUS Packet Type Codes" in [RADTYPE]. Values 256- + 16,777,213 are for permanent, standard commands, allocated by IETF + Consensus [IANA]. This document defines the Command Codes 257, 258, + 271, 274-275, 280 and 282. See Section 3.1 for the assignment of the + namespace in this specification. + + The values 16,777,214 and 16,777,215 (hexadecimal values 0xfffffe - + 0xffffff) are reserved for experimental commands. As these codes are + only for experimental and testing purposes, no guarantee is made for + interoperability between Diameter peers using experimental commands, + as outlined in [IANA-EXP]. + + + + + +Calhoun, et al. Standards Track [Page 128] + +RFC 3588 Diameter Based Protocol September 2003 + + +11.2.2. Command Flags + + There are eight bits in the Command Flags field of the Diameter + header. This document assigns bit 0 ('R'equest), bit 1 ('P'roxy), + bit 2 ('E'rror) and bit 3 ('T'). Bits 4 through 7 MUST only be + assigned via a Standards Action [IANA]. + +11.3. Application Identifiers + + As defined in Section 2.4, the Application Identifier is used to + identify a specific Diameter Application. There are standards-track + application ids and vendor specific application ids. + + IANA [IANA] has assigned the range 0x00000001 to 0x00ffffff for + standards-track applications; and 0x01000000 - 0xfffffffe for vendor + specific applications, on a first-come, first-served basis. The + following values are allocated. + + Diameter Common Messages 0 + NASREQ 1 [NASREQ] + Mobile-IP 2 [DIAMMIP] + Diameter Base Accounting 3 + Relay 0xffffffff + + Assignment of standards-track application IDs are by Designated + Expert with Specification Required [IANA]. + + Both Application-Id and Acct-Application-Id AVPs use the same + Application Identifier space. + + Vendor-Specific Application Identifiers, are for Private Use. + Vendor-Specific Application Identifiers are assigned on a First Come, + First Served basis by IANA. + +11.4. AVP Values + + Certain AVPs in Diameter define a list of values with various + meanings. For attributes other than those specified in this section, + adding additional values to the list can be done on a First Come, + First Served basis by IANA. + +11.4.1. Result-Code AVP Values + + As defined in Section 7.1, the Result-Code AVP (AVP Code 268) defines + the values 1001, 2001-2002, 3001-3010, 4001-4002 and 5001-5017. + + All remaining values are available for assignment via IETF Consensus + [IANA]. + + + +Calhoun, et al. Standards Track [Page 129] + +RFC 3588 Diameter Based Protocol September 2003 + + +11.4.2. Accounting-Record-Type AVP Values + + As defined in Section 9.8.1, the Accounting-Record-Type AVP (AVP Code + 480) defines the values 1-4. All remaining values are available for + assignment via IETF Consensus [IANA]. + +11.4.3. Termination-Cause AVP Values + + As defined in Section 8.15, the Termination-Cause AVP (AVP Code 295) + defines the values 1-8. All remaining values are available for + assignment via IETF Consensus [IANA]. + +11.4.4. Redirect-Host-Usage AVP Values + + As defined in Section 6.13, the Redirect-Host-Usage AVP (AVP Code + 261) defines the values 0-5. All remaining values are available for + assignment via IETF Consensus [IANA]. + +11.4.5. Session-Server-Failover AVP Values + + As defined in Section 8.18, the Session-Server-Failover AVP (AVP Code + 271) defines the values 0-3. All remaining values are available for + assignment via IETF Consensus [IANA]. + +11.4.6. Session-Binding AVP Values + + As defined in Section 8.17, the Session-Binding AVP (AVP Code 270) + defines the bits 1-4. All remaining bits are available for + assignment via IETF Consensus [IANA]. + +11.4.7. Disconnect-Cause AVP Values + + As defined in Section 5.4.3, the Disconnect-Cause AVP (AVP Code 273) + defines the values 0-2. All remaining values are available for + assignment via IETF Consensus [IANA]. + +11.4.8. Auth-Request-Type AVP Values + + As defined in Section 8.7, the Auth-Request-Type AVP (AVP Code 274) + defines the values 1-3. All remaining values are available for + assignment via IETF Consensus [IANA]. + +11.4.9. Auth-Session-State AVP Values + + As defined in Section 8.11, the Auth-Session-State AVP (AVP Code 277) + defines the values 0-1. All remaining values are available for + assignment via IETF Consensus [IANA]. + + + + +Calhoun, et al. Standards Track [Page 130] + +RFC 3588 Diameter Based Protocol September 2003 + + +11.4.10. Re-Auth-Request-Type AVP Values + + As defined in Section 8.12, the Re-Auth-Request-Type AVP (AVP Code + 285) defines the values 0-1. All remaining values are available for + assignment via IETF Consensus [IANA]. + +11.4.11. Accounting-Realtime-Required AVP Values + + As defined in Section 9.8.7, the Accounting-Realtime-Required AVP + (AVP Code 483) defines the values 1-3. All remaining values are + available for assignment via IETF Consensus [IANA]. + +11.4.12. Inband-Security-Id AVP (code 299) + + As defined in Section 6.10, the Inband-Security-Id AVP (AVP Code 299) + defines the values 0-1. All remaining values are available for + assignment via IETF Consensus [IANA]. + +11.5. Diameter TCP/SCTP Port Numbers + + The IANA has assigned TCP and SCTP port number 3868 to Diameter. + +11.6. NAPTR Service Fields + + The registration in the RFC MUST include the following information: + + Service Field: The service field being registered. An example for a + new fictitious transport protocol called NCTP might be "AAA+D2N". + + Protocol: The specific transport protocol associated with that + service field. This MUST include the name and acronym for the + protocol, along with reference to a document that describes the + transport protocol. For example - "New Connectionless Transport + Protocol (NCTP), RFC 5766". + + Name and Contact Information: The name, address, email address and + telephone number for the person performing the registration. + + The following values have been placed into the registry: + + Services Field Protocol + AAA+D2T TCP + AAA+D2S SCTP + +12. Diameter protocol related configurable parameters + + This section contains the configurable parameters that are found + throughout this document: + + + +Calhoun, et al. Standards Track [Page 131] + +RFC 3588 Diameter Based Protocol September 2003 + + + Diameter Peer + A Diameter entity MAY communicate with peers that are statically + configured. A statically configured Diameter peer would require + that either the IP address or the fully qualified domain name + (FQDN) be supplied, which would then be used to resolve through + DNS. + + Realm Routing Table + A Diameter proxy server routes messages based on the realm portion + of a Network Access Identifier (NAI). The server MUST have a + table of Realm Names, and the address of the peer to which the + message must be forwarded to. The routing table MAY also include + a "default route", which is typically used for all messages that + cannot be locally processed. + + Tc timer + The Tc timer controls the frequency that transport connection + attempts are done to a peer with whom no active transport + connection exists. The recommended value is 30 seconds. + +13. Security Considerations + + The Diameter base protocol assumes that messages are secured by using + either IPSec or TLS. This security mechanism is acceptable in + environments where there is no untrusted third party agent. In other + situations, end-to-end security is needed. + + Diameter clients, such as Network Access Servers (NASes) and Mobility + Agents MUST support IP Security [SECARCH] and MAY support TLS [TLS]. + Diameter servers MUST support TLS and IPsec. Diameter + implementations MUST use transmission-level security of some kind + (IPsec or TLS) on each connection. + + If a Diameter connection is not protected by IPsec, then the CER/CEA + exchange MUST include an Inband-Security-ID AVP with a value of TLS. + For TLS usage, a TLS handshake will begin when both ends are in the + open state, after completion of the CER/CEA exchange. If the TLS + handshake is successful, all further messages will be sent via TLS. + If the handshake fails, both ends move to the closed state. + + It is suggested that IPsec be used primarily at the edges for intra- + domain exchanges. For NAS devices without certificate support, pre- + shared keys can be used between the NAS and a local AAA proxy. + + For protection of inter-domain exchanges, TLS is recommended. See + Sections 13.1 and 13.2 for more details on IPsec and TLS usage. + + + + + +Calhoun, et al. Standards Track [Page 132] + +RFC 3588 Diameter Based Protocol September 2003 + + +13.1. IPsec Usage + + All Diameter implementations MUST support IPsec ESP [IPsec] in + transport mode with non-null encryption and authentication algorithms + to provide per-packet authentication, integrity protection and + confidentiality, and MUST support the replay protection mechanisms of + IPsec. + + Diameter implementations MUST support IKE for peer authentication, + negotiation of security associations, and key management, using the + IPsec DOI [IPSECDOI]. Diameter implementations MUST support peer + authentication using a pre-shared key, and MAY support certificate- + based peer authentication using digital signatures. Peer + authentication using the public key encryption methods outlined in + IKE's Sections 5.2 and 5.3 [IKE] SHOULD NOT be used. + + Conformant implementations MUST support both IKE Main Mode and + Aggressive Mode. When pre-shared keys are used for authentication, + IKE Aggressive Mode SHOULD be used, and IKE Main Mode SHOULD NOT be + used. When digital signatures are used for authentication, either + IKE Main Mode or IKE Aggressive Mode MAY be used. + + When digital signatures are used to achieve authentication, an IKE + negotiator SHOULD use IKE Certificate Request Payload(s) to specify + the certificate authority (or authorities) that are trusted in + accordance with its local policy. IKE negotiators SHOULD use + pertinent certificate revocation checks before accepting a PKI + certificate for use in IKE's authentication procedures. + + The Phase 2 Quick Mode exchanges used to negotiate protection for + Diameter connections MUST explicitly carry the Identity Payload + fields (IDci and IDcr). The DOI provides for several types of + identification data. However, when used in conformant + implementations, each ID Payload MUST carry a single IP address and a + single non-zero port number, and MUST NOT use the IP Subnet or IP + Address Range formats. This allows the Phase 2 security association + to correspond to specific TCP and SCTP connections. + + Since IPsec acceleration hardware may only be able to handle a + limited number of active IKE Phase 2 SAs, Phase 2 delete messages may + be sent for idle SAs, as a means of keeping the number of active + Phase 2 SAs to a minimum. The receipt of an IKE Phase 2 delete + message SHOULD NOT be interpreted as a reason for tearing down a + Diameter connection. Rather, it is preferable to leave the + connection up, and if additional traffic is sent on it, to bring up + another IKE Phase 2 SA to protect it. This avoids the potential for + continually bringing connections up and down. + + + + +Calhoun, et al. Standards Track [Page 133] + +RFC 3588 Diameter Based Protocol September 2003 + + +13.2. TLS Usage + + A Diameter node that initiates a connection to another Diameter node + acts as a TLS client according to [TLS], and a Diameter node that + accepts a connection acts as a TLS server. Diameter nodes + implementing TLS for security MUST mutually authenticate as part of + TLS session establishment. In order to ensure mutual authentication, + the Diameter node acting as TLS server must request a certificate + from the Diameter node acting as TLS client, and the Diameter node + acting as TLS client MUST be prepared to supply a certificate on + request. + + Diameter nodes MUST be able to negotiate the following TLS cipher + suites: + + TLS_RSA_WITH_RC4_128_MD5 + TLS_RSA_WITH_RC4_128_SHA + TLS_RSA_WITH_3DES_EDE_CBC_SHA + + Diameter nodes SHOULD be able to negotiate the following TLS cipher + suite: + + TLS_RSA_WITH_AES_128_CBC_SHA + + Diameter nodes MAY negotiate other TLS cipher suites. + +13.3. Peer-to-Peer Considerations + + As with any peer-to-peer protocol, proper configuration of the trust + model within a Diameter peer is essential to security. When + certificates are used, it is necessary to configure the root + certificate authorities trusted by the Diameter peer. These root CAs + are likely to be unique to Diameter usage and distinct from the root + CAs that might be trusted for other purposes such as Web browsing. + In general, it is expected that those root CAs will be configured so + as to reflect the business relationships between the organization + hosting the Diameter peer and other organizations. As a result, a + Diameter peer will typically not be configured to allow connectivity + with any arbitrary peer. When certificate authentication Diameter + peers may not be known beforehand, and therefore peer discovery may + be required. + + Note that IPsec is considerably less flexible than TLS when it comes + to configuring root CAs. Since use of Port identifiers is prohibited + within IKE Phase 1, within IPsec it is not possible to uniquely + configure trusted root CAs for each application individually; the + same policy must be used for all applications. This implies, for + example, that a root CA trusted for use with Diameter must also be + + + +Calhoun, et al. Standards Track [Page 134] + +RFC 3588 Diameter Based Protocol September 2003 + + + trusted to protect SNMP. These restrictions can be awkward at best. + Since TLS supports application-level granularity in certificate + policy, TLS SHOULD be used to protect Diameter connections between + administrative domains. IPsec is most appropriate for intra-domain + usage when pre-shared keys are used as a security mechanism. + + When pre-shared key authentication is used with IPsec to protect + Diameter, unique pre-shared keys are configured with Diameter peers, + who are identified by their IP address (Main Mode), or possibly their + FQDN (Aggressive Mode). As a result, it is necessary for the set of + Diameter peers to be known beforehand. Therefore, peer discovery is + typically not necessary. + + The following is intended to provide some guidance on the issue. + + It is recommended that a Diameter peer implement the same security + mechanism (IPsec or TLS) across all its peer-to-peer connections. + Inconsistent use of security mechanisms can result in redundant + security mechanisms being used (e.g., TLS over IPsec) or worse, + potential security vulnerabilities. When IPsec is used with + Diameter, a typical security policy for outbound traffic is "Initiate + IPsec, from me to any, destination port Diameter"; for inbound + traffic, the policy would be "Require IPsec, from any to me, + destination port Diameter". + + This policy causes IPsec to be used whenever a Diameter peer + initiates a connection to another Diameter peer, and to be required + whenever an inbound Diameter connection occurs. This policy is + attractive, since it does not require policy to be set for each peer + or dynamically modified each time a new Diameter connection is + created; an IPsec SA is automatically created based on a simple + static policy. Since IPsec extensions are typically not available to + the sockets API on most platforms, and IPsec policy functionality is + implementation dependent, use of a simple static policy is the often + the simplest route to IPsec-enabling a Diameter implementation. + + One implication of the recommended policy is that if a node is using + both TLS and IPsec, there is not a convenient way in which to use + either TLS or IPsec, but not both, without reserving an additional + port for TLS usage. Since Diameter uses the same port for TLS and + non-TLS usage, where the recommended IPsec policy is put in place, a + TLS-protected connection will match the IPsec policy, and both IPsec + and TLS will be used to protect the Diameter connection. To avoid + this, it would be necessary to plumb peer-specific policies either + statically or dynamically. + + + + + + +Calhoun, et al. Standards Track [Page 135] + +RFC 3588 Diameter Based Protocol September 2003 + + + If IPsec is used to secure Diameter peer-to-peer connections, IPsec + policy SHOULD be set so as to require IPsec protection for inbound + connections, and to initiate IPsec protection for outbound + connections. This can be accomplished via use of inbound and + outbound filter policy. + +14. References + +14.1. Normative References + + [AAATRANS] Aboba, B. and J. Wood, "Authentication, Authorization + and Accounting (AAA) Transport Profile", RFC 3539, + June 2003. + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [ASSIGNNO] Reynolds, J., "Assigned Numbers: RFC 1700 is Replaced + by an On-line Database", RFC 3232, January 2002. + + [DIFFSERV] Nichols, K., Blake, S., Baker, F. and D. Black, + "Definition of the Differentiated Services Field (DS + Field) in the IPv4 and IPv6 Headers", RFC 2474, + December 1998. + + [DIFFSERVAF] Heinanen, J., Baker, F., Weiss, W. and J. Wroclawski, + "Assured Forwarding PHB Group", RFC 2597, June 1999. + + [DIFFSERVEF] Davie, B., Charny, A., Bennet, J., Benson, K., Le + Boudec, J., Courtney, W., Davari, S., Firoiu, V. and + D. Stiliadis, "An Expedited Forwarding PHB", RFC 3246, + March 2002. + + [DNSSRV] Gulbrandsen, A., Vixie, P. and L. Esibov, "A DNS RR + for specifying the location of services (DNS SRV)", + RFC 2782, February 2000. + + [EAP] Blunk, L. and J. Vollbrecht, "PPP Extensible + Authentication Protocol (EAP)", RFC 2284, March 1998. + + [FLOATPOINT] Institute of Electrical and Electronics Engineers, + "IEEE Standard for Binary Floating-Point Arithmetic", + ANSI/IEEE Standard 754-1985, August 1985. + + [IANA] Narten, T. and H. Alvestrand, "Guidelines for Writing + an IANA Considerations Section in RFCs", BCP 26, RFC + 2434, October 1998. + + + + +Calhoun, et al. Standards Track [Page 136] + +RFC 3588 Diameter Based Protocol September 2003 + + + [IANAADFAM] IANA; "Address Family Numbers", + http://www.iana.org/assignments/address-family-numbers + + [IANAWEB] IANA, "Number assignment", http://www.iana.org + + [IKE] Harkins, D. and D. Carrel, "The Internet Key Exchange + (IKE)", RFC 2409, November 1998. + + [IPComp] Shacham, A., Monsour, R., Pereira, R. and M. Thomas, + "IP Payload Compression Protocol (IPComp)", RFC 3173, + September 2001. + + [IPSECDOI] Piper, D., "The Internet IP Security Domain of + Interpretation for ISAKMP", RFC 2407, November 1998. + + [IPV4] Postel, J., "Internet Protocol", STD 5, RFC 791, + September 1981. + + [IPV6] Hinden, R. and S. Deering, "IP Version 6 Addressing + Architecture", RFC 2373, July 1998. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [NAI] Aboba, B. and M. Beadles, "The Network Access + Identifier", RFC 2486, January 1999. + + [NAPTR] Mealling, M. and R. Daniel, "The naming authority + pointer (NAPTR) DNS resource record," RFC 2915, + September 2000. + + [RADTYPE] IANA, "RADIUS Types", + http://www.iana.org/assignments/radius-types + + [SCTP] Stewart, R., Xie, Q., Morneault, K., Sharp, C., + Schwarzbauer, H., Taylor, T., Rytina, I., Kalla, M., + Zhang, L. and V. Paxson, "Stream Control Transmission + Protocol", RFC 2960, October 2000. + + [SLP] Veizades, J., Guttman, E., Perkins, C. and M. Day, + "Service Location Protocol, Version 2", RFC 2165, June + 1999. + + [SNTP] Mills, D., "Simple Network Time Protocol (SNTP) + Version 4 for IPv4, IPv6 and OSI", RFC 2030, October + 1996. + + + + + +Calhoun, et al. Standards Track [Page 137] + +RFC 3588 Diameter Based Protocol September 2003 + + + [TCP] Postel, J. "Transmission Control Protocol", STD 7, RFC + 793, January 1981. + + [TEMPLATE] Guttman, E., Perkins, C. and J. Kempf, "Service + Templates and Service: Schemes", RFC 2609, June 1999. + + [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version + 1.0", RFC 2246, January 1999. + + [TLSSCTP] Jungmaier, A., Rescorla, E. and M. Tuexen, "Transport + Layer Security over Stream Control Transmission + Protocol", RFC 3436, December 2002. + + [URI] Berners-Lee, T., Fielding, R. and L. Masinter, + "Uniform Resource Identifiers (URI): Generic Syntax", + RFC 2396, August 1998. + + [UTF8] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", RFC 2279, January 1998. + +14.2. Informative References + + [AAACMS] P. Calhoun, W. Bulley, S. Farrell, "Diameter CMS + Security Application", Work in Progress. + + [AAAREQ] Aboba, B., Calhoun, P., Glass, S., Hiller, T., McCann, + P., Shiino, H., Zorn, G., Dommety, G., Perkins, C., + Patil, B., Mitton, D., Manning, S., Beadles, M., + Walsh, P., Chen, X., Sivalingham, S., Hameed, A., + Munson, M., Jacobs, S., Lim, B., Hirschman, B., Hsu, + R., Xu, Y., Campbell, E., Baba, S. and E. Jaques, + "Criteria for Evaluating AAA Protocols for Network + Access", RFC 2989, November 2000. + + [ACCMGMT] Aboba, B., Arkko, J. and D. Harrington. "Introduction + to Accounting Management", RFC 2975, October 2000. + + [CDMA2000] Hiller, T., Walsh, P., Chen, X., Munson, M., Dommety, + G., Sivalingham, S., Lim, B., McCann, P., Shiino, H., + Hirschman, B., Manning, S., Hsu, R., Koo, H., Lipford, + M., Calhoun, P., Lo, C., Jaques, E., Campbell, E., Xu, + Y., Baba, S., Ayaki, T., Seki, T. and A. Hameed, + "CDMA2000 Wireless Data Requirements for AAA", RFC + 3141, June 2001. + + [DIAMMIP] P. Calhoun, C. Perkins, "Diameter Mobile IP + Application", Work in Progress. + + + + +Calhoun, et al. Standards Track [Page 138] + +RFC 3588 Diameter Based Protocol September 2003 + + + [DYNAUTH] Chiba, M., Dommety, G., Eklund, M., Mitton, D. and B. + Aboba, "Dynamic Authorization Extensions to Remote + Authentication Dial In User Service (RADIUS)", RFC + 3576, July 2003. + + [IANA-EXP] T. Narten, "Assigning Experimental and Testing Numbers + Considered Useful", Work in Progress. + + [MIPV4] Perkins, C., "IP Mobility Support for IPv4", RFC 3344, + August 2002. + + [MIPREQ] Glass, S., Hiller, T., Jacobs, S. and C. Perkins, + "Mobile IP Authentication, Authorization, and + Accounting Requirements", RFC 2977, October 2000. + + [NASNG] Mitton, D. and M. Beadles, "Network Access Server + Requirements Next Generation (NASREQNG) NAS Model", + RFC 2881, July 2000. + + [NASREQ] P. Calhoun, W. Bulley, A. Rubens, J. Haag, "Diameter + NASREQ Application", Work in Progress. + + [NASCRIT] Beadles, M. and D. Mitton, "Criteria for Evaluating + Network Access Server Protocols", RFC 3169, September + 2001. + + [PPP] Simpson, W., "The Point-to-Point Protocol (PPP)", STD + 51, RFC 1661, July 1994. + + [PROXYCHAIN] Aboba, B. and J. Vollbrecht, "Proxy Chaining and + Policy Implementation in Roaming", RFC 2607, June + 1999. + + [RADACCT] Rigney, C., "RADIUS Accounting", RFC 2866, June 2000. + + [RADEXT] Rigney, C., Willats, W. and P. Calhoun, "RADIUS + Extensions", RFC 2869, June 2000. + + [RADIUS] Rigney, C., Willens, S., Rubens, A. and W. Simpson, + "Remote Authentication Dial In User Service (RADIUS)", + RFC 2865, June 2000. + + [ROAMREV] Aboba, B., Lu, J., Alsop, J., Ding, J. and W. Wang, + "Review of Roaming Implementations", RFC 2194, + September 1997. + + [ROAMCRIT] Aboba, B. and G. Zorn, "Criteria for Evaluating + Roaming Protocols", RFC 2477, January 1999. + + + +Calhoun, et al. Standards Track [Page 139] + +RFC 3588 Diameter Based Protocol September 2003 + + + [SECARCH] Kent, S. and R. Atkinson, "Security Architecture for + the Internet Protocol", RFC 2401, November 1998. + + [TACACS] Finseth, C., "An Access Control Protocol, Sometimes + Called TACACS", RFC 1492, July 1993. + +15. Acknowledgements + + The authors would like to thank Nenad Trifunovic, Tony Johansson and + Pankaj Patel for their participation in the pre-IETF Document Reading + Party. Allison Mankin, Jonathan Wood and Bernard Aboba provided + invaluable assistance in working out transport issues, and similarly + with Steven Bellovin in the security area. + + Paul Funk and David Mitton were instrumental in getting the Peer + State Machine correct, and our deep thanks go to them for their time. + + Text in this document was also provided by Paul Funk, Mark Eklund, + Mark Jones and Dave Spence. Jacques Caron provided many great + comments as a result of a thorough review of the spec. + + The authors would also like to acknowledge the following people for + their contribution in the development of the Diameter protocol: + + Allan C. Rubens, Haseeb Akhtar, William Bulley, Stephen Farrell, + David Frascone, Daniel C. Fox, Lol Grant, Ignacio Goyret, Nancy + Greene, Peter Heitman, Fredrik Johansson, Mark Jones, Martin Julien, + Bob Kopacz, Paul Krumviede, Fergal Ladley, Ryan Moats, Victor Muslin, + Kenneth Peirce, John Schnizlein, Sumit Vakil, John R. Vollbrecht and + Jeff Weisberg. + + Finally, Pat Calhoun would like to thank Sun Microsystems since most + of the effort put into this document was done while he was in their + employ. + + + + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 140] + +RFC 3588 Diameter Based Protocol September 2003 + + +Appendix A. Diameter Service Template + + The following service template describes the attributes used by + Diameter servers to advertise themselves. This simplifies the + process of selecting an appropriate server to communicate with. A + Diameter client can request specific Diameter servers based on + characteristics of the Diameter service desired (for example, an AAA + server to use for accounting.) + + Name of submitter: "Erik Guttman" <[email protected]> Language of + service template: en + + Security Considerations: + Diameter clients and servers use various cryptographic mechanisms + to protect communication integrity, confidentiality as well as + perform end-point authentication. It would thus be difficult if + not impossible for an attacker to advertise itself using SLPv2 and + pose as a legitimate Diameter peer without proper preconfigured + secrets or cryptographic keys. Still, as Diameter services are + vital for network operation it is important to use SLPv2 + authentication to prevent an attacker from modifying or + eliminating service advertisements for legitimate Diameter + servers. + + Template text: + -------------------------template begins here----------------------- + template-type=service:diameter + + template-version=0.0 + + template-description= + The Diameter protocol is defined by RFC 3588. + + template-url-syntax= + url-path= ; The Diameter URL format is described in Section 2.9. + ; Example: 'aaa://aaa.example.com:1812;transport=tcp + supported-auth-applications= string L M + # This attribute lists the Diameter applications supported by the + # AAA implementation. The applications currently defined are: + # Application Name Defined by + # ---------------- ----------------------------------- + # NASREQ Diameter Network Access Server Application + # MobileIP Diameter Mobile IP Application + # + # Notes: + # . Diameter implementations support one or more applications. + # . Additional applications may be defined in the future. + # An updated service template will be created at that time. + + + +Calhoun, et al. Standards Track [Page 141] + +RFC 3588 Diameter Based Protocol September 2003 + + + # + NASREQ,MobileIP + + supported-acct-applications= string L M + # This attribute lists the Diameter applications supported by the + # AAA implementation. The applications currently defined are: + # Application Name Defined by + # ---------------- ----------------------------------- + # NASREQ Diameter Network Access Server Application + # MobileIP Diameter Mobile IP Application + # + # Notes: + # . Diameter implementations support one or more applications. + # . Additional applications may be defined in the future. + # An updated service template will be created at that time. + # + NASREQ,MobileIP + + supported-transports= string L M + SCTP + # This attribute lists the supported transports that the Diameter + # implementation accepts. Note that a compliant Diameter + # implementation MUST support SCTP, though it MAY support other + # transports, too. + SCTP,TCP + + -------------------------template ends here----------------------- + +Appendix B. NAPTR Example + + As an example, consider a client that wishes to resolve aaa:ex.com. + The client performs a NAPTR query for that domain, and the following + NAPTR records are returned: + + ;; order pref flags service regexp replacement + IN NAPTR 50 50 "s" "AAA+D2S" "" + _diameter._sctp.example.com IN NAPTR 100 50 "s" "AAA+D2T" + "" _aaa._tcp.example.com + + This indicates that the server supports SCTP, and TCP, in that order. + If the client supports over SCTP, SCTP will be used, targeted to a + host determined by an SRV lookup of _diameter._sctp.ex.com. That + lookup would return: + + ;; Priority Weight Port Target + IN SRV 0 1 5060 server1.example.com IN SRV 0 + 2 5060 server2.example.com + + + + +Calhoun, et al. Standards Track [Page 142] + +RFC 3588 Diameter Based Protocol September 2003 + + +Appendix C. Duplicate Detection + + As described in Section 9.4, accounting record duplicate detection is + based on session identifiers. Duplicates can appear for various + reasons: + + - Failover to an alternate server. Where close to real-time + performance is required, failover thresholds need to be kept low + and this may lead to an increased likelihood of duplicates. + Failover can occur at the client or within Diameter agents. + + - Failure of a client or agent after sending of a record from non- + volatile memory, but prior to receipt of an application layer ACK + and deletion of the record. record to be sent. This will result + in retransmission of the record soon after the client or agent has + rebooted. + + - Duplicates received from RADIUS gateways. Since the + retransmission behavior of RADIUS is not defined within [RFC2865], + the likelihood of duplication will vary according to the + implementation. + + - Implementation problems and misconfiguration. + + The T flag is used as an indication of an application layer + retransmission event, e.g., due to failover to an alternate server. + It is defined only for request messages sent by Diameter clients or + agents. For instance, after a reboot, a client may not know whether + it has already tried to send the accounting records in its non- + volatile memory before the reboot occurred. Diameter servers MAY use + the T flag as an aid when processing requests and detecting duplicate + messages. However, servers that do this MUST ensure that duplicates + are found even when the first transmitted request arrives at the + server after the retransmitted request. It can be used only in cases + where no answer has been received from the Server for a request and + the request is sent again, (e.g., due to a failover to an alternate + peer, due to a recovered primary peer or due to a client re-sending a + stored record from non-volatile memory such as after reboot of a + client or agent). + + In some cases the Diameter accounting server can delay the duplicate + detection and accounting record processing until a post-processing + phase takes place. At that time records are likely to be sorted + according to the included User-Name and duplicate elimination is easy + in this case. In other situations it may be necessary to perform + real-time duplicate detection, such as when credit limits are imposed + or real-time fraud detection is desired. + + + + +Calhoun, et al. Standards Track [Page 143] + +RFC 3588 Diameter Based Protocol September 2003 + + + In general, only generation of duplicates due to failover or re- + sending of records in non-volatile storage can be reliably detected + by Diameter clients or agents. In such cases the Diameter client or + agents can mark the message as possible duplicate by setting the T + flag. Since the Diameter server is responsible for duplicate + detection, it can choose to make use of the T flag or not, in order + to optimize duplicate detection. Since the T flag does not affect + interoperability, and may not be needed by some servers, generation + of the T flag is REQUIRED for Diameter clients and agents, but MAY be + implemented by Diameter servers. + + As an example, it can be usually be assumed that duplicates appear + within a time window of longest recorded network partition or device + fault, perhaps a day. So only records within this time window need + to be looked at in the backward direction. Secondly, hashing + techniques or other schemes, such as the use of the T flag in the + received messages, may be used to eliminate the need to do a full + search even in this set except for rare cases. + + The following is an example of how the T flag may be used by the + server to detect duplicate requests. + + A Diameter server MAY check the T flag of the received message to + determine if the record is a possible duplicate. If the T flag is + set in the request message, the server searches for a duplicate + within a configurable duplication time window backward and + forward. This limits database searching to those records where + the T flag is set. In a well run network, network partitions and + device faults will presumably be rare events, so this approach + represents a substantial optimization of the duplicate detection + process. During failover, it is possible for the original record + to be received after the T flag marked record, due to differences + in network delays experienced along the path by the original and + duplicate transmissions. The likelihood of this occurring + increases as the failover interval is decreased. In order to be + able to detect out of order duplicates, the Diameter server should + use backward and forward time windows when performing duplicate + checking for the T flag marked request. For example, in order to + allow time for the original record to exit the network and be + recorded by the accounting server, the Diameter server can delay + processing records with the T flag set until a time period + TIME_WAIT + RECORD_PROCESSING_TIME has elapsed after the closing + of the original transport connection. After this time period has + expired, then it may check the T flag marked records against the + database with relative assurance that the original records, if + sent, have been received and recorded. + + + + + +Calhoun, et al. Standards Track [Page 144] + +RFC 3588 Diameter Based Protocol September 2003 + + +Appendix D. Intellectual Property Statement + + The IETF takes no position regarding the validity or scope of any + intellectual property or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; neither does it represent that it + has made any effort to identify any such rights. Information on the + IETF's procedures with respect to rights in standards-track and + standards-related documentation can be found in BCP-11. Copies of + claims of rights made available for publication and any assurances of + licenses to be made available, or the result of an attempt made to + obtain a general license or permission for the use of such + proprietary rights by implementers or users of this specification can + be obtained from the IETF Secretariat. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights which may cover technology that may be required to practice + this standard. Please address the information to the IETF Executive + Director. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 145] + +RFC 3588 Diameter Based Protocol September 2003 + + +Authors' Addresses + + Pat R. Calhoun + Airespace, Inc. + 110 Nortech Parkway + San Jose, California, 95134 + USA + + Phone: +1 408-635-2023 + Fax: +1 408-635-2020 + EMail: [email protected] + + John Loughney + Nokia Research Center + Itamerenkatu 11-13 + 00180 Helsinki + Finland + + Phone: +358 50 483 6242 + EMail: [email protected] + + Jari Arkko + Ericsson + 02420 Jorvas + Finland + + Phone: +358 40 5079256 + EMail: [email protected] + + Erik Guttman + Sun Microsystems, Inc. + Eichhoelzelstr. 7 + 74915 Waibstadt + Germany + + Phone: +49 7263 911 701 + EMail: [email protected] + + Glen Zorn + Cisco Systems, Inc. + 500 108th Avenue N.E., Suite 500 + Bellevue, WA 98004 + USA + + Phone: +1 425 438 8218 + + + + + + +Calhoun, et al. Standards Track [Page 146] + +RFC 3588 Diameter Based Protocol September 2003 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2003). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 147] + diff --git a/lib/diameter/doc/standard/rfc4005.txt b/lib/diameter/doc/standard/rfc4005.txt new file mode 100644 index 0000000000..561508b53b --- /dev/null +++ b/lib/diameter/doc/standard/rfc4005.txt @@ -0,0 +1,4763 @@ + + + + + + +Network Working Group P. Calhoun +Request for Comments: 4005 G. Zorn +Category: Standards Track Cisco Systems Inc. + D. Spence + Consultant + D. Mitton + Circular Networks + August 2005 + + + Diameter Network Access Server Application + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2005). + +Abstract + + This document describes the Diameter protocol application used for + Authentication, Authorization, and Accounting (AAA) services in the + Network Access Server (NAS) environment. When combined with the + Diameter Base protocol, Transport Profile, and Extensible + Authentication Protocol specifications, this application + specification satisfies typical network access services requirements. + + Initial deployments of the Diameter protocol are expected to include + legacy systems. Therefore, this application has been carefully + designed to ease the burden of protocol conversion between RADIUS and + Diameter. This is achieved by including the RADIUS attribute space + to eliminate the need to perform many attribute translations. + + The interactions between Diameter applications and RADIUS specified + in this document are to be applied to all Diameter applications. In + this sense, this document extends the Base Diameter protocol. + + + + + + + + + +Calhoun, et al. Standards Track [Page 1] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . 5 + 1.2. Requirements Language . . . . . . . . . . . . . . . . . 6 + 1.3. Advertising Application Support . . . . . . . . . . . . 6 + 2. NAS Calls, Ports, and Sessions . . . . . . . . . . . . . . . . 6 + 2.1. Diameter Session Establishment . . . . . . . . . . . . . 7 + 2.2. Diameter Session Reauthentication or Reauthorization . . 7 + 2.3. Diameter Session Termination . . . . . . . . . . . . . . 8 + 3. NAS Messages . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 3.1. AA-Request (AAR) Command . . . . . . . . . . . . . . . . 9 + 3.2. AA-Answer (AAA) Command . . . . . . . . . . . . . . . . 11 + 3.3. Re-Auth-Request (RAR) Command . . . . . . . . . . . . . 13 + 3.4. Re-Auth-Answer (RAA) Command . . . . . . . . . . . . . . 14 + 3.5. Session-Termination-Request (STR) Command . . . . . . . 15 + 3.6. Session-Termination-Answer (STA) Command . . . . . . . . 15 + 3.7. Abort-Session-Request (ASR) Command . . . . . . . . . . 16 + 3.8. Abort-Session-Answer (ASA) Command . . . . . . . . . . . 17 + 3.9. Accounting-Request (ACR) Command . . . . . . . . . . . . 17 + 3.10. Accounting-Answer (ACA) Command. . . . . . . . . . . . . 19 + 4. NAS Session AVPs . . . . . . . . . . . . . . . . . . . . . . . 20 + 4.1. Call and Session Information . . . . . . . . . . . . . . 21 + 4.2. NAS-Port AVP . . . . . . . . . . . . . . . . . . . . . . 22 + 4.3. NAS-Port-Id AVP . . . . . . . . . . . . . . . . . . . . 22 + 4.4. NAS-Port-Type AVP . . . . . . . . . . . . . . . . . . . 22 + 4.5. Called-Station-Id AVP . . . . . . . . . . . . . . . . . 23 + 4.6. Calling-Station-Id AVP . . . . . . . . . . . . . . . . . 23 + 4.7. Connect-Info AVP . . . . . . . . . . . . . . . . . . . . 24 + 4.8. Originating-Line-Info AVP . . . . . . . . . . . . . . . 24 + 4.9. Reply-Message AVP . . . . . . . . . . . . . . . . . . . 25 + 5. NAS Authentication AVPs . . . . . . . . . . . . . . . . . . . 26 + 5.1. User-Password AVP . . . . . . . . . . . . . . . . . . . 26 + 5.2. Password-Retry AVP . . . . . . . . . . . . . . . . . . . 27 + 5.3. Prompt AVP . . . . . . . . . . . . . . . . . . . . . . . 27 + 5.4. CHAP-Auth AVP . . . . . . . . . . . . . . . . . . . . . 27 + 5.5. CHAP-Algorithm AVP . . . . . . . . . . . . . . . . . . . 28 + 5.6. CHAP-Ident AVP . . . . . . . . . . . . . . . . . . . . . 28 + 5.7. CHAP-Response AVP . . . . . . . . . . . . . . . . . . . 28 + 5.8. CHAP-Challenge AVP . . . . . . . . . . . . . . . . . . . 28 + 5.9. ARAP-Password AVP . . . . . . . . . . . . . . . . . . . 28 + 5.10. ARAP-Challenge-Response AVP. . . . . . . . . . . . . . . 28 + 5.11. ARAP-Security AVP. . . . . . . . . . . . . . . . . . . . 29 + 5.12. ARAP-Security-Data AVP . . . . . . . . . . . . . . . . . 29 + 6. NAS Authorization AVPs . . . . . . . . . . . . . . . . . . . . 29 + 6.1. Service-Type AVP . . . . . . . . . . . . . . . . . . . . 30 + 6.2. Callback-Number AVP . . . . . . . . . . . . . . . . . . 32 + 6.3. Callback-Id AVP . . . . . . . . . . . . . . . . . . . . 32 + + + +Calhoun, et al. Standards Track [Page 2] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + 6.4. Idle-Timeout AVP . . . . . . . . . . . . . . . . . . . . 32 + 6.5. Port-Limit AVP . . . . . . . . . . . . . . . . . . . . . 32 + 6.6. NAS-Filter-Rule AVP . . . . . . . . . . . . . . . . . . 32 + 6.7. Filter-Id AVP . . . . . . . . . . . . . . . . . . . . . 33 + 6.8. Configuration-Token AVP . . . . . . . . . . . . . . . . 33 + 6.9. QoS-Filter-Rule AVP . . . . . . . . . . . . . . . . . . 33 + 6.10. Framed Access Authorization AVPs . . . . . . . . . . . . 35 + 6.10.1. Framed-Protocol AVP . . . . . . . . . . . . . . 35 + 6.10.2. Framed-Routing AVP. . . . . . . . . . . . . . . 35 + 6.10.3. Framed-MTU AVP. . . . . . . . . . . . . . . . . 35 + 6.10.4. Framed-Compression AVP. . . . . . . . . . . . . 36 + 6.11. IP Access Authorization AVPs.. . . . . . . . . . . . . . 36 + 6.11.1. Framed-IP-Address AVP . . . . . . . . . . . . . 36 + 6.11.2. Framed-IP-Netmask AVP . . . . . . . . . . . . . 36 + 6.11.3. Framed-Route AVP. . . . . . . . . . . . . . . . 37 + 6.11.4. Framed-Pool AVP . . . . . . . . . . . . . . . . 37 + 6.11.5. Framed-Interface-Id AVP . . . . . . . . . . . . 37 + 6.11.6. Framed-IPv6-Prefix AVP. . . . . . . . . . . . . 38 + 6.11.7. Framed-IPv6-Route AVP . . . . . . . . . . . . . 38 + 6.11.8. Framed-IPv6-Pool AVP. . . . . . . . . . . . . . 38 + 6.12. IPX Access . . . . . . . . . . . . . . . . . . . . . . . 38 + 6.12.1. Framed-IPX-Network AVP. . . . . . . . . . . . . 39 + 6.13. AppleTalk Network Access . . . . . . . . . . . . . . . . 39 + 6.13.1. Framed-AppleTalk-Link AVP . . . . . . . . . . . 39 + 6.13.2. Framed-AppleTalk-Network AVP . . . . . . . . . 39 + 6.13.3. Framed-AppleTalk-Zone AVP . . . . . . . . . . . 40 + 6.14. AppleTalk Remote Access. . . . . . . . . . . . . . . . . 40 + 6.14.1. ARAP-Features AVP . . . . . . . . . . . . . . . 40 + 6.14.2. ARAP-Zone-Access AVP. . . . . . . . . . . . . . 40 + 6.15. Non-Framed Access Authorization AVPs . . . . . . . . . . 40 + 6.15.1. Login-IP-Host AVP . . . . . . . . . . . . . . . 40 + 6.15.2. Login-IPv6-Host AVP . . . . . . . . . . . . . . 41 + 6.15.3. Login-Service AVP . . . . . . . . . . . . . . . 41 + 6.16. TCP Services . . . . . . . . . . . . . . . . . . . . . . 42 + 6.16.1. Login-TCP-Port AVP . . . . . . . . . . . . . . 42 + 6.17. LAT Services . . . . . . . . . . . . . . . . . . . . . . 42 + 6.17.1. Login-LAT-Service AVP . . . . . . . . . . . . . 42 + 6.17.2. Login-LAT-Node AVP. . . . . . . . . . . . . . . 43 + 6.17.3. Login-LAT-Group AVP . . . . . . . . . . . . . . 43 + 6.17.4. Login-LAT-Port AVP. . . . . . . . . . . . . . . 43 + 7. NAS Tunneling . . . . . . . . . . . . . . . . . . . . . . . . 44 + 7.1. Tunneling AVP . . . . . . . . . . . . . . . . . . . . . 44 + 7.2. Tunnel-Type AVP . . . . . . . . . . . . . . . . . . . . 45 + 7.3. Tunnel-Medium-Type AVP . . . . . . . . . . . . . . . . . 46 + 7.4. Tunnel-Client-Endpoint AVP . . . . . . . . . . . . . . . 46 + 7.5. Tunnel-Server-Endpoint AVP . . . . . . . . . . . . . . . 47 + 7.6. Tunnel-Password AVP . . . . . . . . . . . . . . . . . . 48 + 7.7. Tunnel-Private-Group-Id AVP . . . . . . . . . . . . . . 48 + + + +Calhoun, et al. Standards Track [Page 3] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + 7.8. Tunnel-Assignment-Id AVP . . . . . . . . . . . . . . . . 48 + 7.9. Tunnel-Preference AVP . . . . . . . . . . . . . . . . . 49 + 7.10. Tunnel-Client-Auth-Id AVP. . . . . . . . . . . . . . . . 50 + 7.11. Tunnel-Server-Auth-Id AVP. . . . . . . . . . . . . . . . 50 + 8. NAS Accounting . . . . . . . . . . . . . . . . . . . . . . . . 50 + 8.1. Accounting-Input-Octets AVP . . . . . . . . . . . . . . 51 + 8.2. Accounting-Output-Octets AVP . . . . . . . . . . . . . . 52 + 8.3. Accounting-Input-Packets AVP . . . . . . . . . . . . . . 52 + 8.4. Accounting-Output-Packets AVP . . . . . . . . . . . . . 52 + 8.5. Acct-Session-Time AVP . . . . . . . . . . . . . . . . . 52 + 8.6. Acct-Authentic AVP . . . . . . . . . . . . . . . . . . . 52 + 8.7. Accounting-Auth-Method AVP . . . . . . . . . . . . . . . 53 + 8.8. Acct-Delay-Time . . . . . . . . . . . . . . . . . . . . 53 + 8.9. Acct-Link-Count . . . . . . . . . . . . . . . . . . . . 54 + 8.10. Acct-Tunnel-Connection AVP . . . . . . . . . . . . . . . 54 + 8.11. Acct-Tunnel-Packets-Lost AVP . . . . . . . . . . . . . . 55 + 9. RADIUS/Diameter Protocol Interactions . . . . . . . . . . . . 55 + 9.1. RADIUS Request Forwarded as Diameter Request . . . . . . 55 + 9.1.1. RADIUS Dynamic Authorization Considerations . . 59 + 9.2. Diameter Request Forwarded as RADIUS Request . . . . . . 60 + 9.2.1. RADIUS Dynamic Authorization Considerations . . 62 + 9.3. AVPs Used Only for Compatibility . . . . . . . . . . . . 63 + 9.3.1. NAS-Identifier AVP. . . . . . . . . . . . . . . 63 + 9.3.2. NAS-IP-Address AVP. . . . . . . . . . . . . . . 64 + 9.3.3. NAS-IPv6-Address AVP. . . . . . . . . . . . . . 65 + 9.3.4. State AVP . . . . . . . . . . . . . . . . . . . 65 + 9.3.5. Termination-Cause AVP Code Values . . . . . . . 66 + 9.3.6. Origin-AAA-Protocol . . . . . . . . . . . . . . 68 + 9.4. Prohibited RADIUS Attributes . . . . . . . . . . . . . . 69 + 9.5. Translatable Diameter AVPs . . . . . . . . . . . . . . . 69 + 9.6. RADIUS Vendor-Specific Attributes . . . . . . . . . . . 69 + 9.6.1. Forwarding a Diameter Vendor Specific AVP as a + RADIUS VSA . . . . . . . . . . . . . . . . . . . 70 + 9.6.2. Forwarding a RADIUS VSA as a Diameter Vendor + Specific AVP . . . . . . . . . . . . . . . . . . 70 + 10. AVP Occurrence Tables. . . . . . . . . . . . . . . . . . . . . 71 + 10.1. AA-Request/Answer AVP Table. . . . . . . . . . . . . . . 71 + 10.2. Accounting AVP Tables. . . . . . . . . . . . . . . . . . 73 + 10.2.1. Accounting Framed Access AVP Table. . . . . . . 74 + 10.2.2. Accounting Non-Framed Access AVP Table. . . . . 76 + 11. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 77 + 11.1. Command Codes. . . . . . . . . . . . . . . . . . . . . . 77 + 11.2. AVP Codes. . . . . . . . . . . . . . . . . . . . . . . . 78 + 11.3. Application Identifier . . . . . . . . . . . . . . . . . 78 + 11.4. CHAP-Algorithm AVP Values. . . . . . . . . . . . . . . . 78 + 11.5. Accounting-Auth-Method AVP Values. . . . . . . . . . . . 78 + 11.6. Origin-AAA-Protocol AVP Values . . . . . . . . . . . . . 78 + 12. Security Considerations. . . . . . . . . . . . . . . . . . . . 78 + + + +Calhoun, et al. Standards Track [Page 4] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 79 + 13.1. Normative References . . . . . . . . . . . . . . . . . . 79 + 13.2. Informative References . . . . . . . . . . . . . . . . . 80 + 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 83 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 84 + Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 85 + +1. Introduction + + This document describes the Diameter protocol application used for + AAA in the Network Access Server (NAS) environment. When combined + with the Diameter Base protocol [BASE], Transport Profile + [DiamTrans], and EAP [DiamEAP] specifications, this Diameter NAS + application specification satisfies NAS-related requirements defined + in RFC 2989 [AAACriteria] and RFC 3169 [NASCriteria]. + + Initial deployments of the Diameter protocol are expected to include + legacy systems. Therefore, this application has been carefully + designed to ease the burden of protocol conversion between RADIUS and + Diameter. This is achieved by including the RADIUS attribute space + to eliminate the need to perform many attribute translations. + + The interactions specified in this document between Diameter + applications and RADIUS are to be applied to all Diameter + applications. In this sense, this document extends the Base Diameter + protocol [BASE]. + + First, this document describes the operation of a Diameter NAS + application. Then it defines the Diameter message Command-Codes. + The following sections list the AVPs used in these messages, grouped + by common usage. These are session identification, authentication, + authorization, tunneling, and accounting. The authorization AVPs are + further broken down by service type. Interaction and backward + compatibility issues with RADIUS are discussed in later sections. + +1.1. Terminology + + The base Diameter [BASE] specification section 1.4 defines most of + the terminology used in this document. Additionally, the following + terms and acronyms are used in this application: + + NAS (Network Access Server) - A device that provides an access + service for a user to a network. The service may be a network + connection or a value-added service such as terminal emulation + [NASModel]. + + + + + + +Calhoun, et al. Standards Track [Page 5] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + PPP (Point-to-Point Protocol) - A multiprotocol serial datalink. PPP + is the primary IP datalink used for dial-in NAS connection service + [PPP]. + + CHAP (Challenge Handshake Authentication Protocol) - An + authentication process used in PPP [PPPCHAP]. + + PAP (Password Authentication Protocol) - A deprecated PPP + authentication process, but often used for backward compatibility + [PAP]. + + SLIP (Serial Line Interface Protocol) - A serial datalink that only + supports IP. A design prior to PPP. + + ARAP (Appletalk Remote Access Protocol) - A serial datalink for + accessing Appletalk networks [ARAP]. + + IPX (Internet Packet Exchange) - The network protocol used by NetWare + networks [IPX]. + + LAT (Local Area Transport) - A Digital Equipment Corp. LAN protocol + for terminal services [LAT]. + + VPN (Virtual Private Network) - In this document, this term is used + to describe access services that use tunneling methods. + +1.2. Requirements Language + + In this document, the key words "MAY", "MUST", "MUST NOT", + "OPTIONAL", "RECOMMENDED", "SHOULD", and "SHOULD NOT" are to be + interpreted as described in [Keywords]. + +1.3. Advertising Application Support + + Diameter applications conforming to this specification MUST advertise + support by including the value of one (1) in the Auth-Application-Id + of Capabilities-Exchange-Request (CER), AA-Request (AAR), and AA- + Answer (AAA) messages. All other messages are defined by [BASE] and + use the Base application id value. + +2. NAS Calls, Ports, and Sessions + + The arrival of a new call or service connection at a port of a + Network Access Server (NAS) starts a Diameter NAS message exchange. + Information about the call, the identity of the user, and the user's + authentication information are packaged into a Diameter AA-Request + (AAR) message and sent to a server. + + + + +Calhoun, et al. Standards Track [Page 6] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + The server processes the information and responds with a Diameter + AA-Answer (AAA) message that contains authorization information for + the NAS, or a failure code (Result-Code AVP). A value of + DIAMETER_MULTI_ROUND_AUTH indicates an additional authentication + exchange, and several AAR and AAA messages may be exchanged until the + transaction completes. + + Depending on the Auth-Request-Type AVP, the Diameter protocol allows + authorization-only requests that contain no authentication + information from the client. This capability goes beyond the Call + Check capabilities described in section 5.6 of [RADIUS] in that no + access decision is requested. As a result, service cannot be started + as a result of a response to an authorization-only request without + introducing a significant security vulnerability. + + Since no equivalent capability exists in RADIUS, authorization-only + requests from a NAS implementing Diameter may not be easily + translated to an equivalent RADIUS message by a Diameter/RADIUS + gateway. For example, when a Diameter authorization-only request + cannot be translated to a RADIUS Call Check, it would be necessary + for the Diameter/RADIUS gateway to add authentication information to + the RADIUS Access Request. On receiving the Access-Reply, the + Diameter/RADIUS gateway would need to discard the access decision + (Accept/Reject). It is not clear whether these translations can be + accomplished without adding significant security vulnerabilities. + +2.1. Diameter Session Establishment + + When the authentication or authorization exchange completes + successfully, the NAS application SHOULD start a session context. If + the Result-Code of DIAMETER_MULTI_ROUND_AUTH is returned, the + exchange continues until a success or error is returned. + + If accounting is active, the application MUST also send an Accounting + message [BASE]. An Accounting-Record-Type of START_RECORD is sent + for a new session. If a session fails to start, the EVENT_RECORD + message is sent with the reason for the failure described. + + Note that the return of an unsupportable Accounting-Realtime-Required + value [BASE] would result in a failure to establish the session. + +2.2. Diameter Session Reauthentication or Reauthorization + + The Diameter Base protocol allows users to be periodically + reauthenticated and/or reauthorized. In such instances, the + Session-Id AVP in the AAR message MUST be the same as the one present + in the original authentication/authorization message. + + + + +Calhoun, et al. Standards Track [Page 7] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + A Diameter server informs the NAS of the maximum time allowed before + reauthentication or reauthorization via the Authorization-Lifetime + AVP [BASE]. A NAS MAY reauthenticate and/or reauthorize before the + end, but A NAS MUST reauthenticate and/or reauthorize at the end of + the period provided by the Authorization-Lifetime AVP. The failure + of a reauthentication exchange will terminate the service. + + Furthermore, it is possible for Diameter servers to issue an + unsolicited reauthentication and/or reauthorization request (e.g., + Re-Auth-Request (RAR) message [BASE]) to the NAS. Upon receipt of + such a message, the NAS MUST respond to the request with a Re-Auth- + Answer (RAA) message [BASE]. + + If the RAR properly identifies an active session, the NAS will + initiate a new local reauthentication or authorization sequence as + indicated by the Re-Auth-Request-Type value. This will cause the NAS + to send a new AAR message using the existing Session-Id. The server + will respond with an AAA message to specify the new service + parameters. + + If accounting is active, every change of authentication or + authorization SHOULD generate an accounting message. If the NAS + service is a continuation of the prior user context, then an + Accounting-Record-Type of INTERIM_RECORD indicating the new session + attributes and cumulative status would be appropriate. If a new user + or a significant change in authorization is detected by the NAS, then + the service may send two messages of the types STOP_RECORD and + START_RECORD. Accounting may change the subsession identifiers + (Acct-Session-ID, or Acct-Sub-Session-Id) to indicate such sub- + sessions. A service may also use a different Session-Id value for + accounting (see [BASE] section 9.6). + + However, the Diameter Session-ID AVP value used for the initial + authorization exchange MUST be used to generate an STR message when + the session context is terminated. + +2.3. Diameter Session Termination + + When a NAS receives an indication that a user's session is being + disconnected by the client (e.g., LCP Terminate is received) or an + administrative command, the NAS MUST issue a Session-Termination- + Request (STR) [BASE] to its Diameter Server. This will ensure that + any resources maintained on the servers are freed appropriately. + + Furthermore, a NAS that receives an Abort-Session-Request (ASR) + [BASE] MUST issue an ASA if the session identified is active and + disconnect the PPP (or tunneling) session. + + + + +Calhoun, et al. Standards Track [Page 8] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + If accounting is active, an Accounting STOP_RECORD message [BASE] + MUST be sent upon termination of the session context. + + More information on Diameter Session Termination is included in + [BASE] sections 8.4 and 8.5. + +3. NAS Messages + + This section defines the Diameter message Command-Code [BASE] values + that MUST be supported by all Diameter implementations conforming to + this specification. The Command Codes are as follows: + + Command-Name Abbrev. Code Reference + ------------------------------------------------------- + AA-Request AAR 265 3.1 + AA-Answer AAA 265 3.2 + Re-Auth-Request RAR 258 3.3 + Re-Auth-Answer RAA 258 3.4 + Session-Termination-Request STR 275 3.5 + Session-Termination-Answer STA 275 3.6 + Abort-Session-Request ASR 274 3.7 + Abort-Session-Answer ASA 274 3.8 + Accounting-Request ACR 271 3.9 + Accounting-Answer ACA 271 3.10 + +3.1. AA-Request (AAR) Command + + The AA-Request (AAR), which is indicated by setting the Command-Code + field to 265 and the 'R' bit in the Command Flags field, is used to + request authentication and/or authorization for a given NAS user. + The type of request is identified through the Auth-Request-Type AVP + [BASE]. The recommended value for most RADIUS interoperabily + situations is AUTHORIZE_AUTHENTICATE. + + If Authentication is requested, the User-Name attribute SHOULD be + present, as well as any additional authentication AVPs that would + carry the password information. A request for authorization SHOULD + only include the information from which the authorization will be + performed, such as the User-Name, Called-Station-Id, or Calling- + Station-Id AVPs. All requests SHOULD contain AVPs uniquely + identifying the source of the call, such as Origin-Host and NAS-Port. + Certain networks MAY use different AVPs for authorization purposes. + A request for authorization will include some AVPs defined in section + 6. + + It is possible for a single session to be authorized first and then + for an authentication request to follow. + + + + +Calhoun, et al. Standards Track [Page 9] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + This AA-Request message MAY be the result of a multi-round + authentication exchange, which occurs when the AA-Answer message is + received with the Result-Code AVP set to DIAMETER_MULTI_ROUND_AUTH. + A subsequent AAR message SHOULD be sent, with the User-Password AVP + that includes the user's response to the prompt, and MUST include any + State AVPs that were present in the AAA message. + + Message Format + <AA-Request> ::= < Diameter Header: 265, REQ, PXY > + < Session-Id > + { Auth-Application-Id } + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Auth-Request-Type } + [ Destination-Host ] + [ NAS-Identifier ] + [ NAS-IP-Address ] + [ NAS-IPv6-Address ] + [ NAS-Port ] + [ NAS-Port-Id ] + [ NAS-Port-Type ] + [ Origin-AAA-Protocol ] + [ Origin-State-Id ] + [ Port-Limit ] + [ User-Name ] + [ User-Password ] + [ Service-Type ] + [ State ] + [ Authorization-Lifetime ] + [ Auth-Grace-Period ] + [ Auth-Session-State ] + [ Callback-Number ] + [ Called-Station-Id ] + [ Calling-Station-Id ] + [ Originating-Line-Info ] + [ Connect-Info ] + [ CHAP-Auth ] + [ CHAP-Challenge ] + * [ Framed-Compression ] + [ Framed-Interface-Id ] + [ Framed-IP-Address ] + * [ Framed-IPv6-Prefix ] + [ Framed-IP-Netmask ] + [ Framed-MTU ] + [ Framed-Protocol ] + [ ARAP-Password ] + [ ARAP-Security ] + + + +Calhoun, et al. Standards Track [Page 10] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + * [ ARAP-Security-Data ] + * [ Login-IP-Host ] + * [ Login-IPv6-Host ] + [ Login-LAT-Group ] + [ Login-LAT-Node ] + [ Login-LAT-Port ] + [ Login-LAT-Service ] + * [ Tunneling ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +3.2. AA-Answer (AAA) Command + + The AA-Answer (AAA) message is indicated by setting the Command-Code + field to 265 and clearing the 'R' bit in the Command Flags field. It + is sent in response to the AA-Request (AAR) message. If + authorization was requested, a successful response will include the + authorization AVPs appropriate for the service being provided, as + defined in section 6. + + For authentication exchanges requiring more than a single round trip, + the server MUST set the Result-Code AVP to DIAMETER_MULTI_ROUND_AUTH. + An AAA message with this result code MAY include one Reply-Message or + more and MAY include zero or one State AVPs. + + If the Reply-Message AVP was present, the network access server + SHOULD send the text to the user's client to display to the user, + instructing the client to prompt the user for a response. For + example, this capability can be achieved in PPP via PAP. If the + access client is unable to prompt the user for a new response, it + MUST treat the AA-Answer (AAA) with the Reply-Message AVP as an error + and deny access. + + Message Format + + <AA-Answer> ::= < Diameter Header: 265, PXY > + < Session-Id > + { Auth-Application-Id } + { Auth-Request-Type } + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + [ Service-Type ] + * [ Class ] + * [ Configuration-Token ] + [ Acct-Interim-Interval ] + + + +Calhoun, et al. Standards Track [Page 11] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + [ Error-Message ] + [ Error-Reporting-Host ] + * [ Failed-AVP ] + [ Idle-Timeout ] + [ Authorization-Lifetime ] + [ Auth-Grace-Period ] + [ Auth-Session-State ] + [ Re-Auth-Request-Type ] + [ Multi-Round-Time-Out ] + [ Session-Timeout ] + [ State ] + * [ Reply-Message ] + [ Origin-AAA-Protocol ] + [ Origin-State-Id ] + * [ Filter-Id ] + [ Password-Retry ] + [ Port-Limit ] + [ Prompt ] + [ ARAP-Challenge-Response ] + [ ARAP-Features ] + [ ARAP-Security ] + * [ ARAP-Security-Data ] + [ ARAP-Zone-Access ] + [ Callback-Id ] + [ Callback-Number ] + [ Framed-Appletalk-Link ] + * [ Framed-Appletalk-Network ] + [ Framed-Appletalk-Zone ] + * [ Framed-Compression ] + [ Framed-Interface-Id ] + [ Framed-IP-Address ] + * [ Framed-IPv6-Prefix ] + [ Framed-IPv6-Pool ] + * [ Framed-IPv6-Route ] + [ Framed-IP-Netmask ] + * [ Framed-Route ] + [ Framed-Pool ] + [ Framed-IPX-Network ] + [ Framed-MTU ] + [ Framed-Protocol ] + [ Framed-Routing ] + * [ Login-IP-Host ] + * [ Login-IPv6-Host ] + [ Login-LAT-Group ] + [ Login-LAT-Node ] + [ Login-LAT-Port ] + [ Login-LAT-Service ] + [ Login-Service ] + + + +Calhoun, et al. Standards Track [Page 12] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + [ Login-TCP-Port ] + * [ NAS-Filter-Rule ] + * [ QoS-Filter-Rule ] + * [ Tunneling ] + * [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ AVP ] + +3.3. Re-Auth-Request (RAR) Command + + A Diameter server may initiate a re-authentication and/or re- + authorization service for a particular session by issuing a Re-Auth- + Request (RAR) message [BASE]. + + For example, for pre-paid services, the Diameter server that + originally authorized a session may need some confirmation that the + user is still using the services. + + If a NAS receives an RAR message with Session-Id equal to a currently + active session and a Re-Auth-Type that includes authentication, it + MUST initiate a re-authentication toward the user, if the service + supports this particular feature. + + Message Format + + <RA-Request> ::= < Diameter Header: 258, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Destination-Host } + { Auth-Application-Id } + { Re-Auth-Request-Type } + [ User-Name ] + [ Origin-AAA-Protocol ] + [ Origin-State-Id ] + [ NAS-Identifier ] + [ NAS-IP-Address ] + [ NAS-IPv6-Address ] + [ NAS-Port ] + [ NAS-Port-Id ] + [ NAS-Port-Type ] + [ Service-Type ] + [ Framed-IP-Address ] + [ Framed-IPv6-Prefix ] + [ Framed-Interface-Id ] + + + +Calhoun, et al. Standards Track [Page 13] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + [ Called-Station-Id ] + [ Calling-Station-Id ] + [ Originating-Line-Info ] + [ Acct-Session-Id ] + [ Acct-Multi-Session-Id ] + [ State ] + * [ Class ] + [ Reply-Message ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +3.4. Re-Auth-Answer (RAA) Command + + The Re-Auth-Answer (RAA) message [BASE] is sent in response to the + RAR. The Result-Code AVP MUST be present and indicates the + disposition of the request. + + A successful RAA transaction MUST be followed by an AAR message. + + Message Format + + <RA-Answer> ::= < Diameter Header: 258, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + [ Origin-AAA-Protocol ] + [ Origin-State-Id ] + [ Error-Message ] + [ Error-Reporting-Host ] + * [ Failed-AVP ] + * [ Redirected-Host ] + [ Redirected-Host-Usage ] + [ Redirected-Host-Cache-Time ] + [ Service-Type ] + * [ Configuration-Token ] + [ Idle-Timeout ] + [ Authorization-Lifetime ] + [ Auth-Grace-Period ] + [ Re-Auth-Request-Type ] + [ State ] + * [ Class ] + * [ Reply-Message ] + [ Prompt ] + * [ Proxy-Info ] + * [ AVP ] + + + +Calhoun, et al. Standards Track [Page 14] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +3.5. Session-Termination-Request (STR) Command + + The Session-Termination-Request (STR) message [BASE] is sent by the + NAS to inform the Diameter Server that an authenticated and/or + authorized session is being terminated. + + Message Format + + <ST-Request> ::= < Diameter Header: 275, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Auth-Application-Id } + { Termination-Cause } + [ User-Name ] + [ Destination-Host ] + * [ Class ] + [ Origin-AAA-Protocol ] + [ Origin-State-Id ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +3.6. Session-Termination-Answer (STA) Command + + The Session-Termination-Answer (STA) message [BASE] is sent by the + Diameter Server to acknowledge the notification that the session has + been terminated. The Result-Code AVP MUST be present and MAY contain + an indication that an error occurred while the STR was being + serviced. + + Upon sending or receiving the STA, the Diameter Server MUST release + all resources for the session indicated by the Session-Id AVP. Any + intermediate server in the Proxy-Chain MAY also release any + resources, if necessary. + + Message Format + + <ST-Answer> ::= < Diameter Header: 275, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + * [ Class ] + [ Error-Message ] + [ Error-Reporting-Host ] + + + +Calhoun, et al. Standards Track [Page 15] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + * [ Failed-AVP ] + [ Origin-AAA-Protocol ] + [ Origin-State-Id ] + * [ Redirect-Host ] + [ Redirect-Host-Usase ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ AVP ] + +3.7. Abort-Session-Request (ASR) Command + + The Abort-Session-Request (ASR) message [BASE] may be sent by any + server to the NAS providing session service, to request that the + session identified by the Session-Id be stopped. + + Message Format + + <AS-Request> ::= < Diameter Header: 274, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Destination-Host } + { Auth-Application-Id } + [ User-Name ] + [ Origin-AAA-Protocol ] + [ Origin-State-Id ] + [ NAS-Identifier ] + [ NAS-IP-Address ] + [ NAS-IPv6-Address ] + [ NAS-Port ] + [ NAS-Port-Id ] + [ NAS-Port-Type ] + [ Service-Type ] + [ Framed-IP-Address ] + [ Framed-IPv6-Prefix ] + [ Framed-Interface-Id ] + [ Called-Station-Id ] + [ Calling-Station-Id ] + [ Originating-Line-Info ] + [ Acct-Session-Id ] + [ Acct-Multi-Session-Id ] + [ State ] + * [ Class ] + * [ Reply-Message ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + + + +Calhoun, et al. Standards Track [Page 16] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +3.8. Abort-Session-Answer (ASA) Command + + The ASA message [BASE] is sent in response to the ASR. The Result- + Code AVP MUST be present and indicates the disposition of the + request. + + If the session identified by Session-Id in the ASR was successfully + terminated, Result-Code is set to DIAMETER_SUCCESS. If the session + is not currently active, Result-Code is set to + DIAMETER_UNKNOWN_SESSION_ID. If the access device does not stop the + session for any other reason, Result-Code is set to + DIAMETER_UNABLE_TO_COMPLY. + + Message Format + + <AS-Answer> ::= < Diameter Header: 274, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + [ Origin-AAA-Protocol ] + [ Origin-State-Id ] + [ State] + [ Error-Message ] + [ Error-Reporting-Host ] + * [ Failed-AVP ] + * [ Redirected-Host ] + [ Redirected-Host-Usage ] + [ Redirected-Max-Cache-Time ] + * [ Proxy-Info ] + * [ AVP ] + +3.9. Accounting-Request (ACR) Command + + The ACR message [BASE] is sent by the NAS to report its session + information to a target server downstream. + + Either of Acct-Application-Id or Vendor-Specific-Application-Id AVPs + MUST be present. If the Vendor-Specific-Application-Id grouped AVP + is present, it must have an Acct-Application-Id inside. + + The AVPs listed in the Base MUST be assumed to be present, as + appropriate. NAS service-specific accounting AVPs SHOULD be present + as described in section 8 and the rest of this specification. + + + + + + +Calhoun, et al. Standards Track [Page 17] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + Message Format + + <AC-Request> ::= < Diameter Header: 271, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Accounting-Record-Type } + { Accounting-Record-Number } + [ Acct-Application-Id ] + [ Vendor-Specific-Application-Id ] + [ User-Name ] + [ Accounting-Sub-Session-Id ] + [ Acct-Session-Id ] + [ Acct-Multi-Session-Id ] + [ Origin-AAA-Protocol ] + [ Origin-State-Id ] + [ Destination-Host ] + [ Event-Timestamp ] + [ Acct-Delay-Time ] + [ NAS-Identifier ] + [ NAS-IP-Address ] + [ NAS-IPv6-Address ] + [ NAS-Port ] + [ NAS-Port-Id ] + [ NAS-Port-Type ] + * [ Class ] + [ Service-Type ] + [ Termination-Cause ] + [ Accounting-Input-Octets ] + [ Accounting-Input-Packets ] + [ Accounting-Output-Octets ] + [ Accounting-Output-Packets ] + [ Acct-Authentic ] + [ Accounting-Auth-Method ] + [ Acct-Link-Count ] + [ Acct-Session-Time ] + [ Acct-Tunnel-Connection ] + [ Acct-Tunnel-Packets-Lost ] + [ Callback-Id ] + [ Callback-Number ] + [ Called-Station-Id ] + [ Calling-Station-Id ] + * [ Connection-Info ] + [ Originating-Line-Info ] + [ Authorization-Lifetime ] + [ Session-Timeout ] + [ Idle-Timeout ] + + + +Calhoun, et al. Standards Track [Page 18] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + [ Port-Limit ] + [ Accounting-Realtime-Required ] + [ Acct-Interim-Interval ] + * [ Filter-Id ] + * [ NAS-Filter-Rule ] + * [ Qos-Filter-Rule ] + [ Framed-AppleTalk-Link ] + [ Framed-AppleTalk-Network ] + [ Framed-AppleTalk-Zone ] + [ Framed-Compression ] + [ Framed-Interface-Id ] + [ Framed-IP-Address ] + [ Framed-IP-Netmask ] + * [ Framed-IPv6-Prefix ] + [ Framed-IPv6-Pool ] + * [ Framed-IPv6-Route ] + [ Framed-IPX-Network ] + [ Framed-MTU ] + [ Framed-Pool ] + [ Framed-Protocol ] + * [ Framed-Route ] + [ Framed-Routing ] + * [ Login-IP-Host ] + * [ Login-IPv6-Host ] + [ Login-LAT-Group ] + [ Login-LAT-Node ] + [ Login-LAT-Port ] + [ Login-LAT-Service ] + [ Login-Service ] + [ Login-TCP-Port ] + * [ Tunneling ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +3.10. Accounting-Answer (ACA) Command + + The ACA message [BASE] is used to acknowledge an Accounting-Request + command. The Accounting-Answer command contains the same Session-Id + as the Request. If the Accounting-Request was protected by end-to- + end security, then the corresponding ACA message MUST be protected as + well. + + Only the target Diameter Server or home Diameter Server SHOULD + respond with the Accounting-Answer command. + + Either Acct-Application-Id or Vendor-Specific-Application-Id AVPs + MUST be present, as it was in the request. + + + +Calhoun, et al. Standards Track [Page 19] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + The AVPs listed in the Base MUST be assumed to be present, as + appropriate. NAS service-specific accounting AVPs SHOULD be present + as described in section 8 and the rest of this specification. + + Message Format + + <AC-Answer> ::= < Diameter Header: 271, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + { Accounting-Record-Type } + { Accounting-Record-Number } + [ Acct-Application-Id ] + [ Vendor-Specific-Application-Id ] + [ User-Name ] + [ Accounting-Sub-Session-Id ] + [ Acct-Session-Id ] + [ Acct-Multi-Session-Id ] + [ Event-Timestamp ] + [ Error-Message ] + [ Error-Reporting-Host ] + * [ Failed-AVP ] + [ Origin-AAA-Protocol ] + [ Origin-State-Id ] + [ NAS-Identifier ] + [ NAS-IP-Address ] + [ NAS-IPv6-Address ] + [ NAS-Port ] + [ NAS-Port-Id ] + [ NAS-Port-Type ] + [ Service-Type ] + [ Termination-Cause ] + [ Accounting-Realtime-Required ] + [ Acct-Interim-Interval ] + * [ Class ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +4. NAS Session AVPs + + Diameter reserves the AVP Codes 0 - 255 for RADIUS functions that are + implemented in Diameter. + + AVPs new to Diameter have code values of 256 and greater. A Diameter + message that includes one of these AVPs may represent functions not + present in the RADIUS environment and may cause interoperability + + + +Calhoun, et al. Standards Track [Page 20] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + issues, should the request traverse an AAA system that only supports + the RADIUS protocol. + + Some RADIUS attributes are not allowed or supported directly in + Diameter. See section 9 for more information. + +4.1. Call and Session Information + + This section contains the AVPs specific to NAS Diameter applications + that are needed to identify the call and session context and status + information. On a request, this information allows the server to + qualify the session. + + These AVPs are used in addition to the Base AVPs of: + + Session-Id + Auth-Application-Id + Origin-Host + Origin-Realm + Auth-Request-Type + Termination-Cause + + The following table describes the session level AVPs; their AVP Code + values, types, and possible flag values; and whether the AVP MAY be + encrypted. + + +---------------------+ + | AVP Flag rules | + |----+-----+----+-----|----+ + AVP Section | | |SHLD| MUST| | + Attribute Name Code Defined Value Type |MUST| MAY | NOT| NOT|Encr| + -----------------------------------------|----+-----+----+-----|----| + NAS-Port 5 4.2 Unsigned32 | M | P | | V | Y | + NAS-Port-Id 87 4.3 UTF8String | M | P | | V | Y | + NAS-Port-Type 61 4.4 Enumerated | M | P | | V | Y | + Called-Station-Id 30 4.5 UTF8String | M | P | | V | Y | + Calling-Station- 31 4.6 UTF8String | M | P | | V | Y | + Id | | | | | | + Connect-Info 77 4.7 UTF8String | M | P | | V | Y | + Originating-Line- 94 4.8 OctetString| | M,P | | V | Y | + Info | | | | | | + Reply-Message 18 4.9 UTF8String | M | P | | V | Y | + -----------------------------------------|----+-----+----+-----|----| + + + + + + + + +Calhoun, et al. Standards Track [Page 21] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +4.2. NAS-Port AVP + + The NAS-Port AVP (AVP Code 5) is of type Unsigned32 and contains the + physical or virtual port number of the NAS which is authenticating + the user. Note that "port" is meant in its sense as a service + connection on the NAS, not as an IP protocol identifier. + + Either NAS-Port or NAS-Port-Id (AVP Code 87) SHOULD be present in + AA-Request (AAR) commands if the NAS differentiates among its ports. + +4.3. NAS-Port-Id AVP + + The NAS-Port-Id AVP (AVP Code 87) is of type UTF8String and consists + of ASCII text identifying the port of the NAS authenticating the + user. Note that "port" is meant in its sense as a service connection + on the NAS, not as an IP protocol identifier. + + Either NAS-Port or NAS-Port-Id SHOULD be present in AA-Request (AAR) + commands if the NAS differentiates among its ports. NAS-Port-Id is + intended for use by NASes that cannot conveniently number their + ports. + +4.4. NAS-Port-Type AVP + + The NAS-Port-Type AVP (AVP Code 61) is of type Enumerated and + contains the type of the port on which the NAS is authenticating the + user. This AVP SHOULD be present if the NAS uses the same NAS-Port + number ranges for different service types concurrently. + + The supported values are defined in [RADIUSTypes]. The following + list is informational and subject to change by the IANA. + + 0 Async + 1 Sync + 2 ISDN Sync + 3 ISDN Async V.120 + 4 ISDN Async V.110 + 5 Virtual + 6 PIAFS + 7 HDLC Clear Channel + 8 X.25 + 9 X.75 + 10 G.3 Fax + 11 SDSL - Symmetric DSL + 12 ADSL-CAP - Asymmetric DSL, Carrierless Amplitude Phase + Modulation + 13 ADSL-DMT - Asymmetric DSL, Discrete Multi-Tone + 14 IDSL - ISDN Digital Subscriber Line + + + +Calhoun, et al. Standards Track [Page 22] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + 15 Ethernet + 16 xDSL - Digital Subscriber Line of unknown type + 17 Cable + 18 Wireless - Other + 19 Wireless - IEEE 802.11 + 20 Token-Ring [RAD802.1X] + 21 FDDI [RAD802.1X] + 22 Wireless - CDMA2000 + 23 Wireless - UMTS + 24 Wireless - 1X-EV + 25 IAPP [IEEE 802.11f] + +4.5. Called-Station-Id AVP + + The Called-Station-Id AVP (AVP Code 30) is of type UTF8String and + allows the NAS to send the ASCII string describing the layer 2 + address the user contacted in the request. For dialup access, this + can be a phone number obtained by using Dialed Number Identification + (DNIS) or a similar technology. Note that this may be different from + the phone number the call comes in on. For use with IEEE 802 access, + the Called-Station-Id MAY contain a MAC address formatted as + described in [RAD802.1X]. It SHOULD only be present in + authentication and/or authorization requests. + + If the Auth-Request-Type AVP is set to authorization-only and the + User-Name AVP is absent, the Diameter Server MAY perform + authorization based on this field. This can be used by a NAS to + request whether a call should be answered based on the DNIS. + + The codification of this field's allowed usage range is outside the + scope of this specification. + +4.6. Calling-Station-Id AVP + + The Calling-Station-Id AVP (AVP Code 31) is of type UTF8String and + allows the NAS to send the ASCII string describing the layer 2 + address from which the user connected in the request. For dialup + access, this is the phone number the call came from, using Automatic + Number Identification (ANI) or a similar technology. For use with + IEEE 802 access, the Calling-Station-Id AVP MAY contain a MAC + address, formated as described in [RAD802.1X]. It SHOULD only be + present in authentication and/or authorization requests. + + If the Auth-Request-Type AVP is set to authorization-only and the + User-Name AVP is absent, the Diameter Server MAY perform + authorization based on this field. This can be used by a NAS to + request whether a call should be answered based on the layer 2 + address (ANI, MAC Address, etc.) + + + +Calhoun, et al. Standards Track [Page 23] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + The codification of this field's allowed usage range is outside the + scope of this specification. + +4.7. Connect-Info AVP + + The Connect-Info AVP (AVP Code 77) is of type UTF8String and is sent + in the AA-Request message or ACR STOP message. When sent in the + Access-Request, it indicates the nature of the user's connection. + The connection speed SHOULD be included at the beginning of the first + Connect-Info AVP in the message. If the transmit and receive + connection speeds differ, both may be included in the first AVP with + the transmit speed listed first (the speed the NAS modem transmits + at), then a slash (/), then the receive speed, and then other + optional information. + + For example: "28800 V42BIS/LAPM" or "52000/31200 V90" + + More than one Connect-Info attribute may be present in an + Accounting-Request packet to accommodate expected efforts by the ITU + to have modems report more connection information in a standard + format that might exceed 252 octets. + + If sent in the ACR STOP, this attribute may summarize statistics + relating to session quality. For example, in IEEE 802.11, the + Connect-Info attribute may contain information on the number of link + layer retransmissions. The exact format of this attribute is + implementation specific. + +4.8. Originating-Line-Info AVP + + The Originating-Line-Info AVP (AVP Code 94) is of type OctetString + and is sent by the NAS system to convey information about the origin + of the call from an SS7 system. + + The originating line information (OLI) element indicates the nature + and/or characteristics of the line from which a call originated + (e.g., pay phone, hotel, cellular). Telephone companies are starting + to offer OLI to their customers as an option over Primary Rate + Interface (PRI). Internet Service Providers (ISPs) can use OLI in + addition to Called-Station-Id and Calling-Station-Id attributes to + differentiate customer calls and to define different services. + + The Value field contains two octets (00 - 99). ANSI T1.113 and + BELLCORE 394 can be used for additional information about these + values and their use. For more information on current assignment + values, see [ANITypes]. + + + + + +Calhoun, et al. Standards Track [Page 24] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + Value Description + ------------------------------------------------------------ + 00 Plain Old Telephone Service (POTS) + 01 Multiparty Line (more than 2) + 02 ANI Failure + 03 ANI Observed + 04 ONI Observed + 05 ANI Failure Observed + 06 Station Level Rating + 07 Special Operator Handling Required + 08 InterLATA Restricted + 10 Test Call + 20 Automatic Identified Outward Dialing (AIOD) + 23 Coin or Non-Coin + 24 Toll Free Service (Non-Pay Origination) + 25 Toll Free Service (Pay Origination) + 27 Toll Free Service (Coin Control Origination) + 29 Prison/Inmate Service + 30-32 Intercept + 30 Intercept (Blank) + 31 Intercept (Trouble) + 32 Intercept (Regular) + 34 Telco Operator Handled Call + 40-49 Unrestricted Use + 52 Outward Wide Area Telecommunications Service (OUTWATS) + 60 Telecommunications Relay Service (TRS)(Unrestricted) + 61 Cellular/Wireless PCS (Type 1) + 62 Cellular/Wireless PCS (Type 2) + 63 Cellular/Wireless PCS (Roaming) + 66 TRS (Hotel) + 67 TRS (Restricted) + 70 Pay Station, No Coin Control + 93 Access for Private Virtual Network Service + +4.9. Reply-Message AVP + + The Reply-Message AVP (AVP Code 18) is of type UTF8String and + contains text that MAY be displayed to the user. When used in an + AA-Answer message with a successful Result-Code AVP, it indicates + success. When found in an AAA message with a Result-Code other than + DIAMETER_SUCCESS, the AVP contains a failure message. + + The Reply-Message AVP MAY indicate dialog text to prompt the user + before another AA-Request attempt. When used in an AA-Answer with a + Result-Code of DIAMETER_MULTI_ROUND_AUTH or in an Re-Auth-Request + message, it MAY contain a dialog text to prompt the user for a + response. + + + + +Calhoun, et al. Standards Track [Page 25] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + Multiple Reply-Messages MAY be included, and if any are displayed, + they MUST be displayed in the same order as they appear in the + Diameter message. + +5. NAS Authentication AVPs + + This section defines the AVPs necessary to carry the authentication + information in the Diameter protocol. The functionality defined here + provides a RADIUS-like AAA service over a more reliable and secure + transport, as defined in the base protocol [BASE]. + + The following table describes the AVPs; their AVP Code values, types, + and possible flag values, and whether the AVP MAY be encrypted. + + +---------------------+ + | AVP Flag rules | + |----+-----+----+-----|----+ + AVP Section | | |SHLD| MUST| | + Attribute Name Code Defined Value Type |MUST| MAY | NOT| NOT|Encr| + -----------------------------------------|----+-----+----+-----|----| + User-Password 2 5.1 OctetString| M | P | | V | Y | + Password-Retry 75 5.2 Unsigned32 | M | P | | V | Y | + Prompt 76 5.3 Enumerated | M | P | | V | Y | + CHAP-Auth 402 5.4 Grouped | M | P | | V | Y | + CHAP-Algorithm 403 5.5 Enumerated | M | P | | V | Y | + CHAP-Ident 404 5.6 OctetString| M | P | | V | Y | + CHAP-Response 405 5.7 OctetString| M | P | | V | Y | + CHAP-Challenge 60 5.8 OctetString| M | P | | V | Y | + ARAP-Password 70 5.9 OctetString| M | P | | V | Y | + ARAP-Challenge- 84 5.10 OctetString| M | P | | V | Y | + Response | | | | | | + ARAP-Security 73 5.11 Unsigned32 | M | P | | V | Y | + ARAP-Security- 74 5.12 OctetString| M | P | | V | Y | + Data | | | | | | + -----------------------------------------|----+-----+----+-----|----| + +5.1. User-Password AVP + + The User-Password AVP (AVP Code 2) is of type OctetString and + contains the password of the user to be authenticated, or the user's + input in a multi-round authentication exchange. + + The User-Password AVP contains a user password or one-time password + and therefore represents sensitive information. As required in + [BASE], Diameter messages are encrypted by using IPsec or TLS. + Unless this AVP is used for one-time passwords, the User-Password AVP + + + + + +Calhoun, et al. Standards Track [Page 26] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + SHOULD NOT be used in untrusted proxy environments without encrypting + it by using end-to-end security techniques, such as the proposed CMS + Security [DiamCMS]. + + The clear-text password (prior to encryption) MUST NOT be longer than + 128 bytes in length. + +5.2. Password-Retry AVP + + The Password-Retry AVP (AVP Code 75) is of type Unsigned32 and MAY be + included in the AA-Answer if the Result-Code indicates an + authentication failure. The value of this AVP indicates how many + authentication attempts a user is permitted before being + disconnected. This AVP is primarily intended for use when the + Framed-Protocol AVP (see section 6.10.1) is set to ARAP. + +5.3. Prompt AVP + + The Prompt AVP (AVP Code 76) is of type Enumerated and MAY be present + in the AA-Answer message. When present, it is used by the NAS to + determine whether the user's response, when entered, should be + echoed. + + The supported values are listed in [RADIUSTypes]. The following list + is informational: + + 0 No Echo + 1 Echo + +5.4. CHAP-Auth AVP + + The CHAP-Auth AVP (AVP Code 402) is of type Grouped and contains the + information necessary to authenticate a user using the PPP + Challenge-Handshake Authentication Protocol (CHAP) [PPPCHAP]. If the + CHAP-Auth AVP is found in a message, the CHAP-Challenge AVP MUST be + present as well. The optional AVPs containing the CHAP response + depend upon the value of the CHAP-Algorithm AVP. The grouped AVP has + the following ABNF grammar: + + CHAP-Auth ::= < AVP Header: 402 > + { CHAP-Algorithm } + { CHAP-Ident } + [ CHAP-Response ] + * [ AVP ] + + + + + + + +Calhoun, et al. Standards Track [Page 27] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +5.5. CHAP-Algorithm AVP + + The CHAP-Algorithm AVP (AVP Code 403) is of type Enumerated and + contains the algorithm identifier used in the computation of the CHAP + response [PPPCHAP]. The following values are currently supported: + + CHAP with MD5 5 + The CHAP response is computed by using the procedure described + in [PPPCHAP]. This algorithm requires that the CHAP-Response + AVP MUST be present in the CHAP-Auth AVP. + +5.6. CHAP-Ident AVP + + The CHAP-Ident AVP (AVP Code 404) is of type OctetString and contains + the 1 octet CHAP Identifier used in the computation of the CHAP + response [PPPCHAP]. + +5.7. CHAP-Response AVP + + The CHAP-Response AVP (AVP Code 405) is of type OctetString and + contains the 16 octet authentication data provided by the user in + response to the CHAP challenge [PPPCHAP]. + +5.8. CHAP-Challenge AVP + + The CHAP-Challenge AVP (AVP Code 60) is of type OctetString and + contains the CHAP Challenge sent by the NAS to the CHAP peer + [PPPCHAP]. + +5.9. ARAP-Password AVP + + The ARAP-Password AVP (AVP Code 70) is of type OctetString and is + only present when the Framed-Protocol AVP (see section 6.10.1) is + included in the message and is set to ARAP. This AVP MUST NOT be + present if either the User-Password or the CHAP-Auth AVP is present. + See [RADIUSExt] for more information on the contents of this AVP. + +5.10. ARAP-Challenge-Response AVP + + The ARAP-Challenge-Response AVP (AVP Code 84) is of type OctetString + and is only present when the Framed-Protocol AVP (see section 6.10.1) + is included in the message and is set to ARAP. This AVP contains an + 8 octet response to the dial-in client's challenge. The RADIUS + server calculates this value by taking the dial-in client's challenge + from the high-order 8 octets of the ARAP-Password AVP and performing + DES encryption on this value with the authenticating user's password + + + + + +Calhoun, et al. Standards Track [Page 28] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + as the key. If the user's password is fewer than 8 octets in length, + the password is padded at the end with NULL octets to a length of 8 + before it is used as a key. + +5.11. ARAP-Security AVP + + The ARAP-Security AVP (AVP Code 73) is of type Unsigned32 and MAY be + present in the AA-Answer message if the Framed-Protocol AVP (see + section 6.10.1) is set to the value of ARAP, and the Result-Code AVP + is set to DIAMETER_MULTI_ROUND_AUTH. See [RADIUSExt] for more + information on the format of this AVP. + +5.12. ARAP-Security-Data AVP + + The ARAP-Security AVP (AVP Code 74) is of type OctetString and MAY be + present in the AA-Request or AA-Answer message if the Framed-Protocol + AVP is set to the value of ARAP, and the Result-Code AVP is set to + DIAMETER_MULTI_ROUND_AUTH. This AVP contains the security module + challenge or response associated with the ARAP Security Module + specified in ARAP-Security. + +6. NAS Authorization AVPs + + This section contains the authorization AVPs supported in the NAS + Application. The Service-Type AVP SHOULD be present in all messages, + and, based on its value, additional AVPs defined in this section and + in section 7 MAY be present. + + Due to space constraints, the short-form IPFltrRule is used to + represent IPFilterRule, and QoSFltrRule is used for QoSFilterRule. + + +---------------------+ + | AVP Flag rules | + |----+-----+----+-----|----+ + AVP Section | | |SHLD| MUST| | + Attribute Name Code Defined Value Type |MUST| MAY | NOT| NOT|Encr| + -----------------------------------------|----+-----+----+-----|----| + Service-Type 6 6.1 Enumerated | M | P | | V | Y | + Callback-Number 19 6.2 UTF8String | M | P | | V | Y | + Callback-Id 20 6.3 UTF8String | M | P | | V | Y | + Idle-Timeout 28 6.4 Unsigned32 | M | P | | V | Y | + Port-Limit 62 6.5 Unsigned32 | M | P | | V | Y | + NAS-Filter-Rule 400 6.6 IPFltrRule | M | P | | V | Y | + Filter-Id 11 6.7 UTF8String | M | P | | V | Y | + Configuration- 78 6.8 OctetString| M | | | P,V | | + Token | | | | | | + QoS-Filter-Rule 407 6.9 QoSFltrRule| | | | | | + Framed-Protocol 7 6.10.1 Enumerated | M | P | | V | Y | + + + +Calhoun, et al. Standards Track [Page 29] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + Framed-Routing 10 6.10.2 Enumerated | M | P | | V | Y | + Framed-MTU 12 6.10.3 Unsigned32 | M | P | | V | Y | + Framed- 13 6.10.4 Enumerated | M | P | | V | Y | + Compression | | | | | | + Framed-IP-Address 8 6.11.1 OctetString| M | P | | V | Y | + Framed-IP-Netmask 9 6.11.2 OctetString| M | P | | V | Y | + Framed-Route 22 6.11.3 UTF8String | M | P | | V | Y | + Framed-Pool 88 6.11.4 OctetString| M | P | | V | Y | + Framed- 96 6.11.5 Unsigned64 | M | P | | V | Y | + Interface-Id | | | | | | + Framed-IPv6- 97 6.11.6 OctetString| M | P | | V | Y | + Prefix | | | | | | + Framed-IPv6- 99 6.11.7 UTF8String | M | P | | V | Y | + Route | | | | | | + Framed-IPv6-Pool 100 6.11.8 OctetString| M | P | | V | Y | + Framed-IPX- 23 6.12.1 UTF8String | M | P | | V | Y | + Network | | | | | | + Framed-Appletalk- 37 6.13.1 Unsigned32 | M | P | | V | Y | + Link | | | | | | + Framed-Appletalk- 38 6.13.2 Unsigned32 | M | P | | V | Y | + Network | | | | | | + Framed-Appletalk- 39 6.13.3 OctetString| M | P | | V | Y | + Zone | | | | | | + ARAP-Features 71 6.14.1 OctetString| M | P | | V | Y | + ARAP-Zone-Access 72 6.14.2 Enumerated | M | P | | V | Y | + Login-IP-Host 14 6.15.1 OctetString| M | P | | V | Y | + Login-IPv6-Host 98 6.15.2 OctetString| M | P | | V | Y | + Login-Service 15 6.15.3 Enumerated | M | P | | V | Y | + Login-TCP-Port 16 6.16.1 Unsigned32 | M | P | | V | Y | + Login-LAT-Service 34 6.17.1 OctetString| M | P | | V | Y | + Login-LAT-Node 35 6.17.2 OctetString| M | P | | V | Y | + Login-LAT-Group 36 6.17.3 OctetString| M | P | | V | Y | + Login-LAT-Port 63 6.17.4 OctetString| M | P | | V | Y | + -----------------------------------------|----+-----+----+-----|----| + +6.1. Service-Type AVP + + The Service-Type AVP (AVP Code 6) is of type Enumerated and contains + the type of service the user has requested or the type of service to + be provided. One such AVP MAY be present in an authentication and/or + authorization request or response. A NAS is not required to + implement all of these service types. It MUST treat unknown or + unsupported Service-Types received in a response as a failure and end + the session with a DIAMETER_INVALID_AVP_VALUE Result-Code. + + When used in a request, the Service-Type AVP SHOULD be considered a + hint to the server that the NAS believes the user would prefer the + kind of service indicated. The server is not required to honor the + + + +Calhoun, et al. Standards Track [Page 30] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + hint. Furthermore, if the service specified by the server is + supported, but not compatible with the current mode of access, the + NAS MUST fail to start the session. The NAS MUST also generate the + appropriate error message(s). + + The following values have been defined for the Service-Type AVP. The + complete list of defined values can be found in [RADIUS] and + [RADIUSTypes]. The following list is informational: + + 1 Login + 2 Framed + 3 Callback Login + 4 Callback Framed + 5 Outbound + 6 Administrative + 7 NAS Prompt + 8 Authenticate Only + 9 Callback NAS Prompt + 10 Call Check + 11 Callback Administrative + 12 Voice + 13 Fax + 14 Modem Relay + 15 IAPP-Register [IEEE 802.11f] + 16 IAPP-AP-Check [IEEE 802.11f] + 17 Authorize Only [RADDynAuth] + + The following values are further qualified: + + Login 1 + The user should be connected to a host. The message MAY + include additional AVPs defined in sections 6.16 or 6.17. + + Framed 2 + A Framed Protocol, such as PPP or SLIP, should be started for + the User. The message MAY include additional AVPs defined in + section 6.10, or section 7 for tunneling services. + + Callback Login 3 + The user should be disconnected and called back, then connected + to a host. The message MAY include additional AVPs defined in + this section. + + Callback Framed 4 + The user should be disconnected and called back, and then a + Framed Protocol, such as PPP or SLIP, should be started for the + User. The message MAY include additional AVPs defined in + section 6.10, or in section 7 for tunneling services. + + + +Calhoun, et al. Standards Track [Page 31] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +6.2. Callback-Number AVP + + The Callback-Number AVP (AVP Code 19) is of type UTF8String and + contains a dialing string to be used for callback. It MAY be used in + an authentication and/or authorization request as a hint to the + server that a Callback service is desired, but the server is not + required to honor the hint in the corresponding response. + + The codification of this field's allowed usage range is outside the + scope of this specification. + +6.3. Callback-Id AVP + + The Callback-Id AVP (AVP Code 20) is of type UTF8String and contains + the name of a place to be called, to be interpreted by the NAS. This + AVP MAY be present in an authentication and/or authorization + response. + + This AVP is not roaming-friendly as it assumes that the Callback-Id + is configured on the NAS. Using the Callback-Number AVP therefore + preferable. + +6.4. Idle-Timeout AVP + + The Idle-Timeout AVP (AVP Code 28) is of type Unsigned32 and sets the + maximum number of consecutive seconds of idle connection allowable to + the user before termination of the session or before a prompt is + issued. The default is none, or system specific. + +6.5. Port-Limit AVP + + The Port-Limit AVP (AVP Code 62) is of type Unsigned32 and sets the + maximum number of ports the NAS provides to the user. It MAY be used + in an authentication and/or authorization request as a hint to the + server that multilink PPP [PPPMP] service is desired, but the server + is not required to honor the hint in the corresponding response. + +6.6. NAS-Filter-Rule AVP + + The NAS-Filter-Rule AVP (AVP Code 400) is of type IPFilterRule and + provides filter rules that need to be configured on the NAS for the + user. One or more of these AVPs MAY be present in an authorization + response. + + + + + + + + +Calhoun, et al. Standards Track [Page 32] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +6.7. Filter-Id AVP + + The Filter-Id AVP (AVP Code 11) is of type UTF8String and contains + the name of the filter list for this user. Zero or more Filter-Id + AVPs MAY be sent in an authorization answer. + + Identifying a filter list by name allows the filter to be used on + different NASes without regard to filter-list implementation details. + However, this AVP is not roaming friendly, as filter naming differs + from one service provider to another. + + In non-RADIUS environments, it is RECOMMENDED that the NAS-Filter- + Rule AVP be used instead. + +6.8. Configuration-Token AVP + + The Configuration-Token AVP (AVP Code 78) is of type OctetString and + is sent by a Diameter Server to a Diameter Proxy Agent or Translation + Agent in an AA-Answer command to indicate a type of user profile to + be used. It should not be sent to a Diameter Client (NAS). + + The format of the Data field of this AVP is site specific. + +6.9. QoS-Filter-Rule AVP + + The QoS-Filter-Rule AVP (AVP Code 407) is of type QoSFilterRule and + provides QoS filter rules that need to be configured on the NAS for + the user. One or more such AVPs MAY be present in an authorization + response. + + Note: Due to an editorial mistake in [BASE], only the AVP format is + discussed. The complete QoSFilterRule definition was not included. + It is reprinted here for clarification. + + QoSFilterRule + + The QosFilterRule format is derived from the OctetString AVP Base + Format. It uses the ASCII charset. Packets may be marked or + metered based on the following information: + + Direction (in or out) + Source and destination IP address (possibly masked) + Protocol + Source and destination port (lists or ranges) + DSCP values (no mask or range) + + Rules for the appropriate direction are evaluated in order; the + first matched rule terminates the evaluation. Each packet is + + + +Calhoun, et al. Standards Track [Page 33] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + evaluated once. If no rule matches, the packet is treated as best + effort. An access device unable to interpret or apply a QoS rule + SHOULD NOT terminate the session. + + QoSFilterRule filters MUST follow the following format: + + action dir proto from src to dst [options] + + tag - Mark packet with a specific DSCP + [DIFFSERV]. The DSCP option MUST be + included. + meter - Meter traffic. The metering options + MUST be included. + + dir The format is as described under IPFilterRule. + + proto The format is as described under IPFilterRule. + + src and dst The format is as described under IPFilterRule. + + options: + + DSCP <color> + Color values as defined in [DIFFSERV]. Exact + matching of DSCP values is required (no masks or + ranges). + + metering <rate> <color_under> <color_over> + The metering option provides Assured Forwarding, + as defined in [DIFFSERVAF], and MUST be present + if the action is set to meter. The rate option is + the throughput, in bits per second, used + by the access device to mark packets. Traffic + over the rate is marked with the color_over + codepoint, and traffic under the rate is marked + with the color_under codepoint. The color_under + and color_over options contain the drop + preferences and MUST conform to the recommended + codepoint keywords described in [DIFFSERVAF] + (e.g., AF13). + + The metering option also supports the strict + limit on traffic required by Expedited + Forwarding, as defined in [DIFFSERVEF]. The + color_over option may contain the keyword "drop" + to prevent forwarding of traffic that exceeds the + rate parameter. + + + + +Calhoun, et al. Standards Track [Page 34] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + The rule syntax is a modified subset of ipfw(8) from FreeBSD, + and the ipfw.c code may provide a useful base for + implementations. + +6.10. Framed Access Authorization AVPs + + This section lists the authorization AVPs necessary to + support framed access, such as PPP and SLIP. AVPs defined in this + section MAY be present in a message if the Service-Type AVP was set + to "Framed" or "Callback Framed". + +6.10.1. Framed-Protocol AVP + + The Framed-Protocol AVP (AVP Code 7) is of type Enumerated and + contains the framing to be used for framed access. This AVP MAY be + present in both requests and responses. The supported values are + listed in [RADIUSTypes]. The following list is informational: + + 1 PPP + 2 SLIP + 3 AppleTalk Remote Access Protocol (ARAP) + 4 Gandalf proprietary SingleLink/MultiLink protocol + 5 Xylogics proprietary IPX/SLIP + 6 X.75 Synchronous + +6.10.2. Framed-Routing AVP + + The Framed-Routing AVP (AVP Code 10) is of type Enumerated and + contains the routing method for the user when the user is a router to + a network. This AVP SHOULD only be present in authorization + responses. The supported values are listed in [RADIUSTypes]. The + following list is informational: + + 0 None + 1 Send routing packets + 2 Listen for routing packets + 3 Send and Listen + +6.10.3. Framed-MTU AVP + + The Framed-MTU AVP (AVP Code 12) is of type Unsigned32 and contains + the Maximum Transmission Unit to be configured for the user, when it + is not negotiated by some other means (such as PPP). This AVP SHOULD + only be present in authorization responses. The MTU value MUST be in + the range from 64 to 65535. + + + + + + +Calhoun, et al. Standards Track [Page 35] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +6.10.4. Framed-Compression AVP + + The Framed-Compression AVP (AVP Code 13) is of type Enumerated and + contains the compression protocol to be used for the link. It MAY be + used in an authorization request as a hint to the server that a + specific compression type is desired, but the server is not required + to honor the hint in the corresponding response. + + More than one compression protocol AVP MAY be sent. The NAS is + responsible for applying the proper compression protocol to the + appropriate link traffic. + + The supported values are listed in [RADIUSTypes]. The following list + is informational: + + 0 None + 1 VJ TCP/IP header compression + 2 IPX header compression + 3 Stac-LZS compression + +6.11. IP Access Authorization AVPs + + The AVPs defined in this section are used when the user requests, or + is being granted, access service to IP. + +6.11.1. Framed-IP-Address AVP + + The Framed-IP-Address AVP (AVP Code 8) [RADIUS] is of type + OctetString and contains an IPv4 address of the type specified in the + attribute value to be configured for the user. It MAY be used in an + authorization request as a hint to the server that a specific address + is desired, but the server is not required to honor the hint in the + corresponding response. + + Two values have special significance: 0xFFFFFFFF and 0xFFFFFFFE. The + value 0xFFFFFFFF indicates that the NAS should allow the user to + select an address (i.e., negotiated). The value 0xFFFFFFFE indicates + that the NAS should select an address for the user (e.g., assigned + from a pool of addresses kept by the NAS). + +6.11.2. Framed-IP-Netmask AVP + + The Framed-IP-Netmask AVP (AVP Code 9) is of type OctetString and + contains the four octets of the IPv4 netmask to be configured for the + user when the user is a router to a network. It MAY be used in an + authorization request as a hint to the server that a specific netmask + + + + + +Calhoun, et al. Standards Track [Page 36] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + is desired, but the server is not required to honor the hint in the + corresponding response. This AVP MUST be present in a response if + the request included this AVP with a value of 0xFFFFFFFF. + +6.11.3. Framed-Route AVP + + The Framed-Route AVP (AVP Code 22) is of type UTF8String and contains + the ASCII routing information to be configured for the user on the + NAS. Zero or more of these AVPs MAY be present in an authorization + response. + + The string MUST contain a destination prefix in dotted quad form + optionally followed by a slash and a decimal length specifier stating + how many high-order bits of the prefix should be used. This is + followed by a space, a gateway address in dotted quad form, a space, + and one or more metrics separated by spaces; for example, + + "192.168.1.0/24 192.168.1.1 1". + + The length specifier may be omitted, in which case it should default + to 8 bits for class A prefixes, to 16 bits for class B prefixes, and + to 24 bits for class C prefixes; for example, + + "192.168.1.0 192.168.1.1 1". + + Whenever the gateway address is specified as "0.0.0.0" the IP address + of the user SHOULD be used as the gateway address. + +6.11.4. Framed-Pool AVP + + The Framed-Pool AVP (AVP Code 88) is of type OctetString and contains + the name of an assigned address pool that SHOULD be used to assign an + address for the user. If a NAS does not support multiple address + pools, the NAS SHOULD ignore this AVP. Address pools are usually + used for IP addresses but can be used for other protocols if the NAS + supports pools for those protocols. + + Although specified as type OctetString for compatibility with RADIUS + [RADIUSExt], the encoding of the Data field SHOULD also conform to + the rules for the UTF8String Data Format. + +6.11.5. Framed-Interface-Id AVP + + The Framed-Interface-Id AVP (AVP Code 96) is of type Unsigned64 and + contains the IPv6 interface identifier to be configured for the user. + It MAY be used in authorization requests as a hint to the server that + a specific interface id is desired, but the server is not required to + honor the hint in the corresponding response. + + + +Calhoun, et al. Standards Track [Page 37] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +6.11.6. Framed-IPv6-Prefix AVP + + The Framed-IPv6-Prefix AVP (AVP Code 97) is of type OctetString and + contains the IPv6 prefix to be configured for the user. One or more + AVPs MAY be used in authorization requests as a hint to the server + that specific IPv6 prefixes are desired, but the server is not + required to honor the hint in the corresponding response. + +6.11.7. Framed-IPv6-Route AVP + + The Framed-IPv6-Route AVP (AVP Code 99) is of type UTF8String and + contains the ASCII routing information to be configured for the user + on the NAS. Zero or more of these AVPs MAY be present in an + authorization response. + + The string MUST contain an IPv6 address prefix followed by a slash + and a decimal length specifier stating how many high order bits of + the prefix should be used. This is followed by a space, a gateway + address in hexadecimal notation, a space, and one or more metrics + separated by spaces; for example, + + "2000:0:0:106::/64 2000::106:a00:20ff:fe99:a998 1". + + Whenever the gateway address is the IPv6 unspecified address, the IP + address of the user SHOULD be used as the gateway address, such as + in: + + "2000:0:0:106::/64 :: 1". + +6.11.8. Framed-IPv6-Pool AVP + + The Framed-IPv6-Pool AVP (AVP Code 100) is of type OctetString and + contains the name of an assigned pool that SHOULD be used to assign + an IPv6 prefix for the user. If the access device does not support + multiple prefix pools, it MUST ignore this AVP. + + Although specified as type OctetString for compatibility with RADIUS + [RADIUSIPv6], the encoding of the Data field SHOULD also conform to + the rules for the UTF8String Data Format. + +6.12. IPX Access + + The AVPs defined in this section are used when the user requests, or + is being granted, access to an IPX network service. + + + + + + + +Calhoun, et al. Standards Track [Page 38] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +6.12.1. Framed-IPX-Network AVP + + The Framed-IPX-Network AVP (AVP Code 23) is of type Unsigned32 and + contains the IPX Network number to be configured for the user. It + MAY be used in an authorization request as a hint to the server that + a specific address is desired, but the server is not required to + honor the hint in the corresponding response. + + Two addresses have special significance: 0xFFFFFFFF and 0xFFFFFFFE. + The value 0xFFFFFFFF indicates that the NAS should allow the user to + select an address (i.e., Negotiated). The value 0xFFFFFFFE indicates + that the NAS should select an address for the user (e.g., assign it + from a pool of one or more IPX networks kept by the NAS). + +6.13. AppleTalk Network Access + + The AVPs defined in this section are used when the user requests, or + is being granted, access to an AppleTalk network [AppleTalk]. + +6.13.1. Framed-AppleTalk-Link AVP + + The Framed-AppleTalk-Link AVP (AVP Code 37) is of type Unsigned32 and + contains the AppleTalk network number that should be used for the + serial link to the user, which is another AppleTalk router. This AVP + MUST only be present in an authorization response and is never used + when the user is not another router. + + Despite the size of the field, values range from 0 to 65,535. The + special value of 0 indicates an unnumbered serial link. A value of 1 + to 65,535 means that the serial line between the NAS and the user + should be assigned that value as an AppleTalk network number. + +6.13.2. Framed-AppleTalk-Network AVP + + The Framed-AppleTalk-Network AVP (AVP Code 38) is of type Unsigned32 + and contains the AppleTalk Network number that the NAS should probe + to allocate an AppleTalk node for the user. This AVP MUST only be + present in an authorization response and is never used when the user + is not another router. Multiple instances of this AVP indicate that + the NAS may probe, using any of the network numbers specified. + + Despite the size of the field, values range from 0 to 65,535. The + special value 0 indicates that the NAS should assign a network for + the user, using its default cable range. A value between 1 and + 65,535 (inclusive) indicates to the AppleTalk Network that the NAS + should probe to find an address for the user. + + + + + +Calhoun, et al. Standards Track [Page 39] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +6.13.3. Framed-AppleTalk-Zone AVP + + The Framed-AppleTalk-Zone AVP (AVP Code 39) is of type OctetString + and contains the AppleTalk Default Zone to be used for this user. + This AVP MUST only be present in an authorization response. Multiple + instances of this AVP in the same message are not allowed. + + The codification of this field's allowed range is outside the scope + of this specification. + +6.14. AppleTalk Remote Access + + The AVPs defined in this section are used when the user requests, or + is being granted, access to the AppleTalk network via the AppleTalk + Remote Access Protocol [ARAP]. They are only present if the Framed- + Protocol AVP (see section 6.10.1) is set to ARAP. Section 2.2 of RFC + 2869 [RADIUSExt] describes the operational use of these attributes. + +6.14.1. ARAP-Features AVP + + The ARAP-Features AVP (AVP Code 71) is of type OctetString and MAY be + present in the AA-Accept message if the Framed-Protocol AVP is set to + the value of ARAP. See [RADIUSExt] for more information about the + format of this AVP. + +6.14.2. ARAP-Zone-Access AVP + + The ARAP-Zone-Access AVP (AVP Code 72) is of type Enumerated and MAY + be present in the AA-Accept message if the Framed-Protocol AVP is set + to the value of ARAP. + + The supported values are listed in [RADIUSTypes] and defined in + [RADIUSExt]. + +6.15. Non-Framed Access Authorization AVPs + + This section contains the authorization AVPs that are needed to + support terminal server functionality. AVPs defined in this section + MAY be present in a message if the Service-Type AVP was set to + "Login" or "Callback Login". + +6.15.1. Login-IP-Host AVP + + The Login-IP-Host AVP (AVP Code 14) [RADIUS] is of type OctetString + and contains the IPv4 address of a host with which to connect the + user when the Login-Service AVP is included. It MAY be used in an + AA-Request command as a hint to the Diameter Server that a specific + + + + +Calhoun, et al. Standards Track [Page 40] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + host is desired, but the Diameter Server is not required to honor the + hint in the AA-Answer. + + Two addresses have special significance: all ones and 0. The value + of all ones indicates that the NAS SHOULD allow the user to select an + address. The value 0 indicates that the NAS SHOULD select a host to + connect the user to. + +6.15.2. Login-IPv6-Host AVP + + The Login-IPv6-Host AVP (AVP Code 98) [RADIUSIPv6] is of type + OctetString and contains the IPv6 address of a host with which to + connect the user when the Login-Service AVP is included. It MAY be + used in an AA-Request command as a hint to the Diameter Server that a + specific host is desired, but the Diameter Server is not required to + honor the hint in the AA-Answer. + + Two addresses have special significance: + + 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF and 0. The value + 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF indicates that the NAS SHOULD + allow the user to select an address. The value 0 indicates that the + NAS SHOULD select a host to connect the user to. + +6.15.3. Login-Service AVP + + The Login-Service AVP (AVP Code 15) is of type Enumerated and + contains the service that should be used to connect the user to the + login host. This AVP SHOULD only be present in authorization + responses. + + The supported values are listed in [RADIUSTypes]. The following list + is informational: + + 0 Telnet + 1 Rlogin + 2 TCP Clear + 3 PortMaster (proprietary) + 4 LAT + 5 X25-PAD + 6 X25-T3POS + 8 TCP Clear Quiet (suppresses any NAS-generated connect + string) + + + + + + + + +Calhoun, et al. Standards Track [Page 41] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +6.16. TCP Services + + The AVPs described in this section MAY be present if the Login- + Service AVP is set to Telnet, Rlogin, TCP Clear, or TCP Clear Quiet. + +6.16.1. Login-TCP-Port AVP + + The Login-TCP-Port AVP (AVP Code 16) is of type Unsigned32 and + contains the TCP port with which the user is to be connected when the + Login-Service AVP is also present. This AVP SHOULD only be present + in authorization responses. The value MUST NOT be greater than + 65,535. + +6.17. LAT Services + + The AVPs described in this section MAY be present if the Login- + Service AVP is set to LAT [LAT]. + +6.17.1. Login-LAT-Service AVP + + The Login-LAT-Service AVP (AVP Code 34) is of type OctetString and + contains the system with which the user is to be connected by LAT. + It MAY be used in an authorization request as a hint to the server + that a specific service is desired, but the server is not required to + honor the hint in the corresponding response. This AVP MUST only be + present in the response if the Login-Service AVP states that LAT is + desired. + + Administrators use this service attribute when dealing with clustered + systems, such as a VAX or Alpha cluster. In these environments, + several different time-sharing hosts share the same resources (disks, + printers, etc.), and administrators often configure each host to + offer access (service) to each of the shared resources. In this + case, each host in the cluster advertises its services through LAT + broadcasts. + + Sophisticated users often know which service providers (machines) are + faster and tend to use a node name when initiating a LAT connection. + Some administrators want particular users to use certain machines as + a primitive form of load balancing (although LAT knows how to do load + balancing itself). + + The String field contains the identity of the LAT service to use. + The LAT Architecture allows this string to contain $ (dollar), - + (hyphen), . (period), _ (underscore), numerics, upper- and lowercase + alphabetics, and the ISO Latin-1 character set extension [ISOLatin]. + All LAT string comparisons are case insensitive. + + + + +Calhoun, et al. Standards Track [Page 42] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +6.17.2. Login-LAT-Node AVP + + The Login-LAT-Node AVP (AVP Code 35) is of type OctetString and + contains the Node with which the user is to be automatically + connected by LAT. It MAY be used in an authorization request as a + hint to the server that a specific LAT node is desired, but the + server is not required to honor the hint in the corresponding + response. This AVP MUST only be present in a response if the Login- + Service-Type AVP is set to LAT. + + The String field contains the identity of the LAT service to use. + The LAT Architecture allows this string to contain $ (dollar), - + (hyphen), . (period), _ (underscore), numerics, upper- and lowercase + alphabetics, and the ISO Latin-1 character set extension [ISOLatin]. + All LAT string comparisons are case insensitive. + +6.17.3. Login-LAT-Group AVP + + The Login-LAT-Group AVP (AVP Code 36) is of type OctetString and + contains a string identifying the LAT group codes this user is + authorized to use. It MAY be used in an authorization request as a + hint to the server that a specific group is desired, but the server + is not required to honor the hint in the corresponding response. + This AVP MUST only be present in a response if the Login-Service-Type + AVP is set to LAT. + + LAT supports 256 different group codes, which LAT uses as a form of + access rights. LAT encodes the group codes as a 256-bit bitmap. + + Administrators can assign one or more of the group code bits at the + LAT service provider; it will only accept LAT connections that have + these group codes set in the bitmap. The administrators assign a + bitmap of authorized group codes to each user. LAT gets these from + the operating system and uses them in its requests to the service + providers. + + The codification of the range of allowed usage of this field is + outside the scope of this specification. + +6.17.4. Login-LAT-Port AVP + + The Login-LAT-Port AVP (AVP Code 63) is of type OctetString and + contains the Port with which the user is to be connected by LAT. It + MAY be used in an authorization request as a hint to the server that + a specific port is desired, but the server is not required to honor + the hint in the corresponding response. This AVP MUST only be + present in a response if the Login-Service-Type AVP is set to LAT. + + + + +Calhoun, et al. Standards Track [Page 43] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + The String field contains the identity of the LAT service to use. + The LAT Architecture allows this string to contain $ (dollar), - + (hyphen), . (period), _ (underscore), numerics, upper- and lower-case + alphabetics, and the ISO Latin-1 character set extension [ISOLatin]. + All LAT string comparisons are case insensitive. + +7. NAS Tunneling + + Some NASes support compulsory tunnel services in which the incoming + connection data is conveyed by an encapsulation method to a gateway + elsewhere in the network. This is typically transparent to the + service user, and the tunnel characteristics may be described by the + remote AAA server, based on the user's authorization information. + Several tunnel characteristics may be returned, and the NAS + implementation may choose one [RADTunnels], [RADTunlAcct]. + + +---------------------+ + | AVP Flag rules | + |----+-----+----+-----|----+ + AVP Section | | |SHLD| MUST| | + Attribute Name Code Defined Value Type |MUST| MAY | NOT| NOT |Encr| + -----------------------------------------|----+-----+----+-----|----| + Tunneling 401 7.1 Grouped | M | P | | V | N | + Tunnel-Type 64 7.2 Enumerated | M | P | | V | Y | + Tunnel-Medium- 65 7.3 Enumerated | M | P | | V | Y | + Type | | | | | | + Tunnel-Client- 66 7.4 UTF8String | M | P | | V | Y | + Endpoint | | | | | | + Tunnel-Server- 67 7.5 UTF8String | M | P | | V | Y | + Endpoint | | | | | | + Tunnel-Password 69 7.6 OctetString| M | P | | V | Y | + Tunnel-Private- 81 7.7 OctetString| M | P | | V | Y | + Group-Id | | | | | | + Tunnel- 82 7.8 OctetString| M | P | | V | Y | + Assignment-Id | | | | | | + Tunnel-Preference 83 7.9 Unsigned32 | M | P | | V | Y | + Tunnel-Client- 90 7.10 UTF8String | M | P | | V | Y | + Auth-Id | | | | | | + Tunnel-Server- 91 7.11 UTF8String | M | P | | V | Y | + Auth-Id | | | | | | + -----------------------------------------|----+-----+----+-----|----| + +7.1. Tunneling AVP + + The Tunneling AVP (AVP Code 401) is of type Grouped and contains the + following AVPs, used to describe a compulsory tunnel service: + [RADTunnels], [RADTunlAcct]. Its data field has the following ABNF + grammar: + + + +Calhoun, et al. Standards Track [Page 44] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + Tunneling ::= < AVP Header: 401 > + { Tunnel-Type } + { Tunnel-Medium-Type } + { Tunnel-Client-Endpoint } + { Tunnel-Server-Endpoint } + [ Tunnel-Preference ] + [ Tunnel-Client-Auth-Id ] + [ Tunnel-Server-Auth-Id ] + [ Tunnel-Assignment-Id ] + [ Tunnel-Password ] + [ Tunnel-Private-Group-Id ] + +7.2. Tunnel-Type AVP + + The Tunnel-Type AVP (AVP Code 64) is of type Enumerated and contains + the tunneling protocol(s) to be used (in the case of a tunnel + initiator) or in use (in the case of a tunnel terminator). It MAY be + used in an authorization request as a hint to the server that a + specific tunnel type is desired, but the server is not required to + honor the hint in the corresponding response. + + The Tunnel-Type AVP SHOULD also be included in Accounting-Request + messages. + + A tunnel initiator is not required to implement any of these tunnel + types. If a tunnel initiator receives a response that contains only + unknown or unsupported Tunnel-Types, the tunnel initiator MUST behave + as though a response were received with the Result-Code indicating a + failure. + + The supported values are listed in [RADIUSTypes]. The following list + is informational: + + 1 Point-to-Point Tunneling Protocol (PPTP) + 2 Layer Two Forwarding (L2F) + 3 Layer Two Tunneling Protocol (L2TP) + 4 Ascend Tunnel Management Protocol (ATMP) + 5 Virtual Tunneling Protocol (VTP) + 6 IP Authentication Header in the Tunnel-mode (AH) + 7 IP-in-IP Encapsulation (IP-IP) + 8 Minimal IP-in-IP Encapsulation (MIN-IP-IP) + 9 IP Encapsulating Security Payload in the Tunnel-mode (ESP) + 10 Generic Route Encapsulation (GRE) + 11 Bay Dial Virtual Services (DVS) + 12 IP-in-IP Tunneling + 13 Virtual LANs (VLAN) + + + + + +Calhoun, et al. Standards Track [Page 45] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +7.3. Tunnel-Medium-Type AVP + + The Tunnel-Medium-Type AVP (AVP Code 65) is of type Enumerated and + contains the transport medium to use when creating a tunnel for + protocols (such as L2TP) that can operate over multiple transports. + It MAY be used in an authorization request as a hint to the server + that a specific medium is desired, but the server is not required to + honor the hint in the corresponding response. + + The supported values are listed in [RADIUSTypes]. The following list + is informational: + + 1 IPv4 (IP version 4) + 2 IPv6 (IP version 6) + 3 NSAP + 4 HDLC (8-bit multidrop) + 5 BBN 1822 + 6 802 (includes all 802 media plus Ethernet "canonical + format") + 7 E.163 (POTS) + 8 E.164 (SMDS, Frame Relay, ATM) + 9 F.69 (Telex) + 10 X.121 (X.25, Frame Relay) + 11 IPX + 12 Appletalk + 13 Decnet IV + 14 Banyan Vines + 15 E.164 with NSAP format subaddress + +7.4. Tunnel-Client-Endpoint AVP + + The Tunnel-Client-Endpoint AVP (AVP Code 66) is of type UTF8String + and contains the address of the initiator end of the tunnel. It MAY + be used in an authorization request as a hint to the server that a + specific endpoint is desired, but the server is not required to honor + the hint in the corresponding response. + + This AVP SHOULD be included in the corresponding Accounting-Request + messages, in which case it indicates the address from which the + tunnel was initiated. This AVP, along with the Tunnel-Server- + Endpoint and Session-Id AVP [BASE], MAY be used to provide a globally + unique means to identify a tunnel for accounting and auditing + purposes. + + If Tunnel-Medium-Type is IPv4 (1), then this string is either the + fully qualified domain name (FQDN) of the tunnel client machine, or a + + + + + +Calhoun, et al. Standards Track [Page 46] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + "dotted-decimal" IP address. Implementations MUST support the + dotted-decimal format and SHOULD support the FQDN format for IP + addresses. + + If Tunnel-Medium-Type is IPv6 (2), then this string is either the + FQDN of the tunnel client machine, or a text representation of the + address in either the preferred or alternate form [IPv6Addr]. + Conforming implementations MUST support the preferred form and SHOULD + support both the alternate text form and the FQDN format for IPv6 + addresses. + + If Tunnel-Medium-Type is neither IPv4 nor IPv6, then this string is a + tag referring to configuration data local to the Diameter client that + describes the interface or medium-specific client address to use. + +7.5. Tunnel-Server-Endpoint AVP + + The Tunnel-Server-Endpoint AVP (AVP Code 67) is of type UTF8String + and contains the address of the server end of the tunnel. It MAY be + used in an authorization request as a hint to the server that a + specific endpoint is desired, but the server is not required to honor + the hint in the corresponding response. + + This AVP SHOULD be included in the corresponding Accounting-Request + messages, in which case it indicates the address from which the + tunnel was initiated. This AVP, along with the Tunnel-Client- + Endpoint and Session-Id AVP [BASE], MAY be used to provide a globally + unique means to identify a tunnel for accounting and auditing + purposes. + + If Tunnel-Medium-Type is IPv4 (1), then this string is either the + fully qualified domain name (FQDN) of the tunnel server machine, or a + "dotted-decimal" IP address. Implementations MUST support the + dotted-decimal format and SHOULD support the FQDN format for IP + addresses. + + If Tunnel-Medium-Type is IPv6 (2), then this string is either the + FQDN of the tunnel server machine, or a text representation of the + address in either the preferred or alternate form [IPv6Addr]. + Implementations MUST support the preferred form and SHOULD support + both the alternate text form and the FQDN format for IPv6 addresses. + + If Tunnel-Medium-Type is not IPv4 or IPv6, this string is a tag + referring to configuration data local to the Diameter client that + describes the interface or medium-specific server address to use. + + + + + + +Calhoun, et al. Standards Track [Page 47] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +7.6. Tunnel-Password AVP + + The Tunnel-Password AVP (AVP Code 69) is of type OctetString and may + contain a password to be used to authenticate to a remote server. + The Tunnel-Password AVP contains sensitive information. This value + is not protected in the same manner as RADIUS [RADTunnels]. + + As required in [BASE], Diameter messages are encrypted by using IPsec + or TLS. The Tunnel-Password AVP SHOULD NOT be used in untrusted + proxy environments without encrypting it by using end-to-end security + techniques, such as CMS Security [DiamCMS]. + +7.7. Tunnel-Private-Group-Id AVP + + The Tunnel-Private-Group-Id AVP (AVP Code 81) is of type OctetString + and contains the group Id for a particular tunneled session. The + Tunnel-Private-Group-Id AVP MAY be included in an authorization + request if the tunnel initiator can predetermine the group resulting + from a particular connection. It SHOULD be included in the + authorization response if this tunnel session is to be treated as + belonging to a particular private group. Private groups may be used + to associate a tunneled session with a particular group of users. + For example, it MAY be used to facilitate routing of unregistered IP + addresses through a particular interface. This AVP SHOULD be + included in the Accounting-Request messages that pertain to the + tunneled session. + +7.8. Tunnel-Assignment-Id AVP + + The Tunnel-Assignment-Id AVP (AVP Code 82) is of type OctetString and + is used to indicate to the tunnel initiator the particular tunnel to + which a session is to be assigned. Some tunneling protocols, such as + [PPTP] and [L2TP], allow for sessions between the same two tunnel + endpoints to be multiplexed over the same tunnel and also for a given + session to use its own dedicated tunnel. This attribute provides a + mechanism for Diameter to inform the tunnel initiator (e.g., PAC, + LAC) whether to assign the session to a multiplexed tunnel or to a + separate tunnel. Furthermore, it allows for sessions sharing + multiplexed tunnels to be assigned to different multiplexed tunnels. + + A particular tunneling implementation may assign differing + characteristics to particular tunnels. For example, different + tunnels may be assigned different QoS parameters. Such tunnels may + be used to carry either individual or multiple sessions. The + Tunnel-Assignment-Id attribute thus allows the Diameter server to + indicate that a particular session is to be assigned to a tunnel + providing an appropriate level of service. It is expected that any + QoS-related Diameter tunneling attributes defined in the future + + + +Calhoun, et al. Standards Track [Page 48] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + accompanying this one will be associated by the tunnel initiator with + the Id given by this attribute. In the meantime, any semantic given + to a particular Id string is a matter left to local configuration in + the tunnel initiator. + + The Tunnel-Assignment-Id AVP is of significance only to Diameter and + the tunnel initiator. The Id it specifies is only intended to be of + local use to Diameter and the tunnel initiator. The Id assigned by + the tunnel initiator is not conveyed to the tunnel peer. + + This attribute MAY be included in authorization responses. The + tunnel initiator receiving this attribute MAY choose to ignore it and + to assign the session to an arbitrary multiplexed or non-multiplexed + tunnel between the desired endpoints. This AVP SHOULD also be + included in the Accounting-Request messages pertaining to the + tunneled session. + + If a tunnel initiator supports the Tunnel-Assignment-Id AVP, then it + should assign a session to a tunnel in the following manner: + + - If this AVP is present and a tunnel exists between the + specified endpoints with the specified Id, then the session + should be assigned to that tunnel. + + - If this AVP is present and no tunnel exists between the + specified endpoints with the specified Id, then a new tunnel + should be established for the session and the specified Id + should be associated with the new tunnel. + + - If this AVP is not present, then the session is assigned to an + unnamed tunnel. If an unnamed tunnel does not yet exist + between the specified endpoints, then it is established and + used for this session and for subsequent ones established + without the Tunnel-Assignment-Id attribute. A tunnel initiator + MUST NOT assign a session for which a Tunnel-Assignment-Id AVP + was not specified to a named tunnel (i.e., one that was + initiated by a session specifying this AVP). + + Note that the same Id may be used to name different tunnels if these + tunnels are between different endpoints. + +7.9. Tunnel-Preference AVP + + The Tunnel-Preference AVP (AVP Code 83) is of type Unsigned32 and is + used to identify the relative preference assigned to each tunnel when + more than one set of tunneling AVPs is returned within separate + Grouped-AVP AVPs. It MAY be used in an authorization request as a + hint to the server that a specific preference is desired, but the + + + +Calhoun, et al. Standards Track [Page 49] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + server is not required to honor the hint in the corresponding + response. + + For example, suppose that AVPs describing two tunnels are returned by + the server, one with a Tunnel-Type of PPTP and the other with a + Tunnel-Type of L2TP. If the tunnel initiator supports only one of + the Tunnel-Types returned, it will initiate a tunnel of that type. + If, however, it supports both tunnel protocols, it SHOULD use the + value of the Tunnel-Preference AVP to decide which tunnel should be + started. The tunnel with the lowest numerical value in the Value + field of this AVP SHOULD be given the highest preference. The values + assigned to two or more instances of the Tunnel-Preference AVP within + a given authorization response MAY be identical. In this case, the + tunnel initiator SHOULD use locally configured metrics to decide + which set of AVPs to use. + +7.10. Tunnel-Client-Auth-Id AVP + + The Tunnel-Client-Auth-Id AVP (AVP Code 90) is of type UTF8String and + specifies the name used by the tunnel initiator during the + authentication phase of tunnel establishment. It MAY be used in an + authorization request as a hint to the server that a specific + preference is desired, but the server is not required to honor the + hint in the corresponding response. This AVP MUST be present in the + authorization response if an authentication name other than the + default is desired. This AVP SHOULD be included in the Accounting- + Request messages pertaining to the tunneled session. + +7.11. Tunnel-Server-Auth-Id AVP + + The Tunnel-Server-Auth-Id AVP (AVP Code 91) is of type UTF8String and + specifies the name used by the tunnel terminator during the + authentication phase of tunnel establishment. It MAY be used in an + authorization request as a hint to the server that a specific + preference is desired, but the server is not required to honor the + hint in the corresponding response. This AVP MUST be present in the + authorization response if an authentication name other than the + default is desired. This AVP SHOULD be included in the Accounting- + Request messages pertaining to the tunneled session. + +8. NAS Accounting + + Applications implementing this specification use Diameter Accounting, + as defined in [BASE], and the AVPs in the following section. + Service-specific AVP usage is defined in the tables in section 10. + + If accounting is active, Accounting Request (ACR) messages SHOULD be + sent after the completion of any Authentication or Authorization + + + +Calhoun, et al. Standards Track [Page 50] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + transaction and at the end of a Session. The Accounting-Record-Type + value indicates the type of event. All other AVPs identify the + session and provide additional information relevant to the event. + + The successful completion of the first Authentication or + Authorization transaction SHOULD cause a START_RECORD to be sent. If + additional Authentications or Authorizations occur in later + transactions, the first exchange should generate a START_RECORD, and + the later an INTERIM_RECORD. For a given session, there MUST only be + one set of matching START and STOP records, with any number of + INTERIM_RECORDS in between, or one EVENT_RECORD indicating the reason + a session wasn't started. + + The following table describes the AVPs; their AVP Code values, types, + and possible flag values; and whether the AVP MAY be encrypted. + + +---------------------+ + | AVP Flag rules | + |----+-----+----+-----|----+ + AVP Section | | |SHLD| MUST| | + Attribute Name Code Defined Value Type |MUST| MAY | NOT| NOT|Encr| + -----------------------------------------|----+-----+----+-----|----| + Accounting- 363 8.1 Unsigned64 | M | P | | V | Y | + Input-Octets | | | | | | + Accounting- 364 8.2 Unsigned64 | M | P | | V | Y | + Output-Octets | | | | | | + Accounting- 365 8.3 Unsigned64 | M | P | | V | Y | + Input-Packets | | | | | | + Accounting- 366 8.4 Unsigned64 | M | P | | V | Y | + Output-Packets | | | | | | + Acct-Session-Time 46 8.5 Unsigned32 | M | P | | V | Y | + Acct-Authentic 45 8.6 Enumerated | M | P | | V | Y | + Acounting-Auth- 406 8.7 Enumerated | M | P | | V | Y | + Method | | | | | | + Acct-Delay-Time 41 8.8 Unsigned32 | M | P | | V | Y | + Acct-Link-Count 51 8.9 Unsigned32 | M | P | | V | Y | + Acct-Tunnel- 68 8.10 OctetString| M | P | | V | Y | + Connection | | | | | | + Acct-Tunnel- 86 8.11 Unsigned32 | M | P | | V | Y | + Packets-Lost | | | | | | + -----------------------------------------|----+-----+----+-----|----| + +8.1. Accounting-Input-Octets AVP + + The Accounting-Input-Octets AVP (AVP Code 363) is of type Unsigned64 + and contains the number of octets received from the user. + + + + + +Calhoun, et al. Standards Track [Page 51] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + For NAS usage, this AVP indicates how many octets have been received + from the port in the course of this session. It can only be present + in ACR messages with an Accounting-Record-Type of INTERIM_RECORD or + STOP_RECORD. + +8.2. Accounting-Output-Octets AVP + + The Accounting-Output-Octets AVP (AVP Code 364) is of type Unsigned64 + and contains the number of octets sent to the user. + + For NAS usage, this AVP indicates how many octets have been sent to + the port in the course of this session. It can only be present in + ACR messages with an Accounting-Record-Type of INTERIM_RECORD or + STOP_RECORD. + +8.3. Accounting-Input-Packets AVP + + The Accounting-Input-Packets (AVP Code 365) is of type Unsigned64 and + contains the number of packets received from the user. + + For NAS usage, this AVP indicates how many packets have been received + from the port over the course of a session being provided to a Framed + User. It can only be present in ACR messages with an Accounting- + Record-Type of INTERIM_RECORD or STOP_RECORD. + +8.4. Accounting-Output-Packets AVP + + The Accounting-Output-Packets (AVP Code 366) is of type Unsigned64 + and contains the number of IP packets sent to the user. + + For NAS usage, this AVP indicates how many packets have been sent to + the port over the course of a session being provided to a Framed + User. It can only be present in ACR messages with an Accounting- + Record-Type of INTERIM_RECORD or STOP_RECORD. + +8.5. Acct-Session-Time AVP + + The Acct-Session-Time AVP (AVP Code 46) is of type Unsigned32 and + indicates the length of the current session in seconds. It can only + be present in ACR messages with an Accounting-Record-Type of + INTERIM_RECORD or STOP_RECORD. + +8.6. Acct-Authentic AVP + + The Acct-Authentic AVP (AVP Code 45) is of type Enumerated and + specifies how the user was authenticated. The supported values are + listed in [RADIUSTypes]. The following list is informational: + + + + +Calhoun, et al. Standards Track [Page 52] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + 1 RADIUS + 2 Local + 3 Remote + 4 Diameter + +8.7. Accounting-Auth-Method AVP + + The Accounting-Auth-Method AVP (AVP Code 406) is of type Enumerated. + A NAS MAY include this AVP in an Accounting-Request message to + indicate the method used to authenticate the user. (Note that this + is equivalent to the RADIUS MS-Acct-Auth-Type VSA attribute). + + The following values are defined: + + 1 PAP + 2 CHAP + 3 MS-CHAP-1 + 4 MS-CHAP-2 + 5 EAP + 7 None + +8.8. Acct-Delay-Time + + The Acct-Delay-Time AVP (AVP Code 41) is of type Unsigned32 and + indicates the number of seconds the Diameter client has been trying + to send the Accounting-Request (ACR). The accounting server may + subtract this value from the time when the ACR arrives at the server + to calculate the approximate time of the event that caused the ACR to + be generated. + + This AVP is not used for retransmissions at the transport level (TCP + or SCTP). Rather, it may be used when an ACR command cannot be + transmitted because there is no appropriate peer to transmit it to or + was rejected because it could not be delivered. In these cases, the + command MAY be buffered and transmitted later, when an appropriate + peer-connection is available or after sufficient time has passed that + the destination-host may be reachable and operational. If the ACR is + resent in this way, the Acct-Delay-Time AVP SHOULD be included. The + value of this AVP indicates the number of seconds that elapsed + between the time of the first attempt at transmission and the current + attempt. + + + + + + + + + + +Calhoun, et al. Standards Track [Page 53] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +8.9. Acct-Link-Count + + The Acct-Link-Count AVP (AVP Code 51) is of type Unsigned32 and + indicates the total number of links that have been active (current or + closed) in a given multilink session at the time the accounting + record is generated. This AVP MAY be included in Accounting-Requests + for any session that may be part of a multilink service. + + The Acct-Link-Count AVP may be used to make it easier for an + accounting server to know when it has all the records for a given + multilink service. When the number of Accounting-Requests received + with Accounting-Record-Type = STOP_RECORD and with the same Acct- + Multi-Session-Id and unique Session-Ids equals the largest value of + Acct-Link-Count seen in those Accounting-Requests, all STOP_RECORD + Accounting-Requests for that multilink service have been received. + + The following example, showing eight Accounting-Requests, illustrates + how the Acct-Link-Count AVP is used. In the table below, only the + relevant AVPs are shown, although additional AVPs containing + accounting information will be present in the Accounting-Requests. + + Acct-Multi- Accounting- Acct- + Session-Id Session-Id Record-Type Link-Count + -------------------------------------------------------- + "...10" "...10" START_RECORD 1 + "...10" "...11" START_RECORD 2 + "...10" "...11" STOP_RECORD 2 + "...10" "...12" START_RECORD 3 + "...10" "...13" START_RECORD 4 + "...10" "...12" STOP_RECORD 4 + "...10" "...13" STOP_RECORD 4 + "...10" "...10" STOP_RECORD 4 + +8.10. Acct-Tunnel-Connection AVP + + The Acct-Tunnel-Connection AVP (AVP Code 68) is of type OctetString + and contains the identifier assigned to the tunnel session. This + AVP, along with the Tunnel-Client-Endpoint and Tunnel-Server-Endpoint + AVPs, may be used to provide a means to uniquely identify a tunnel + session for auditing purposes. + + The format of the identifier in this AVP depends upon the value of + the Tunnel-Type AVP. For example, to identify an L2TP tunnel + connection fully, the L2TP Tunnel Id and Call Id might be encoded in + this field. The exact encoding of this field is implementation + dependent. + + + + + +Calhoun, et al. Standards Track [Page 54] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +8.11. Acct-Tunnel-Packets-Lost AVP + + The Acct-Tunnel-Packets-Lost AVP (AVP Code 86) is of type Unsigned32 + and contains the number of packets lost on a given link. + +9. RADIUS/Diameter Protocol Interactions + + This section describes some basic guidelines that servers acting as + AAA Translation Agents may use. A complete description of all the + differences between RADIUS and Diameter is beyond the scope of this + section and document. Note that this document does not restrict + implementations from creating additional translation methods, as long + as the translation function doesn't violate the RADIUS or the + Diameter protocols. + + Although the Diameter protocol is in many ways a superset of RADIUS + functions, a number of RADIUS representations are not allowed, so + that new capabilities can be used without the old problems. + + There are primarily two different situations that must be handled: + one in which a RADIUS request is received that must be forwarded as a + Diameter request, and another in which the inverse is true. RADIUS + does not support a peer-to-peer architecture, and server-initiated + operations are generally not supported. See [RADDynAuth] for an + alternative. + + Some RADIUS attributes are encrypted. RADIUS security and encryption + techniques are applied on a hop-per-hop basis. A Diameter agent will + have to decrypt RADIUS attribute data entering the Diameter system, + and if that information is forwarded, the agent MUST secure it by + using Diameter specific techniques. + + Note that this section uses the two terms, "AVP" and "attribute", in + a concise and specific manner. The former is used to signify a + Diameter AVP, and the latter to signify a RADIUS attribute. + +9.1. RADIUS Request Forwarded as Diameter Request + + This section describes the actions that should be taken when a + Translation Agent receives a RADIUS message to be translated to a + Diameter message. + + Note that RADIUS servers are assumed to be stateless. It is also + quite possible for the RADIUS messages that comprise the session + (i.e., authentication and accounting messages) to be handled by + different Translation Agents in the proxy network. Therefore, a + RADIUS/Diameter Translation Agent SHOULD NOT be assumed to have an + accurate track on session-state information. + + + +Calhoun, et al. Standards Track [Page 55] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + When a Translation Agent receives a RADIUS message, the following + steps should be taken: + + - If a Message-Authenticator attribute is present, the value MUST + be checked but not included in the Diameter message. If it is + incorrect, the RADIUS message should be silently discarded. + The gateway system SHOULD generate and include a Message- + Authenticator in returned RADIUS responses. + + - The transport address of the sender MUST be checked against the + NAS identifying attributes. See the description of NAS- + Identifier and NAS-IP-Address below. + + - The Translation Agent must maintain transaction state + information relevant to the RADIUS request, such as the + Identifier field in the RADIUS header, any existing RADIUS + Proxy-State attribute, and the source IP address and port + number of the UDP packet. These may be maintained locally in a + state table or saved in a Proxy-Info AVP group. A Diameter + Session-Id AVP value must be created using a session state + mapping mechanism. + + - If the RADIUS request contained a State attribute and the + prefix of the data is "Diameter/", the data following the + prefix contains the Diameter Origin-Host/Origin-Realm/Session- + Id. If no such attributes are present and the RADIUS command + is an Access-Request, a new Session-Id is created. The + Session-Id is included in the Session-Id AVP. + + - The Diameter Origin-Host and Origin-Realm AVPs MUST be created + and added by using the information from an FQDN corresponding + to the NAS-IP-Address attribute (preferred if available), + and/or to the NAS-Identifier attribute. (Note that the RADIUS + NAS-Identifier is not required to be an FQDN.) + + - The response MUST have an Origin-AAA-Protocol AVP added, + indicating the protocol of origin of the message. + + - The Proxy-Info group SHOULD be added, with the local server's + identity specified in the Proxy-Host AVP. This should ensure + that the response is returned to this system. + + - The Destination-Realm AVP is created from the information found + in the RADIUS User-Name attribute. + + + + + + + +Calhoun, et al. Standards Track [Page 56] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + - If the RADIUS User-Password attribute is present, the password + must be unencrypted by using the link's RADIUS shared secret. + The unencrypted value must be forwarded in a User-Password AVP + using Diameter security. + + - If the RADIUS CHAP-Password attribute is present, the Ident and + Data portion of the attribute are used to create the CHAP-Auth + grouped AVP. + + - If the RADIUS message contains an address attribute, it MUST be + converted to the appropriate Diameter AVP and type. + + - If the RADIUS message contains Tunnel information [RADTunnels], + the attributes or tagged groups should each be converted to a + Diameter Tunneling Grouped AVP set. If the tunnel information + contains a Tunnel-Password attribute, the RADIUS encryption + must be resolved, and the password forwarded, by using Diameter + security methods. + + - If the RADIUS message received is an Accounting-Request, the + Acct-Status-Type attribute value must be converted to a + Accounting-Record-Type AVP value. If the Acct-Status-Type + attribute value is STOP, the local server MUST issue a + Session-Termination-Request message once the Diameter + Accounting-Answer message has been received. + + - If the Accounting message contains an Acct-Termination-Cause + attribute, it should be translated to the equivalent + Termination-Cause AVP value. (see below) + + - If the RADIUS message contains the Accounting-Input-Octets, + Accounting-Input-Packets, Accounting-Output-Octets, or + Accounting-Output-Packets, these attributes must be converted + to the Diameter equivalents. Further, if the Acct-Input- + Gigawords or Acct-Output-Gigawords attributes are present, + these must be used to properly compute the Diameter accounting + AVPs. + + The corresponding Diameter response is always guaranteed to be + received by the same Translation Agent that translated the original + request, due to the contents of the Proxy-Info AVP group in the + Diameter request. The following steps are applied to the response + message during the Diameter-to-RADIUS translation: + + - If the Diameter Command-Code is set to AA-Answer and the + Result-Code AVP is set to DIAMETER_MULTI_ROUND_AUTH, the + gateway must send a RADIUS Access-Challenge. This must have + the Origin-Host, Origin-Realm, and Diameter Session-Id AVPs + + + +Calhoun, et al. Standards Track [Page 57] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + encapsulated in the RADIUS State attribute, with the prefix + "Diameter/", concatenated in the above order separated with "/" + characters, in UTF-8 [UTF-8]. This is necessary to ensure that + the Translation Agent receiving the subsequent RADIUS Access- + Request will have access to the Session Identifier and be able + to set the Destination-Host to the correct value. If the + Multi-Round-Time-Out AVP is present, the value of the AVP MUST + be inserted in the RADIUS Session-Timeout AVP. + + - If the Command-Code is set to AA-Answer, the Diameter Session- + Id AVP is saved in a new RADIUS Class attribute whose format + consists of the string "Diameter/" followed by the Diameter + Session Identifier. This will ensure that the subsequent + Accounting messages, which could be received by any Translation + Agent, would have access to the original Diameter Session + Identifier. + - If a Proxy-State attribute was present in the RADIUS request, + the same attribute is added in the response. This information + may be found in the Proxy-Info AVP group, or in a local state + table. + + - If state information regarding the RADIUS request was saved in + a Proxy-Info AVP or local state table, the RADIUS Identifier + and UDP IP Address and port number are extracted and used in + issuing the RADIUS reply. + + When translating a Diameter AA-Answer (with successful result code) + to RADIUS Access-Accept that contains a Session-Timeout or + Authorization-Lifetime AVP, take the following steps: + + - If the Diameter message contains a Session-Timeout AVP but no + Authorization-Lifetime AVP, translate it to a Session-Timeout + attribute (not a Termination-Action). + + - If the Diameter message contains an Authorization-Lifetime AVP + but no Session-Timeout AVP, translate it to a Session-Timeout + attribute and a Termination-Action set to AA-REQUEST. (Remove + Authorization-Lifetime and Re-Auth-Request-Type.) + + - If the Diameter message has both, the Session-Timeout must be + greater than or equal to the Authorization-Lifetime (required + by [BASE]). Translate it to a Session-Timeout value (with + value from Authorization-Lifetime AVP, the smaller one) and + with the Termination-Action set to AA-REQUEST. (Remove the + Authorization-Lifetime and Re-Auth-Request-Type.) + + + + + + +Calhoun, et al. Standards Track [Page 58] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +9.1.1. RADIUS Dynamic Authorization Considerations + + A Diameter/RADIUS gateway may communicate with a server that + implements RADIUS Dynamic Authorization [RADDynAuth]. If the server + supports these functions, it MUST be listening on the assigned port + and would receive RADIUS CoA-Request and Disconnect-Request messages. + These can be mapped into the Diameter Re-Auth-Request (RAR) and + Abort-Session-Request (ASR) message exchanges, respectively [BASE]. + + If the [RADDynAuth] is not supported, the port would not be active + and the RADIUS server would receive an ICMP Port Unreachable + indication. Alternatively, if the messages are received but with an + inappropriate Service-Type, the gateway can respond with the + appropriate NAK message and an Error-Cause attribute with the value + of 405, "Unsupported Service". + + The RADIUS CoA-Request and Disconnect-Request messages will not + contain a Diameter Session-Id. Diameter requires that this value + match an active session context. The gateway MUST have a session Id + cache (or other means) to identify the sessions these functions + pertain to. If unable to identify the session, the gateway (or NAS) + should return an Error-Cause value 503, "Session Context Not Found". + + The RADIUS CoA-Request message only supports a change of + authorization attributes, and the received CoA-Request SHOULD include + a Service-Type of "Authorize-Only". This indicates an extended + exchange request by the rules given in [RADDynAuth] section 3.2, note + 6. This is the only type of exchange supported by Diameter [BASE]. + + For the CoA-Request, the translated RAR message will have a Re-Auth- + Type of AUTHORIZE_ONLY. The returned RAA will be translated into a + CoA-NAK with Error-Cause "Request Initiated". The gateway's Diameter + client SHOULD also start a reauthorization sequence by sending an AAR + message, which will be translated into an Access-Request message. + The RADIUS server will use the Access-Accept (or Access-Reject) + message to convey the new authorization attributes, which the gateway + will pass back in an AAA message. + + Any attributes included in the COA-Request or Access-Accept message + are to be considered mandatory in Diameter. If they cannot be + supported, they MUST result in an error message return to the RADIUS + server, with an Error-Cause of "Unsupported Attribute". The Diameter + NAS will attempt to apply all the attributes supplied in the AA + message to the session. + + A RADIUS Disconnect-Request message received by the gateway would be + translated to a Diameter Abort-Session-Request (ASR) message [BASE]. + The results will be returned by the Diameter client in an Abort- + + + +Calhoun, et al. Standards Track [Page 59] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + Session-Answer (ASA) message. A success indication would translate + to a RADIUS Disconnect-ACK, and a failure would generate a + Disconnect-NAK. + +9.2. Diameter Request Forwarded as RADIUS Request + + When a server receives a Diameter request to be forwarded to a RADIUS + entity, the following are examples of the steps that may be taken: + + - The Origin-Host AVP's value is inserted into the NAS-Identifier + attribute. + + - The following information MUST be present in the corresponding + Diameter response and therefore MUST be saved, either in a + local state table or encoded in a RADIUS Proxy-State attribute: + + 1. Origin-Host AVP + 2. Session-Id AVP + 3. Proxy-Info AVP + 4. Any other AVP that MUST be present in the response and + has no corresponding RADIUS attribute. + + - If the CHAP-Auth AVP is present, the grouped AVPs are used to + create the RADIUS CHAP-Password attribute data. + + - If the User-Password AVP is present, the data should be + encrypted and forwarded by using RADIUS rules. The same is + true for any other RADIUS-encrypted attribute values. + + - AVPs of the type Address must be translated to the + corresponding RADIUS attribute. + + - If the Accounting-Input-Octets, Accounting-Input-Packets, + Accounting-Output-Octets, or Accounting-Output-Packets AVPs are + present, they must be translated to the corresponding RADIUS + attributes. If the value of the Diameter AVPs do not fit + within a 32-bit RADIUS attribute, the RADIUS Acct-Input- + Gigawords and Acct-Output-Gigawords must be used. + + - If the RADIUS link supports the Message-Authenticator attribute + [RADIUSExt], it SHOULD be generated and added to the request. + + When the corresponding response is received by the Translation Agent, + which is guaranteed in the RADIUS protocol, the following steps may + be taken: + + + + + + +Calhoun, et al. Standards Track [Page 60] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + - If the RADIUS code is set to Access-Challenge, a Diameter AA- + Answer message is created with the Result-Code set to + DIAMETER_MULTI_ROUND_AUTH. If the Session-Timeout AVP is + present in the RADIUS message, its value is inserted into the + Multi-Round-Time-Out AVP. + + - If a Proxy-State attribute is present, extract the encoded + information; otherwise, retrieve the original Proxy-Info AVP + group information from the local state table. + + - The response's Origin-Host information is created from the FQDN + of the RADIUS message's source IP address. The same FQDN is + also stored to a Route-Record AVP. + + - The response's Destination-Host AVP is copied from the saved + request's Origin-Host information. + + - The Session-Id information can be recovered from local state, + or from the constructed State or Proxy-State attribute, as + above. + + - If a Proxy-Info AVP was present in the request, the same AVP + MUST be added to the response. + + - If the RADIUS State attributes are present, they must be + present in the Diameter response, minus those added by the + gateway. + + - Any other AVPs that were saved at request time, and that MUST + be present in the response, are added to the message. + + When translating a RADIUS Access-Accept to Diameter AA-Answer that + contains a Session-Timeout attribute, do the following: + + - If the RADIUS message contains a Session-Timeout attribute and + a Termination-Action attribute set to DEFAULT (or no + Termination-Action attribute at all), translate it to AA-Answer + with a Session-Timeout AVP and remove the Termination-Action + attribute. + + - If the RADIUS message contains a Session-Timeout attribute and + a Termination-Action attribute set to AA-REQUEST, translate it + to AA-Answer with Authorization-Lifetime AVP and with Re-Auth- + Request-Type set to AUTHORIZE_AUTHENTICATE and remove the + Session-Timeout attribute. + + + + + + +Calhoun, et al. Standards Track [Page 61] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +9.2.1. RADIUS Dynamic Authorization Considerations + + A RADIUS/Diameter gateway communicating with a RADIUS client that + implements RADIUS Dynamic Authorization [RADDynAuth] may translate + Diameter Re-Auth-Request (RAR) messages and Abort-Session-Request + (ASR) messages [BASE] into RADIUS CoA-Request and Disconnect-Request + messages respectively. + + If the RADIUS client does not support the capability, the gateway + will receive an ICMP Port Unreachable indication when it transmits + the RADIUS message. Even if the NAS supports [RADDynAuth], it may + not support the Service-Type in the request message. In this case it + will respond with a NAK message and (optionally) an Error-Cause + attribute with value 405, "Unsupported Service". If the gateway + encounters these error conditions, or if it does not support + [RADDynAuth], it sends a Diameter Answer message with an Result-Code + AVP of "DIAMETER_COMMAND_UNSUPPORTED" to the AAA server. + + When encoding the RADIUS messages, the gateway MUST include the + Diameter Session-ID in the RADIUS State attribute value, as mentioned + above. The RADIUS client should return it in the response. + + A Diameter Re-Auth-Request (RAR) message [BASE] received by the + gateway will be translated into a RADIUS CoA-Request and sent to the + RADIUS client. The RADIUS client should respond with a CoA-ACK or + CoA-NAK message, which the gateway should translate into a Re-Auth- + Answer (RAA) message. + + If the gateway receives a RADIUS CoA-NAK response containing a + Service-Type Attribute with value "Authorize Only" and an Error-Cause + Attribute with value "Request Initiated", this indicates an extended + exchange request per [RADDynAuth] section 3.2, note 6. + + The response is translated to a Diameter Re-Auth-Answer (RAA) with a + Result-Code AVP of "DIAMETER_LIMITED_SUCCESS" sent to the AAA server. + + Subsequently, the gateway should receive a RADIUS Access-Request from + the NAS, with a Service-Type of "Authorize Only". This is translated + into a Diameter AA-Request with an Auth-Request-Type AVP of + AUTHORIZE_ONLY and sent to the AAA server. The AAA server will then + reply with a Diameter AA-Answer, which is translated into a RADIUS + Access-Accept or Access-Reject, depending on the value of the + Result-Code AVP. + + A Diameter Abort-Session-Request (ASR) message [BASE] received by the + gateway will be translated into a RADIUS Disconnect-Request and sent + to the RADIUS client. The RADIUS client should respond with a + + + + +Calhoun, et al. Standards Track [Page 62] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + Disconnect-ACK or Disconnect-NAK message, which the gateway should + translate into an Abort-Session-Answer (ASA) message. + + If the gateway receives a RADIUS Disconnect-NAK response containing a + Service-Type Attribute with value "Authorize Only" and an Error-Cause + Attribute with value "Request Initiated", the Disconnect-NAK response + is translated into a Diameter Abort-Session-Answer (ASA) with a + Result-Code AVP of "DIAMETER_LIMITED_SUCCESS" sent to the AAA server. + + Subsequently, the gateway should receive a RADIUS Access-Request from + the NAS, with a Service-Type of "Authorize Only". This is translated + into a Diameter AA-Request with an Auth-Request-Type AVP of + AUTHORIZE_ONLY and sent to the AAA server. The AAA server will then + reply with a Diameter AA-Answer, which is translated into a RADIUS + Access-Accept or Access-Reject, depending on the value of the + Result-Code AVP. + +9.3. AVPs Used Only for Compatibility + + The AVPs defined in this section SHOULD only be used for backwards + compatibility when a Diameter/RADIUS translation function is invoked + and are not typically originated by Diameter systems during normal + operations. + + +---------------------+ + | AVP Flag rules | + |----+-----+----+-----|----+ + AVP Section | | |SHLD| MUST| | + Attribute Name Code Defined Value Type |MUST| MAY | NOT| NOT|Encr| + -----------------------------------------|----+-----+----+-----|----| + NAS-Identifier 32 9.3.1 UTF8String | M | P | | V | Y | + NAS-IP-Address 4 9.3.2 OctetString| M | P | | V | Y | + NAS-IPv6-Address 95 9.3.3 OctetString| M | P | | V | Y | + State 24 9.3.4 OctetString| M | P | | V | Y | + Termination- 295 9.3.5 Enumerated | M | P | | V | Y | + Cause | | | | | | + Origin-AAA- 408 9.3.6 Enumerated | M | P | | V | Y | + Protocol | | | | | | + -----------------------------------------|----+-----+----+-----|----| + +9.3.1. NAS-Identifier AVP + + The NAS-Identifier AVP (AVP Code 32) [RADIUS] is of type UTF8String + and contains the identity of the NAS providing service to the user. + This AVP SHOULD only be added by a RADIUS/Diameter Translation Agent. + When this AVP is present, the Origin-Host AVP identifies the NAS + providing service to the user. + + + + +Calhoun, et al. Standards Track [Page 63] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + In RADIUS it would be possible for a rogue NAS to forge the NAS- + Identifier attribute. Diameter/RADIUS translation agents SHOULD + attempt to check a received NAS-Identifier attribute against the + source address of the RADIUS packet, by doing an A/AAAA RR query. If + the NAS-Identifier attribute contains an FQDN, then such a query + would resolve to an IP address matching the source address. However, + the NAS-Identifier attribute is not required to contain an FQDN, so + such a query could fail. If it fails, an error should be logged, but + no action should be taken, other than a reverse lookup on the source + address and insert the resulting FQDN into the Route-Record AVP. + + Diameter agents and servers SHOULD check whether a NAS-Identifier AVP + corresponds to an entry in the Route-Record AVP. If no match is + found, then an error is logged, but no other action is taken. + +9.3.2. NAS-IP-Address AVP + + The NAS-IP-Address AVP (AVP Code 4) [RADIUS] is of type OctetString + and contains the IP Address of the NAS providing service to the user. + This AVP SHOULD only be added by a RADIUS/Diameter Translation Agent. + When this AVP is present, the Origin-Host AVP identifies the NAS + providing service to the user. + + In RADIUS it would be possible for a rogue NAS to forge the NAS-IP- + Address attribute value. Diameter/RADIUS translation agents MUST + check a received NAS-IP-Address or NAS-IPv6-Address attribute against + the source address of the RADIUS packet. If they do not match and + the Diameter/RADIUS translation agent does not know whether the + packet was sent by a RADIUS proxy or NAS (e.g., no Proxy-State + attribute), then by default it is assumed that the source address + corresponds to a RADIUS proxy, and that the NAS Address is behind + that proxy, potentially with some additional RADIUS proxies in + between. The Diameter/RADIUS translation agent MUST insert entries + in the Route-Record AVP corresponding to the apparent route. This + implies doing a reverse lookup on the source address and NAS-IP- + Address or NAS-IPv6-Address attributes to determine the corresponding + FQDNs. + + If the source address and the NAS-IP-Address or NAS-IPv6-Address do + not match, and the Diameter/RADIUS translation agent knows that it is + talking directly to the NAS (e.g., there are no RADIUS proxies + between it and the NAS), then the error should be logged, and the + packet MUST be discarded. + + Diameter agents and servers MUST check whether the NAS-IP-Address AVP + corresponds to an entry in the Route-Record AVP. This is done by + doing a reverse lookup (PTR RR) for the NAS-IP-Address to retrieve + the corresponding FQDN, and by checking for a match with the Route- + + + +Calhoun, et al. Standards Track [Page 64] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + Record AVP. If no match is found, then an error is logged, but no + other action is taken. + +9.3.3. NAS-IPv6-Address AVP + + The NAS-IPv6-Address AVP (AVP Code 95) [RADIUSIPv6] is of type + OctetString and contains the IPv6 Address of the NAS providing + service to the user. This AVP SHOULD only be added by a + RADIUS/Diameter Translation Agent. When this AVP is present, the + Origin-Host AVP identifies the NAS providing service to the user. + + In RADIUS it would be possible for a rogue NAS to forge the NAS- + IPv6-Address attribute. Diameter/RADIUS translation agents MUST + check a received NAS-IPv6-Address attribute against the source + address of the RADIUS packet. If they do not match and the + Diameter/RADIUS translation agent does not know whether the packet + was sent by a RADIUS proxy or NAS (e.g., no Proxy-State attribute), + then by default it is assumed that the source address corresponds to + a RADIUS proxy, and that the NAS-IPv6-Address is behind that proxy, + potentially with some additional RADIUS proxies in between. The + Diameter/RADIUS translation agent MUST insert entries in the Route- + Record AVP corresponding to the apparent route. This implies doing a + reverse lookup on the source address and NAS-IPv6-Address attributes + to determine the corresponding FQDNs. + + If the source address and the NAS-IPv6-Address do not match, and the + Diameter/RADIUS translation agent knows that it is talking directly + to the NAS (e.g., there are no RADIUS proxies between it and the + NAS), then the error should be logged, and the packet MUST be + discarded. + + Diameter agents and servers MUST check whether the NAS-IPv6-Address + AVP corresponds to an entry in the Route-Record AVP. This is done by + doing a reverse lookup (PTR RR) for the NAS-IPv6-Address to retrieve + the corresponding FQDN, and by checking for a match with the Record- + Route AVP. If no match is found, then an error is logged, but no + other action is taken. + +9.3.4. State AVP + + The State AVP (AVP Code 24) [RADIUS] is of type OctetString and has + two uses in the Diameter NAS application. + + The State AVP MAY be sent by a Diameter Server to a NAS in an AA- + Response command that contains a Result-Code of + DIAMETER_MULTI_ROUND_AUTH. If so, the NAS MUST return it unmodified + in the subsequent AA-Request command. + + + + +Calhoun, et al. Standards Track [Page 65] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + The State AVP MAY also be sent by a Diameter Server to a NAS in an + AA-Response command that also includes a Termination-Action AVP with + the value of AA-REQUEST. If the NAS performs the Termination-Action + by sending a new AA-Request command upon termination of the current + service, it MUST return the State AVP unmodified in the new request + command. + + In either usage, the NAS MUST NOT interpret the AVP locally. Usage + of the State AVP is implementation dependent. + +9.3.5. Termination-Cause AVP Code Values + + This section defines a mapping between Termination-Cause AVP code + values and RADIUS Acct-Terminate-Cause attribute code values from RFC + 2866 [RADIUSAcct] and [RADIUSTypes], thereby allowing a + RADIUS/Diameter Translation Agent to convert between the attribute + and AVP values. This section thus extends the definitions in the + "Termination-Cause AVP" section of the Base Diameter specification. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 66] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + The table in this section defines the mapping between Termination- + Cause AVP and RADIUS Acct-Terminate-Cause causes. + + +-----------------------+ + | Value | + +-----------+-----------+ + Cause Value Name | RADIUS | Diameter | + ------------------------------|-----------+-----------+ + User Request | 1 | 11 | + Lost Carrier | 2 | 12 | + Lost Service | 3 | 13 | + Idle Timeout | 4 | 14 | + Session Timeout | 5 | 15 | + Admin Reset | 6 | 16 | + Admin Reboot | 7 | 17 | + Port Error | 8 | 18 | + NAS Error | 9 | 19 | + NAS Request | 10 | 20 | + NAS Reboot | 11 | 21 | + Port Unneeded | 12 | 22 | + Port Preempted | 13 | 23 | + Port Suspended | 14 | 24 | + Service Unavailable | 15 | 25 | + Callback | 16 | 26 | + User Error | 17 | 27 | + Host Request | 18 | 28 | + Supplicant Restart | 19 | 29 | [RAD802.1X] + Reauthentication Failure | 20 | 30 | [RAD802.1X] + Port Reinit | 21 | 31 | [RAD802.1X] + Port Disabled | 22 | 32 | [RAD802.1X] + ------------------------------|-----------+-----------+ + + From RFC 2866, the termination causes are as follows: + + User Request User requested termination of service, for + example with LCP Terminate or by logging out. + + Lost Carrier DCD was dropped on the port. + + Lost Service Service can no longer be provided; for + example, user's connection to a host was + interrupted. + + Idle Timeout Idle timer expired. + + Session Timeout Maximum session length timer expired. + + Admin Reset Administrator reset the port or session. + + + +Calhoun, et al. Standards Track [Page 67] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + Admin Reboot Administrator is ending service on the NAS, + for example, prior to rebooting the NAS. + + Port Error NAS detected an error on the port that + required ending the session. + + NAS Error NAS detected an error (other than on the + port) that required ending the session. + + NAS Request NAS ended the session for a non-error reason not + otherwise listed here. + + NAS Reboot NAS ended the session to reboot + non-administratively ("crash"). + + Port Unneeded NAS ended the session because resource usage + fell below a low-water mark (for example, if + a bandwidth-on-demand algorithm decided that + the port was no longer needed). + + Port Preempted NAS ended the session to allocate the + port to a higher priority use. + + Port Suspended NAS ended the session to suspend a virtual + session. + + Service Unavailable NAS was unable to provide requested service. + + Callback NAS is terminating the current session + to perform callback for a new session. + + User Error Input from user is in error, causing + session termination. + + Host Request Login Host terminated session normally. + +9.3.6. Origin-AAA-Protocol + + The Origin-AAA-Protocol AVP (AVP Code 408) is of the type Enumerated + and should be inserted in a Diameter message translated by a gateway + system from another AAA protocol, such as RADIUS. It identifies the + source protocol of the message to the Diameter system receiving the + message. + + The supported values are: + + 1 RADIUS + + + + +Calhoun, et al. Standards Track [Page 68] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +9.4. Prohibited RADIUS Attributes + + The following RADIUS attributes MUST NOT appear in a Diameter + message. Instead, they are translated to other Diameter AVPs or + handled in some special manner. The rules for the treatment of the + attributes are discussed in sections 9.1, 9.2, and 9.6. + + Attribute Description Defined Nearest Diameter AVP + ----------------------------------------------------------------- + 3 CHAP-Password RFC 2865 CHAP-Auth Group + 26 Vendor-Specific RFC 2865 Vendor Specific AVP + 29 Termination-Action RFC 2865 Authorization-Lifetime + 40 Acct-Status-Type RFC 2866 Accounting-Record-Type + 42 Acct-Input-Octets RFC 2866 Accounting-Input-Octets + 43 Acct-Output-Octets RFC 2866 Accounting-Output-Octets + 47 Acct-Input-Packets RFC 2866 Accounting-Input-Packets + 48 Acct-Output-Packets RFC 2866 Accounting-Output-Packets + 49 Acct-Terminate-Cause RFC 2866 Termination-Cause + 52 Acct-Input-Gigawords RFC 2869 Accounting-Input-Octets + 53 Acct-Output-Gigawords RFC 2869 Accounting-Output-Octets + 80 Message-Authenticator RFC 2869 none - check and discard + +9.5. Translatable Diameter AVPs + + In general, Diameter AVPs that are not RADIUS compatible have code + values greater than 255. The table in the section above shows the + AVPs that can be converted into RADIUS attributes. + + Another problem may occur with Diameter AVP values that may be more + than 253 octets in length. Some RADIUS attributes (including but not + limited to (8)Reply-Message, (79)EAP-Message, and (77)Connect-Info) + allow concatenation of multiple instances to overcome this + limitation. If this is not possible, a Result-Code of + DIAMETER_INVALID_AVP_LENGTH should be returned. + +9.6. RADIUS Vendor Specific Attributes + + RADIUS supports the inclusion of Vendor Specific Attributes (VSAs) + through the use of attribute 26. The recommended format [RADIUS] of + the attribute data field includes a 4 octet vendor code followed by a + one octet vendor type field and a one octet length field. The last + two fields MAY be repeated. + + A system communicating between Diameter and RADIUS MAY have specific + knowledge of vendor formats, and MAY be able to translate between the + two formats. However, given the deployment of many RADIUS vendor + formats that do not follow the example format in RFC 2865 [RADIUS], + (e.g., those that use a longer vendor type code) the translations in + + + +Calhoun, et al. Standards Track [Page 69] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + the next two sections will not work in general for those VSAs. RFC + 2865 states that a robust implementation SHOULD support the field as + undistinguished octets. + + Systems that don't have vendor format knowledge MAY discard such + attributes without knowing a suitable translation. An alternative + format is under consideration [VSA], which proposes encodings that + would preserve the native information and not require vendor + knowledge in the gateway system. + + The following sections are an example for translating RADIUS VSAs + that use the example RADIUS format, and Diameter VSAs that have type + codes less than 255, and value field lengths less than 252. + +9.6.1. Forwarding a Diameter Vendor Specific AVP as a RADIUS VSA + + For Type codes less than 255, the value field length MUST be less + than 252 or the AVP will be discarded. The RADIUS VSA attribute + should consist of the following fields; + + RADIUS Type = 26, Vendor Specific Attribute + RADIUS Length = total length of attribute (header + data) + RADIUS Vendor code = Diameter Vendor code + RADIUS Vendor type code = low order byte of Diameter AVP code + RADIUS Vendor data length = length of Diameter data + + If the Diameter AVP code is greater than 255, then the RADIUS + speaking code may use a Vendor specific field coding, if it knows one + for that vendor. Otherwise, the AVP will be ignored. If it is + flagged as Mandatory, a "DIAMETER_AVP_UNSUPPORTED" Result-Code will + be returned, and the RADIUS message will not be sent. + +9.6.2. Forwarding a RADIUS VSA as a Diameter Vendor Specific AVP + + The Diameter AVP will consist of the following fields: + + Diameter Flags: V=1, M=0, P=0 + Diameter Vendor code = RADIUS VSA Vendor code + Diameter AVP code = RADIUS VSA Vendor type code + Diameter AVP length = length of AVP (header + data) + Diameter Data = RADIUS VSA vendor data + + Note that the VSAs are considered optional by RADIUS rules, and this + specification does not set the Mandatory flag. If an implementor + desires a VSA be made mandatory because it represents a required + service policy, the RADIUS gateway should have a process to set the + bit on the Diameter side. + + + + +Calhoun, et al. Standards Track [Page 70] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + If the RADIUS receiving code knows of vendor specific field + interpretations for the specific vendor, it may employ them to parse + an extended AVP code or data length. Otherwise the recommended + standard fields will be used. + + Nested Multiple vendor data fields MUST be expanded into multiple + Diameter AVPs. + +10. AVP Occurrence Tables + + The following tables present the AVPs used by NAS applications in NAS + messages and specify in which Diameter messages they MAY or MAY NOT + be present. [BASE] messages and AVPs are not described in this + document. Note that AVPs that can only be present within a Grouped + AVP are not represented in this table. + + The table uses the following symbols: + + 0 The AVP MUST NOT be present in the message. + 0+ Zero or more instances of the AVP MAY be present in the + message. + 0-1 Zero or one instance of the AVP MAY be present in the + message. + 1 One instance of the AVP MUST be present in the message. + +10.1. AA-Request/Answer AVP Table + + The table in this section is limited to the Command Codes defined in + this specification. + + +-----------+ + | Command | + |-----+-----+ + Attribute Name | AAR | AAA | + ------------------------------|-----+-----+ + Acct-Interim-Interval | 0 | 0-1 | + ARAP-Challenge-Response | 0 | 0-1 | + ARAP-Features | 0 | 0-1 | + ARAP-Password | 0-1 | 0 | + ARAP-Security | 0-1 | 0-1 | + ARAP-Security-Data | 0+ | 0+ | + ARAP-Zone-Access | 0 | 0-1 | + Auth-Application-Id | 1 | 1 | + Auth-Grace-Period | 0-1 | 0-1 | + Auth-Request-Type | 1 | 1 | + Auth-Session-State | 0-1 | 0-1 | + Authorization-Lifetime | 0-1 | 0-1 | + ------------------------------|-----+-----+ + + + +Calhoun, et al. Standards Track [Page 71] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + +-----------+ + | Command | + |-----+-----+ + Attribute Name | AAR | AAA | + ------------------------------|-----+-----+ + Callback-Id | 0 | 0-1 | + Callback-Number | 0-1 | 0-1 | + Called-Station-Id | 0-1 | 0 | + Calling-Station-Id | 0-1 | 0 | + CHAP-Auth | 0-1 | 0 | + CHAP-Challenge | 0-1 | 0 | + Class | 0 | 0+ | + Configuration-Token | 0 | 0+ | + Connect-Info | 0+ | 0 | + Destination-Host | 0-1 | 0 | + Destination-Realm | 1 | 0 | + Error-Message | 0 | 0-1 | + Error-Reporting-Host | 0 | 0-1 | + Failed-AVP | 0+ | 0+ | + Filter-Id | 0 | 0+ | + Framed-Appletalk-Link | 0 | 0-1 | + Framed-Appletalk-Network | 0 | 0+ | + Framed-Appletalk-Zone | 0 | 0-1 | + Framed-Compression | 0+ | 0+ | + Framed-Interface-Id | 0-1 | 0-1 | + Framed-IP-Address | 0-1 | 0-1 | + Framed-IP-Netmask | 0-1 | 0-1 | + Framed-IPv6-Prefix | 0+ | 0+ | + Framed-IPv6-Pool | 0 | 0-1 | + Framed-IPv6-Route | 0 | 0+ | + Framed-IPX-Network | 0 | 0-1 | + Framed-MTU | 0-1 | 0-1 | + Framed-Pool | 0 | 0-1 | + Framed-Protocol | 0-1 | 0-1 | + Framed-Route | 0 | 0+ | + Framed-Routing | 0 | 0-1 | + Idle-Timeout | 0 | 0-1 | + Login-IP-Host | 0+ | 0+ | + Login-IPv6-Host | 0+ | 0+ | + Login-LAT-Group | 0-1 | 0-1 | + Login-LAT-Node | 0-1 | 0-1 | + Login-LAT-Port | 0-1 | 0-1 | + Login-LAT-Service | 0-1 | 0-1 | + Login-Service | 0 | 0-1 | + Login-TCP-Port | 0 | 0-1 | + Multi-Round-Time-Out | 0 | 0-1 | + ------------------------------|-----+-----+ + + + + +Calhoun, et al. Standards Track [Page 72] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + +-----------+ + | Command | + |-----+-----+ + Attribute Name | AAR | AAA | + ------------------------------|-----+-----+ + NAS-Filter-Rule | 0 | 0+ | + NAS-Identifier | 0-1 | 0 | + NAS-IP-Address | 0-1 | 0 | + NAS-IPv6-Address | 0-1 | 0 | + NAS-Port | 0-1 | 0 | + NAS-Port-Id | 0-1 | 0 | + NAS-Port-Type | 0-1 | 0 | + Origin-AAA-Protocol | 0-1 | 0-1 | + Origin-Host | 1 | 1 | + Origin-Realm | 1 | 1 | + Origin-State-Id | 0-1 | 0-1 | + Originating-Line-Info | 0-1 | 0 | + Password-Retry | 0 | 0-1 | + Port-Limit | 0-1 | 0-1 | + Prompt | 0 | 0-1 | + Proxy-Info | 0+ | 0+ | + QoS-Filter-Rule | 0 | 0+ | + Re-Auth-Request-Type | 0 | 0-1 | + Redirect-Host | 0 | 0+ | + Redirect-Host-Usage | 0 | 0-1 | + Redirect-Max-Cache-Time | 0 | 0-1 | + Reply-Message | 0 | 0+ | + Result-Code | 0 | 1 | + Route-Record | 0+ | 0+ | + Service-Type | 0-1 | 0-1 | + Session-Id | 1 | 1 | + Session-Timeout | 0 | 0-1 | + State | 0-1 | 0-1 | + Tunneling | 0+ | 0+ | + User-Name | 0-1 | 0-1 | + User-Password | 0-1 | 0 | + ------------------------------|-----+-----+ + +10.2. Accounting AVP Tables + + The tables in this section are used to show which AVPs defined in + this document are to be present and used in NAS application + Accounting messages. These AVPs are defined in this document, as + well as in [BASE] and [RADIUSAcct]. + + + + + + + +Calhoun, et al. Standards Track [Page 73] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +10.2.1. Accounting Framed Access AVP Table + + The table in this section is used when the Service-Type specifies + Framed Access. + + +-----------+ + | Command | + |-----+-----+ + Attribute Name | ACR | ACA | + ---------------------------------------|-----+-----+ + Accounting-Auth-Method | 0-1 | 0 | + Accounting-Input-Octets | 1 | 0 | + Accounting-Input-Packets | 1 | 0 | + Accounting-Output-Octets | 1 | 0 | + Accounting-Output-Packets | 1 | 0 | + Accounting-Record-Number | 0-1 | 0-1 | + Accounting-Record-Type | 1 | 1 | + Accounting-Realtime-Required | 0-1 | 0-1 | + Accounting-Sub-Session-Id | 0-1 | 0-1 | + Acct-Application-Id | 0-1 | 0-1 | + Acct-Session-Id | 1 | 0-1 | + Acct-Multi-Session-Id | 0-1 | 0-1 | + Acct-Authentic | 1 | 0 | + Acct-Delay-Time | 0-1 | 0 | + Acct-Interim-Interval | 0-1 | 0-1 | + Acct-Link-Count | 0-1 | 0 | + Acct-Session-Time | 1 | 0 | + Acct-Tunnel-Connection | 0-1 | 0 | + Acct-Tunnel-Packets-Lost | 0-1 | 0 | + Authorization-Lifetime | 0-1 | 0 | + Callback-Id | 0-1 | 0 | + Callback-Number | 0-1 | 0 | + Called-Station-Id | 0-1 | 0 | + Calling-Station-Id | 0-1 | 0 | + Class | 0+ | 0+ | + Connection-Info | 0+ | 0 | + Destination-Host | 0-1 | 0 | + Destination-Realm | 1 | 0 | + Event-Timestamp | 0-1 | 0-1 | + Error-Message | 0 | 0-1 | + Error-Reporting-Host | 0 | 0-1 | + Failed-AVP | 0 | 0+ | + ---------------------------------------|-----+-----+ + + + + + + + + +Calhoun, et al. Standards Track [Page 74] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + +-----------+ + | Command | + |-----+-----+ + Attribute Name | ACR | ACA | + ---------------------------------------|-----+-----+ + Framed-AppleTalk-Link | 0-1 | 0 | + Framed-AppleTalk-Network | 0-1 | 0 | + Framed-AppleTalk-Zone | 0-1 | 0 | + Framed-Compression | 0-1 | 0 | + Framed-IP-Address | 0-1 | 0 | + Framed-IP-Netmask | 0-1 | 0 | + Framed-IPv6-Prefix | 0+ | 0 | + Framed-IPv6-Pool | 0-1 | 0 | + Framed-IPX-Network | 0-1 | 0 | + Framed-MTU | 0-1 | 0 | + Framed-Pool | 0-1 | 0 | + Framed-Protocol | 0-1 | 0 | + Framed-Route | 0-1 | 0 | + Framed-Routing | 0-1 | 0 | + NAS-Filter-Rule | 0+ | 0 | + NAS-Identifier | 0-1 | 0-1 | + NAS-IP-Address | 0-1 | 0-1 | + NAS-IPv6-Address | 0-1 | 0-1 | + NAS-Port | 0-1 | 0-1 | + NAS-Port-Id | 0-1 | 0-1 | + NAS-Port-Type | 0-1 | 0-1 | + Origin-AAA-Protocol | 0-1 | 0-1 | + Origin-Host | 1 | 1 | + Origin-Realm | 1 | 1 | + Origin-State-Id | 0-1 | 0-1 | + Originating-Line-Info | 0-1 | 0 | + Proxy-Info | 0+ | 0+ | + QoS-Filter-Rule | 0+ | 0 | + Route-Record | 0+ | 0+ | + Result-Code | 0 | 1 | + Service-Type | 0-1 | 0-1 | + Session-Id | 1 | 1 | + Termination-Cause | 0-1 | 0-1 | + Tunnel-Assignment-Id | 0-1 | 0 | + Tunnel-Client-Endpoint | 0-1 | 0 | + Tunnel-Medium-Type | 0-1 | 0 | + Tunnel-Private-Group-Id | 0-1 | 0 | + Tunnel-Server-Endpoint | 0-1 | 0 | + Tunnel-Type | 0-1 | 0 | + User-Name | 0-1 | 0-1 | + Vendor-Specific-Application-Id | 0-1 | 0-1 | + ---------------------------------------|-----+-----+ + + + + +Calhoun, et al. Standards Track [Page 75] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +10.2.2. Accounting Non-Framed Access AVP Table + + The table in this section is used when the Service-Type specifies + Non-Framed Access. + + +-----------+ + | Command | + |-----+-----+ + Attribute Name | ACR | ACA | + ---------------------------------------|-----+-----+ + Accounting-Auth-Method | 0-1 | 0 | + Accounting-Input-Octets | 1 | 0 | + Accounting-Output-Octets | 1 | 0 | + Accounting-Record-Type | 1 | 1 | + Accounting-Record-Number | 0-1 | 0-1 | + Accounting-Realtime-Required | 0-1 | 0-1 | + Accounting-Sub-Session-Id | 0-1 | 0-1 | + Acct-Application-Id | 0-1 | 0-1 | + Acct-Session-Id | 1 | 0-1 | + Acct-Multi-Session-Id | 0-1 | 0-1 | + Acct-Authentic | 1 | 0 | + Acct-Delay-Time | 0-1 | 0 | + Acct-Interim-Interval | 0-1 | 0-1 | + Acct-Link-Count | 0-1 | 0 | + Acct-Session-Time | 1 | 0 | + Authorization-Lifetime | 0-1 | 0 | + Callback-Id | 0-1 | 0 | + Callback-Number | 0-1 | 0 | + Called-Station-Id | 0-1 | 0 | + Calling-Station-Id | 0-1 | 0 | + Class | 0+ | 0+ | + Connection-Info | 0+ | 0 | + Destination-Host | 0-1 | 0 | + Destination-Realm | 1 | 0 | + Event-Timestamp | 0-1 | 0-1 | + Error-Message | 0 | 0-1 | + Error-Reporting-Host | 0 | 0-1 | + Failed-AVP | 0 | 0+ | + Login-IP-Host | 0+ | 0 | + Login-IPv6-Host | 0+ | 0 | + Login-LAT-Service | 0-1 | 0 | + Login-LAT-Node | 0-1 | 0 | + Login-LAT-Group | 0-1 | 0 | + Login-LAT-Port | 0-1 | 0 | + Login-Service | 0-1 | 0 | + Login-TCP-Port | 0-1 | 0 | + ---------------------------------------|-----+-----+ + + + + +Calhoun, et al. Standards Track [Page 76] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + +-----------+ + | Command | + |-----+-----+ + Attribute Name | ACR | ACA | + ---------------------------------------|-----+-----+ + NAS-Identifier | 0-1 | 0-1 | + NAS-IP-Address | 0-1 | 0-1 | + NAS-IPv6-Address | 0-1 | 0-1 | + NAS-Port | 0-1 | 0-1 | + NAS-Port-Id | 0-1 | 0-1 | + NAS-Port-Type | 0-1 | 0-1 | + Origin-AAA-Protocol | 0-1 | 0-1 | + Origin-Host | 1 | 1 | + Origin-Realm | 1 | 1 | + Origin-State-Id | 0-1 | 0-1 | + Originating-Line-Info | 0-1 | 0 | + Proxy-Info | 0+ | 0+ | + QoS-Filter-Rule | 0+ | 0 | + Route-Record | 0+ | 0+ | + Result-Code | 0 | 1 | + Session-Id | 1 | 1 | + Service-Type | 0-1 | 0-1 | + Termination-Cause | 0-1 | 0-1 | + User-Name | 0-1 | 0-1 | + Vendor-Specific-Application-Id | 0-1 | 0-1 | + ---------------------------------------|-----+-----+ + +11. IANA Considerations + + This section provides guidance to the Internet Assigned Numbers + Authority (IANA) regarding registration of values related to the + Diameter protocol, in accordance with BCP 26 [IANAConsid]. + + This document defines values in the namespaces that have been created + and defined in the Diameter Base [BASE]. The IANA Considerations + section of that document details the assignment criteria. Values + assigned in this document, or by future IANA action, must be + coordinated within this shared namespace. + +11.1. Command Codes + + This specification assigns the value 265 from the Command Code + namespace defined in [BASE]. See sections 3.1 and 3.2 for the + assignment of the namespace in this specification. + + + + + + + +Calhoun, et al. Standards Track [Page 77] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +11.2. AVP Codes + + This specification assigns the values 363 - 366 and 400 - 408 from + the AVP Code namespace defined in [BASE]. See sections 4 and 5 for + the assignment of the namespace in this specification. Note that the + values 363 - 366 are jointly, but consistently, assigned in + [DiamMIP]. This document also creates one new namespace to be + managed by IANA, as described in section 11.5. + + This specification also specifies the use of AVPs in the 0 - 255 + range, which are defined in [RADIUSTypes]. These values are assigned + by the policy in RFC 2865 section 6 [RADIUS] and are amended by RFC + 3575 [RADIUSIANA]. + +11.3. Application Identifier + + This specification uses the value one (1) in the Application + Identifier namespace as assigned in [BASE]. See section 1.2 above + for more information. + +11.4. CHAP-Algorithm AVP Values + + As defined in section 5.5, the CHAP-Algorithm AVP (AVP Code 403) uses + the values of the "PPP AUTHENTICATION ALGORITHMS" namespace defined + in [PPPCHAP]. + +11.5. Accounting-Auth-Method AVP Values + + As defined in section 8.6, the Accounting-Auth-Method AVP (AVP Code + 406) defines the values 1 - 5. All remaining values are available + for assignment via IETF Consensus [IANA]. + +11.6. Origin-AAA-Protocol AVP Values + + As defined in section 9.3.6, the Origin-AAA-Protocol AVP (AVP Code + 408) defines the value 1. All remaining values are available for + assignment with a "Specification Required" policy [IANAConsid]. + +12. Security Considerations + + This document describes the extension of Diameter for the NAS + application. The security considerations of the Diameter protocol + itself have been discussed in [BASE]. Use of this application of + Diameter MUST take into consideration the security issues and + requirements of the Base protocol. + + + + + + +Calhoun, et al. Standards Track [Page 78] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + This document does not contain a security protocol but does discuss + how PPP authentication protocols can be carried within the Diameter + protocol. The PPP authentication protocols described are PAP and + CHAP. + + The use of PAP SHOULD be discouraged, as it exposes users' passwords + to possibly non-trusted entities. However, PAP is also frequently + used for use with One-Time Passwords, which do not expose a security + risk. + + This document also describes how CHAP can be carried within the + Diameter protocol, which is required for RADIUS backward + compatibility. The CHAP protocol, as used in a RADIUS environment, + facilitates authentication replay attacks. + + The use of the EAP authentication protocols described in [DiamEAP] + can offer better security, given a method suitable for the + circumstances. + +13. References + +13.1. Normative References + + [BASE] Calhoun, P., Loughney, J., Guttman, E., Zorn, G., and + J. Arkko, "Diameter Base Protocol", RFC 3588, + September 2003. + + [DiamTrans] Aboba, B. and J. Wood, "Authentication, Authorization + and Accounting (AAA) Transport Profile", RFC 3539, + June 2003. + + [RADIUS] Rigney, C., Willens, S., Rubens, A., and W. Simpson, + "Remote Authentication Dial In User Service (RADIUS)", + RFC 2865, June 2000. + + [RADIUSTypes] IANA, "RADIUS Types", URL: + <http://www.iana.org/assignments/radius-types> + + [RADIUSIPv6] Aboba, B., Zorn, G., and D. Mitton, "RADIUS and IPv6", + RFC 3162, August 2001. + + [IPv6Addr] Nerenberg, L., "IMAP4 Binary Content Extension", RFC + 3516, April 2003. + + [PPPCHAP] Simpson, W., "PPP Challenge Handshake Authentication + Protocol (CHAP)", RFC 1994, August 1996. + + + + + +Calhoun, et al. Standards Track [Page 79] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + [IANAConsid] Narten, T. and H. Alvestrand, "Guidelines for Writing + an IANA Considerations Section in RFCs", BCP 26, RFC + 2434, October 1998. + + [IANA] IANA Assigned Numbers Database, URL: + <http://www.iana.org/numbers.html> + + [Keywords] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [ANITypes] NANPA Number Resource Info, ANI Assignments, URL: + <http://www.nanpa.com/number_resource_info/ + ani_ii_assignments.html> + +13.2. Informative References + + [RADIUSAcct] Rigney, C., "RADIUS Accounting", RFC 2866, June 2000. + + [RADIUSExt] Rigney, C., Willats, W., and P. Calhoun, "RADIUS + Extensions", RFC 2869, June 2000. + + [RADTunnels] Zorn, G., Leifer, D., Rubens, A., Shriver, J., + Holdrege, M., and I. Goyret, "RADIUS Attributes for + Tunnel Protocol Support", RFC 2868, June 2000. + + [RADTunlAcct] Zorn, G., Aboba, B., and D. Mitton, "RADIUS Accounting + Modifications for Tunnel Protocol Support", RFC 2867, + June 2000. + + [RADDynAuth] Chiba, M., Dommety, G., Eklund, M., Mitton, D., and B. + Aboba, "Dynamic Authorization Extensions to Remote + Authentication Dial In User Service (RADIUS)", RFC + 3576, July 2003. + + [RADIUSIANA] Aboba, B., "IANA Considerations for RADIUS (Remote + Authentication Dial In User Service)", RFC 3575, July + 2003. + + [NASModel] Mitton, D. and M. Beadles, "Network Access Server + Requirements Next Generation (NASREQNG) NAS Model", + RFC 2881, July 2000. + + [NASCriteria] Beadles, M. and D. Mitton, "Criteria for Evaluating + Network Access Server Protocols", RFC 3169, September + 2001. + + + + + + +Calhoun, et al. Standards Track [Page 80] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + [AAACriteria] Aboba, B., Calhoun, P., Glass, S., Hiller, T., McCann, + P., Shiino, H., Zorn, G., Dommety, G., Perkins, C., + Patil, B., Mitton, D., Manning, S., Beadles, M., + Walsh, P., Chen, X., Sivalingham, S., Hameed, A., + Munson, M., Jacobs, S., Lim, B., Hirschman, B., Hsu, + R., Xu, Y., Campbell, E., Baba, S., and E. Jaques, + "Criteria for Evaluating AAA Protocols for Network + Access", RFC 2989, November 2000. + + [DiamEAP] Eronen, P., "Diameter EAP Application", Work in + Progress, May 2004. + + [DiamCMS] Calhoun, P., Bulley, W., and S. Farrell, "Diameter CMS + Security Application", Work in Progress, March 2002. + + [DiamMIP] Calhoun, P., Johansson, T., Perkins, C., Hiller, T., + and P. McCann "Diameter Mobile IPv4 Application", RFC + 4004, August 2005. + + [VSA] Mitton, D., "Diameter/RADIUS Vendor Specific AVP + Translation", Work in Progress, April 2005. + + [RAD802.1X] Congdon, P., Aboba, B., Smith, A., Zorn, G., and J. + Roese, "IEEE 802.1X Remote Authentication Dial In User + Service (RADIUS) Usage Guidelines", RFC 3580, + September 2003. + + [CDMA2000] 3GPP2 "P.S0001-B", Wireless IP Network Standard, + October 2002. + http://www.3gpp2.com/Public_html/specs/P.S0001- + B_v1.0.pdf + + [AppleTalk] Sidhu, Gursharan; Andrews, Richard F. & Oppenheimer, + Alan B. "Inside AppleTalk", Second Edition, Apple + Computer., 1990 + + [ARAP] Apple Remote Access Protocol (ARAP) Version 2.0 + External Reference Specification", Apple Computer, + September 1994, R0612LL/B + + [IPX] Novell, Inc., "NetWare System Technical Interface + Overview", June 1989, # 883-000780-001 + + [LAT] Local Area Transport (LAT) Specification V5.0, Digital + Equipment Corp., AA-NL26A-TE, June 1989 + + + + + + +Calhoun, et al. Standards Track [Page 81] + +RFC 4005 Diameter Network Access Server Application August 2005 + + + [DIFFSERV] Nichols, K., Blake, S., Baker, F., and D. Black, + "Definition of the Differentiated Services Field (DS + Field) in the IPv4 and IPv6 Headers", RFC 2474, + December 1998. + + [DIFFSERVAF] Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski, + "Assured Forwarding PHB Group", RFC 2597, June 1999. + + [DIFFSERVEF] Davie, B., Charny, A., Bennet, J.C., Benson, K., Le + Boudec, J., Courtney, W., Davari, S., Firoiu, V., and + D. Stiliadis, "An Expedited Forwarding PHB (Per-Hop + Behavior)", RFC 3246, March 2002. + + [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [ISOLatin] ISO 8859. International Standard -- Information + Processing -- 8-bit Single-Byte Coded Graphic + Character Sets -- Part 1: Latin Alphabet No. 1, ISO + 8859-1:1987. URL: + <http://www.iso.ch/cate/d16338.html> + + [PPP] Simpson, W., "The Point-to-Point Protocol (PPP)", STD + 51, RFC 1661, July 1994. + + [PAP] Lloyd, B. and W. Simpson, "PPP Authentication + Protocols", RFC 1334, October 1992. + + [L2TP] Townsley, W., Valencia, A., Rubens, A., Pall, G., + Zorn, G., and B. Palter, "Layer Two Tunneling Protocol + "L2TP"", RFC 2661, August 1999. + + [PPPMP] Sklower, K., Lloyd, B., McGregor, G., Carr, D., and T. + Coradetti, "The PPP Multilink Protocol (MP)", RFC + 1990, August 1996. + + [PPTP] Hamzeh, K., Pall, G., Verthein, W., Taarud, J., + Little, W., and G. Zorn, "Point-to-Point Tunneling + Protocol", RFC 2637, July 1999. + + [IEEE 802.11F] IEEE, "Trial-Use Recommended Practice for Multi-Vendor + Access Point Interoperability via an Inter-Access + Point Protocol Across Distribution Systems Supporting + IEEE 802.11 Operation", IEEE 802.11F-2003, June 2003. + + + + + + + +Calhoun, et al. Standards Track [Page 82] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +14. Acknowledgements + + The authors would like to thank Carl Rigney, Allan C. Rubens, William + Allen Simpson, and Steve Willens for their work on the original + RADIUS [RADIUS], from which many of the concepts in this + specification were derived. Thanks, also, to Carl Rigney for + [RADIUSAcct] and [RADIUSExt]; Ward Willats for [RADIUSExt]; Glen + Zorn, Bernard Aboba, and Dave Mitton for [RADTunlAcct] and + [RADIUSIPv6]; and Dory Leifer, John Shriver, Matt Holdrege, and + Ignacio Goyret for their work on [RADTunnels]. This document stole + text and concepts from both [RADTunnels] and [RADIUSExt]. Thanks go + to Carl Williams for providing IPv6-specific text. + + The authors would also like to acknowledge the following people for + their contributions in the development of the Diameter protocol: + Bernard Aboba, Jari Arkko, William Bulley, Kuntal Chowdhury, Daniel + C. Fox, Lol Grant, Nancy Greene, Jeff Hagg, Peter Heitman, Paul + Krumviede, Fergal Ladley, Ryan Moats, Victor Muslin, Kenneth Peirce, + Sumit Vakil, John R. Vollbrecht, and Jeff Weisberg. + + Finally, Pat Calhoun would like to thank Sun Microsystems, as most of + the effort put into this document was done while he was in their + employ. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 83] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +Authors' Addresses + + Pat Calhoun + Cisco Systems, Inc. + 170 West Tasman Drive + San Jose, CA 95134 + USA + + Phone: +1 408-853-5269 + EMail: [email protected] + + + Glen Zorn + Cisco Systems, Inc. + 500 108th Avenue N.E., Suite 500 + Bellevue, WA 98004 + USA + + Phone: 1 425-471-4861 + EMail: [email protected] + + + David Spence + 3259 Bluett Rd. + Ann Arbor, MI 48105 + USA + + Phone: +1 734 834 6481 + EMail: [email protected] + + + David Mitton + Circular Networks + 733 Turnpike St #154 + North Andover, MA 01845 + + EMail: [email protected] + + + + + + + + + + + + + + +Calhoun, et al. Standards Track [Page 84] + +RFC 4005 Diameter Network Access Server Application August 2005 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2005). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + +Calhoun, et al. Standards Track [Page 85] + diff --git a/lib/diameter/doc/standard/rfc4006.txt b/lib/diameter/doc/standard/rfc4006.txt new file mode 100644 index 0000000000..3f3e5e1d1b --- /dev/null +++ b/lib/diameter/doc/standard/rfc4006.txt @@ -0,0 +1,6387 @@ + + + + + + +Network Working Group H. Hakala +Request for Comments: 4006 L. Mattila +Category: Standards Track Ericsson + J-P. Koskinen + M. Stura + J. Loughney + Nokia + August 2005 + + + Diameter Credit-Control Application + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2005). + +Abstract + + This document specifies a Diameter application that can be used to + implement real-time credit-control for a variety of end user services + such as network access, Session Initiation Protocol (SIP) services, + messaging services, and download services. + +Table of Contents + + 1. Introduction................................................. 4 + 1.1. Requirements Language................................. 5 + 1.2. Terminology........................................... 5 + 1.3. Advertising Application Support....................... 7 + 2. Architecture Models.......................................... 7 + 3. Credit-Control Messages...................................... 9 + 3.1. Credit-Control-Request (CCR) Command.................. 9 + 3.2. Credit-Control-Answer (CCA) Command................... 11 + 4. Credit-Control Application Overview.......................... 11 + 4.1. Service-Specific Rating Input and Interoperability.... 13 + 5. Session Based Credit-Control................................. 15 + 5.1. General Principles.................................... 15 + 5.2. First Interrogation................................... 21 + 5.3. Intermediate Interrogation............................ 27 + 5.4. Final Interrogation................................... 29 + + + +Hakala, et al. Standards Track [Page 1] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + 5.5. Server-Initiated Credit Re-Authorization.............. 30 + 5.6. Graceful Service Termination.......................... 32 + 5.7. Failure Procedures.................................... 38 + 6. One Time Event............................................... 41 + 6.1. Service Price Enquiry................................. 42 + 6.2. Balance Check......................................... 42 + 6.3. Direct Debiting....................................... 43 + 6.4. Refund................................................ 44 + 6.5. Failure Procedure..................................... 44 + 7. Credit-Control Application State Machine..................... 46 + 8. Credit-Control AVPs.......................................... 55 + 8.1. CC-Correlation-Id AVP................................. 58 + 8.2. CC-Request-Number AVP................................. 58 + 8.3. CC-Request-Type AVP................................... 58 + 8.4. CC-Session-Failover AVP............................... 59 + 8.5. CC-Sub-Session-Id AVP................................. 59 + 8.6. Check-Balance-Result AVP.............................. 60 + 8.7. Cost-Information AVP.................................. 60 + 8.8. Unit-Value AVP........................................ 61 + 8.9. Exponent AVP.......................................... 61 + 8.10. Value-Digits AVP...................................... 61 + 8.11. Currency-Code AVP..................................... 62 + 8.12. Cost-Unit AVP......................................... 62 + 8.13. Credit-Control AVP.................................... 62 + 8.14. Credit-Control-Failure-Handling AVP................... 62 + 8.15. Direct-Debiting-Failure-Handling AVP.................. 63 + 8.16. Multiple-Services-Credit-Control AVP.................. 64 + 8.17. Granted-Service-Unit AVP.............................. 65 + 8.18. Requested-Service-Unit AVP............................ 66 + 8.19. Used-Service-Unit AVP................................. 66 + 8.20. Tariff-Time-Change AVP................................ 67 + 8.21. CC-Time AVP........................................... 67 + 8.22. CC-Money AVP.......................................... 67 + 8.23. CC-Total-Octets AVP................................... 68 + 8.24. CC-Input-Octets AVP................................... 68 + 8.25. CC-Output-Octets AVP.................................. 68 + 8.26. CC-Service-Specific-Units AVP......................... 68 + 8.27. Tariff-Change-Usage AVP............................... 68 + 8.28. Service-Identifier AVP................................ 69 + 8.29. Rating-Group AVP...................................... 69 + 8.30. G-S-U-Pool-Reference AVP.............................. 69 + 8.31. G-S-U-Pool-Identifier AVP............................. 70 + 8.32. CC-Unit-Type AVP...................................... 70 + 8.33. Validity-Time AVP..................................... 70 + 8.34. Final-Unit-Indication AVP............................. 71 + 8.35. Final-Unit-Action AVP................................. 72 + 8.36. Restriction-Filter-Rule AVP........................... 72 + 8.37. Redirect-Server AVP................................... 73 + + + +Hakala, et al. Standards Track [Page 2] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + 8.38. Redirect-Address-Type AVP............................. 73 + 8.39. Redirect-Server-Address AVP........................... 74 + 8.40. Multiple-Services-Indicator AVP....................... 74 + 8.41. Requested-Action AVP.................................. 74 + 8.42. Service-Context-Id AVP................................ 75 + 8.43. Service-Parameter-Info AVP............................ 76 + 8.44. Service-Parameter-Type AVP............................ 76 + 8.45. Service-Parameter-Value AVP........................... 77 + 8.46. Subscription-Id AVP................................... 77 + 8.47. Subscription-Id-Type AVP.............................. 77 + 8.48. Subscription-Id-Data AVP.............................. 78 + 8.49. User-Equipment-Info AVP............................... 78 + 8.50. User-Equipment-Info-Type AVP.......................... 78 + 8.50. User-Equipment-Info-Value AVP......................... 79 + 9. Result Code AVP Values....................................... 79 + 9.1. Transient Failures.................................... 79 + 9.2. Permanent Failures.................................... 80 + 10. AVP Occurrence Table......................................... 80 + 10.1. Credit-Control AVP Table.............................. 81 + 10.2. Re-Auth-Request/Answer AVP Table...................... 82 + 11. RADIUS/Diameter Credit-Control Interworking Model............ 82 + 12. IANA Considerations.......................................... 85 + 12.1. Application Identifier................................ 86 + 12.2. Command Codes......................................... 86 + 12.3. AVP Codes............................................. 86 + 12.4. Result-Code AVP Values................................ 86 + 12.5. CC-Request-Type AVP................................... 86 + 12.6. CC-Session-Failover AVP............................... 86 + 12.7. CC-Unit-Type AVP...................................... 87 + 12.8. Check-Balance-Result AVP.............................. 87 + 12.9. Credit-Control AVP.................................... 87 + 12.10. Credit-Control-Failure-Handling AVP................... 87 + 12.11. Direct-Debiting-Failure-Handling AVP.................. 87 + 12.12. Final-Unit-Action AVP................................. 87 + 12.13. Multiple-Services-Indicator AVP....................... 87 + 12.14. Redirect-Address-Type AVP............................. 88 + 12.15. Requested-Action AVP.................................. 88 + 12.16. Subscription-Id-Type AVP.............................. 88 + 12.17. Tariff-Change-Usage AVP............................... 88 + 12.18. User-Equipment-Info-Type AVP.......................... 88 + 13. Credit-Control Application Related Parameters................ 88 + 14. Security Considerations...................................... 89 + 14.1. Direct Connection with Redirects...................... 90 + 15. References................................................... 91 + 15.1. Normative References.................................. 91 + 15.2. Informative References................................ 92 + 16. Acknowledgements............................................. 93 + Appendix A Credit-Control Sequences.............................. 94 + + + +Hakala, et al. Standards Track [Page 3] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + A.1. Flow I................................................ 94 + A.2. Flow II............................................... 96 + A.3. Flow III.............................................. 98 + A.4. Flow IV............................................... 99 + A.5. Flow V................................................ 100 + A.6. Flow VI............................................... 102 + A.7. Flow VII.............................................. 103 + A.8. Flow VIII............................................. 105 + A.9. Flow IX............................................... 107 + Authors' Addresses............................................... 112 + Full Copyright Statement......................................... 114 + +1. Introduction + + This document specifies a Diameter application that can be used to + implement real-time credit-control for a variety of end user services + such as network access, Session Initiation Protocol (SIP) services, + messaging services, and download services. It provides a general + solution to real-time cost and credit-control. + + The prepaid model has been shown to be very successful, for instance, + in GSM networks, where network operators offering prepaid services + have experienced a substantial growth of their customer base and + revenues. Prepaid services are now cropping up in many other + wireless and wire line based networks. + + In next generation wireless networks, additional functionality is + required beyond that specified in the Diameter base protocol. For + example, the 3GPP Charging and Billing requirements [3GPPCHARG] state + that an application must be able to rate service information in + real-time. In addition, it is necessary to check that the end user's + account provides coverage for the requested service prior to + initiation of that service. When an account is exhausted or expired, + the user must be denied the ability to compile additional chargeable + events. + + A mechanism has to be provided to allow the user to be informed of + the charges to be levied for a requested service. In addition, there + are services such as gaming and advertising that may credit as well + as debit a user account. + + The other Diameter applications provide service specific + authorization, and they do not provide credit authorization for + prepaid users. The credit authorization shall be generic and + applicable to all the service environments required to support + prepaid services. + + + + + +Hakala, et al. Standards Track [Page 4] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + To fulfill these requirements, it is necessary to facilitate credit- + control communication between the network element providing the + service (e.g., Network Access Server, SIP Proxy, and Application + Server) and a credit-control server. + + The scope of this specification is the credit authorization. Service + specific authorization and authentication is out of the scope. + +1.1. Requirements Language + + In this document, the key words "MAY", "MUST, "MUST NOT", "OPTIONAL", + "RECOMMENDED", "SHOULD", and "SHOULD NOT", are to be interpreted as + described in [KEYWORDS]. + +1.2. Terminology + + AAA + + Authentication, Authorization, and Accounting + + AA answer + + AA answer generically refers to a service specific authorization and + authentication answer. AA answer commands are defined in service + specific authorization applications, e.g., [NASREQ] and [DIAMMIP]. + + AA request + + AA request generically refers to a service specific authorization and + authentication request. AA request commands are defined in service + specific authorization applications e.g., [NASREQ] and [DIAMMIP]. + + Credit-control + + Credit-control is a mechanism that directly interacts in real-time + with an account and controls or monitors the charges related to the + service usage. Credit-control is a process of checking whether + credit is available, credit-reservation, deduction of credit from the + end user account when service is completed and refunding of reserved + credit that is not used. + + Diameter Credit-control Server + + A Diameter credit-control server acts as a prepaid server, performing + real-time rating and credit-control. It is located in the home + domain and is accessed by service elements or Diameter AAA servers in + + + + + +Hakala, et al. Standards Track [Page 5] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + real-time for purpose of price determination and credit-control + before the service event is delivered to the end-user. It may also + interact with business support systems. + + Diameter Credit-control Client + + A Diameter credit-control client is an entity that interacts with a + credit-control server. It monitors the usage of the granted quota + according to instructions returned by credit-control server. + + Interrogation + + The Diameter credit-control client uses interrogation to initiate a + session based credit-control process. During the credit-control + process, it is used to report the used quota and request a new one. + An interrogation maps to a request/answer transaction. + + One-time event + + Basically, a request/answer transaction of type event. + + Rating + + The act of determining the cost of the service event. + + Service + + A type of task performed by a service element for an end user. + + Service Element + + A network element that provides a service to the end users. The + Service Element may include the Diameter credit-control client, or + another entity (e.g., RADIUS AAA server) that can act as a Credit- + control client on behalf of the Service Element. In the latter case, + the interface between the Service Element and the Diameter credit- + control client is outside the scope of this specification. Examples + of the Service Elements include Network Access Server (NAS), SIP + Proxy, and Application Servers such as messaging server, content + server, and gaming server. + + Service Event + + An event relating to a service provided to the end user. + + + + + + + +Hakala, et al. Standards Track [Page 6] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Session based credit-control + + A credit-control process that makes use of several interrogations: + the first, a possible intermediate, and the final. The first + interrogation is used to reserve money from the user's account and to + initiate the process. The intermediate interrogations may be needed + to request new quota while the service is being rendered. The final + interrogation is used to exit the process. The credit-control server + is required to maintain session state for session-based credit- + control. + +1.3. Advertising Application Support + + Diameter nodes conforming to this specification MUST advertise + support by including the value of 4 in the Auth-Application-Id of the + Capabilities-Exchange-Request and Capabilities-Exchange-Answer + command [DIAMBASE]. + +2. Architecture Models + + The current accounting models specified in the Radius Accounting + [RFC2866] and Diameter base [DIAMBASE] are not sufficient for real- + time credit-control, where credit-worthiness is to be determined + prior to service initiation. Also, the existing Diameter + authorization applications, [NASREQ] and [DIAMMIP], only provide + service authorization, but do not provide credit authorization for + prepaid users. In order to support real-time credit-control, a new + type of server is needed in the AAA infrastructure: Diameter credit- + control server. The Diameter credit-control server is the entity + responsible for credit authorization for prepaid subscribers. + + A service element may authenticate and authorize the end user with + the AAA server by using AAA protocols; e.g., RADIUS or a Diameter + base protocol with a possible Diameter application. + + Accounting protocols such as RADIUS accounting and the Diameter base + accounting protocol can be used to provide accounting data to the + accounting server after service is initiated, and to provide possible + interim reports until service completion. However, for real-time + credit-control, these authorization and accounting models are not + sufficient. + + When real-time credit-control is required, the credit-control client + contacts the credit-control server with information about a possible + service event. The credit-control process is performed to determine + potential charges and to verify whether the end user's account + balance is sufficient to cover the cost of the service being + rendered. + + + +Hakala, et al. Standards Track [Page 7] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Figure 1 illustrates the typical credit-control architecture, which + consists of a Service Element with an embedded Diameter credit- + control client, a Diameter credit-control server, and an AAA server. + A Business Support System is usually deployed; it includes at least + the billing functionality. The credit-control server and AAA server + in this architecture model are logical entities. The real + configuration can combine them into a single host. The credit- + control protocol is the Diameter base protocol with the Diameter + credit-control application. + + When an end user requests services such as SIP or messaging, the + request is typically forwarded to a service element (e.g., SIP Proxy) + in the user's home domain. In some cases it might be possible that + the service element in the visited domain can offer services to the + end user; however, a commercial agreement must exist between the + visited domain and the home domain. Network access is an example of + a service offered in the visited domain where the NAS, through an AAA + infrastructure, authenticates and authorizes the user with the user's + home network. + + Service Element AAA and CC + +----------+ +---------+ Protocols+-----------+ +--------+ + | End |<---->|+-------+|<------------>| AAA | |Business| + | User | +->|| CC || | Server |->|Support | + | | | || Client||<-----+ | | |System | + +----------+ | |+-------+| | +-----------+ | | + | +---------+ | ^ +--------+ + +----------+ | | CC Protocol | ^ + | End |<--+ | +-----v----+ | + | User | +------>|Credit- | | + +----------+ Credit-Control |Control |--------+ + Protocol |Server | + +----------+ + + Figure 1: Typical credit-control architecture + + There can be multiple credit-control servers in the system for + redundancy and load balancing. The system can also contain separate + rating server(s), and accounts can be located in a centralized + database. To ensure that the end user's account is not debited or + credited multiple times for the same service event, only one place in + the credit-control system should perform duplicate detection. System + internal interfaces can exist to relay messages between servers and + an account manager. However, the detailed architecture of the + credit-control system and its interfaces are implementation specific + and are out of scope of this specification. + + + + + +Hakala, et al. Standards Track [Page 8] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Protocol transparent Diameter relays can exist between the credit- + control client and credit-control server. Also, Diameter Redirect + agents that refer credit-control clients to credit-control servers + and allow them to communicate directly can exist. These agents + transparently support the Diameter credit-control application. The + different roles of Diameter Agents are defined in Diameter base + [DIAMBASE], section 2.8. + + If Diameter credit-control proxies exist between the credit-control + client and the credit-control server, they MUST advertise the + Diameter credit-control application support. + +3. Credit-Control Messages + + This section defines new Diameter message Command-Code values that + MUST be supported by all Diameter implementations that conform to + this specification. The Command Codes are as follows: + + Command-Name Abbrev. Code Reference + ----------------------------------------------------------- + Credit-Control-Request CCR 272 3.1 + Credit-Control-Answer CCA 272 3.2 + + Diameter Base [DIAMBASE] defines in the section 3.2 the Command Code + ABNF specification. These formats are observed in Credit-Control + messages. + +3.1. Credit-Control-Request (CCR) Command + + The Credit-Control-Request message (CCR) is indicated by the + command-code field being set to 272 and the 'R' bit being set in the + Command Flags field. It is used between the Diameter credit-control + client and the credit-control server to request credit authorization + for a given service. + + The Auth-Application-Id MUST be set to the value 4, indicating the + Diameter credit-control application. + + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 9] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Message Format + + <Credit-Control-Request> ::= < Diameter Header: 272, REQ, PXY > + < Session-Id > + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Auth-Application-Id } + { Service-Context-Id } + { CC-Request-Type } + { CC-Request-Number } + [ Destination-Host ] + [ User-Name ] + [ CC-Sub-Session-Id ] + [ Acct-Multi-Session-Id ] + [ Origin-State-Id ] + [ Event-Timestamp ] + *[ Subscription-Id ] + [ Service-Identifier ] + [ Termination-Cause ] + [ Requested-Service-Unit ] + [ Requested-Action ] + *[ Used-Service-Unit ] + [ Multiple-Services-Indicator ] + *[ Multiple-Services-Credit-Control ] + *[ Service-Parameter-Info ] + [ CC-Correlation-Id ] + [ User-Equipment-Info ] + *[ Proxy-Info ] + *[ Route-Record ] + *[ AVP ] + + + + + + + + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 10] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +3.2. Credit-Control-Answer (CCA) Command + + The Credit-Control-Answer message (CCA) is indicated by the command- + code field being set to 272 and the 'R' bit being cleared in the + Command Flags field. It is used between the credit-control server + and the Diameter credit-control client to acknowledge a Credit- + Control-Request command. + + Message Format + + <Credit-Control-Answer> ::= < Diameter Header: 272, PXY > + < Session-Id > + { Result-Code } + { Origin-Host } + { Origin-Realm } + { Auth-Application-Id } + { CC-Request-Type } + { CC-Request-Number } + [ User-Name ] + [ CC-Session-Failover ] + [ CC-Sub-Session-Id ] + [ Acct-Multi-Session-Id ] + [ Origin-State-Id ] + [ Event-Timestamp ] + [ Granted-Service-Unit ] + *[ Multiple-Services-Credit-Control ] + [ Cost-Information] + [ Final-Unit-Indication ] + [ Check-Balance-Result ] + [ Credit-Control-Failure-Handling ] + [ Direct-Debiting-Failure-Handling ] + [ Validity-Time] + *[ Redirect-Host] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + *[ Proxy-Info ] + *[ Route-Record ] + *[ Failed-AVP ] + *[ AVP ] + +4. Credit-Control Application Overview + + The credit authorization process takes place before and during + service delivery to the end user and generally requires the user's + authentication and authorization before any request is sent to the + credit-control server. The credit-control application defined in + this specification supports two different credit authorization + models: credit authorization with money reservation and credit + + + +Hakala, et al. Standards Track [Page 11] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + authorization with direct debiting. In both models, the credit- + control client requests credit authorization from the credit-control + server prior to allowing any service to be delivered to the end user. + + In the first model, the credit-control server rates the request, + reserves a suitable amount of money from the user's account, and + returns the corresponding amount of credit resources. Note that + credit resources may not imply actual monetary credit; credit + resources may be granted to the credit control client in the form of + units (e.g., data volume or time) to be metered. + + Upon receipt of a successful credit authorization answer with a + certain amount of credit resources, the credit-control client allows + service delivery to the end user and starts monitoring the usage of + the granted resources. When the credit resources granted to the user + have been consumed or the service has been successfully delivered or + terminated, the credit-control client reports back to the server the + used amount. The credit-control server deducts the used amount from + the end user's account; it may perform rating and make a new credit + reservation if the service delivery is continuing. This process is + accomplished with session based credit-control that includes the + first interrogation, possible intermediate interrogations, and the + final interrogation. For session based credit-control, both the + credit control client and the credit-control server are required to + maintain credit-control session state. Session based credit-control + is described in more detail, with more variations, in section 5. + + In contrast, credit authorization with direct debiting is a single + transaction process wherein the credit-control server directly + deducts a suitable amount of money from the user's account as soon as + the credit authorization request is received. Upon receipt of a + successful credit authorization answer, the credit-control client + allows service delivery to the end user. This process is + accomplished with the one-time event. Session state is not + maintained. + + In a multi-service environment, an end user can issue an additional + service request (e.g., data service) during an ongoing service (e.g., + voice call) toward the same account. Alternatively, during an active + multimedia session, an additional media type is added to the session, + causing a new simultaneous request toward same account. + Consequently, this needs to be considered when credit resources are + granted to the services. + + The credit-control application also supports operations such as + service price enquiry, user's balance check, and refund of credit on + the user's account. These operations are accomplished with the one- + time event. Session state is not maintained. + + + +Hakala, et al. Standards Track [Page 12] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + A flexible credit-control application specific failure handling is + defined in which the home service provider can model the credit- + control client behavior according to its own credit risk management + policy. + + The Credit-Control-Failure-Handling AVP and the Direct-Debiting- + Failure-Handling AVP are defined to determine what is done if the + sending of credit-control messages to the credit-control server has + been temporarily prevented. The usage of the Credit-Control- + Failure-Handling AVP and the Direct-Debiting-Failure-Handling AVP + allows flexibility, as failure handling for the credit-control + session and one time event direct debiting may be different. + +4.1. Service-Specific Rating Input and Interoperability + + The Diameter credit-control application defines the framework for + credit-control; it provides generic credit-control mechanisms + supporting multiple service applications. The credit-control + application, therefore, does not define AVPs that could be used as + input in the rating process. Listing the possible services that + could use this Diameter application is out of scope for this generic + mechanism. + + It is reasonable to expect that a service level agreement will exist + between providers of the credit-control client and the credit-control + server covering the charging, services offered, roaming agreements, + agreed rating input (i.e., AVPs), and so on. + + Therefore, it is assumed that a Diameter credit-control server will + provide service only for Diameter credit-control clients that have + agreed beforehand as to the content of credit-control messages. + Naturally, it is possible that any arbitrary Diameter credit-control + client can interchange credit-control messages with any Diameter + credit-control server, but with a higher likelihood that unsupported + services/AVPs could be present in the credit-control message, causing + the server to reject the request with an appropriate result-code. + +4.1.1. Specifying Rating Input AVPs + + There are two ways to provide rating input to the credit-control + server: either by using AVPs or by including them in the Service- + Parameter-Info AVP. The general principles for sending rating + parameters are as follows: + + 1a. The service SHOULD re-use existing AVPs if it can use AVPs + defined in existing Diameter applications (e.g., NASREQ for network + access services). Re-use of existing AVPs is strongly recommended in + [DIAMBASE]. + + + +Hakala, et al. Standards Track [Page 13] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + For AVPs of type Enumerated, the service may require a new value to + be defined. Allocation of new AVP values is done as specified in + [DIAMBASE], section 1.2. + + 1b. New AVPs can be defined if the existing AVPs do not provide + sufficient rating information. In this case, the procedures defined + in [DIAMBASE] for creating new AVPs MUST be followed. + + 1c. For services specific only to one vendor's implementation, a + Vendor-Specific AVP code for Private use can be used. Where a + Vendor-Specific AVP is implemented by more than one vendor, + allocation of global AVPs is encouraged instead; refer to [DIAMBASE]. + + 2. The Service-Parameter-Info AVP MAY be used as a container to pass + legacy rating information in its original encoded form (e.g., ASN.1 + BER). This method can be used to avoid unnecessary conversions from + an existing data format to an AVP format. In this case, the rating + input is embedded in the Service-Parameter-Info AVP as defined in + section 8.43. + + New service applications SHOULD favor the use of explicitly defined + AVPs as described in items 1a and 1b, to simplify interoperability. + +4.1.2. Service-Specific Documentation + + The service specific rating input AVPs, the contents of the Service- + Parameter-Info AVP or Service-Context-Id AVP (defined in section + 8.42) are not within the scope of this document. To facilitate + interoperability, it is RECOMMENDED that the rating input and the + values of the Service-Context-Id be coordinated via an informational + RFC or other permanent and readily available reference. The + specification of another cooperative standardization body (e.g., + 3GPP, OMA, and 3GPP2) SHOULD be used. However, private services may + be deployed that are subject to agreements between providers of the + credit-control server and client. In this case, vendor specific AVPs + can be used. + + This specification, together with the above service specific + documents, governs the credit-control message. Service specific + documents define which existing AVPs or new AVPs are used as input to + the rating process (i.e., those that do not define new credit-control + applications), and thus have to be included in the Credit-Control- + Request command by a Diameter credit-control client supporting a + given service as *[AVP]. Should Service-Parameter-Info be used, then + the service specific document MUST specify the exact content of this + grouped AVP. + + + + + +Hakala, et al. Standards Track [Page 14] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The Service-Context-Id AVP MUST be included at the command level of a + Credit-Control Request to identify the service specific document that + applies to the request. The specific service or rating group the + request relates to is uniquely identified by the combination of + Service-Context-Id and Service-Identifier or Rating-Group. + +4.1.3. Handling of Unsupported/Incorrect Rating Input + + Diameter credit-control implementations are required to support the + Mandatory rating AVPs defined in service specific documentation of + the services they support, according to the 'M' bit rules in + [DIAMBASE]. + + If a rating input required for the rating process is incorrect in the + Credit-control request, or if the credit-control server does not + support the requested service context (identified by the Service- + Context-Id AVP at command level), the Credit-control answer MUST + contain the error code DIAMETER_RATING_FAILED. A CCA message with + this error MUST contain one or more Failed-AVP AVPs containing the + missing and/or unsupported AVPs that caused the failure. A Diameter + credit-control client that receives the error code + DIAMETER_RATING_FAILED in response to a request MUST NOT send similar + requests in the future. + +4.1.4. RADIUS Vendor-Specific Rating Attributes + + When service specific documents include RADIUS vendor specific + attributes that could be used as input in the rating process, the + rules described in [NASREQ] for formatting the Diameter AVP MUST be + followed. + + For example, if the AVP code used is the vendor attribute type code, + the Vendor-Specific flag MUST be set to 1 and the Vendor-ID MUST be + set to the IANA Vendor identification value. The Diameter AVP data + field contains only the attribute value of the RADIUS attribute. + +5. Session Based Credit-Control + +5.1. General Principles + + For a session-based credit-control, several interrogations are + needed: the first, intermediate (optional) and the final + interrogations. This is illustrated in Figures 2 and 3. + + If the credit-control client performs credit-reservation before + granting service to the end user, it MUST use several interrogations + toward the credit-control server (i.e., session based credit- + + + + +Hakala, et al. Standards Track [Page 15] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + control). In this case, the credit-control server MUST maintain the + credit-control session state. + + Each credit-control session MUST have a globally unique Session-Id as + defined in [DIAMBASE], which MUST NOT be changed during the lifetime + of a credit-control session. + + Certain applications require multiple credit-control sub-sessions. + These applications would send messages with a constant Session-Id + AVP, but with a different CC-Sub-Session-Id AVP. If several credit + sub-sessions will be used, all sub-sessions MUST be closed separately + before the main session is closed so that units per sub-session may + be reported. The absence of this AVP implies that no sub-sessions + are in use. + + Note that the service element might send a service specific re- + authorization message to the AAA server due to expiration of the + authorization-lifetime during an ongoing credit-control session. + However, the service specific re-authorization does not influence the + credit authorization that is ongoing between the credit-control + client and credit-control server, as credit authorization is + controlled by the burning rate of the granted quota. + + If service specific re-authorization fails, the user will be + disconnected, and the credit-control client MUST send a final + interrogation to the credit-control server. + + The Diameter credit-control server may seek to control the validity + time of the granted quota and/or the production of intermediate + interrogations. Thus, it MAY include the Validity-Time AVP in the + answer message to the credit-control client. Upon expiration of the + Validity-Time, the credit-control client MUST generate a credit- + control update request and report the used quota to the credit- + control server. It is up to the credit-control server to determine + the value of the Validity-Time to be used for consumption of the + granted service units. If the Validity-Time is used, its value + SHOULD be given as input to set the session supervision timer Tcc + (the session supervision timer MAY be set to two times the value of + the Validity-Time, as defined in section 13). Since credit-control + update requests are also produced at the expiry of granted service + units and/or for mid-session service events, the omission of + Validity-Time does not mean that intermediate interrogation for the + purpose of credit-control is not performed. + + + + + + + + +Hakala, et al. Standards Track [Page 16] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +5.1.1. Basic Tariff-Time Change Support + + The Diameter credit-control server and client MAY optionally support + a tariff change mechanism. The Diameter credit-control server may + include a Tariff-Time-Change AVP in the answer message. Note that + the granted units should be allocated based on the worst-case + scenario in case of forthcoming tariff change, so that the overall + reported used units would never exceed the credit reservation. + + When the Diameter credit-control client reports the used units and a + tariff change has occurred during the reporting period, the Diameter + credit-control client MUST separately itemize the units used before + and after the tariff change. If the client is unable to distinguish + whether units straddling the tariff change were used before or after + the tariff change, the credit-control client MUST itemize those units + in a third category. + + If a client does not support the tariff change mechanism and it + receives a CCA message carrying the Tariff-Time-Change AVP, it MUST + terminate the credit-control session, giving a reason of + DIAMETER_BAD_ANSWER in the Termination-Cause AVP. + + For time based services, the quota is continuously consumed at the + regular rate of 60 seconds per minute. At the time when credit + resources are allocated, the server already knows how many units will + be consumed before the tariff time change and how many units will be + consumed afterward. Similarly, the server can determine the units + consumed at the before rate and the units consumed at the rate + afterward in the event that the end-user closes the session before + the consumption of the allotted quota. There is no need for + additional traffic between client and server in the case of tariff + time changes for continuous time based service. Therefore, the + tariff change mechanism is not used for such services. For time- + based services in which the quota is NOT continuously consumed at a + regular rate, the tariff change mechanism described for volume and + event units MAY be used. + +5.1.2. Credit-Control for Multiple Services within a (sub-)Session + + When multiple services are used within the same user session and each + service or group of services is subject to different cost, it is + necessary to perform credit-control for each service independently. + Making use of credit-control sub-sessions to achieve independent + credit-control will result in increased signaling load and usage of + resources in both the credit-control client and the credit-control + server. For instance, during one network access session the end user + may use several http-services subject to different access cost. The + network access specific attributes such as the quality of service + + + +Hakala, et al. Standards Track [Page 17] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + (QoS) are common to all the services carried within the access + bearer, but the cost of the bearer may vary depending on its content. + + To support these scenarios optimally, the credit-control application + enables independent credit-control of multiple services in a single + credit-control (sub-)session. This is achieved by including the + optional Multiple-Services-Credit-Control AVP in Credit-Control- + Request/Answer messages. It is possible to request and allocate + resources as a credit pool shared between multiple services. The + services can be grouped into rating groups in order to achieve even + further aggregation of credit allocation. It is also possible to + request and allocate quotas on a per service basis. Where quotas are + allocated to a pool by means of the Multiple-Services-Credit-Control + AVP, the quotas remain independent objects that can be re-authorized + independently at any time. Quotas can also be given independent + result codes, validity times, and Final-Unit-Indications. + + A Rating-Group gathers a set of services, identified by a Service- + Identifier, and subject to the same cost and rating type (e.g., + $0.1/minute). It is assumed that the service element is provided + with Rating-Groups, Service-Identifiers, and their associated + parameters that define what has to be metered by means outside the + scope of this specification. (Examples of parameters associated to + Service-Identifiers are IP 5-tuple and HTTP URL.) Service-Identifiers + enable authorization on a per-service based credit as well as + itemized reporting of service usage. It is up to the credit-control + server whether to authorize credit for one or more services or for + the whole rating-group. However, the client SHOULD always report + used units at the finest supported level of granularity. Where quota + is allocated to a rating-group, all the services belonging to that + group draw from the allotted quota. The following is a graphical + representation of the relationship between service-identifiers, + rating-groups, credit pools, and credit-control (sub-)session. + + DCC (Sub-)Session + | + +------------+-----------+-------------+--------------- + + | | | | | + Service-Id a Service-Id b Service-Id c Service-Id d.....Service-Id z + \ / \ / / + \ / \ / / + \ / Rating-Group 1.......Rating-Group n + \ / | | + Quota ---------------Quota Quota + | / | + | / | + Credit-Pool Credit-Pool + + + + +Hakala, et al. Standards Track [Page 18] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + If independent credit-control of multiple services is used, the + validity-time and final-unit-indication SHOULD be present either in + the Multiple-Services-Credit-Control AVP(s) or at command level as + single AVPs. However, the Result-Code AVP MAY be present both on the + command level and within the Multiple-Services-Credit-Control AVP. + If the Result-Code on the command level indicates a value other than + SUCCESS, then the Result-Code on command level takes precedence over + any included in the Multiple-Services-Credit-Control AVP. + + The credit-control client MUST indicate support for independent + credit-control of multiple services within a (sub-)session by + including the Multiple-Services-Indicator AVP in the first + interrogation. A credit-control server not supporting this feature + MUST treat the Multiple-Services-Indicator AVP and any received + Multiple-Services-Credit-Control AVPs as invalid AVPs. + + If the client indicated support for independent credit-control of + multiple services, a credit-control server that wishes to use the + feature MUST return the granted units within the Multiple-Services- + Credit-Control AVP associated to the corresponding service-identifier + and/or rating-group. + + To avoid a situation where several parallel (and typically also + small) credit reservations must be made on the same account (i.e., + credit fragmentation), and also to avoid unnecessary load on the + credit-control server, it is possible to provide service units as a + pool that applies to multiple services or rating groups. This is + achieved by providing the service units in the form of a quota for a + particular service or rating group in the Multiple-Services-Credit- + Control AVP, and also by including a reference to a credit pool for + that unit type. + + The reference includes a multiplier derived from the rating + parameter, which translates from service units of a specific type to + the abstract service units in the pool. For instance, if the rating + parameter for service 1 is $1/MB and the rating parameter for service + 2 is $0.5/MB, the multipliers could be 10 and 5 for services 1 and 2, + respectively. + + If S is the total service units within the pool, M1, M2, ..., Mn are + the multipliers provided for services 1, 2, ..., n, and C1, C2, ..., + Cn are the used resources within the session, then the pool credit is + exhausted and re-authorization MUST be sought when: + + C1*M1 + C2*M2 + ... + Cn*Mn >= S + + + + + + +Hakala, et al. Standards Track [Page 19] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The total credit in the pool, S, is calculated from the quotas, which + are currently allocated to the pool as follows: + + S = Q1*M1 + Q2*M2 + ... + Qn*Mn + + If services or rating groups are added to or removed from the pool, + then the total credit is adjusted appropriately. Note that when the + total credit is adjusted because services or rating groups are + removed from the pool, the value that need to be removed is the + consumed one (i.e., Cx*Mx). + + Re-authorizations for an individual service or rating group may be + sought at any time; for example, if a 'non-pooled' quota is used up + or the Validity-Time expires. + + Where multiple G-S-U-Pool-Reference AVPs (section 8.30) with the same + G-S-U-Pool-Identifier are provided within a Multiple-Services- + Credit-Control AVP (section 8.16) along with the Granted-Service-Unit + AVP, then these MUST have different CC-Unit-Type values, and they all + draw from the credit pool separately. For instance, if one + multiplier for time (M1t) and one multiplier for volume (M1v) are + given, then the used resources from the pool is the sum C1t*M1t + + C1v*M1v, where C1t is the time unit and C1v is the volume unit. + + Where service units are provided within a Multiple-Services-Credit- + Control AVP without a corresponding G-S-U-Pool-Reference AVP, then + these are handled independently from any credit pool and from any + other services or rating groups within the session. + + The credit pool concept is an optimal tool to avoid the over- + reservation effect of the basic single quota tariff time change + mechanism (the mechanism described in section 5.1.1). Therefore, + Diameter credit-control clients and servers implementing the + independent credit-control of multiple services SHOULD leverage the + credit pool concept when supporting the tariff time change. The + Diameter credit-control server SHOULD include both the Tariff-Time- + Change and Tariff-Change-Usage AVPs in two quota allocations in the + answer message (i.e., two instances of the Multiple-Services-Credit- + Control AVP). One of the granted units is allocated to be used + before the potential tariff change, while the second granted units + are for use after a tariff change. Both granted unit quotas MUST + contain the same Service-Identifier and/or Rating-Group. This dual + quota mechanism ensures that the overall reported used units would + never exceed the credit reservation. The Diameter credit-control + client reports both the used units before and after the tariff change + in a single instance of the Multiple-Services-Credit-Control AVP. + + + + + +Hakala, et al. Standards Track [Page 20] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The failure handling for credit-control sessions is defined in + section 5.7 and reflected in the basic credit-control state machine + in section 7. Credit-control clients and servers implementing the + independent credit-control of multiple services in a (sub-)session + functionality MUST ensure failure handling and general behavior fully + consistent with the above mentioned sections, while maintaining the + ability to handle parallel ongoing credit re-authorization within a + (sub-)session. Therefore, it is RECOMMENDED that Diameter credit- + control clients maintain a PendingU message queue and restart the Tx + timer (section 13) every time a CCR message with the value + UPDATE_REQUEST is sent while they are in PendingU state. When + answers to all pending messages are received, the state machine moves + to OPEN state, and Tx is stopped. Naturally, the action performed + when a problem for the session is detected according to section 5.7 + affects all the ongoing services (e.g., failover to a backup server + if possible affect all the CCR messages with the value UPDATE_REQUEST + in the PendingU queue). + + Since the client may send CCR messages with the value UPDATE_REQUEST + while in PendingU (i.e., without waiting for an answer to ongoing + credit re-authorization), the time space between these requests may + be very short, and the server may not have received the previous + request(s) yet. Therefore, in this situation the server may receive + out of sequence requests and SHOULD NOT consider this an error + condition. A proper answer is to be returned to each of those + requests. + +5.2. First Interrogation + + When session based credit-control is required (e.g., the + authentication server indicated a prepaid user), the first + interrogation MUST be sent before the Diameter credit-control client + allows any service event to the end user. The CC-Request-Type is set + to the value INITIAL_REQUEST in the request message. + + If the Diameter credit-control client knows the cost of the service + event (e.g., a content server delivering ringing tones may know their + cost) the monetary amount to be charged is included in the + Requested-Service-Unit AVP. If the Diameter credit-control client + does not know the cost of the service event, the Requested-Service- + Unit AVP MAY contain the number of requested service events. Where + the Multiple-Services-Credit-Control AVP is used, it MUST contain the + Requested-Service-Unit AVP to indicate that the quota for the + associated service/rating-group is requested. In the case of + multiple services, the Service-Identifier AVP or the Rating-Group AVP + within the Multiple-Services-Credit-Control AVP always indicates the + service concerned. Additional service event information to be rated + + + + +Hakala, et al. Standards Track [Page 21] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + MAY be sent as service specific AVPs or MAY be sent within the + Service-Parameter-Info AVP at command level. The Service-Context-Id + AVP indicates the service specific document applicable to the + request. + + The Event-Timestamp AVP SHOULD be included in the request and + contains the time when the service event is requested in the service + element. The Subscription-Id AVP SHOULD be included to identify the + end user in the credit-control server. The credit-control client MAY + include the User-Equipment-Info AVP so that the credit-control server + has some indication of the type and capabilities of the end user + access device. How the credit-control server uses this information + is outside the scope of this document. + + The credit-control server SHOULD rate the service event and make a + credit-reservation from the end user's account that covers the cost + of the service event. If the type of the Requested-Service-Unit AVP + is money, no rating is needed, but the corresponding monetary amount + is reserved from the end user's account. + + The credit-control server returns the Granted-Service-Unit AVP in the + Answer message to the Diameter credit-control client. The Granted- + Service-Unit AVP contains the amount of service units that the + Diameter credit-control client can provide to the end user until a + new Credit-Control-Request MUST be sent to the credit-control server. + If several unit types are sent in the Answer message, the credit- + control client MUST handle each unit type separately. The type of + the Granted-Service-Unit AVP can be time, volume, service specific, + or money, depending on the type of service event. The unit type(s) + SHOULD NOT be changed within an ongoing credit-control session. + + There MUST be a maximum of one instance of the same unit type in one + Answer message. However, if multiple quotas are conveyed to the + credit-control client in the Multiple-Services-Credit-Control AVPs, + it is possible to carry two instances of the same unit type + associated to a service-identifier/rating-group. This is typically + the case when a tariff time change is expected and the credit-control + server wants to make a distinction between the granted quota before + and after tariff change. + + If the credit-control server determines that no further control is + needed for the service, it MAY include the result code indicating + that the credit-control is not applicable (e.g., if the service is + free of charge). This result code at command level implies that the + credit-control session is to be terminated. + + The Credit-Control-Answer message MAY also include the Final-Unit- + Indication AVP to indicate that the answer message contains the final + + + +Hakala, et al. Standards Track [Page 22] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + units for the service. After the end user has consumed these units, + the Diameter credit-control-client MUST behave as described in + section 5.6. + + This document defines two different approaches to perform the first + interrogation to be used in different network architectures. The + first approach uses credit-control messages after the user's + authorization and authentication takes place. The second approach + uses service specific authorization messages to perform the first + interrogation during the user's authorization/authentication phase, + and credit-control messages for the intermediate and final + interrogations. If an implementation of the credit-control client + supports both the methods, determining which method to use SHOULD be + configurable. + + In service environments such as the Network Access Server (NAS), it + is desired to perform the first interrogation as part of the + authorization/authentication process for the sake of protocol + efficiency. Further credit authorizations after the first + interrogation are performed with credit-control commands defined in + this specification. Implementations of credit-control clients + operating in the mentioned environments SHOULD support this method. + If the credit-control server and AAA server are separate physical + entities, the service element sends the request messages to the AAA + server, which then issues an appropriate request or proxies the + received request forward to the credit-control server. + + In other service environments, such as the 3GPP network and some SIP + scenarios, there is a substantial decoupling between + registration/access to the network and the actual service request + (i.e., the authentication/authorization is executed once at + registration/access to the network and is not executed for every + service event requested by the subscriber). In these environments, + it is more appropriate to perform the first interrogation after the + user has been authenticated and authorized. The first, the + intermediate, and the final interrogations are executed with credit- + control commands defined in this specification. + + Other IETF standards or standards developed by other standardization + bodies may define the most suitable method in their architectures. + +5.2.1. First Interrogation after Authorization and Authentication + + The Diameter credit-control client in the service element may get + information from the authorization server as to whether credit- + control is required, based on its knowledge of the end user. If + credit-control is required the credit-control server needs to be + contacted prior to initiating service delivery to the end user. The + + + +Hakala, et al. Standards Track [Page 23] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + accounting protocol and the credit-control protocol can be used in + parallel. The authorization server may also determine whether the + parallel accounting stream is required. + + The following diagram illustrates the case where both protocols are + used in parallel and the service element sends credit-control + messages directly to the credit-control server. More credit-control + sequence examples are given in Annex A. + + Diameter + End User Service Element AAA Server CC Server + (CC Client) + | Registration | AA request/answer(accounting,cc or both)| + |<----------------->|<------------------>| | + | : | | | + | : | | | + | Service Request | | | + |------------------>| | | + | | CCR(Initial,Credit-Control AVPs) | + | +|---------------------------------------->| + | CC stream|| | CCA(Granted-Units)| + | +|<----------------------------------------| + | Service Delivery | | | + |<----------------->| ACR(start,Accounting AVPs) | + | : |------------------->|+ | + | : | ACA || Accounting stream | + | |<-------------------|+ | + | : | | | + | : | | | + | | CCR(Update,Used-Units) | + | |---------------------------------------->| + | | | CCA(Granted-Units)| + | |<----------------------------------------| + | : | | | + | : | | | + | End of Service | | | + |------------------>| CCR(Termination, Used-Units) | + | |---------------------------------------->| + | | | CCA | + | |<----------------------------------------| + | | ACR(stop) | | + | |------------------->| | + | | ACA | | + | |<-------------------| | + + Figure 2: Protocol example with first interrogation after user's + authorization/authentication + + + + +Hakala, et al. Standards Track [Page 24] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +5.2.2. Authorization Messages for First Interrogation + + The Diameter credit-control client in the service element MUST + actively co-operate with the authorization/authentication client in + the construction of the AA request by adding appropriate credit- + control AVPs. The credit-control client MUST add the Credit-Control + AVP to indicate credit-control capabilities and MAY add other + relevant credit-control specific AVPs to the proper + authorization/authentication command to perform the first + interrogation toward the home Diameter AAA server. The Auth- + Application-Id is set to the appropriate value, as defined in the + relevant service specific authorization/authentication application + document (e.g., [NASREQ], [DIAMMIP]). The home Diameter AAA server + authenticates/authorizes the subscriber and determines whether + credit-control is required. + + If credit-control is not required for the subscriber, the home + Diameter AAA server will respond as usual, with an appropriate AA + answer message. If credit-control is required for the subscriber and + the Credit-Control AVP with the value set to CREDIT_AUTHORIZATION was + present in the authorization request, the home AAA server MUST + contact the credit-control server to perform the first interrogation. + If credit-control is required for the subscriber and the Credit- + Control AVP was not present in the authorization request, the home + AAA server MUST send an authorization reject answer message. + + The Diameter AAA server supporting credit-control is required to send + the Credit-Control-Request command (CCR) defined in this document to + the credit-control server. The Diameter AAA server populates the CCR + based on service specific AVPs used for input to the rating process, + and possibly on credit-control AVPs received in the AA request. The + credit-control server will reserve money from the user's account, + will rate the request and will send a Credit-Control-Answer message + to the home Diameter AAA server. The answer message includes the + Granted-Service-Unit AVP(s) and MAY include other credit-control + specific AVPs, as appropriate. Additionally, the credit-control + server MAY set the Validity-Time and MAY include the Credit-Control- + Failure-Handling AVP and the Direct-Debiting-Failure-Handling AVP to + determine what to do if the sending of credit-control messages to the + credit-control server has been temporarily prevented. + + Upon receiving the Credit-Control-Answer message from the credit- + control server, the home Diameter AAA server will populate the AA + answer with the received credit-control AVPs and with the appropriate + service attributes according to the authorization/authentication + specific application (e.g., [NASREQ], [DIAMMIP]). It will then + forward the packet to the credit-control client. If the home + Diameter AAA server receives a credit-control reject message, it will + + + +Hakala, et al. Standards Track [Page 25] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + simply generate an appropriate authorization reject message to the + credit-control client, including the credit-control specific error + code. + + In this model, the credit-control client sends further credit-control + messages to the credit-control server via the home Diameter AAA + server. Upon receiving a successful authorization answer message + with the Granted-Service-Unit AVP(s), the credit-control client will + grant the service to the end user and will generate an intermediate + credit-control request, as required by using credit-control commands. + The CC-Request-Number of the first UPDATE_REQUEST MUST be set to 1 + (for how to produce unique value for the CC-Request-Number AVP, see + section 8.2). + + If service specific re-authorization is performed (i.e., + authorization-lifetime expires), the credit-control client MUST add + to the service specific re-authorization request the Credit-Control + AVP with a value set to RE_AUTHORIZATION to indicate that the + credit-control server MUST NOT be contacted. When session based + credit-control is used for the subscriber, a constant credit-control + message stream flows through the home Diameter AAA server. The home + Diameter AAA server can make use of this credit-control message flow + to deduce that the user's activity is ongoing; therefore, it is + recommended to set the authorization-lifetime to a reasonably high + value when credit-control is used for the subscriber. + + In this scenario, the home Diameter AAA server MUST advertise support + for the credit-control application to its peers during the capability + exchange process. + + + + + + + + + + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 26] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The following diagram illustrates the use of + authorization/authentication messages to perform the first + interrogation. The parallel accounting stream is not shown in the + figure. + + Service Element Diameter + End User (CC Client) AAA Server CC Server + | Service Request | AA Request (CC AVPs) | + |------------------>|------------------->| | + | | | CCR(Initial, CC AVPs) + | | |------------------->| + | | | CCA(Granted-Units) + | | |<-------------------| + | | AA Answer(Granted-Units) | + | Service Delivery |<-------------------| | + |<----------------->| | | + | : | | | + | : | | | + | : | | | + | | | | + | | CCR(Update,Used-Units) | + | |------------------->| CCR(Update,Used-Units) + | | |------------------->| + | | | CCA(Granted-Units)| + | | CCA(Granted-Units)|<-------------------| + | |<-------------------| | + | : | | | + | : | | | + | End of Service | | | + |------------------>| CCR(Termination,Used-Units) | + | |------------------->| CCR(Term.,Used-Units) + | | |------------------->| + | | | CCA | + | | CCA |<-------------------| + | |<-------------------| | + + Figure 3: Protocol example with use of the + authorization messages for the first interrogation + +5.3. Intermediate Interrogation + + When all the granted service units for one unit type are spent by the + end user or the Validity-Time is expired, the Diameter credit-control + client MUST send a new Credit-Control-Request to the credit-control + server. In the event that credit-control for multiple services is + applied in one credit-control session (i.e., units associated to + Service-Identifier(s) or Rating-Group are granted), a new Credit- + Control-Request MUST be sent to the credit-control server when the + + + +Hakala, et al. Standards Track [Page 27] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + credit reservation has been wholly consumed, or upon expiration of + the Validity-Time. It is always up to the Diameter credit-control + client to send a new request well in advance of the expiration of the + previous request in order to avoid interruption in the service + element. Even if the granted service units reserved by the credit- + control server have not been spent upon expiration of the Validity- + Time, the Diameter credit-control client MUST send a new Credit- + Control-Request to the credit-control server. + + There can also be mid-session service events, which might affect the + rating of the current service events. In this case, a spontaneous + updating (a new Credit-Control-Request) SHOULD be sent including + information related to the service event even if all the granted + service units have not been spent or the Validity-Time has not + expired. + + When the used units are reported to the credit-control server, the + credit-control client will not have any units in its possession + before new granted units are received from the credit-control server. + When the new granted units are received, these units apply from the + point where the measurement of the reported used units stopped. + Where independent credit-control of multiple services is supported, + this process may be executed for one or more services, a single + rating-group, or a pool within the (sub)session. + + The CC-Request-Type AVP is set to the value UPDATE_REQUEST in the + intermediate request message. The Subscription-Id AVP SHOULD be + included in the intermediate message to identify the end user in the + credit-control server. The Service-Context-Id AVP indicates the + service specific document applicable to the request. + + The Requested-Service-Unit AVP MAY contain the new amount of + requested service units. Where the Multiple-Services-Credit-Control + AVP is used, it MUST contain the Requested-Service-Unit AVP if a new + quota is requested for the associated service/rating-group. The + Used-Service-Unit AVP contains the amount of used service units + measured from the point when the service became active or, if interim + interrogations are used during the session, from the point when the + previous measurement ended. The same unit types used in the previous + message SHOULD be used. If several unit types were included in the + previous answer message, the used service units for each unit type + MUST be reported. + + The Event-Timestamp AVP SHOULD be included in the request and + contains the time of the event that triggered the sending of the new + Credit-Control-Request. + + + + + +Hakala, et al. Standards Track [Page 28] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The credit-control server MUST deduct the used amount from the end + user's account. It MAY rate the new request and make a new credit- + reservation from the end user's account that covers the cost of the + requested service event. + + A Credit-Control-Answer message with the CC-Request-Type AVP set to + the value UPDATE_REQUEST MAY include the Cost-Information AVP + containing the accumulated cost estimation for the session, without + taking any credit-reservation into account. + + The Credit-Control-Answer message MAY also include the Final-Unit- + Indication AVP to indicate that the answer message contains the final + units for the service. After the end user has consumed these units, + the Diameter credit-control-client MUST behave as described in + section 5.6. + + There can be several intermediate interrogations within a session. + +5.4. Final Interrogation + + When the end user terminates the service session, or when the + graceful service termination described in section 5.6 takes place, + the Diameter credit-control client MUST send a final Credit-Control- + Request message to the credit-control server. The CC-Request-Type + AVP is set to the value TERMINATION_REQUEST. The Service-Context-Id + AVP indicates the service specific document applicable to the + request. + + The Event-Timestamp AVP SHOULD be included in the request and + contains the time when the session was terminated. + + The Used-Service-Unit AVP contains the amount of used service units + measured from the point when the service became active or, if interim + interrogations are used during the session, from the point when the + previous measurement ended. If several unit types were included in + the previous answer message, the used service units for each unit + type MUST be reported. + + After final interrogation, the credit-control server MUST refund the + reserved credit amount not used to the end user's account and deduct + the used monetary amount from the end user's account. + + A Credit-Control-Answer message with the CC-Request-Type set to the + value TERMINATION_REQUEST MAY include the Cost-Information AVP + containing the estimated total cost for the session in question. + + If the user logs off during an ongoing credit-control session, or if + some other reason causes the user to become logged off (e.g., final- + + + +Hakala, et al. Standards Track [Page 29] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + unit indication causes user logoff according to local policy), the + service element, according to application specific policy, may send a + Session-Termination-Request (STR) to the home Diameter AAA server as + usual [DIAMBASE]. Figure 4 illustrates the case when the final-unit + indication causes user logoff upon consumption of the final granted + units and the generation of STR. + + Service Element AAA Server CC Server + End User (CC Client) + | Service Delivery | | | + |<----------------->| | | + | : | | | + | : | | | + | : | | | + | | | | + | | CCR(Update,Used-Units) | + | |------------------->| CCR(Update,Used-Units) + | | |------------------->| + | | CCA(Final-Unit, Terminate) + | CCA(Final-Unit, Terminate)|<-------------------| + | |<-------------------| | + | : | | | + | : | | | + | Disconnect user | | | + |<------------------| CCR(Termination,Used-Units) | + | |------------------->| CCR(Term.,Used-Units) + | | |------------------->| + | | | CCA | + | | CCA |<-------------------| + | |<-------------------| | + | | STR | | + | |------------------->| | + | | STA | | + | |<-------------------| | + + Figure 4: User disconnected due to exhausted account + +5.5. Server-Initiated Credit Re-Authorization + + The Diameter credit-control application supports server-initiated + re-authorization. The credit-control server MAY optionally initiate + the credit re-authorization by issuing a Re-Auth-Request (RAR) as + defined in the Diameter base protocol [DIAMBASE]. The Auth- + Application-Id in the RAR message is set to 4 to indicate Diameter + Credit Control, and the Re-Auth-Request-Type is set to + AUTHORIZE_ONLY. + + + + + +Hakala, et al. Standards Track [Page 30] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Section 5.1.2 defines the feature to enable credit-control for + multiple services within a single (sub-)session where the server can + authorize credit usage at a different level of granularity. Further, + the server may provide credit resources to multiple services or + rating groups as a pool (see section 5.1.2 for details and + definitions). Therefore, the server, based on its service logic and + its knowledge of the ongoing session, can decide to request credit + re-authorization for a whole (sub-)session, a single credit pool, a + single service, or a single rating-group. To request credit re- + authorization for a credit pool, the server includes in the RAR + message the G-S-U-Pool-Identifier AVP indicating the affected pool. + To request credit re-authorization for a service or a rating-group, + the server includes in the RAR message the Service-Identifier AVP or + the Rating-Group AVP, respectively. To request credit re- + authorization for all the ongoing services within the (sub-)session, + the server includes none of the above mentioned AVPs in the RAR + message. + + If a credit re-authorization is not already ongoing (i.e., the + credit-control session is in Open state), a credit control client + that receives an RAR message with Session-Id equal to a currently + active credit-control session MUST acknowledge the request by sending + the Re-Auth-Answer (RAA) message and MUST initiate the credit re- + authorization toward the server by sending a Credit-Control-Request + message with the CC-Request-Type AVP set to the value UPDATE_REQUEST. + The Result-Code 2002 (DIAMETER_LIMITED_SUCCESS) SHOULD be used in the + RAA message to indicate that an additional message (i.e., CCR message + with the value UPDATE_REQUEST) is required to complete the procedure. + If a quota was allocated to the service, the credit-control client + MUST report the used quota in the Credit-Control-Request. Note that + the end user does not need to be prompted for the credit re- + authorization, since the credit re-authorization is transparent to + the user (i.e., it takes place exclusively between the credit-control + client and the credit-control server). + + Where multiple services in a user's session are supported, the + procedure in the above paragraph will be executed at the granularity + requested by the server in the RAR message. + + If credit re-authorization is ongoing at the time when the RAR + message is received (i.e., RAR-CCR collision), the credit-control + client successfully acknowledges the request but does not initiate a + new credit re-authorization. The Result-Code 2001 (DIAMETER_SUCCESS) + SHOULD be used in the RAA message to indicate that a credit re- + authorization procedure is already ongoing (i.e., the client was in + PendingU state when the RAR was received). The credit-control server + SHOULD process the Credit-Control-Request as if it was received in + answer to the server initiated credit re-authorization, and should + + + +Hakala, et al. Standards Track [Page 31] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + consider the server initiated credit re-authorization process + successful upon reception of the Re-Auth-Answer message. + + When multiple services are supported in a user's session, the server + may request credit re-authorization for a credit pool (or for the + (sub-)session) while a credit re-authorization is already ongoing for + some of the services or rating-groups. In this case, the client + acknowledges the server request with an RAA message and MUST send a + new Credit-Control-Request message to perform re-authorization for + the remaining services/rating-groups. The Result-Code 2002 + (DIAMETER_LIMITED_SUCCESS) SHOULD be used in the RAA message to + indicate that an additional message (i.e., CCR message with value + UPDATE_REQUEST) is required to complete the procedure. The server + processes the received requests and returns an appropriate answer to + both requests. + + The above-defined procedures are enabled for each of the possibly + active Diameter credit-control sub-sessions. The server MAY request + re-authorization for an active sub-session by including the CC-Sub- + Session-Id AVP in the RAR message in addition to the Session-Id AVP. + +5.6. Graceful Service Termination + + When the user's account runs out of money, the user may not be + allowed to compile additional chargeable events. However, the home + service provider may offer some services; for instance, access to a + service portal where it is possible to refill the account, for which + the user is allowed to benefit for a limited time. The length of + this time is usually dependent on the home service provider policy. + + This section defines the optional graceful service termination + feature that MAY be supported by the credit-control server. Credit- + control client implementations MUST support the Final-Unit-Indication + with at least the teardown of the ongoing service session once the + subscriber has consumed all the final granted units. + + Where independent credit-control of multiple services in a single + credit-control (sub-)session is supported, it is possible to use the + graceful service termination for each of the services/rating-groups + independently. Naturally, the graceful service termination process + defined in the following sub-sections will apply to the specific + service/rating-group as requested by the server. + + In some service environments (e.g., NAS), the graceful service + termination may be used to redirect the subscriber to a service + portal for online balance refill or other services offered by the + home service provider. In this case, the graceful termination + process installs a set of packet filters to restrict the user's + + + +Hakala, et al. Standards Track [Page 32] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + access capability only to/from the specified destinations. All the + IP packets not matching the filters will be dropped or, possibly, + re-directed to the service portal. The user may also be sent an + appropriate notification as to why the access has been limited. + These actions may be communicated explicitly from the server to the + client or may be configured per-service at the client. Explicitly + signaled redirect or restrict instructions always take precedence + over configured ones. + + It is also possible use the graceful service termination to connect + the prepaid user to a top-up server that plays an announcement and + prompts the user to replenish the account. In this case, the + credit-control server sends only the address of the top-up server + where the prepaid user shall be connected after the final granted + units have been consumed. An example of this is given in Appendix A + (Flow VII). + + The credit-control server MAY initiate the graceful service + termination by including the Final-Unit-Indication AVP in the + Credit-Control-Answer to indicate that the message contains the final + units for the service. + + When the credit-control client receives the Final-Unit-Indication AVP + in the answer from the server, its behavior depends on the value + indicated in the Final-Unit-Action AVP. The server may request the + following actions: TERMINATE, REDIRECT, or RESTRICT_ACCESS. + + A following figure illustrates the graceful service termination + procedure described in the following sub-sections. + + + + + + + + + + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 33] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Diameter + End User Service Element AAA Server CC Server + (CC Client) + | Service Delivery | | | + |<----------------->| | | + | |CCR(Update,Used-Units) | + | |------------------->|CCR(Update,Used-Units) + | : | |------------------->| + | : | |CCA(Final-Unit,Action) + | : | |<-------------------| + | |CCA(Final-Unit,Action) | + | |<-------------------| | + | | | | + | : | | | + | : | | | + | : | | | + | /////////////// |CCR(Update,Used-Units) | + |/Final Units End/->|------------------->|CCR(Update,Used-Units) + |/Action and // | |------------------->| + |/Restrictions // | | CCA(Validity-Time)| + |/Start // | CCA(Validity-Time)|<-------------------| + | ///////////// |<-------------------| | + | : | | | + | : | | | + | Replenish Account +-------+ | + |<-------------------------------------------->|Account| | + | | | +-------+ | + | | | RAR | + | + | RAR |<===================| + | | |<===================| | + | | | RAA | | + | ///////////// | |===================>| RAA | + | /If supported / | | CCR(Update) |===================>| + | /by CC Server/ | |===================>| CCR(Update) | + | ///////////// | | |===================>| + | | | | CCA(Granted-Unit)| + | | | CCA(Granted-Unit)|<===================| + | Restrictions ->+ |<===================| | + | removed | | | + | : | | | + | OR | CCR(Update) | | + | Validity-Time ->|------------------->| CCR(Update) | + | expires | |------------------->| + | | | CCA(Granted-Unit)| + | | CCA(Granted-Unit)|<-------------------| + | Restrictions ->|<-------------------| | + | removed | | | + + + + +Hakala, et al. Standards Track [Page 34] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Figure 5: Optional graceful service termination procedure + +5.6.1. Terminate Action + + The Final-Unit-Indication AVP with Final-Unit-Action TERMINATE does + not include any other information. When the subscriber has consumed + the final granted units, the service element MUST terminate the + service. This is the default handling applicable whenever the + credit-control client receives an unsupported Final-Unit-Action value + and MUST be supported by all the Diameter credit-control client + implementations conforming to this specification. A final Credit- + Control-Request message to the credit-control server MUST be sent if + the Final-Unit-Indication AVP indicating action TERMINATE was present + at command level. The CC-Request-Type AVP in the request is set to + the value TERMINATION_REQUEST. + +5.6.2. Redirect Action + + The Final-Unit-Indication AVP with Final-Unit-Action REDIRECT + indicates to the service element supporting this action that, upon + consumption of the final granted units, the user MUST be re-directed + to the address specified in the Redirect-Server AVP as follows. + + The credit-control server sends the Redirect-Server AVP in the + Credit-Control-Answer message. In such a case, the service element + MUST redirect or connect the user to the destination specified in the + Redirect-Server AVP, if possible. When the end user is redirected + (by using protocols others than Diameter) to the specified server or + connected to the top-up server, an additional authorization (and + possibly authentication) may be needed before the subscriber can + replenish the account; however, this is out of the scope of this + specification. + + In addition to the Redirect-Server AVP, the credit-control server MAY + include one or more Restriction-Filter-Rule AVPs or one or more + Filter-Id AVPs in the Credit-Control-Answer message to enable the + user to access other services (for example, zero-rated services). In + such a case, the access device MUST drop all the packets not matching + the IP filters specified in the Credit-Control-Answer message and, if + possible, redirect the user to the destination specified in the + Redirect-Server AVP. + + An entity other than the credit-control server may provision the + access device with appropriate IP packet filters to be used in + conjunction with the Diameter credit-control application. This case + is considered in section 5.6.3. + + + + + +Hakala, et al. Standards Track [Page 35] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + When the final granted units have been consumed, the credit-control + client MUST perform an intermediate interrogation. The purpose of + this interrogation is to indicate to the credit-control server that + the specified action started and to report the used units. The + credit-control server MUST deduct the used amount from the end user's + account but MUST NOT make a new credit reservation. The credit- + control client, however, may send intermediate interrogations before + all the final granted units have been consumed for which rating and + money reservation may be needed; for instance, upon Validity-Time + expires or upon mid-session service events that affect the rating of + the current service. Therefore, the credit-control client MUST NOT + include any rating related AVP in the request sent once all the final + granted units have been consumed as an indication to the server that + the requested final unit action started, rating and money reservation + are not required (when the Multiple-Services-Credit-Control AVP is + used, the Service-Identifier or Rating-Group AVPs is included to + indicate the concerned services). Naturally, the Credit-Control- + Answer message does not contain any granted service unit and MUST + include the Validity-Time AVP to indicate to the credit-control + client how long the subscriber is allowed to use network resources + before a new intermediate interrogation is sent to the server. + + At the expiry of Validity-Time, the credit-control client sends a + Credit-Control-Request (UPDATE_REQUEST) as usual. This message does + not include the Used-Service-Unit AVP, as there is no allotted quota + to report. The credit-control server processes the request and MUST + perform the credit reservation. If during this time the subscriber + did not replenish his/her account, whether he/she will be + disconnected or will be granted access to services not controlled by + a credit-control server for an unlimited time is dependent on the + home service provider policy (note: the latter option implies that + the service element should not remove the restriction filters upon + termination of the credit-control). The server will return the + appropriate Result-Code (see section 9.1) in the Credit-Control- + Answer message in order to implement the policy-defined action. + Otherwise, new quota will be returned, the service element MUST + remove all the possible restrictions activated by the graceful + service termination process and continue the credit-control session + and service session as usual. + + The credit-control client may not wait until the expiration of the + Validity-Time and may send a spontaneous update (a new Credit- + Control-Request) if the service element can determine, for instance, + that communication between the end user and the top-up server took + place. An example of this is given in Appendix A (Figure A.8). + + + + + + +Hakala, et al. Standards Track [Page 36] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Note that the credit-control server may already have initiated the + above-described process for the first interrogation. However, the + user's account might be empty when this first interrogation is + performed. In this case, the subscriber can be offered a chance to + replenish the account and continue the service. The credit-control + client receives a Credit-Control-Answer or service specific + authorization answer with the Final-Unit-Indication and Validity-Time + AVPs but no Granted-Service-Unit. It immediately starts the graceful + service termination without sending any message to the server. An + example of this case is illustrated in Appendix A. + +5.6.3. Restrict Access Action + + A Final-Unit-Indication AVP with the Final-Unit-Action + RESTRICT_ACCESS indicates to the device supporting this action that + the user's access MUST be restricted according to the IP packet + filters given in the Restriction-Filter-Rule AVP(s) or according to + the IP packet filters identified by the Filter-Id AVP(s). The + credit-control server SHOULD include either the Restriction-Filter- + Rule AVP or the Filter-Id AVP in the Credit-Control-Answer message. + + An entity other than the credit-control server may provision the + access device with appropriate IP packet filters to be used in + conjunction with the Diameter credit-control application. Such an + entity may, for instance, configure the access device with IP flows + to be passed when the Diameter credit-control application indicates + RESTRICT_ACCESS or REDIRECT. The access device passes IP packets + according to the filter rules that may have been received in the + Credit-Control-Answer message in addition to those that may have been + configured by the other entity. However, when the user's account + cannot cover the cost of the requested service, the action taken is + the responsibility of the credit-control server that controls the + prepaid subscriber. + + If another entity working in conjunction with the Diameter credit- + control application already provisions the access device with all the + required filter rules for the end user, the credit-control server + presumably need not send any additional filter. Therefore, it is + RECOMMENDED that credit-control server implementations supporting the + graceful service termination be configurable for sending the + Restriction-Filter-Rule AVP, the Filter-Id AVP, or none of the above. + + When the final granted units have been consumed, the credit-control + client MUST perform an intermediate interrogation. The credit- + control client and the credit-control server process this + intermediate interrogation and execute subsequent procedures, as + specified in the previous section for the REDIRECT action. + + + + +Hakala, et al. Standards Track [Page 37] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The credit-control server may initiate the graceful service + termination with action RESTRICT_ACCESS already for the first + interrogation, as specified in the previous section for the REDIRECT + action. + +5.6.4. Usage of the Server-Initiated Credit Re-Authorization + + Once the subscriber replenishes the account, she presumably expects + all the restrictions placed by the graceful termination procedure to + be removed immediately and unlimited service' access to be resumed. + For the best user experience, the credit-control server + implementation MAY support the server-initiated credit re- + authorization (see section 5.5). In such a case, upon the successful + account top-up, the credit-control server sends the Re-Auth-Request + (RAR) message to solicit the credit re-authorization. The credit- + control client initiates the credit re-authorization by sending the + Credit-Control-Request message with the CC-Request-Type AVP set to + the value UPDATE_REQUEST. The Used-Service-Unit AVP is not included + in the request, as there is no allotted quota to report. The + Requested-Service-Unit AVP MAY be included in the request. After the + credit-control client successfully receives the Credit-Control-Answer + with new Granted-Service-Unit, all the possible restrictions + activated for the purpose of the graceful service termination MUST be + removed in the service element. The credit-control session and the + service session continue as usual. + +5.7. Failure Procedures + + The Credit-Control-Failure-Handling AVP (CCFH), as described in this + section, determines the behavior of the credit-control client in + fault situations. The CCFH may be received from the Diameter home + AAA server, from the credit-control server, or may be configured + locally. The CCFH value received from the home AAA server overrides + the locally configured value. The CCFH value received from the + credit-control server in the Credit-Control-Answer message always + overrides any existing value. + + The authorization server MAY include the Accounting-Realtime-Required + AVP to determine what to do if the sending of accounting records to + the accounting server has been temporarily prevented, as defined in + [DIAMBASE]. It is RECOMMENDED that the client complement the + credit-control failure procedures with backup accounting flow toward + an accounting server. By using different combinations of + Accounting-Realtime-Required and Credit-Control-Failure-Handling + AVPs, different safety levels can be built. For example, by choosing + a Credit-Control-Failure-Handling AVP equal to CONTINUE for the + credit-control flow and a Accounting-Realtime-Required AVP equal to + DELIVER_AND_GRANT for the accounting flow, the service can be granted + + + +Hakala, et al. Standards Track [Page 38] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + to the end user even if the connection to the credit-control server + is down, as long as the accounting server is able to collect the + accounting information and information exchange is taking place + between the accounting server and credit-control server. + + As the credit-control application is based on real-time bi- + directional communication between the credit-control client and the + credit-control server, the usage of alternative destinations and the + buffering of messages may not be sufficient in the event of + communication failures. Because the credit-control server has to + maintain session states, moving the credit-control message stream to + a backup server requires a complex context transfer solution. + Whether the credit-control message stream is moved to a backup + credit-control server during an ongoing credit-control session + depends on the value of the CC-Session-Failover AVP. However, + failover may occur at any point in the path between the credit- + control client and the credit-control server if a transport failure + is detected with a peer, as described in [DIAMBASE]. As a + consequence, the credit-control server might receive duplicate + messages. These duplicates or out of sequence messages can be + detected in the credit-control server based on the credit-control + server session state machine (section 7), Session-Id AVP, and CC- + Request-Number AVP. + + If a failure occurs during an ongoing credit-control session, the + credit-control client may move the credit-control message stream to + an alternative server if the CC-server indicated FAILOVER_SUPPORTED + in the CC-Session-Failover AVP. A secondary credit-control server + name, either received from the home Diameter AAA server or configured + locally, can be used as an address of the backup server. If the CC- + Session-Failover AVP is set to FAILOVER_NOT_SUPPORTED, the credit- + control message stream MUST NOT be moved to a backup server. + + For new credit-control sessions, failover to an alternative credit- + control server SHOULD be performed if possible. For instance, if an + implementation of the credit-control client can determine primary + credit-control server unavailability, it can establish the new + credit-control sessions with a possibly available secondary credit- + control server. + + The AAA transport profile [AAATRANS] defines the application layer + watchdog algorithm that enables failover from a peer that has failed + and is controlled by a watchdog timer (Tw) defined in [AAATRANS]. + The recommended default initial value for Tw (Twinit) is 30 seconds. + Twinit may be set as low as 6 seconds; however, according to + [AAATRANS], setting too low a value for Twinit is likely to result in + an increased probability of duplicates, as well as an increase in + spurious failover and failback attempts. The Diameter base protocol + + + +Hakala, et al. Standards Track [Page 39] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + is common to several different types of Diameter AAA applications + that may be run in the same service element. Therefore, tuning the + timer Twinit to a lower value in order to satisfy the requirements of + real-time applications, such as the Diameter credit-control + application, will certainly cause the above mentioned problems. For + prepaid services, however, the end user expects an answer from the + network in a reasonable time. Thus, the Diameter credit-control + client will react faster than would the underlying base protocol. + Therefore this specification defines the timer Tx that is used by the + credit-control client (as defined in section 13) to supervise the + communication with the credit-control server. When the timer Tx + elapses, the credit-control client takes an action to the end user + according to the Credit-Control-Failure-Handling AVP. + + When Tx expires, the Diameter credit-control client always terminates + the service if the Credit-Control-Failure-Handling (CCFH) AVP is set + to the value TERMINATE. The credit-control session may be moved to + an alternative server only if a protocol error DIAMETER_TOO_BUSY or + DIAMETER_UNABLE_TO_DELIVER is received before Tx expires. Therefore, + the value TERMINATE is not appropriate if proper failover behavior is + desired. + + If the Credit-Control-Failure-Handling AVP is set to the value + CONTINUE or RETRY_AND_TERMINATE, the service will be granted to the + end user when the timer Tx expires. An answer message with granted- + units may arrive later if the base protocol transport failover + occurred in the path to the credit-control server. (The Twinit + default value is 3 times more than the Tx recommended value.) The + credit-control client SHOULD grant the service to the end user, start + monitoring the resource usage, and wait for the possible late answer + until the timeout of the request (e.g., 120 seconds). If the request + fails and the CC-Session-Failover AVP is set to + FAILOVER_NOT_SUPPORTED, the credit-control client terminates or + continues the service depending on the value set in the CCFH and MUST + free all the reserved resources for the credit-control session. If + the protocol error DIAMETER_UNABLE_TO_DELIVER or DIAMETER_TOO_BUSY is + received or the request times out and the CC-Session-Failover AVP is + set to FAILOVER_SUPPORTED, the credit-control client MAY send the + request to a backup server, if possible. If the credit-control + client receives a successful answer from the backup server, it + continues the credit-control session with such a server. If the re- + transmitted request also fails, the credit-control client terminates + or continues the service depending on the value set in the CCFH and + MUST free all the reserved resources for the credit-control session. + + If a communication failure occurs during the graceful service + termination procedure, the service element SHOULD always terminate + the ongoing service session. + + + +Hakala, et al. Standards Track [Page 40] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + If the credit-control server detects a failure during an ongoing + credit-control session, it will terminate the credit-control session + and return the reserved units back to the end user's account. + + The supervision session timer Tcc (as defined in section 13) is used + in the credit-control server to supervise the credit-control session. + + In order to support failover between credit-control servers, + information transfer about the credit-control session and account + state SHOULD take place between the primary and the secondary + credit-control server. Implementations supporting the credit-control + session failover MUST also ensure proper detection of duplicate or + out of sequence messages. The communication between the servers is + regarded as an implementation issue and is outside of the scope of + this specification. + +6. One Time Event + + The one-time event is used when there is no need to maintain any + state in the Diameter credit-control server; for example, enquiring + about the price of the service. The use of a one-time event implies + that the user has been authenticated and authorized beforehand. + + The one time event can be used when the credit-control client wants + to know the cost of the service event or to check the account balance + without any credit-reservation. It can also be used for refunding + service units on the user's account or for direct debiting without + any credit-reservation. The one time event is shown in Figure 6. + + Diameter + End User Service Element AAA Server CC Server + (CC Client) + | Service Request | | | + |------------------>| | | + | | CCR(Event) | | + | |------------------->| CCR(Event) | + | | |------------------->| + | | | CCA(Granted-Units)| + | | CCA(Granted-Units)|<-------------------| + | Service Delivery |<-------------------| | + |<----------------->| | | + + Figure 6: One time event + + In environments such as the 3GPP architecture, the one time event can + be sent from the service element directly to the credit-control + server. + + + + +Hakala, et al. Standards Track [Page 41] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +6.1. Service Price Enquiry + + The credit-control client may need to know the price of the service + event. Services offered by application service providers whose + prices are not known in the credit-control client might exist. The + end user might also want to get an estimation of the price of a + service event before requesting it. + + A Diameter credit-control client requesting the cost information MUST + set the CC-Request-Type AVP equal to EVENT_REQUEST, include the + Requested-Action AVP set to PRICE_ENQUIRY, and set the requested + service event information into the Service-Identifier AVP in the + Credit-Control-Request message. Additional service event information + may be sent as service specific AVPs or within the Service- + Parameter-Info AVP. The Service-Context-Id AVP indicates the service + specific document applicable to the request. + + The credit-control server calculates the cost of the requested + service event, but it does not perform any account balance check or + credit-reservation from the account. + + The estimated cost of the requested service event is returned to the + credit-control client in the Cost-Information AVP in the Credit- + Control-Answer message. + +6.2. Balance Check + + The Diameter credit-control client may only have to verify that the + end user's account balance covers the cost of a certain service + without reserving any units from the account at the time of the + inquiry. This method does not guarantee that credit would be left + when the Diameter credit-control client requests the debiting of the + account with a separate request. + + A Diameter credit-control client requesting the balance check MUST + set the CC-Request-Type AVP equal to EVENT_REQUEST, include a + Requested-Action AVP set to CHECK_BALANCE, and include the + Subscription-Id AVP in order to identify the end user in the credit- + control server. The Service-Context-Id AVP indicates the service + specific document applicable to the request. + + The credit-control server makes the balance check, but it does not + make any credit-reservation from the account. + + The result of balance check (ENOUGH_CREDIT/NO_CREDIT) is returned to + the credit-control client in the Check-Balance-Result AVP in the + Credit-Control-Answer message. + + + + +Hakala, et al. Standards Track [Page 42] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +6.3. Direct Debiting + + There are certain service events for which service execution is + always successful in the service environment. The delay between the + service invocation and the actual service delivery to the end user + can be sufficiently long that the use of the session-based credit- + control would lead to unreasonably long credit-control sessions. In + these cases, the Diameter credit-control client can use the one-time + event scenario for direct debiting. The Diameter credit-control + client SHOULD be sure that the requested service event execution + would be successful when this scenario is used. + + In the Credit-Control-Request message, the CC-Request-Type is set to + the value EVENT_REQUEST and the Requested-Action AVP is set to + DIRECT_DEBITING. The Subscription-Id AVP SHOULD be included to + identify the end user in the credit-control server. The Event- + Timestamp AVP SHOULD be included in the request and contain the time + when the service event is requested in the service element. The + Service-Context-Id AVP indicates the service specific document + applicable to the request. + + The Diameter credit-control client MAY include the monetary amount to + be charged in the Requested-Service-Unit AVP, if it knows the cost of + the service event. If the Diameter credit-control client does not + know the cost of the service event, the Requested-Service-Unit AVP + MAY contain the number of requested service events. The Service- + Identifier AVP always indicates the service concerned. Additional + service event information to be rated MAY be sent as service specific + AVPs or within the Service-Parameter-Info AVP. + + The credit-control server SHOULD rate the service event and deduct + the corresponding monetary amount from the end user's account. If + the type of the Requested-Service-Unit AVP is money, no rating is + needed, but the corresponding monetary amount is deducted from the + end user's account. + + The credit-control server returns the Granted-Service-Unit AVP in the + Credit-Control-Answer message to the Diameter credit-control client. + The Granted-Service-Unit AVP contains the amount of service units + that the Diameter credit-control client can provide to the end user. + The type of the Granted-Service-Unit can be time, volume, service + specific, or money, depending on the type of service event. + + If the credit-control server determines that no credit-control is + needed for the service, it can include the result code indicating + that the credit-control is not applicable (e.g., service is free of + charge). + + + + +Hakala, et al. Standards Track [Page 43] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + For informative purposes, the Credit-Control-Answer message MAY also + include the Cost-Information AVP containing the estimated total cost + of the requested service. + +6.4. Refund + + Some services may refund service units to the end user's account; for + example, gaming services. + + The credit-control client MUST set CC-Request-Type to the value + EVENT_REQUEST and the Requested-Action AVP to REFUND_ACCOUNT in the + Credit-Control-Request message. The Subscription-Id AVP SHOULD be + included to identify the end user in the credit-control server. The + Service-Context-Id AVP indicates the service specific document + applicable to the request. + + The Diameter credit-control client MAY include the monetary amount to + be refunded in the Requested-Service-Unit AVP. The Service- + Identifier AVP always indicates the concerned service. If the + Diameter credit-control client does not know the monetary amount to + be refunded, in addition to the Service-Identifier AVP it MAY send + service specific AVPs or the Service-Parameter-Info AVP containing + additional service event information to be rated. + + For informative purposes, the Credit-Control-Answer message MAY also + include the Cost-Information AVP containing the estimated monetary + amount of refunded unit. + +6.5. Failure Procedure + + Failover to an alternative credit-control server is allowed for a one + time event, as the server is not maintaining session states. For + instance, if the credit-control client receives a protocol error + DIAMETER_UNABLE_TO_DELIVER or DIAMETER_TOO_BUSY, it can re-send the + request to an alternative server, if possible. There MAY be protocol + transparent Diameter relays and redirect agents or Diameter credit- + control proxies between the credit-control client and credit-control + server. Failover may occur at any point in the path between the + credit-control client and the credit-control server if a transport + failure is detected with a peer, as described in [DIAMBASE]. Because + there can be duplicate requests for various reasons, the credit- + control server is responsible for real time duplicate detection. + Implementation issues for duplicate detection are discussed in + [DIAMBASE], Appendix C. + + When the credit-control client detects a communication failure with + the credit-control server, its behavior depends on the requested + action. The timer Tx (as defined in section 13) is used in the + + + +Hakala, et al. Standards Track [Page 44] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + credit-control client to supervise the communication with the + credit-control server. + + If the requested action is PRICE_ENQUIRY or CHECK_BALANCE and + communication failure is detected, the credit-control client SHOULD + forward the request messages to an alternative credit-control server, + if possible. The secondary credit-control server name, if received + from the home Diameter AAA server, can be used as an address of + backup server. + + If the requested action is DIRECT_DEBITING, the Direct-Debiting- + Failure-Handling AVP (DDFH) controls the credit-control client's + behavior. The DDFH may be received from the home Diameter AAA server + or may be locally configured. The credit-control server may also + send the DDFH in any CCA message to be used for direct debiting + events compiled thereafter. The DDFH value received from the home + Diameter AAA server overrides the locally configured value, and the + DDFH value received from the credit-control server in a Credit- + Control-Answer message always overrides any existing value. + + If the DDFH is set to TERMINATE_OR_BUFFER, the credit-control client + SHOULD NOT grant the service if it can determine, eventually after a + possible re-transmission attempt to an alternative credit-control + server, from the result code or error code in the answer message that + units have not been debited. Otherwise, the credit-control client + SHOULD grant the service to the end user and store the request in the + credit-control application level non-volatile storage. (Note that + re-sending the request at a later time is not a guarantee that the + service will be debited, as the user's account may be empty when the + server successfully processes the request.) The credit-control + client MUST mark these request messages as possible duplicates by + setting the T-flag in the command header as described in [DIAMBASE], + section 3. + + If the Direct-Debiting-Failure-Handling AVP is set to CONTINUE, the + service SHOULD be granted, even if credit-control messages cannot be + delivered and messages are not buffered. + + If the timer Tx expires, the credit-control client MUST continue the + service and wait for a possible late answer. If the request times + out, the credit-control client re-transmits the request (marked with + T-flag) to a backup credit-control server, if possible. If the re- + transmitted request also times out, or if a temporary error is + received in answer, the credit-control client buffers the request if + the value of the Direct-Debiting-Failure-Handling AVP is set to + TERMINATE_OR_BUFFER. If a failed answer is received for the + + + + + +Hakala, et al. Standards Track [Page 45] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + re-transmitted request, the credit-control client frees all the + resources reserved for the event message and deletes the request + regardless of the value of the DDFH. + + The Credit-Control-Request with the requested action REFUND_ACCOUNT + should always be stored in the credit-control application level non- + volatile storage in case of temporary failure. The credit-control + client MUST mark the re-transmitted request message as a possible + duplicate by setting the T-flag in the command header as described in + [DIAMBASE], section 3. + + For stored requests, the implementation may choose to limit the + number of re-transmission attempts and to define a re-transmission + interval. + + Note that only one place in the credit-control system SHOULD be + responsible for duplicate detection. If there is only one credit- + control server within the given realm, the credit-control server may + perform duplicate detection. If there is more than one credit- + control server in a given realm, only one entity in the credit- + control system should be responsible, to ensure that the end user's + account is not debited or credited multiple times for the same + service event. + +7. Credit-Control Application State Machine + + This section defines the credit-control application state machine. + + The first four state machines are to be observed by credit-control + clients. The first one describes the session-based credit-control + when the first interrogation is executed as part of the + authorization/authentication process. The second describes the + session-based credit-control when the first interrogation is executed + after the authorization/authentication process. The requirements as + to what state machines have to be supported are discussed in section + 5.2. + + The third state machine describes the session-based credit-control + for the intermediate and final interrogations. The fourth one + describes the event-based credit-control. These latter state + machines are to be observed by all implementations that conform to + this specification. + + The fifth state machine describes the credit-control session from a + credit-control server perspective. + + + + + + +Hakala, et al. Standards Track [Page 46] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Any event not listed in the state machines MUST be considered an + error condition, and a corresponding answer, if applicable, MUST be + returned to the originator of the message. + + In the state table, the event 'Failure to send' means that the + Diameter credit-control client is unable to communicate with the + desired destination or, if failover procedure is supported, with a + possibly defined alternative destination (e.g., the request times out + and the answer message is not received). This could be due to the + peer being down, or due to a physical link failure in the path to or + from the credit-control server. + + The event 'Temporary error' means that the Diameter credit-control + client received a protocol error notification (DIAMETER_TOO_BUSY, + DIAMETER_UNABLE_TO_DELIVER, or DIAMETER_LOOP_DETECTED) in the + Result-Code AVP of the Credit-Control-Answer command. The above + protocol error notification may ultimately be received in answer to + the re-transmitted request to a defined alternative destination, if + failover is supported. + + The event 'Failed answer' means that the Diameter credit-control + client received non-transient failure (permanent failure) + notification in the Credit-Control-Answer command. The above + permanent failure notification may ultimately be received in answer + to the re-transmitted request to a defined alternative destination, + if failover is supported. + + The action 'store request' means that a request is stored in the + credit-control application level non-volatile storage. + + The event 'Not successfully processed' means that the credit-control + server could not process the message; e.g., due to an unknown end + user, account being empty, or errors defined in [DIAMBASE]. + + The event 'User service terminated' can be triggered by various + reasons, e.g., normal user termination, network failure, and ASR + (Abort-Session-Request). The Termination-Cause AVP contains + information about the termination reason, as specified in [DIAMBASE]. + + The Tx timer, which is used to control the waiting time in the + credit-control client in the Pending state, is stopped upon exit of + the Pending state. The stopping of the Tx timer is omitted in the + state machine when the new state is Idle, as moving to Idle state + implies the clearing of the session and all the variables associated + to it. + + + + + + +Hakala, et al. Standards Track [Page 47] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The states PendingI, PendingU, PendingT, PendingE, and PendingB stand + for pending states to wait for an answer to a credit-control request + related to Initial, Update, Termination, Event, or Buffered request, + respectively. + + The acronyms CCFH and DDFH stand for Credit-Control-Failure-Handling + and Direct-Debiting-Failure-Handling, respectively. + + In the following state machine table, the failover to a secondary + server upon 'Temporary error' or 'Failure to send' is not explicitly + described. Moving an ongoing credit-control message stream to an + alternative server is, however, possible if the CC-Session-Failover + AVP is set to FAILOVER_SUPPORTED, as described in section 5.7. + + Re-sending a credit-control event to an alternative server is + supported as described in section 6.5. + + CLIENT, SESSION BASED for the first interrogation with AA request + + State Event Action New State + --------------------------------------------------------------- + Idle Client or device requests Send PendingI + access/service AA request + with added + CC AVPs, + start Tx + + PendingI Successful AA req. Grant Open + answer received service to + end user, + stop Tx + + PendingI Tx expired Disconnect Idle + user/dev + + PendingI Failed AA answer received Disconnect Idle + user/dev + + PendingI AA answer Grant Idle + received with result code service + equal to CREDIT_CONTROL_ to end user + NOT_APPLICABLE + + PendingI User service terminated Queue PendingI + termination + event + + + + + +Hakala, et al. Standards Track [Page 48] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + PendingI Change in rating condition Queue PendingI + changed + rating + condition + event + + CLIENT, SESSION BASED for the first interrogation with CCR + + State Event Action New State + ---------------------------------------------------------------- + + + Idle Client or device requests Send PendingI + access/service CC initial + req., + start Tx + + PendingI Successful CC initial Stop Tx Open + answer received + + PendingI Failure to send, or Grant Idle + temporary error and service to + CCFH equal to CONTINUE end user + + PendingI Failure to send, or Terminate Idle + temporary error and end user's + CCFH equal to TERMINATE service + or to RETRY_AND_TERMINATE + + PendingI Tx expired and CCFH Terminate Idle + equal to TERMINATE end user's + service + + PendingI Tx expired and CCFH equal Grant PendingI + to CONTINUE or to service to + RETRY_AND_TERMINATE end user + + PendingI CC initial answer Terminate Idle + received with result code end user's + END_USER_SERVICE_DENIED or service + USER_UNKNOWN + + PendingI CC initial answer Grant Idle + received with result code service + equal to CREDIT_CONTROL_ to end user + NOT_APPLICABLE + + + + + +Hakala, et al. Standards Track [Page 49] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + PendingI Failed CC initial answer Grant Idle + received and CCFH equal to service to + CONTINUE end user + + PendingI Failed CC initial answer Terminate Idle + received and CCFH equal end user's + to TERMINATE or to service + RETRY_AND_TERMINATE + + PendingI User service terminated Queue PendingI + termination + event + + PendingI Change in rating condition Queue PendingI + changed + rating + condition + event + + CLIENT, SESSION BASED for intermediate and final interrogations + + State Event Action New State + ---------------------------------------------------------------- + + Open Granted unit elapses Send PendingU + and no final unit CC update + indication received req., + start Tx + + Open Granted unit elapses Terminate PendingT + and final unit action end user's + equal to TERMINATE service, send + received CC termination + req. + + Open Change in rating condition Send PendingU + in queue CC update + req., + Start Tx + + Open Service terminated in queue Send PendingT + CC termination + req. + + Open Change in rating condition Send PendingU + or Validity-Time elapses CC update + req., + Start Tx + + + +Hakala, et al. Standards Track [Page 50] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Open User service terminated Send PendingT + CC termination + req. + + Open RAR received Send RAA PendingU + followed by + CC update req., + start Tx + + PendingU Successful CC update Stop Tx Open + answer received + + PendingU Failure to send, or Grant Idle + temporary error and service to + CCFH equal to CONTINUE end user + + PendingU Failure to send, or Terminate Idle + temporary error and end user's + CCFH equal to TERMINATE service + or to RETRY_AND_TERMINATE + + PendingU Tx expired and CCFH Terminate Idle + equal to TERMINATE end user's + service + + PendingU Tx expired and CCFH equal Grant PendingU + to CONTINUE or to service to + RETRY_AND_TERMINATE end user + + PendingU CC update answer Terminate Idle + received with result code end user's + END_USER_SERVICE_DENIED service + + PendingU CC update answer Grant Idle + received with result code service + equal to CREDIT_CONTROL_ to end user + NOT_APPLICABLE + + PendingU Failed CC update Grant Idle + answer received and service to + CCFH equal to CONTINUE end user + + PendingU Failed CC update Terminate Idle + answer received and CCFH end user's + equal to TERMINATE or service + to RETRY_AND_TERMINATE + + + + + +Hakala, et al. Standards Track [Page 51] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + PendingU User service terminated Queue PendingU + termination + event + + PendingU Change in rating Queue PendingU + condition changed + rating + condition + event + + PendingU RAR received Send RAA PendingU + + PendingT Successful CC Idle + termination answer received + + PendingT Failure to send, temporary Idle + error, or failed answer + + PendingT Change in rating condition PendingT + + CLIENT, EVENT BASED + + State Event Action New State + ---------------------------------------------------------------- + Idle Client or device requests Send PendingE + a one-time service CC event + req., + Start Tx + + Idle Request in storage Send PendingB + stored + request + + PendingE Successful CC event Grant Idle + answer received service to + end user + + PendingE Failure to send, temporary Indicate Idle + error, failed CC event service + answer received, or error + Tx expired; requested + action CHECK_BALANCE or + PRICE_ENQUIRY + + PendingE CC event answer Terminate Idle + received with result code end user's + END_USER_SERVICE_DENIED or service + USER_UNKNOWN and Tx running + + + +Hakala, et al. Standards Track [Page 52] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + PendingE CC event answer Grant Idle + received with result code service + CREDIT_CONTROL_NOT_APPLICABLE; to end + requested action user + DIRECT_DEBITING + + PendingE Failure to send, temporary Grant Idle + error, or failed CC event service + answer received; requested to end + action DIRECT_DEBITING; user + DDFH equal to CONTINUE + + PendingE Failed CC event Terminate Idle + answer received or temporary end user's + error; requested action service + DIRECT_DEBITING; + DDFH equal to + TERMINATE_OR_BUFFER and + Tx running + + PendingE Tx expired; requested Grant PendingE + action DIRECT_DEBITING service + to end + user + + PendingE Failure to send; requested Store Idle + action DIRECT_DEBITING; request with + DDFH equal to T-flag + TERMINATE_OR_BUFFER + + PendingE Temporary error; requested Store Idle + action DIRECT_DEBITING; request + DDFH equal to + TERMINATE_OR_BUFFER; + Tx expired + + PendingE Failed answer or answer Idle + received with result code + END_USER_SERVICE DENIED or + USER_UNKNOWN; requested action + DIRECT_DEBITING; Tx expired + + PendingE Failed CC event answer Indicate Idle + received; requested service + action REFUND_ACCOUNT error and + delete request + + + + + +Hakala, et al. Standards Track [Page 53] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + PendingE Failure to send or Store Idle + Tx expired; requested request + action REFUND_ACCOUNT with T-flag + + PendingE Temporary error, Store Idle + and requested action request + REFUND_ACCOUNT + + PendingB Successful CC answer Delete Idle + received request + + PendingB Failed CC answer Delete Idle + received request + + PendingB Failure to send or Idle + temporary error + + SERVER, SESSION AND EVENT BASED + + State Event Action New State + ---------------------------------------------------------------- + + Idle CC initial request Send Open + received and successfully CC initial + processed answer, + reserve units, + start Tcc + + Idle CC initial request Send Idle + received but not CC initial + successfully processed answer with + Result-Code + != SUCCESS + + Idle CC event request Send Idle + received and successfully CC event + processed answer + + Idle CC event request Send Idle + received but not CC event + successfully processed answer with + Result-Code + != SUCCESS + + + + + + + + +Hakala, et al. Standards Track [Page 54] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Open CC update request Send CC Open + received and successfully update answer, + processed debit used + units, + reserve + new units, + restart Tcc + + Open CC update request Send Idle + received but not CC update + successfully processed answer with + Result-Code + != SUCCESS, + debit used + units + + Open CC termination request Send Idle + received and successfully CC termin. + processed answer, + Stop Tcc, + debit used + units + + Open CC termination request Send Idle + received but not CC termin. + successfully processed answer with + Result-Code + != SUCCESS, + debit used + units + + Open Session supervision timer Tcc Release Idle + expired reserved + units + +8. Credit-Control AVPs + + This section defines the credit-control AVPs that are specific to + Diameter credit-control application and that MAY be included in the + Diameter credit-control messages. + + The AVPs defined in this section MAY also be included in + authorization commands defined in authorization-specific + applications, such as [NASREQ] and [DIAMMIP], if the first + interrogation is performed as part of the + authorization/authentication process, as described in section 5.2. + + + + + +Hakala, et al. Standards Track [Page 55] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The Diameter AVP rules are defined in the Diameter Base [DIAMBASE], + section 4. These AVP rules are observed in AVPs defined in this + section. + + The following table describes the Diameter AVPs defined in the + credit-control application, their AVP Code values, types, possible + flag values, and whether the AVP MAY be encrypted. The Diameter base + [DIAMBASE] specifies the AVP Flag rules for AVPs in section 4.5. + + +--------------------+ + | AVP Flag rules | + |----+-----+----+----|----+ + AVP Section | | |SHLD|MUST| | + Attribute Name Code Defined Data Type |MUST| MAY | NOT|NOT |Encr| + -----------------------------------------|----+-----+----+----|----| + CC-Correlation-Id 411 8.1 OctetString| | P,M | | V | Y | + CC-Input-Octets 412 8.24 Unsigned64 | M | P | | V | Y | + CC-Money 413 8.22 Grouped | M | P | | V | Y | + CC-Output-Octets 414 8.25 Unsigned64 | M | P | | V | Y | + CC-Request-Number 415 8.2 Unsigned32 | M | P | | V | Y | + CC-Request-Type 416 8.3 Enumerated | M | P | | V | Y | + CC-Service- 417 8.26 Unsigned64 | M | P | | V | Y | + Specific-Units | | | | | | + CC-Session- 418 8.4 Enumerated | M | P | | V | Y | + Failover | | | | | | + CC-Sub-Session-Id 419 8.5 Unsigned64 | M | P | | V | Y | + CC-Time 420 8.21 Unsigned32 | M | P | | V | Y | + CC-Total-Octets 421 8.23 Unsigned64 | M | P | | V | Y | + CC-Unit-Type 454 8.32 Enumerated | M | P | | V | Y | + Check-Balance- 422 8.6 Enumerated | M | P | | V | Y | + Result | | | | | | + Cost-Information 423 8.7 Grouped | M | P | | V | Y | + Cost-Unit 424 8.12 UTF8String | M | P | | V | Y | + Credit-Control 426 8.13 Enumerated | M | P | | V | Y | + Credit-Control- 427 8.14 Enumerated | M | P | | V | Y | + Failure-Handling | | | | | | + Currency-Code 425 8.11 Unsigned32 | M | P | | V | Y | + Direct-Debiting- 428 8.15 Enumerated | M | P | | V | Y | + Failure-Handling | | | | | | + Exponent 429 8.9 Integer32 | M | P | | V | Y | + Final-Unit-Action 449 8.35 Enumerated | M | P | | V | Y | + Final-Unit- 430 8.34 Grouped | M | P | | V | Y | + Indication | | | | | | + Granted-Service- 431 8.17 Grouped | M | P | | V | Y | + Unit | | | | | | + G-S-U-Pool- 453 8.31 Unsigned32 | M | P | | V | Y | + Identifier | | | | | | + + + + +Hakala, et al. Standards Track [Page 56] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + G-S-U-Pool- 457 8.30 Grouped | M | P | | V | Y | + Reference | | | | | | + Multiple-Services 456 8.16 Grouped | M | P | | V | Y | + -Credit-Control | | | | | | + Multiple-Services 455 8.40 Enumerated | M | P | | V | Y | + -Indicator | | | | | | + Rating-Group 432 8.29 Unsigned32 | M | P | | V | Y | + Redirect-Address 433 8.38 Enumerated | M | P | | V | Y | + -Type | | | | | | + Redirect-Server 434 8.37 Grouped | M | P | | V | Y | + Redirect-Server 435 8.39 UTF8String | M | P | | V | Y | + -Address | | | | | | + Requested-Action 436 8.41 Enumerated | M | P | | V | Y | + Requested-Service 437 8.18 Grouped | M | P | | V | Y | + -Unit | | | | | | + Restriction 438 8.36 IPFiltrRule| M | P | | V | Y | + -Filter-Rule | | | | | | + Service-Context 461 8.42 UTF8String | M | P | | V | Y | + -Id | | | | | | + Service- 439 8.28 Unsigned32 | M | P | | V | Y | + Identifier | | | | | | + Service-Parameter 440 8.43 Grouped | | P,M | | V | Y | + -Info | | | | | | + Service- 441 8.44 Unsigned32 | | P,M | | V | Y | + Parameter-Type | | | | | | + Service- 442 8.45 OctetString| | P,M | | V | Y | + Parameter-Value | | | | | | + Subscription-Id 443 8.46 Grouped | M | P | | V | Y | + Subscription-Id 444 8.48 UTF8String | M | P | | V | Y | + -Data | | | | | | + Subscription-Id 450 8.47 Enumerated | M | P | | V | Y | + -Type | | | | | | + Tariff-Change 452 8.27 Enumerated | M | P | | V | Y | + -Usage | | | | | | + Tariff-Time 451 8.20 Time | M | P | | V | Y | + -Change | | | | | | + Unit-Value 445 8.8 Grouped | M | P | | V | Y | + Used-Service-Unit 446 8.19 Grouped | M | P | | V | Y | + User-Equipment 458 8.49 Grouped | | P,M | | V | Y | + -Info | | | | | | + User-Equipment 459 8.50 Enumerated | | P,M | | V | Y | + -Info-Type | | | | | | + User-Equipment 460 8.51 OctetString| | P,M | | V | Y | + -Info-Value | | | | | | + Value-Digits 447 8.10 Integer64 | M | P | | V | Y | + Validity-Time 448 8.33 Unsigned32 | M | P | | V | Y | + + + + + +Hakala, et al. Standards Track [Page 57] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +8.1. CC-Correlation-Id AVP + + The CC-Correlation-Id AVP (AVP Code 411) is of type OctetString and + contains information to correlate credit-control requests generated + for different components of the service; e.g., transport and service + level. The one who allocates the Service-Context-Id (i.e., unique + identifier of a service specific document) is also responsible for + defining the content and encoding of the CC-Correlation-Id AVP. + +8.2. CC-Request-Number AVP + + The CC-Request-Number AVP (AVP Code 415) is of type Unsigned32 and + identifies this request within one session. As Session-Id AVPs are + globally unique, the combination of Session-Id and CC-Request-Number + AVPs is also globally unique and can be used in matching credit- + control messages with confirmations. An easy way to produce unique + numbers is to set the value to 0 for a credit-control request of type + INITIAL_REQUEST and EVENT_REQUEST and to set the value to 1 for the + first UPDATE_REQUEST, to 2 for the second, and so on until the value + for TERMINATION_REQUEST is one more than for the last UPDATE_REQUEST. + +8.3. CC-Request-Type AVP + + The CC-Request-Type AVP (AVP Code 416) is of type Enumerated and + contains the reason for sending the credit-control request message. + It MUST be present in all Credit-Control-Request messages. The + following values are defined for the CC-Request-Type AVP: + + INITIAL_REQUEST 1 + An Initial request is used to initiate a credit-control session, + and contains credit control information that is relevant to the + initiation. + + UPDATE_REQUEST 2 + An Update request contains credit-control information for an + existing credit-control session. Update credit-control requests + SHOULD be sent every time a credit-control re-authorization is + needed at the expiry of the allocated quota or validity time. + Further, additional service-specific events MAY trigger a + spontaneous Update request. + + TERMINATION_REQUEST 3 + A Termination request is sent to terminate a credit-control + session and contains credit-control information relevant to the + existing session. + + + + + + +Hakala, et al. Standards Track [Page 58] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + EVENT_REQUEST 4 + An Event request is used when there is no need to maintain any + credit-control session state in the credit-control server. This + request contains all information relevant to the service, and is + the only request of the service. The reason for the Event request + is further detailed in the Requested-Action AVP. The Requested- + Action AVP MUST be included in the Credit-Control-Request message + when CC-Request-Type is set to EVENT_REQUEST. + +8.4. CC-Session-Failover AVP + + The CC-Session-Failover AVP (AVP Code 418) is type of Enumerated and + contains information as to whether moving the credit-control message + stream to a backup server during an ongoing credit-control session is + supported. In communication failures, the credit-control message + streams can be moved to an alternative destination if the credit- + control server supports failover to an alternative server. The + secondary credit-control server name, if received from the home + Diameter AAA server, can be used as an address of the backup server. + An implementation is not required to support moving a credit-control + message stream to an alternative server, as this also requires moving + information related to the credit-control session to backup server. + + The following values are defined for the CC-Session-Failover AVP: + + FAILOVER_NOT_SUPPORTED 0 + When the CC-Session-Failover AVP is set to FAILOVER_NOT_SUPPORTED, + the credit-control message stream MUST NOT to be moved to an + alternative destination in the case of communication failure. + + This is the default behavior if the AVP isn't included in the + reply from the authorization or credit-control server. + + FAILOVER_SUPPORTED 1 + When the CC-Session-Failover AVP is set to FAILOVER_SUPPORTED, the + credit-control message stream SHOULD be moved to an alternative + destination in the case of communication failure. Moving the + credit-control message stream to a backup server MAY require that + information related to the credit-control session should also be + forwarded to alternative server. + +8.5. CC-Sub-Session-Id AVP + + The CC-Sub-Session-Id AVP (AVP Code 419) is of type Unsigned64 and + contains the credit-control sub-session identifier. The combination + of the Session-Id and this AVP MUST be unique per sub-session, and + + + + + +Hakala, et al. Standards Track [Page 59] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + the value of this AVP MUST be monotonically increased by one for all + new sub-sessions. The absence of this AVP implies that no sub- + sessions are in use. + +8.6. Check-Balance-Result AVP + + The Check Balance Result AVP (AVP Code 422) is of type Enumerated and + contains the result of the balance check. This AVP is applicable + only when the Requested-Action AVP indicates CHECK_BALANCE in the + Credit-Control-Request command. + + The following values are defined for the Check-Balance-Result AVP. + + ENOUGH_CREDIT 0 + There is enough credit in the account to cover the requested + service. + + NO_CREDIT 1 + There isn't enough credit in the account to cover the requested + service. + +8.7. Cost-Information AVP + + The Cost-Information AVP (AVP Code 423) is of type Grouped, and it is + used to return the cost information of a service, which the credit- + control client can transfer transparently to the end user. The + included Unit-Value AVP contains the cost estimate (always type of + money) of the service, in the case of price enquiry, or the + accumulated cost estimation, in the case of credit-control session. + + The Currency-Code specifies in which currency the cost was given. + The Cost-Unit specifies the unit when the service cost is a cost per + unit (e.g., cost for the service is $1 per minute). + + When the Requested-Action AVP with value PRICE_ENQUIRY is included in + the Credit-Control-Request command, the Cost-Information AVP sent in + the succeeding Credit-Control-Answer command contains the cost + estimation of the requested service, without any reservation being + made. + + The Cost-Information AVP included in the Credit-Control-Answer + command with the CC-Request-Type set to UPDATE_REQUEST contains the + accumulated cost estimation for the session, without taking any + credit reservation into account. + + + + + + + +Hakala, et al. Standards Track [Page 60] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The Cost-Information AVP included in the Credit-Control-Answer + command with the CC-Request-Type set to EVENT_REQUEST or + TERMINATION_REQUEST contains the estimated total cost for the + requested service. + + It is defined as follows (per the grouped-avp-def of + RFC 3588 [DIAMBASE]): + + Cost-Information ::= < AVP Header: 423 > + { Unit-Value } + { Currency-Code } + [ Cost-Unit ] + +8.8. Unit-Value AVP + + Unit-Value AVP is of type Grouped (AVP Code 445) and specifies the + units as decimal value. The Unit-Value is a value with an exponent; + i.e., Unit-Value = Value-Digits AVP * 10^Exponent. This + representation avoids unwanted rounding off. For example, the value + of 2,3 is represented as Value-Digits = 23 and Exponent = -1. The + absence of the exponent part MUST be interpreted as an exponent equal + to zero. + + It is defined as follows (per the grouped-avp-def of + RFC 3588 [DIAMBASE]): + + Unit-Value ::= < AVP Header: 445 > + { Value-Digits } + [ Exponent ] + +8.9. Exponent AVP + + Exponent AVP is of type Integer32 (AVP Code 429) and contains the + exponent value to be applied for the Value-Digit AVP within the + Unit-Value AVP. + +8.10. Value-Digits AVP + + The Value-Digits AVP is of type Integer64 (AVP Code 447) and contains + the significant digits of the number. If decimal values are needed + to present the units, the scaling MUST be indicated with the related + Exponent AVP. For example, for the monetary amount $ 0.05 the value + of Value-Digits AVP MUST be set to 5, and the scaling MUST be + indicated with the Exponent AVP set to -2. + + + + + + + +Hakala, et al. Standards Track [Page 61] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +8.11. Currency-Code AVP + + The Currency-Code AVP (AVP Code 425) is of type Unsigned32 and + contains a currency code that specifies in which currency the values + of AVPs containing monetary units were given. It is specified by + using the numeric values defined in the ISO 4217 standard [ISO4217]. + +8.12. Cost-Unit AVP + + The Cost-Unit AVP (AVP Code 424) is of type UTF8String, and it is + used to display a human readable string to the end user. It + specifies the applicable unit to the Cost-Information when the + service cost is a cost per unit (e.g., cost of the service is $1 per + minute). The Cost-Unit can be minutes, hours, days, kilobytes, + megabytes, etc. + +8.13. Credit-Control AVP + + The Credit-Control AVP (AVP Code 426) is of type Enumerated and MUST + be included in AA requests when the service element has credit- + control capabilities. + + CREDIT_AUTHORIZATION 0 + If the home Diameter AAA server determines that the user has + prepaid subscription, this value indicates that the credit-control + server MUST be contacted to perform the first interrogation. The + value of the Credit-Control AVP MUST always be set to 0 in an AA + request sent to perform the first interrogation and to initiate a + new credit-control session. + + RE_AUTHORIZATION 1 + This value indicates to the Diameter AAA server that a credit- + control session is ongoing for the subscriber and that the + credit-control server MUST not be contacted. The Credit-Control + AVP set to the value of 1 is to be used only when the first + interrogation has been successfully performed and the credit- + control session is ongoing (i.e., re-authorization triggered by + Authorization-Lifetime). This value MUST NOT be used in an AA + request sent to perform the first interrogation. + +8.14. Credit-Control-Failure-Handling AVP + + The Credit-Control-Failure-Handling AVP (AVP Code 427) is of type + Enumerated. The credit-control client uses information in this AVP + to decide what to do if sending credit-control messages to the + credit-control server has been, for instance, temporarily prevented + due to a network problem. Depending on the service logic, the + credit-control server can order the client to terminate the service + + + +Hakala, et al. Standards Track [Page 62] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + immediately when there is a reason to believe that the service cannot + be charged, or to try failover to an alternative server, if possible. + Then the server could either terminate or grant the service, should + the alternative connection also fail. + + TERMINATE 0 + When the Credit-Control-Failure-Handling AVP is set to TERMINATE, + the service MUST only be granted for as long as there is a + connection to the credit-control server. If the credit-control + client does not receive any Credit-Control-Answer message within + the Tx timer (as defined in section 13), the credit-control + request is regarded as failed, and the end user's service session + is terminated. + + This is the default behavior if the AVP isn't included in the + reply from the authorization or credit-control server. + + CONTINUE 1 + When the Credit-Control-Failure-Handling AVP is set to CONTINUE, + the credit-control client SHOULD re-send the request to an + alternative server in the case of transport or temporary failures, + provided that a failover procedure is supported in the credit- + control server and the credit-control client, and that an + alternative server is available. Otherwise, the service SHOULD be + granted, even if credit-control messages can't be delivered. + + RETRY_AND_TERMINATE 2 + When the Credit-Control-Failure-Handling AVP is set to + RETRY_AND_TERMINATE, the credit-control client SHOULD re-send the + request to an alternative server in the case of transport or + temporary failures, provided that a failover procedure is + supported in the credit-control server and the credit-control + client, and that an alternative server is available. Otherwise, + the service SHOULD not be granted when the credit-control messages + can't be delivered. + +8.15. Direct-Debiting-Failure-Handling AVP + + The Direct-Debiting-Failure-Handling AVP (AVP Code 428) is of type + Enumerated. The credit-control client uses information in this AVP + to decide what to do if sending credit-control messages (Requested- + Action AVP set to DIRECT_DEBITING) to the credit-control server has + been, for instance, temporarily prevented due to a network problem. + + TERMINATE_OR_BUFFER 0 + When the Direct-Debiting-Failure-Handling AVP is set to + TERMINATE_OR_BUFFER, the service MUST be granted for as long as + there is a connection to the credit-control server. If the + + + +Hakala, et al. Standards Track [Page 63] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + credit-control client does not receive any Credit-Control-Answer + message within the Tx timer (as defined in section 13) the + credit-control request is regarded as failed. The client SHOULD + terminate the service if it can determine from the failed answer + that units have not been debited. Otherwise the credit-control + client SHOULD grant the service, store the request in application + level non-volatile storage, and try to re-send the request. These + requests MUST be marked as possible duplicates by setting the T- + flag in the command header as described in [DIAMBASE] section 3. + + This is the default behavior if the AVP isn't included in the + reply from the authorization server. + + CONTINUE 1 + When the Direct-Debiting-Failure-Handling AVP is set to CONTINUE, + the service SHOULD be granted, even if credit-control messages + can't be delivered, and the request should be deleted. + +8.16. Multiple-Services-Credit-Control AVP + + Multiple-Services-Credit-Control AVP (AVP Code 456) is of type + Grouped and contains the AVPs related to the independent credit- + control of multiple services feature. Note that each instance of + this AVP carries units related to one or more services or related to + a single rating group. + + The Service-Identifier and the Rating-Group AVPs are used to + associate the granted units to a given service or rating group. If + both the Service-Identifier and the Rating-Group AVPs are included, + the target of the service units is always the service(s) indicated by + the value of the Service-Identifier AVP(s). If only the Rating- + Group-Id AVP is present, the Multiple-Services-Credit-Control AVP + relates to all the services that belong to the specified rating + group. + + The G-S-U-Pool-Reference AVP allows the server to specify a G-S-U- + Pool-Identifier identifying a credit pool within which the units of + the specified type are considered pooled. If a G-S-U-Pool-Reference + AVP is present, then actual service units of the specified type MUST + also be present. For example, if the G-S-U-Pool-Reference AVP + specifies Unit-Type TIME, then the CC-Time AVP MUST be present. + + The Requested-Service-Unit AVP MAY contain the amount of requested + service units or the requested monetary value. It MUST be present in + the initial interrogation and within the intermediate interrogations + in which new quota is requested. If the credit-control client does + not include the Requested-Service-Unit AVP in a request command, + because for instance, it has determined that the end-user terminated + + + +Hakala, et al. Standards Track [Page 64] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + the service, the server MUST debit the used amount from the user's + account but MUST NOT return a new quota in the corresponding answer. + The Validity-Time, Result-Code, and Final-Unit-Indication AVPs MAY be + present in an answer command as defined in sections 5.1.2 and 5.6 for + the graceful service termination. + + When both the Tariff-Time-Change and Tariff-Change-Usage AVPs are + present, the server MUST include two separate instances of the + Multiple-Services-Credit-Control AVP with the Granted-Service-Unit + AVP associated to the same service-identifier and/or rating-group. + Where the two quotas are associated to the same pool or to different + pools, the credit pooling mechanism defined in section 5.1.2 applies. + The Tariff-Change-Usage AVP MUST NOT be included in request commands + to report used units before, and after tariff time change the Used- + Service-Unit AVP MUST be used. + + A server not implementing the independent credit-control of multiple + services functionality MUST treat the Multiple-Services-Credit- + Control AVP as an invalid AVP. + + The Multiple-Services-Control AVP is defined as follows (per the + grouped-avp-def of RFC 3588 [DIAMBASE]): + + Multiple-Services-Credit-Control ::= < AVP Header: 456 > + [ Granted-Service-Unit ] + [ Requested-Service-Unit ] + *[ Used-Service-Unit ] + [ Tariff-Change-Usage ] + *[ Service-Identifier ] + [ Rating-Group ] + *[ G-S-U-Pool-Reference ] + [ Validity-Time ] + [ Result-Code ] + [ Final-Unit-Indication ] + *[ AVP ] + +8.17. Granted-Service-Unit AVP + + Granted-Service-Unit AVP (AVP Code 431) is of type Grouped and + contains the amount of units that the Diameter credit-control client + can provide to the end user until the service must be released or the + new Credit-Control-Request must be sent. A client is not required to + implement all the unit types, and it must treat unknown or + unsupported unit types in the answer message as an incorrect CCA + answer. In this case, the client MUST terminate the credit-control + session and indicate in the Termination-Cause AVP reason + DIAMETER_BAD_ANSWER. + + + + +Hakala, et al. Standards Track [Page 65] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The Granted-Service-Unit AVP is defined as follows (per the grouped- + avp-def of RFC 3588 [DIAMBASE]): + + Granted-Service-Unit ::= < AVP Header: 431 > + [ Tariff-Time-Change ] + [ CC-Time ] + [ CC-Money ] + [ CC-Total-Octets ] + [ CC-Input-Octets ] + [ CC-Output-Octets ] + [ CC-Service-Specific-Units ] + *[ AVP ] + +8.18. Requested-Service-Unit AVP + + The Requested-Service-Unit AVP (AVP Code 437) is of type Grouped and + contains the amount of requested units specified by the Diameter + credit-control client. A server is not required to implement all the + unit types, and it must treat unknown or unsupported unit types as + invalid AVPs. + + The Requested-Service-Unit AVP is defined as follows (per the + grouped-avp-def of RFC 3588 [DIAMBASE]): + + Requested-Service-Unit ::= < AVP Header: 437 > + [ CC-Time ] + [ CC-Money ] + [ CC-Total-Octets ] + [ CC-Input-Octets ] + [ CC-Output-Octets ] + [ CC-Service-Specific-Units ] + *[ AVP ] + +8.19. Used-Service-Unit AVP + + The Used-Service-Unit AVP is of type Grouped (AVP Code 446) and + contains the amount of used units measured from the point when the + service became active or, if interim interrogations are used during + the session, from the point when the previous measurement ended. + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 66] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The Used-Service-Unit AVP is defined as follows (per the grouped- + avp-def of RFC 3588 [DIAMBASE]): + + Used-Service-Unit ::= < AVP Header: 446 > + [ Tariff-Change-Usage ] + [ CC-Time ] + [ CC-Money ] + [ CC-Total-Octets ] + [ CC-Input-Octets ] + [ CC-Output-Octets ] + [ CC-Service-Specific-Units ] + *[ AVP ] + +8.20. Tariff-Time-Change AVP + + The Tariff-Time-Change AVP (AVP Code 451) is of type Time. It is + sent from the server to the client and includes the time in seconds + since January 1, 1900, 00:00 UTC, when the tariff of the service will + be changed. + + The tariff change mechanism is optional for the client and server, + and it is not used for time-based services defined in section 5. If + a client does not support the tariff time change mechanism, it MUST + treat Tariff-Time-Change AVP in the answer message as an incorrect + CCA answer. In this case, the client terminates the credit-control + session and indicates in the Termination-Cause AVP reason + DIAMETER_BAD_ANSWER. + + Omission of this AVP means that no tariff change is to be reported. + +8.21. CC-Time AVP + + The CC-Time AVP (AVP Code 420) is of type Unsigned32 and indicates + the length of the requested, granted, or used time in seconds. + +8.22. CC-Money AVP + + The CC-Money AVP (AVP Code 413) is of type Grouped and specifies the + monetary amount in the given currency. The Currency-Code AVP SHOULD + be included. It is defined as follows (per the grouped-avp-def of + RFC 3588 [DIAMBASE]): + + CC-Money ::= < AVP Header: 413 > + { Unit-Value } + [ Currency-Code ] + + + + + + +Hakala, et al. Standards Track [Page 67] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +8.23. CC-Total-Octets AVP + + The CC-Total-Octets AVP (AVP Code 421) is of type Unsigned64 and + contains the total number of requested, granted, or used octets + regardless of the direction (sent or received). + +8.24. CC-Input-Octets AVP + + The CC-Input-Octets AVP (AVP Code 412) is of type Unsigned64 and + contains the number of requested, granted, or used octets that can + be/have been received from the end user. + +8.25. CC-Output-Octets AVP + + The CC-Output-Octets AVP (AVP Code 414) is of type Unsigned64 and + contains the number of requested, granted, or used octets that can + be/have been sent to the end user. + +8.26. CC-Service-Specific-Units AVP + + The CC-Service-Specific-Units AVP (AVP Code 417) is of type + Unsigned64 and specifies the number of service-specific units (e.g., + number of events, points) given in a selected service. The service- + specific units always refer to the service identified in the + Service-Identifier AVP (or Rating-Group AVP when the Multiple- + Services-Credit-Control AVP is used). + +8.27. Tariff-Change-Usage AVP + + The Tariff-Change-Usage AVP (AVP Code 452) is of type Enumerated and + defines whether units are used before or after a tariff change, or + whether the units straddled a tariff change during the reporting + period. Omission of this AVP means that no tariff change has + occurred. + + In addition, when present in answer messages as part of the + Multiple-Services-Credit-Control AVP, this AVP defines whether units + are allocated to be used before or after a tariff change event. + + When the Tariff-Time-Change AVP is present, omission of this AVP in + answer messages means that the single quota mechanism applies. + + Tariff-Change-Usage can be one of the following: + + UNIT_BEFORE_TARIFF_CHANGE 0 + When present in the Multiple-Services-Credit-Control AVP, this + value indicates the amount of the units allocated for use before a + tariff change occurs. + + + +Hakala, et al. Standards Track [Page 68] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + When present in the Used-Service-Unit AVP, this value indicates + the amount of resource units used before a tariff change had + occurred. + + UNIT_AFTER_TARIFF_CHANGE 1 + When present in the Multiple-Services-Credit-Control AVP, this + value indicates the amount of the units allocated for use after a + tariff change occurs. + + When present in the Used-Service-Unit AVP, this value indicates + the amount of resource units used after tariff change had + occurred. + + UNIT_INDETERMINATE 2 + The used unit contains the amount of units that straddle the + tariff change (e.g., the metering process reports to the credit- + control client in blocks of n octets, and one block straddled the + tariff change). This value is to be used only in the Used- + Service-Unit AVP. + +8.28. Service-Identifier AVP + + The Service-Identifier AVP is of type Unsigned32 (AVP Code 439) and + contains the identifier of a service. The specific service the + request relates to is uniquely identified by the combination of + Service-Context-Id and Service-Identifier AVPs. + + A usage example of this AVP is illustrated in Appendix A (Flow IX). + +8.29. Rating-Group AVP + + The Rating-Group AVP is of type Unsigned32 (AVP Code 432) and + contains the identifier of a rating group. All the services subject + to the same rating type are part of the same rating group. The + specific rating group the request relates to is uniquely identified + by the combination of Service-Context-Id and Rating-Group AVPs. + + A usage example of this AVP is illustrated in Appendix A (Flow IX). + +8.30. G-S-U-Pool-Reference AVP + + The G-S-U-Pool-Reference AVP (AVP Code 457) is of type Grouped. It + is used in the Credit-Control-Answer message, and associates the + Granted-Service-Unit AVP within which it appears with a credit pool + within the session. + + The G-S-U-Pool-Identifier AVP specifies the credit pool from which + credit is drawn for this unit type. + + + +Hakala, et al. Standards Track [Page 69] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The CC-Unit-Type AVP specifies the type of units for which credit is + pooled. + + The Unit-Value AVP specifies the multiplier, which converts between + service units of type CC-Unit-Type and abstract service units within + the credit pool (and thus to service units of any other service or + rating group associated with the same pool). + + The G-S-U-Pool-Reference AVP is defined as follows (per the grouped- + avp-def of RFC 3588 [DIAMBASE]): + + G-S-U-Pool-Reference ::= < AVP Header: 457 > + { G-S-U-Pool-Identifier } + { CC-Unit-Type } + { Unit-Value } + +8.31. G-S-U-Pool-Identifier AVP + + The G-S-U-Pool-Identifier AVP (AVP Code 453) is of type Unsigned32 + and identifies a credit pool within the session. + +8.32. CC-Unit-Type AVP + + The CC-Unit-Type AVP (AVP Code 454) is of type Enumerated and + specifies the type of units considered to be pooled into a credit + pool. + + The following values are defined for the CC-Unit-Type AVP: + + TIME 0 + MONEY 1 + TOTAL-OCTETS 2 + INPUT-OCTETS 3 + OUTPUT-OCTETS 4 + SERVICE-SPECIFIC-UNITS 5 + +8.33. Validity-Time AVP + + The Validity-Time AVP is of type Unsigned32 (AVP Code 448). It is + sent from the credit-control server to the credit-control client. + The AVP contains the validity time of the granted service units. The + measurement of the Validity-Time is started upon receipt of the + Credit-Control-Answer Message containing this AVP. If the granted + service units have not been consumed within the validity time + specified in this AVP, the credit-control client MUST send a Credit- + Control-Request message to the server, with CC-Request-Type set to + UPDATE_REQUEST. The value field of the Validity-Time AVP is given in + seconds. + + + +Hakala, et al. Standards Track [Page 70] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The Validity-Time AVP is also used for the graceful service + termination (see section 5.6) to indicate to the credit-control + client how long the subscriber is allowed to use network resources + after the specified action (i.e., REDIRECT or RESTRICT_ACCESS) + started. When the Validity-Time elapses, a new intermediate + interrogation is sent to the server. + +8.34. Final-Unit-Indication AVP + + The Final-Unit-Indication AVP (AVP Code 430) is of type Grouped and + indicates that the Granted-Service-Unit AVP in the Credit-Control- + Answer, or in the AA answer, contains the final units for the + service. After these units have expired, the Diameter credit-control + client is responsible for executing the action indicated in the + Final-Unit-Action AVP (see section 5.6). + + If more than one unit type is received in the Credit-Control-Answer, + the unit type that first expired SHOULD cause the credit-control + client to execute the specified action. + + In the first interrogation, the Final-Unit-Indication AVP with + Final-Unit-Action REDIRECT or RESTRICT_ACCESS can also be present + with no Granted-Service-Unit AVP in the Credit-Control-Answer or in + the AA answer. This indicates to the Diameter credit-control client + to execute the specified action immediately. If the home service + provider policy is to terminate the service, naturally, the server + SHOULD return the appropriate transient failure (see section 9.1) in + order to implement the policy-defined action. + + The Final-Unit-Action AVP defines the behavior of the service element + when the user's account cannot cover the cost of the service and MUST + always be present if the Final-Unit-Indication AVP is included in a + command. + + If the Final-Unit-Action AVP is set to TERMINATE, no other AVPs MUST + be present. + + If the Final-Unit-Action AVP is set to REDIRECT at least the + Redirect-Server AVP MUST be present. The Restriction-Filter-Rule AVP + or the Filter-Id AVP MAY be present in the Credit-Control-Answer + message if the user is also allowed to access other services that are + not accessible through the address given in the Redirect-Server AVP. + + If the Final-Unit-Action AVP is set to RESTRICT_ACCESS, either the + Restriction-Filter-Rule AVP or the Filter-Id AVP SHOULD be present. + + + + + + +Hakala, et al. Standards Track [Page 71] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The Filter-Id AVP is defined in [NASREQ]. The Filter-Id AVP can be + used to reference an IP filter list installed in the access device by + means other than the Diameter credit-control application, e.g., + locally configured or configured by another entity. + + The Final-Unit-Indication AVP is defined as follows (per the + grouped-avp-def of RFC 3588 [DIAMBASE]): + + Final-Unit-Indication ::= < AVP Header: 430 > + { Final-Unit-Action } + *[ Restriction-Filter-Rule ] + *[ Filter-Id ] + [ Redirect-Server ] + +8.35. Final-Unit-Action AVP + + The Final-Unit-Action AVP (AVP Code 449) is of type Enumerated and + indicates to the credit-control client the action to be taken when + the user's account cannot cover the service cost. + + The Final-Unit-Action can be one of the following: + + TERMINATE 0 + The credit-control client MUST terminate the service session. + This is the default handling, applicable whenever the credit- + control client receives an unsupported Final-Unit-Action value, + and it MUST be supported by all the Diameter credit-control client + implementations conforming to this specification. + + REDIRECT 1 + The service element MUST redirect the user to the address + specified in the Redirect-Server-Address AVP. The redirect action + is defined in section 5.6.2. + + RESTRICT_ACCESS 2 + The access device MUST restrict the user access according to the + IP packet filters defined in the Restriction-Filter-Rule AVP or + according to the IP packet filters identified by the Filter-Id + AVP. All the packets not matching the filters MUST be dropped + (see section 5.6.3). + +8.36. Restriction-Filter-Rule AVP + + The Restriction-Filter-Rule AVP (AVP Code 438) is of type + IPFilterRule and provides filter rules corresponding to services that + are to remain accessible even if there are no more service units + granted. The access device has to configure the specified filter + + + + +Hakala, et al. Standards Track [Page 72] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + rules for the subscriber and MUST drop all the packets not matching + these filters. Zero, one, or more such AVPs MAY be present in a + Credit-Control-Answer message or in an AA answer message. + +8.37. Redirect-Server AVP + + The Redirect-Server AVP (AVP Code 434) is of type Grouped and + contains the address information of the redirect server (e.g., HTTP + redirect server, SIP Server) with which the end user is to be + connected when the account cannot cover the service cost. It MUST be + present when the Final-Unit-Action AVP is set to REDIRECT. + + It is defined as follows (per the grouped-avp-def of RFC 3588 + [DIAMBASE]): + + Redirect-Server ::= < AVP Header: 434 > + { Redirect-Address-Type } + { Redirect-Server-Address } + +8.38. Redirect-Address-Type AVP + + The Redirect-Address-Type AVP (AVP Code 433) is of type Enumerated + and defines the address type of the address given in the Redirect- + Server-Address AVP. + + The address type can be one of the following: + + IPv4 Address 0 + The address type is in the form of "dotted-decimal" IPv4 address, + as defined in [IPv4]. + + IPv6 Address 1 + The address type is in the form of IPv6 address, as defined in + [IPv6Addr]. The address is a text representation of the address + in either the preferred or alternate text form [IPv6Addr]. + Conformant implementations MUST support the preferred form and + SHOULD support the alternate text form for IPv6 addresses. + + URL 2 + The address type is in the form of Uniform Resource Locator, as + defined in [URL]. + + SIP URI 3 + The address type is in the form of SIP Uniform Resource + Identifier, as defined in [SIP]. + + + + + + +Hakala, et al. Standards Track [Page 73] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +8.39. Redirect-Server-Address AVP + + The Redirect-Server-Address AVP (AVP Code 435) is of type UTF8String + and defines the address of the redirect server (e.g., HTTP redirect + server, SIP Server) with which the end user is to be connected when + the account cannot cover the service cost. + +8.40. Multiple-Services-Indicator AVP + + The Multiple-Services-Indicator AVP (AVP Code 455) is of type + Enumerated and indicates whether the Diameter credit-control client + is capable of handling multiple services independently within a + (sub-) session. The absence of this AVP means that independent + credit-control of multiple services is not supported. + + A server not implementing the independent credit-control of multiple + services MUST treat the Multiple-Services-Indicator AVP as an invalid + AVP. + + The following values are defined for the Multiple-Services-Indicator + AVP: + + MULTIPLE_SERVICES_NOT_SUPPORTED 0 + Client does not support independent credit-control of multiple + services within a (sub-)session. + + MULTIPLE_SERVICES_SUPPORTED 1 + Client supports independent credit-control of multiple services + within a (sub-)session. + +8.41. Requested-Action AVP + + The Requested-Action AVP (AVP Code 436) is of type Enumerated and + contains the requested action being sent by Credit-Control-Request + command where the CC-Request-Type is set to EVENT_REQUEST. The + following values are defined for the Requested-Action AVP: + + DIRECT_DEBITING 0 + This indicates a request to decrease the end user's account + according to information specified in the Requested-Service-Unit + AVP and/or Service-Identifier AVP (additional rating information + may be included in service-specific AVPs or in the Service- + Parameter-Info AVP). The Granted-Service-Unit AVP in the Credit- + Control-Answer command contains the debited units. + + + + + + + +Hakala, et al. Standards Track [Page 74] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + REFUND_ACCOUNT 1 + This indicates a request to increase the end user's account + according to information specified in the Requested-Service-Unit + AVP and/or Service-Identifier AVP (additional rating information + may be included in service-specific AVPs or in the Service- + Parameter-Info AVP). The Granted-Service-Unit AVP in the Credit- + Control-Answer command contains the refunded units. + + CHECK_BALANCE 2 + This indicates a balance check request. In this case, the + checking of the account balance is done without any credit + reservation from the account. The Check-Balance-Result AVP in the + Credit-Control-Answer command contains the result of the balance + check. + + PRICE_ENQUIRY 3 + This indicates a price enquiry request. In this case, neither + checking of the account balance nor reservation from the account + will be done; only the price of the service will be returned in + the Cost-Information AVP in the Credit-Control-Answer Command. + +8.42. Service-Context-Id AVP + + The Service-Context-Id AVP is of type UTF8String (AVP Code 461) and + contains a unique identifier of the Diameter credit-control service + specific document that applies to the request (as defined in section + 4.1.2). This is an identifier allocated by the service provider, by + the service element manufacturer, or by a standardization body, and + MUST uniquely identify a given Diameter credit-control service + specific document. The format of the Service-Context-Id is: + + "service-context" "@" "domain" + + service-context = Token + + The Token is an arbitrary string of characters and digits. + + 'domain' represents the entity that allocated the Service-Context-Id. + It can be ietf.org, 3gpp.org, etc., if the identifier is allocated by + a standardization body, or it can be the FQDN of the service provider + (e.g., provider.example.com) or of the vendor (e.g., + vendor.example.com) if the identifier is allocated by a private + entity. + + This AVP SHOULD be placed as close to the Diameter header as + possible. + + + + + +Hakala, et al. Standards Track [Page 75] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Service-specific documents that are for private use only (i.e., to + one provider's own use, where no interoperability is deemed useful) + may define private identifiers without need of coordination. + However, when interoperability is wanted, coordination of the + identifiers via, for example, publication of an informational RFC is + RECOMMENDED in order to make Service-Context-Id globally available. + +8.43. Service-Parameter-Info AVP + + The Service-Parameter-Info AVP (AVP Code 440) is of type Grouped and + contains service-specific information used for price calculation or + rating. The Service-Parameter-Type AVP defines the service parameter + type, and the Service-Parameter-Value AVP contains the parameter + value. The actual contents of these AVPs are not within the scope of + this document and SHOULD be defined in another Diameter application, + in standards written by other standardization bodies, or in service- + specific documentation. + + In the case of an unknown service request (e.g., unknown Service- + Parameter-Type), the corresponding answer message MUST contain the + error code DIAMETER_RATING_FAILED. A Credit-Control-Answer message + with this error MUST contain one or more Failed-AVP AVPs containing + the Service-Parameter-Info AVPs that caused the failure. + + It is defined as follows (per the grouped-avp-def of RFC 3588 + [DIAMBASE]): + + Service-Parameter-Info ::= < AVP Header: 440 > + { Service-Parameter-Type } + { Service-Parameter-Value } + +8.44. Service-Parameter-Type AVP + + The Service-Parameter-Type AVP is of type Unsigned32 (AVP Code 441) + and defines the type of the service event specific parameter (e.g., + it can be the end-user location or service name). The different + parameters and their types are service specific, and the meanings of + these parameters are not defined in this document. Whoever allocates + the Service-Context-Id (i.e., unique identifier of a service-specific + document) is also responsible for assigning Service-Parameter-Type + values for the service and ensuring their uniqueness within the given + service. The Service-Parameter-Value AVP contains the value + associated with the service parameter type. + + + + + + + + +Hakala, et al. Standards Track [Page 76] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +8.45. Service-Parameter-Value AVP + + The Service-Parameter-Value AVP is of type OctetString (AVP Code 442) + and contains the value of the service parameter type. + +8.46. Subscription-Id AVP + + The Subscription-Id AVP (AVP Code 443) is used to identify the end + user's subscription and is of type Grouped. The Subscription-Id AVP + includes a Subscription-Id-Data AVP that holds the identifier and a + Subscription-Id-Type AVP that defines the identifier type. + + It is defined as follows (per the grouped-avp-def of RFC 3588 + [DIAMBASE]): + + Subscription-Id ::= < AVP Header: 443 > + { Subscription-Id-Type } + { Subscription-Id-Data } + +8.47. Subscription-Id-Type AVP + + The Subscription-Id-Type AVP (AVP Code 450) is of type Enumerated, + and it is used to determine which type of identifier is carried by + the Subscription-Id AVP. + + This specification defines the following subscription identifiers. + However, new Subscription-Id-Type values can be assigned by an IANA + designated expert, as defined in section 12. A server MUST implement + all the Subscription-Id-Types required to perform credit + authorization for the services it supports, including possible future + values. Unknown or unsupported Subscription-Id-Types MUST be treated + according to the 'M' flag rule, as defined in [DIAMBASE]. + + END_USER_E164 0 + The identifier is in international E.164 format (e.g., MSISDN), + according to the ITU-T E.164 numbering plan defined in [E164] and + [CE164]. + + END_USER_IMSI 1 + The identifier is in international IMSI format, according to the + ITU-T E.212 numbering plan as defined in [E212] and [CE212]. + + END_USER_SIP_URI 2 + The identifier is in the form of a SIP URI, as defined in [SIP]. + + END_USER_NAI 3 + The identifier is in the form of a Network Access Identifier, as + defined in [NAI]. + + + +Hakala, et al. Standards Track [Page 77] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + END_USER_PRIVATE 4 + The Identifier is a credit-control server private identifier. + +8.48. Subscription-Id-Data AVP + + The Subscription-Id-Data AVP (AVP Code 444) is used to identify the + end user and is of type UTF8String. The Subscription-Id-Type AVP + defines which type of identifier is used. + +8.49. User-Equipment-Info AVP + + The User-Equipment-Info AVP (AVP Code 458) is of type Grouped and + allows the credit-control client to indicate the identity and + capability of the terminal the subscriber is using for the connection + to network. + + It is defined as follows (per the grouped-avp-def of RFC 3588 + [DIAMBASE]): + + User-Equipment-Info ::= < AVP Header: 458 > + { User-Equipment-Info-Type } + { User-Equipment-Info-Value } + +8.50. User-Equipment-Info-Type AVP + + The User-Equipment-Info-Type AVP is of type Enumerated (AVP Code + 459) and defines the type of user equipment information contained in + the User-Equipment-Info-Value AVP. + + This specification defines the following user equipment types. + However, new User-Equipment-Info-Type values can be assigned by an + IANA designated expert, as defined in section 12. + + IMEISV 0 + The identifier contains the International Mobile Equipment + Identifier and Software Version in the international IMEISV format + according to 3GPP TS 23.003 [3GPPIMEI]. + + MAC 1 + The 48-bit MAC address is formatted as described in [RAD802.1X]. + + EUI64 2 + The 64-bit identifier used to identify hardware instance of the + product, as defined in [EUI64]. + + + + + + + +Hakala, et al. Standards Track [Page 78] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + MODIFIED_EUI64 3 + There are a number of types of terminals that have identifiers + other than IMEI, IEEE 802 MACs, or EUI-64. These identifiers can + be converted to modified EUI-64 format as described in [IPv6Addr] + or by using some other methods referred to in the service-specific + documentation. + +8.51. User-Equipment-Info-Value AVP + + The User-Equipment-Info-Value AVP (AVP Code 460) is of type + OctetString. The User-Equipment-Info-Type AVP defines which type of + identifier is used. + +9. Result Code AVP Values + + This section defines new Result-Code AVP [DIAMBASE] values that must + be supported by all Diameter implementations that conform to this + specification. + + The Credit-Control-Answer message includes the Result-Code AVP, which + may indicate that an error was present in the Credit-Control-Request + message. A rejected Credit-Control-Request message SHOULD cause the + user's session to be terminated. + +9.1. Transient Failures + + Errors that fall within the transient failures category are used to + inform a peer that the request could not be satisfied at the time it + was received, but that the request MAY be able to be satisfied in the + future. + + DIAMETER_END_USER_SERVICE_DENIED 4010 + The credit-control server denies the service request due to + service restrictions. If the CCR contained used-service-units, + they are deducted, if possible. + + DIAMETER_CREDIT_CONTROL_NOT_APPLICABLE 4011 + The credit-control server determines that the service can be + granted to the end user but that no further credit-control is + needed for the service (e.g., service is free of charge). + + DIAMETER_CREDIT_LIMIT_REACHED 4012 + The credit-control server denies the service request because the + end user's account could not cover the requested service. If the + CCR contained used-service-units they are deducted, if possible. + + + + + + +Hakala, et al. Standards Track [Page 79] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +9.2. Permanent Failures + + Errors that fall within the permanent failure category are used to + inform the peer that the request failed and should not be attempted + again. + + DIAMETER_USER_UNKNOWN 5030 + The specified end user is unknown in the credit-control server. + + DIAMETER_RATING_FAILED 5031 + This error code is used to inform the credit-control client that + the credit-control server cannot rate the service request due to + insufficient rating input, an incorrect AVP combination, or an AVP + or an AVP value that is not recognized or supported in the rating. + The Failed-AVP AVP MUST be included and contain a copy of the + entire AVP(s) that could not be processed successfully or an + example of the missing AVP complete with the Vendor-Id if + applicable. The value field of the missing AVP should be of + correct minimum length and contain zeros. + +10. AVP Occurrence Table + + The following table presents the AVPs defined in this document and + specifies in which Diameter messages they MAY or MAY NOT be present. + Note that AVPs that can only be present within a Grouped AVP are not + represented in this table. + + The table uses the following symbols: + + 0 The AVP MUST NOT be present in the message. + 0+ Zero or more instances of the AVP MAY be present in the + message. + 0-1 Zero or one instance of the AVP MAY be present in the + message. It is considered an error if there is more + than one instance of the AVP. + 1 One instance of the AVP MUST be present in the message. + 1+ At least one instance of the AVP MUST be present in the + message. + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 80] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +10.1. Credit-Control AVP Table + + The table in this section is used to represent which credit-control + applications specific AVPs defined in this document are to be present + in the credit-control messages. + + +-----------+ + | Command | + | Code | + |-----+-----+ + Attribute Name | CCR | CCA | + ------------------------------|-----+-----+ + Acct-Multi-Session-Id | 0-1 | 0-1 | + Auth-Application-Id | 1 | 1 | + CC-Correlation-Id | 0-1 | 0 | + CC-Session-Failover | 0 | 0-1 | + CC-Request-Number | 1 | 1 | + CC-Request-Type | 1 | 1 | + CC-Sub-Session-Id | 0-1 | 0-1 | + Check-Balance-Result | 0 | 0-1 | + Cost-Information | 0 | 0-1 | + Credit-Control-Failure- | 0 | 0-1 | + Handling | | | + Destination-Host | 0-1 | 0 | + Destination-Realm | 1 | 0 | + Direct-Debiting-Failure- | 0 | 0-1 | + Handling | | | + Event-Timestamp | 0-1 | 0-1 | + Failed-AVP | 0 | 0+ | + Final-Unit-Indication | 0 | 0-1 | + Granted-Service-Unit | 0 | 0-1 | + Multiple-Services-Credit- | 0+ | 0+ | + Control | | | + Multiple-Services-Indicator | 0-1 | 0 | + Origin-Host | 1 | 1 | + Origin-Realm | 1 | 1 | + Origin-State-Id | 0-1 | 0-1 | + Proxy-Info | 0+ | 0+ | + Redirect-Host | 0 | 0+ | + Redirect-Host-Usage | 0 | 0-1 | + Redirect-Max-Cache-Time | 0 | 0-1 | + Requested-Action | 0-1 | 0 | + Requested-Service-Unit | 0-1 | 0 | + Route-Record | 0+ | 0+ | + Result-Code | 0 | 1 | + Service-Context-Id | 1 | 0 | + Service-Identifier | 0-1 | 0 | + Service-Parameter-Info | 0+ | 0 | + + + +Hakala, et al. Standards Track [Page 81] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Session-Id | 1 | 1 | + Subscription-Id | 0+ | 0 | + Termination-Cause | 0-1 | 0 | + User-Equipment-Info | 0-1 | 0 | + Used-Service-Unit | 0+ | 0 | + User-Name | 0-1 | 0-1 | + Validity-Time | 0 | 0-1 | + ------------------------------|-----+-----+ + +10.2. Re-Auth-Request/Answer AVP Table + + This section defines AVPs that are specific to the Diameter credit- + control application and that MAY be included in the Diameter Re- + Auth-Request/Answer (RAR/RAA) message [DIAMBASE]. + + Re-Auth-Request/Answer command MAY include the following additional + AVPs: + + +---------------+ + | Command Code | + |-------+-------+ + Attribute Name | RAR | RAA | + ------------------------------+-------+-------+ + CC-Sub-Session-Id | 0-1 | 0-1 | + G-S-U-Pool-Identifier | 0-1 | 0-1 | + Service-Identifier | 0-1 | 0-1 | + Rating-Group | 0-1 | 0-1 | + ------------------------------+-------+-------+ + +11. RADIUS/Diameter Credit-Control Interworking Model + + This section defines the basic principles for the Diameter credit- + control/RADIUS prepaid inter-working model; that is, a message + translation between a RADIUS based prepaid solution and a Diameter + credit-control application. A complete description of the protocol + translations between RADIUS and the Diameter credit-control + application is beyond the scope of this specification and SHOULD be + addressed in another appropriate document, such as the RADIUS prepaid + specification. + + The Diameter credit-control architecture may have a Translation Agent + capable of translation between RADIUS prepaid and Diameter credit- + control protocols. An AAA server (usually the home AAA server) may + act as a Translation Agent and as a Diameter credit-control client + for service elements that use credit-control mechanisms other than + Diameter credit control for instance, RADIUS prepaid. In this case, + the home AAA server contacts the Diameter credit-control server as + part of the authorization process. The interworking architecture is + + + +Hakala, et al. Standards Track [Page 82] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + illustrated in Figure 7, and interworking flow in Figure 8. In a + roaming situation the service element (e.g., the NAS) may be located + in the visited network, and a visited AAA server is usually + contacted. The visited AAA server connects then to the home AAA + server. + + RADIUS Prepaid + +--------+ +---------+ protocol +------------+ +--------+ + | End |<----->| Service |<---------->| Home AAA | |Business| + | User | | Element | | Server | |Support | + +--------+ +-->| | |+----------+|->|System | + | +---------+ ||CC Client || | | + | |+----------+| | | + +--------+ | +------^-----+ +----^---+ + | End |<--+ Credit-Control | | + | User | Protocol | | + +--------+ +-------V--------+ | + |Credit-Control |----+ + | Server | + +----------------+ + + Figure 7: Credit-control architecture with service element + containing translation agent, translating RADIUS + prepaid to Diameter credit-control protocol + + When the AAA server acting as a Translation Agent receives an initial + RADIUS Access-Request message from service element (e.g., NAS + access), it performs regular authentication and authorization. If + the RADIUS Access-Request message indicates that the service element + is capable of credit-control, and if the home AAA server finds that + the subscriber is a prepaid subscriber, then a Diameter credit- + control request SHOULD be sent toward the credit-control server to + perform credit authorization and to establish a credit-control + session. After the Diameter credit-control server checks the end + user's account balance, rates the service, and reserves credit from + the end user's account, the reserved quota is returned to the home + AAA server in the Diameter Credit-Control-Answer. Then the home AAA + server sends the reserved quota to the service element in the RADIUS + Access-Accept. + + At the expiry of the allocated quota, the service element sends a new + RADIUS Access-Request containing the units used this far to the home + AAA server. The home AAA server shall map a RADIUS Access-Request + containing the reported units to the Diameter credit-control server + in a Diameter Credit-Control-Request (UPDATE_REQUEST). The Diameter + credit-control server debits the used units from the end user's + account and allocates a new quota that is returned to the home AAA + server in the Diameter Credit-Control-Answer. The quota is + + + +Hakala, et al. Standards Track [Page 83] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + transferred to the service element in the RADIUS Access-Accept. When + the end user terminates the service, or when the entire quota has + been used, the service element sends a RADIUS Access-Request. To + debit the used units from the end user's account and to stop the + credit-control session, the home AAA server sends a Diameter Credit- + Control-Request (TERMINATION_REQUEST) to the credit-control server. + The Diameter credit-control server acknowledges the session + termination by sending a Diameter Credit-Control-Answer to the home + AAA server. The RADIUS Access-Accept is sent to the NAS. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 84] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + A following diagram illustrates a RADIUS prepaid - Diameter credit- + control interworking sequence. + + Service Element Translation Agent + (e.g., NAS) (CC Client) CC Server + | Access-Request | | + |----------------------->| | + | | CCR (initial) | + | |----------------------->| + | | CCA (Granted-Units) | + | |<-----------------------| + | Access-Accept | | + | (Granted-Units) | | + |<-----------------------| | + : : : + | Access-Request | | + | (Used-Units) | | + |----------------------->| | + | | CCR (update, | + | | Used-Units) | + | |----------------------->| + | | CCA (Granted-Units) | + | |<-----------------------| + | Access-Accept | | + | (Granted-Units) | | + |<-----------------------| | + : : : + | Access-Request | | + |----------------------->| | + | | CCR (terminate, | + | | Used-Units) | + | |----------------------->| + | | CCA | + | |<-----------------------| + | Access-Accept | | + |<-----------------------| | + | | | + + Figure 8: Message flow example with RADIUS prepaid - + Diameter credit-control interworking + +12. IANA Considerations + + This section contains the namespaces that have either been created in + this specification, or the values assigned to existing namespaces + managed by IANA. + + + + + +Hakala, et al. Standards Track [Page 85] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + In the subsections below, when we speak about review by a Designated + Expert, please note that the designated expert will be assigned by + the IESG. Initially, such Expert discussions take place on the AAA + WG mailing list. + +12.1. Application Identifier + + This specification assigns the value 4, 'Diameter Credit Control', to + the Application Identifier namespace defined in [DIAMBASE]. See + section 1.3 for more information. + +12.2. Command Codes + + This specification uses the value 272 from the Command code namespace + defined in [DIAMBASE] for the Credit-Control-Request (CCR) and + Credit-Control-Answer (CCA) commands. + +12.3. AVP Codes + + This specification assigns the values 411 - 461 from the AVP code + namespace defined in [DIAMBASE]. See section 8 for the assignment of + the namespace in this specification. + +12.4. Result-Code AVP Values + + This specification assigns the values 4010, 4011, 4012, 5030, 5031 + from the Result-Code AVP value namespace defined in [DIAMBASE]. See + section 9 for the assignment of the namespace in this specification. + +12.5. CC-Request-Type AVP + + As defined in section 8.3, the CC-Request-Type AVP includes + Enumerated type values 1 - 4. IANA has created and is maintaining a + namespace for this AVP. All remaining values are available for + assignment by a Designated Expert [IANA]. + +12.6. CC-Session-Failover AVP + + As defined in section 8.4, the CC-Failover-Supported AVP includes + Enumerated type values 0 - 1. IANA has created and is maintaining a + namespace for this AVP. All remaining values are available for + assignment by a Designated Expert [IANA]. + + + + + + + + + +Hakala, et al. Standards Track [Page 86] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +12.7. CC-Unit-Type AVP + + As defined in section 8.32, the CC-Unit-Type AVP includes Enumerated + type values 0 - 5. IANA has created and is maintaining a namespace + for this AVP. All remaining values are available for assignment by a + Designated Expert [IANA]. + +12.8. Check-Balance-Result AVP + + As defined in section 8.6, the Check-Balance-Result AVP includes + Enumerated type values 0 - 1. IANA has created and is maintaining a + namespace for this AVP. All remaining values are available for + assignment by a Designated Expert [IANA]. + +12.9. Credit-Control AVP + + As defined in section 8.13, the Credit-Control AVP includes + Enumerated type values 0 - 1. IANA has created and is maintaining a + namespace for this AVP. All remaining values are available for + assignment by a Designated Expert [IANA]. + +12.10. Credit-Control-Failure-Handling AVP + + As defined in section 8.14, the Credit-Control-Failure-Handling AVP + includes Enumerated type values 0 - 2. IANA has created and is + maintaining a namespace for this AVP. All remaining values are + available for assignment by a Designated Expert [IANA]. + +12.11. Direct-Debiting-Failure-Handling AVP + + As defined in section 8.15, the Direct-Debiting-Failure-Handling AVP + includes Enumerated type values 0 - 1. IANA has created and is + maintaining a namespace for this AVP. All remaining values are + available for assignment by a Designated Expert [IANA]. + +12.12. Final-Unit-Action AVP + + As defined in section 8.35, the Final-Unit-Action AVP includes + Enumerated type values 0 - 2. IANA has created and is maintaining a + namespace for this AVP. All remaining values are available for + assignment by a Designated Expert [IANA]. + +12.13. Multiple-Services-Indicator AVP + + As defined in section 8.40, the Multiple-Services-Indicator AVP + includes Enumerated type values 0 - 1. IANA has created and is + maintaining a namespace for this AVP. All remaining values are + available for assignment by a Designated Expert [IANA]. + + + +Hakala, et al. Standards Track [Page 87] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +12.14. Redirect-Address-Type AVP + + As defined in section 8.38, the Redirect-Address-Type AVP includes + Enumerated type values 0 - 3. IANA has created and is maintaining a + namespace for this AVP. All remaining values are available for + assignment by a Designated Expert [IANA]. + +12.15. Requested-Action AVP + + As defined in section 8.41, the Requested-Action AVP includes + Enumerated type values 0 - 3. IANA has created and is maintaining a + namespace for this AVP. All remaining values are available for + assignment by a Designated Expert [IANA]. + +12.16. Subscription-Id-Type AVP + + As defined in section 8.47, the Subscription-Id-Type AVP includes + Enumerated type values 0 - 4. IANA has created and is maintaining a + namespace for this AVP. All remaining values are available for + assignment by a Designated Expert [IANA]. + +12.17. Tariff-Change-Usage AVP + + As defined in section 8.27, the Tariff-Change-Usage AVP includes + Enumerated type values 0 - 2. IANA has created and is maintaining a + namespace for this AVP. All remaining values are available for + assignment by a Designated Expert [IANA]. + +12.18. User-Equipment-Info-Type AVP + + As defined in section 8.50, the User-Equipment-Info-Type AVP includes + Enumerated type values 0 - 3. IANA has created and is maintaining a + namespace for this AVP. All remaining values are available for + assignment by a Designated Expert [IANA]. + +13. Credit-Control Application Related Parameters + + Tx timer + + When real-time credit-control is required, the credit-control + client contacts the credit-control server before and while the + service is provided to an end user. Due to the real-time nature + of the application, the communication delays SHOULD be minimized; + e.g., to avoid an overly long service setup time experienced by + the end user. The Tx timer is introduced to control the waiting + time in the client in the Pending state. When the Tx timer + elapses, the credit-control client takes an action to the end user + according to the value of the Credit-Control-Failure-Handling AVP + + + +Hakala, et al. Standards Track [Page 88] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + or Direct-Debiting-Failure-Handling AVP. The recommended value is + 10 seconds. + + Tcc timer + + The Tcc timer supervises an ongoing credit-control session in the + credit-control server. It is RECOMMENDED to use the Validity-Time + as input to set the Tcc timer value. In case of transient + failures in the network, the Diameter credit-control server might + change to Idle state. To avoid this, the Tcc timer MAY be set so + that Tcc equals to 2 x Validity-Time. + + Credit-Control-Failure-Handling and Direct-Debiting-Failure-Handling + + Client implementations may offer the possibility of locally + configuring these AVPs. In such a case their value and behavior + is defined in section 5.7 for the Credit-Control-Failure-Handling + and in section 6.5 for the Direct-Debiting-Failure-Handling. + +14. Security Considerations + + The Diameter base protocol [DIAMBASE] requires that each Diameter + implementation use underlying security; i.e., IPsec or TLS. These + mechanisms are believed to provide sufficient protection under the + normal Internet threat model; that is, assuming that the authorized + nodes engaging in the protocol have not been compromised, but that + the attacker has complete control over the communication channels + between them. This includes eavesdropping, message modification, + insertion, and man-in-the-middle and replay attacks. Note also that + this application includes a mechanism for application layer replay + protection by means of the Session-Id from [DIAMBASE] and CC- + Request-Number, which is specified in this document. The Diameter + credit-control application is often used within one domain, and there + may be a single hop between the peers. In these environments, the + use of TLS or IPsec is sufficient. The details of TLS and IPsec + related security considerations are discussed in the [DIAMBASE]. + + Because this application handles monetary transactions (directly or + indirectly), it increases the interest for various security attacks. + Therefore, all parties communicating with each other MUST be + authenticated, including, for instance, TLS client-side + authentication. In addition, authorization of the client SHOULD be + emphasized; i.e., that the client is allowed to perform credit- + control for a certain user. The specific means of authorization are + outside of the scope of this specification but can be, for instance, + manual configuration. + + + + + +Hakala, et al. Standards Track [Page 89] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Another kind of threat is malicious modification, injection, or + deletion of AVPs or complete credit-control messages. The credit- + control messages contain sensitive billing related information (such + as subscription Id, granted units, used units, cost information) + whose malicious modification can have financial consequences. + Sometimes simply delaying the credit-control messages can cause + disturbances in the credit-control client or server. + + Even without any modification to the messages, an adversary can + invite a security threat by eavesdropping, as the transactions + contain private information about the user. Also, by monitoring the + credit-control messages one can collect information about the + credit-control server's billing models and business relationships. + + When third-party relays or proxy are involved, the hop-by-hop + security does not necessarily provide sufficient protection for + Diameter user session. In some cases, it may be inappropriate to + send Diameter messages, such as CCR and CCA, containing sensitive + AVPs via untrusted Diameter proxy agents, as there are no assurances + that third-party proxies will not modify the credit-control commands + or AVP values. + +14.1. Direct Connection with Redirects + + A Diameter credit-control agent cannot always know whether agents + between it and the end user's Diameter credit-control server are + reliable. In this case, the Diameter credit-control agent doesn't + have a routing entry in its Diameter Routing Table (defined in + [DIAMBASE], section 2.7) for the realm of the credit-control server + in the end user's home domain. The Diameter credit-control agent can + have a default route configured to a local Redirect agent, and it + redirects the CCR message to the redirect agent. The local Redirect + agent then returns a redirect notification (Result-code 3006, + DIAMETER_REDIRECT_INDICATION) to the credit-control agent, as well as + Diameter credit-control server(s) information (Redirect-Host AVP) and + information (Redirect-Host-Usage AVP) about how the routing entry + resulting from the Redirect-Host is to be used. The Diameter + credit-control agent then forwards the CCR message directly to one of + the hosts identified by the CCA message from the redirect agent. If + the value of the Redirect-Host-Usage AVP is unequal to zero, all + following messages are sent to the host specified in the Redirect- + Host AVP until the time specified by the Redirect-Max-Cache-Time AVP + is expired. + + There are some authorization issues even with redirects. There may + be attacks toward nodes that have been properly authorized, but that + abuse their authorization or have been compromised. These issues are + discussed more widely in [DIAMEAP], section 8. + + + +Hakala, et al. Standards Track [Page 90] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +15. References + +15.1. Normative References + + [DIAMBASE] Calhoun, P., Loughney, J., Guttman, E., Zorn, G., and J. + Arkko, "Diameter Base Protocol", RFC 3588, September + 2003. + + [3GPPCHARG] 3rd Generation Partnership Project; Technical + Specification Group Services and System Aspects, Service + aspects; Charging and Billing, (release 5), 3GPP TS + 22.115 v. 5.2.1, 2002-03. + + [SIP] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, + A., Peterson, J., Sparks, R., Handley, M., and E. + Schooler, "SIP: Session Initiation Protocol", RFC 3261, + June 2002. + + [NAI] Aboba, B. and M. Beadles, "The Network Access + Identifier", RFC 2486, January 1999. + + [E164] Recommendation E.164/I.331 (05/97): The International + Public Telecommunication Numbering Plan. 1997. + + [CE164] Complement to ITU-T Recommendation E.164 (05/1997):"List + of ITU-T Recommendation E.164 assigned country codes", + June 2000. + + [E212] Recommendation E.212 (11/98): The international + identification plan for mobile terminals and mobile + users. 1998. + + [CE212] Complement to ITU-T Recommendation E.212 (11/1997):" List + of mobile country or geographical area codes", February + 1999. + + [IANA] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 2434, + October 1998. + + [IPv4] Postel, J., "Internet Protocol", STD 5, RFC 791, + September 1981. + + [IPv6Addr] Hinden, R. and S. Deering, "Internet Protocol Version 6 + (IPv6) Addressing Architecture", RFC 3513, April 2003. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + + +Hakala, et al. Standards Track [Page 91] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + [ISO4217] Codes for the representation of currencies and funds, + International Standard ISO 4217,2001 + + [NASREQ] Calhoun, P., Zorn, G., Spence, D., and D. Mitton, + "Diameter Network Access Server Application", RFC 4005, + August 2005. + + [AAATRANS] Aboba, B. and J. Wood, "Authentication, Authorization and + Accounting (AAA) Transport Profile", RFC 3539, June 2003. + + [URL] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform + Resource Locators (URL)", RFC 1738, December 1994. + + [RAD802.1X] Congdon, P., Aboba, B., Smith, A., Zorn, G., and J. + Roese, "IEEE 802.1X Remote Authentication Dial In User + Service (RADIUS) Usage Guidelines", RFC 3580, September + 2003. + + [EUI64] IEEE, "Guidelines for 64-bit Global Identifier (EUI-64) + Registration Authority", + http://standards.ieee.org/regauth/oui/tutorials/ + EUI64.html March 1997. + + [3GPPIMEI] 3rd Generation Partnership Project; Technical + Specification Group Core Network, Numbering, addressing + and identification, (release 5), 3GPP TS 23.003 v. 5.8.0, + 2003-12 + +15.2. Informative References + + [RFC2866] Rigney, C., "RADIUS Accounting", RFC 2866, June 2000. + + [DIAMMIP] Calhoun, P., Johansson, T., Perkins, C., Hiller, T., and + P. McCann, "Diameter Mobile IPv4 Application", RFC 4004, + August 2005. + + [DIAMEAP] Eronen, P., Hiller, T., and G. Zorn, "Diameter Extensible + Authentication Protocol (EAP) Application", Work in + Progress. + + [RFC3725] Rosenberg, J., Peterson, J., Schulzrinne, H., and G. + Camarillo, "Best Current Practices for Third Party Call + Control (3pcc) in the Session Initiation Protocol (SIP)", + BCP 85, RFC 3725, April 2004. + + + + + + + +Hakala, et al. Standards Track [Page 92] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +16. Acknowledgements + + The authors would like to thank Bernard Aboba, Jari Arkko, Robert + Ekblad, Pasi Eronen, Benny Gustafsson, Robert Karlsson, Avi Lior, + Paco Marin, Jussi Maki, Jeff Meyer, Anne Narhi, John Prudhoe, + Christopher Richards, Juha Vallinen, and Mark Watson for their + comments and suggestions. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 93] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +Appendix A. Credit-Control Sequences + +A.1. Flow I + + NAS + End User (CC Client) AAA Server CC Server + |(1)User Logon |(2)AA Request (CC AVPs) | + |------------------>|------------------->| | + | | |(3)CCR(initial, CC AVPs) + | | |------------------->| + | | | (4)CCA(Granted-Units) + | | |<-------------------| + | |(5)AA Answer(Granted-Units) | + |(6)Access granted |<-------------------| | + |<----------------->| | | + | | | | + : : : : + | |(7)CCR(update,Used-Units) | + | |------------------->|(8)CCR | + | | | (update,Used-Units) + | | |------------------->| + | | |(9)CCA(Granted-Units) + | |(10)CCA(Granted-Units)<------------------| + | |<-------------------| | + : : : : + | (Auth. lifetime expires) | | + | |(11) AAR (CC AVP) | | + | |------------------->| | + | | (12) AAA | | + | |<-------------------| | + : : : : + : : : : + |(13) User logoff | | | + |------------------>|(14)CCR(term.,Used-Units) | + | |------------------->|(15)CCR | + | | | (term.,Used-Units) + | | |------------------->| + | | | (16)CCA | + | | (17)CCA |<-------------------| + | |<-------------------| | + | |(18)STR | | + | |------------------->| | + | | (19)STA | | + | |<-------------------| | + + Figure A.1: Flow I + + + + + +Hakala, et al. Standards Track [Page 94] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + A credit-control flow for Network Access Services prepaid is shown in + Figure A.1. The Diameter [NASREQ] is implemented in the Network + Access Server (NAS). The focus of this flow is in the credit + authorization. + + The user logs on to the network (1). The Diameter NAS sends a + Diameter AA-Request (AAR) to the home Diameter AAA server. The + credit-control client populates the AAR with the Credit-Control AVP + set to CREDIT_AUTHORIZATION, and service-specific AVPs are included, + as usual [NASREQ]. The home Diameter AAA server performs service- + specific Authentication and Authorization, as usual. The home + Diameter AAA server determines that the user is a prepaid user and + notices from the Credit-Control AVP that the NAS has credit-control + capabilities. It sends a Diameter Credit-Control-Request with CC- + Request-Type set to INITIAL_REQUEST to the Diameter credit-control + server to perform credit authorization (3) and to establish a + credit-control session. (The home Diameter AAA server may forward + service-specific AVPs received from the NAS as input for the rating + process.) The Diameter credit-control server checks the end user's + account balance, rates the service, and reserves credit from the end + user's account. The reserved quota is returned to the home Diameter + AAA server in the Diameter Credit-Control-Answer (4). The home + Diameter AAA server sends the reserved quota to the NAS in the + Diameter AA-Answer (AAA). Upon successful AAA, the NAS starts the + credit-control session and starts monitoring the granted units (5). + The NAS grants access to the end user (6). At the expiry of the + allocated quota, the NAS sends a Diameter Credit-Control-Request with + CC-Request-Type set to UPDATE_REQUEST to the Home Diameter AAA server + (7). This message contains the units used thus far. The home + Diameter AAA server forwards the CCR to the Diameter credit-control + server (8). The Diameter credit-control server debits the used units + from the end user's account and allocates a new quota that is + returned to the home Diameter AAA server in the Diameter Credit- + Control-Answer (9). The message is forwarded to the NAS (10). + During the ongoing credit-control session, the authorization lifetime + expires, and the authorization/authentication client in the NAS + performs service specific re-authorization to the home Diameter AAA + server, as usual. The credit-control client populates the AAR with + the Credit-Control AVP set to RE_AUTHORIZATION, indicating that the + credit-control server shall not be contacted, as the credit + authorization is controlled by the burning rate of the granted units + (11). The home Diameter AAA server performs service-specific re- + authorization as usual and returns the AA-Answer to the NAS (12). + The end user logs off from the network (13). To debit the used units + from the end user's account and to stop the credit-control session, + the NAS sends a Diameter Credit-Control-Request with CC-Request-Type + set to TERMINATION_REQUEST to the home Diameter AAA server (14). The + home Diameter AAA server forwards the CCR to the credit-control + + + +Hakala, et al. Standards Track [Page 95] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + server (15). The Diameter credit-control server acknowledges the + session termination by sending a Diameter Credit-Control-Answer to + the home Diameter AAA server (16). The home Diameter AAA server + forwards the answer to the NAS (17). STR/STA takes place between the + NAS and home Diameter AAA server, as usual (18-19). + +A.2. Flow II + + SIP Proxy/Registrar AAA + A (CC Client) Server B CC Server + |(i) REGISTER | | | | + |------------->|(ii) | | | + | |------------->| | | + | |authentication & | | + | |authorization | | | + | |<-------------| | | + |(iii)200 OK | | | + |<-------------| | | + : : : : + |(1) INVITE | : + |------------->| + | |(2) CCR (Initial, SIP specific AVP) | + | |------------------------------------------->| + | |(3) CCA (Granted-Units) | + | |<-------------------------------------------| + | |(4) INVITE | | + | |---------------------------->| | + : : : : + | |(5) CCR (update, Used-Units) | + | |------------------------------------------->| + | |(6) CCA (Granted-Units) | + | |<-------------------------------------------| + : : : : + |(7) BYE | | | + |------------->| | | + | |(8) BYE | | + | |---------------------------->| | + | |(9) CCR (termination, Used-Units) | + | |------------------------------------------->| + | |(10) CCA () | + | |<-------------------------------------------| + | | | | + + Figure A.2: Flow II + + + + + + + +Hakala, et al. Standards Track [Page 96] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + This is an example of Diameter credit-control for SIP sessions. + Although the flow focuses on illustrating the usage of credit-control + messages, the SIP signaling is inaccurate, and the diagram is not by + any means an attempt to define a service provider's SIP network. + However, for the sake of this example, some assumptions are made + below. + + Typically, prepaid services based, for example, on time usage for SIP + session require an entity in the service provider network to + intercept all the requests within the SIP dialog in order to detect + events, such as session establishment and session release, that are + essential to perform credit-control operations with the credit- + control server. Therefore, in this example, it is assumed that the + SIP Proxy adds a Record-Route header in the initial SIP INVITE to + make sure that all the future requests in the created dialog traverse + through it (for the definitions of 'Record-Route' and 'dialog' please + refer to [SIP]). Finally, the degree of credit-control measuring of + the media by the proxy depends on the business model design used in + setting up the end system and proxies in the SIP network. + + The end user (SIP User Agent A) sends REGISTER with credentials (i). + The SIP Proxy sends a request to the home AAA server to perform + Multimedia authentication and authorization by using, for instance, + Diameter Multimedia application (ii). The home AAA server checks + that the credentials are correct and checks the user profile. + Eventually, 200 OK response (iii) is sent to the UA. Note that the + Authentication and Authorization is valid for the registration + validity period duration (i.e., until re-registration is performed). + Several SIP sessions may be established without re-authorization. + + UA A sends an INVITE (1). The SIP Proxy sends a Diameter Credit- + Control-Request (INITIAL_REQUEST) to the Diameter credit-control + server (2). The Credit-Control-Request contains information obtained + from the SIP signaling describing the requested service (e.g., + calling party, called party, Session Description Protocol + attributes). The Diameter credit-control server checks the end + user's account balance, rates the service, and reserves credit from + the end user's account. The reserved quota is returned to the SIP + Proxy in the Diameter Credit-Control-Answer (3). The SIP Proxy + forwards the SIP INVITE to UA B (4). B's phone rings, and B answers. + The media flows between them, and the SIP Proxy starts measuring the + quota. At the expiry of the allocated quota, the SIP Proxy sends a + Diameter Credit-Control-Request (UPDATE_REQUEST) to the Diameter + credit-control server (5). This message contains the units used thus + far. The Diameter credit-control server debits the used units from + the end user's account and allocates new credit that is returned to + the SIP Proxy in the Diameter Credit-Control-Answer (6). The end + user terminates the service by sending a BYE (7). The SIP Proxy + + + +Hakala, et al. Standards Track [Page 97] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + forwards the BYE message to UA B (8) and sends a Diameter Credit- + Control-Request (TERMINATION_REQUEST) to the credit-control server + (9). The Diameter credit-control server acknowledges the session + termination by sending a Diameter Credit-Control-Answer to the SIP + Proxy (10). + +A.3. Flow III + + MMS Server + A (CC Client) B CC Server + |(1) Send MMS | | | + |--------------->| | | + | |(2) CCR (event, DIRECT_DEBITING,| + | | MMS specific AVP) | + | |-------------------------------->| + | |(3) CCA (Granted-Units) | + | |<--------------------------------| + |(4) Send MMS Ack| | | + |<---------------| | | + | |(5) Notify MMS | | + | |--------------->| | + : : : : + | |(6) Retrieve MMS| | + | |<---------------| | + | |(7) Retrieve MMS| | + | | Ack | | + | |--------------->| | + | | | | + + Figure A.3: Flow III + + A credit-control flow for Multimedia Messaging Services is shown in + Figure A.3. The sender is charged as soon as the messaging server + successfully stores the message. + + The end user A sends a Multimedia Message (MMS) to the MMS server + (1). The MMS server stores the message and sends a Diameter Credit- + Control-Request (EVENT_REQUEST with Requested-Action DIRECT_DEBITING) + to the Diameter credit-control server (2). The Credit-Control- + Request contains information about the MMS message (e.g., size, + recipient address, image coding type). The Diameter credit-control + server checks the end user's account balance, rates the service, and + debits the service from the end user's account. The granted quota is + returned to the MMS server in the Diameter Credit-Control-Answer (3). + The MMS server acknowledges the successful reception of the MMS + message (4). The MMS Server notifies the recipient about the new MMS + (5), and end user B retrieves the message from the MMS message store + (6),(7). + + + +Hakala, et al. Standards Track [Page 98] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +A.4. Flow IV + + MMS Server + Content Server (CC Client) B CC Server + |(1) Send MMS | | | + |--------------->| | | + | |(2) CCR (event, CHECK_BALANCE, | + | | MMS specific AVP) | + | |-------------------------------->| + | |(3) CCA (ENOUGH_CREDIT) | + | |<--------------------------------| + |(4) Send MMS Ack| | | + |<---------------| | | + | |(5) Notify MMS | | + | |--------------->| | + : : : : + | |(6) Retrieve MMS| | + | |<---------------| | + | |(7) CCR (event, DIRECT_DEBITING,| + | | MMS specific AVP) | + | |-------------------------------->| + | |(8) CCA (Granted-Units) | + | |<--------------------------------| + | |(9) Retrieve MMS| | + | | Ack | | + | |--------------->| | + | | | | + + Figure A.4: Flow IV + + This is an example of Diameter credit-control for direct debiting + using the Multimedia Messaging Service environment. Although the + flow focuses on illustrating the usage of credit-control messages, + the MMS signaling is inaccurate, and the diagram is not by any means + an attempt to define any service provider's MMS configuration or + billing model. + + A credit-control flow for Multimedia Messaging Service is shown in + Figure A.4. The recipient is charged at the message delivery. + + A content server sends a Multimedia Message (MMS) to the MMS server + (1) that stores the message. The message recipient will be charged + for the MMS message in this case. As there can be a substantially + long time between the receipt of the message at the MMS server and + the actual retrieval of the message, the MMS server does not + establish any credit-control session to the Diameter credit-control + server but performs first only a balance check (without any credit + reservation) by sending a Diameter Credit-Control-Request + + + +Hakala, et al. Standards Track [Page 99] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + (EVENT_REQUEST with Requested-Action CHECK_BALANCE) to verify that + end user B can cover the cost for the MMS (2). The Diameter credit- + control server checks the end user's account balance and returns the + answer to the MMS server in the Diameter Credit-Control-Answer (3). + The MMS server acknowledges the successful reception of the MMS + message (4). The MMS server notifies the recipient of the new MMS + (5), and after some time end user B retrieves the message from the + MMS message store (6). The MMS server sends a Diameter Credit- + Control-Request (EVENT_REQUEST with Requested-Action: + DIRECT_DEBITING) to the Diameter credit-control server (7). The + Credit-Control-Request contains information about the MMS message + (e.g., size, recipient address, coding type). The Diameter credit- + control server checks the end user's account balance, rates the + service, and debits the service from the end user's account. The + granted quota is returned to the MMS server in the Diameter Credit- + Control-Request (8). The MMS is transferred to end user B (9). + + Note that the transfer of the MMS message can take an extended time + and can fail, in which case a recovery action is needed. The MMS + server should return the already debited units to the user's account + by using the REFUND action described in section 6.4. + +A.5. Flow V + + SIP Controller + A (CC Client) B CC Server + |(1)INVITE B(SDP)| | | + |--------------->| | | + | |(2) CCR (event, PRICE_ENQUIRY, | + | | SIP specific AVPs) | + | |-------------------------------->| + | |(3) CCA (Cost-Information) | + | |<--------------------------------| + | (4)MESSAGE(URL)| | | + |<---------------| | | + |(5)HTTP GET | | | + |--------------->| | | + |(6)HTTP POST | | | + |--------------->|(7)INVITE(SDP) | | + | |--------------->| | + | | (8)200 OK | | + | (9)200 OK |<---------------| | + |<---------------| | | + + Figure A.5: Flow V + + + + + + +Hakala, et al. Standards Track [Page 100] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + This is an example of Diameter credit-control for SIP sessions. + Although the flow focuses on illustrating the usage of credit-control + messages, the SIP signaling is inaccurate, and the diagram is not by + any means an attempt to define a service provider's SIP network. + + Figure A.5 is an example of Advice of Charge (AoC) service for SIP + call. User A can be either a postpaid or prepaid subscriber using + the AoC service. It is assumed that the SIP controller also has HTTP + capabilities and delivers an interactive AoC web page with, for + instance, the cost information, the details of the call derived from + the SDP, and a button to accept/not accept the charges. (There may + be many other ways to deliver AoC information; however, this flow + focuses on the use of the credit-control messages.) The user has + been authenticated and authorized prior to initiating the call and + subscribed to AoC service. + + UA A sends an INVITE with SDP to B (1). The SIP controller + determines that the user is subscribed to AoC service and sends a + Diameter Credit-Control-Request (EVENT_REQUEST with Requested-Action: + PRICE_ENQUIRY) to the Diameter credit-control server (2). The + Credit-Control-Request contains SIP specific AVPs derived from the + SIP signaling, describing the requested service (e.g., calling party, + called party, Session Description Protocol attributes). The Diameter + credit-control server determines the cost of the service and returns + the Credit-Control-Answer including the Cost-Information AVP (3). + The SIP controller manufactures the AoC web page with information + received in SIP signaling and with the cost information received from + the credit-control server. Then it sends a SIP MESSAGE that contains + a URL pointing to the AoC information web page (4). At the receipt + of the SIP MESSAGE, A's UA automatically invokes the web browser that + retrieves the AoC information (5). The user clicks on a proper + button and accepts the charges (6). The SIP controller continues the + session and sends the INVITE to the B party, which accepts the call + (7,8,9). + + + + + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 101] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +A.6. Flow VI + + Gaming Server + End User (CC Client) CC Server + | (1)Service Delivery | | + |<---------------------->| | + : : : + : : : + | |(2)CCR(event,REFUND,Requested- + | |Service-Unit,Service-Parameter-Info) + | |----------------------->| + | | (3)CCA(Cost-Information) + | |<-----------------------| + | (4)Notification | | + |<-----------------------| | + + Figure A.6: Flow VI + + Figure A.6 illustrates a credit-control flow for the REFUND case. It + is assumed that there is a trusted relationship and secure connection + between the Gaming server and the Diameter credit-control server. + The end user may be a prepaid subscriber or a postpaid subscriber. + + While the end user is playing the game (1), she enters a new level + that entitles her to a bonus. The Gaming server sends a Diameter + Credit-Control-Request (EVENT_REQUEST with Requested-Action: + REFUND_ACCOUNT) to the Diameter credit-control server (2). The + Credit-Control-Request Request contains the Requested-Service-Unit + AVP with the CC-Service-Specific-Units containing the number of + points the user just won. The Service-Parameter-Info AVP is also + included in the request and specifies the service event to be rated + (e.g., Tetris Bonus). From information received, the Diameter + credit-control server determines the amount to be credited, refunds + the user's account, and returns the Credit-Control-Answer, including + the Cost-Information AVP (3). The Cost-Information indicates the + credited amount. At the first opportunity, the Gaming server + notifies the end user of the credited amount (4). + + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 102] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +A.7. Flow VII + + SIP Controller Top-Up + A (CC Client) Server B CC Server + | | | | | + | | (1) CCR(Update,Used-Unit) | | + | |------------------------------------------>| + | | (2) CCA(Final-Unit, Redirect)| + | |<------------------------------------------| + : : : : : + : : : : : + | | (3) CCR(Update, Used-Units)| | + | |------------------------------------------>| + | | (3a)INVITE("hold") | | + | |--------------------------->| | + | | | (4) CCA(Validity-Time)| + | |<------------------------------------------| + | (5)INVITE | (6)INVITE | | | + |<--------------|------------->| | | + | (7)RTP | | | + |..............................| | | + | | (8)BYE | | | + | |<-------------| | | + | | (9)CCR(Update) | | + | |------------------------------------------>| + | | (10)CCA(Granted-Unit) | + | |<------------------------------------------| + | (12)INVITE | (11)INVITE | | + |<--------------|--------------------------->| | + + Figure A.7: Flow VII + + Figure A.7 is an example of the graceful service termination for a + SIP call. It is assumed that the call is set up so that the + controller is in the call as a B2BUA (Back to Back User Agent) + performing third-party call control (3PCC). Note that the SIP + signaling is inaccurate, as the focus of this flow is in the graceful + service termination and credit-control authorization. The best + practice for 3PCC is defined in [RFC3725]. + + The call is ongoing between users A and B; user A has a prepaid + subscription. At the expiry of the allocated quota, the SIP + controller sends a Diameter Credit-Control-Request (UPDATE_REQUEST) + to the Diameter credit-control server (1). This message contains the + units used thus far. The Diameter credit-control server debits the + used units from the end user's account and allocates the final quota + returned to the SIP controller in the Diameter Credit-Control-Answer + (2). This message contains the Final-Unit-Indication AVP with the + + + +Hakala, et al. Standards Track [Page 103] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Final-Unit-Action set to REDIRECT, the Redirect-Address-Type set to + SIP URI, and the Redirect-Server-Address set to the Top-up server + name (e.g., sip:[email protected]). At the expiry of the + final allocated quota, the SIP controller sends a Diameter Credit- + Control-Request (UPDATE_REQUEST) to the Diameter credit-control + server (3) and places the called party on "hold" by sending an INVITE + with the appropriate connection address in the SDP (3a). The + Credit-Control-Request message contains the units used thus far. The + Diameter credit-control server debits the used units from the end + user's account but does not make any credit reservation. The + Credit-Control-Answer message, which contains the Validity-Time to + supervise the graceful service termination, is returned to the SIP + controller (4). The SIP controller establishes a SIP session between + the prepaid user and the Top-up server (5, 6). The Top-up server + plays an announcement and prompts the user to enter a credit card + number and the amount of money to be used to replenish the account + (7). The Top-up server validates the credit card number and + replenishes the user's account (using some means outside the scope of + this specification) and releases the SIP session (8). The SIP + controller can now assume that communication between the prepaid user + and the Top-up server took place. It sends a spontaneous Credit- + Control-Request (UPDATE_REQUEST) to the Diameter credit-control + server to check whether the account has been replenished (9). The + Diameter credit-control server reserves credit from the end user's + account and returns the reserved quota to the SIP controller in the + Credit-Control-Answer (10). At this point, the SIP controller re- + connects the caller and the called party (11,12). + + + + + + + + + + + + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 104] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +A.8. Flow VIII + + NAS Top-up CC + End-User (CC Client) AAA Server Server Server + |(1)User Logon |(2)AA Request (CC AVPs) | | + |------------------>|------------------->| | | + | | |(3)CCR(initial, CC AVPs) + | | |------------------->| + | | |(4)CCA(Final-Unit, | + | | | Validity-Time)| + | | |<-------------------| + | |(5)AA Answer(Final-Unit,Validity-Time) | + |(6)Limited Access |<-------------------| | | + | granted | | | | + |<----------------->| | | | + | | | | | + | (7)TCP/HTTP | (8)TCP/HTTP | | + |<----------------->|<----------------------------->| | + | (9) Replenish account | | + |<------------------------------------------------->| | + | | | (10)RAR | + | |<-------------------|<-------------------| + | | (11) RAA | | + | |------------------->|------------------->| + | |(12)CCR(update) | | + | |------------------->|(13)CCR(Update) | + | | |------------------->| + | | |(14)CCA(Granted-Units) + | |(15)CCA(Granted-Units)<------------------| + | |<-------------------| | + + Figure A.8: Flow VIII + + Figure A.8 is an example of the graceful service termination + initiated when the first interrogation takes place because the user's + account is empty. In this example, the credit-control server + supports the server-initiated credit re-authorization. The Diameter + [NASREQ] is implemented in the Network Access Server (NAS). + + The user logs on to the network (1). The Diameter NAS sends a + Diameter AA-Request to the home Diameter AAA server. The credit- + control client populates the AAR with the Credit-Control AVP set to + CREDIT_AUTHORIZATION, and service specific AVPs are included, as + usual [NASREQ]. The home Diameter AAA server performs service + specific Authentication and Authorization, as usual. The home + Diameter AAA server determines that the user has a prepaid + subscription and notices from the Credit-Control AVP that the NAS has + credit-control capabilities. It sends a Diameter Credit-Control- + + + +Hakala, et al. Standards Track [Page 105] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Request with CC-Request-Type set to INITIAL_REQUEST to the Diameter + credit-control server to perform credit authorization (3) and to + establish a credit-control session. (The home Diameter AAA server + may forward service specific AVPs received from the NAS as input for + the rating process.) The Diameter credit-control server checks the + end user's account balance, determines that the account cannot cover + the cost of the service, and initiates the graceful service + termination. The Credit-Control-Answer is returned to the home + Diameter AAA server (4). This message contains the Final-Unit- + Indication AVP and the Validity-Time AVP set to a reasonable amount + of time to give the user a chance to replenish his/her account (e.g., + 10 minutes). The Final-Unit-Indication AVP includes the Final-Unit- + Action set to REDIRECT, the Redirect-Address-Type set to URL, and the + Redirect-Server-Address set to the HTTP Top-up server name. The home + Diameter AAA server sends the received credit-control AVPs to the NAS + in the Diameter AA-Answer (5). Upon successful AAA, the NAS starts + the credit-control session and immediately starts the graceful + service termination, as instructed by the server. The NAS grants + limited access to the user (6). The HTTP client software running in + the user's device opens the transport connection redirected by the + NAS to the Top-up server (7,8). The user is displayed an appropriate + web page on which to enter the credit card number, and the amount of + money to be used to replenish the account, and with a notification + message that she is granted unlimited access if the replenishment + operation will be successfully executed within the next, for example, + 10 minutes. The Top-up server validates the credit card number and + replenishes the user's account (using some means outside the scope of + this specification)(9). After successful account top-up, the + credit-control server sends a Re-Auth-Request message to the NAS + (10). The NAS acknowledges the request by returning the Re-Auth- + Answer message (11) and initiates the credit re-authorization by + sending a Credit-Control-request (UPDATE_REQUEST) to the Diameter + credit-control server (12,13). + + The Diameter credit-control server reserves credit from the end + user's account and returns the reserved quota to the NAS via the home + Diameter AAA server in the Credit-Control-Answer (14,15). The NAS + removes the restriction placed by the graceful service termination + and starts monitoring the granted units. + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 106] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +A.9. Flow IX + + The Diameter credit-control application defines the Multiple- + Services-Credit-Control AVP that can be used to support independent + credit-control of multiple services in a single credit-control (sub-) + session for service elements that have such capabilities. It is + possible to request and allocate resources as a credit pool that is + shared between services or rating groups. + + The flow example hereafter illustrates a usage scenario where the + credit-control client and server support independent credit-control + of multiple services, as defined in section 5.1.2. It is assumed + that Service-Identifiers, Rating-Groups, and their associated + parameters (e.g., IP 5-tuple) are locally configured in the service + element or provisioned by an entity other than the credit-control + server. + + End User Service Element CC Server + (CC client) + |(1)User logon | | + |------------------>|(2)CCR(initial, Service-Id access, | + | | Access specific AVPs, | + | | Multiple-Service-Indicator) | + | |---------------------------------------->| + | |(3)CCA(Multiple-Services-CC ( | + | | Granted-Units(Total-Octets), | + | | Service-Id access, | + | | Validity-time, | + | | G-S-U-Pool-Reference(Pool-Id 1, | + | | Multiplier 10))) | + | |<----------------------------------------| + : : : + |(4)Service-Request (Service 1) | + |------------------>|(5)CCR(update, Multiple-Services-CC( | + | | Requested-Units(), Service-Id 1, | + | | Rating-Group 1)) | + | |---------------------------------------->| + | |(6)CCA(Multiple-Services-CC ( | + | | Granted-Units(Time), | + | | Rating-Group 1, | + | | G-S-U-Pool-Reference(Pool-Id 1, | + | | Multiplier 1))) | + | |<----------------------------------------| + : : : + |(7)Service-Request (Service 2) | + |------------------>| | + + + + + +Hakala, et al. Standards Track [Page 107] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + : : : + : : : + |(8)Service-Request (Service 3&4) | + |------------------>|(9)CCR(update, Multiple-Services-CC ( | + | | Requested-Units(), Service-Id 3, | + | | Rating-Group 2), | + | | Multiple-Services-CC ( | + | | Requested-Units(), Service-Id 4, | + | | Rating-Group 3)) | + | |---------------------------------------->| + | |(10)CCA(Multiple-Services-CC ( | + | | Granted-Units(Total-Octets), | + | | Service-Id 3, Rating-Group 2, | + | | Validity-time, | + | | G-S-U-Pool-Reference(Pool-Id 2, | + | | Multiplier 2)), | + | | Multiple-Services-CC ( | + | | Granted-Units(Total-Octets), | + | | Service-Id 4, Rating-Group 3 | + | | Validity-Time, | + | | Final-Unit-Ind.(Terminate), | + | | G-S-U-Pool-Reference(Pool-Id 2, | + | | Multiplier 5))) | + | |<----------------------------------------| + : : : + : : : + | +--------------+ | | + | |Validity time | |(11)CCR(update, | + | |expires for | | Multiple-Services-CC ( | + | |Service-Id | | Requested-Unit(), | + | | access | | Used-Units(In-Octets,Out-Octets),| + | +--------------+ | Service-Id access)) | + | |---------------------------------------->| + | |(12)CCA(Multiple-Services-CC ( | + | | Granted-Units(Total-Octets), | + | | Service-Id access, | + | | Validity-Time, | + | | G-S-U-Pool-Reference(Pool-Id 1, | + | | Multiplier 10))) | + | |<----------------------------------------| + : : : + : : : + + + + + + + + + +Hakala, et al. Standards Track [Page 108] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + | +--------------+ | | + | |Total Quota | |(13)CCR(update, | + | |elapses for | | Multiple-Services-CC ( | + | |pool 2: | | Requested-Unit(), | + | |service 4 not | | Used-Units(In-Octets,Out-Octets),| + | |allowed, | | Service-Id 3, Rating-group 2), | + | |service 3 cont| | Multiple-Services-CC ( | + | +--------------+ | Used-Units(In-Octets,Out-Octets),| + | | Service-Id 4, Rating-Group 3)) | + | |---------------------------------------->| + | |(14)CCA(Multiple-Services-CC ( | + | | Result-Code 4011, | + | | Service-Id 3)) | + | |<----------------------------------------| + : : : + : : : + |(15) User logoff | | + |------------------>|(16)CCR(term, | + | | Multiple-Services-CC ( | + | | Used-Units(In-Octets,Out-Octets),| + | | Service-Id access), | + | | Multiple-Services-CC ( | + | | Used-Units(Time), | + | | Service-Id 1, Rating-Group 1), | + | | Multiple-Services-CC ( | + | | Used-Units(Time), | + | | Service-Id 2, Rating-Group 1)) | + | |---------------------------------------->| + | |(17)CCA(term) | + | |<----------------------------------------| + + Figure A.9: Flow example independent credit-control of multiple + services in a credit-control (sub-)Session + + The user logs on to the network (1). The service element sends a + Diameter Credit-Control-Request with CC-Request-Type set to + INITIAL_REQUEST to the Diameter credit-control server to perform + credit authorization for the bearer service (e.g., Internet access + service) and to establish a credit-control session (2). In this + message, the credit-control client indicates support for independent + credit-control of multiple services within the session by including + the Multiple-Service-Indicator AVP. The Diameter credit-control + server checks the end user's account balance, with rating information + received from the client (i.e., Service-Id and access specific AVPs), + rates the request, and reserves credit from the end user's account. + Suppose that the server reserves $5 and determines that the cost is + $1/MB. It then returns to the service element a Credit-Control- + Answer message that includes the Multiple-Services-Credit-Control AVP + + + +Hakala, et al. Standards Track [Page 109] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + with a quota of 5MB associated to the Service-Id (access), to a + multiplier value of 10, and to the Pool-Id 1 (3). + + The user uses Service 1 (4). The service element sends a Diameter + Credit-Control-Request with CC-Request-Type set to UPDATE_REQUEST to + the credit-control server to perform credit authorization for service + 1 (5). This message includes the Multiple-Services-Credit-Control + AVP to request service units for Service 1 that belong to Rating- + Group 1. The Diameter credit-control server determines that Service + 1 draws credit resources from the same account as the access service + (i.e., pool 1). It rates the request according to Service- + Id/Rating-Group and updates the existing reservation by requesting + more credit. Suppose that the server reserves $5 more (now the + reservation is $10) and determines that the cost is $0.1/minute. The + server authorizes the whole Rating-Group. It then returns to the + service element a Credit-Control-Answer message that includes the + Multiple-Services-Credit-Control AVP with a quota of 50min. + associated to the Rating-Group 1, to a multiplier value of 1, and to + the Pool-Id 1 (6). The client adjusts the total amount of resources + for pool 1 according the received quota, which gives S for Pool 1 = + 100. + + The user uses Service 2, which belongs to the authorized Rating- + Group, 1 (7). Resources are then consumed from the pool 1. + + The user now requests Services 3 and 4 as well, which are not + authorized (8). The service element sends a Diameter Credit- + Control-Request with CC-Request-Type set to UPDATE_REQUEST to the + credit-control server in order to perform credit authorization for + Services 3 and 4 (9). This message includes two instances of the + Multiple-Services-Credit-Control AVP to request service units for + Service 3 that belong to Rating-Group 2 and for Service 4 that belong + to Rating-Group 3. The Diameter credit-control server determines + that Services 3 and 4 draw credit resources from another account + (i.e., pool 2). It checks the end user's account balance and, + according to Service-Ids/Rating-Groups information, rates the + request. Then it reserves credit from pool 2. + + For example, the server reserves $5 and determines that Service 3 + costs $0.2/MB and Service 4 costs $0.5/MB. The server authorizes + only Services 3 and 4. It returns to the service element a Credit- + Control-Answer message that includes two instances of the Multiple- + Services-Credit-Control AVP (10). One instance grants a quota of + 12.5MB associated to the Service-Id 3 to a multiplier value of 2 and + to the Pool-Id 2. The other instance grants a quota of 5 MB + associated to the Service-Id 4 to a multiplier value of 5 and to the + Pool-Id 2. + + + + +Hakala, et al. Standards Track [Page 110] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + The server also determines that pool 2 is exhausted and Service 4 is + not allowed to continue after these units will be consumed. + Therefore the Final-Unit-Indication AVP with action TERMINATE is + associated to the Service-Id 4. The client calculates the total + amount of resources that can be used for pool 2 according the + received quotas and multipliers, which gives S for Pool 2 = 50. + + The Validity-Time for the access service expires. The service + element sends a Credit-Control-Request message to the server in order + to perform credit re-authorization for Service-Id (access) (11). + This message carries one instance of the Multiple-Services-Credit- + Control AVP that includes the units used by this service. Suppose + that the total amount of used units is 4MB. The client adjusts the + total amount of resources for pool 1 accordingly, which gives S for + Pool 1 = 60. + + The server deducts $4 from the user's account and updates the + reservation by requesting more credit. Suppose that the server + reserves $5 more (now the reservation is $11) and already knows the + cost of the Service-Id (access), which is $1/MB. It then returns to + the service element a Credit-Control-Answer message that includes the + Multiple-Services-Credit-Control AVP with a quota of 5 MB associated + to the Service-Id (access), to a multiplier value of 10, and to the + Pool-Id 1 (12). The client adjusts the total amount of resources for + pool 1 according the received quota, which gives S for Pool 1 = 110. + + Services 3 and 4 consume the total amount of pool 2 credit resources + (i.e., C1*2 + C2*5 >= S). The service element immediately starts the + TERMINATE action concerning Service 4 and sends a Credit-Control- + Request message with CC-Request-Type set to UPDATE_REQUEST to the + credit-control server in order to perform credit re-authorization for + Service 3 (13). This message contains two instances of the + Multiple-Services-Credit-Control AVP to report the units used by + Services 3 and 4. The server deducts the last $5 from the user's + account (pool 2) and returns the answer with Result-Code 4011 in the + Multiple-Services-Credit-Control AVP to indicate that Service 3 can + continue without credit-control (14). + + The end user logs off from the network (15). To debit the used units + from the end user's account and to stop the credit-control session, + the service element sends a Diameter Credit-Control-Request with CC- + Request-Type set to TERMINATION_REQUEST to the credit-control server + (16). This message contains the units consumed by each of the used + services in multiple instances of the Multiple-Services-Credit- + Control AVP. The used units are associated with the relevant + Service-Identifier and Rating-Group. The Diameter credit-control + + + + + +Hakala, et al. Standards Track [Page 111] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + server debits the used units to the user's account (Pool 1) and + acknowledges the session termination by sending a Diameter Credit- + Control-Answer to the service element (17). + +Authors' Addresses + + Harri Hakala + Oy L M Ericsson Ab + Joukahaisenkatu 1 + 20520 Turku + Finland + + Phone: +358 2 265 3722 + EMail: [email protected] + + + Leena Mattila + Oy L M Ericsson Ab + Joukahaisenkatu 1 + 20520 Turku + Finland + + Phone: +358 2 265 3731 + EMail: [email protected] + + + Juha-Pekka Koskinen + Nokia Networks + Hatanpaanvaltatie 30 + 33100 Tampere + Finland + + Phone: +358 7180 74027 + EMail: [email protected] + + + + + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 112] + +RFC 4006 Diameter Credit-Control Application August 2005 + + + Marco Stura + Nokia Networks + Hiomotie 32 + 00380 Helsinki + Finland + + Phone: +358 7180 64308 + EMail: [email protected] + + + John Loughney + Nokia Research Center + Itamerenkatu 11-13 + 00180 Helsinki + Finland + + Phone: +358 50 483 642 + EMail: [email protected] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hakala, et al. Standards Track [Page 113] + +RFC 4006 Diameter Credit-Control Application August 2005 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2005). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + +Hakala, et al. Standards Track [Page 114] + diff --git a/lib/diameter/doc/standard/rfc4072.txt b/lib/diameter/doc/standard/rfc4072.txt new file mode 100644 index 0000000000..dd0b3a18ac --- /dev/null +++ b/lib/diameter/doc/standard/rfc4072.txt @@ -0,0 +1,1851 @@ + + + + + + +Network Working Group P. Eronen, Ed. +Request for Comments: 4072 Nokia +Category: Standards Track T. Hiller + Lucent Technologies + G. Zorn + Cisco Systems + August 2005 + + + Diameter Extensible Authentication Protocol (EAP) Application + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2005). + +Abstract + + The Extensible Authentication Protocol (EAP) provides a standard + mechanism for support of various authentication methods. This + document defines the Command-Codes and AVPs necessary to carry EAP + packets between a Network Access Server (NAS) and a back-end + authentication server. + +Table of Contents + + 1. Introduction ...................................................2 + 1.1. Conventions Used in This Document ........................3 + 2. Extensible Authentication Protocol Support in Diameter .........3 + 2.1. Advertising Application Support ..........................3 + 2.2. Protocol Overview ........................................4 + 2.3. Sessions and NASREQ Interaction ..........................6 + 2.3.1. Scenario 1: Direct Connection .....................7 + 2.3.2. Scenario 2: Direct Connection with Redirects ......8 + 2.3.3. Scenario 3: Direct EAP, Authorization via Agents ..9 + 2.3.4. Scenario 4: Proxy Agents .........................10 + 2.4. Invalid Packets .........................................10 + 2.5. Retransmission ..........................................11 + 2.6. Fragmentation ...........................................12 + 2.7. Accounting ..............................................12 + 2.8. Usage Guidelines ........................................13 + + + +Eronen, et al. Standards Track [Page 1] + +RFC 4072 Diameter EAP Application August 2005 + + + 2.8.1. User-Name AVP ....................................13 + 2.8.2. Conflicting AVPs .................................13 + 2.8.3. Displayable Messages .............................14 + 2.8.4. Role Reversal ....................................14 + 2.8.5. Identifier Space .................................14 + 3. Command-Codes .................................................14 + 3.1. Diameter-EAP-Request (DER) Command ......................15 + 3.2. Diameter-EAP-Answer (DEA) Command .......................16 + 4. Attribute-Value Pairs .........................................18 + 4.1. New AVPs ................................................18 + 4.1.1. EAP-Payload AVP ..................................18 + 4.1.2. EAP-Reissued-Payload AVP .........................18 + 4.1.3. EAP-Master-Session-Key AVP .......................19 + 4.1.4. EAP-Key-Name AVP .................................19 + 4.1.5. Accounting-EAP-Auth-Method AVP ...................19 + 5. AVP Occurrence Tables .........................................19 + 5.1. EAP Command AVP Table ...................................20 + 5.2. Accounting AVP Table ....................................21 + 6. RADIUS/Diameter Interactions ..................................22 + 6.1. RADIUS Request Forwarded as Diameter Request ............22 + 6.2. Diameter Request Forwarded as RADIUS Request ............23 + 6.3. Accounting Requests .....................................24 + 7. IANA Considerations ...........................................24 + 8. Security Considerations .......................................24 + 8.1. Overview ................................................24 + 8.2. AVP Editing .............................................26 + 8.3. Negotiation Attacks .....................................27 + 8.4. Session Key Distribution ................................28 + 8.5. Privacy Issues ..........................................28 + 8.6. Note about EAP and Impersonation ........................29 + 9. Acknowledgements ..............................................29 + 10. References ....................................................30 + 10.1. Normative References ....................................30 + 10.2. Informative References ..................................30 + +1. Introduction + + The Extensible Authentication Protocol (EAP), defined in [EAP], is an + authentication framework which supports multiple authentication + mechanisms. EAP may be used on dedicated links, switched circuits, + and wired as well as wireless links. + + To date, EAP has been implemented with hosts and routers that connect + via switched circuits or dial-up lines using PPP [RFC1661], IEEE 802 + wired switches [IEEE-802.1X], and IEEE 802.11 wireless access points + [IEEE-802.11i]. EAP has also been adopted for IPsec remote access in + IKEv2 [IKEv2]. + + + + +Eronen, et al. Standards Track [Page 2] + +RFC 4072 Diameter EAP Application August 2005 + + + This document specifies the Diameter EAP application that carries EAP + packets between a Network Access Server (NAS) working as an EAP + Authenticator and a back-end authentication server. The Diameter EAP + application is based on the Diameter Network Access Server + Application [NASREQ] and is intended for environments similar to + NASREQ. + + In the Diameter EAP application, authentication occurs between the + EAP client and its home Diameter server. This end-to-end + authentication reduces the possibility for fraudulent authentication, + such as replay and man-in-the-middle attacks. End-to-end + authentication also provides a possibility for mutual authentication, + which is not possible with PAP and CHAP in a roaming PPP environment. + + The Diameter EAP application relies heavily on [NASREQ], and in + earlier versions was part of the Diameter NASREQ application. It can + also be used in conjunction with NASREQ, selecting the application + based on the user authentication mechanism (EAP or PAP/CHAP). The + Diameter EAP application defines new Command-Codes and Attribute- + Value Pairs (AVPs), and can work together with RADIUS EAP support + [RFC3579]. + +1.1. Conventions Used in This Document + + 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 [RFC2119]. + +2. Extensible Authentication Protocol Support in Diameter + +2.1. Advertising Application Support + + Diameter nodes conforming to this specification MUST advertise + support by including the Diameter EAP Application ID value of 5 in + the Auth-Application-Id AVP of the Capabilities-Exchange-Request and + Capabilities-Exchange-Answer command [BASE]. + + If the NAS receives a response with the Result-Code set to + DIAMETER_APPLICATION_UNSUPPORTED [BASE], it indicates that the + Diameter server in the home realm does not support EAP. If possible, + the access device MAY attempt to negotiate another authentication + protocol, such as PAP or CHAP. An access device SHOULD be cautious + when determining whether a less secure authentication protocol will + be used, since this could result from a downgrade attack (see + Section 8.3). + + + + + + +Eronen, et al. Standards Track [Page 3] + +RFC 4072 Diameter EAP Application August 2005 + + +2.2. Protocol Overview + + The EAP conversation between the authenticating peer and the access + device begins with the initiation of EAP within a link layer, such as + PPP [RFC1661] or IEEE 802.11i [IEEE-802.11i]. Once EAP has been + initiated, the access device will typically send a Diameter-EAP- + Request message with an empty EAP-Payload AVP to the Diameter server, + signifying an EAP-Start. + + If the Diameter home server is willing to do EAP authentication, it + responds with a Diameter-EAP-Answer message containing an EAP-Payload + AVP that includes an encapsulated EAP packet. The Result-Code AVP in + the message will be set to DIAMETER_MULTI_ROUND_AUTH, signifying that + a subsequent request is expected. The EAP payload is forwarded by + the access device to the EAP client. This is illustrated in the + diagram below. + + User NAS Server + | | | + | (initiate EAP) | | + |<------------------------------>| | + | | Diameter-EAP-Request | + | | EAP-Payload(EAP Start) | + | |------------------------------->| + | | | + | | Diameter-EAP-Answer | + | Result-Code=DIAMETER_MULTI_ROUND_AUTH | + | | EAP-Payload(EAP Request #1) | + | |<-------------------------------| + | EAP Request #1 | | + |<-------------------------------| | + : : : + : ...continues... : + + The initial Diameter-EAP-Answer in a multi-round exchange normally + includes an EAP-Request/Identity, requesting the EAP client to + identify itself. Upon receipt of the EAP client's EAP-Response, the + access device will then issue a second Diameter-EAP-Request message, + with the client's EAP payload encapsulated within the EAP-Payload + AVP. + + A preferred approach is for the access device to issue the + EAP-Request/Identity message to the EAP client, and forward the + EAP-Response/Identity packet, encapsulated within the EAP-Payload + AVP, as a Diameter-EAP-Request to the Diameter server (see the + diagram below). This alternative reduces the number of Diameter + message round trips. When the EAP-Request/Identity message is issued + by the access device, it SHOULD interpret the EAP-Response/Identity + + + +Eronen, et al. Standards Track [Page 4] + +RFC 4072 Diameter EAP Application August 2005 + + + packet returned by the authenticating peer, and copy its value to a + User-Name AVP in Diameter-EAP-Request. This is useful in roaming + environments, since the Destination-Realm is needed for routing + purposes. Note that this alternative cannot be universally employed, + as there are circumstances in which a user's identity is not needed + (such as when authorization occurs based on a calling or called phone + number). + + User NAS Server + | | | + | (initiate EAP) | | + |<------------------------------>| | + | | | + | EAP Request(Identity) | | + |<-------------------------------| | + | | | + | EAP Response(Identity) | | + |------------------------------->| | + | | Diameter-EAP-Request | + | | EAP-Payload(EAP Response) | + | |------------------------------->| + : : : + : ...continues... : + + The conversation continues until the Diameter server sends a + Diameter-EAP-Answer with a Result-Code AVP indicating success or + failure, and an optional EAP-Payload. The Result-Code AVP is used by + the access device to determine whether service is to be provided to + the EAP client. The access device MUST NOT rely on the contents of + the optional EAP-Payload to determine whether service is to be + provided. + + + + + + + + + + + + + + + + + + + + +Eronen, et al. Standards Track [Page 5] + +RFC 4072 Diameter EAP Application August 2005 + + + : ...continued... : + : : : + | EAP Response #N | | + |------------------------------->| | + | | Diameter-EAP-Request | + | | EAP-Payload(EAP Response #N) | + | |------------------------------->| + | | | + | | Diameter-EAP-Answer | + | | Result-Code=DIAMETER_SUCCESS | + | | EAP-Payload(EAP Success) | + | | [EAP-Master-Session-Key] | + | | (authorization AVPs) | + | |<-------------------------------| + | | | + | EAP Success | | + |<-------------------------------| | + + If authorization was requested, a Diameter-EAP-Answer with + Result-Code set to DIAMETER_SUCCESS SHOULD also include the + appropriate authorization AVPs required for the service requested + (see Section 5 and [NASREQ]). In some cases, the home server may not + be able to provide all necessary authorization AVPs; in this case, a + separate authorization step MAY be used as described in + Section 2.3.3. Diameter-EAP-Answer messages whose Result-Code AVP is + set to DIAMETER_MULTI_ROUND_AUTH MAY include authorization AVPs. + + A Diameter-EAP-Answer with successful Result-Code MAY also include an + EAP-Master-Session-Key AVP that contains keying material for + protecting the communication between the user and the NAS. Exactly + how this keying material is used depends on the link layer in + question, and is beyond the scope of this document. + + A home Diameter server MAY request EAP re-authentication by issuing + the Re-Auth-Request [BASE] message to the Diameter client. + + Should an EAP authentication session be interrupted due to a home + server failure, the session MAY be directed to an alternate server, + but the authentication session will have to be restarted from the + beginning. + +2.3. Sessions and NASREQ Interaction + + The previous section introduced the basic protocol between the NAS + and the home server. Since the Diameter-EAP-Answer message may + include a Master Session Key (MSK) for protecting the communication + between the user and the NAS, one must ensure that this key does not + fall into wrong hands. + + + +Eronen, et al. Standards Track [Page 6] + +RFC 4072 Diameter EAP Application August 2005 + + + Basic Diameter security mechanisms (IPsec and TLS) protect Diameter + messages hop-by-hop. Since there are currently no end-to-end + (NAS-to-home server) security mechanisms defined for Diameter, this + section describes possible scenarios on how the messages could be + transport protected using these hop-by-hop mechanisms. + + This list of scenarios is not intended to be exhaustive, and it is + possible to combine them. For instance, the first proxy agent after + the NAS could use redirects as in Scenario 2 to bypass any additional + proxy agents. + +2.3.1. Scenario 1: Direct Connection + + The simplest case is when the NAS contacts the home server directly. + All authorization AVPs and EAP keying material are delivered by the + home server. + + NAS home server + | | + | Diameter-EAP-Request | + | Auth-Request-Type=AUTHORIZE_AUTHENTICATE | + | EAP-Payload(EAP Start) | + |---------------------------------------------------------------->| + | | + | Diameter-EAP-Answer | + | Result-Code=DIAMETER_MULTI_ROUND_AUTH | + | EAP-Payload(EAP Request) | + |<----------------------------------------------------------------| + | | + : ...more EAP Request/Response pairs... : + | | + | Diameter-EAP-Request | + | EAP-Payload(EAP Response) | + |---------------------------------------------------------------->| + | | + | Diameter-EAP-Answer | + | Result-Code=DIAMETER_SUCCESS | + | EAP-Payload(EAP Success) | + | EAP-Master-Session-Key | + | (authorization AVPs) | + |<----------------------------------------------------------------| + + This scenario is the most likely to be used in small networks, or in + cases where Diameter agents are not needed to provide routing or + additional authorization AVPs. + + + + + + +Eronen, et al. Standards Track [Page 7] + +RFC 4072 Diameter EAP Application August 2005 + + +2.3.2. Scenario 2: Direct Connection with Redirects + + In this scenario the NAS uses a redirect agent to locate the home + server. The rest of the session proceeds as before. + + NAS Local redirect agent Home server + | | | + | Diameter-EAP-Request | | + | Auth-Request-Type=AUTHORIZE_AUTHENTICATE | + | EAP-Payload(EAP Start) | | + |------------------------------->| | + | | | + | Diameter-EAP-Answer | + | Redirect-Host=homeserver.example.com | + | Redirect-Host-Usage=REALM_AND_APPLICATION | + |<-------------------------------| | + | : | + | Diameter-EAP-Request : | + | Auth-Request-Type=AUTHORIZE_AUTHENTICATE | + | EAP-Payload(EAP Start) : | + |---------------------------------------------------------------->| + | : | + : ...rest of the session continues as in first case... : + : : : + + The advantage of this scenario is that knowledge of realms and home + servers is centralized to a redirect agent, and it is not necessary + to modify the NAS configuration when, for example, a new roaming + agreement is made. + + + + + + + + + + + + + + + + + + + + + + +Eronen, et al. Standards Track [Page 8] + +RFC 4072 Diameter EAP Application August 2005 + + +2.3.3. Scenario 3: Direct EAP, Authorization via Agents + + In this scenario the EAP authentication is done directly with the + home server (with Auth-Request-Type set to AUTHENTICATE_ONLY), and + authorization AVPs are retrieved from local proxy agents. This + scenario is intended for environments in which the home server cannot + provide all the necessary authorization AVPs to the NAS. + + NAS Local proxy agent Home server + | : | + | Diameter-EAP-Request : | + | Auth-Request-Type=AUTHENTICATE_ONLY | + | EAP-Payload(EAP Start) : | + |---------------------------------------------------------------->| + | : | + | : Diameter-EAP-Answer | + | Result-Code=DIAMETER_MULTI_ROUND_AUTH | + | : EAP-Payload(EAP Request) | + |<----------------------------------------------------------------| + | : | + : ...more EAP Request/Response pairs... : + | : | + | Diameter-EAP-Request : | + | EAP-Payload(EAP Response) : | + |---------------------------------------------------------------->| + | : | + | : Diameter-EAP-Answer | + | : Result-Code=DIAMETER_SUCCESS | + | : EAP-Payload(EAP Success) | + | : EAP-Master-Session-Key | + | : (authorization AVPs) | + |<----------------------------------------------------------------| + | | | + | AA-Request | | + | Auth-Request-Type=AUTHORIZE_ONLY | + | (some AVPs from first session) | | + |------------------------------->| | + | | | + | AA-Answer | | + | Result-Code=DIAMETER_SUCCESS | | + | (authorization AVPs) | | + |<-------------------------------| | + + The NASREQ application is used here for authorization because the + realm-specific routing table supports routing based on application, + not on Diameter commands. + + + + + +Eronen, et al. Standards Track [Page 9] + +RFC 4072 Diameter EAP Application August 2005 + + +2.3.4. Scenario 4: Proxy Agents + + This scenario is the same as Scenario 1, but the NAS contacts the + home server through proxies. Note that the proxies can see the EAP + session keys, thus it is not suitable for environments where proxies + cannot be trusted. + + NAS Local proxy/relay agent Home server + | | | + | Diameter-EAP-Request | | + | Auth-Request-Type=AUTHORIZE_AUTHENTICATE | + | EAP-Payload(EAP Start) | | + |------------------------------->|------------------------------->| + | | | + | | Diameter-EAP-Answer | + | Result-Code=DIAMETER_MULTI_ROUND_AUTH | + | | EAP-Payload(EAP Request) | + |<-------------------------------|<-------------------------------| + | : | + : ...more EAP Request/Response pairs... : + | : | + | Diameter-EAP-Request | | + | EAP-Payload(EAP Response) | | + |------------------------------->|------------------------------->| + | | | + | | Diameter-EAP-Answer | + | | Result-Code=DIAMETER_SUCCESS | + | | EAP-Payload(EAP Success) | + | | EAP-Master-Session-Key | + | | (authorization AVPs) | + |<-------------------------------|<-------------------------------| + +2.4. Invalid Packets + + While acting as a pass-through, the NAS MUST validate the EAP header + fields (Code, Identifier, Length) prior to forwarding an EAP packet + to or from the Diameter server. On receiving an EAP packet from the + peer, the NAS checks the Code (Code 2=Response) and Length fields, + and matches the Identifier value against the current Identifier, + supplied by the Diameter server in the most recently validated EAP + Request. On receiving an EAP packet from the Diameter server + (encapsulated within a Diameter-EAP-Answer), the NAS checks the Code + (Code 1=Request) and Length fields, then updates the current + Identifier value. Pending EAP Responses that do not match the + current Identifier value are silently discarded by the NAS. + + + + + + +Eronen, et al. Standards Track [Page 10] + +RFC 4072 Diameter EAP Application August 2005 + + + Since EAP method fields (Type, Type-Data) are typically not validated + by a NAS operating as a pass-through, despite these checks it is + possible for a NAS to forward an invalid EAP packet to or from the + Diameter server. + + A Diameter server receiving an EAP-Payload AVP that it does not + understand SHOULD determine whether the error is fatal or non-fatal + based on the EAP Type. A Diameter server determining that a fatal + error has occurred MUST send a Diameter-EAP-Answer with a failure + Result-Code and an EAP-Payload AVP encapsulating an EAP Failure + packet. A Diameter server determining that a non-fatal error has + occurred MUST send a Diameter-EAP-Answer with + DIAMETER_MULTI_ROUND_AUTH Result-Code, but no EAP-Payload AVP. To + simplify RADIUS translation, this message MUST also include an + EAP-Reissued-Payload AVP encapsulating the previous EAP Request sent + by the server. + + When receiving a Diameter-EAP-Answer without an EAP-Payload AVP (and + DIAMETER_MULTI_ROUND_AUTH Result-Code), the NAS SHOULD discard the + EAP-Response packet most recently transmitted to the Diameter server + and check whether additional EAP Response packets that match the + current Identifier value have been received. If so, a new EAP + Response packet, if available, MUST be sent to the Diameter server + within an Diameter-EAP-Request. If no EAP Response packet is + available, then the previous EAP Request is resent to the peer, and + the retransmission timer is reset. + + In order to provide protection against Denial of Service (DoS) + attacks, it is advisable for the NAS to allocate a finite buffer for + EAP packets received from the peer, and to discard packets according + to an appropriate policy once that buffer has been exceeded. Also, + the Diameter server is advised to permit only a modest number of + invalid EAP packets within a single session, prior to terminating the + session with DIAMETER_AUTHENTICATION_REJECTED Result-Code. By + default, a value of 5 invalid EAP packets is recommended. + +2.5. Retransmission + + As noted in [EAP], if an EAP packet is lost in transit between the + authenticating peer and the NAS (or vice versa), the NAS will + retransmit. + + It may be necessary to adjust retransmission strategies and + authentication time-outs in certain cases. For example, when a token + card is used, additional time may be required to allow the user to + find the card and enter the token. Since the NAS will typically not + have knowledge of the required parameters, these need to be provided + by the Diameter server. + + + +Eronen, et al. Standards Track [Page 11] + +RFC 4072 Diameter EAP Application August 2005 + + + If a Multi-Round-Time-Out AVP [BASE] is present in a Diameter-EAP- + Answer message that also contains an EAP-Payload AVP, that value is + used to set the EAP retransmission timer for that EAP Request and + that Request alone. + +2.6. Fragmentation + + Using the EAP-Payload AVP, it is possible for the Diameter server to + encapsulate an EAP packet that is larger than the MTU on the link + between the NAS and the peer. Since it is not possible for the + Diameter server to use MTU discovery to ascertain the link MTU, a + Framed-MTU AVP may be included in a Diameter-EAP-Request message in + order to provide the Diameter server with this information. + + A Diameter server having received a Framed-MTU AVP in a + Diameter-EAP-Request message MUST NOT send any subsequent packet in + this EAP conversation containing EAP-Payload AVP whose length exceeds + that specified by the Framed-MTU value, taking the link type + (specified by the NAS-Port-Type AVP) into account. For example, as + noted in [RFC3580] Section 3.10, for a NAS-Port-Type value of IEEE + 802.11, the RADIUS server may send an EAP packet as large as + Framed-MTU minus four (4) octets, taking into account the additional + overhead for the IEEE 802.1X Version (1 octet), Type (1 octet) and + Body Length (2 octets) fields. + +2.7. Accounting + + When a user is authenticated using EAP, the NAS MAY include an + Accounting-Auth-Method AVP [NASREQ] with value 5 (EAP) in + Accounting-Request messages. This document specifies one additional + AVP for accounting messages. One or more Accounting-EAP-Auth-Method + AVPs (see Section 4.1.5) MAY be included in Accounting-Request + messages to indicate the EAP method(s) used to authenticate the user. + + If the NAS has authenticated the user with a locally implemented EAP + method, it knows the method used and SHOULD include it in an + Accounting-EAP-Auth-Method AVP. + + If the authentication was done using Diameter-EAP-Request/Answer + messages, the Diameter server SHOULD include one or more + Accounting-EAP-Auth-Method AVPs in Diameter-EAP-Answer packets with a + successful result code. In this case, the NAS SHOULD include these + AVPs in Accounting-Request messages. + + + + + + + + +Eronen, et al. Standards Track [Page 12] + +RFC 4072 Diameter EAP Application August 2005 + + +2.8. Usage Guidelines + +2.8.1. User-Name AVP + + Unless the access device interprets the EAP-Response/Identity packet + returned by the authenticating peer, it will not have access to the + user's identity. Furthermore, some EAP methods support identity + protection where the user's real identity is not included in + EAP-Response/Identity. Therefore, the Diameter Server SHOULD return + the user's identity by inserting a User-Name AVP to + Diameter-EAP-Answer messages that have a Result-Code of + DIAMETER_SUCCESS. A separate billing identifier or pseudonym MAY be + used for privacy reasons (see Section 8.5). If the user's identity + is not available to the NAS, the Session-Id AVP MAY be used for + accounting and billing; however operationally this could be very + difficult to manage. + +2.8.2. Conflicting AVPs + + A Diameter-EAP-Answer message containing an EAP-Payload of type + EAP-Success or EAP-Failure MUST NOT have the Result-Code AVP set to + DIAMETER_MULTI_ROUND_AUTH. + + Some lower layers assume that the authorization decision is made by + the EAP server, and thus the peer considers EAP Success as an + indication that access was granted. In this case, the Result-Code + SHOULD match the contained EAP packet: a successful Result-Code for + EAP-Success, and a failure Result-Code for EAP-Failure. If the + encapsulated EAP packet does not match the result implied by the + Result-Code AVP, the combination is likely to cause confusion, + because the NAS and peer will conclude the outcome of the + authentication differently. For example, if the NAS receives a + failure Result-Code with an encapsulated EAP Success, it will not + grant access to the peer. However, on receiving the EAP Success, the + peer will be led to believe that access was granted. + + This situation can be difficult to avoid when Diameter proxy agents + make authorization decisions (that is, proxies can change the + Result-Code AVP sent by the home server). Because it is the + responsibility of the Diameter server to avoid conflicts, the NAS + MUST NOT "manufacture" EAP result packets in order to correct the + contradictory messages that it receives. This behavior, originally + mandated within [IEEE-802.1X], is now deprecated. + + + + + + + + +Eronen, et al. Standards Track [Page 13] + +RFC 4072 Diameter EAP Application August 2005 + + +2.8.3. Displayable Messages + + The Reply-Message AVP [NASREQ] MUST NOT be included in any Diameter + message containing an EAP-Payload AVP. + +2.8.4. Role Reversal + + Some environments in which EAP is used, such as PPP, support + peer-to-peer operation. Both parties act as authenticators and + authenticatees at the same time, in two simultaneous and independent + EAP conversations. + + This specification is intended for communication between EAP + (passthrough) authenticator and backend authentication server. A + Diameter client MUST NOT send a Diameter-EAP-Request encapsulating an + EAP Request packet, and a Diameter server receiving such a packet + MUST respond with a failure Result-Code. + +2.8.5. Identifier Space + + In EAP, each session has its own unique Identifier space. Diameter + server implementations MUST be able to distinguish between EAP + packets with the same Identifier existing within distinct EAP + sessions and originating on the same NAS. This is done by using the + Session-Id AVP. + + If a Diameter NAS is in the middle of a multi-round authentication + exchange, and it detects that the EAP session between the client and + the NAS has been terminated, it MUST select a new Diameter Session-Id + for any subsequent EAP sessions. This is necessary in order to + distinguish a restarted EAP authentication process from the + continuation of an ongoing process (by the same user on the same NAS + and port). + + In RADIUS, the same functionality can be achieved through the + inclusion or omission of the State attribute. Translation rules in + [NASREQ] ensure that an Access-Request without the State attribute + maps to a new Diameter Session-Id AVP value. Furthermore, a + translation agent will always include a State attribute in + Access-Challenge messages, making sure that the State attribute is + available for a RADIUS NAS. + +3. Command-Codes + + This section defines new Command-Code values that MUST be supported + by all Diameter implementations conforming to this specification. + The following commands are defined in this section: + + + + +Eronen, et al. Standards Track [Page 14] + +RFC 4072 Diameter EAP Application August 2005 + + + Command-Name Abbrev. Code Reference + -------------------------------------------------------- + Diameter-EAP-Request DER 268 3.1 + Diameter-EAP-Answer DEA 268 3.2 + + When the NASREQ AA-Request (AAR) or AA-Answer (AAA) commands are used + for AUTHORIZE_ONLY messages in conjunction with EAP (see + Section 2.3.3), an Application Identifier value of 1 (NASREQ) is + used, and the commands follow the rules and ABNF defined in [NASREQ]. + + When the Re-Auth-Request (RAR), Re-Auth-Answer (RAA), + Session-Termination-Request (STR), Session-Termination-Answer (STA), + Abort-Session-Request (ASR), Abort-Session-Answer (ASA), + Accounting-Request (ACR), and Accounting-Answer (ACA) commands are + used together with the Diameter EAP application, they follow the + rules in [NASREQ] and [BASE]. The accounting commands use + Application Identifier value of 3 (Diameter Base Accounting); the + others use 0 (Diameter Common Messages). + +3.1. Diameter-EAP-Request (DER) Command + + The Diameter-EAP-Request (DER) command, indicated by the Command-Code + field set to 268 and the 'R' bit set in the Command Flags field, is + sent by a Diameter client to a Diameter server, and conveys an + EAP-Response from the EAP client. The Diameter-EAP-Request MUST + contain one EAP-Payload AVP containing the actual EAP payload. An + EAP-Payload AVP with no data MAY be sent to the Diameter server to + initiate an EAP authentication session. + + The DER message MAY be the result of a multi-round authentication + exchange that occurs when the DEA is received with the Result-Code + AVP set to DIAMETER_MULTI_ROUND_AUTH [BASE]. A subsequent DER + message MUST include any State AVPs [NASREQ] that were present in the + DEA. For re-authentication, it is recommended that the Identity + request be skipped in order to reduce the number of authentication + round trips. This is only possible when the user's identity is + already known by the home Diameter server. + + Message format + + <Diameter-EAP-Request> ::= < Diameter Header: 268, REQ, PXY > + < Session-Id > + { Auth-Application-Id } + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { Auth-Request-Type } + [ Destination-Host ] + + + +Eronen, et al. Standards Track [Page 15] + +RFC 4072 Diameter EAP Application August 2005 + + + [ NAS-Identifier ] + [ NAS-IP-Address ] + [ NAS-IPv6-Address ] + [ NAS-Port ] + [ NAS-Port-Id ] + [ NAS-Port-Type ] + [ Origin-State-Id ] + [ Port-Limit ] + [ User-Name ] + { EAP-Payload } + [ EAP-Key-Name ] + [ Service-Type ] + [ State ] + [ Authorization-Lifetime ] + [ Auth-Grace-Period ] + [ Auth-Session-State ] + [ Callback-Number ] + [ Called-Station-Id ] + [ Calling-Station-Id ] + [ Originating-Line-Info ] + [ Connect-Info ] + * [ Framed-Compression ] + [ Framed-Interface-Id ] + [ Framed-IP-Address ] + * [ Framed-IPv6-Prefix ] + [ Framed-IP-Netmask ] + [ Framed-MTU ] + [ Framed-Protocol ] + * [ Tunneling ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +3.2. Diameter-EAP-Answer (DEA) Command + + The Diameter-EAP-Answer (DEA) message, indicated by the Command-Code + field set to 268 and the 'R' bit cleared in the Command Flags field, + is sent by the Diameter server to the client for one of the following + reasons: + + 1. The message is part of a multi-round authentication exchange, and + the server is expecting a subsequent Diameter-EAP-Request. This + is indicated by setting the Result-Code to + DIAMETER_MULTI_ROUND_AUTH, and MAY include zero or more State + AVPs. + + + + + + +Eronen, et al. Standards Track [Page 16] + +RFC 4072 Diameter EAP Application August 2005 + + + 2. The EAP client has been successfully authenticated and + authorized, in which case the message MUST include the + Result-Code AVP indicating success, and SHOULD include an + EAP-Payload of type EAP-Success. This event MUST cause the + access device to provide service to the EAP client. + + 3. The EAP client has not been successfully authenticated and/or + authorized, and the Result-Code AVP is set to indicate failure. + This message SHOULD include an EAP-Payload, but this AVP is not + used to determine whether service is to be provided. + + If the message from the Diameter client included a request for + authorization, a successful response MUST include the authorization + AVPs that are relevant to the service being provided. + + Message format + + <Diameter-EAP-Answer> ::= < Diameter Header: 268, PXY > + < Session-Id > + { Auth-Application-Id } + { Auth-Request-Type } + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + [ EAP-Payload ] + [ EAP-Reissued-Payload ] + [ EAP-Master-Session-Key ] + [ EAP-Key-Name ] + [ Multi-Round-Time-Out ] + [ Accounting-EAP-Auth-Method ] + [ Service-Type ] + * [ Class ] + * [ Configuration-Token ] + [ Acct-Interim-Interval ] + [ Error-Message ] + [ Error-Reporting-Host ] + * [ Failed-AVP ] + [ Idle-Timeout ] + [ Authorization-Lifetime ] + [ Auth-Grace-Period ] + [ Auth-Session-State ] + [ Re-Auth-Request-Type ] + [ Session-Timeout ] + [ State ] + * [ Reply-Message ] + [ Origin-State-Id ] + * [ Filter-Id ] + + + +Eronen, et al. Standards Track [Page 17] + +RFC 4072 Diameter EAP Application August 2005 + + + [ Port-Limit ] + [ Callback-Id ] + [ Callback-Number ] + [ Framed-Appletalk-Link ] + * [ Framed-Appletalk-Network ] + [ Framed-Appletalk-Zone ] + * [ Framed-Compression ] + [ Framed-Interface-Id ] + [ Framed-IP-Address ] + * [ Framed-IPv6-Prefix ] + [ Framed-IPv6-Pool ] + * [ Framed-IPv6-Route ] + [ Framed-IP-Netmask ] + * [ Framed-Route ] + [ Framed-Pool ] + [ Framed-IPX-Network ] + [ Framed-MTU ] + [ Framed-Protocol ] + [ Framed-Routing ] + * [ NAS-Filter-Rule ] + * [ QoS-Filter-Rule ] + * [ Tunneling ] + * [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ AVP ] + +4. Attribute-Value Pairs + + This section both defines new AVPs, unique to the EAP Diameter + application and describes the usage of AVPs defined elsewhere (if + that usage in the EAP application is noteworthy). + +4.1. New AVPs + +4.1.1. EAP-Payload AVP + + The EAP-Payload AVP (AVP Code 462) is of type OctetString and is used + to encapsulate the actual EAP packet that is being exchanged between + the EAP client and the home Diameter server. + +4.1.2. EAP-Reissued-Payload AVP + + The EAP-Reissued-Payload AVP (AVP Code 463) is of type OctetString. + The use of this AVP is described in Section 2.4. + + + + + +Eronen, et al. Standards Track [Page 18] + +RFC 4072 Diameter EAP Application August 2005 + + +4.1.3. EAP-Master-Session-Key AVP + + The EAP-Master-Session-Key AVP (AVP Code 464) is of type OctetString. + It contains keying material for protecting the communications between + the user and the NAS. Exactly how this keying material is used + depends on the link layer in question, and is beyond the scope of + this document. + +4.1.4. EAP-Key-Name AVP + + The EAP-Key-Name AVP (Radius Attribute Type 102) is of type + OctetString. It contains an opaque key identifier (name) generated + by the EAP method. Exactly how this name is used depends on the link + layer in question, and is beyond the scope of this document (see + [EAPKey] for more discussion). + + Note that not all link layers use this name, and currently most EAP + methods do not generate it. Since the NAS operates in pass-through + mode, it cannot know the Key-Name before receiving it from the AAA + server. As a result, a Key-Name AVP sent in a Diameter-EAP-Request + MUST NOT contain any data. A home Diameter server receiving a + Diameter-EAP-Request with a Key-Name AVP with non-empty data MUST + silently discard the AVP. In addition, the home Diameter server + SHOULD include this AVP in Diameter-EAP-Response only if an empty + EAP-Key-Name AVP was present in Diameter-EAP-Request. + +4.1.5. Accounting-EAP-Auth-Method AVP + + The Accounting-EAP-Auth-Method AVP (AVP Code 465) is of type + Unsigned64. In case of expanded types [EAP, Section 5.7], this AVP + contains the value ((Vendor-Id * 2^32) + Vendor-Type). + + The use of this AVP is described in Section 2.7. + +5. AVP Occurrence Tables + + The following tables use these symbols: + + 0 The AVP MUST NOT be present in the message + 0+ Zero or more instances of the AVP MAY be present in the message + 0-1 Zero or one instance of the AVP MAY be present in the message + 1 One instance of the AVP MUST be present in the message + + Note that AVPs that can only be present within a Grouped AVP are not + represented in these tables. + + + + + + +Eronen, et al. Standards Track [Page 19] + +RFC 4072 Diameter EAP Application August 2005 + + +5.1. EAP Command AVP Table + + The following table lists the AVPs that may be present in the DER and + DEA Commands, as defined in this document; the AVPs listed are + defined both here and in [NASREQ]. + + +---------------+ + | Command-Code | + |-------+-------+ + Attribute Name | DER | DEA | + ------------------------------------|-------+-------| + Accounting-EAP-Auth-Method | 0 | 0+ | + Acct-Interim-Interval [BASE] | 0 | 0-1 | + Auth-Application-Id [BASE] | 1 | 1 | + Auth-Grace-Period [BASE] | 0-1 | 0-1 | + Auth-Request-Type [BASE] | 1 | 1 | + Auth-Session-State [BASE] | 0-1 | 0-1 | + Authorization-Lifetime [BASE] | 0-1 | 0-1 | + Callback-Id [NASREQ] | 0 | 0-1 | + Callback-Number [NASREQ] | 0-1 | 0-1 | + Called-Station-Id [NASREQ] | 0-1 | 0 | + Calling-Station-Id [NASREQ] | 0-1 | 0 | + Class [BASE] | 0 | 0+ | + Configuration-Token [NASREQ] | 0 | 0+ | + Connect-Info [NASREQ] | 0-1 | 0 | + Destination-Host [BASE] | 0-1 | 0 | + Destination-Realm [BASE] | 1 | 0 | + EAP-Master-Session-Key | 0 | 0-1 | + EAP-Key-Name | 0-1 | 0-1 | + EAP-Payload | 1 | 0-1 | + EAP-Reissued-Payload | 0 | 0-1 | + Error-Message [BASE] | 0 | 0-1 | + Error-Reporting-Host [BASE] | 0 | 0-1 | + Failed-AVP [BASE] | 0 | 0+ | + Filter-Id [NASREQ] | 0 | 0+ | + Framed-Appletalk-Link [NASREQ] | 0 | 0-1 | + Framed-Appletalk-Network [NASREQ] | 0 | 0+ | + Framed-Appletalk-Zone [NASREQ] | 0 | 0-1 | + Framed-Compression [NASREQ] | 0+ | 0+ | + Framed-Interface-Id [NASREQ] | 0-1 | 0-1 | + Framed-IP-Address [NASREQ] | 0-1 | 0-1 | + Framed-IP-Netmask [NASREQ] | 0-1 | 0-1 | + Framed-IPv6-Prefix [NASREQ] | 0+ | 0+ | + Framed-IPv6-Pool [NASREQ] | 0 | 0-1 | + Framed-IPv6-Route [NASREQ] | 0 | 0+ | + Framed-IPX-Network [NASREQ] | 0 | 0-1 | + Framed-MTU [NASREQ] | 0-1 | 0-1 | + Framed-Pool [NASREQ] | 0 | 0-1 | + + + +Eronen, et al. Standards Track [Page 20] + +RFC 4072 Diameter EAP Application August 2005 + + + Framed-Protocol [NASREQ] | 0-1 | 0-1 | + Framed-Route [NASREQ] | 0 | 0+ | + Framed-Routing [NASREQ] | 0 | 0-1 | + Idle-Timeout [NASREQ] | 0 | 0-1 | + Multi-Round-Time-Out [BASE] | 0 | 0-1 | + NAS-Filter-Rule [NASREQ] | 0 | 0+ | + NAS-Identifier [NASREQ] | 0-1 | 0 | + NAS-IP-Address [NASREQ] | 0-1 | 0 | + NAS-IPv6-Address [NASREQ] | 0-1 | 0 | + NAS-Port [NASREQ] | 0-1 | 0 | + NAS-Port-Id [NASREQ] | 0-1 | 0 | + NAS-Port-Type [NASREQ] | 0-1 | 0 | + Originating-Line-Info [NASREQ] | 0-1 | 0 | + Origin-Host [BASE] | 1 | 1 | + Origin-Realm [BASE] | 1 | 1 | + Origin-State-Id [BASE] | 0-1 | 0-1 | + Port-Limit [NASREQ] | 0-1 | 0-1 | + Proxy-Info [BASE] | 0+ | 0+ | + QoS-Filter-Rule [NASREQ] | 0 | 0+ | + Re-Auth-Request-Type [BASE] | 0 | 0-1 | + Redirect-Host [BASE] | 0 | 0+ | + Redirect-Host-Usage [BASE] | 0 | 0-1 | + Redirect-Max-Cache-Time [BASE] | 0 | 0-1 | + Reply-Message [NASREQ] | 0 | 0+ | + Result-Code [BASE] | 0 | 1 | + Route-Record [BASE] | 0+ | 0+ | + Service-Type [NASREQ] | 0-1 | 0-1 | + Session-Id [BASE] | 1 | 1 | + Session-Timeout [BASE] | 0 | 0-1 | + State [NASREQ] | 0-1 | 0-1 | + Tunneling [NASREQ] | 0+ | 0+ | + User-Name [BASE] | 0-1 | 0-1 | + +5.2. Accounting AVP Table + + The table in this section is used to represent which AVPs defined in + this document are to be present in the Accounting messages, as + defined in [BASE]. + + +-----------+ + | Command | + | Code | + |-----+-----+ + Attribute Name | ACR | ACA | + ---------------------------------------|-----+-----+ + Accounting-EAP-Auth-Method | 0+ | 0 | + + + + + +Eronen, et al. Standards Track [Page 21] + +RFC 4072 Diameter EAP Application August 2005 + + +6. RADIUS/Diameter Interactions + + Section 9 of [NASREQ] describes basic guidelines for translation + agents that translate between RADIUS and Diameter protocols. These + guidelines SHOULD be followed for Diameter EAP application as well, + with some additional guidelines given in this section. Note that + this document does not restrict implementations from creating + additional methods, as long as the translation function does not + violate the RADIUS or the Diameter protocols. + +6.1. RADIUS Request Forwarded as Diameter Request + + RADIUS Access-Request to Diameter-EAP-Request: + + o RADIUS EAP-Message attribute(s) are translated to a Diameter + EAP-Payload AVP. If multiple RADIUS EAP-Message attributes are + present, they are concatenated and translated to a single Diameter + EAP-Payload AVP. + + o An empty RADIUS EAP-Message attribute (with length 2) signifies + EAP-Start, and it is translated to an empty EAP-Payload AVP. + + Diameter-EAP-Answer to RADIUS Access-Accept/Reject/Challenge: + + o Diameter EAP-Payload AVP is translated to RADIUS EAP-Message + attribute(s). If necessary, the value is split into multiple + RADIUS EAP-Message attributes. + + o Diameter EAP-Reissued-Payload AVP is translated to a message that + contains RADIUS EAP-Message attribute(s), and a RADIUS Error-Cause + attribute [RFC3576] with value 202 (decimal), "Invalid EAP Packet + (Ignored)" [RFC3579]. + + o As described in [NASREQ], if the Result-Code AVP set to + DIAMETER_MULTI_ROUND_AUTH and the Multi-Round-Time-Out AVP is + present, it is translated to the RADIUS Session-Timeout attribute. + + o Diameter EAP-Master-Session-Key AVP can be translated to the + vendor-specific RADIUS MS-MPPE-Recv-Key and MS-MPPE-Send-Key + attributes [RFC2548]. The first up to 32 octets of the key is + stored into MS-MPPE-Recv-Key, and the next up to 32 octets (if + present) are stored into MS-MPPE-Send-Key. The encryption of this + attribute is described in [RFC2548]. + + o Diameter Accounting-EAP-Auth-Method AVPs, if present, are + discarded. + + + + + +Eronen, et al. Standards Track [Page 22] + +RFC 4072 Diameter EAP Application August 2005 + + +6.2. Diameter Request Forwarded as RADIUS Request + + Diameter-EAP-Request to RADIUS Access-Request: + + o The Diameter EAP-Payload AVP is translated to RADIUS EAP-Message + attribute(s). + + o An empty Diameter EAP-Payload AVP signifies EAP-Start, and is + translated to an empty RADIUS EAP-Message attribute. + + o The type (or expanded type) field from the EAP-Payload AVP can be + saved either in a local state table, or encoded in a RADIUS + Proxy-State attribute. This information is needed to construct an + Accounting-EAP-Auth-Method AVP for the answer message (see below). + + RADIUS Access-Accept/Reject/Challenge to Diameter-EAP-Answer: + + o If the RADIUS Access-Challenge message does not contain an + Error-Cause attribute [RFC3576] with value 202 (decimal), "Invalid + EAP Packet (Ignored)" [RFC3579], any RADIUS EAP-Message attributes + are translated to a Diameter EAP-Payload AVP, concatenating them + if multiple attributes are present. + + o If the Error-Cause attribute with value 202 is present, any RADIUS + EAP-Message attributes are translated to a Diameter + EAP-Reissued-Payload AVP, concatenating them if multiple + attributes are present. + + o As described in [NASREQ], if the Session-Timeout attribute is + present in a RADIUS Access-Challenge message, it is translated to + the Diameter Multi-Round-Time-Out AVP. + + o If the vendor-specific RADIUS MS-MPPE-Recv-Key and/or + MS-MPPE-Send-Key attributes [RFC2548] are present, they can be + translated to a Diameter EAP-Master-Session-Key AVP. The + attributes have to be decrypted before conversion, and the Salt, + Key-Length and Padding sub-fields are discarded. The Key + sub-fields are concatenated (MS-MPPE-Recv-Key first, + MS-MPPE-Send-Key next), and the concatenated value is stored into + a Diameter EAP-Master-Session-Key AVP. + + o If the Diameter-EAP-Answer will have a successful result code, the + saved state (see above) can be used to construct an + Accounting-EAP-Auth-Method AVP. + + + + + + + +Eronen, et al. Standards Track [Page 23] + +RFC 4072 Diameter EAP Application August 2005 + + +6.3. Accounting Requests + + In Accounting-Requests, the vendor-specific RADIUS MS-Acct-EAP-Type + attribute [RFC2548] can be translated to a Diameter + Accounting-EAP-Auth-Method AVP, and vice versa. + + When translating from Diameter to RADIUS, note that the + MS-Acct-EAP-Type attribute does not support expanded EAP types. Type + values greater than 255 should be translated to type 254. + +7. IANA Considerations + + This document does not create any new namespaces to be maintained by + IANA, but it requires new values in namespaces that have been defined + in the Diameter Base protocol and RADIUS specifications. + + o This document defines one new Diameter command (in Section 3) + whose Command Code is allocated from the Command Code namespace + defined in [BASE]. The Command Code for DER / DEA is 268. + + o This document defines four new AVPs whose AVP Codes are allocated + from the AVP Code namespace defined in [BASE] as follows: + + 462 for EAP-Payload (defined in Section 4.1.1), + 463 for EAP-Reissued-Payload (defined in Section 4.1.2), + 464 for EAP-Master-Session-Key (defined in Section 4.1.3), and + 465 for Accounting-EAP-Auth-Method (defined in Section 4.1.5). + + o This document defines one new AVP (attribute) whose AVP Code + (Attribute Type) is to be allocated from the Attribute Type + namespace defined in [RFC2865] and [RFC3575]. The Radius + Attribute Type for EAP-Key-Name (defined in Section 4.1.4) is 102. + + o This document defines one new Diameter application (in + Section 2.1) whose Application ID is to be allocated from the + Application Identifier namespace defined in [BASE]. The + Application ID for Diameter EAP is 5. + +8. Security Considerations + +8.1. Overview + + Diameter peer-to-peer connections can be protected with IPsec or TLS. + These mechanisms are believed to provide sufficient protection under + the normal Internet threat model, that is, assuming the authorized + nodes engaging in the protocol have not been compromised, but the + attacker has complete control over the communication channels between + them. This includes eavesdropping, message modification, insertion, + + + +Eronen, et al. Standards Track [Page 24] + +RFC 4072 Diameter EAP Application August 2005 + + + man-in-the-middle and replay attacks. The details and related + security considerations are discussed in [BASE]. + + In addition to authentication provided by IPsec or TLS, authorization + is also required. Here, authorization means determining if a + Diameter message received from an authenticated Diameter peer should + be accepted (and not authorization of users requesting network access + from a NAS). In other words, when a Diameter server receives a + Diameter-EAP-Request, it has to decide if the client is authorized to + act as a NAS for the specific user, service type, and so on. + Correspondingly, when a NAS contacts a server to send a + Diameter-EAP-Request, it has to determine whether the server is + authorized to act as home server for the realm in question. + + Authorization can involve local Access Control Lists (ACLs), + information contained in certificates, or some other means. See + [BASE] for more discussion and related security considerations. Note + that authorization issues are particularly relevant when Diameter + redirects are used. While redirection reduces the number of nodes + which have access to the contents of Diameter messages, a compromised + Diameter agent may not supply the right home server's address. If + the Diameter client is unable to tell whether this particular server + is authorized to act as the home server for this particular user, the + security of the communications rests on the redirect agent. + + The hop-by-hop security mechanisms (IPsec and TLS) combined with + proper authorization provide good protection against "outside" + attackers, except for denial-of-service attacks. The remaining part + of this section deals with attacks by nodes that have been properly + authorized (to function as a NAS, Diameter agent, or Diameter + server), but abuse their authorization or have been compromised. In + general, it is not possible to completely protect against attacks by + compromised nodes, but this section offers advice on limiting the + extent of the damage. + + Attacks involving eavesdropping or modification of EAP messages are + beyond the scope of these document. See [EAP] for discussion of + these security considerations (including method negotiation, + dictionary attacks, and privacy issues). While these attacks can be + carried out by an attacker between the client and the NAS, + compromised NASes and Diameter agents are naturally also in a good + position to modify and eavesdrop on the EAP messages. + + Similarly, attacks involving the link layer protocol used between the + client and the NAS, such as PPP or IEEE 802.11, are beyond the scope + of this document. + + + + + +Eronen, et al. Standards Track [Page 25] + +RFC 4072 Diameter EAP Application August 2005 + + +8.2. AVP Editing + + Diameter agents can modify, insert, and delete AVPs. Diameter agents + are usually meant to modify AVPs, and the protocol cannot distinguish + well-intentioned and malicious modifications (see [RFC2607] for more + discussion). Similarly, a compromised NAS or server can naturally + include a different set of AVPs than expected. + + Therefore, the question is what an attacker who compromises an + authorized NAS, agent, or server can do using Diameter EAP messages. + Some of the consequences are rather obvious. For instance, a + Diameter agent can give access to unauthorized users by changing the + Result-Code to DIAMETER_SUCCESS. Other consequences are less obvious + and are discussed below and authentication method negotiation attacks + are discussed in the next section. + + By including suitable AVPs in an AA-Answer/Diameter-EAP-Answer + messages, an attacker may be able (depending on implementation and + configuration details) to: + + o Give unauthorized users access, or deny access to authorized users + (Result-Code). + + o Give an attacker a login session to a host otherwise protected by + firewalls, or redirect an authorized user's login session to a + host controlled by the attacker (Login-Host). + + o Route an authorized user's traffic through a host controlled by + the attacker (various tunneling AVPs). + + o Redirect an authorized user's DNS requests to a malicious DNS + server (various vendor-specific AVPs). + + o Modify routing tables at the NAS and thus redirect packets + destined for someone else (Framed-Route, Framed-Routing). + + o Remove packet filters and other restrictions for user (Filter, + Callback, various vendor-specific AVPs). + + o Cause the NAS to call some number, possibly an expensive toll + number controlled by the attacker (callback AVPs). + + o Execute Command Line Interface (CLI) commands on the NAS (various + vendor-specific attributes). + + + + + + + +Eronen, et al. Standards Track [Page 26] + +RFC 4072 Diameter EAP Application August 2005 + + + By modifying an AA-Request/Diameter-EAP-Request, an attacker may be + able to: + + o Change NAS-Identifier/NAS-Port/Origin-Host (or another attribute) + so that a valid user appears to be accessing the network from a + different NAS than in reality. + + o Modify Calling-Station-ID (either to hide the true value, gain + access, or frame someone else). + + o Modify password change messages (some vendor-specific attributes). + + o Modify usage information in accounting messages. + + o Modify contents of Class and State AVPs. + + Some of these attacks can be prevented if the NAS or server is + configured to not accept some particular AVPs, or accepts them only + from some nodes. + +8.3. Negotiation Attacks + + This section deals with attacks where the NAS, any Diameter agents, + or Diameter server attempt to cause the authenticating user to choose + some authentication method other than EAP, such as PAP or CHAP + (negotiation attacks within EAP are discussed in [EAP], Section 7.8). + + The vulnerability can be mitigated via implementation of a per- + connection policy by the authenticating peer, and a per-user policy + by the Diameter server. For the authenticating peer, the + authentication policy should be set on a per-connection basis. + + With a per-connection policy, an authenticating peer will only + attempt to negotiate EAP for a session in which EAP support is + expected. As a result, it is presumed that an authenticating peer + selecting EAP requires that level of security. If it cannot be + provided, there is likely a misconfiguration, or the authenticating + peer may be contacting the wrong server. In this case, the + authenticating peer simply disconnects. + + Similarly, with a per-user policy, the home server will not accept + authentication methods other than EAP for users for which EAP support + is expected. + + For a NAS, it may not be possible to determine whether a peer is + required to authenticate with EAP until the peer's identity is known. + For example, for shared-uses NASes one reseller may implement EAP + while another does not. Alternatively, some peer might be + + + +Eronen, et al. Standards Track [Page 27] + +RFC 4072 Diameter EAP Application August 2005 + + + authenticated locally by the NAS while other peers are authenticated + via Diameter. In such cases, if any peers of the NAS MUST do EAP, + then the NAS MUST attempt to negotiate EAP for every session. This + avoids forcing a peer to support more than one authentication type, + which could weaken security. + +8.4. Session Key Distribution + + Since there are currently no end-to-end (NAS-to-home server) security + mechanisms specified for Diameter, any agents that process + Diameter-EAP-Answer messages can see the contents of the + EAP-Master-Session-Key AVP. For this reason, this specification + strongly recommends avoiding Diameter agents when they cannot be + trusted to keep the keys secret. + + In environments where agents are present, several factors should be + considered when deciding whether the agents that are authorized (and + considered "trustworthy enough") to grant access to users and specify + various authorization and tunneling AVPs are also "trustworthy + enough" to handle the session keys. These factors include (but are + not limited to) the type of access provided (e.g., public Internet or + corporate internet), security level of the agents, and the + possibilities for attacking user's traffic after it has been + decrypted by the NAS. + + Note that the keys communicated in Diameter messages are usually + short-term session keys (or short-term master keys that are used to + derive session keys). To actually cause any damage, those session + keys must end up with some malicious party that must be able to + eavesdrop, modify, or insert traffic between the user and the NAS + during the lifetime of those keys (for example, in 802.11i the + attacker must also eavesdrop the "four-way handshake"). + +8.5. Privacy Issues + + Diameter messages can contain AVPs that can be used to identify the + user (e.g., User-Name) and approximate location of the user (e.g., + Origin-Host for WLAN access points, Calling-Station-Id for fixed + phone lines). Thus, any Diameter nodes that process the messages may + be able to determine the geographic location of users. + + Note that in many cases, the user identity is also sent in clear + inside EAP-Payload AVPs, and it may be possible to eavesdrop this + between the user and the NAS. + + This can be mitigated somewhat by using EAP methods that provide + identity protection (see [EAP], Section 7.3), and using Session-Id or + pseudonyms for accounting. + + + +Eronen, et al. Standards Track [Page 28] + +RFC 4072 Diameter EAP Application August 2005 + + +8.6. Note about EAP and Impersonation + + If the EAP method used does not provide mutual authentication, + obviously anyone can impersonate the network to the user. Even when + EAP mutual authentication is used, it occurs between the user and the + Diameter home server. See [EAPKey] for an extensive discussion about + the details and their implications. + + One issue is worth pointing out here. As described in [EAPKey], the + current EAP architecture does not allow the home server to restrict + what service parameters or identities (such as SSID or BSSID in + 802.11 wireless LANs) are advertised by the NAS to the client. That + is, a compromised NAS can change its BSSID or SSID, and thus appear + to offer a different service than intended. Even if these parameters + are included in Diameter-EAP-Answer messages, the NAS can tell + different values to the client. + + Therefore, the NAS's possession of the session keys proves that the + user is talking to an authorized NAS, but a compromised NAS can lie + about its exact identity. See [EAPKey] for discussion on how + individual EAP methods can provide authentication of NAS service + parameters and identities. + + Note that the usefulness of this authentication may be rather limited + in many environments. For instance, in wireless LANs the user does + not usually securely know the identity (such as BSSID) of the "right" + access point; it is simply picked from a beacon message that has the + correct SSID and good signal strength (something that is easy to + spoof). Thus, simply authenticating the identity may not allow the + user to distinguish the "right" access point from all others. + +9. Acknowledgements + + This Diameter application relies heavily on earlier work on Diameter + NASREQ application [NASREQ] and RADIUS EAP support [RFC3579]. Much + of the material in this specification has been copied from these + documents. + + The authors would also like to acknowledge the following people for + their contributions to this document: Bernard Aboba, Jari Arkko, + Julien Bournelle, Pat Calhoun, Henry Haverinen, John Loughney, + Yoshihiro Ohba, and Joseph Salowey. + + + + + + + + + +Eronen, et al. Standards Track [Page 29] + +RFC 4072 Diameter EAP Application August 2005 + + +10. References + +10.1. Normative References + + [BASE] Calhoun, P., Loughney, J., Guttman, E., Zorn, G., and + J. Arkko, "Diameter Base Protocol", RFC 3588, + September 2003. + + [EAP] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and + H. Levkowetz, "Extensible Authentication Protocol + (EAP)", RFC 3748, June 2004. + + [NASREQ] Calhoun, P., Zorn, G., Spence, D., and D. Mitton, + "Diameter Network Access Server Application", RFC + 4005, August 2005. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + +10.2. Informative References + + [EAPKey] Aboba, B., Simon, D., Arkko, J., Eronen, P., and H. + Levkowetz, "Extensible Authentication Protocol (EAP) + Key Management Framework", Work in Progress, July + 2004. + + [IEEE-802.1X] Institute of Electrical and Electronics Engineers, + "Local and Metropolitan Area Networks: Port-Based + Network Access Control", IEEE Standard 802.1X, + September 2001. + + [IEEE-802.11i] Institute of Electrical and Electronics Engineers, + "IEEE Standard for Information technology - + Telecommunications and information exchange between + systems - Local and metropolitan area networks - + Specific requirements - Part 11: Wireless Medium + Access Control (MAC) and Physical Layer (PHY) + Specifications: Amendment 6: Medium Access Control + (MAC) Security Enhancements", IEEE Standard + 802.11i-2004, July 2004. + + [IKEv2] Kaufman, C., Ed., "Internet Key Exchange (IKEv2) + Protocol", Work in Progress, June 2004. + + [RFC1661] Simpson, W., "The Point-to-Point Protocol (PPP)", + STD 51, RFC 1661, July 1994. + + + + + +Eronen, et al. Standards Track [Page 30] + +RFC 4072 Diameter EAP Application August 2005 + + + [RFC2548] Zorn, G., "Microsoft Vendor-specific RADIUS + Attributes", RFC 2548, March 1999. + + [RFC2607] Aboba, B. and J. Vollbrecht, "Proxy Chaining and + Policy Implementation in Roaming", RFC 2607, + June 1999. + + [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, + "Remote Authentication Dial In User Service (RADIUS)", + RFC 2865, June 2000. + + [RFC3575] Aboba, B., "IANA Considerations for RADIUS (Remote + Authentication Dial In User Service)", RFC 3575, + July 2003. + + [RFC3576] Chiba, M., Dommety, G., Eklund, M., Mitton, D., and B. + Aboba, "Dynamic Authorization Extensions to Remote + Authentication Dial In User Service (RADIUS)", + RFC 3576, July 2003. + + [RFC3579] Aboba, B. and P. Calhoun, "RADIUS (Remote + Authentication Dial In User Service) Support For + Extensible Authentication Protocol (EAP)", RFC 3579, + September 2003. + + [RFC3580] Congdon, P., Aboba, B., Smith, A., Zorn, G., and J. + Roese, "IEEE 802.1X Remote Authentication Dial In User + Service (RADIUS) Usage Guidelines", RFC 3580, + September 2003. + + + + + + + + + + + + + + + + + + + + + + +Eronen, et al. Standards Track [Page 31] + +RFC 4072 Diameter EAP Application August 2005 + + +Authors' Addresses + + Pasi Eronen (editor) + Nokia Research Center + P.O. Box 407 + FIN-00045 Nokia Group + Finland + + EMail: [email protected] + + + Tom Hiller + Lucent Technologies + 1960 Lucent Lane + Naperville, IL 60566 + USA + + Phone: +1 630 979 7673 + EMail: [email protected] + + + Glen Zorn + Cisco Systems + 500 108th Avenue N.E., Suite 500 + Bellevue, WA 98004 + USA + + Phone: +1 425 344 8113 + EMail: [email protected] + + + + + + + + + + + + + + + + + + + + + + +Eronen, et al. Standards Track [Page 32] + +RFC 4072 Diameter EAP Application August 2005 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2005). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + +Eronen, et al. Standards Track [Page 33] + diff --git a/lib/diameter/doc/standard/rfc4740.txt b/lib/diameter/doc/standard/rfc4740.txt new file mode 100644 index 0000000000..2154334b66 --- /dev/null +++ b/lib/diameter/doc/standard/rfc4740.txt @@ -0,0 +1,4035 @@ + + + + + + +Network Working Group M. Garcia-Martin, Ed. +Request for Comments: 4740 Nokia +Category: Standards Track M. Belinchon + M. Pallares-Lopez + C. Canales-Valenzuela + Ericsson + K. Tammi + Nokia + November 2006 + + + Diameter Session Initiation Protocol (SIP) Application + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The IETF Trust (2006). + +Abstract + + This document specifies the Diameter Session Initiation Protocol + (SIP) application. This is a Diameter application that allows a + Diameter client to request authentication and authorization + information. This application is designed to be used in conjunction + with SIP and provides a Diameter client co-located with a SIP server, + with the ability to request the authentication of users and + authorization of SIP resources usage from a Diameter server. + + + + + + + + + + + + + + + + + +Garcia-Martin, et al. Standards Track [Page 1] + +RFC 4740 Diameter SIP Application November 2006 + + +Table of Contents + + 1. Introduction ....................................................4 + 2. Terminology .....................................................5 + 3. Definitions .....................................................5 + 4. Acronyms ........................................................6 + 5. Applicability Statement .........................................6 + 6. Overview of Operation ...........................................7 + 6.1. General Architecture .......................................7 + 6.2. Diameter Server Authenticates the User .....................9 + 6.3. Delegating Final Authentication Check to the SIP Server ...12 + 6.4. SIP Server Requests Authentication and Authorization ......15 + 6.5. Locating the Recipient of the SIP Request .................16 + 6.6. Update of the User Profile ................................17 + 6.7. SIP Soft State Termination ................................18 + 6.8. Diameter Server Discovery .................................19 + 7. Advertising Application Support ................................21 + 8. Diameter SIP Application Command Codes .........................22 + 8.1. User-Authorization-Request (UAR) Command ..................22 + 8.2. User-Authorization-Answer (UAA) Command ...................23 + 8.3. Server-Assignment-Request (SAR) Command ...................27 + 8.4. Server-Assignment-Answer (SAA) Command ....................29 + 8.5. Location-Info-Request (LIR) Command .......................33 + 8.6. Location-Info-Answer (LIA) Command ........................33 + 8.7. Multimedia-Auth-Request (MAR) Command .....................35 + 8.8. Multimedia-Auth-Answer (MAA) Command ......................36 + 8.9. Registration-Termination-Request (RTR) Command ............39 + 8.10. Registration-Termination-Answer (RTA) Command ............39 + 8.11. Push-Profile-Request (PPR) Command .......................41 + 8.12. Push-Profile-Answer (PPA) Command ........................42 + 9. Diameter SIP Application AVPs ..................................44 + 9.1. SIP-Accounting-Information AVP ............................46 + 9.1.1. SIP-Accounting-Server-URI AVP ......................47 + 9.1.2. SIP-Credit-Control-Server-URI AVP ..................47 + 9.2. SIP-Server-URI AVP ........................................47 + 9.3. SIP-Server-Capabilities AVP ...............................47 + 9.3.1. SIP-Mandatory-Capability AVP .......................48 + 9.3.2. SIP-Optional-Capability AVP ........................48 + 9.4. SIP-Server-Assignment-Type AVP ............................48 + 9.5. SIP-Auth-Data-Item AVP ....................................50 + 9.5.1. SIP-Authentication-Scheme AVP ......................50 + 9.5.2. SIP-Item-Number AVP ................................51 + 9.5.3. SIP-Authenticate AVP ...............................51 + 9.5.4. SIP-Authorization AVP ..............................52 + 9.5.5. SIP-Authentication-Info AVP ........................52 + 9.5.6. Digest AVPs ........................................53 + 9.6. SIP-Number-Auth-Items AVP .................................55 + + + + +Garcia-Martin, et al. Standards Track [Page 2] + +RFC 4740 Diameter SIP Application November 2006 + + + 9.7. SIP-Deregistration-Reason AVP .............................55 + 9.7.1. SIP-Reason-Code AVP ................................55 + 9.7.2. SIP-Reason-Info AVP ................................56 + 9.8. SIP-AOR AVP ...............................................56 + 9.9. SIP-Visited-Network-Id AVP ................................56 + 9.10. SIP-User-Authorization-Type AVP ..........................56 + 9.11. SIP-Supported-User-Data-Type AVP .........................57 + 9.12. SIP-User-Data AVP ........................................57 + 9.12.1. SIP-User-Data-Type AVP ............................58 + 9.12.2. SIP-User-Data-Contents AVP ........................58 + 9.13. SIP-User-Data-Already-Available AVP ......................58 + 9.14. SIP-Method AVP ...........................................59 + 10. New Values for Existing AVPs ..................................59 + 10.1. Extension to the Result-Code AVP Values ..................59 + 10.1.1. Success Result-Code AVP Values ....................59 + 10.1.2. Transient Failures Result-Code AVP Values .........60 + 10.1.3. Permanent Failures Result-Code AVP Values .........60 + 11. Authentication Details ........................................61 + 12. Migration from RADIUS .........................................63 + 12.1. Gateway from RADIUS Client to Diameter Server ............63 + 12.2. Gateway from Diameter Client to RADIUS Server ............63 + 12.3. Known Limitations ........................................64 + 13. IANA Considerations ...........................................64 + 13.1. Application Identifier ...................................64 + 13.2. Command Codes ............................................65 + 13.3. AVP Codes ................................................65 + 13.4. Additional Values for the Result-Code AVP Value ..........65 + 13.5. Creation of the SIP-Server-Assignment-Type + Section in the AAA .......................................66 + 13.6. Creation of the SIP-Authentication-Scheme Section + in the AAA ...............................................66 + 13.7. Creation of the SIP-Reason-Code Section in the + AAA Registry .............................................66 + 13.8. Creation of the SIP-User-Authorization-Type + Section in the AAA .......................................66 + 13.9. Creation of the SIP-User-Data-Already-Available + Section in the ...........................................66 + 14. Security Considerations .......................................67 + 14.1. Final Authentication Check in the Diameter + Client/SIP Server ........................................67 + 15. Contributors ..................................................68 + 16. Acknowledgements ..............................................68 + 17. References ....................................................68 + 17.1. Normative References .....................................68 + 17.2. Informative References ...................................69 + + + + + + +Garcia-Martin, et al. Standards Track [Page 3] + +RFC 4740 Diameter SIP Application November 2006 + + +1. Introduction + + This document specifies the Diameter Session Initiation Protocol + (SIP) application. This is a Diameter application that allows a + Diameter client to request authentication and authorization + information to a Diameter server for SIP-based IP multimedia services + (see [RFC3261] about SIP). Furthermore, this Diameter SIP + application provides the Diameter client with functions that go + beyond the typical authorization and authentication, such as the + ability to download or receive updated user profiles, or rudimentary + routing functions that can assist a SIP server in finding another SIP + server allocated to the user. + + We assume that the SIP server (such as SIP proxy server, registrar, + redirect server, or alike) and the Diameter client are co-located in + the same node, so that the SIP server is able to receive and process + SIP requests and responses. In turn, the SIP server relies on the + Authentication, Authorization, and Accounting (AAA) infrastructure + for authenticating the SIP request and authorizing the usage of + particular SIP services. + + This document provides Diameter procedures to implement certain + required functionality when SIP is the protocol chosen to initiate + and tear down multimedia sessions or when SIP is used for other + non-session-related applications. However, this document does not + mandate any particular mapping of SIP procedures to Diameter SIP + application procedures, nor does it mandate any particular sequence + of events between SIP and Diameter. This document provides useful + examples to show the interaction between SIP and the Diameter SIP + application in order to achieve the desired functionality. + + This application does not require and is not related to other + authentication services provided by the Diameter Mobile IPv4 + [RFC4004] or the Diameter Network Access Server [RFC4005] + applications. + + This Diameter SIP application is loosely related to the Diameter + credit-control application [RFC4006]. Although both applications are + independent, the Diameter SIP application is able to supply the + addresses of credit-control servers that will be implementing the + Diameter credit-control application [RFC4006]. + + Section 5 discusses assumptions and configurations assumed by this + document. + + Section 6 provides the reader with informative descriptions of the + Diameter SIP application commands and responses and with some + guidance about their linkage with SIP procedures. + + + +Garcia-Martin, et al. Standards Track [Page 4] + +RFC 4740 Diameter SIP Application November 2006 + + + Advertisement of this application is specified in Section 7. + + Section 8 provides a normative description of all the new Diameter + commands defined by this specification. + + This application extends the Result-Code Attribute-Value-Pair (AVP) + with some new values. Further information is described in + Section 10. + + This application defines some new AVPs. All these AVPs are described + in Section 9. + + Some extra information about authentication is provided in + Section 11. + +2. Terminology + + In this document, the key words "MUST", "MUST NOT", "REQUIRED", + "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT + RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as + described in BCP 14, RFC 2119 [RFC2119] and indicate requirement + levels for compliant implementations. + +3. Definitions + + For the purpose of this document, the following terms and definitions + apply: + + Node: an addressable device attached to a computer network that + implements SIP functionality, Diameter functionality, or a + combination of both. + + For the purpose of this document, the following terms and definitions + given in RFC 3261 [RFC3261] Section 6, apply: + + o Address-of-Record (AOR) + o Outbound proxy + o Proxy + o Registrar + o Server (SIP server) + o User Agent (UA) + o User Agent Client (UAC) + o User Agent Server (UAS) + + For the purpose of this document, the following terms and definitions + given in RFC 3588 [RFC3588] Section 1.3, apply: + + + + + +Garcia-Martin, et al. Standards Track [Page 5] + +RFC 4740 Diameter SIP Application November 2006 + + + o Authorization + o Authentication + o Attribute-Value Pair (AVP) + o Diameter Client + o Diameter Server + o Home Realm + o Redirect Agent + o User + +4. Acronyms + + AKA: Authentication and Key Agreement + LIR: Location-Info-Request + LIA: Location-Info-Answer + MAR: Multimedia-Auth-Request + MAA: Multimedia-Auth-Answer + PPR: Push-Profile-Request + PPA: Push-Profile-Answer + RTR: Registration-Termination-Request + RTA: Registration-Termination-Answer + SAR: Server-Assignment-Request + SAA: Server-Assignment-Answer + SL: Subscriber Locator + UAR: User-Authorization-Request + UAA: User-Authorization-Answer + +5. Applicability Statement + + This document assumes a general architecture where a Home Realm is + composed of one or more nodes implementing Diameter or SIP functions. + Users are issuing SIP requests to access SIP resources. For each + particular user, the Home Realm needs to authenticate and authorize + the usage of those resources and/or the route to the appropriate + node. We assume that the database containing the user-related data + is located outside the SIP node that requires authorization. Data + belonging to different users may be stored in different nodes in the + Home Realm, but we assume that all the data related to a particular + user is stored in a single node. + + Note: Central to the architecture is the fact that the user data + is stored in a single point in the network. This restriction does + not mandate a particular implementation, e.g., it is possible to + implement clusters of databases operating in mirror mode to + provide redundancy. The property required by this specification + is that the user data the Diameter server has access to is stored + safely in what is seen, from the external point of view, as a + single user database. + + + + +Garcia-Martin, et al. Standards Track [Page 6] + +RFC 4740 Diameter SIP Application November 2006 + + + This document allows several configurations of the Home Realm. In + one configuration, a SIP server (proxy, registrar, etc.) is allocated + to a user for the purpose of triggering and executing services. The + allocation of the SIP server may be done dynamically, e.g., at the + time the user registers in the network. This configuration requires + a SIP server, typically located at the edge of the network, that is + able to allocate another SIP server for the user and that also + supports routing of SIP requests and responses towards that allocated + SIP server. Both SIP server nodes implement a Diameter client. + + In another configuration, the address of a SIP outbound proxy is + configured (by means outside the scope of this specification) into + the SIP User Agent. The outbound Diameter client in the SIP outbound + proxy node authenticates the user, requests authorization for SIP + requests, and performs accounting activities. + +6. Overview of Operation + + This section provides an informative description of how the Diameter + SIP application can be used together with SIP. This section is not + intended to mandate any specific usage of the Diameter SIP + application nor does it mandate a specific mapping between SIP and + Diameter messages. We provide a collection of examples that show how + the required AAA functionality can be achieved in conjunction with + SIP. + +6.1. General Architecture + + The Diameter SIP application can be used in a SIP environment where + an interface to a AAA infrastructure is required to authenticate and + authorize the usage of SIP resources. This application provides + support for SIP User Agents and proxies that implement and use HTTP + Digest authentication [RFC2617], which is the authentication + mechanism mandated by SIP [RFC3261]. The application is extensible + and, if need arises, it can be extended to provide support for other + authentication mechanisms or extensions to HTTP Digest authentication + when they occur. + + This application provides limited support for accounting services as + follows: the Diameter server is able to provide the addresses of + accounting severs to the Diameter client. Figure 1, below, shows a + general overview of the integration of the SIP architecture with the + AAA architecture. + + According to Figure 1, there are one or more SIP User Agents (UAs) + that initiate or terminate SIP traffic through one or more SIP + servers. Both SIP servers implement a Diameter client that supports + the Diameter application described in this specification. + + + +Garcia-Martin, et al. Standards Track [Page 7] + +RFC 4740 Diameter SIP Application November 2006 + + + +--------+ + UAR/UAA +--->|Diameter|<----+ PPR/PPA + LIR/LIA | | server | | MAR/MAA + | +--------+ | SAR/SAA + | | RTR/RTA + | | + v v + +------+ SIP +--------+ SIP +--------+ SIP +------+ + | SIP |<--------->| SIP |<-------->| SIP |<--------->| SIP | + | UA | |server 1| |server 2| | UA | + +------+ +--------+ +--------+ +------+ + ^ ^ + UAR/UAA | | + LIR/LIA | | MAR/MAA + | +--------+ | SAR/SAA + +--->|Diameter|<----+ + | SL | + +--------+ + + Figure 1: Architecture of the Diameter application for SIP + + In Figure 1, it can be seen that SIP server 1 sends different + Diameter commands and receives different responses than those sent + and received by SIP server 2. This is because SIP server 1 in + Figure 1 is located at the edge of a network, and its main task is to + locate SIP server 2. SIP server 2 is requesting and receiving + authentication and authorization data from the Diameter server and is + not located at the edge of the network. + + This Diameter application assumes that all the data pertaining to a + given user is stored in a single Diameter server. For redundancy + purposes, several Diameter servers can be configured in a redundancy + fashion, in which case all of them keep the data synchronized and + operate externally as a single Diameter server. + + With respect to SIP server 1 in Figure 1, the Diameter SIP + application provides support for the existence of a farm of these + servers, typically configured through one or more DNS records that + point to several hosts (this is a typical configuration in common SIP + deployments). There is no requirement for these types of servers to + keep state related to the Diameter SIP application. + + The Diameter SIP application provides support for a feature that + allows an administrative domain to provide a collection of SIP + servers 2 (as per Figure 1). Once the user registers for the first + time, one of these SIP servers is selected and all the SIP requests + related to the user are processed by the same SIP server. + + + + +Garcia-Martin, et al. Standards Track [Page 8] + +RFC 4740 Diameter SIP Application November 2006 + + + The Diameter Subscriber Locator (SL) serves the purpose of locating + the Diameter server that contains the user-related data. Its + functionality is based on the Diameter redirect mechanism and is + further described in Section 6.8. + + It should be noted that this document does not mandate any particular + SIP/AAA architecture. However, the Diameter SIP application provides + the functionality needed to accommodate all the different + architectures where SIP and Diameter are used. + + The following subsections provide an informative overview of the + Diameter SIP application, its commands, and a possible interaction + with SIP signaling. + +6.2. Diameter Server Authenticates the User + + This is the generic mechanism to authenticate users. In this + approach, we show an example of an administrative network where the + Diameter server is authenticating SIP user requests. This could be + the case of a medium-size network where the Diameter server is + keeping user records and authenticating SIP requests to perform a + certain transaction. We have chosen to show a SIP REGISTER request + in the example, but the SIP server could request authentication of + any other SIP request. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Garcia-Martin, et al. Standards Track [Page 9] + +RFC 4740 Diameter SIP Application November 2006 + + + +--------+ +--------+ +--------+ + | SIP | |Diameter| | SIP | + |server 1| | server | |server 2| + +--------+ +--------+ +--------+ + | | | + 1. SIP REGISTER | | | + -------------------->| 2. UAR | | + |------------------>| | + | 3. UAA | | + |<------------------| | + | 4. SIP REGISTER | + |-------------------------------------->| + | | 5. MAR | + | |<------------------| + | | 6. MAA | + | |------------------>| + | 7. SIP 401 (Unauthorized) | + 8. SIP 401 (Unauth.) |<--------------------------------------| + <--------------------| | | + 9. SIP REGISTER | | | + -------------------->| 10. UAR | | + |------------------>| | + | 11. UAA | | + |<------------------| | + | 12. SIP REGISTER | + |-------------------------------------->| + | | 13. MAR | + | |<------------------| + | | 14. MAA | + | |------------------>| + | 15. SIP 200 (OK) | + 16. SIP 200 (OK) |<--------------------------------------| + <--------------------| | | + | | 17. SAR | + | |<------------------| + | | 18. SAA | + | |------------------>| + | | | + + Figure 2: Authentication performed in the Diameter server + + According to Figure 2, a SIP User Agent Client (UAC) sends a SIP + REGISTER request (step 1) to SIP server 1, which receives the SIP + request. In Figure 2, we assume that this SIP server is located at + the edge of the administrative home domain. The Diameter client in + SIP server 1 contacts its Diameter server by sending a Diameter + User-Authorization-Request (UAR) message (step 2) to determine if + this user is allowed to receive service, and if so, request the + + + +Garcia-Martin, et al. Standards Track [Page 10] + +RFC 4740 Diameter SIP Application November 2006 + + + address of a local SIP server capable of handling this user. The + Diameter server answers with a Diameter User-Authorization-Answer + (UAA) message (step 3), which indicates a list of capabilities that + SIP server 1 may use to select an appropriate SIP server (SIP server + 2) and/or a SIP or SIPS URI pointing to SIP server 2. + + SIP server 1 forwards the SIP REGISTER request (step 4) to an + appropriate SIP server (SIP server 2). Then the Diameter client in + SIP server 2 requests user authentication from the Diameter server by + sending a Diameter Multimedia-Auth-Request (MAR) message (step 5). + This request also serves to make the Diameter server aware of the SIP + or SIPS URI of SIP server 2, so as to return subsequent requests for + the same user to the same SIP server 2. The Diameter server responds + with a Diameter Multimedia-Auth-Answer (MAA) message (step 6) with + Result-Code AVP set to the value DIAMETER_MULTI_ROUND_AUTH. The + Diameter server also generates a nonce and includes a challenge in + the MAA message. SIP server 2 uses that challenge to map into the + WWW-Authenticate header in the SIP 401 (Unauthorized) response (step + 7), which is sent back to SIP server 1 and then to the SIP UAC (step + 8). + + SIP server 1 receives a next SIP REGISTER request containing the user + credentials (step 9). Note that SIP server 1 does not need to keep a + state, and even more, there is no guarantee that the SIP request + arrives at the same SIP server 1; there could be a farm of SIP + servers 1 operating in redundant configuration. The Diameter client + in SIP server 1 contacts the Diameter server by sending a Diameter + UAR message (step 10) to determine the SIP server allocated to the + user. The Diameter server sends the SIP or SIPS URI of SIP server 2 + in a Diameter UAA message (step 11). + + Then SIP server 1 forwards the SIP REGISTER request to SIP server 2 + (step 12). SIP server 2 extracts the credentials from the SIP + REGISTER request. The Diameter client in SIP server 2 sends those + credentials in a Diameter MAR message (step 13) to the Diameter + server. At this point, the Diameter server is able to authenticate + the user, and upon success, returns a Diameter MAA message (step 14) + with the AVP Result-Code set to the value DIAMETER_SUCCESS. + + Then SIP server 2 generates a SIP 200 (OK) response (step 15), which + is forwarded to SIP server 1 and eventually to the SIP UAC (step 16). + + If the Diameter client in SIP server 2 is interested in downloading + the user profile information or is required to store the address of + the SIP server in the Diameter server, then the Diameter client sends + a Diameter SAR message (step 17) to the Diameter server. The + Diameter server replies with a Diameter SAA message (step 18) that + contains the requested user profile information and the + + + +Garcia-Martin, et al. Standards Track [Page 11] + +RFC 4740 Diameter SIP Application November 2006 + + + acknowledgement of the SIP server address storage. These actions are + needed when the SIP server has to retrieve a user profile used to + provide services to the served user, or when the SIP server keeps a + state for the user, so the Diameter server needs to store the SIP + server's address. + +6.3. Delegating Final Authentication Check to the SIP Server + + An operator with a large base of installed SIP servers may wish to + minimize the number of round-trips between the Diameter client and + the Diameter server. We provide support for a mechanism where the + Diameter server delegates the final authentication check to the SIP + server, thereby saving a round-trip. Section 14.1 discusses the + security considerations of this scenario. + + It must noted that this scenario is not applicable when the Diameter + server is configured to use a session MD5 (MD5-sess) algorithm, + because the Diameter server requires the client nonce to compute the + H(A1) before sending it to the Diameter client. However, the client + nonce might not be available at that time. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Garcia-Martin, et al. Standards Track [Page 12] + +RFC 4740 Diameter SIP Application November 2006 + + + +--------+ +--------+ +--------+ + | SIP | |Diameter| | SIP | + |server 1| | server | |server 2| + +--------+ +--------+ +--------+ + | | | + 1. SIP REGISTER | | | + -------------------->| 2. UAR | | + |------------------>| | + | 3. UAA | | + |<------------------| | + | 4. SIP REGISTER | + |-------------------------------------->| + | | 5. MAR | + | |<------------------| + | | 6. MAA | + | |------------------>| + | 7. SIP 401 (Unauthorized) | + 8. SIP 401 (Unauth.) |<--------------------------------------| + <--------------------| | | + 9. SIP REGISTER | | | + -------------------->| 10. UAR | | + |------------------>| | + | 11. UAA | | + |<------------------| | + | 12. SIP REGISTER | + |-------------------------------------->| + | | 13. SAR | + | |<------------------| + | | 14. SAA | + | |------------------>| + | 15. SIP 200 (OK) | + 16. SIP 200 (OK) |<--------------------------------------| + <--------------------| | | + | | | + + Figure 3: Delegation of authentication to the SIP server + + Figure 3 shows an example where a SIP server is dynamically allocated + to serve a SIP User Agent with the support of the Diameter server. + This may be the case of certain architectures, such as that of the + 3rd Generation Partnership Project (3GPP) IP Multimedia Core Network + Subsystem. + + A first SIP server receives a SIP REGISTER request (step 1) whose + target is the home network domain. In Figure 3, we assume that this + SIP server is located at the edge of the administrative home domain. + The Diameter client in this SIP server requests authorization from + the Diameter server to proceed with the registration, by sending a + + + +Garcia-Martin, et al. Standards Track [Page 13] + +RFC 4740 Diameter SIP Application November 2006 + + + Diameter User-Authorization-Request (UAR) message (step 2). The + message includes, among other Attribute-Value-Pairs (AVPs), the SIP + Address-Of-Record (AOR) that is included in the SIP REGISTER request. + The Diameter server verifies the SIP AOR and, if it is a valid + defined user in the home network, authorizes the registration to + proceed. The Diameter server responds with a Diameter + User-Authorization-Answer (UAA) message (step 3), which informs the + Diameter client/SIP server about the result of the user + authorization. In case of a successful authorization, the Diameter + UAA message indicates the address of a local SIP server (SIP server 2 + in Figure 3) and/or a list of capabilities that SIP server 1 may use + to select an appropriate SIP server 2. + + When the authorization is successful, SIP server 1 forwards the SIP + REGISTER request (step 4) to the appropriate SIP server (SIP server + 2). The Diameter client in SIP server 2 requests authentication + parameters by sending a Diameter Multimedia-Auth-Request (MAR) + message (step 5) to the Diameter server. This request also makes the + Diameter server aware of the SIP or SIPS URI of SIP server 2, so as + to return subsequent requests of the same user to the same SIP server + 2. The Diameter server responds with a Diameter + Multimedia-Auth-Answer (MAA) message (step 6), which includes a nonce + and all the rest of the parameters necessary for the designated + authentication algorithm associated with the user. Among others, the + MAA message includes a Digest-HA1 AVP that contains H(A1) (as defined + in RFC 2617 [RFC2617]), and that allows the Diameter client to + calculate the expected response. Then the Diameter client can + compare this expected response with the response to the challenge + sent from the SIP UA. The absence of the Digest-HA1 AVP in MAA + indicates that authentication and authorization take place in the + Diameter server, as per the scenario described in Section 6.2. + + SIP server 2 creates a SIP 401 (Unauthorized) SIP response (step 7) + based on the challenge included in the MAA message, including the + authentication material needed by the SIP User Agent Client (UAC) to + include the appropriate credentials. SIP server 1 forwards the SIP + response to the SIP UAC (step 8). + + The SIP server 1 receives the next SIP REGISTER request containing + the user credentials (step 9). Because SIP server 1 does not need to + keep a state (and there is no guarantee that the SIP request arrives + to the same SIP server 1), the Diameter client in SIP server 1 + contacts the Diameter server again by sending a Diameter UAR message + (step 10) to determine the SIP server allocated to the user. The + Diameter server sends the SIP or SIPS URI of SIP server 2 in a + Diameter UAA message (step 11). + + + + + +Garcia-Martin, et al. Standards Track [Page 14] + +RFC 4740 Diameter SIP Application November 2006 + + + SIP server 1 forwards the SIP REGISTER request to SIP server 2 (step + 12). SIP server 2 validates the credentials by comparing the + response supplied by the SIP UA with the expected response calculated + by the SIP server 2 (based on the H(A1) received from the Diameter + server). + + If the credentials are valid, SIP server 2 sends a Diameter + Server-Assignment-Request (SAR) message (step 13) requesting the + Diameter server to confirm the completion of the authentication + procedure and to confirm the SIP or SIPS URI of the SIP server that + is currently serving the user. The Diameter SAR message also serves + the purpose of requesting that the Diameter server send the user + profile to the SIP server. The Diameter server responds with a + Diameter Server-Assignment-Answer (SAA) message (step 14). If the + Result-Code AVP value does not inform SIP Server 2 of an error, the + SAA message can include zero or more SIP-User-Data AVPs containing + the information that SIP server 2 needs in order to provide a service + to the user. + + SIP server 2 generates a SIP 200 (OK) response (step 15), which is + forwarded to SIP server 1 and eventually to the SIP UAC (step 16). + +6.4. SIP Server Requests Authentication and Authorization + + Figure 4 depicts a typical scenario where a stateless SIP proxy + requests authentication information and authorization to a Diameter + server, for the purpose of providing SIP routing services to a SIP + User Agent. The SIP proxy server may be configured as an outbound + SIP proxy, so that all the requests initiated by the SIP UA traverse + the SIP proxy. + + According to Figure 4, a SIP User Agent sends a SIP request to its + outbound SIP proxy server. In this case, the message is a SIP INVITE + request (see step 1), but it could be any other SIP request. We + assume that this SIP request does not contain any credentials at this + time. The outbound SIP proxy server needs to authenticate and + authorize the proxy services offered to the user. The Diameter + client in the SIP server sends a Multimedia-Auth-Request (MAR) + message (step 2). The Diameter server generates a nonce and sends a + Multimedia-Auth-Answer (MAA) message (step 3) that includes the nonce + and the rest of the data necessary for the SIP server to challenge + the user, typically with HTTP Digest Authentication indicated in the + MAA message. This data enables the SIP server to create a SIP 407 + (Proxy Authentication Required) response (step 4) that contains a + challenge. The SIP UA creates a new INVITE request (step 5) that + contains the credentials. The Diameter client in the SIP server + sends the credentials to the Diameter server in a new Diameter MAR + message (step 6). The Diameter server validates the credentials and + + + +Garcia-Martin, et al. Standards Track [Page 15] + +RFC 4740 Diameter SIP Application November 2006 + + + authorize the SIP transaction in a Diameter MAA message (step 7). + The SIP server forwards the SIP INVITE request to its destination + (step 8) as per regular SIP procedures. Eventually, the session + setup is confirmed with a SIP 200 (OK) response (step 9) that is + forwarded to the SIP UA (step 10). The session setup is complete. + + +--------+ +--------+ + |Diameter| | SIP | + | server | | server | + +--------+ +--------+ + | | + | | + 1. SIP INVITE | + ----------------------------------->| + | 2. MAR | + |<------------------| + | 3. MAA | + |------------------>| + | | + 4. SIP 407 (Proxy | + Authentication Required) | + <-----------------------------------| + | | + 5. SIP INVITE | + ----------------------------------->| + | 6. MAR | + |<------------------| + | 7. MAA | + |------------------>| 8. SIP INVITE + | |----------------> + | | 9. SIP 200 (OK) + 10. SIP 200 (OK) |<---------------- + <-----------------------------------| + | | + + Figure 4: SIP server requests authorization + +6.5. Locating the Recipient of the SIP Request + + Figure 5 shows the scenario where SIP server 1 may be configured as a + SIP edge proxy server, processing SIP traffic at the edge of a + network. SIP server 1 receives a SIP INVITE request (step 1). SIP + server 1 needs to find the address of SIP server 2, which is serving + the recipient of the SIP request. The Diameter client in SIP server + 1 sends a Diameter Location-Info-Request (LIR) message (step 2) to + the Diameter server. The Diameter server responds with a Diameter + Location-Info-Answer (LIA) message (step 3) that contains the SIP or + + + + +Garcia-Martin, et al. Standards Track [Page 16] + +RFC 4740 Diameter SIP Application November 2006 + + + SIPS URI of SIP server 2. SIP server 1 then forwards the SIP INVITE + to SIP server 2 (step 4). SIP server 2 eventually forwards the SIP + INVITE to the appropriate UAS (step 5). + + +--------+ +--------+ +--------+ + | SIP | |Diameter| | SIP | + |server 1| | server | |server 2| + +--------+ +--------+ +--------+ + | | | + 1. SIP INVITE | | | + -------------->| 2. LIR | | + |---------------->| | + | 3. LIA | | + |<----------------| | + | 4. SIP INVITE | + |--------------------------------->| + | | | 5. SIP INVITE + | | |--------------> + | | | + | | | + + Figure 5: Locating the SIP server of the recipient + + Although the example shows the connection between a SIP INVITE + request and the Diameter LIR message, any SIP request other than + REGISTER (such as SUBSCRIBE, OPTIONS, etc.) would trigger the same + Diameter message. (A SIP REGISTER request will trigger a Diameter + UAR message, as indicated in Figure 2 and Figure 3.) + + The scenario described in this section is also applicable in case an + outbound SIP server is not interested in authenticating the user, but + is required to locate a further SIP server to route the outbound SIP + requests. In this case, the outbound SIP server is mapped to SIP + server 1 as shown in Figure 5. + +6.6. Update of the User Profile + + The Diameter SIP application provides a mechanism for a Diameter + server to asynchronously download a user profile to a SIP server + whenever there is an update of such user profile. It must be noted + that the Diameter server also attaches the user profile to the + Diameter Server-Assignment-Answer (SAA) message. This is valid for + most of the daily situations; however, the administrator may decide + to update or modify the user profile for a particular user, due to, + e.g., new services made available to the user. This may involve + mechanisms outside the scope of this specification, such as human + + + + + +Garcia-Martin, et al. Standards Track [Page 17] + +RFC 4740 Diameter SIP Application November 2006 + + + intervention, in the Diameter server. In this situation, the + Diameter server is able to push the new user profile into the SIP + server allocated to the user. + + The scenario is illustrated in Figure 6. When the user profile + changes, the Diameter server sends a Diameter Push-Profile-Request + (PPR) message (step 1) to the Diameter client in the SIP server + allocated to that user (SIP server 2 in the examples). The Diameter + PPR message contains one or more SIP-User-Data AVPs, a User-Name AVP + and zero or more SIP-AOR AVPs. The Diameter client in SIP server 2 + acknowledges the Diameter PPR message by sending a Diameter + Push-Profile-Answer (PPA) message (step 2) to the Diameter server. + + +--------+ +--------+ + |Diameter| | SIP | + | server | |server 2| + +--------+ +--------+ + | | + | 1. PPR | + |------------------>| + | | + | 2. PPA | + |<------------------| + | | + + Figure 6: Diameter server pushes an update of the user profile + +6.7. SIP Soft State Termination + + SIP can create soft states in SIP nodes based on events such as SIP + registrations or SIP event subscriptions. These states are + periodically refreshed, and cease to exist if they are not refreshed. + Additionally, an administrative action can be taken to terminate a + SIP soft state, or the SIP UA can explicitly terminate a SIP soft + state. + + The Diameter base protocol offers a mechanism to create and delete + states in Diameter nodes. These states are called Diameter user + sessions. The Diameter server decides whether to use a Diameter user + session as a mechanism to map to a SIP soft state. If the Diameter + server decides to use Diameter user sessions, the termination of a + Diameter user session implies the termination of the corresponding + SIP soft state (e.g., registration, event subscription), and vice + versa. If the Diameter server does not use Diameter user sessions, + this Diameter SIP application offers specific commands to manage the + SIP soft states. Implementations compliant with this specification + MUST support both mechanisms of session management. + + + + +Garcia-Martin, et al. Standards Track [Page 18] + +RFC 4740 Diameter SIP Application November 2006 + + + We provide support for both Diameter client- and Diameter + server-initiated session termination. Depending on whether Diameter + sessions are used, termination of a SIP soft state can be achieved by + one of the following methods: + + o When the Diameter client (SIP proxy) wants to terminate the SIP + soft state and Diameter user sessions are not maintained (i.e., + the Auth-Session-State AVP has been previously set to + NO_STATE_MAINTAINED), the Diameter client MUST send a + Server-Assignment-Request (SAR) message with the + SIP-Server-Assignment-Type AVP (Section 9.4) set to any of the + deregistration values: TIMEOUT_DEREGISTRATION, + USER_DEREGISTRATION, TIMEOUT_DEREGISTRATION_STORE_SERVER_NAME, + USER_DEREGISTRATION_STORE_SERVER_NAME, + ADMINISTRATIVE_DEREGISTRATION, DEREGISTRATION_TOO_MUCH_DATA. + + o When the Diameter client (SIP proxy) wants to terminate the SIP + soft state and Diameter user sessions are maintained (i.e., the + Auth-Session-State AVP has been previously set to + STATE_MAINTAINED), the Diameter client MUST send a Session- + Termination-Request (STR) message as per regular procedures + according to RFC 3588 [RFC3588]. + + o When the Diameter server wants to terminate the SIP soft state and + Diameter user sessions are not maintained (i.e., the + Auth-Session-State AVP has been previously set to + NO_STATE_MAINTAINED), the Diameter server MUST send a + Registration-Termination-Request (RTR) message (see Section 8.9). + + o When the Diameter server wants to terminate the SIP soft state and + Diameter user sessions are maintained (i.e., the + Auth-Session-State AVP has been previously set to + STATE_MAINTAINED), the Diameter server MUST send an + Abort-Session-Request (ASR) message as per regular procedures + according to RFC 3588 [RFC3588]. + +6.8. Diameter Server Discovery + + The basic architecture assumption of this document is that all the + data related to a user is stored in a unique Diameter server. + Contrary to general opinion, this does not create a single point of + failure. It is assumed that Diameter servers are configured in a + redundant fashion in an attempt to mitigate the + single-point-of-failure problem. + + In large networks, where the number of users may be significantly + high, there might be a need to scale the number of Diameter servers. + All the data associated with a user is still stored in one Diameter + + + +Garcia-Martin, et al. Standards Track [Page 19] + +RFC 4740 Diameter SIP Application November 2006 + + + server (typically, operating in a redundant configuration), but the + data associated with different users may reside in different Diameter + servers. + + Although this configuration scales well, it introduces a new problem, + namely: given the user's SIP AOR as an input, how to determine which + of various Diameter servers is storing the data for that particular + SIP AOR. We solve this problem with inspiration from the Diameter + redirection mechanism specified in RFC 3588 [RFC3588]. We include in + the architecture a new Diameter node that, for the purpose of this + document, is known as Diameter Subscriber Locator (SL). The Diameter + SL contains a database or routing tables that map SIP AORs to + Diameter server URIs. A particular Diameter server URI points to the + actual Diameter server that stores all the data related to a + particular SIP AOR, and in consequence, to the user who owns the SIP + AOR. The Diameter SL acts in a similar way to a Diameter Redirect + Agent, dispatching Diameter requests (e.g., providing the redirection + URI in the answer). The Diameter SL can redirect all the request + pertaining to a user by setting the Redirect-Host-Usage AVP with a + value ALL_USER, as specified in RFC 3588 [RFC3588]. + + The Diameter SL can be replicated in different nodes along the + network, for the purpose of building scalability and redundancy. The + database or routing tables have to be consistent across all these + different Diameter SLs, so that equal Diameter requests will produce + equal Diameter answers, no matter which Diameter SL processes the + request. + + +--------+ +--------+ +--------+ +--------+ + | SIP | |Diameter| |Diameter| | SIP | + |server 1| |SL red. | |server 1| |server 2| + +--------+ +--------+ +--------+ +--------+ + | | | | + 1. SIP INVITE| | | | + ------------>| 2. LIR | | | + |---------->| | | + | 3. LIA | | | + |<----------| | | + | 4. LIR | | + |---------------------->| | + | 5. LIA | | + |<----------------------| | + | 6. SIP INVITE | | + |----------------------------------->| 7. SIP INVITE + | | | | -------------> + | | | | + + Figure 7: Locating a Diameter server. SL redirecting requests + + + +Garcia-Martin, et al. Standards Track [Page 20] + +RFC 4740 Diameter SIP Application November 2006 + + + Figure 7 shows an example of operation of a Diameter SL acting in + redirect mode. SIP server 1 receives an INVITE request (step 1) + addressed (in the SIP Request-URI) to a user for which the Diameter + client in SIP server 1 does not possess routing information. In + other words, the Diameter client in SIP server 1 does not know the + URI of the Diameter server 1. The Diameter client sends a Diameter + LIR message (step 2) to any of the Diameter SLs configured in the + network. The address of those SLs is assumed to be pre-provisioned + in the Diameter client. The Diameter SL, based on the contents of + the SIP-AOR AVP and its own routing tables, determines the Diameter + server that stores the information allocated to such user. Then it + builds a Diameter LIA message (step 3) that includes a Result-Code + AVP set to DIAMETER_REDIRECT_INDICATION and one Redirect-Host AVP, + whose value is set to the URI of the Diameter server that stores the + information related to such user. Then the Diameter client in SIP + server 1 builds a new LIR message (step 4) addressed to the Diameter + server received in the Redirect-Host AVP. The rest of the procedure + is completed as described in previous sections. + +7. Advertising Application Support + + Diameter implementations conforming to this specification MUST + advertise its support by including an Auth-Application-Id AVP in the + Capabilities-Exchange-Request (CER) and Capabilities-Exchange-Answer + (CEA) commands, according to the Diameter base protocol, RFC 3588 + [RFC3588]. This Auth-Application-Id AVP MUST be set to the value of + this Diameter SIP application (Section 13.1 indicates the actual + value allocated by IANA). + + + + + + + + + + + + + + + + + + + + + + + +Garcia-Martin, et al. Standards Track [Page 21] + +RFC 4740 Diameter SIP Application November 2006 + + +8. Diameter SIP Application Command Codes + + All the Diameter implementations conforming to this specification + MUST implement and support the list of Diameter commands listed in + Table 1. + + +-------------------------------------+-------+------+--------------+ + | Command Name | Abbr. | Code | Reference | + +-------------------------------------+-------+------+--------------+ + | User-Authorization-Request | UAR | 283 | Section 8.1 | + | User-Authorization-Answer | UAA | 283 | Section 8.2 | + | Server-Assignment-Request | SAR | 284 | Section 8.3 | + | Server-Assignment-Answer | SAA | 284 | Section 8.4 | + | Location-Info-Request | LIR | 285 | Section 8.5 | + | Location-Info-Answer | LIA | 285 | Section 8.6 | + | Multimedia-Auth-Request | MAR | 286 | Section 8.7 | + | Multimedia-Auth-Answer | MAA | 286 | Section 8.8 | + | Registration-Termination-Request | RTR | 287 | Section 8.9 | + | Registration-Termination-Answer | RTA | 287 | Section 8.10 | + | Push-Profile-Request | PPR | 288 | Section 8.11 | + | Push-Profile-Answer | PPA | 288 | Section 8.12 | + +-------------------------------------+-------+------+--------------+ + + Table 1: Defined command codes + + Sections defining commands contain the Message Format for that + particular command. The Message Formats included in this document + are defined as per Section 3.2 of RFC 3588 [RFC3588]. + +8.1. User-Authorization-Request (UAR) Command + + The User-Authorization-Request (UAR) is indicated by the Command-Code + set to 283 and the Command Flags' 'R' bit set. The Diameter client + in a SIP server sends this command to the Diameter server to request + authorization for the SIP User Agent to route a SIP REGISTER request. + Because the SIP REGISTER request implicitly carries a permission to + bind an AOR to a contact address, the Diameter client uses the + Diameter UAR as a first authorization request towards the Diameter + server to authorize the registration. For instance, the Diameter + server can verify that the AOR is a legitimate user of the realm. + + The Diameter client in the SIP server requests authorization for one + of the possible values defined in the SIP-User-Authorization-Type AVP + (Section 9.10). + + The user name used for authentication of the user is conveyed in a + User-Name AVP (defined in the Diameter base protocol, RFC 3588 + [RFC3588]). The location of the authentication user name in the SIP + + + +Garcia-Martin, et al. Standards Track [Page 22] + +RFC 4740 Diameter SIP Application November 2006 + + + REGISTER request varies depending on the authentication mechanism. + When the authentication mechanism is HTTP Digest as defined in RFC + 2617 [RFC2617], the authentication user name is found in the + "username" directive of the SIP Authorization header field value. + This Diameter SIP application only provides support for HTTP Digest + authentication in SIP; other authentication mechanisms are not + currently supported. + + The SIP or SIPS URI to be registered is conveyed in the SIP-AOR AVP + (Section 9.8). Typically this SIP or SIPS URI is found in the To + header field value of the SIP REGISTER request that triggered the + Diameter UAR message. + + The SIP-Visited-Network-Id AVP indicates the network that is + providing SIP services (e.g., SIP proxy functionality or any other + kind of services) to the SIP User Agent. + + The Message Format of the UAR command is as follows: + + <UAR> ::= < Diameter Header: 283, REQ, PXY > + < Session-Id > + { Auth-Application-Id } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { SIP-AOR } + [ Destination-Host ] + [ User-Name ] + [ SIP-Visited-Network-Id ] + [ SIP-User-Authorization-Type ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.2. User-Authorization-Answer (UAA) Command + + The User-Authorization-Answer (UAA) is indicated by the Command-Code + set to 283 and the Command Flags' 'R' bit cleared. The Diameter + server sends this command in response to a previously received + Diameter User-Authorization-Request (UAR) command. The Diameter + server indicates the result of the requested registration + authorization. Additionally, the Diameter server may indicate a + collection of SIP capabilities that assists the Diameter client to + select a SIP proxy to the AOR under registration. + + + + + + +Garcia-Martin, et al. Standards Track [Page 23] + +RFC 4740 Diameter SIP Application November 2006 + + + In addition to the values already defined in RFC 3588 [RFC3588], the + Result-Code AVP may contain one of the values defined in + Section 10.1. + + Whenever the Diameter server fails to process the Diameter UAR + message, it MUST stop processing and return the relevant error in the + Diameter UAA message. When there is success in the process, the + Diameter server MUST set the code to DIAMETER_SUCCESS in the Diameter + UAA message. + + If the Diameter server requires a User-Name AVP value to process the + Diameter UAR request, but the Diameter UAR message did not contain a + User-Name AVP value, the Diameter server MUST set the Result-Code AVP + value to DIAMETER_USER_NAME_REQUIRED (see Section 10.1.2) and return + it in a Diameter UAA message. Upon reception of this Diameter UAA + message with the Result-Code AVP value set to + DIAMETER_USER_NAME_REQUIRED, the SIP server typically requests + authentication by sending a SIP 401 (Unauthorized) or SIP 407 (Proxy + Authentication Required) response back to the originator. + + When the authorization procedure succeeds, the Diameter server + constructs a User-Authorization-Answer (UAA) message that MUST + include (1) the address of the SIP server already assigned to the + user name, (2) the capabilities needed by the SIP server (Diameter + client) to select another SIP server for the user, or (3) a + combination of the previous two options. + + If the Diameter server is already aware of a SIP server allocated to + the user, the Diameter UAA message contains the address of that SIP + server. + + The Diameter UAA message contains the capabilities required by a SIP + server to trigger and execute services. It is required that these + capabilities are present in the Diameter UAA message due to the + possibility that the Diameter client (in the SIP server) allocates a + different SIP server to trigger and execute services for that + particular user. + + If a User-Name AVP is present in the Diameter UAR message, then the + Diameter server MUST verify the existence of the user in the realm, + i.e., the User-Name AVP value is a valid user within that realm. If + the Diameter server does not recognize the user name received in the + User-Name AVP, the Diameter server MUST build a Diameter User- + Authorization-Answer (UAA) message and MUST set the Result-Code AVP + to DIAMETER_ERROR_USER_UNKNOWN. + + + + + + +Garcia-Martin, et al. Standards Track [Page 24] + +RFC 4740 Diameter SIP Application November 2006 + + + If a User-Name AVP is present in the Diameter UAR message, then the + Diameter server MUST authorize that User-Name AVP value is able to + register the SIP or SIPS URI included in the SIP-AOR AVP. If this + authorization fails, the Diameter server must set the Result-Code AVP + to DIAMETER_ERROR_IDENTITIES_DONT_MATCH and send it in a Diameter + User-Authorization-Answer (UAA) message. + + Note: Correlation between User-Name and SIP-AOR AVP values is + required in order to avoid registration of a SIP-AOR allocated to + another user. + + If there is a SIP-Visited-Network-Id AVP in the Diameter UAR message, + and the SIP-User-Authorization-Type AVP value received in the + Diameter UAR message is set to REGISTRATION or REGISTRATION& + CAPABILITIES, then the Diameter server SHOULD verify whether the user + is allowed to roam into the network specified in the + SIP-Visited-Network-Id AVP in the Diameter UAR message. If the user + is not allowed to roam into that network, the Diameter AAA server + MUST set the Result-Code AVP value in the Diameter UAA message to + DIAMETER_ERROR_ROAMING_NOT_ALLOWED. + + If the SIP-User-Authorization-Type AVP value received in the Diameter + UAR message is set to REGISTRATION or REGISTRATION&CAPABILITIES, then + the Diameter server SHOULD verify whether the SIP-AOR AVP value is + authorized to register in the Home Realm. Where the SIP AOR is not + authorized to register in the Home Realm, the Diameter server MUST + set the Result-Code AVP to DIAMETER_AUTHORIZATION_REJECTED and send + it in a Diameter UAA message. + + When the SIP-User-Authorization-Type AVP is not present in the + Diameter UAR message, or when it is present and its value is set to + REGISTRATION, then: + + o If the Diameter server is not aware of any previous registration + of the user name (including registrations of other SIP AORs + allocated to the same user name), then the Diameter server does + not know of any SIP server allocated to the user. In this case, + the Diameter server MUST set the Result-Code AVP value to + DIAMETER_FIRST_REGISTRATION in the Diameter UAA message, and the + Diameter server SHOULD include the required SIP server + capabilities in the SIP-Server-Capabilities AVP value in the + Diameter UAA message. The SIP-Server-Capabilities AVP assists the + Diameter client (SIP server) to select an appropriate SIP server + for the user, according to the required capabilities. + + o In some cases, the Diameter server is aware of a previously + assigned SIP server for the same or different SIP AORs allocated + to the same user name. In these cases, re-assignment of a new SIP + + + +Garcia-Martin, et al. Standards Track [Page 25] + +RFC 4740 Diameter SIP Application November 2006 + + + server may or may not be needed, depending on the capabilities of + the SIP server. The Diameter server MUST always include the + allocated SIP server URI in the SIP-Server-URI AVP of the UAA + message. If the Diameter server does not return the SIP + capabilities, the Diameter server MUST set the Result-Code AVP in + the Diameter UAA message to DIAMETER_SUBSEQUENT_REGISTRATION. + Otherwise (i.e., if the Diameter server includes a + SIP-Server-Capabilities AVP), then the Diameter server MUST set + the Result-Code AVP in the Diameter UAA message to + DIAMETER_SERVER_SELECTION. Then the Diameter client determines, + based on the received information, whether it needs to select a + new SIP server. + + When the SIP-User-Authorization-Type AVP value received in the + Diameter UAR message is set to REGISTRATION&CAPABILITIES, then + Diameter Server MUST return the list of capabilities in the + SIP-Server-Capabilities AVP value of the Diameter UAA message, it + MUST set the Result-Code to DIAMETER_SUCCESS, and it MUST NOT return + a SIP-Server-URI AVP. The SIP-Server-Capabilities AVP enables the + SIP server (Diameter client) to select another appropriate SIP server + for invoking and executing services for the user, depending on the + required capabilities. The Diameter server MAY leave the list of + capabilities empty to indicate that any SIP server can be selected. + + When the SIP-User-Authorization-Type AVP value received in the + Diameter UAR message is set to DEREGISTRATION, then: + + o If the Diameter server is aware of a SIP server assigned to the + SIP AOR under deregistration, the Diameter server MUST set the + Result-Code AVP to DIAMETER_SUCCESS and MUST set the + SIP-Server-URI AVP value to the known SIP server, and return them + in the Diameter UAA message. + + o If the Diameter server is not aware of a SIP server assigned to + the SIP AOR under deregistration, then the Diameter server MUST + set the Result-Code AVP in the Diameter UAA message to + DIAMETER_ERROR_IDENTITY_NOT_REGISTERED. + + The Message Format of the UAA command is as follows: + + <UAA> ::= < Diameter Header: 283, PXY > + < Session-Id > + { Auth-Application-Id } + { Auth-Session-State } + { Result-Code } + { Origin-Host } + { Origin-Realm } + [ SIP-Server-URI ] + + + +Garcia-Martin, et al. Standards Track [Page 26] + +RFC 4740 Diameter SIP Application November 2006 + + + [ SIP-Server-Capabilities ] + [ Authorization-Lifetime ] + [ Auth-Grace-Period ] + [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.3. Server-Assignment-Request (SAR) Command + + The Server-Assignment-Request (SAR) command is indicated by the + Command-Code set to 284 and the Command Flags' 'R' bit set. The + Diameter client in a SIP server sends this command to the Diameter + server to indicate the completion of the authentication process and + to request that the Diameter server store the URI of the SIP server + that is currently serving the user. The main functions of the + Diameter SAR command are to inform the Diameter server of the URI of + the SIP server allocated to the user, and to store or clear it from + the Diameter server. Additionally, the Diameter client can request + to download the user profile or part of it. + + During the registration procedure, a SIP server becomes assigned to + the user. The Diameter client in the assigned SIP server MUST + include its own URI in the SIP-Server-URI AVP of the + Server-Assignment-Request (SAR) Diameter message and send it to the + Diameter server. The Diameter server then becomes aware of the + allocation of the SIP server to the user name and the server's URI. + + The Diameter client in the SIP server MAY send a Diameter SAR message + because of other reasons. These reasons are identified in the + SIP-Server-Assignment-Type AVP (Section 9.4) value. For instance, a + Diameter client in a SIP server may contact the Diameter server to + request deregistration of a user, to inform the Diameter server of an + authentication failure, or just to download the user profile. For a + complete description of all the SIP-Server-Assignment-Type AVP + values, see Section 9.4. + + Typically the reception of a SIP REGISTER request in a SIP server + will trigger the Diameter client in the SIP server to send the + Diameter SAR message. However, if a SIP server is receiving other + SIP request, such as INVITE, and the SIP server does not have the + user profile, the Diameter client in the SIP server may send the + Diameter SAR message to the Diameter server in order to download the + user profile and make the Diameter server aware of the SIP server + assigned to the user. + + + + +Garcia-Martin, et al. Standards Track [Page 27] + +RFC 4740 Diameter SIP Application November 2006 + + + The user profile is an important piece of information that dictates + the behavior of the SIP server when triggering or providing services + for the user. Typically the user profile is divided into: + + o Services to be rendered to the user when the user is registered + and initiates a SIP request. + + o Services to be rendered to the user when the user is registered + and a SIP request destined to that user arrives to the SIP proxy. + + o Services to be rendered to the user when the user is not + registered and a SIP request destined to that user arrives to the + SIP proxy. + + The SIP-Server-Assignment-Type AVP indicates the reason why the + Diameter client (SIP server) contacted the Diameter server. If the + Diameter client sets the SIP-Server-Assignment-Type AVP value to + REGISTRATION, RE_REGISTRATION, UNREGISTERED_USER, NO_ASSIGNMENT, + AUTHENTICATION_FAILURE or AUTHENTICATION_TIMEOUT, the Diameter client + MUST include exactly one SIP-AOR AVP in the Diameter SAR message. + + The SAR message MAY contain zero or more SIP-Supported-User-Data-Type + AVPs. Each of them contains a type of user data understood by the + SIP server. This allows the Diameter client to provide an indication + to the Diameter server of the different format of user data + understood by the SIP server. The Diameter server uses this + information to select one or more SIP-User-Data AVPs that will be + included in the SAA message. + + The Message Format of the SAR command is as follows: + + <SAR> ::= < Diameter Header: 284, REQ, PXY > + < Session-Id > + { Auth-Application-Id } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { SIP-Server-Assignment-Type } + { SIP-User-Data-Already-Available } + [ Destination-Host ] + [ User-Name ] + [ SIP-Server-URI ] + * [ SIP-Supported-User-Data-Type ] + * [ SIP-AOR ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + + + +Garcia-Martin, et al. Standards Track [Page 28] + +RFC 4740 Diameter SIP Application November 2006 + + +8.4. Server-Assignment-Answer (SAA) Command + + The Server-Assignment-Answer (SAA) is indicated by the Command-Code + set to 284 and the Command Flags' 'R' bit cleared. The Diameter + server sends this command in response to a previously received + Diameter Server-Assignment-Request (SAR) command. The response may + include the user profile or part of it, if requested. + + In addition to the values already defined in RFC 3588 [RFC3588], the + Result-Code AVP may contain one of the values defined in + Section 10.1. + + The Result-Code AVP value in the Diameter SAA message may indicate a + success or an error in the execution of the Diameter SAR command. If + Result-Code AVP value in the Diameter SAA message does not contain an + error code, the SAA message MAY include one or more SIP-User-Data + AVPs that typically contain the profile of the user, indicating + services that the SIP server can provide to that user. + + The Diameter server MAY include one or more + SIP-Supported-User-Data-Type AVPs, each one identifying a type of + user data format supported in the Diameter server. If there is not a + common supported user data type between the Diameter client and the + Diameter server, the Diameter server SHOULD declare its list of + supported user data types by including one or more + SIP-Supported-User-Data-Type AVPs in a Diameter SAA message. This + indication is merely for debugging reasons, since there is not a + fallback mechanism that allows the Diameter client to retrieve the + profile in a supported format. + + If the Diameter server requires a User-Name AVP value to process the + Diameter SAR request, but the Diameter SAR message did not contain a + User-Name AVP value, the Diameter server MUST set the Result-Code AVP + value to DIAMETER_USER_NAME_REQUIRED (see Section 10.1.2) and return + it in a Diameter SAA message. Upon reception of this Diameter SAA + message with the Result-Code AVP value set to + DIAMETER_USER_NAME_REQUIRED, the SIP server typically requests + authentication by generating a SIP 401 (Unauthorized) or SIP 407 + (Proxy Authentication Required) response back to the originator. + + If the User-Name AVP is included in the Diameter SAR message, upon + reception of the Diameter SAR message, the Diameter server MUST + verify the existence of the user in the realm, i.e., the User-Name + AVP value is a valid user within that realm. If the Diameter server + does not recognize the user name received in the User-Name AVP, the + Diameter server MUST build a Diameter Server-Assignment-Answer (SAA) + message and MUST set the Result-Code AVP to + DIAMETER_ERROR_USER_UNKNOWN. + + + +Garcia-Martin, et al. Standards Track [Page 29] + +RFC 4740 Diameter SIP Application November 2006 + + + Then the Diameter server MUST authorize that User-Name AVP value is a + valid authentication name for the SIP or SIPS URI included in the + SIP-AOR AVP of the Diameter SAR message. If this authorization + fails, the Diameter server must set the Result-Code AVP to + DIAMETER_ERROR_IDENTITIES_DONT_MATCH and send it in a Diameter + Server-Assignment-Answer (SAA) message. + + After successful execution of the Diameter SAR command, the Diameter + server MUST clear the "authentication pending" flag and SHOULD move + the temporarily stored SIP server URI to permanent storage. + + The actions of the Diameter server upon reception of the Diameter SAR + message depend on the value of the SIP-Server-Assignment-Type: + + o If the SIP-Server-Assignment-Type AVP value in the Diameter SAR + message is set to REGISTRATION or RE_REGISTRATION, the Diameter + server SHOULD verify that there is only one SIP-AOR AVP. + Otherwise, the Diameter server MUST answer with a Diameter SAA + message with the Result-Code AVP value set to + DIAMETER_AVP_OCCURS_TOO_MANY_TIMES and MUST NOT include any + SIP-User-Data AVP. If there is only one SIP-AOR AVP and if the + SIP-User-Data-Already-Available AVP value is set to + USER_DATA_NOT_AVAILABLE, then the Diameter server SHOULD include + one or more user profile data with the SIP or SIPS URI (SIP-AOR + AVP) and all other SIP identities associated with that AVP in the + SIP-User-Data AVP value of the Diameter SAA message. On selecting + the type of user data, the Diameter server SHOULD take into + account the supported formats at the SIP server + (SIP-Supported-User-Data-Type AVP in the SAR message) and the + local policy. Additionally, the Diameter server MUST set the + Result-Code AVP value to DIAMETER_SUCCESS in the Diameter SAA + message. The Diameter server considers the SIP AOR authenticated + and registered. + + o If the SIP-Server-Assignment-Type AVP value in the Diameter SAR + message is set to UNREGISTERED_USER, then the Diameter server MUST + store the SIP server address included in the SIP-Server-URI AVP + value. The Diameter server will return the SIP server address in + Diameter Location-Info-Answer (LIA) messages. If the + SIP-User-Data-Already-Available AVP value is set to + USER_DATA_NOT_AVAILABLE, then the Diameter server SHOULD include + one or more user profile data associated with the SIP or SIPS URI + (SIP-AOR AVP) and associated identities in the SIP-User-Data AVP + value of the Diameter SAA message. On selecting the type of user + data, the Diameter server SHOULD take into account the supported + formats at the SIP server (SIP-Supported-User-Data-Type AVP in the + SAR message) and the local policy. The Diameter server MUST set + the Result-Code AVP value to DIAMETER_SUCCESS. The Diameter + + + +Garcia-Martin, et al. Standards Track [Page 30] + +RFC 4740 Diameter SIP Application November 2006 + + + server considers the SIP AOR UNREGISTERED, but with a SIP server + allocated to trigger and provide services for unregistered users. + Note that in case of UNREGISTERED_USER (SIP-Server-Assignment-Type + AVP), the Diameter server MUST verify that there is only one + SIP-AOR AVP. Otherwise, the Diameter server MUST answer the + Diameter SAR message with a Diameter SAA message, and it MUST set + the Result-Code AVP value to DIAMETER_AVP_OCCURS_TOO_MANY_TIMES + and MUST NOT include any SIP-User-Data AVP. + If the User-Name AVP was not present in the Diameter SAR message + and the SIP-AOR is not known for the Diameter server, the Diameter + server MUST NOT include a User-Name AVP in the Diameter SAA + message and MUST set the Result-Code AVP value to + DIAMETER_ERROR_USER_UNKNOWN. + + o If the SIP-Server-Assignment-Type AVP value in the Diameter SAR + message is set to TIMEOUT_DEREGISTRATION, USER_DEREGISTRATION, + DEREGISTRATION_TOO_MUCH_DATA, or ADMINISTRATIVE_DEREGISTRATION, + the Diameter server MUST clear the SIP server address associated + with all SIP AORs indicated in each of the SIP-AOR AVP values + included in the Diameter SAR message. The Diameter server + considers all of these SIP AORs as not registered. The Diameter + server MUST set the Result-Code AVP value to DIAMETER_SUCCESS in + the Diameter SAA message. + + o If the SIP-Server-Assignment-Type AVP value in the Diameter SAR + message is set to TIMEOUT_DEREGISTRATION_STORE_SERVER_NAME or + USER_DEREGISTRATION_STORE_SERVER_NAME, the Diameter server MAY + keep the SIP server address associated with the SIP AORs included + in the SIP-AOR AVP values of the Diameter SAR message, even though + the SIP AORs become unregistered. This feature allows a SIP + server to request that the Diameter server remain an assigned SIP + server for those SIP AORs (SIP-AOR AVP values) allocated to the + same user name, and avoid SIP server assignment. The Diameter + server MUST consider all these SIP AORs as not registered. If the + Diameter server honors the request of the Diameter client (SIP + server) to remain as an allocated SIP server, then the Diameter + server MUST keep the SIP server assigned to those SIP AORs + allocated to the username and MUST set the Result-Code AVP value + to DIAMETER_SUCCESS in the Diameter SAA message. Otherwise, when + the Diameter server does not honor the request of the Diameter + client (SIP server) to remain as an allocated SIP server, the + Diameter server MUST clear the SIP server name assigned to those + SIP AORs and it MUST set the Result-Code AVP value to + DIAMETER_SUCCESS_SERVER_NAME_NOT_STORED in the Diameter SAA + message. + + + + + + +Garcia-Martin, et al. Standards Track [Page 31] + +RFC 4740 Diameter SIP Application November 2006 + + + o If the SIP-Server-Assignment-Type AVP value in the Diameter SAR + message is set to NO_ASSIGNMENT, the Diameter server SHOULD first + verify that the SIP-Server-URI AVP value in the Diameter SAR + message is the same URI as the one assigned to the SIP-AOR AVP + value. If they differ, then the Diameter server MUST set the + Result-Code AVP value to DIAMETER_UNABLE_TO_COMPLY in the Diameter + SAA message. Otherwise, if the SIP-User-Data-Already-Available + AVP value is set to USER_DATA_NOT_AVAILABLE, then the Diameter + server SHOULD include the user profile data with the SIP or SIPS + URI (SIP-AOR AVP) and all other SIP identities associated with + that AVP in the SIP-User-Data AVP value of the Diameter SAA + message. On selecting the type of user data, the Diameter server + SHOULD take into account the supported formats at the SIP server + (SIP-Supported-User-Data-Type AVP in the SAR message) and the + local policy. + + o If the SIP-Server-Assignment-Type AVP value in the Diameter SAR + message is set to AUTHENTICATION_FAILURE or + AUTHENTICATION_TIMEOUT, the Diameter server MUST verify that there + is exactly one SIP-AOR AVP in the Diameter SAR message. If the + number of occurrences of the SIP-AOR AVP is not exactly one, the + Diameter server MUST set the Result-Code AVP value to + DIAMETER_AVP_OCCURS_TOO_MANY_TIMES in the Diameter SAA message, + and SHOULD not take further actions. If there is exactly one + SIP-AOR AVP in the Diameter SAR message, the Diameter server MUST + clear the address of the SIP server assigned to the SIP AOR + allocated to the user name, and the Diameter server MUST set the + Result-Code AVP value to DIAMETER_SUCCESS in the Diameter SAA + message. The Diameter server MUST consider the SIP AOR as not + registered. + + The Message Format of the SAA command is as follows: + + <SAA> ::= < Diameter Header: 284, PXY > + < Session-Id > + { Auth-Application-Id } + { Result-Code } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + * [ SIP-User-Data ] + [ SIP-Accounting-Information ] + * [ SIP-Supported-User-Data-Type ] + [ User-Name ] + [ Auth-Grace-Period ] + [ Authorization-Lifetime ] + [ Redirect-Host ] + [ Redirect-Host-Usage ] + + + +Garcia-Martin, et al. Standards Track [Page 32] + +RFC 4740 Diameter SIP Application November 2006 + + + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.5. Location-Info-Request (LIR) Command + + The Location-Info-Request (LIR) is indicated by the Command-Code set + to 285 and the Command Flags' 'R' bit set. The Diameter client in a + SIP server sends this command to the Diameter server to request + routing information, e.g., the URI of the SIP server assigned to the + SIP-AOR AVP value allocated to the users. + + The Message Format of the LIR command is as follows: + + <LIR> ::= < Diameter Header: 285, REQ, PXY > + < Session-Id > + { Auth-Application-Id } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { SIP-AOR } + [ Destination-Host ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.6. Location-Info-Answer (LIA) Command + + The Location-Info-Answer (LIA) is indicated by the Command-Code set + to 285 and the Command Flags' 'R' bit cleared. The Diameter server + sends this command in response to a previously received Diameter + Location-Info-Request (LIR) command. + + In addition to the values already defined in RFC 3588 [RFC3588], the + Result-Code AVP may contain one of the values defined in + Section 10.1. When the Diameter server finds an error in processing + the Diameter LIR message, the Diameter server MUST stop the process + of the message and answer with a Diameter LIA message that includes + the appropriate error code in the Result-Code AVP value. When there + is no error, the Diameter server MUST set the Result-Code AVP value + to DIAMETER_SUCCESS in the Diameter LIA message. + + One of the errors that the Diameter server may find is that the + SIP-AOR AVP value is not a valid user in the realm. In such cases, + the Diameter server MUST set the Result-Code AVP value to + DIAMETER_ERROR_USER_UNKNOWN and return it in a Diameter LIA message. + + + +Garcia-Martin, et al. Standards Track [Page 33] + +RFC 4740 Diameter SIP Application November 2006 + + + If the Diameter server cannot process the Diameter LIR command, e.g., + due to a database error, the Diameter server MUST set the Result-Code + AVP value to DIAMETER_UNABLE_TO_COMPLY and return it in a Diameter + LIA message. The Diameter server MUST NOT include any SIP-Server-URI + or SIP-Server-Capabilities AVP in the Diameter LIA message. + + The Diameter server may or may not be aware of a SIP server assigned + to the SIP-AOR AVP value included in the Diameter LIR message. If + the Diameter server is aware of a SIP server allocated to that + particular user, the Diameter server MUST include the URI of such SIP + server in the SIP-Server-URI AVP and return it in a Diameter LIA + message. This is typically the situation when the user is either + registered, or unregistered but a SIP server is still assigned to the + user. + + When the Diameter server is not aware of a SIP server allocated to + the user (typically the case when the user unregistered), the + Result-Code AVP value in the Diameter LIA message depends on whether + the Diameter server is aware that the user has services defined for + unregistered users: + + o Those users who have services defined for unregistered users may + require the allocation of a SIP server to trigger and perhaps + execute those services. Therefore, when the Diameter server is + not aware of an assigned SIP server, but the user has services + defined for unregistered users, the Diameter server MUST set the + Result-Code AVP value to DIAMETER_UNREGISTERED_SERVICE and return + it in a Diameter LIA message. The Diameter server MAY also + include a SIP-Server-Capabilities AVP to facilitate the SIP server + (Diameter client) with the selection of an appropriate SIP server + with the required capabilities. Absence of the SIP-Server- + Capabilities AVP indicates to the SIP server (Diameter client) + that any SIP server is suitable to be allocated for the user. + + o Those users who do not have service defined for unregistered users + do not require further processing. The Diameter server MUST set + the Result-Code AVP value to + DIAMETER_ERROR_IDENTITY_NOT_REGISTERED and return it to the + Diameter client in a Diameter LIA message. The SIP server + (Diameter client) may return the appropriate SIP response (e.g., + 480 (Temporarily unavailable)) to the original SIP request. + + The Message Format of the LIA command is as follows: + + <LIA> ::= < Diameter Header: 285, PXY > + < Session-Id > + { Auth-Application-Id } + { Result-Code } + + + +Garcia-Martin, et al. Standards Track [Page 34] + +RFC 4740 Diameter SIP Application November 2006 + + + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + [ SIP-Server-URI ] + [ SIP-Server-Capabilities ] + [ Auth-Grace-Period ] + [ Authorization-Lifetime ] + [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.7. Multimedia-Auth-Request (MAR) Command + + The Multimedia-Auth-Request (MAR) command is indicated by the + Command-Code set to 286 and the Command Flags' 'R' bit set. The + Diameter client in a SIP server sends this command to the Diameter + server to request that the Diameter server authenticate and authorize + a user attempt to use some SIP service (in this context, SIP service + can be something as simple as a SIP subscription or using the proxy + services for a SIP request). + + The MAR command may also register the SIP server's own URI to the + Diameter server, so that future LIR/LIA messages can return this URI. + If the SIP server is acting as a SIP registrar (see examples in + Sections 6.2 and 6.3), its Diameter client MUST include a SIP- + Server-URI AVP in the MAR command. In any other cases (see example + in Section 6.4), its Diameter client MUST NOT include a SIP-Server- + URI AVP in the MAR command. + + The SIP-Method AVP MUST include the SIP method name of the SIP + request that triggered this Diameter MAR message. The Diameter + server can use this AVP to authorize some SIP requests depending on + the method. + + The Diameter MAR message MUST include a SIP-AOR AVP. The SIP-AOR AVP + indicates the target of the SIP request. The value of the AVP is + extracted from different places in SIP request, depending on the + semantics of the SIP request. For SIP REGISTER messages the SIP-AOR + AVP value indicates the intended public user identity under + registration, and it is the SIP or SIPS URI populated in the To + header field value (addr-spec as per RFC 3261 [RFC3261]) of the SIP + REGISTER request. For other types of SIP requests, such as INVITE, + SUBSCRIBE, MESSAGE, etc., the SIP-AOR AVP value indicates the + intended destination of the request. This is typically populated in + the Request-URI of the SIP request. Extracting the SIP-AOR AVP value + + + +Garcia-Martin, et al. Standards Track [Page 35] + +RFC 4740 Diameter SIP Application November 2006 + + + from the proper SIP header field is the Diameter client's + responsibility. Extensions to SIP (new SIP methods or new semantics) + may require the SIP-AOR to be extracted from other parts of the + request. + + If the SIP request includes some sort of authentication information, + the Diameter client MUST include the user name, extracted from the + authentication information of the SIP request, in the User-Name AVP + value. + + The Message Format of the MAR command is as follows: + + <MAR> ::= < Diameter Header: 286, REQ, PXY > + < Session-Id > + { Auth-Application-Id } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { SIP-AOR } + { SIP-Method } + [ Destination-Host ] + [ User-Name ] + [ SIP-Server-URI ] + [ SIP-Number-Auth-Items ] + [ SIP-Auth-Data-Item ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.8. Multimedia-Auth-Answer (MAA) Command + + The Multimedia-Auth-Answer (MAA) is indicated by the Command-Code set + to 286 and the Command Flags' 'R' bit cleared. The Diameter server + sends this command in response to a previously received Diameter + Multimedia-Auth-Request (MAR) command. + + In addition to the values already defined in RFC 3588 [RFC3588], the + Result-Code AVP may contain one of the values defined in + Section 10.1. + + If the Diameter server requires a User-Name AVP value to process the + Diameter MAR request, but the Diameter MAR message did not contain a + User-Name AVP value, the Diameter server MUST set the Result-Code AVP + value to DIAMETER_USER_NAME_REQUIRED (see Section 10.1.2) and return + it in a Diameter MAA message. The Diameter server MAY include a + SIP-Number-Auth-Items AVP and one or more SIP-Auth-Data-Item AVPs + with authentication information (e.g., a challenge). Upon reception + + + +Garcia-Martin, et al. Standards Track [Page 36] + +RFC 4740 Diameter SIP Application November 2006 + + + of this Diameter MAA message with the Result-Code AVP value set to + DIAMETER_USER_NAME_REQUIRED, the SIP server typically requests + authentication by generating a SIP 401 (Unauthorized) or SIP 407 + (Proxy Authentication Required) response back to the originator. + + If the User-Name AVP is present in the Diameter MAR message, the + Diameter server MUST verify the existence of the user in the realm, + i.e., the User-Name AVP value is a valid user within that realm. If + the Diameter server does not recognize the user name received in the + User-Name AVP, the Diameter server MUST build a Diameter + Multimedia-Auth-Answer (MAA) message and MUST set the Result-Code AVP + to DIAMETER_ERROR_USER_UNKNOWN. + + If the SIP-Methods AVP value of the Diameter MAR message is set to + REGISTER and a User-Name AVP is present, then the Diameter server + MUST authorize that User-Name AVP value is able to use the URI + included in the SIP-AOR AVP. If this authorization fails, the + Diameter server must set the Result-Code AVP to + DIAMETER_ERROR_IDENTITIES_DONT_MATCH and send it in a Diameter + Multimedia-Auth-Answer (MAA) message. + + Note: Correlation between User-Name and SIP-AOR AVP values is only + required for SIP REGISTER request, to prevent a user from + registering a SIP-AOR allocated to another user. In other types + of SIP requests (e.g., INVITE), the SIP-AOR indicates the intended + destination of the request, rather than the originator of it. + + The Diameter server MUST verify whether the authentication scheme + (SIP-Authentication-Scheme AVP value) indicated in the grouped + SIP-Auth-Data-Item AVP is supported or not. If that authentication + scheme is not supported, then the Diameter server MUST set the + Result-Code AVP to DIAMETER_ERROR_AUTH_SCHEME_NOT_SUPPORTED and send + it in a Diameter Multimedia-Auth-Answer (MAA) message. + + If the SIP-Number-Auth-Items AVP is present in the Diameter MAR + message, it indicates the number of authentication data items that + the Diameter client is requesting. It is RECOMMENDED that the + Diameter server, when building the Diameter MAA message, includes a + number of SIP-Auth-Data-Item AVPs that are a subset of the + authentication data items requested by the Diameter client in the + SIP-Number-Auth-Items AVP value of the Diameter MAR message. + + If the SIP-Server-URI AVP is present in the Diameter MAR message, + then the Diameter server MUST compare the stored SIP server (assigned + to the user) with the SIP-Server-URI AVP value (received in the + Diameter MAR message). If they don't match, the Diameter server MUST + temporarily save the newly received SIP server assigned to the user, + and MUST set an "authentication pending" flag for the user. If they + + + +Garcia-Martin, et al. Standards Track [Page 37] + +RFC 4740 Diameter SIP Application November 2006 + + + match, the Diameter server shall clear the "authentication pending" + flag for the user. + + In any other situation, if there is a success in processing the + Diameter MAR command and the Diameter server stored the + SIP-Server-URI, the Diameter server MUST set the Result-Code AVP + value to DIAMETER_SUCCESS and return it in a Diameter MAA message. + + If there is a success in processing the Diameter MAR command, but the + Diameter server does not store the SIP-Server-URI because the AVP was + not present in the Diameter MAR command, then the Diameter server + MUST set the Result-Code AVP value to either: + + 1. DIAMETER_SUCCESS_AUTH_SENT_SERVER_NOT_STORED, if the Diameter + server is sending authentication credentials to create a + challenge. + + 2. DIAMETER_SUCCESS_SERVER_NAME_NOT_STORED, if the Diameter server + successfully authenticated the user and authorized the SIP server + to proceed with the SIP request. + + Otherwise, the Diameter server MUST set the Result-Code AVP value to + DIAMETER_UNABLE_TO_COMPLY, and it MUST NOT include any + SIP-Auth-Data-Item AVP. + + The Message Format of the MAA command is as follows: + + <MAA> ::= < Diameter Header: 286, PXY > + < Session-Id > + { Auth-Application-Id } + { Result-Code } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + [ User-Name ] + [ SIP-AOR ] + [ SIP-Number-Auth-Items ] + * [ SIP-Auth-Data-Item ] + [ Authorization-Lifetime ] + [ Auth-Grace-Period ] + [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + + + + + +Garcia-Martin, et al. Standards Track [Page 38] + +RFC 4740 Diameter SIP Application November 2006 + + +8.9. Registration-Termination-Request (RTR) Command + + The Registration-Termination-Request (RTR) command is indicated by + the Command-Code set to 287 and the Command Flags' 'R' bit set. The + Diameter server sends this command to the Diameter client in a SIP + server to indicate to the SIP server that one or more SIP AORs have + to be deregistered. The command allows an operator to + administratively cancel the registration of a user from a centralized + Diameter server. + + The Diameter server has the capability to initiate the deregistration + of a user and inform the SIP server by means of the Diameter RTR + command. The Diameter server can decide whether only one SIP AOR is + going to be deregistered, a list of SIP AORs, or all the SIP AORs + allocated to the user. + + The absence of a SIP-AOR AVP in the Diameter RTR message indicates + that all the SIP AORs allocated to the user identified by the + User-Name AVP are being deregistered. + + The Diameter server MUST include a SIP-Deregistration-Reason AVP + value to indicate the reason for the deregistration. + + The Message Format of the RTR command is as follows: + + <RTR> ::= < Diameter Header: 287, REQ, PXY > + < Session-Id > + { Auth-Application-Id } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + { Destination-Host } + { SIP-Deregistration-Reason } + [ Destination-Realm ] + [ User-Name ] + * [ SIP-AOR ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.10. Registration-Termination-Answer (RTA) Command + + The Registration-Termination-Answer (RTA) is indicated by the + Command-Code set to 287 and the Command Flags' 'R' bit cleared. The + Diameter client sends this command in response to a previously + received Diameter Registration-Termination-Request (RTR) command. + + + + + +Garcia-Martin, et al. Standards Track [Page 39] + +RFC 4740 Diameter SIP Application November 2006 + + + In addition to the values already defined in RFC 3588 [RFC3588], the + Result-Code AVP may contain one of the values defined in + Section 10.1. + + If the SIP server (Diameter client) requires a User-Name AVP value to + process the Diameter RTR request, but the Diameter RTR message did + not contain a User-Name AVP value, the Diameter client MUST set the + Result-Code AVP value to DIAMETER_USER_NAME_REQUIRED (see Section + 10.1.2) and return it in a Diameter RTA message. + + The SIP server (Diameter client) applies the administrative + deregistration to each of the URIs included in each of the SIP-AOR + AVP values, or, if there is no SIP-AOR AVP present in the Diameter + RTR request, to all the URIs allocated to the User-Name AVP value. + + The value of the SIP-Deregistration-Reason AVP in the Diameter RTR + command has an effect on the actions performed at the SIP server + (Diameter client): + + o If the value is set to PERMANENT_TERMINATION, then the user has + terminated his/her registration to the realm. If informing the + interested parties (e.g., subscribers to the "reg" event + [RFC3680]) about the administrative deregistration is supported + through SIP procedures, the SIP server (Diameter client) will do + so. The Diameter Client in the SIP Server SHOULD NOT request a + new user registration. The SIP server clears the registration + state of the deregistered AORs. + + o If the value is set to NEW_SIP_SERVER_ASSIGNED, the Diameter + server informs the SIP server (Diameter client) that a new SIP + server has been allocated to the user, due to some reason. The + SIP server, if supported through SIP procedures, will inform the + interested parties (e.g., subscribers to the "reg" event + [RFC3680]) about the administrative deregistration at this SIP + server. The Diameter client in the SIP server SHOULD NOT request + a new user registration. The SIP server clears the registration + state of the deregistered SIP AORs. + + o If the value is set to SIP_SERVER_CHANGE, the Diameter server + informs the SIP server (Diameter client) that a new SIP server has + to be allocated to the user, e.g., due to user's capabilities + requiring a new SIP server, or not enough resources in the current + SIP server. If informing the interested parties about the + administrative deregistration is supported through SIP procedures + (e.g., subscriptions to the "reg" event [RFC3680]), the SIP server + will do so. The Diameter client in the SIP Server SHOULD NOT + request a new user registration. The SIP server clears the + registration state of the deregistered SIP AORs. + + + +Garcia-Martin, et al. Standards Track [Page 40] + +RFC 4740 Diameter SIP Application November 2006 + + + o If the value is set to REMOVE_SIP_SERVER, the Diameter server + informs the SIP server (Diameter client) that the SIP server will + no longer be bound in the Diameter server with that user. The SIP + server can delete all data related to the user. + + The Message Format of the RTA command is as follows: + + <RTA> ::= < Diameter Header: 287, PXY > + < Session-Id > + { Auth-Application-Id } + { Result-Code } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + [ Authorization-Lifetime ] + [ Auth-Grace-Period ] + [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.11. Push-Profile-Request (PPR) Command + + The Push-Profile-Request (PPR) command is indicated by the + Command-Code set to 288 and the Command Flags' 'R' bit set. The + Diameter server sends this command to the Diameter client in a SIP + server to update either the user profile of an already registered + user in that SIP server or the SIP accounting information. This + allows an operator to modify the data of a user profile or the + accounting information and push it to the SIP server where the user + is registered. + + Each user has a user profile associated with him/her and other + accounting information. The profile or the accounting information + may change with time, e.g., due to addition of new services to the + user. When the user profile or the accounting information changes, + the Diameter server sends a Diameter Push-Profile-Request (PPR) + command to the Diameter client in a SIP server, in order to start + applying those new services. + + A PPR command MAY contain a SIP-Accounting-Information AVP that + updates the addresses of the accounting servers. Changes in the + addresses of the accounting servers take effect immediately. The + Diameter client SHOULD close any existing accounting session with the + existing server and start providing accounting information to the + newly acquired accounting server. + + + +Garcia-Martin, et al. Standards Track [Page 41] + +RFC 4740 Diameter SIP Application November 2006 + + + A PPR command MAY contain zero or more SIP-User-Data AVP values + containing the new user profile. On selecting the type of user data, + the Diameter server SHOULD take into account the supported formats at + the SIP server (SIP-Supported-User-Data-Type AVP sent in a previous + SAR message) and the local policy. + + The User-Name AVP indicates the user to whom the profile is + applicable. + + The Message Format of the PPR command is as follows: + + <PPR> ::= < Diameter Header: 288, REQ, PXY > + < Session-Id > + { Auth-Application-Id } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + { Destination-Realm } + { User-Name } + * [ SIP-User-Data ] + [ SIP-Accounting-Information ] + [ Destination-Host ] + [ Authorization-Lifetime ] + [ Auth-Grace-Period ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +8.12. Push-Profile-Answer (PPA) Command + + The Push-Profile-Answer (PPA) is indicated by the Command-Code set to + 288 and the Command Flags' 'R' bit cleared. The Diameter client + sends this command in response to a previously received Diameter + Push-Profile-Request (PPR) command. + + In addition to the values already defined in RFC 3588 [RFC3588], the + Result-Code AVP may contain one of the values defined in + Section 10.1. + + If there is no error when processing the received Diameter PPR + message, the SIP server (Diameter client) MUST download the received + user profile from the SIP-User-Data AVP values in the Diameter PPR + message and store it associated with the user specified in the + User-Name AVP value. + + If the SIP server does not recognize or does not support some of the + data transferred in the SIP-User-Data AVP values, the Diameter client + in the SIP server MUST return a Diameter PPA message that includes a + + + +Garcia-Martin, et al. Standards Track [Page 42] + +RFC 4740 Diameter SIP Application November 2006 + + + Result-Code AVP set to the value + DIAMETER_ERROR_NOT_SUPPORTED_USER_DATA. + + If the SIP server (Diameter client) receives a Diameter PPR message + with a User-Name AVP that is unknown, the Diameter client MUST set + the Result-Code AVP value to DIAMETER_ERROR_USER_UNKNOWN and MUST + return it to the Diameter server in a Diameter PPA message. + + If the SIP server (Diameter client) receives in the + SIP-User-Data-Content AVP value (of the grouped SIP-User-Data AVP) + more data than it can accept, it MUST set the Result-Code AVP value + to DIAMETER_ERROR_TOO_MUCH_DATA and MUST return it to the Diameter + server in a Diameter PPA message. The SIP server MUST NOT override + the existing user profile with the one received in the PPR message. + + If the Diameter server receives the Result-Code AVP value set to + DIAMETER_ERROR_TOO_MUCH_DATA in a Diameter PPA message, it SHOULD + force a new re-registration of the user by sending to the Diameter + client a Diameter Registration-Termination-Request (RTR) with the + SIP-Deregistration-Reason AVP value set to SIP_SERVER_CHANGE. This + will force a re-registration of the user and will trigger a selection + of a new SIP server. + + If the Diameter client is not able to honor the command, for any + other reason, it MUST set the Result-Code AVP value to + DIAMETER_UNABLE_TO_COMPLY and it MUST return it in a Diameter PPA + message. + + The Message Format of the PPA command is as follows: + + <PPA> ::= < Diameter Header: 288, PXY > + < Session-Id > + { Auth-Application-Id } + { Result-Code } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + + + + + + + + +Garcia-Martin, et al. Standards Track [Page 43] + +RFC 4740 Diameter SIP Application November 2006 + + +9. Diameter SIP Application AVPs + + This section defines new AVPs used in this Diameter SIP application. + Applications compliant with this specification MUST implement these + AVPs. + + Table 2 lists the new AVPs defined in this Diameter SIP application. + The following abbreviations are used in the Data-Type column: + + o DURI: DiameterURI + o E: Enumerated + o G: Grouped + o OS: OctetString + o UTF8S: UTF8String + o U32: Unsigned32 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Garcia-Martin, et al. Standards Track [Page 44] + +RFC 4740 Diameter SIP Application November 2006 + + + +-----------------------------------+------+----------------+-------+ + | Attribute Name | AVP | Reference | Data- | + | | Code | | Type | + +-----------------------------------+------+----------------+-------+ + | SIP-Accounting-Information | 368 | Section 9.1 | G | + | SIP-Accounting-Server-URI | 369 | Section 9.1.1 | DURI | + | SIP-Credit-Control-Server-URI | 370 | Section 9.1.2 | DURI | + | SIP-Server-URI | 371 | Section 9.2 | UTF8S | + | SIP-Server-Capabilities | 372 | Section 9.3 | G | + | SIP-Mandatory-Capability | 373 | Section 9.3.1 | U32 | + | SIP-Optional-Capability | 374 | Section 9.3.2 | U32 | + | SIP-Server-Assignment-Type | 375 | Section 9.4 | E | + | SIP-Auth-Data-Item | 376 | Section 9.5 | G | + | SIP-Authentication-Scheme | 377 | Section 9.5.1 | E | + | SIP-Item-Number | 378 | Section 9.5.2 | U32 | + | SIP-Authenticate | 379 | Section 9.5.3 | G | + | SIP-Authorization | 380 | Section 9.5.4 | G | + | SIP-Authentication-Info | 381 | Section 9.5.5 | G | + | SIP-Number-Auth-Items | 382 | Section 9.6 | U32 | + | SIP-Deregistration-Reason | 383 | Section 9.7 | G | + | SIP-Reason-Code | 384 | Section 9.7.1 | E | + | SIP-Reason-Info | 385 | Section 9.7.2 | UTF8S | + | SIP-Visited-Network-Id | 386 | Section 9.9 | UTF8S | + | SIP-User-Authorization-Type | 387 | Section 9.10 | E | + | SIP-Supported-User-Data-Type | 388 | Section 9.11 | UTF8S | + | SIP-User-Data | 389 | Section 9.12 | G | + | SIP-User-Data-Type | 390 | Section 9.12.1 | UTF8S | + | SIP-User-Data-Contents | 391 | Section 9.12.2 | OS | + | SIP-User-Data-Already-Available | 392 | Section 9.13 | E | + | SIP-Method | 393 | Section 9.14 | UTF8S | + +-----------------------------------+------+----------------+-------+ + + Table 2: Defined AVPs + + Table 3 expands the table of AVPs included in Section 4.5 of RFC 3588 + [RFC3588]. The table indicates the Diameter AVPs defined in this + Diameter SIP Application, their possible flag values, and whether the + AVP may be encrypted. The acronyms 'M', 'P', and 'V' refer to AVP + flags whose semantics are described in RFC 3588 [RFC3588]. The value + of the 'Encr' column is also described in RFC 3588 [RFC3588]. + + + + + + + + + + + +Garcia-Martin, et al. Standards Track [Page 45] + +RFC 4740 Diameter SIP Application November 2006 + + + +----------------------------------+------+-----+-----+------+------+ + | Attribute Name | MUST | MAY | SHD | MUST | Encr | + | | | | NOT | NOT | | + +----------------------------------+------+-----+-----+------+------+ + | SIP-Accounting-Information | M | P | | V | N | + | SIP-Accounting-Server-URI | M | P | | V | N | + | SIP-Credit-Control-Server-URI | M | P | | V | N | + | SIP-Server-URI | M | P | | V | N | + | SIP-Server-Capabilities | M | P | | V | N | + | SIP-Mandatory-Capability | M | P | | V | N | + | SIP-Optional-Capability | M | P | | V | N | + | SIP-Server-Assignment-Type | M | P | | V | N | + | SIP-Auth-Data-Item | M | P | | V | N | + | SIP-Authentication-Scheme | M | P | | V | N | + | SIP-Item-Number | M | P | | V | N | + | SIP-Authenticate | M | P | | V | N | + | SIP-Authorization | M | P | | V | N | + | SIP-Authentication-Info | M | P | | V | N | + | SIP-Number-Auth-Items | M | P | | V | N | + | SIP-Deregistration-Reason | M | P | | V | N | + | SIP-Reason-Code | M | P | | V | N | + | SIP-Reason-Info | M | P | | V | N | + | SIP-Visited-Network-Id | M | P | | V | N | + | SIP-User-Authorization-Type | M | P | | V | N | + | SIP-Supported-User-Data-Type | M | P | | V | N | + | SIP-User-Data | M | P | | V | N | + | SIP-User-Data-Type | M | P | | V | N | + | SIP-User-Data-Contents | M | P | | V | N | + | SIP-User-Data-Already-Available | M | P | | V | N | + | SIP-Method | M | P | | V | N | + +----------------------------------+------+-----+-----+------+------+ + + Table 3: Summary of the new AVPs flags + +9.1. SIP-Accounting-Information AVP + + The SIP-Accounting-Information (AVP Code 368) is of type Grouped, and + contains the Diameter addresses of those nodes that are able to + collect accounting information. + + The SIP-Accounting-Information AVP is defined as follows (per the + grouped-avp-def of RFC 3588 [RFC3588]): + + SIP-Accounting-Information ::= < AVP Header: 368 > + * [ SIP-Accounting-Server-URI ] + * [ SIP-Credit-Control-Server-URI ] + * [ AVP] + + + + +Garcia-Martin, et al. Standards Track [Page 46] + +RFC 4740 Diameter SIP Application November 2006 + + +9.1.1. SIP-Accounting-Server-URI AVP + + The SIP-Accounting-Server-URI AVP (AVP Code 369) is of type + DiameterURI. This AVP contains the address of a Diameter server that + is able to receive SIP-session-related accounting information. + +9.1.2. SIP-Credit-Control-Server-URI AVP + + The SIP-Credit-Control-Server-URI AVP (AVP Code 370) is of type + DiameterURI. This AVP contains the address of a Diameter server that + is able to authorize real-time credit control usage. The Diameter + Credit-Control Application [RFC4006] may be used for this purpose. + +9.2. SIP-Server-URI AVP + + The SIP-Server-URI AVP (AVP Code 371) is of type UTF8String. This + AVP contains a SIP or SIPS URI (as defined in RFC 3261 [RFC3261]) + that identifies a SIP server. + +9.3. SIP-Server-Capabilities AVP + + The SIP-Server-Capabilities AVP (AVP Code 372) is of type Grouped. + The Diameter indicates in this AVP the requirements for a particular + SIP capability, so that the Diameter client (SIP server) is able to + select another appropriate SIP server to serve the user. + + The SIP-Server-Capabilities AVP allows a Diameter client (SIP server) + to select another SIP server for triggering or executing services to + the user. A user may have enabled some services that require the + implementation of certain capabilities in the SIP server that + triggers or executes those services. For example, the SIP server + that triggers or executes services to this user may need to implement + SIP servlets [JSR-000116], Call Processing Language (CPL) [RFC3880], + or any other kind of capability. Or perhaps that user belongs to a + premium users group that has a certain stringent quality-of-service + agreement that requires a fast SIP server. The capabilities required + or recommended to a given user are conveyed in the + SIP-Server-Capabilities AVP. When it receives them, the Diameter + client (SIP server) that does the SIP server selection needs to have + the means to find out available SIP servers that meet the required or + optional capabilities. Such means are outside the scope of this + specification. + + Note that the SIP-Server-Capabilities AVP assists the Diameter client + (SIP server) to produce a subset of all the available SIP servers to + be allocated to the user in the Home Realm; this is the subset that + conforms the requirements of capabilities on a per-user basis. + Typically this subset will be formed of more than a single SIP + + + +Garcia-Martin, et al. Standards Track [Page 47] + +RFC 4740 Diameter SIP Application November 2006 + + + server, so once the subset of those SIP servers is identified, it is + possible that several instances of these SIP servers exist, in which + case the Diameter client (SIP server) should choose one particular + SIP server to execute and trigger services to this user. It is + expected that at this point the SIP server (Diameter client) will + follow the procedures of RFC 3263 [RFC3263] to allocate one SIP + server to the user. + + The SIP-Server-Capabilities AVP is defined as follows (per the + grouped-avp-def of RFC 3588 [RFC3588]): + + SIP-Server-Capabilities ::= < AVP Header: 372 > + * [ SIP-Mandatory-Capability ] + * [ SIP-Optional-Capability ] + * [ SIP-Server-URI ] + * [ AVP ] + +9.3.1. SIP-Mandatory-Capability AVP + + The SIP-Mandatory-Capability AVP (AVP Code 373) is of type + Unsigned32. The value represents a certain capability (or set of + capabilities) that have to be fulfilled by the SIP server allocated + to the user. + + The semantics of the different values are not standardized, as it is + a matter of the administrative network to allocate its own semantics + within its own network. Each value has to represent a single + capability within the administrative network. + +9.3.2. SIP-Optional-Capability AVP + + The SIP-Optional-Capability AVP (AVP Code 374) is of type Unsigned32. + The value represents a certain capability (or set of capabilities) + that, optionally, may be fulfilled by the SIP server allocated to the + user. + + The semantics of the different values are not standardized, as it is + a matter of the administrative network to allocate its own semantics + within its own network. Each value has to represent a single + capability within the administrative network. + +9.4. SIP-Server-Assignment-Type AVP + + The SIP-Server-Assignment-Type AVP (AVP Code 375) is of type + Enumerated and indicates the type of server update being performed in + a Diameter Server-Assignment-Request (SAR) operation. The following + values are defined: + + + + +Garcia-Martin, et al. Standards Track [Page 48] + +RFC 4740 Diameter SIP Application November 2006 + + + o NO_ASSIGNMENT (0) + The Diameter client uses this value to request the user profile of + a SIP AOR, without affecting the registration state of that + identity. + + o REGISTRATION (1) + First SIP registration of a SIP AOR. + + o RE_REGISTRATION (2) + Subsequent SIP registration of a SIP AOR. + + o UNREGISTERED_USER (3) + The SIP server has received a SIP request (e.g., SIP INVITE) + addressed for a SIP AOR that is not registered. + + o TIMEOUT_DEREGISTRATION (4) + The SIP registration timer of an identity has expired. + + o USER_DEREGISTRATION (5) + The SIP server has received a request to deregister a SIP AOR. + + o TIMEOUT_DEREGISTRATION_STORE_SERVER_NAME (6) + The SIP registration timer of an identity has expired. The SIP + server keeps the user data stored and requests the Diameter server + to store the SIP server address. + + o USER_DEREGISTRATION_STORE_SERVER_NAME (7) + The SIP server has received a user-initiated deregistration + request. The SIP server keeps the user data stored and requests + the Diameter server to store the SIP server address. + + o ADMINISTRATIVE_DEREGISTRATION (8) + The SIP server, due to administrative reasons, has deregistered a + SIP AOR. + + o AUTHENTICATION_FAILURE (9) + The authentication of a user has failed. + + o AUTHENTICATION_TIMEOUT (10) + The authentication timer has expired. + + o DEREGISTRATION_TOO_MUCH_DATA (11) + The SIP server has requested user profile information from the + Diameter server and has received a volume of data higher than it + can accept. + + + + + + +Garcia-Martin, et al. Standards Track [Page 49] + +RFC 4740 Diameter SIP Application November 2006 + + +9.5. SIP-Auth-Data-Item AVP + + The SIP-Auth-Data-Item (AVP Code 376) is of type Grouped and contains + the authentication and/or authorization information pertaining to a + user. + + When the Diameter server uses the grouped SIP-Auth-Data-Item AVP to + include a SIP-Authenticate AVP, the Diameter server MUST send a + maximum of one authentication data item (e.g., in case the SIP + request contained several credentials). Section 11 contains a + detailed discussion and normative text of the case when a SIP request + contains several credentials. + + The SIP-Auth-Data-Item AVP is defined as follows (per the + grouped-avp-def of RFC 3588 [RFC3588]): + + SIP-Auth-Data-Item ::= < AVP Header: 376 > + { SIP-Authentication-Scheme } + [ SIP-Item-Number ] + [ SIP-Authenticate ] + [ SIP-Authorization ] + [ SIP-Authentication-Info ] + * [ AVP ] + +9.5.1. SIP-Authentication-Scheme AVP + + The SIP-Authentication-Scheme AVP (AVP Code 377) is of type + Enumerated and indicates the authentication scheme used in the + authentication of SIP services. RFC 2617 identifies this value as an + "auth-scheme" (see Section 1.2 of RFC 2617 [RFC2617]). The only + currently defined value is: + + o DIGEST (0) to indicate HTTP Digest authentication as specified in + RFC 2617 [RFC2617] Section 3.2.1. Derivative work is also + considered Digest authentication scheme, as long as the + "auth-scheme" is identified as Digest in the SIP headers carrying + the HTTP authentication. This includes, e.g., the HTTP Digest + authentication using AKA [RFC3310]. + + Each HTTP Digest directive (parameter) is transported in a + corresponding AVP, whose name follows the pattern Digest-*. The + Digest-* AVPs are RADIUS attributes imported from the RADIUS + Extension for Digest Authentication [RFC4590] namespace, allowing a + smooth transition between RADIUS and Diameter applications supporting + SIP. The Diameter SIP application goes a step further by grouping + the Digest-* AVPs into the SIP-Authenticate, SIP-Authorization, and + + + + + +Garcia-Martin, et al. Standards Track [Page 50] + +RFC 4740 Diameter SIP Application November 2006 + + + SIP-Authentication-Info grouped AVPs that correspond to the SIP WWW- + Authenticate/Proxy-Authentication, Authorization/Proxy-Authorization, + and Authentication-Info headers fields, respectively. + + Note: Due to the fact that HTTP Digest authentication [RFC2617] is + the only mandatory authentication mechanism in SIP, this memo only + provides support for HTTP Digest authentication and derivative + work such as HTTP Digest authentication using AKA [RFC3310]. + Extensions to this memo can register new values and new AVPs to + provide support for other authentication schemes or extensions to + HTTP Digest authentication. + + Note: Although RFC 2617 [RFC2617] defines the Basic and Digest + schemes for authenticating HTTP requests, RFC 3261 [RFC3261] only + imports HTTP Digest as a mechanism to provide authentication in + SIP. + + Due to syntactic requirements, HTTP Digest authentication has to + escape quote characters in contents of HTTP Digest directives. When + translating directives into Digest-* AVPs, the Diameter client or + server removes the surrounding quotes where present, as required by + the syntax of the Digest-* attributes defined in the "RADIUS + Extension for Digest Authentication" [RFC4590]. + +9.5.2. SIP-Item-Number AVP + + The SIP-Item-Number (AVP Code 378) is of type Unsigned32 and is + included in a SIP-Auth-Data-Item grouped AVP in circumstances where + there are multiple occurrences of SIP-Auth-Data-Item AVPs and the + order of processing is relevant. The AVP indicates the order in + which the Grouped SIP-Auth-Data-Item should be processed. Lower + values of the SIP-Item-Number AVP indicate that the whole + SIP-Auth-Data-Item SHOULD be processed before other + SIP-Auth-Data-Item AVPs that contain higher values in the + SIP-Item-Number AVP. + +9.5.3. SIP-Authenticate AVP + + The SIP-Authenticate AVP (AVP Code 379) is of type Grouped and + contains a reconstruction of either the SIP WWW-Authenticate or + Proxy-Authentication header fields specified in RFC 2617 [RFC2617] + for the HTTP Digest authentication scheme. Additionally, the AVP may + include a Digest-HA1 AVP that contains H(A1) (as defined in RFC 2617 + [RFC2617]). H(A1) allows the Diameter client to create an expected + response and compare it with the Digest response received from the + SIP UA. + + + + + +Garcia-Martin, et al. Standards Track [Page 51] + +RFC 4740 Diameter SIP Application November 2006 + + + The SIP-Authenticate AVP is defined as follows (per the + grouped-avp-def of RFC 3588 [RFC3588]): + + SIP-Authenticate ::= < AVP Header: 379 > + { Digest-Realm } + { Digest-Nonce } + [ Digest-Domain ] + [ Digest-Opaque ] + [ Digest-Stale ] + [ Digest-Algorithm ] + [ Digest-QoP ] + [ Digest-HA1] + * [ Digest-Auth-Param ] + * [ AVP ] + +9.5.4. SIP-Authorization AVP + + The SIP-Authorization AVP (AVP Code 380) is of type Grouped and + contains a reconstruction of either the SIP Authorization or + Proxy-Authorization header fields specified in RFC 2617 [RFC2617] for + the HTTP Digest authentication scheme. + + The SIP-Authorization AVP is defined as follows (per the + grouped-avp-def of RFC 3588 [RFC3588]): + + SIP-Authorization ::= < AVP Header: 380 > + { Digest-Username } + { Digest-Realm } + { Digest-Nonce } + { Digest-URI } + { Digest-Response } + [ Digest-Algorithm ] + [ Digest-CNonce ] + [ Digest-Opaque ] + [ Digest-QoP ] + [ Digest-Nonce-Count ] + [ Digest-Method] + [ Digest-Entity-Body-Hash ] + * [ Digest-Auth-Param ] + * [ AVP ] + +9.5.5. SIP-Authentication-Info AVP + + The SIP-Authentication-Info AVP (AVP Code 381) is of type Grouped and + contains a reconstruction of the SIP Authentication-Info header + specified in RFC 2617 [RFC2617] for the HTTP Digest authentication + scheme. + + + + +Garcia-Martin, et al. Standards Track [Page 52] + +RFC 4740 Diameter SIP Application November 2006 + + + The SIP-Authentication-Info AVP is defined as follows (per the + grouped-avp-def of RFC 3588 [RFC3588]): + + SIP-Authentication-Info ::= < AVP Header: 381 > + [ Digest-Nextnonce ] + [ Digest-QoP ] + [ Digest-Response-Auth ] + [ Digest-CNonce ] + [ Digest-Nonce-Count ] + * [ AVP ] + + Note that, in some cases, the Digest-Response-Auth AVP cannot be + calculated at the Diameter server, but has to be calculated at the + Diameter client (SIP server). For example, if the value of the + quality of protection (qop) parameter in Digest is set to "auth-int", + then the response-digest (rspauth parameter value in Digest) is + calculated with the hash of the body of the SIP response, which is + not available at the Diameter server. In this case, the Diameter + client (SIP server) must calculate the response-digest once the body + of the SIP response is calculated. + + Therefore, a value of "auth-int" in the Digest-QoP AVP of the + SIP-Authentication-Info AVP indicates that the Diameter client (SIP + server) MUST compute the Digest "rspauth" parameter value at the + Diameter client (SIP server). + +9.5.6. Digest AVPs + + The following AVPs are RADIUS attributes defined in the RADIUS + Extension for Digest Authentication [RFC4590] and imported by this + specification: Digest-AKA-Auts, Digest-Algorithm, Digest-Auth-Param, + Digest-CNonce, Digest-Domain, Digest-Entity-Body-Hash, Digest-HA1, + Digest-Method, Digest-Nextnonce, Digest-Nonce, Digest-Nonce-Count, + Digest-Opaque, Digest-QoP, Digest-Realm, Digest-Response, + Digest-Response-Auth, Digest-URI, Digest-Username, and Digest-Stale. + +9.5.6.1. Considerations about Digest-HA1 AVP + + The Digest-HA1 AVP contains the value, pre-calculated at the Diameter + server, of H(A1) as defined in RFC 2617 [RFC2617]. The Diameter + client can use H(A1) to calculate the expected Digest response, + according to this challenge. If the SIP UA is in possession of the + credentials, the calculated expected response and the response sent + from the SIP UA will match. The Diameter server MAY include this AVP + to enable and assist the SIP server in authenticating the SIP UA. + + This scenario is not applicable when the Diameter server is + configured to use a session MD5 (MD5-sess) algorithm, because the + + + +Garcia-Martin, et al. Standards Track [Page 53] + +RFC 4740 Diameter SIP Application November 2006 + + + Diameter server requires the client nonce to compute the H(A1) before + sending it to the Diameter client, and the client nonce might not be + available when the computation of H(A1) is done. Therefore, if the + final authentication is delegated to the Diameter client, it is + RECOMMENDED to configure the Diameter server to use algorithms + different than MD5-sess in HTTP Digest. + + It is up to the Diameter server to include a Digest-HA1 AVP. The + Diameter server calculates the Digest H(A1) with the username, + password, and realm (and nonce and cnonce, if applicable) as inputs, + and places the result in the Digest-HA1 AVP value. For more details + of the A1 computation, see RFC 2617 [RFC2617] Section 3.2.2.2. The + Diameter client can calculate the Digest expected response with H(A1) + as input, as described in RFC 2617 [RFC2617] Section 3.2.2. + + Section 11 provides further normative details about the usage of the + Digest-HA1 AVP. + +9.5.6.2. Considerations about Digest-Entity-Body-Hash AVP + + The Digest-Entity-Body-Hash AVP contains a hash of the entity body + contained in the SIP message. This hash is required by HTTP Digest + with quality of protection set to "auth-int". Diameter clients MUST + use this AVP to transport the hash of the entity body when HTTP + Digest is the authentication mechanism and the Diameter server + requires verification of the integrity of the entity body (e.g., qop + parameter set to "auth-int"). + + The clarifications described in Section 22.4 of RFC 3261 [RFC3261] + about the hash of empty entity bodies apply to the + Digest-Entity-Body-Hash AVP. + +9.5.6.3. Considerations about Digest-Auth-Param AVP + + The Digest-Auth-Param AVP is the mechanism whereby the Diameter + client and Diameter server can exchange possible extension parameters + contained in Digest headers that are either not understood by the + Diameter client or for which there are no corresponding stand-alone + AVPs. Unlike the previously listed Digest-* AVPs, the + Digest-Auth-Param contains not only the value, but also the parameter + name, since it is unknown to the Diameter client. The Diameter node + MUST insert one Digest parameter/value combination per AVP value. If + the Digest header contains several unknown parameters, then the + Diameter implementation MUST repeat this AVP and each instance MUST + contain one different unknown Digest parameter/value combination. + This AVP corresponds to the "auth-param" parameter defined in Section + 3.2.1 of RFC 2617 [RFC2617]. + + + + +Garcia-Martin, et al. Standards Track [Page 54] + +RFC 4740 Diameter SIP Application November 2006 + + + Example: Assume that the Diameter server wants the SIP server to send + a "foo" parameter with the value set to "bar", so that the SIP server + sends that combination in a SIP WWW-Authenticate header field. The + Diameter server builds a grouped SIP-Authenticate AVP that contains a + Digest-Auth-Param whose value is set to foo="bar". Then the SIP + server creates the WWW-Authenticate header field with all the digest + parameters (received in Digest-* AVPs) and adds the foo="bar" + parameter to that header field. + +9.6. SIP-Number-Auth-Items AVP + + The SIP-Number-Auth-Items AVP (AVP Code 382) is of type Unsigned32 + and indicates the number of authentication and/or authorization + credentials that the Diameter server included in a Diameter message. + + When the AVP is present in a request, it indicates the number of + SIP-Auth-Data-Items the Diameter client is requesting. This can be + used, for instance, when the SIP server is requesting several + pre-calculated authentication credentials. In the answer message, + the SIP-Number-Auth-Items AVP indicates the actual number of items + that the Diameter server included. + +9.7. SIP-Deregistration-Reason AVP + + The SIP-Deregistration-Reason AVP (AVP Code 383) is of type Grouped + and indicates the reason for a deregistration operation. + + The SIP-Deregistration-Reason AVP is defined as follows (per the + grouped-avp-def of RFC 3588 [RFC3588]): + + SIP-Deregistration-Reason ::= < AVP Header: 383 > + { SIP-Reason-Code } + [ SIP-Reason-Info ] + * [ AVP ] + +9.7.1. SIP-Reason-Code AVP + + The SIP-Reason-Code AVP (AVP Code 384) is of type Enumerated and + defines the reason for the network initiated deregistration. The + following values are defined: + + o PERMANENT_TERMINATION (0) + o NEW_SIP_SERVER_ASSIGNED (1) + o SIP_SERVER_CHANGE (2) + o REMOVE_SIP_SERVER (3) + + + + + + +Garcia-Martin, et al. Standards Track [Page 55] + +RFC 4740 Diameter SIP Application November 2006 + + +9.7.2. SIP-Reason-Info AVP + + The SIP-Reason-Info AVP (AVP Code 385) is of type UTF8String and + contains textual information that can be rendered to the user, about + the reason for a deregistration. + +9.8. SIP-AOR AVP + + The SIP-AOR AVP is a RADIUS attribute imported from the RADIUS + Extension for Digest Authentication [RFC4590] namespace, allowing a + smooth transition between RADIUS and Diameter applications supporting + SIP. The SIP-AOR AVP carries the URI of the intended user related to + the SIP request (whose location in SIP may vary depending on the + actual SIP request and whether the SIP server is acting on Diameter + due to a SIP-originated or terminating requests). + + The Diameter client (SIP server) uses the value found in a SIP + Request-URI or a header field value of the SIP request to construct + the SIP-AOR AVP. The selection of a Request-URI or a particular + header field to create the value of the SIP-AOR AVP depends on the + semantics of the SIP message and whether the SIP server is acting for + originating or terminating requests. For instance, when the SIP + server receives an INVITE request addressed to the served user (e.g., + the SIP server is receiving a terminating SIP request), it maps the + SIP Request-URI of the SIP request to this AVP. However, when the + SIP server receives an INVITE request originated by the served user, + it can map either the P-Asserted-Identity or the From header field + values to this AVP. If the SIP server is acting as a SIP registrar, + then it maps the To header field of the REGISTER request to the + SIP-AOR AVP. + +9.9. SIP-Visited-Network-Id AVP + + The SIP-Visited-Network-Id AVP (AVP Code 386) is of type UTF8String. + This AVP contains an identifier that helps the home network identify + the visited network (e.g., the visited network domain name), in order + to authorize roaming to that visited network. + +9.10. SIP-User-Authorization-Type AVP + + The SIP-User-Authorization-Type AVP (AVP Code 387) is of type + Enumerated and indicates the type of user authorization being + performed in a User Authorization operation, i.e., the Diameter + User-Authorization-Request (UAR) command. The following values are + defined: + + + + + + +Garcia-Martin, et al. Standards Track [Page 56] + +RFC 4740 Diameter SIP Application November 2006 + + + o REGISTRATION (0) + This value is used for initial registration or re-registration. + This is the default value. + + o DEREGISTRATION (1) + This value is used for deregistration. + + o REGISTRATION_AND_CAPABILITIES (2) + This value is used for initial registration or re-registration + when the SIP server explicitly requests the Diameter server to get + capability information. This capability information helps the SIP + server to allocate another SIP server to serve the user. + +9.11. SIP-Supported-User-Data-Type AVP + + The SIP-Supported-User-Data-Type AVP (AVP Code 388) is of type + UTF8String and contains a string that identifies the type of + supported user data (user profile, see SIP-User-Data AVP + (Section 9.12)) supported in the node. The AVP can be repeated, if + the SIP server supports several user data types. In case of + repetition, the Diameter client should order the different instances + of this AVP according to its preferences. + + When the Diameter client inserts this AVP in a SAR message, it allows + the Diameter client to provide an indication to the Diameter server + of the types of user data supported by the SIP server. The Diameter + server, upon inspection of these AVPs, will return a suitable + SIP-User-Data AVP (Section 9.12) of the type indicated in the + SIP-User-Data-Type AVP (Section 9.12.1). + +9.12. SIP-User-Data AVP + + The SIP-User-Data AVP (AVP Code 389) is of type Grouped. This AVP + allows the Diameter server to transport user-specific data, such as a + user profile, to the SIP server (in the Diameter client). The + Diameter server selects a type of user data that is understood by the + SIP server in the Diameter client, and has been indicated in a + SIP-Supported-User-Data-Type AVP. In case the Diameter client + indicated support for several types of user data, the Diameter server + SHOULD choose the first type supported by the client. + + The SIP-User-Data grouped AVP contains a SIP-User-Data-Type AVP that + indicates the type of user data included in the + SIP-User-Data-Contents-AVP. + + The SIP-User-Data AVP is defined as follows (per the grouped-avp-def + of RFC 3588 [RFC3588]): + + + + +Garcia-Martin, et al. Standards Track [Page 57] + +RFC 4740 Diameter SIP Application November 2006 + + + SIP-User-Data ::= < AVP Header: 389 > + { SIP-User-Data-Type } + { SIP-User-Data-Contents } + * [ AVP ] + +9.12.1. SIP-User-Data-Type AVP + + The SIP-User-Data AVP (AVP Code 390) is of type UTF8String and + contains a string that identifies the type of user data included in + the SIP-User-Data AVP (Section 9.12). + + This document does not specify a convention to characterize the type + of user data contained in the SIP-User-Data AVP (Section 9.12). It + is believed that in most cases this feature will be used in + environments controlled by a network administrator who can configure + both the client and server to assign the same value type at the + client and server. It is also RECOMMENDED that organizations + developing their own profile of SIP-User-Data AVP (Section 9.12) + allocate a type based on their canonical DNS name. For instance, + organization "example.com" can define several types of SIP-User-Data + and allocate the types "type1.dsa.example.com", + "type2.dsa.example.com", and so on. This convention will avoid a + clash in the allocation of types of SIP-User-Data AVP (Section 9.12). + +9.12.2. SIP-User-Data-Contents AVP + + The SIP-User-Data-Contents AVP (AVP Code 391) is of type OctetString. + The Diameter peers do not need to understand the value of this AVP. + + The AVP contains the user profile data required for a SIP server to + give service to the user. + +9.13. SIP-User-Data-Already-Available AVP + + The SIP-User-Data-Already-Available AVP (AVP Code 392) is of type + Enumerated and gives an indication to the Diameter server about + whether the Diameter client (SIP server) already received the portion + of the user profile needed in order to serve the user. The following + values are defined: + + o USER_DATA_NOT_AVAILABLE (0) + The Diameter client (SIP server) does not have the data that it + needs to serve the user. + + o USER_DATA_ALREADY_AVAILABLE (1) + The Diameter client (SIP server) already has received the data + that it needs to serve the user. + + + + +Garcia-Martin, et al. Standards Track [Page 58] + +RFC 4740 Diameter SIP Application November 2006 + + +9.14. SIP-Method AVP + + The SIP-Method-AVP (AVP Code 393) is of type UTF8String and contains + the method of the SIP request that triggered the Diameter message. + The Diameter server MUST use this AVP solely for authorization of SIP + requests, and MUST NOT use it to compute the Digest authentication. + To compute the Digest authentication, the Diameter server MUST use + the Digest-Method AVP instead. + +10. New Values for Existing AVPs + + This section defines new values that the Diameter SIP application + extends to already existing AVPs. + +10.1. Extension to the Result-Code AVP Values + + The Result-Code AVP is already defined in RFC 3588 [RFC3588]. In + addition to the values already defined in RFC 3588 [RFC3588], the + Diameter SIP application defines the following new Result-Code AVP + values: + +10.1.1. Success Result-Code AVP Values + + A Diameter peer uses Result-Code AVP values that fall into the + success category to inform the remote peer that a request has been + successfully completed. + + o DIAMETER_FIRST_REGISTRATION 2003 + The user was not previously registered. The Diameter server has + now authorized the registration. + + o DIAMETER_SUBSEQUENT_REGISTRATION 2004 + The user is already registered. The Diameter server has now + authorized the re-registration. + + o DIAMETER_UNREGISTERED_SERVICE 2005 + The user is not currently registered, but the requested service + can still be granted to the user. + + o DIAMETER_SUCCESS_SERVER_NAME_NOT_STORED 2006 + The request operation was successfully processed. The Diameter + server does not keep a record of the SIP server address assigned + to the user. + + o DIAMETER_SERVER_SELECTION 2007 + The Diameter server has authorized the registration. The user has + already been assigned a SIP server, but it may be necessary to + select a new SIP server for the user. + + + +Garcia-Martin, et al. Standards Track [Page 59] + +RFC 4740 Diameter SIP Application November 2006 + + + o DIAMETER_SUCCESS_AUTH_SENT_SERVER_NOT_STORED 2008 + The requested operation was successfully executed. The Diameter + server is sending a number of authentication credentials in the + answer message. The Diameter server does not keep a record of the + SIP server. + +10.1.2. Transient Failures Result-Code AVP Values + + A Diameter peer uses a Result-Code AVP value that falls in the + transient failures category to inform the remote peer that a request + could not be satisfied at the time it was received, but it MAY be + satisfied by the Diameter peer in the future. + + o DIAMETER_USER_NAME_REQUIRED 4013 + The Diameter request did not contain a User-Name AVP, which is + required to complete the transaction. The Diameter peer MAY + include a User-Name AVP and attempt the request again. + +10.1.3. Permanent Failures Result-Code AVP Values + + A Diameter peer uses a Result-Code AVP value that falls into the + permanent failure category to inform the remote peer that the request + failed and should not be attempted again. + + o DIAMETER_ERROR_USER_UNKNOWN 5032 + The SIP-AOR AVP value does not belong to a known user in this + realm. + + o DIAMETER_ERROR_IDENTITIES_DONT_MATCH 5033 + The value in one of the SIP-AOR AVPs is not allocated to the user + specified in the User-Name AVP. + + o DIAMETER_ERROR_IDENTITY_NOT_REGISTERED 5034 + A query for location information is received for a SIP AOR that + has not been registered before. The user to which this identity + belongs cannot be given service in this situation. + + o DIAMETER_ERROR_ROAMING_NOT_ALLOWED 5035 + The user is not allowed to roam to the visited network. + + o DIAMETER_ERROR_IDENTITY_ALREADY_REGISTERED 5036 + The identity being registered has already been assigned a server + and the registration status does not allow that it is overwritten. + + o DIAMETER_ERROR_AUTH_SCHEME_NOT_SUPPORTED 5037 + The authentication scheme indicated in an authentication request + is not supported. + + + + +Garcia-Martin, et al. Standards Track [Page 60] + +RFC 4740 Diameter SIP Application November 2006 + + + o DIAMETER_ERROR_IN_ASSIGNMENT_TYPE 5038 + The SIP server address sent in the SIP-Server-URI AVP value of the + Diameter Server-Assignment-Request (SAR) command is the same SIP + server address that is currently assigned to the user name, but + the SIP-Server-Assignment-Type AVP is not allowed. For example, + the user is registered and the Server-Assignment-Request indicates + the assignment for an unregistered user. + + o DIAMETER_ERROR_TOO_MUCH_DATA 5039 + The Diameter peer in the SIP server receives more data than it can + accept. The SIP server cannot overwrite the already stored data. + + o DIAMETER_ERROR_NOT SUPPORTED_USER_DATA 5040 + The SIP server informs the Diameter server that the received + subscription data contained information that was not recognized or + supported. + +11. Authentication Details + + Authenticating a user can occur through various mechanisms. + Currently HTTP Digest authentication is supported. The actual + authentication is performed in either the SIP server or the Diameter + server. + + If the Diameter server wants to assure that authentication will take + place in the Diameter server (as opposed to a delegated + authentication taking place in the SIP server), it MUST NOT include a + Digest-HA1 AVP (part of the grouped SIP-Authenticate AVP, which in + turn is part of the SIP-Auth-Data-Item AVP) in a MAA message. The + Diameter server MAY include a pre-calculated Digest-HA1 AVP in the + MAA message if it wants to delegate authentication of the user to the + SIP server. + + Note that on systems where the SIP User Agent is using HTTP Digest + authentication [RFC2617] inside of Transport Layer Security (TLS) + [RFC4346], where only the SIP proxy server has a certificate, + delegating authentication to the SIP server (by making Digest-HA1 + available to the SIP server) might reduce the load on the Diameter + server. + + When requesting authentication, the Diameter client indicates in the + SIP-Number-Auth-Items AVP value of a Diameter MAR message how many + authentication credentials are being requested. In the Diameter MAA + message, the Diameter server MAY include more than one + SIP-Auth-Data-Item AVP, but it is only useful for the Diameter client + if the Digest-QoP AVP was set to 'auth-int' (in the MAR message), and + if future authentications will have the same realm. When including + more than one SIP-Auth-Data-Item AVP, the Diameter server SHOULD + + + +Garcia-Martin, et al. Standards Track [Page 61] + +RFC 4740 Diameter SIP Application November 2006 + + + indicate how many instances of SIP-Auth-Data-Item AVPs are present + with the SIP-Number-Auth-Items AVP. This number may be different + from the one requested in the Diameter MAR message. If multiple + SIP-Auth-Data-Item AVPs are present, and their ordering is + significant, the Diameter server MUST include a SIP-Item-Number AVP + in each grouping to indicate the order. The + SIP-Authentication-Scheme AVP indicates "Digest" and the + SIP-Authenticate AVP contains data (typically a challenge of some + kind) that the user can use for her authentication. The grouped + SIP-Authorization AVP contains the AVPs that conform to the response + expected from the user. + + If the Diameter server performs the authentication of the user, the + Diameter MAR message that the Diameter client sends to the Diameter + server MUST include all the authentication credentials supplied by + the SIP UA (there might be more than one credential, e.g., different + realms, authentication of proxies, etc.). Each credential is + inserted in a grouped SIP-Authorization AVP (part of the grouped + SIP-Auth-Data-Item AVP). The Diameter client MUST insert a + SIP-Number-Auth-Items AVP with the value set to the number of + credentials enclosed. If necessary, the Digest-Entity-Body-Hash AVP + will contain a hash of the body, needed to perform the + authentication. If the authentication is successful, the Diameter + MAA message will contain a Result-Code AVP indicating success, and if + necessary, the Diameter server MAY include one or more + SIP-Auth-Data-Item AVPs to provide further authentication credentials + to the SIP server. If the authentication is unsuccessful due to + missing credentials, the Diameter MAA message will include a + SIP-Auth-Data-Item AVP with the SIP-Authentication-Scheme and + SIP-Authenticate AVPs containing data (typically a challenge of some + kind) that the user can use to authenticate itself. + + There are situations where a SIP request traverses several proxies, + and each of the proxies requests to authenticate the SIP UA. In this + situation, it is a valid scenario that a SIP request received at a + SIP server contains several sets of credentials. The 'realm' + directive in HTTP is the key that the Diameter client can use to + determine which credential is applicable. Also, none of the realms + may be of interest to the Diameter client, in which case the Diameter + client MUST consider that no credentials (of interest) were sent. In + any case, a Diameter client MUST send zero or exactly one credential + to the Diameter server. The Diameter client MUST choose the + credential based on the 'realm' directive in the + Authorization/Proxy-Authorization header field, and it MUST match the + realm of the Diameter client. + + It must be noted that nonces are always generated in the Diameter + server. + + + +Garcia-Martin, et al. Standards Track [Page 62] + +RFC 4740 Diameter SIP Application November 2006 + + +12. Migration from RADIUS + + RADIUS offers support for HTTP Digest authentication in the RADIUS + Extension for Digest Authentication [RFC4590]. A number of AVPs (the + Digest-* AVPs) of this Diameter SIP application are imported from the + RADIUS attributes namespace, thus making the migration from RADIUS to + Diameter smooth. + + Note that the RADIUS Extension for Digest Authentication [RFC4590] + provides a more limited scope than this Diameter SIP application. + Specifically, the RADIUS extension for Digest Authentication merely + provides support for HTTP Digest authentication, whereas the Diameter + SIP application provides support for user location, profile + downloading and update, etc. + + The following sections discuss several configurations in which a + gateway translates RADIUS to Diameter and vice versa. + +12.1. Gateway from RADIUS Client to Diameter Server + + The gateway maps Access-Request messages to MAR request. If a RADIUS + Access-Request message contains at least one Digest-* attribute, the + gateway maps all Digest-* attributes to the AVPs of a Diameter + SIP-Authorization AVP, constructs a MAR message, and sends it to the + Diameter server. If the RADIUS Access-Request message does not + contain any Digest-* attribute, then the RADIUS client does not want + to apply HTTP Digest authentication, in which case, actions at the + gateway are outside the scope of this document. + + The Diameter server responds with a MAA message. If the MAA message + contains a Result-Code AVP set to the value DIAMETER_MULTI_ROUND_AUTH + and contains challenge parameters in a SIP-Authenticate AVP, then the + gateway translates the AVPs of SIP-Authenticate AVP and puts the + resulting RADIUS attributes into an Access-Challenge message. It + sends the Access-Challenge message to the RADIUS client. + + If the MAA message contains a SIP-Authentication-Info and a + Digest-Response AVP, the gateway converts these AVPs to the + corresponding RADIUS attributes and constructs a RADIUS message. If + the Result-Code AVP is DIAMETER_SUCCESS, an Access-Accept is sent. + In all other cases, an Access-Reject is sent. + +12.2. Gateway from Diameter Client to RADIUS Server + + The Diameter client sends a Diameter MAR message to the gateway. If + the MAR message does not contain SIP-Auth-Data-Item AVPs, the gateway + constructs an Access-Request message and maps the SIP-AOR and + SIP-Method AVPs to RADIUS attributes. The gateway sends the + + + +Garcia-Martin, et al. Standards Track [Page 63] + +RFC 4740 Diameter SIP Application November 2006 + + + Access-Request message to the RADIUS server, which will respond with + an Access-Challenge. The gateway creates a MAA message with a + Result-Code AVP set to DIAMETER_MULTI_ROUND_AUTH and maps the + Digest-* attributes to Diameter AVPs in a SIP-Authenticate AVP. The + gateway sends the resulting MAA to the Diameter client, which will + respond with a new MAR. + + The gateway checks the SIP-Auth-Data-Item AVPs of this MAR for an AVP + where the Digest-Realm AVP matches the locally configured realm + value. It takes the AVPs from this SIP-Auth-Data-Item AVP, converts + them into the corresponding RADIUS attributes and constructs a RADIUS + Access-Request message. The gateway sends the Access-Request message + to the RADIUS server. If the RADIUS server responds with an + Access-Accept message, the gateway converts the RADIUS attributes to + Diameter AVPs, constructs a MAA message with a Result-Code AVP set to + DIAMETER_SUCCESS and sends this message to the Diameter client. If + the RADIUS server responds with an Access-Reject message, the gateway + converts the RADIUS attributes to Diameter AVPs, constructs a MAA + message with a Result-Code AVP set to + DIAMETER_ERROR_IDENTITIES_DONT_MATCH, and sends this message to the + Diameter client. + +12.3. Known Limitations + + As mentioned earlier, there is not a 100% match between the Diameter + SIP application and the RADIUS Extension for Digest Authentication + [RFC4590]. In particular, the RADIUS Extension for Digest + Authentication [RFC4590] does not offer equivalent functionality to + the Diameter UAR/UAA, SAR/SAA, LIR/LIA, RTR/RTA, and PPR/PPA messages + defined by this specification. + +13. IANA Considerations + + This document serves as IANA registration request for a number of + items that should be registered in the AAA parameters registry. + +13.1. Application Identifier + + This document defines a standards-track Application-ID that falls + into the Application Identifier standards-track address space defined + by RFC 3588 [RFC3588] Section 11.3. This Application-ID has been + registered in the Application IDs sub-registry of the AAA parameters + registry with the following data: + + ID values Name Reference + ----------- ------------------------ --------- + 6 Diameter Session Initiation RFC 4740 + Protocol (SIP) Application + + + +Garcia-Martin, et al. Standards Track [Page 64] + +RFC 4740 Diameter SIP Application November 2006 + + +13.2. Command Codes + + This document defines new standard commands whose Command Codes are + to be allocated within the standard permanent Command Codes address + space defined in RFC 3588 [RFC3588] Section 11.2.1. These command + codes should be registered in the Command Codes sub-registry of the + AAA parameters registry. + + Table 1 in Section 8 contains the detailed list of Command Code names + and values that are part of this Diameter application. + +13.3. AVP Codes + + This document defines new standard AVPs, whose AVP Codes are to be + allocated within the AVP Codes address space defined in RFC 3588 + [RFC3588] Section 11.4. These AVP codes have been registered in the + AVP Codes sub-registry of the AAA parameters registry. + + Table 2 in Section 9 contains the detailed list of AVP names and AVP + codes that are part of this Diameter application. + +13.4. Additional Values for the Result-Code AVP Value + + This document defines new standard Result-Code AVP values to be + allocated within the Result-Code AVP address space defined in RFC + 3588 [RFC3588] Section 14.4.1. These values are listed in the + Result-Code AVP values section of the AVP Specific Values + sub-registry of the AAA parameters registry. + + Section 10.1.1 lists the new Result-Code AVP values that fall into + the success category, according to RFC 3588 [RFC3588] Section 7.1.2. + + Section 10.1.2 lists the new Result-Code AVP values that fall into + the transient failures category, according to RFC 3588 [RFC3588] + Section 7.1.4. + + Section 10.1.3 lists the new Result-Code AVP values that fall into + the permanent failures category, according to RFC 3588 [RFC3588] + Section 7.1.5. + + + + + + + + + + + + +Garcia-Martin, et al. Standards Track [Page 65] + +RFC 4740 Diameter SIP Application November 2006 + + +13.5. Creation of the SIP-Server-Assignment-Type Section in the AAA + Registry + + This document defines a new SIP-Server-Assignment-Type AVP (see + Section 9.4). This AVP is of type Enumerated. We define an initial + set of values that should be registered by IANA. IANA should create + a new "SIP-Sever-Assignment-Type AVP values" section under the AVP + Specific Values sub-registry of the AAA parameters registry. The + initial list of values is listed in Section 9.4. + +13.6. Creation of the SIP-Authentication-Scheme Section in the AAA + Registry + + This document defines a new SIP-Authentication-Scheme AVP (see + Section 9.5.1). This AVP is of type Enumerated. We currently define + a single value that should be registered by IANA. IANA should create + a new "SIP-Authentication-Scheme AVP values" section under the AVP + Specific Values sub-registry of the AAA parameters registry. The + initial list of values is included in Section 9.5.1. + +13.7. Creation of the SIP-Reason-Code Section in the AAA Registry + + This document defines a new SIP-Reason-Code AVP (see Section 9.7.1). + This AVP is of type Enumerated. We define an initial set of values + that should be registered by IANA. IANA should create a new + "SIP-Reason-Code AVP values" section under the AVP Specific Values + sub-registry of the AAA parameters registry. The initial list of + values is listed in Section 9.7.1. + +13.8. Creation of the SIP-User-Authorization-Type Section in the AAA + Registry + + This document defines a new SIP-User-Authorization-Type AVP (see + Section 9.10). This AVP is of type Enumerated. We define an initial + set of values that should be registered by IANA. IANA should create + a new "SIP-User-Authorization-Type AVP values" section under the AVP + Specific Values sub-registry of the AAA parameters registry. The + initial list of values is listed in Section 9.10. + +13.9. Creation of the SIP-User-Data-Already-Available Section in the + AAA Registry + + This document defines a new SIP-User-Data-Already-Available AVP (see + Section 9.13). This AVP is of type Enumerated. We define an initial + set of values which should be registered by IANA. IANA should create + a new "SIP-User-Data-Already-Available AVP values" section under the + AVP Specific Values sub-registry of the AAA parameters registry. The + initial list of values is listed in Section 9.13. + + + +Garcia-Martin, et al. Standards Track [Page 66] + +RFC 4740 Diameter SIP Application November 2006 + + +14. Security Considerations + + This memo does not describe a stand-alone protocol, but a particular + application for the Diameter protocol [RFC3588]. Consequently, all + the security considerations applicable to Diameter automatically + apply to this memo. In particular, Section 13 of RFC 3588 applies to + this memo. + + This Diameter SIP application allows a Diameter client to use the + properties of HTTP Digest authentication [RFC2617] by evaluating or + sending to the Diameter server the credentials supplied by a user. + The discussion of HTTP Digest authentication in Section 4 of RFC 2617 + [RFC2617] is also applicable to this memo. + + This Diameter SIP application also allows a Diameter client to use + the properties of HTTP Digest authentication using AKA [RFC3310] by + evaluating or sending to the Diameter server the credentials supplied + by a user. Section 5 of RFC 3310 [RFC3310] is also applicable to + this memo. + +14.1. Final Authentication Check in the Diameter Client/SIP Server + + The Diameter SIP application can be configured to operate in a + scenario where the final authentication check is performed in the + Diameter client (SIP server). There are a number of security + considerations associated to it; all of them are consequences of the + requirement to transfer H(A1) from the Diameter server to the + Diameter client: + + o Both Diameter client and server must trust each other, such as + when both client and server belong to the same administrative + domain. + + o To avoid eavesdroppers, the transport protocol between the + Diameter client and server MUST be secured. RFC 3588 [RFC3588] + specifies TLS [RFC4346] and IPsec as possible transport protection + mechanisms for Diameter. + + Due to these security considerations, it is RECOMMENDED to configure + the Diameter SIP application to operate in the mode where the final + authentication check is performed in the Diameter server. + + + + + + + + + + +Garcia-Martin, et al. Standards Track [Page 67] + +RFC 4740 Diameter SIP Application November 2006 + + +15. Contributors + + The authors would like to thank the following contributors who made + substantial contributions to this work: + + Pete McCann Lucent + + Jaakko Rajaniemi Nokia + + Wolfgang Beck (Deutsche Telekom AG) provided the text in Section 12, + "Migration from RADIUS". + +16. Acknowledgements + + The authors would like to thank Tony Johansson and Kevin Purser for + their invaluable contribution to the start-up of this application and + the continuous progress. The authors would like to thank Daniel + Warren, Jayshree Bharatia, Kuntal Chowdhury, Jari Arkko, Avi Lior, + Wolfgang Beck, Ulrich Wiehe, Cullen Jennings, Anu Leinonen, Glen + Zorn, German Blanco, Mikko Aittola, Bert Wijnen, and Sam Hartman for + their reviews and valuable comments. + + The Diameter SIP application is based on the Diameter application for + the Cx interface of the 3GPP IP Multimedia Subsystem [3GPP.29.229]. + The authors would like to thank 3GPP Working Group CN4 for this work. + +17. References + +17.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, + S., Leach, P., Luotonen, A., and L. Stewart, "HTTP + Authentication: Basic and Digest Access + Authentication", RFC 2617, June 1999. + + [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., + Johnston, A., Peterson, J., Sparks, R., Handley, M., + and E. Schooler, "SIP: Session Initiation Protocol", + RFC 3261, June 2002. + + [RFC3310] Niemi, A., Arkko, J., and V. Torvinen, "Hypertext + Transfer Protocol (HTTP) Digest Authentication Using + Authentication and Key Agreement (AKA)", RFC 3310, + September 2002. + + + + +Garcia-Martin, et al. Standards Track [Page 68] + +RFC 4740 Diameter SIP Application November 2006 + + + [RFC3588] Calhoun, P., Loughney, J., Guttman, E., Zorn, G., and + J. Arkko, "Diameter Base Protocol", RFC 3588, + September 2003. + + [RFC4590] Sterman, B., Sadolevsky, D., Schwartz, D., Williams, + D., and W. Beck, "RADIUS Extension for Digest + Authentication", RFC 4590, July 2006. + +17.2. Informative References + + [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer + Security (TLS) Protocol Version 1.1", RFC 4346, April + 2006. + + [RFC3263] Rosenberg, J. and H. Schulzrinne, "Session Initiation + Protocol (SIP): Locating SIP Servers", RFC 3263, + June 2002. + + [RFC3680] Rosenberg, J., "A Session Initiation Protocol (SIP) + Event Package for Registrations", RFC 3680, + March 2004. + + [RFC3880] Lennox, J., Wu, X., and H. Schulzrinne, "Call + Processing Language (CPL): A Language for User Control + of Internet Telephony Services", RFC 3880, + October 2004. + + [RFC4004] Calhoun, P., Johansson, T., Perkins, C., Hiller, T., + and P. McCann, "Diameter Mobile IPv4 Application", + RFC 4004, August 2005. + + [RFC4005] Calhoun, P., Zorn, G., Spence, D., and D. Mitton, + "Diameter Network Access Server Application", + RFC 4005, August 2005. + + [RFC4006] Hakala, H., Mattila, L., Koskinen, J-P., Stura, M., + and J. Loughney, "Diameter Credit-Control + Application", RFC 4006, August 2005. + + [3GPP.29.229] 3GPP, "Cx and Dx interfaces based on the Diameter + protocol; Protocol details", 3GPP TS 29.229 5.12.0, + June 2006. + + [JSR-000116] Java Community Process, "SIP Servlet API Specification + 1.0 Final Release", JSR 000116, March 2003. + + + + + + +Garcia-Martin, et al. Standards Track [Page 69] + +RFC 4740 Diameter SIP Application November 2006 + + +Authors' Addresses + + Miguel A. Garcia-Martin (Editor) + Nokia + P.O. Box 407 + NOKIA GROUP, FIN 00045 + Finland + + Phone: +358 50 480 4586 + EMail: [email protected] + + + Maria-Carmen Belinchon + Ericsson + Via de los Poblados 13 + Madrid 28033 + Spain + + Phone: +34 91 339 3535 + EMail: [email protected] + + + Miguel A. Pallares-Lopez + Ericsson + Via de los Poblados 13 + Madrid 28033 + Spain + + Phone: +34 91 339 4222 + EMail: [email protected] + + + Carolina Canales-Valenzuela + Ericsson + Via de los Poblados 13 + Madrid 28033 + Spain + + Phone: +34 91 339 2680 + EMail: [email protected] + + + + + + + + + + + +Garcia-Martin, et al. Standards Track [Page 70] + +RFC 4740 Diameter SIP Application November 2006 + + + Kalle Tammi + Nokia + P.O.Box 785 + Tampere 33101 + Finland + + Phone: +358 40 505 8670 + EMail: [email protected] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Garcia-Martin, et al. Standards Track [Page 71] + +RFC 4740 Diameter SIP Application November 2006 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, + AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT + THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY + IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR + PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + +Garcia-Martin, et al. Standards Track [Page 72] + diff --git a/lib/diameter/doc/standard/rfc5447.txt b/lib/diameter/doc/standard/rfc5447.txt new file mode 100644 index 0000000000..ec556ccc9f --- /dev/null +++ b/lib/diameter/doc/standard/rfc5447.txt @@ -0,0 +1,955 @@ + + + + + + +Network Working Group J. Korhonen, Ed. +Request for Comments: 5447 Nokia Siemens Networks +Category: Standards Track J. Bournelle + Orange Labs + H. Tschofenig + Nokia Siemens Networks + C. Perkins + WiChorus + K. Chowdhury + Starent Networks + February 2009 + + + Diameter Mobile IPv6: + Support for Network Access Server to Diameter Server Interaction + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (c) 2009 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. + +Abstract + + A Mobile IPv6 node requires a home agent address, a home address, and + a security association with its home agent before it can start + utilizing Mobile IPv6. RFC 3775 requires that some or all of these + parameters be statically configured. Mobile IPv6 bootstrapping work + aims to make this information dynamically available to the mobile + node. An important aspect of the Mobile IPv6 bootstrapping solution + is to support interworking with existing Authentication, + Authorization, and Accounting (AAA) infrastructures. This document + describes MIPv6 bootstrapping using the Diameter Network Access + Server to home AAA server interface. + + + + +Korhonen, et al. Standards Track [Page 1] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Terminology and Abbreviations . . . . . . . . . . . . . . . . 3 + 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 4. Commands, Attribute-Value Pairs, and Advertising + Application Support . . . . . . . . . . . . . . . . . . . . . 6 + 4.1. Advertising Application Support . . . . . . . . . . . . . 6 + 4.2. Attribute-Value Pair Definitions . . . . . . . . . . . . . 6 + 4.2.1. MIP6-Agent-Info AVP . . . . . . . . . . . . . . . . . 6 + 4.2.2. MIP-Home-Agent-Address AVP . . . . . . . . . . . . . . 7 + 4.2.3. MIP-Home-Agent-Host AVP . . . . . . . . . . . . . . . 7 + 4.2.4. MIP6-Home-Link-Prefix AVP . . . . . . . . . . . . . . 8 + 4.2.5. MIP6-Feature-Vector AVP . . . . . . . . . . . . . . . 8 + 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.1. Home Agent Assignment by the NAS . . . . . . . . . . . . . 10 + 5.2. Home Agent Assignment by the Diameter Server . . . . . . . 11 + 5.3. Home Agent Assignment by the NAS or Diameter Server . . . 11 + 6. Attribute-Value Pair Occurrence Tables . . . . . . . . . . . . 12 + 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 + 7.1. Registration of New AVPs . . . . . . . . . . . . . . . . . 13 + 7.2. New Registry: Mobility Capability . . . . . . . . . . . . 13 + 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 10.1. Normative References . . . . . . . . . . . . . . . . . . . 15 + 10.2. Informative References . . . . . . . . . . . . . . . . . . 15 + + + + + + + + + + + + + + + + + + + + + + + + +Korhonen, et al. Standards Track [Page 2] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + +1. Introduction + + The Mobile IPv6 (MIPv6) specification [RFC3775] requires a mobile + node (MN) to perform registration with a home agent (HA) with + information about its current point of attachment (care-of address). + The HA creates and maintains the binding between the MN's home + address and the MN's care-of address. + + In order to register with an HA, the MN needs to know some + information, such as the home link prefix, the HA address, the home + address(es), the home link prefix length, and security-association- + related information. + + The aforementioned information may be statically configured. + However, static provisioning becomes an administrative burden for an + operator. Moreover, it does not address load balancing, failover, + opportunistic home link assignment, or assignment of local HAs in + close proximity to the MN. Also, the ability to react to sudden + environmental or topological changes is minimal. Static provisioning + may not be desirable, in light of these limitations. + + Dynamic assignment of MIPv6 home registration information is a + desirable feature for ease of deployment and network maintenance. + For this purpose, the AAA infrastructure, which is used for access + authentication, can be leveraged to assign some or all of the + necessary parameters. The Diameter server in the Access Service + Provider's (ASP's) or Mobility Service Provider's (MSP's) network may + return these parameters to the AAA client. Regarding the + bootstrapping procedures, the AAA client might either be the Network + Access Server, in case of the integrated scenario, or the HA, in case + of the split scenario [RFC5026]. The terms "integrated" and "split" + are described in the following terminology section and were + introduced in [RFC4640] and [AAA]. + +2. Terminology and Abbreviations + + 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 RFC 2119 [RFC2119]. + + General mobility terminology can be found in [RFC3753]. The + following additional terms are either borrowed from [RFC4640] or + [RFC5026] or are introduced in this document: + + Access Service Authorizer (ASA): + + A network operator that authenticates an MN and establishes the + MN's authorization to receive Internet service. + + + +Korhonen, et al. Standards Track [Page 3] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + + Access Service Provider (ASP): + + A network operator that provides direct IP packet-forwarding to + and from the MN. + + Mobility Service Authorizer (MSA): + + A service provider that authorizes MIPv6 service. + + Mobility Service Provider (MSP): + + A service provider that provides MIPv6 service. In order to + obtain such service, the MN must be authenticated and authorized + to do so. + + Split Scenario: + + A scenario where the mobility service and the network access + service are authorized by different entities. + + Integrated Scenario: + + A scenario where the mobility service and the network access + service are authorized by the same entity. + + Network Access Server (NAS): + + A device that provides an access service for a user to a network. + + Home AAA (HAAA): + + An Authentication, Authorization, and Accounting server located in + the user's home network, i.e., in the home realm. + + Local AAA (LAAA): + + An Authentication, Authorization, and Accounting proxy located in + the local (ASP) network. + + Visited AAA (VAAA): + + An Authentication, Authorization, and Accounting proxy located in + a visited network, i.e., in the visited realm. In a roaming case, + the local Diameter proxy has the VAAA role (see Figure 1). + + + + + + + +Korhonen, et al. Standards Track [Page 4] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + +3. Overview + + This document addresses the Authentication, Authorization, and + Accounting (AAA) functionality required for the MIPv6 bootstrapping + solutions outlined in [RFC4640], and focuses on the Diameter-based + AAA functionality for the NAS-to-HAAA (home AAA) server + communication. + + In the integrated scenario, MIPv6 bootstrapping is provided as part + of the network access authentication procedure. Figure 1 shows the + participating entities. + + +---------------------------+ +-----------------+ + |Access Service Provider | |ASA/MSA/(MSP) | + |(Mobility Service Provider)| | | + | | | | + | +--------+ | | +--------+ | + | |Local | Diameter | | |Home | | + | |Diameter|<---------------------->|Diameter| | + | |Proxy | (*) | | |Server | | + | +--------+ | | +--------+ | + | ^ ^ | | ^ | + | | | | | |(+) | + | | | | | | | + | Diameter | | v | + | | |(+) +-------+ | | +-------+ | + | | | |Home | | | |Home | | + | | +-------->|Agent | | | |Agent | | + | (*)| |in ASP | | | |in MSP | | + | v +-------+ | | +-------+ | + +-------+ IEEE | +-----------+ +-------+ | +-----------------+ + |Mobile | 802.1X | |NAS/Relay | |DHCPv6 | | + |Node |------------|Diameter |---|Server | | + | | PANA, | |Client |(+)| | | + +-------+ IKEv2, | +-----------+ +-------+ | + DHCP,... +---------------------------+ + (+) + + Legend: + (*): Functionality in scope of this specification. + (+): Extensions described in other documents. + + Figure 1: Mobile IPv6 Bootstrapping in the Integrated Scenario + + In a typical MIPv6 access scenario, an MN is attached to an ASP's + network. During the network attachment procedure, the MN interacts + with the NAS/Diameter client. Subsequently, the NAS/Diameter client + interacts with the Diameter server over the NAS-to-HAAA interface. + + + +Korhonen, et al. Standards Track [Page 5] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + + When the Diameter server performs the authentication and + authorization for network access, it also determines whether the user + is authorized for the MIPv6 service. Based on the MIPv6 service + authorization and the user's policy profile, the Diameter server may + return several MIPv6 bootstrapping-related parameters to the NAS. + The NAS-to-HAAA interface described in this document is not tied to + the Dynamic Host Configuration Protocol for IPv6 (DHCPv6) as the only + mechanism to convey MIPv6-related configuration parameters from the + NAS/Diameter client to the mobile node. + + While this specification addresses the bootstrapping of MIPv6 HA + information and possibly the assignment of the home link prefix, it + does not address how the Security Association (SA) between the MN and + the HA for MIPv6 purposes is created. The creation or the use of the + SA between the MN and the HA takes places after the procedures + described in this specification, and therefore are out of scope. + +4. Commands, Attribute-Value Pairs, and Advertising Application Support + +4.1. Advertising Application Support + + This document does not define a new application. On the other hand, + it defines a number of attribute-value pairs (AVPs) used in the + interface between NAS to HAAA for the integrated scenario of MIPv6 + bootstrapping. These AVPs can be used with any present and future + Diameter applications, where permitted by the command ABNF. The + examples using existing applications and their commands in the + following sections are for informational purposes only. The examples + in this document reuse the Extensible Authentication Protocol (EAP) + [RFC4072] application and its respective commands. + +4.2. Attribute-Value Pair Definitions + +4.2.1. MIP6-Agent-Info AVP + + The MIP6-Agent-Info AVP (AVP code 486) is of type Grouped and + contains necessary information to assign an HA to the MN. When the + MIP6-Agent-Info AVP is present in a message, it MUST contain either + the MIP-Home-Agent-Address AVP, the MIP-Home-Agent-Host AVP, or both + AVPs. The grouped AVP has the following modified ABNF (as defined in + [RFC3588]): + + MIP6-Agent-Info ::= < AVP-Header: 486 > + *2[ MIP-Home-Agent-Address ] + [ MIP-Home-Agent-Host ] + [ MIP6-Home-Link-Prefix ] + * [ AVP ] + + + + +Korhonen, et al. Standards Track [Page 6] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + + If both the MIP-Home-Agent-Address and MIP-Home-Agent-Host APVs are + present in the MIP6-Agent-Info, the MIP-Home-Agent-Address SHOULD + have a precedence over the MIP-Home-Agent-Host. The reason for this + recommendation is that the MIP-Home-Agent-Address points to a + specific home agent, whereas the MIP-Home-Agent-Host may point to a + group of HAs located within the same realm. A Diameter client or + agent may use the MIP-Home-Agent-Host AVP, for instance, to find out + in which realm the HA is located. + + The ABNF allows returning up to two MIPv6 HA addresses. This is a + useful feature for deployments where the HA has both IPv6 and IPv4 + addresses, and particularly addresses Dual Stack Mobile IPv6 + (DSMIPv6) deployment scenarios [DSMIPv6]. + + The MIP6-Agent-Info AVP MAY also be attached by the NAS or by the + intermediating Diameter proxies in a request message when sent to the + Diameter server as a hint of a locally assigned HA. This AVP MAY + also be attached by the intermediating Diameter proxies in a reply + message from the Diameter server, if locally assigned HAs are + authorized by the Diameter server. There MAY be multiple instances + of the MIP6-Agent-Info AVP in Diameter messages, for example, in + cases where the NAS receives HA information from an MN's home network + and locally allocated HA information from the visited network. See + Section 4.2.5 for further discussion on possible scenarios. + +4.2.2. MIP-Home-Agent-Address AVP + + The MIP-Home-Agent-Address AVP (AVP Code 334 [RFC4004]) is of type + Address and contains the IPv6 or IPv4 address of the MIPv6 HA. The + Diameter server MAY decide to assign an HA to the MN that is in close + proximity to the point of attachment (e.g., determined by the NAS- + Identifier AVP). There may be other reasons for dynamically + assigning HAs to the MN, for example, to share the traffic load. + +4.2.3. MIP-Home-Agent-Host AVP + + The MIP-Home-Agent-Host AVP (AVP Code 348 [RFC4004]) is of type + Grouped and contains the identity of the assigned MIPv6 HA. Both the + Destination-Realm and the Destination-Host AVPs of the HA are + included in the grouped AVP. The usage of the MIP-Home-Agent-Host + AVP is equivalent to the MIP-Home-Agent-Address AVP but offers an + additional level of indirection by using the DNS infrastructure. The + Destination-Host AVP is used to identify an HA, and the Destination- + Realm AVP is used to identify the realm where the HA is located. + + Depending on the actual deployment and DNS configuration, the + Destination-Host AVP MAY represent one or more home agents. It is + RECOMMENDED that the Destination-Host AVP identifies exactly one HA. + + + +Korhonen, et al. Standards Track [Page 7] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + + It is RECOMMENDED that the MIP-Home-Agent-Host AVP is always included + in the MIP6-Agent-Info AVP. In this way, the HA can be associated + with the corresponding realm of the Diameter entity that added the + MIP6-Agent-Info AVP using the Destination-Realm AVP, which is + included in the MIP-Home-Agent-Host AVP. + +4.2.4. MIP6-Home-Link-Prefix AVP + + The MIP6-Home-Link-Prefix AVP (AVP Code 125) is of type OctetString + and contains the Mobile IPv6 home network prefix information in a + network byte order. The home network prefix MUST be encoded as the + 8-bit prefix length information (one octet) followed by the 128-bit + field (16 octets) for the available home network prefix. The + trailing bits of the IPv6 prefix after the prefix length bits MUST be + set to zero (e.g., if the prefix length is 60, then the remaining 68 + bits MUST be set to zero). + + The HAAA MAY act as a central entity managing prefixes for MNs. In + this case, the HAAA returns to the NAS the prefix allocated to the + MN. The NAS/ASP then delivers the home link prefix to the MN using, + e.g., mechanisms described in [INTEGRATED]. The NAS/ASP MAY propose + to the HAAA a specific prefix to allocate to the MN by including the + MIP6-Home-Link-Prefix AVP in the request message. However, the HAAA + MAY override the prefix allocation hint proposed by the NAS/ASP and + return a different prefix in the response message. + +4.2.5. MIP6-Feature-Vector AVP + + The MIP6-Feature-Vector AVP (AVP Code 124) is of type Unsigned64 and + contains a 64-bit flags field of supported capabilities of the NAS/ + ASP. Sending and receiving the MIP6-Feature-Vector AVP with value 0 + MUST be supported, although that does not provide much guidance about + specific needs of bootstrapping. + + The NAS MAY include this AVP to indicate capabilities of the NAS/ASP + to the Diameter server. For example, the NAS may indicate that a + local HA can be provided. Similarly, the Diameter server MAY include + this AVP to inform the NAS/ASP about which of the NAS/ASP indicated + capabilities are supported or authorized by the ASA/MSA(/MSP). + + The following capabilities are defined in this document: + + + + + + + + + + +Korhonen, et al. Standards Track [Page 8] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + + MIP6_INTEGRATED (0x0000000000000001) + + When this flag is set by the NAS, it means that the Mobile IPv6 + integrated scenario bootstrapping functionality is supported by + the NAS. When this flag is set by the Diameter server, then the + Mobile IPv6 integrated scenario bootstrapping is supported by the + Diameter server. + + LOCAL_HOME_AGENT_ASSIGNMENT (0x0000000000000002) + + When this flag is set in the request message, a local home agent + outside the home realm is requested and may be assigned to the MN. + When this flag is set by the Diameter server in the answer + message, then the assignment of local HAs is authorized by the + Diameter server. + + A local HA may be assigned by the NAS, LAAA, or VAAA depending on + the network architecture and the deployment. + + The following examples show how the LOCAL_HOME_AGENT_ASSIGNMENT + (referred to as LOCAL-bit in the examples) capability and the MIP- + Agent-Info AVP (referred to as HA-Info in the examples) are used to + assign HAs -- either a local HA (L-HA) or a home network HA (H-HA). + Below are examples of request message combinations as seen by the + HAAA: + + LOCAL-bit HA-Info Meaning + + 0 - ASP or [LV]AAA is not able to assign an L-HA. + 0 L-HA Same as above. HA-Info must be ignored. + 1 - ASP or [LV]AAA can/wishes to assign an L-HA. + 1 L-HA Same as above but the ASP or [LV]AAA also + provides a hint of the assigned L-HA. + + The same as above but for answer message combinations as seen by the + NAS: + + LOCAL-bit HA-Info Meaning + + 0 - No HA assignment allowed for HAAA or [LV]AAA. + 0 H-HA L-HA is not allowed. HAAA assigns an H-HA. + 1 - L-HA is allowed. No HAAA- or [LV]AAA-assigned HA. + 1 L-HA L-HA is allowed. [LV]AAA also assigns an L-HA. + 1 H-HA L-HA is allowed. HAAA also assigns an HA. + 1 H-HA L-HA is allowed. HAAA assigns an H-HA and + + L-HA [LV]AAA also assigns an L-HA. + + An NAS should expect to receive multiple MIP6-Agent-Info AVPs. + + + +Korhonen, et al. Standards Track [Page 9] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + +5. Examples + +5.1. Home Agent Assignment by the NAS + + In this scenario, we consider the case where the NAS wishes to + allocate a local HA to the MN. The NAS will also inform the Diameter + server about the HA address it has assigned to the visiting MN (e.g., + 2001:db8:1:c020::1). The Diameter-EAP-Request message, therefore, + has the MIP6-Feature-Vector with the LOCAL_HOME_AGENT_ASSIGNMENT and + the MIP6_INTEGRATED set. The MIP6-Agent-Info AVP contains the MIP- + Home-Agent-Address AVP with the address of the proposed HA. + + Diameter + NAS/VAAA Server + | | + | Diameter-EAP-Request | + | MIP6-Feature-Vector=(LOCAL_HOME_AGENT_ASSIGNMENT | + | | MIP6_INTEGRATED) | + | MIP6-Agent-Info{ | + | MIP-Home-Agent-Address(2001:db8:1:c020::1)} | + | } | + | Auth-Request-Type=AUTHORIZE_AUTHENTICATE | + | EAP-Payload(EAP Start) | + |---------------------------------------------------------------->| + | | + | | + : ...more EAP Request/Response pairs... : + | | + | | + | Diameter-EAP-Answer | + | MIP6-Feature-Vector=(LOCAL_HOME_AGENT_ASSIGNMENT | + | | MIP6_INTEGRATED) | + | Result-Code=DIAMETER_SUCCESS | + | EAP-Payload(EAP Success) | + | EAP-Master-Session-Key | + | (authorization AVPs) | + | ... | + |<----------------------------------------------------------------| + | | + + Figure 2: Home Agent Assignment by the NAS + + Depending on the Diameter server's configuration and the user's + subscription profile, the Diameter server either accepts or rejects + the local HA allocated by the NAS. In our example, the Diameter + server accepts the proposal, and the MIP6-Feature-Vector AVP with + LOCAL_HOME_AGENT_ASSIGNMENT flag (together with the MIP6_INTEGRATED + flag) is set and returned to the NAS. + + + +Korhonen, et al. Standards Track [Page 10] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + +5.2. Home Agent Assignment by the Diameter Server + + In this scenario, we consider the case where the NAS supports the + Diameter MIPv6 integrated scenario as defined in this document, but + does not offer local HA assignment. Hence, the MIP6-Feature-Vector + AVP only has the MIP6_INTEGRATED flag set. The Diameter server + allocates an HA to the mobile node and conveys the address in the + MIP-Home-Agent-Address AVP that is encapsulated in the MIP6-Agent- + Info AVP. Additionally, the MIP6-Feature-Vector AVP has the + MIP6_INTEGRATED flag set. + + Diameter + NAS Server + | | + | Diameter-EAP-Request | + | MIP6-Feature-Vector=(MIP6_INTEGRATED) | + | Auth-Request-Type=AUTHORIZE_AUTHENTICATE | + | EAP-Payload(EAP Start) | + |---------------------------------------------------------------->| + | | + | | + : ...more EAP Request/Response pairs... : + | | + | | + | Diameter-EAP-Answer | + | MIP6-Agent-Info{ | + | MIP-Home-Agent-Address(2001:db8:6000:302::1) | + | } | + | MIP6-Feature-Vector=(MIP6_INTEGRATED) | + | Result-Code=DIAMETER_SUCCESS | + | EAP-Payload(EAP Success) | + | EAP-Master-Session-Key | + | (authorization AVPs) | + | ... | + |<----------------------------------------------------------------| + | | + + Figure 3: Home Agent Assignment by the Diameter Server + +5.3. Home Agent Assignment by the NAS or Diameter Server + + This section shows another message flow for the MIPv6 integrated + scenario bootstrapping where the NAS informs the Diameter server that + it is able to locally assign an HA to the MN. The Diameter server is + able to provide an HA to the MN but also authorizes the assignment of + the local HA. The Diameter server then replies to the NAS with + HA-related bootstrapping information. + + + + +Korhonen, et al. Standards Track [Page 11] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + + Whether the NAS/ASP then offers a locally assigned HA or the + Diameter-server-assigned HA to the MN is, in this example, based on + the local ASP policy. + + Diameter + NAS/VAAA Server + | | + | Diameter-EAP-Request | + | MIP6-Feature-Vector=(LOCAL_HOME_AGENT_ASSIGNMENT | + | | MIP6_INTEGRATED) | + | MIP6-Agent-Info{ | + | MIP-Home-Agent-Address(2001:db8:1:c020::1)} | + | } | + | Auth-Request-Type=AUTHORIZE_AUTHENTICATE | + | EAP-Payload(EAP Start) | + |---------------------------------------------------------------->| + | | + | | + : ...more EAP Request/Response pairs... : + | | + | | + | Diameter-EAP-Answer | + | MIP6-Agent-Info{ | + | MIP-Home-Agent-Address(2001:db8:6000:302::1)} | + | MIP6-Feature-Vector=(LOCAL_HOME_AGENT_ASSIGNMENT | + | | MIP6_INTEGRATED) | + | Result-Code=DIAMETER_SUCCESS | + | EAP-Payload(EAP Success) | + | EAP-Master-Session-Key | + | (authorization AVPs) | + | ... | + |<----------------------------------------------------------------| + | | + + Figure 4: Home Agent Assignment by the NAS or Diameter Server + + If the Diameter server does not allow the MN to use a locally + assigned HA, the Diameter server returns to the MN the MIP6-Feature- + Vector AVP with the LOCAL_HOME_AGENT_ASSIGNMENT bit unset and the HA + address it allocated. + +6. Attribute-Value Pair Occurrence Tables + + Figure 5 lists the MIPv6 bootstrapping NAS-to-HAAA interface AVPs + along with a specification determining how many of each new AVP may + be included in a Diameter command. They may be present in any + Diameter application request and answer commands, where permitted by + the command ABNF. + + + +Korhonen, et al. Standards Track [Page 12] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + + +-----------+ + | Command | + |-----+-----+ + Attribute Name | Req | Ans | + -------------------------------|-----+-----| + MIP6-Agent-Info | 0+ | 0+ | + MIP6-Feature-Vector | 0-1 | 0-1 | + +-----+-----+ + + Figure 5: Generic Request and Answer Commands AVP Table + +7. IANA Considerations + +7.1. Registration of New AVPs + + This specification defines the following AVPs that have been + allocated from a normal Diameter AVP Code space (values >= 256): + + MIP6-Agent-Info is set to 486 + + The following new AVPs are to be allocated from RADIUS Attribute Type + space [RFC2865] so that they are RADIUS backward-compatible (AVP Code + values between 0-255): + + MIP6-Feature-Vector is set to 124 + MIP6-Home-Link-Prefix is set to 125 + +7.2. New Registry: Mobility Capability + + IANA has created a new registry for the Mobility Capability as + described in Section 4.2.5. + + Token | Value | Description + ----------------------------------+---------------------+------------ + MIP6_INTEGRATED | 0x0000000000000001 | [RFC5447] + LOCAL_HOME_AGENT_ASSIGNMENT | 0x0000000000000002 | [RFC5447] + Available for Assignment via IANA | 2^x | + + Allocation rule: Only numeric values that are 2^x (power of two, + where x >= 2) are allowed, based on the allocation policy described + below. + + Following the example policies described in [RFC5226], new values for + the Mobility Capability Registry will be assigned based on the + "Specification Required" policy. No mechanism to mark entries as + "deprecated" is envisioned. + + + + + +Korhonen, et al. Standards Track [Page 13] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + +8. Security Considerations + + The security considerations for the Diameter interaction required to + accomplish the integrated scenario are described in [INTEGRATED]. + Additionally, the security considerations for the Diameter base + protocol [RFC3588], the Diameter NASREQ application [RFC4005], and + the Diameter EAP application (with respect to network access + authentication and the transport of keying material) [RFC4072] are + applicable to this document. Developers should insure that special + attention is paid to configuring the security associations protecting + the messages that enable the global positioning and allocation of + home agents, for instance, as outlined in Section 5. + + Furthermore, the Diameter messages may be transported between the NAS + and the Diameter server via one or more AAA brokers or Diameter + agents (such as proxies). In this case, the AAA communication from + the NAS to the Diameter server relies on the security properties of + the intermediate AAA brokers and Diameter agents. + +9. Acknowledgments + + This document is heavily based on the ongoing work for RADIUS MIPv6 + interaction. Hence, credits go to respective authors for their work + with "RADIUS Mobile IPv6 Support" (November 2008). Furthermore, the + authors of this document would like to thank the authors of "Diameter + Mobile IPv6 Application" (November 2004) -- Franck Le, Basavaraj + Patil, Charles E. Perkins, and Stefano Faccin -- for their work in + the context of MIPv6 Diameter interworking. Their work influenced + this document. Jouni Korhonen would like to thank the Academy of + Finland and TEKES MERCoNe Project for providing funding to work on + this document while he was with TeliaSonera. Julien Bournelle would + like to thank GET/INT since he began to work on this document while + he was in their employ. Authors would also like to acknowledge + Raymond Hsu for his valuable feedback on local HA assignment and + Wolfgang Fritsche for his thorough review. Additionally, we would + like to Domagoj Premec for his review comments. + + Finally, we would like to thank Alper Yegin, Robert Marks, and David + Frascone for their comments at the second WG Last Call. + + + + + + + + + + + + +Korhonen, et al. Standards Track [Page 14] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + +10. References + +10.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, + "Remote Authentication Dial In User Service (RADIUS)", + RFC 2865, June 2000. + + [RFC3588] Calhoun, P., Loughney, J., Guttman, E., Zorn, G., and + J. Arkko, "Diameter Base Protocol", RFC 3588, + September 2003. + + [RFC3775] Johnson, D., Perkins, C., and J. Arkko, "Mobility + Support in IPv6", RFC 3775, June 2004. + + [RFC4004] Calhoun, P., Johansson, T., Perkins, C., Hiller, T., + and P. McCann, "Diameter Mobile IPv4 Application", + RFC 4004, August 2005. + + [RFC4005] Calhoun, P., Zorn, G., Spence, D., and D. Mitton, + "Diameter Network Access Server Application", RFC 4005, + August 2005. + + [RFC4072] Eronen, P., Hiller, T., and G. Zorn, "Diameter + Extensible Authentication Protocol (EAP) Application", + RFC 4072, August 2005. + +10.2. Informative References + + [AAA] Giaretta, G., Guardini, I., Demaria, E., Bournelle, J., + and R. Lopez, "AAA Goals for Mobile IPv6", Work + in Progress, May 2008. + + [DSMIPv6] Solimand, H., "Mobile IPv6 Support for Dual Stack Hosts + and Routers (DSMIPv6)", Work in Progress, + December 2008. + + [INTEGRATED] Chowdhury, K. and A. Yegin, "MIP6-bootstrapping for the + Integrated Scenario", Work in Progress, April 2008. + + [RFC3753] Manner, J. and M. Kojo, "Mobility Related Terminology", + RFC 3753, June 2004. + + + + + + +Korhonen, et al. Standards Track [Page 15] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + + [RFC4640] Patel, A. and G. Giaretta, "Problem Statement for + bootstrapping Mobile IPv6 (MIPv6)", RFC 4640, + September 2006. + + [RFC5026] Giaretta, G., Kempf, J., and V. Devarapalli, "Mobile + IPv6 Bootstrapping in Split Scenario", RFC 5026, + October 2007. + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing + an IANA Considerations Section in RFCs", BCP 26, + RFC 5226, May 2008. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Korhonen, et al. Standards Track [Page 16] + +RFC 5447 Diameter MIPv6 NAS-to-HAAA Interaction February 2009 + + +Authors' Addresses + + Jouni Korhonen (editor) + Nokia Siemens Networks + Linnoitustie 6 + Espoo FIN-02600 + Finland + + EMail: [email protected] + + + Julien Bournelle + Orange Labs + 38-4O rue du general Leclerc + Issy-Les-Moulineaux 92794 + France + + EMail: [email protected] + + + Hannes Tschofenig + Nokia Siemens Networks + Linnoitustie 6 + Espoo 02600 + Finland + + EMail: [email protected] + URI: http://www.tschofenig.priv.at + + + Charles E. Perkins + WiChorus Inc. + 3590 North First St., Suite 300 + San Jose, CA 95134 + US + + EMail: [email protected] + + + Kuntal Chowdhury + Starent Networks + 30 International Place + Tewksbury, MA 01876 + US + + EMail: [email protected] + + + + + +Korhonen, et al. Standards Track [Page 17] + |
