INTERNET DRAFT Pat R. Calhoun Category: Standards Track Sun Microsystems, Inc. Title: draft-calhoun-diameter-res-mgmt-01.txt Nancy Greene Date: May 1998 Nortel DIAMETER Resource Management Extensions Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months. Internet-Drafts may be updated, replaced, or obsoleted by other documents at any time. It is not appropriate to use Internet- Drafts as reference material or to cite them other than as a ``working draft'' or ``work in progress.'' To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). Abstract DIAMETER is a policy protocol used between a client and a server for authentication, authorization and accounting of various services. Examples of such services are for dial-up users (ROAMOPS), RSVP Admission Policies (RAP), FAX Over IP (FAXIP), Voice over IP (SIPTel), Integrated services, etc. This document defines a set of commands which allow DIAMETER servers to maintain session state information. An example of the use of Resource Management would be to limit the number of sessions for a given user. Calhoun expires November 1998 [Page 1] INTERNET DRAFT May 1998 Table of Contents 1.0 Introduction 1.1 Specification of Requirements 1.2 Concept of a session 2.0 Command Codes 2.1 Session-Free-Request 2.2 Session-FreeResponse 2.3 Query-Resource-Request 2.4 Query-Resource-Response 2.5 Resource-Reclaim-Request 3.0 DIAMETER AVPs 3.1 Query-Index 3.2 Resource-Token 4.0 Protocol Definition 4.1 Session Free 4.2 Relinquish Session 4.3 Interaction with Device-Reboot-Indication 4.4 State Resync 5.0 References 6.0 Authors' Addresses 1.0 Introduction Many services requiring Policy Server Support require the server to maintain session state information. This can only be achieved if the protocol has built-in mechanism to allow both the client and the server to resync its state information. A message set is also required to allow the client to inform the server when a session has terminated. An example of such a requirement is in the dial-up PPP world. With the introduction of flat-rate internet access, there has been a surge in fraud that allows a user to provide his username/password pair to other people. The end result is that a single username can have simultaneous concurrent sessions. It is desirable for the Policy Server to maintain a list of the active sessions so it can detect whether a user is attempting fraudulent activities, and restrict the user to a single login. Internet Service Providers have had to implement this functionality using other less-reliable schemes in the past. Unfortunately, those schemes are known to be problematic and therefore a standard method of maintaining state information is desired. The DIAMETER Resource Management extensions are intended to provide Calhoun expires November 1998 [Page 2] INTERNET DRAFT May 1998 the functionality required to have stateful Policy Servers. This document does not specify what resources can be managed by a server since it is service specific, but it does provide the tools required for the services that require it. When reading this document the reader should keep in mind that the authorization of a session by the server is analogous to the allocation of resources. This document does not deal with the allocation of any resources and is simply a complement to the service extension that requires stateful servers. Message sets and the AVPs used for session setup and resource allocation vary depending on the type of service a session is being created for. The general concept of a session is described in this document, and specific message sets for session setup and resource allocation are found in other extension documents, for example, in [2]. 1.1 Specification of Requirements In this document, several words are used to signify the requirements of the specification. These words are often capitalized. MUST This word, or the adjective "required", means that the definition is an absolute requirement of the specification. MUST NOT This phrase means that the definition is an absolute prohibition of the specification. SHOULD This word, or the adjective "recommended", means that there may exist valid reasons in particular circumstances to ignore this item, but the full implications must be understood and carefully weighed before choosing a different course. MAY This word, or the adjective "optional", means that this item is one of an allowed set of alternatives. An implementation which does not include this option MUST be prepared to interoperate with another implementation which does include the option. 1.2 Concept of a session A session defines a thread of Diameter messages. All messages related to a particular session MUST include a Session-Id. (Session-Id is Calhoun expires November 1998 [Page 3] INTERNET DRAFT May 1998 described in [1]). A session can be established by either a client or a server. The Session-Id is assigned by the initiator of the session. Resources can be added to, deleted from, or modified in a session. How this is done for a particular service is described in the relevant extensions document. For example, [2] describes session setup and resource allocation for user authentication and authorization. This document describes the more general functions of querying for information on allocated resources, and freeing a session. 2.0 Command Codes This document defines the following DIAMETER Commands. All DIAMETER implementations supporting this extension MUST support all of the following commands: Command Name Command Code ----------------------------------- Session-Free-Request 266 Session-Free-Response 267 Query-Resource-Request 268 Query-Resource-Response 269 Resource-Reclaim-Request 270 2.1 Session-Free-Request Description The Session-Free-Request message is normally sent by a DIAMETER client to a server, and provides information on specific resources which have been released. The Session-Free-Request message MUST include the Host-IP-Address or the Host-Name as well as the Session-Id AVPs. The Session-Id is used by the server to identify a specific session that was previously authorized. Upon receipt of this message the server MUST free any resources that were previously allocated to the session during the session authorization and respond with the Session-Free-Response. The Session-Free-Request MAY contain the Result-Code AVP if it is a result of a Session-Reclaim-Request. A summary of the Session-Free-Request packet format is shown Calhoun expires November 1998 [Page 4] INTERNET DRAFT May 1998 below. The fields are transmitted from left to right. 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | AVP Flags | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Command Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 256 DIAMETER Command AVP Length The length of this attribute MUST be 12. AVP Flags The flag field MUST have bit one (Mandatory Support) set. Command Code The Command Code field MUST be set to 266 (Session-Free-Request). 2.2 Session-Free-Response Description The Session-Free-Response message is sent by the DIAMETER Server to the client to acknowledge the receipt of the Session-Free- Response message. The Result-Code AVP, which MUST be present in the Session-Free-Response, is used in order to identify whether the Server was able to free the resources associated with the Session-Id. The Host-IP-Address or the Host-Name AVP MUST be present in this message. The following Error Codes are defined for the Session-Free- Response message: DIAMETER_ERROR_ALREADY_FREE 1 The Session Identifier has already been freed. A summary of the Session-Free-Response packet format is shown Calhoun expires November 1998 [Page 5] INTERNET DRAFT May 1998 below. The fields are transmitted from left to right. 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | AVP Flags | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Command Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 256 DIAMETER Command AVP Length The length of this attribute MUST be 12. AVP Flags The flag field MUST have bit one (Mandatory Support) set. Command Code The Command Code field MUST be set to 267 (Session-Free-Response). 2.3 Query-Resource-Request Description The Query-Resource-Request message is sent by a DIAMETER Server to a client. This event MAY occur when a Server has lost its state information and wishes to rebuild the information. However, it is valid for a server to send a request periodically to clients to refresh its state information. The presence of one or more Session-Id AVP in the Query- Resource-Request indicates that the server only wants to receive the Resource-Token for the specified session(s). The initial Query-Resource-Request message MUST contain the Host- IP-Address and the Host-Name AVPs and a Query-Index AVP with a value of zero (see section 4.4 for more info). The Query-Index AVP is used by the client as a placeholder in subsequent Query- Resource-Requests in order to identify which Resource-Token to Calhoun expires November 1998 [Page 6] INTERNET DRAFT May 1998 send to the server. When the client receives a non-zero Query-Index AVP, it MUST include Resource-Tokens beginning at the placeholder associated with the value of the Query-Index AVP. A non-zero Query-Index AVP is sent to the DIAMETER Server in the Query-Resource-Response when the client is unable to include all of the Resource-Tokens within a single response. Once a DIAMETER Server has rebooted or lost its state information for any reason, it is recommended that the Server issue a Query- Resource-Request and receive a valid response from a specific client prior to processing any authorization messages from the client. A summary of the Query-Resource-Request packet format is shown below. The fields are transmitted from left to right. 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | AVP Flags | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Command Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 256 DIAMETER Command AVP Length The length of this attribute MUST be 12. AVP Flags The flag field MUST have bit one (Mandatory Support) set. Command Code The Command Code field MUST be set to 268 (Query-Resource- Request). 2.4 Query-Resource-Response Calhoun expires November 1998 [Page 7] INTERNET DRAFT May 1998 Description Upon receipt of a Query-Resource-Request, each client is responsible to respond with all of the Resource-Tokens for active sessions that were previously allocated by the requesting server. The message MUST include the Query-Index, a Result-Code AVP, a Host-IP-Address or Host-Name AVPs and one or more Resource-Token AVPs. Since more than one Resource-Token AVP may be returned within a Query-Resource-Response, it is likely that the total packet length would exceed the interface's MTU. It is required to make use of the Query-Index AVP in order to request that the server issue a subsequent Query-Resource-Request. The value of the Query-Index MUST be duplicated in the subsequent Query-Resource-Request by the Server in order for the client to know which Resource-Token to start sending in the following response. If the client was able to fit all of the Resource-Tokens within the Query-Resource-Response it MUST include a Query-Index AVP with a zero value. A zero Query-Index will inform the Server that it SHOULD NOT issue another Query-Resource-Request. A summary of the Query-Resource-Response packet format is shown below. The fields are transmitted from left to right. 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | AVP Flags | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Command Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 256 DIAMETER Command AVP Length The length of this attribute MUST be 12. AVP Flags The flag field MUST have bit one (Mandatory Support) set. Calhoun expires November 1998 [Page 8] INTERNET DRAFT May 1998 Command Code The Command Code field MUST be set to 269 (Query-Resource- Response). 2.5 Session-Reclaim-Request Description The Session-Reclaim-Request message is sent by the DIAMETER Server to the client to request that a previously authorized session be freed immediately. This allows the server to free used resources on the client without any manual intervention. The Session-Reclaim-Request message MUST include a Host-IP-Address and the Host-Name AVP and the Session-Id AVP that was used during the session's authorization phase. When a DIAMETER client receives this message it MUST responds with a Session-Free-Request message. A summary of the Resource-Reclaim-Request packet format is shown below. The fields are transmitted from left to right. 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | AVP Flags | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Command Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 256 DIAMETER Command AVP Length The length of this attribute MUST be 12. AVP Flags The flag field MUST have bit one (Mandatory Support) set. Command Code Calhoun expires November 1998 [Page 9] INTERNET DRAFT May 1998 The Command Code field MUST be set to 270 (Query-Reclaim-Request). 3.0 DIAMETER AVPs This section will define the mandatory AVPs which MUST be supported by all DIAMETER implementations supporting this extension. The following AVPs are defined in this document: Attribute Name Attribute Code ----------------------------------- Query-Index 290 Resource-Token 291 3.1 Query-Index Description This attribute is used in conjunction with the Resource Query mechanism and allows the client to exchange resource information through more than one message exchange. In the initial Query-Resource-Request, this attribute MUST be present with a value of zero. Upon receipt of a Resource Query Response command, the DIAMETER server must check if the attribute is still set to zero. If the value is a non-zero, the DIAMETER server MUST return a Query-Resource-Request with a Query-Index value equal to the value which was set in the response. Upon receipt of a zero, the DIAMETER Server MUST assume that this is the last message exchange. 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | AVP Flags | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Integer32 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ AVP Code 290 Query-Index AVP Length The length of this attribute MUST be at least 12. Calhoun expires November 1998 [Page 10] INTERNET DRAFT May 1998 AVP Flags The flag field MUST have bit one (Mandatory Support) set. Integer32 The Integer32 field contains a value that has local significance to client in order to identify which Resource-Token to send in the subsequent Query-Resource-Request. 3.2 Resource-Token Description The Resource-Token AVP is returned by the DIAMETER Server to the client during authorization (or session setup). The Resource-Token is subsequently used during the Query-Resource-Response in order to hand the Server with enough information to rebuild its state information. The data portion of this AVP includes AVPs and at a minimum MUST include the Session-Id AVP, the Host-IP-Address or Host-Name AVP and the Service-Id. Each service MUST define what AVPs must be included in the Resource-Token in order for the Resource Management extension to work for the specific service. It is likely that more than one of these attributes exist in a Query-Resource-Response. 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | AVP Length | AVP Flags | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Data ... +-+-+-+-+-+-+-+-+ AVP Code 291 Resource-Token AVP Length The length of this attribute MUST be at least 9. Calhoun expires November 1998 [Page 11] INTERNET DRAFT May 1998 AVP Flags The flag field MUST have bit one (Mandatory Support) set. Data The Data field contains the Resource-Token that was returned by the DIAMETER Server during the authorization phase. 4.0 Protocol Definition This section will outline how the DIAMETER Resource Management Extension can be used. 4.1 Session Free Upon session termination, a Session-Free-Request message is issue by the client to the DIAMETER Server and MUST contain the Session-Id AVP that was used during the authorization phase of the session. The format of the Session-Free-Request message is as follows: ::= The format of the Session-Free-Response message is as follows: ::= 4.2 Relinquish Session When the server wants the client to relinquish an existing session, the Server issues a Session-Reclaim-Request to the client. The request MUST contain the Session-Id AVP that was used during the authorization phase of the session. The client MUST respond with a Session-Free-Request message. The request MUST contain the Result-Code when it is a response to a Session-Reclaim-Request to indicate whether it was able to free the requested session. The Server MUST respond with the Session-Free- Response. DIAMETER Server DIAMETER Client Calhoun expires November 1998 [Page 12] INTERNET DRAFT May 1998 --------------- --------------- Session-Reclaim-Request --> <-- Session-Free-Request (Result = 0) Session-Free-Response (Result = 0) --> The format of the Session-Reclaim-Request message is as follows: Session-Reclaim-Request ::= In the roaming scenario the Session-Reclaim-Request message is problematic since it is difficult to identify the target client's proxy chain. This can be achieved by including the Host Name of the client that was found in the authorization request within the Host- Name AVP. 4.3 Interaction with Device-Reboot-Indication When a DIAMETER Server receives a Device-Reboot-Indication it MUST assume that all resources currently allocated to the rebooted client MUST be freed. 4.4 State Resync The DIAMETER Server requires a flag in the client database in order to identify whether the client has responded to the Query-Resource- Request. Upon receipt of an Authorization message that requires Resource Management, the Server MUST issue a Query-Resource-Request if the client has not previously responded to such requests. A client MUST respond to a Query-Resource-Request with all of the active Resource-Tokens that have previously been allocated by the requesting server. Since the number of active Resource-Tokens MAY be larger than the interface's MTU, it is required to make use of the Query-Index AVP. The following is an example of an exchange between a Server and a Client that has 26 Resource-Tokens which is too many to fit within a single response. DIAMETER Server DIAMETER Client --------------- --------------- Query-Resource-Request (Index = 0) --> <-- Query-Resource-Response (Index = 10) Query-Resource-Request (Index = 10) --> Calhoun expires November 1998 [Page 13] INTERNET DRAFT May 1998 <-- Query-Resource-Response (Index = 20) Query-Resource-Request (Index = 20) --> <-- Query-Resource-Response (Index = 0) In the above scenario, the Server issues the initial Query-Resource- Request with a zero Query-Index. The client responds but since it can only fit Resource-Tokens 1 through 9, it sets the Query-Index to 10 in the Query-Resource-Response. Upon receipt of the response the server processes the message and issues another Query-Resource-Request with the Query-Index value set to 10. The client, upon receipt of the request, knows that it needs to include the Resource-Tokens starting at 10. Again, since the client can only include the Resource-Tokens up to 19, it sets the Query-Index to 20. The Server issues another Query-Resource-Request with the Query-Index set to 20. At this point the client can fit the remaining Resource- Tokens (20 through 26) and therefore sets the Query-Index to zero to indicate that it has sent all of it's active Resource-Tokens. The format of the Query-Resource-Request is as follows: ::= [] [] [] The format of the Query-Resource-Response message is as follows: ::= [] [] [] 5.0 References [1] Calhoun, Rubens, "DIAMETER", Internet-Draft, draft-calhoun-diameter-03.txt, May 1998. [2] Calhoun, Bulley, "DIAMETER Autentication Extensions", Internet-Draft, draft-calhoun-diameter-auth-03.txt, May 1998. [3] Calhoun, Zorn, Pan, "DIAMETER Framework", Internet- Draft, draft-calhoun-diameter-framework-00.txt, May 1998 Calhoun expires November 1998 [Page 14] INTERNET DRAFT May 1998 6.0 Authors' Addresses Questions about this memo can be directed to: Pat R. Calhoun Technology Development Sun Microsystems, Inc. 15 Network Circle Menlo Park, California, 94025 USA Phone: 1-650-786-7733 Fax: 1-650-786-6445 E-mail: pcalhoun@eng.sun.com Nancy Greene Public Data Networks Nortel (Northern Telecom) PO Box 3511 Station C Ottawa, Ontario K1Y 4H7 Canada Phone: 1-613-763-9789 Fax: 1-613-763-8904 E-mail: ngreene@nortel.ca Calhoun expires November 1998 [Page 15]