Internet Draft Joe Zebarth Document: draft-zebarth-sipping-dtmfad-00.txt Nortel Networks Expires: April 2004 October 2003 A Session Initiation Protocol (SIP) Event Package for DTMF Event Monitoring Status of this Memo This document is an Internet-Draft and is subject to all provisions of Section 10 of RFC 2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract This document defines a Session Initiation Protocol (SIP) event package "DTMFAD" to allow the use of SUBSCRIBE and NOTIFY to collect DTMF signals. This package is required to implement Committee T1 Technical Report T1.TR.82-2003. The "DTMFAD" event package requires the definition of two new Event header field parameters. This package also requires the use of a new MIME type, application/DTMF-event, to allow for the transfer of DTMF data in the NOTIFY body. Registration of this MIME type is also provided in this document. This document has been produced, on behalf of Committee T1, as part of the IANA registration process. Zebarth Expires - April 2004 [Page 1] SIP Event Package for DTMF Event Monitoring October 2003 Table of Contents 1 Introduction ........................................ 3 2 Terminology ......................................... 3 3 Usage Scenarios ..................................... 3 4 Package Definition .................................. 3 5 Example Call Flows .................................. 8 6 Security Considerations ............................. 10 7 IANA Considerations ................................. 10 8 References .......................................... 13 9 Acknowledgements .................................... 14 10 AuthorÆs Addresses ................................. 14 Zebarth Expires - April 2004 [Page 2] SIP Event Package for DTMF Event Monitoring October 2003 1 Introduction This document defines a Session Initiation Protocol (SIP) event package, DTMFAD, which is needed to implement Committee T1 Technical Report T1.TR.82-2003 [5]. The DTMFAD event package requires the definition of two new Event header field parameters thereby allowing use of SUBSCRIBE to request DTMF monitoring and NOTIFY bodies to return detected digits. This package also requires the use of a new MIME type, which is also specified in this document, to allow for the transfer of data in the NOTIFY body. This document has been produced, on behalf of Committee T1, as part of the IANA registration process as required by RFC 3427. 2 Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [3] and indicate requirement levels for compliant implementations. 3 Usage Scenarios This event package MAY be used to allow an application server (subscriber) to request DTMF monitoring and notification of detection from a receiving agent (notifier) in order to enable a caller- initiated re-origination request while a call is in progress. There are other possible applications of this event package. 4 Package Definition This section provides the detail necessary to specify the event package DTMFAD as required by Section 4 of [2]. 4.1 Event Package Name The name of this package is "DTMFAD". As allowed by [2], this value appears in the Event header present in SUBSCRIBE and NOTIFY requests. Example: Event: DTMFAD;duration=][;events=][;maxrate=][;id=] 4.2 Event Package Parameters Three new event header field parameters are defined for this event package: "duration", "event-set", and "maxrate". They are defined as follows: Zebarth Expires - April 2004 [Page 3] SIP Event Package for DTMF Event Monitoring October 2003 duration "duration" is an optional parameter that defines the duration of a continuous DTMF tone (in milliseconds) that will cause the notifier to send a NOTIFY request before detecting the end of the tone. A NOTIFY request is always sent when the notifier detects the end of the key press, but additional NOTIFY requests will be sent during the key press if the tone persists for the value of "duration" beyond the time that the previous NOTIFY was sent. If the "duration" parameter is omitted, event notification occurs only when the end of the DTMF tone is detected. Note: for long key presses, combined with short values of "duration", a single DTMF digit can result in many NOTIFY requests. With calling card re-origination requests, in particular, the Application Server (AS) cannot provide a prompt for a new destination number or begin collecting digits if the caller is still pressing a DTMF key, so the AS must wait for completion of the tone. Therefore, it is likely that sending NOTIFY requests at the termination of each detected DTMF digit is preferable to sending many NOTIFY requests for each digit. As a result, it is RECOMMENDED that the AS not include the "duration" parameter. event-set "event-set" is an optional parameter defining the set of events that are to be detected by the notifier. For DTMF tones, the set includes: digits 0 through 9 (decimal 0-9); the * key (hexadecimal a); the # key (hexadecimal b); and special digits A through D (hexadecimal c-f). As described in Section 4.7, the notifier will report each detected DTMF digit as a discrete event and it is the responsibility of the subscriber to reconstruct the sequence of digits into a string. As a result, the subscriber SHOULD request reporting of all DTMF digits, not just one or two specific DTMF values. The "event-set" parameter is optional, and if not included in the SUBSCRIBE request will be assumed to be the default set of hexadecimal values 0-f (i.e. all DTMF digits). maxrate "maxrate" is an optional parameter defining a maximum number of NOTIFY transactions per minute initiated to report DTMF events. The notifier MUST NOT exceed this limit in any one minute period, but MAY send notifications in more rapid bursts over shorter periods. If "maxrate" is omitted, the notifier MUST limit reporting to forty (40) NOTIFY transactions per minute. "maxrate" SHOULD NOT exceed 60. Zebarth Expires - April 2004 [Page 4] SIP Event Package for DTMF Event Monitoring October 2003 If the reporting rate limit causes a queue of unreported events to build up, the notifier MAY discard some or all of the excess events. If the notifier can choose which events to discard, the notifier SHOULD discard notifications of uncompleted DTMF events resulting from the presence of the "duration" parameter before discarding notifications of completed DTMF events. See also the discussion of maximum reporting rate in Section 4.11 below. 4.2.1 Syntax From the ABNF in RFC 3325 [1]: event-param = generic-param / ( "id" EQUAL token ) This document extends the definition of event-param as follows: event-param =/ dur-param / evset-param / maxrate-param dur-param = "duration" EQUAL 2*4DIGIT ; duration (ms) triggering an early NOTIFY evset-param = "event-set" = 1*16( DIGIT / %x61-66 ) ; set of digit events to be detected, 0-9 and "a" through "f" ; at most one instance of each maxrate-param = "maxrate" EQUAL 1*2DIGIT ; maximum number of events to be reported per minute 4.3 SUBSCRIBE Bodies The DTMFAD event package does not use a SUBSCRIBE body. 4.4 Subscription Duration The default value for subscription duration is 3600 seconds. The subscriber MAY include an Expires header in the SUBSCRIBE request asking for a different duration. 4.5 NOTIFY Bodies The package makes provision for the use of one NOTIFY body type, only for the reporting of DTMF events. The MIME type application/DTMF- event has been defined for this purpose; see Section 7.2. No body is specified in this package for the initial NOTIFY request indicating that the subscription has been accepted, or for a NOTIFY request indicating a subscription state change. Zebarth Expires - April 2004 [Page 5] SIP Event Package for DTMF Event Monitoring October 2003 4.6 Subscriber Generation of SUBSCRIBE Requests The subscriber generates a SUBSCRIBE request in accordance with RFC 3265. This request MUST include an Event header field specifying the DTMFAD event package. The header field MAY include the duration, event-set, and/or maxrate parameters, although as discussed in Section 4.2, the use of the duration parameter is NOT RECOMMENDED. The SUBSCRIBE request SHOULD include the Accept header field, indicating acceptance of the application/DTMF-event MIME type. 4.7 Notifier Processing of SUBSCRIBE Requests If the notifier finds that the SUBSCRIBE invokes the DTMFAD package, it MUST check for the presence of the duration, event-set, and maxrate parameters. If these parameters are present, the notifier MAY accept them or MAY modify them as described in Section 4.8.1. If any of these parameters are absent, the notifier MUST assume that the default value as specified in Section 4.2 was received. If an Accept header is not present in the SUBSCRIBE request, the receiving agent MUST assume that the subscriber will accept a MIME type of application/DTMF-event as defined in Section 7.2. If the Accept header field is present but does not specify the application/DTMF-event MIME type, the notifier MUST reject the subscription using a 406 Not Acceptable response. 4.8 Notifier Generation of NOTIFY Requests The notifier MUST generate a NOTIFY request: - immediately upon receipt of a SUBSCRIBE request - upon a state change, e.g. to confirm a refresh, to confirm a cancellation requested by the subscriber, or to report cancellation triggered at the point of detection. - to report a DTMF event. 4.8.1 NOTIFY Upon Receipt of SUBSCRIBE Request [1] requires that a NOTIFY be generated to indicate the state of a subscription when the SUBSCRIBE was given a 200 or 202 final response. For the DTMFAD package, this NOTIFY request MUST include an Event header field indicating the DTMFAD package and possibly including the duration, event-set, and maxrate parameters as follows: The duration parameter MUST be present if it was present in the SUBSCRIBE request. Its value in the NOTIFY indicates the duration Zebarth Expires - April 2004 [Page 6] SIP Event Package for DTMF Event Monitoring October 2003 the notifier is prepared to use for early DTMF event reporting. The value returned in the NOTIFY MAY be larger than the value received in the SUBSCRIBE, if the notifier is unable or unwilling to support the requested value. The value in the NOTIFY MUST be zero (0), if the notifier is unwilling to report DTMF events until they have ended. The event-set parameter MUST be present if it was present in the SUBSCRIBE request, and must have the same content. The maxrate parameter MUST always be present. It MAY be smaller than the value provided in the SUBSCRIBE request, but MUST NOT be larger. 4.8.2 NOTIFY Upon Change of Subscription State The Event header field for a NOTIFY generated as a result of a change in subscription state MUST be identical to that included in the initial NOTIFY, as described above. 4.8.3 NOTIFY To Report DTMF Events A DTMF event is recognized each time the end of a DTMF tone within the event set is detected. In addition, if a non-zero value of the duration parameter was returned in the confirming NOTIFY as described in Section 4.8.1, a DTMF event is recognized whenever a tone within the event set has a cumulative duration equal to an integer multiple of the value of the duration parameter. Subject to the deletion of queued detected events as described in Sections 4.2 and 4.11, a NOTIFY MUST be sent for each detected event, in the order in which the events were detected. A NOTIFY reporting a DTMF event MUST contain an Event header field identical to the one sent in the initial NOTIFY. It MUST also contain a body of type application/DTMF-event, reporting the type of DTMF event detected, its cumulative duration, its volume, and whether it has completed. Because the order of DTMF events is significant, and to provide a mechanism for throttling of bursts of events, the notifier MUST NOT initiate a NOTIFY transaction to report a DTMF event until the final response has been received for the previous DTMF event reporting transaction. As a result of this restriction and of the application of the maxrate parameter, DTMF events may be queued for reporting. If, as a result of a non-zero duration parameter value, two events are queued relating to the same occurrence of a DTMF tone, the notifier SHOULD discard the earlier event rather than report it. Zebarth Expires - April 2004 [Page 7] SIP Event Package for DTMF Event Monitoring October 2003 4.9 Subscriber Processing of NOTIFY Requests If the subscriber finds that the values of the parameters returned in the initial NOTIFY request are unacceptable, it MAY terminate the subscription. Aside from this, the DTMFAD package does not require any specific processing of NOTIFY requests. 4.10 Handling of Forked Requests This package does not allow forked SUBSCRIBE requests to install multiple subscriptions with the same notifier. 4.11 Rate of Notifications The DTMFAD package provides two throttling mechanisms for the reporting of DTMF events. The first one is explicit control by the maxrate parameter, as described in Section 4.2. The second is the implicit throttling provided by the requirement that each report be acknowledged before the next is sent, as described in Section 4.8.3. The maxrate control is deliberately set up to allow for short-term bursts, because of the bursty nature of DTMF input. Thus the two controls are complementary. 4.12 State Agents State agents have no role in the handling of this package. 5 Example Call Flows This section provides an example call flow, shown in Figure 3. 5.1 Example Call Flow An example call flow is shown in Figure 1. Subscriber Notifier | | | F1 SUBSCRIBE | |----------------------->| | F2 200 OK | |<-----------------------| | F3 NOTIFY | (Initial subscription state |<-----------------------| notification, see Section 4.8.1 | F4 200 OK | |----------------------->| | F5 NOTIFY | (First notification of DTMF |<-----------------------| event, see Section 4.8.3) Zebarth Expires - April 2004 [Page 8] SIP Event Package for DTMF Event Monitoring October 2003 | F6 200 OK | |----------------------->| | . | | . | (Continue until enough digits | . | received) | FX SUBSCRIBE | (Subscribe has expire value of 0) |----------------------->| | FX+1 200 OK | (Notifier terminates subscription) |<-----------------------| | FX+2 NOTIFY | (Notification of subscription |<-----------------------| state change, see Section 4.8.2 | FX+3 200 OK | |----------------------->| Figure 1 5.2 Example Messages Example messages for messages F1, F3, F5 and FX+2 in Figure 1 are provided in the following sections. 5.2.1 Example Message F1 The following is an example of a SUBSCRIBE request to initiate a new subscription SUBSCRIBE sips:+16135551212@nof.biloxi.example.com;user=phone SIP/2.0 Via: SIP/2.0/TLS as.biloxi.example.com:5061;branch=z9hG4bK74bf Max-Forwards: 70 Call-ID: rt4353gs2egg@as.biloxi.example.com To: sips:+16135551212@nof.biloxi.example.com;user=phone From: ;tag=8675309 CSeq: 1 SUBSCRIBE Event: DTMFAD Contact: Accept: application/dtmf-event Content-Length: 0 5.2.2 Example Message F3 The following is an example of a NOTIFY request which acknowledges a change in state of a subscription. This NOTIFY request is an example response to a SUBSCRIBE request such shown as an example in 5.2.1 above. NOTIFY sips:+16135551212@as.biloxi.example.com;user=phone SIP/2.0 Via: SIP/2.0/TLS nof.biloxi.example.com:5061;branch=z9hG4bK74bf Zebarth Expires - April 2004 [Page 9] SIP Event Package for DTMF Event Monitoring October 2003 Max-Forwards: 70 Call-ID: rt4353gs2egg@as.biloxi.example.com To: ;tag=8675309 From: ;tag=5734 CSeq: 1 NOTIFY Event: DTMFAD;maxrate=60 Subscription-State: active;expires=3600 Contact: sips:+16135551212@nof.biloxi.example.com;user=phone Content-Length: 0 5.2.4 Example Message F5 The following is an example of a NOTIFY request which provides notification of a DTMF event. NOTIFY sips:+16135551212@as.biloxi.example.com;user=phone SIP/2.0 Via: SIP/2.0/TLS nof.biloxi.example.com:5061;branch=z9hG4bK74bf Max-Forwards: 70 Call-ID: rt4353gs2egg@as.biloxi.example.com To: ;tag=8675309 From: ;tag=5734 CSeq: 2 NOTIFY Event: DTMFAD;maxrate=60 Subscription-State: active;expires=3580 Contact: sips:+16135551212@nof.biloxi.example.com;user=phoneContent- Type: application/DTMF-event MIME Content-Length: 12 09 8f 00 61 5.2.4 Example FX+2 The following is an example of a NOTIFY request which is issued in response to a cancellation request by the subscriber NOTIFY sips:+16135551212@as.biloxi.example.com;user=phone SIP/2.0 Via: SIP/2.0/TLS nof.biloxi.example.com:5061;branch=z9hG4bK74bf Max-Forwards: 70 Call-ID: rt4353gs2egg@as.biloxi.example.com To: ;tag=8675309 From: ;tag=5734 CSeq: xx NOTIFY Event: DTMFAD;maxrate=60 Subscription-State: terminated;expires=0 Contact: sips:+16135551212@nof.biloxi.example.com;user=phone Content-Length: 0 Zebarth Expires - April 2004 [Page 10] SIP Event Package for DTMF Event Monitoring October 2003 6 Security Considerations Security considerations for SIP event packages are discussed in RFC 3265 [2], and those considerations apply here. A special consideration applying to the DTMFAD package is to ensure that a caller playing with DTMF keys does not take down the network. Thus event throttling is very important. Section 4.11 points out the measures provided in this package for event throttling. 7 IANA Considerations This document registers a new SIP Event Package ôDTMFADö and a new MIME type ômessage/DTMF-eventö. 7.1 SIP Event Package Registration Package name: DTMFAD Type: package Contact: Joe Zebarth Published Specification: RFC XXXX (Note to RFC Editor: Please fill in XXXX with the RFC number of this specification). 7.2 application/DTMF-event MIME Registration MIME media type name: application MIME subtype name: DTMF-event Mandatory parameters: none Optional parameters: none. Encoding considerations: encoding scheme is binary. The notifier shall encode the DTMF-event as four octets as shown below. 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | event |E|R| volume | duration | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ T h e o c d i g n o f t h s e e c o t e s t S H A L L b eencoded as follows: Zebarth Expires - April 2004 [Page 11] SIP Event Package for DTMF Event Monitoring October 2003 Event field: identifies the DTMF event detected by the notifier. The following table shows the encoding of each of the sixteen possible events. Event encoding (hexadecimal) ________________________ 0 00 1 01 2 02 3 03 4 04 5 05 6 06 7 07 8 08 9 09 * 0a # 0b A 0c B 0d C 0e D 0f Table 1: DTMF named events E field: If set to a value of ôoneö, the "end" bit indicates that this packet contains the end of the event and thus the duration parameter reported in this event measures the complete duration of the event. R field: This field is reserved for future use. The notifier MUST set it to ôzeroö and the subscriber MUST ignore it. volume field: For DTMF digits this field describes the power level of the tone, expressed in dBm0 after dropping the sign. Power levels range from 0 to -63 dBm0. Thus, larger values denote lower volume. The range of valid DTMF is from 0 to -36 dBm0 (must accept); lower than -55 dBm0 must be rejected (TR-TSY-000181, ITU-T Q.24A). Since it is expected that applications will not use volume as a criterion of acceptance, the notifier MAY set the level to a consistent arbitrary value, e.g. 15, when the DTMF tone level is between 0 to 36. duration field: Duration of this digit event in milliseconds (Since the beginning of this digit event). Thus, this field is sufficient to express event durations of up to approximately 65.535 seconds. Zebarth Expires - April 2004 [Page 12] SIP Event Package for DTMF Event Monitoring October 2003 Security considerations: See Section 6 of this specification. Interoperability considerations: none Published specification: This document Applications which use this media type: This event type is designed for Pre-Paid Calling Card implementations. Additional Information: none Magic Number: none File Extension: not appropriate Macintosh file type code: not appropriate Personal and email address for further information: Joe Zebarth, Intended usage: COMMON Author/Change controller: The IETF 8 References 8.1 Normative References [1] J. Rosenberg, H. Schulzrinne, G. Camarillo, A. Johnston, J. Peterson, R. Sparks, M. Handley, and E. Schooler, "SIP: session initiation protocol," RFC 3261, Internet Engineering Task Force, June 2002. [2] A. B. Roach, "Session initiation protocol (sip)-specific event notification," RFC 3265, Internet Engineering Task Force, June 2002. [3] S. Bradner, "Key words for use in RFCs to indicate requirement levels," RFC 2119, Internet Engineering Task Force, March 1997. [4] N.Freed and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, Internet Engineering Task Force, November 1996 [5] ôSIP Network Operators Implementers Guide for Pre-Paid Calling Card, with DTMF Detection at the PSTN-IP Gatewayö Committee T1.TR.82-2003 Zebarth Expires - April 2004 [Page 13] SIP Event Package for DTMF Event Monitoring October 2003 [6] D. Crocker and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, Internet Engineering Task Force, November 1997. 9 Acknowledgements Martin Dolly mdolly@att.com Robert Pugh pughrc@nortelnetworks.com Jim Walmsley jwalmsley@sonusnet.com Fidencio Chaidez fchaidez@lucent.com We thank Tom Taylor for his support. 10 Author's Addresses Joe Zebarth T1S1.7 Vice Chair Nortel Networks PO Box 3511, Station C, Ottawa, Ontario, Canada K1Y 4H7 Email: zebarth@nortelnetworks.com Zebarth Expires - April 2004 [Page 14]