SIPPING E. Burger Internet-Draft SnowShore Networks, Inc. Expires: November 15, 2004 M. Dolly AT&T Labs May 17, 2004 A Session Initiation Protocol (SIP) Event Package for Key Press Stimulus (KPML) draft-ietf-sipping-kpml-03 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on November 15, 2004. Copyright Notice Copyright (C) The Internet Society (2004). All Rights Reserved. Abstract The Key Press Stimulus Event Package is a component of the Applications Interaction Framework for the Session Initiation Protocol (SIP). The event package defines a Key Press Markup Language (KPML) that describes filter specifications for reporting key presses entered at a presentation-free user interface SIP User Agent (UA). The scope of this package is for collecting supplemental key presses or mid-call key presses (triggers). We recommend using VoiceXML or MSCML, as described in the Applications Interaction Framework, for building interactive voice response applications. Burger & Dolly Expires November 15, 2004 [Page 1] Internet-Draft KPML May 2004 Conventions used in this document RFC2119 [1] provides the interpretations for the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" found in this document. The Application Interaction Framework [9] provides the interpretations for the terms "User Device", "SIP Application", and "User Input". This document uses the term "Application" and "Requesting Application" interchangeably with "SIP Application". The Application Interaction Framework discusses User Device Proxies. A common instantiation of a User Device Proxy is a Public-Switched Telephone Network (PSTN) gateway. Because the normative behavior of a presentation-free user interface is identical for a presentation-free SIP User Agent and a presentation-free User Device Proxy, this document uses "User Device" for both cases. Burger & Dolly Expires November 15, 2004 [Page 2] Internet-Draft KPML May 2004 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Key Press Stimulus Operation . . . . . . . . . . . . . . . . . 5 2.1 Model . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2 Stream to Monitor . . . . . . . . . . . . . . . . . . . . 7 2.3 Operation . . . . . . . . . . . . . . . . . . . . . . . . 8 3. Event Package Operation . . . . . . . . . . . . . . . . . . . 9 3.1 Event Package Name . . . . . . . . . . . . . . . . . . . . 9 3.2 Event Package Parameters . . . . . . . . . . . . . . . . . 9 3.3 SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 10 3.4 Subscription Duration . . . . . . . . . . . . . . . . . . 11 3.5 NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 11 3.6 Notifier Processing of SUBSCRIBE Requests . . . . . . . . 11 3.7 Notifier Generation of NOTIFY Requests . . . . . . . . . . 13 3.7.1 SIP Protocol-Generated . . . . . . . . . . . . . . . . 13 3.7.2 Match . . . . . . . . . . . . . . . . . . . . . . . . 13 3.7.3 Inter-Digit Timeout No Match . . . . . . . . . . . . . 13 3.7.4 Dialog Terminated . . . . . . . . . . . . . . . . . . 14 3.7.5 No Call Leg . . . . . . . . . . . . . . . . . . . . . 14 3.7.6 Bad Document . . . . . . . . . . . . . . . . . . . . . 14 3.7.7 One-Shot vs. Persistent Requests . . . . . . . . . . . 15 3.8 Subscriber Processing of NOTIFY Requests . . . . . . . . . 15 3.8.1 No KPML Body . . . . . . . . . . . . . . . . . . . . . 15 3.8.2 KPML Body . . . . . . . . . . . . . . . . . . . . . . 15 3.9 Handling of Forked Requests . . . . . . . . . . . . . . . 16 3.10 Rate of Notifications . . . . . . . . . . . . . . . . . . 16 3.11 State Agents . . . . . . . . . . . . . . . . . . . . . . . 16 4. Message Format - KPML . . . . . . . . . . . . . . . . . . . . 16 4.1 KPML Request . . . . . . . . . . . . . . . . . . . . . . . 16 4.1.1 User Input Buffer Behavior . . . . . . . . . . . . . . 17 4.1.2 Pattern Matching . . . . . . . . . . . . . . . . . . . 18 4.1.3 Digit Suppression . . . . . . . . . . . . . . . . . . 22 4.1.4 One-Shot and Persistent Triggers . . . . . . . . . . . 23 4.1.5 Multiple Patterns . . . . . . . . . . . . . . . . . . 24 4.1.6 Monitoring Direction . . . . . . . . . . . . . . . . . 24 4.1.7 Multiple, Simultaneous Subscriptions . . . . . . . . . 24 4.2 KPML Reports . . . . . . . . . . . . . . . . . . . . . . . 25 4.2.1 Pattern Match Reports . . . . . . . . . . . . . . . . 25 4.2.2 KPML No Match Reports . . . . . . . . . . . . . . . . 26 5. DRegex Syntax . . . . . . . . . . . . . . . . . . . . . . . . 27 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 29 6.1 DRegex . . . . . . . . . . . . . . . . . . . . . . . . . . 29 6.2 KPML . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 7. Enumeration of KPML Status Codes . . . . . . . . . . . . . . . 33 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 8.1 MIME Media Type application/kpml+xml . . . . . . . . . . . 34 8.2 URN Sub-Namespace Registration for urn:ietf:xml:ns:kpml . 34 Burger & Dolly Expires November 15, 2004 [Page 3] Internet-Draft KPML May 2004 8.3 KPML Schema Registration . . . . . . . . . . . . . . . . . 35 9. Security Considerations . . . . . . . . . . . . . . . . . . . 35 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 36 10.1 Monitoring for Octothorpe . . . . . . . . . . . . . . . . 36 10.2 Dial String Collection . . . . . . . . . . . . . . . . . . 36 10.3 Interactive Digit Collection . . . . . . . . . . . . . . . 37 11. Call Flow Example . . . . . . . . . . . . . . . . . . . . . 38 11.1 INVITE-Initiated Dialog . . . . . . . . . . . . . . . . . 38 11.2 Third-Party Subscription . . . . . . . . . . . . . . . . . 43 11.3 Remote-End Monitoring . . . . . . . . . . . . . . . . . . 44 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 12.1 Normative References . . . . . . . . . . . . . . . . . . . . 44 12.2 Informative References . . . . . . . . . . . . . . . . . . . 44 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 46 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 46 B. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 46 Intellectual Property and Copyright Statements . . . . . . . . 48 Burger & Dolly Expires November 15, 2004 [Page 4] Internet-Draft KPML May 2004 1. Introduction This document describes the Key Press Stimulus Event Package. The Key Press Stimulus Package is a SIP Event Notification Package [2] that uses the SUBSCRIBE and NOTIFY methods of SIP. The subscription filter and notification report bodies use the Keypad Markup Language, KPML. KPML is a markup [10] that enables presentation-free user interfaces as described in the Application Interaction Framework [9]. In particular, KPML enables "dumb phones" and gateways to dumb phones to report user key-press events. Colloquially, this mechanism provides for "digit reporting" or "Dual-Tone Multi-Frequency (DTMF) reporting." A goal of KPML is to fit in an extremely small memory and processing footprint. Note KPML has a corresponding lack of functionality. For those applications that require more functionality, please refer to VoiceXML [11] and MSCML [12]. The name of the markup, KPML, reflects its legacy support role. The public switched telephony network (PSTN) accomplished end-to-end signaling by transporting DTMF tones in the bearer channel. This is in-band signaling. Voice-over-IP networks transport in-band signaling with actual DTMF waveforms or RFC2833 [13] packets. In RFC2833, the signaling application inserts RFC2833 named signal packets as well as or instead of generating tones in the media path. The receiving application gets the signal information in the media stream. RFC2833 correlates the time the end user pressed a digit with the user's media. However, out-of-band signaling methods, as are appropriate for User Device to application signaling, do not need millisecond accuracy. On the other hand, they do need reliability, which RFC2833 does not provide. An interested application could request notifications of every key press. However, many of the use cases for such signaling has the application interested in only one or a few keystrokes. Thus we need a mechanism for specifying to the User Device what stimulus the application would like notification of. 2. Key Press Stimulus Operation 2.1 Model The Key Press Stimulus reporting model is that key presses, or detected digits, are events at the User Device. The subscription Burger & Dolly Expires November 15, 2004 [Page 5] Internet-Draft KPML May 2004 installs an event filter. That event filter specifies the User Input strings, which, if matched, the User Device sends a notification. There are three usage models for the event package. Functionally, they are equivalent. However, it is useful to understand the use cases. The first model is that of a third-party application that is interested in the User Input. Figure 1 shows an established SIP dialog between the User Device and the SIP UA. The Requesting Application addresses the particular media stream (From RTP [14] port B to RTP port Y) by referencing the dialog identifier referring to the dialog between SIP ports A and X. +-------------+ | Requesting | /---| Application | / +-------------+ / SIP / (SUBSCRIBE/NOTIFY) / / +---M----+ SIP (INVITE) +-----+ | A--------------------X | | User | | SIP | | Device | RTP | UA | | B--------------------Y | +--------+ +-----+ Figure 1: Third-Party Model The second model is that of a SIP User Agent (UA) that directly interacts, on a given dialog, with the User Device. Figure 2 shows a SIP dialog. In this scenario, the SIP UA takes on the role of the Application. Thus it issues a SUBSCRIBE request to establish a new dialog for the User Device to report on User Input (key press) events. This could represent, for example, a toll by-pass scenario where the User Device is an ingress gateway and the SIP UA is an egress gateway. Burger & Dolly Expires November 15, 2004 [Page 6] Internet-Draft KPML May 2004 +--------+ SIP (INVITE) +-----+ | A--------------------X SIP | | | SIP (SUBSCRIBE) | UA | | User A'-------------------X' | | Device | RTP |(App)| | B--------------------Y | +--------+ +-----+ Figure 2: Endpoint Model The third model is that of a media proxy. A media proxy is a media relay in the terminology of RFC1889 [14]. However, in addition to the RTP forwarding capability of a RFC1889 media relay, the media proxy can also do light media processing, such as tone detection, tone transcoding (tones to RFC2833 [13]), and so on. The Requesting Application uses dialog identifiers to identify the stream to monitor. The default is to monitor the media entering the User Device. For example, if the Requesting Application in Figure 3 refers to the dialog represented by SIP ports V-C, then the media coming from SIP UAa RTP port W gets monitored. Likewise, the dialog represented by A-X directs the User Device to monitor the media coming from SIP UAb RTP Port Y. +-------------+ | Requesting | /---| Application | / +-------------+ / SIP / (SUBSCRIBE/NOTIFY) / / +-----+ SIP +---M----+ SIP +-----+ | V--------------------C A--------------------X | | SIP | | User | | SIP | | UAa | RTP | Device | RTP | UAb | | W--------------------D B--------------------Y | +-----+ +--------+ +-----+ Figure 3: Media Proxy Model 2.2 Stream to Monitor The default media stream to monitor is the stream represented by the local tag of the SIP dialog at the monitoring User Device. A requesting application MAY request monitoring of the stream represented by the remote tag of the SIP dialog at the User Device. Burger & Dolly Expires November 15, 2004 [Page 7] Internet-Draft KPML May 2004 Not all User Devices are able to monitor the remote media stream. However, the User Device MUST be able to report on local User Input. In the case where the User Device is a gateway, that is, it is a User Device Proxy, local User Input is the media stream that emanates from the User Device. If the requesting application wishes to monitor both the ingress and egress streams at a given User Device, the application MUST establish two subscriptions, one for each leg. Section 4.1.6 describes how to specify to the User Device which stream direction of the dialog to monitor. 2.3 Operation The Key Press Stimulus Event Package uses explicit subscription notification requests, using the SUBSCRIBE/NOTIFY [2] mechanism. The User Device MUST return a GRUU [15] in the Contact header of a SIP INVITE, 1xx, or 2xx response. NOTE: Generating and using a GRUU is in no way required for the KPML mechanism to operate. For example, consider a restricted deployment scenario, such as between a single service provider's gateway (User Device) and application server (Application) without any intervening proxies. Ignoring the obvious performance issues of requesting GRUUs, the service provider probably does not want the gateway to offer the first, principal feature of a GRUU. Namely, the service provider may NOT want to offer a globally routable Request-URI. All of the mechanisms in this document will work in such deployment topologies without a GRUU. However, as described in the GRUU document, there are scenarios where the subscriber may not be able to find the User Device without a GRUU. Thus, this document mandates the use of a GRUU as part of an Internet standard. That is, mandating a GRUU means the mechanism will work in all deployment scenarios. Likewise, an implementation that did not use a GRUU is not fully compliant with this specification. Following the semantics of SUBSCRIBE, if the User Device receives a second subscription on the same dialog, including id, if present, the User Device MUST terminate the existing KPML subscription and replace it with the new subscription. An Application MAY register multiple User Input patterns in a single KPML subscription. If the User Device supports multiple, simultaneous KPML subscriptions, the Application installs the subscriptions either in a Burger & Dolly Expires November 15, 2004 [Page 8] Internet-Draft KPML May 2004 new SUBSCRIBE-initiated dialog or on an existing SUBSCRIBE-initiated dialog with a new event id tag. If the User Device does not support multiple, simultaneous KPML subscriptions, the User Device MUST respond with an error response code. See Section 4.1.7 for more information. A KPML subscription can be persistent or one-shot. Persistent requests are active until either the dialog terminates, including normal subscription expiration, the Application replaces them, the Application deletes them by sending a null document on the dialog, or the Application deletes the subscription by sending a SUBCRIBE with an expires of zero (0). Standard SUBSCRIBE processing dictates the User Device sends a NOTIFY response if it receives a SUBSCRIBE with an expires of zero. One-shot requests terminate themselves once a match occurs. The "persist" KPML element specifies whether the subscription remains active for the duration specified in the SUBSCRIBE message or if it automatically terminates after a pattern matches. KPML subscriptions route to the User Device using standard SIP request routing. A KPML subscription identifies the media stream by referencing its dialog identifiers. Notifications are KPML documents. If the User Device matched a digit map, the response indicates the User Input detected and whether the User Device suppressed User Input. If the User Device had an error, such as a timeout, it will indicate that instead. 3. Event Package Operation The following sub-sections are the formal specification of the KPML SIP-specific event notification package. 3.1 Event Package Name The name for the Key Press Stimulus Event Package is "kpml". 3.2 Event Package Parameters SIP identifies dialogs by their dialog identifier. The dialog identifier is the remote-tag, local-tag, and Call-ID entities. To identify a specific dialog, all three of these parameters MUST be present. Usually, the local-tag is the To: entity with the To tag, the remote-tag is the From: entity including tag, and the call-id Burger & Dolly Expires November 15, 2004 [Page 9] Internet-Draft KPML May 2004 matches the Call-ID. Although semantically different, the important entities are the To: and From: tags. The "leg" parameter identifies the dialog to monitor. If there is no corresponding dialog, the User Device MUST send a 481 result code in a KPML notification. NOTE: The SUBSCRIBE may succeed, resulting in a SIP 200 OK. However, the "current state" will be the KPML 481 result, and the subscription state will be "terminated." There may be ambiguity in specifying only the SIP dialog to monitor. The dialog may specify multiple SDP streams that could carry key press events. For example, a dialog may have multiple audio streams. Wherever possible, the User Device MAY apply local policy to disambiguate which stream or streams to monitor. In order to have an extensible mechanism for identifying streams, the mechanism for specifying streams is as an element content to the tag. The only content defined today is the tag. For most situations, such as a monaural point-to-point call with a single codec, the stream to monitor is obvious. In such situations the Application need not specify which stream to monitor. The BNF for these parameters is as follows. The definitions of callid, token, EQUAL, and DQUOTE are from RFC3261 [3]. call-id = "call-id" EQUAL DQUOTE callid DQUOTE from-tag = "from-tag" EQUAL token to-tag = "to-tag" EQUAL token The call-id parameter is a quoted string. This is because the BNF for word (which is used by callid) allows for characters not allowed within token. One usually just copies these elements from the Call-Id, to, and from fields of the SIP INVITE. One can use any method of determining the dialog identifier. One method available, particularly for third-party applications, is the SIP Dialog Package [16]. 3.3 SUBSCRIBE Bodies Key press event notification filters use KPML, as described in Section 4.1. The MIME type for KPML is application/kpml+xml. The KPML document MUST be well-formed and SHOULD be valid. KPML documents MUST conform to XML 1.0 [10] and MUST use UTF-8 encoding. Because of the potentially sensitive nature of the information Burger & Dolly Expires November 15, 2004 [Page 10] Internet-Draft KPML May 2004 reported by KPML, subscribers SHOULD use sips: and SHOULD consider the use of S/MIME on the content. Subscribers MUST be prepared for the notifier to insist on authentication at a minimum and to expect encryption on the documents. 3.4 Subscription Duration The "persist" attribute to the tag in the KPML subscription body affects the lifetime of the subscription. If the persist attribute is "one-shot", then once there is a match (or no match is possible), the subscription ends after the User Device notifies the Application. If the persist attribute is "persistent" or "single-notify", then the subscription ends when the Application explicitly ends it or the User Device terminates the subscription. The subscription lifetime MUST NOT be longer than the negotiated expires time, per RFC3265 [2]. The subscription lifetime should be longer than the expected call time. The default subscription lifetime (Expires value) MUST be 7200 seconds. Subscribers MUST be able to handle the User Device returning an Expires value smaller than the requested value. Per RFC3265 [2], the subscription duration is the value returned by the User Device in the 200 OK Expires entity. 3.5 NOTIFY Bodies The key press notification uses KPML, as described in Section 4.2. The MIME type for KPML is application/kpml+xml. The default MIME type for the kpml event package is application/kpml+xml. If the requestor is not using a secure transport protocol such as TLS (e.g., by using a sips: URI), the User Device SHOULD use S/MIME to protect the user information in responses. 3.6 Notifier Processing of SUBSCRIBE Requests The user information transported by KPML is potentially sensitive. For example, it could include calling card or credit card numbers. Thus the first action of the User Device (notifier) SHOULD be to authenticate the requesting party. Burger & Dolly Expires November 15, 2004 [Page 11] Internet-Draft KPML May 2004 User Devices MUST support digest authentication at a minimum. User Devices MUST support the sips: scheme and TLS. Upon authenticating the requesting party, the User Device determines if the requesting party has authorization to monitor the user's key presses. Determining authorization policies and procedures is beyond the scope of this specification. NOTE: While it would be good to require both authorization and user notification for KPML, some uses, such as lawful intercept pen registers, have very strict authorization requirements yet have a requirement of no user notification. Conversely, pre-paid applications running on a private network may have no authorization requirements and already have implicit user acceptance of key press monitoring. Thus we cannot give any guidelines here. After authorizing the request (RECOMMENDED), the User Device checks to see if the request is to terminate a subscription. If the request will terminate the subscription, the User Device does the appropriate processing, including the procedures described in Section 3.7.4. If the request has no KPML body, then any KPML document running on that dialog, and addressed by the event id, if present, immediately terminates. This is a mechanism for unloading a KPML document while keeping the SUBSCRIBE-initiated dialog active. This can be important for secure sessions that have high costs for session establishment, such as TLS. The User Device follows the procedures described in Section 3.7.1. If the dialog referenced by the "leg" parameter to the kpml subscription does not exist, the User Device follows the procedures in Section 3.7.5 Note the User Device MUST issue a 200 OK before issuing the NOTIFY, as the SUBSCRIBE itself is well-formed. If the request has a KPML body, the User Device parses the KPML document. The User Device SHOULD validate the XML document against the schema presented in Section 6.2. If the document is not valid, the User Device performs the procedures described in Section 3.7.6. If there is a loaded KPML document on the dialog (and given event id, if present), the User Device unloads the document. If the KPML document is valid, and the User Device is capable of performing the monitoring, the User Device performs the filtering specified by the KPML document. See Section 4 for the specification of KPML. Burger & Dolly Expires November 15, 2004 [Page 12] Internet-Draft KPML May 2004 3.7 Notifier Generation of NOTIFY Requests 3.7.1 SIP Protocol-Generated The User Device (notifier in SUBSCRIBE/NOTIFY parlance) generates NOTIFY requests based on the requirements of RFC3265 [2]. Specifically, unless a SUBSCRIBE request is not valid, all SUBSCRIBE requests will result in an immediate NOTIFY. The KPML payload distinguishes between a NOTIFY that RFC3265 mandates and a NOTIFY informing of key presses. If there is no User Input quarantined at the time of the SUBSCRIBE (see Section 4.1 below) or the quarantined User Input does not match the new KPML document, then the immediate NOTIFY MUST NOT contain a KPML body. If User Device has User Input quarantined that result in a match using the new KPML document, then the NOTIFY MUST return the appropriate KPML document. 3.7.2 Match During the subscription lifetime, the User Device may detect a key press stimulus that triggers a KPML event. In this case, the User Device (notifier) MUST return the appropriate KPML document. 3.7.3 Inter-Digit Timeout No Match Once a user starts to enter stimulus, it is highly likely they will enter all of the key presses of interest within a specific time period. There is a temporal locality of reference for key presses. It is possible for users to accidentally press a key, however. Moreover, users may start pressing a key and then be lost as to what to do next. For applications to handle this situation, KPML allows applications to request notification if the user starts to enter stimulus but then stops before a match. Once the User Device detects a key press that matches the first character of a digit map, the User Device starts the interdigit timer specified in the tag. Every subsequent key press detected restarts the interdigit timer. If the interdigit timer expires, the User Device generates a KPML report with the KPML status code 423, Timer Expired. The report also includes the User Input collected up to the time the timer expired. This could be the null string. After sending the NOTIFY, the User Device will resume quarantining additional detected User Input. Applications may have different requirements for the interdigit timer. For example, applications targeted to user populations that tend to key in information slowly may require longer interdigit timers. The specification of the interdigit timer is in Burger & Dolly Expires November 15, 2004 [Page 13] Internet-Draft KPML May 2004 milliseconds. The default value is 4000, for 4 seconds. A value of zero indicates disabling the interdigit timer. The User Device MUST round up the requested interdigit timer to the nearest time increment it is capable of detecting. 3.7.4 Dialog Terminated It is possible for a dialog to terminate during key press collection. The cases enumerated here are explicit SUBSCRIPTION termination, automatic SUBSCRIPTION termination, and underlying (INVITE-initiated) dialog termination. If a SUBSCRIBE request has an expires of zero (explicit SUBSCRIBE termination), includes a KPML document, and there is quarantined User Input, then the User Device attempts to process the quarantined digits against the document. If there is a match, the User Device MUST generate the appropriate KPML report with the KPML status code of 200. The SIP NOTIFY body terminates the subscription by setting the subscription state to "terminated" and a reason of "timeout". If the SUBSCRIBE request has an expires of zero and no KPML body or the expires timer on the SUBSCRIBE-initiated dialog fires at the User Device (notifier), then the User Device MUST issue a KPML report with the KPML status code 487, Subscription Expired. The report also includes the User Input collected up to the time the expires timer expired or when the subscription with expires equal to zero was processed. This could be the null string. Per the mechanisms of RFC3265 [2], the User Device MUST terminate the SIP SUBSCRIBE dialog. The User Device does this via the SIP NOTIFY body transporting the final report described in the preceding paragraph. In particular, the subscription state will be "terminated" and a reason of "timeout". Terminating the subscription when a dialog terminates ensures reauthorization (if necessary) for attaching to subsequent call legs. 3.7.5 No Call Leg If a SUBSCRIBE request references a dialog that is not present at the User Device, the User Device MUST generate a KPML report with the KPML status code 481, Dialog Not Found. The User Device terminates the subscription by setting the subscription state to "terminated". 3.7.6 Bad Document If the KPML document is not valid, the User Device generates a KPML report with the KPML status code 501, Bad Document. The User Device Burger & Dolly Expires November 15, 2004 [Page 14] Internet-Draft KPML May 2004 terminates the subscription by setting the subscription state to "terminated". If the document is valid but the User Device does not support a namespace in the document, the User Device MUST respond with a KPML status code 502, Namespace Not Supported. 3.7.7 One-Shot vs. Persistent Requests There are two types of subscriptions: one-shot and persistent. Persistent subscriptions have two sub-types: continuous notify and single-notify. One-shot subscriptions terminate after a pattern match and report. If the User Device detects a key press stimulus that triggers a one-shot KPML event, then the User Device (notifier) MUST set the "Subscription-State" in the NOTIFY message to "terminated". At this point the User Device MUST consider the subscription destroyed. The User Device MUST quarantine User Input per the controls specified in Section 4.1. Persistent subscriptions remain active at the User Device, even after a match. For continuous notify persistent subscriptions, the User Device will emit a notification whenever the User Input matches a pattern. For single-notify persistent subscriptions, the User Device will emit a notification at the first match, but will not emit further notifications until the Application issues a new document on the subscription dialog. NOTE: The single-notify persistent subscription enables lock-step (race-free) quarantining of User Input between different digit maps. 3.8 Subscriber Processing of NOTIFY Requests 3.8.1 No KPML Body If there is no KPML body, it means the SUBSCRIBE was successful. This establishes the dialog if there is no quarantined User Input to report. 3.8.2 KPML Body If there is a KPML document, and the KPML status code is 200, then a match occurred. If there is a KPML document, and the KPML status code is 4xx, then an error occurred with User Input collection. The most likely cause is Burger & Dolly Expires November 15, 2004 [Page 15] Internet-Draft KPML May 2004 a timeout condition. If there is a KPML document, and the KPML status code is 5xx, then an error occurred with the subscription. See Section 7 for more on the meaning of error codes. The subscriber MUST be mindful of the subscription state. The User Device may terminate the subscription at any time. 3.9 Handling of Forked Requests The SUBSCRIBE behavior described in Section 3.6 ensures that it is only possible to have a subscription where there is an active (e.g., voice) dialog. Thus the case of multiple subscription installation cannot occur. 3.10 Rate of Notifications The User Device MUST NOT generate messages faster than one message every 40 milliseconds. This is the minimum time period for MF digit spills. Even 30-millisecond DTMF, as one sometimes finds in Japan, has a 20-millisecond off time, resulting in a 50-millisecond interdigit time. This document strongly RECOMMENDS AGAINST using KPML for digit-by-digit messaging, such as would be the case if the only is "x". The User Device MUST reliably deliver notifications. Because there is no meaningful metric for throttling requests, the User Device SHOULD send NOTIFY messages over a congestion-controlled transport, such as TCP or SCTP. User Devices MUST at a minimum implement SIP over TCP. 3.11 State Agents Not applicable. 4. Message Format - KPML The Key Press Markup Language (KPML) has two, mutually exclusive elements: the request and response. 4.1 KPML Request A KPML request document contains a entity containing a tag with a series of tags. The element specifies a pattern for the User Device to report on. Section 5 describes the DRegex, or digit regular expression, language. Burger & Dolly Expires November 15, 2004 [Page 16] Internet-Draft KPML May 2004 4.1.1 User Input Buffer Behavior User Devices MUST buffer User Input. Subsequent KPML documents apply their patterns against the buffered User Input. Some applications use modal interfaces where the first few key presses determine what the following key presses mean. For a novice user, the application may play a prompt describing what mode the application is in. However, "power users" often barge through the prompt. The markup provides a tag in the element. The default is not to flush User Input. Flushing User Input has the effect of ignoring key presses entered before the installation of the KPML subscription. To flush User Input, include the tag yes in the KPML subscription document. Note that this directive affects only the current subscription dialog/id combination. Lock-step processing of User Input is where the User Device issues a notification, the Application processes the notification while the User Device buffers additional User Input, the Application requests more User Input, and only then does the User Device notify the Application based on the collected User Input. To direct the User Device to operate in lock-step mode, set the attribute persist="single-notify". The User Device MUST be able to process no. This directive is effectively a no-op. Other string values for may be defined in the future. If the User Device receives a string it does not understand, it MUST treat the string as a no-op. If the user presses a key not matched by a tag, the User Device MUST discard the key press from consideration against the current or future KPML documents on a given dialog. However, as described above, once there is a match, the User Device quarantines any key presses the user entered subsequent to the match. NOTE: This behavior allows for applications to only receive User Input that interest them. For example, a pre-paid application only wishes to monitor for a long pound. If the user enters other stimulus, presumably for other applications, the pre-paid applicationd does not want notification of that User Input. This feature is fundamentally different than the behavior of TDM-based equipment where every application receives every key press. To limit reports to only complete matches, set the "nopartial" attribute to the tag to "true". In this case, the User Device attempts to match a rolling window over the collected User Burger & Dolly Expires November 15, 2004 [Page 17] Internet-Draft KPML May 2004 input. KPML subscriptions are independent. Thus it is not possible for the current document to know if a following document will enable barging or want User Input flushed. Therefore, the User Device MUST buffer all User Input. On a given SUBSCRIBE dialog with a given id, the User Device MUST quarantine all User Input detected between the time of the report and the receipt of the next document, if any. If the next document indicates a buffer flush, then the interpreter MUST flush all collected User Input from consideration from KPML documents received on that dialog with the given event id. If the next document does not indicate flushing the quarantined User Input, then the interpreter MUST apply the collected User Input (if possible) against the digit maps presented by the script's tags. If there is a match, the interpreter MUST follow the procedures in Section 3.7.2. If there is no match, the interpreter MUST flush all of the collected User Input. Given the potential for the need for an infinite buffer for User Input, the User Device MAY discard the oldest User Input from the buffer. When the User Device issues a KPML notification, it MUST set the forced_flush attribute of the tag to "true". For future use, the Application MUST consider any non-null value, other than "false" that it does not understand, to be the same as "true". NOTE: The requirement to buffer all User Input for the entire length of the session is not really onerous under normal operation. For example, if one has a gateway with 8,000 sessions, and the gateway buffers 50 key presses on each session, the requirement is only 400,000 bytes, assuming one byte per key press. Unless there is a suppress indicator in the digit map, it is not possible to know if the User Input is for local KPML processing or for other recipients of the media stream. Thus, in the absence of a suppression indicator, the User Device transmits the User Input to the far end in real time, using either RFC2833, generating the appropriate tones, or both. The section Digit Suppression (Section 4.1.3) describes the operation of the suppress indicator. 4.1.2 Pattern Matching 4.1.2.1 Inter-Digit Timing The pattern matching logic works as follows. KPML User Devices MUST Burger & Dolly Expires November 15, 2004 [Page 18] Internet-Draft KPML May 2004 follow the logic presented in this section so that different implementations will perform deterministically on the same KPML document given the same User Input. The pattern match algorithm matches the longest regular expression. This is the same mode as H.248.1 [17] and not the mode presented by MGCP [18]. The pattern match algorithm choice has an impact on determining when a pattern matches. Consider the following KPML document. 0 011 Figure 5: Greedy Matching In Figure 5, if we were to match on the first found pattern, the string "011" would never match. This happens because the "0" rule would match first. While this behavior is what most applications desire, it does come at a cost. Consider the following KPML document snippet. x{7} x{10} Figure 6: Timeout Matching Figure 6 is a typical North American dial plan. From an application perspective, users expect a seven-digit number to respond quickly, not waiting the typical inter-digit critical timer (usually four seconds). Conversely, the User does not want the system to cut off their ten-digit number at seven digits because they did not enter the number fast enough. One approach to this problem is to have an explicit dial string terminator. Typically, it is the pound key (#). Now, consider the following snippet. Burger & Dolly Expires November 15, 2004 [Page 19] Internet-Draft KPML May 2004 x{7}# x{10}# Figure 7: Timeout Matching with Enter The problem with the approach in Figure 7 is that the digit collector will still look for a digit after the "#" in the seven-digit case. Worse yet, the "#" will appear in the returned dial string. The approach used in KPML is to have an explicit "Enter Key", as shown in the following snippet. x{7} x{10} Figure 8: Timeout Matching with Enter Key In Figure 8, the enterkey attribute to the tag specifies a string that terminates a pattern. In this situation, if the user enters seven digits followed by the "#" key, the pattern matches (or fails) immediately. KPML indicates a terminated nomatch with a KPML status code 402. NOTE: The enterkey is a string. The enterkey can be a sequence of key presses. To address the various key press collection scenarios, we define three timers. The timers are the critical timer (criticaltimer), the inter-digit timer (interdigittimer), and the extra digit timer (extradigittimer). The critical timer is the time to wait for another digit if the collected digits can match a pattern. The extra timer is the time to wait after the longest match has occurred (presumably for the return key). The inter-digit timer inter-digit timer is the time to wait between digits in all other cases. Note there is no start timer, as that concept does not apply in the KPML context. The User Device MAY support an inter-digit timeout value. This is the amount of time the User Device will wait for User Input before returning a timeout error result on a partially matched pattern. The application can specify the inter-digit timeout as an integer number of milliseconds by using the "interdigittimer" attribute to the tag. The default is 4000 milliseconds. If the User Device does not support the specification of an inter-digit timeout, the User Device MUST silently ignore the specification. If the User Burger & Dolly Expires November 15, 2004 [Page 20] Internet-Draft KPML May 2004 Device supports the specification of an inter-digit timeout, but not to the granularity specified by the value presented, the User Device MUST round up the requested value to the closest value it can support. The User Device MAY support an extra-digit timeout value. This is the amount of time the User Device will wait for another key press when it already has a matched . The application can specify the extra-digit timeout as an integer number of milliseconds by using the "extradigittimer" attribute to the tag. The default is 500 milliseconds. The User Device MAY support a critical-digit timeout value. This is the amount of time the User Device will wait for another key press when it already has a matched but there is another, longer that may also match the pattern. The application can specify the extra-digit timeout as an integer number of milliseconds by using the "extradigittimer" attribute to the tag. The default is 1000 milliseconds. 4.1.2.2 Intra-Digit Timing Some patterns look for long duration key presses. For example, some applications look for long "#" or long "*". KPML uses the "L" modifier to characters to indicate long key presses. The following KPML document looks for a long pound of at least 3 seconds. L# The request can specify what constitutes "long" by setting the long attribute to the . This attribute is an integer representing the number of milliseconds. If the user presses a key for longer than longtimer milliseconds, the Long modifier is true. The default length of the long attribute is 2500 milliseconds. Some User Devices are unable to present long key presses. An example Burger & Dolly Expires November 15, 2004 [Page 21] Internet-Draft KPML May 2004 is an old private branch exchange (PBX) phone set that emits fixed-length tones when the user presses a key. To address this issue, the User Device MAY interpret a succession of a single key press to be equivalent to a long key press of the same key. The Application indicates it wants this behavior by setting the "longrepeat" attribute tot he to "true". 4.1.3 Digit Suppression Under basic operation, a KPML User Device will transmit in-band tones (RFC2833 [13] or actual tone) in parallel with User Input reporting. NOTE: If KPML did not have this behavior, then a User Device executing KPML could easily break called applications. For example, take a personal assistant that uses "*9" for attention. If the user presses the "*" key, KPML will hold the digit, looking for the "9". What if the user just enters a "*" key, possibly because they accessed an IVR system that looks for "*"? In this case, the "*" would get held by the User Device, because it is looking for the "*9" pattern. The user would probably press the "*" key again, hoping that the called IVR system just did not hear the key press. At that point, the User Device would send both "*" entries, as "**" does not match "*9". However, that would not have the effect the user intended when they pressed "*". On the other hand, there are situations where passing through tones in-band is not desirable. Such situations include call centers that use in-band tone spills to effect a transfer. For those situations, KPML adds a suppression tag, "pre", to the tag. There MUST NOT be more than one 
 in any given
   .

   If there is only a single  and a single , suppression
   processing is straightforward.  The end-point passes User Input until
   the stream matches the regular expression 
.  At that point, the
   User Device will continue collecting User Input, but will suppress
   the generation or pass-through of any in-band User Input.

   If the User Device suppressed stimulus, it MUST indicate this by
   including the attribute "suppressed" with a value of "true" in the
   notification.

   Clearly, if the User Device is processing the KPML document against
   quarantined User Input, it is too late to suppress the transmission
   of the User Input, as the User Device has long sent the stimulus.
   This is a situation where there is a 
 specification, but the
   "suppressed" attribute will not be "true" in the notification.  If



Burger & Dolly         Expires November 15, 2004               [Page 22]

Internet-Draft                    KPML                          May 2004


   there is a 
 tag that the User Device matched and the User Device
   is unable to suppress the User Input, it MUST set the "suppressed"
   attribute to "false".

   A KPML User Device MAY perform suppression.  If it is not capable of
   suppression, it ignores the suppression attribute.  It MUST set the
   "suppressed" attribute to "false".  In this case, the pattern to
   match is the concatenated pattern of pre+value.

   At some point in time, the User Device will collect enough User Input
   to the point it hits a 
 pattern.  The interdigittimer attribute
   indicates how long to wait once the user enters stimulus before
   reporting a time-out error.  If the interdigittimer expires, the User
   Device MUST issue a time-out report, transmit the suppressed User
   Input on the media stream, and stop suppression.

   Once the User Device detects a match and it sends a NOTIFY request to
   report the User Input, the User Device MUST stop suppression.
   Clearly, if subsequent User Input matches another 
 expression,
   then the User Device MUST start suppression.

   After suppression begins, it may become clear that a match will not
   occur.  For example, take the expression " 
*8xxx[2-9]xxxxxx".  At the point the User Device receives
   "*8", it will stop forwarding stimulus.  Let us say that the next
   three digits are "408".  If the next digit is a zero or one, the
   pattern will not match.

      NOTE: It is critically important for the User Device to have a
      sensible inter-digit timer.  This is because an errant dot (".")
      may suppress digit sending forever.  See Section 4.1 for setting
      the inter-digit timer.

   Applications should be very careful to indicate suppression only when
   they are fairly sure the user will enter a digit string that will
   match the regular expression.  In addition, applications should deal
   with situations such as no-match or time-out.  This is because the
   User Device will hold digits, which will have obvious user interface
   issues in the case of a failure.

4.1.4  One-Shot and Persistent Triggers

   The KPML document specifies if the patterns are to be persistent by
   setting the persistent attribute to the  tag to "persistent"
   or "one-notify".  Any other value, including "one-shot", indicates
   the request is a one-shot subscription.  If the User Device does not
   support persistent subscriptions, it returns a KPML document with the
   KPML result code set to 531.  If there are digits in the quarantine



Burger & Dolly         Expires November 15, 2004               [Page 23]

Internet-Draft                    KPML                          May 2004


   buffer and the digits match an expression in the KPML document, the
   User Device prepares the appropriate KPML document.

   Note the values of the persistent attribute are case sensitive.

4.1.5  Multiple Patterns

   Some User Devices may support multiple regular expressions in a given
   pattern request.  In this situation, the application may wish to know
   which pattern triggered the event.

   KPML provides a "tag" attribute to the  tag.  The "tag" is an
   opaque string that the User Device sends back in the notification
   report upon a match in the digit map.  In the case of multiple
   matches, the User Device MUST chose the longest match in the KPML
   document.  If multiple matches match the same length, the User Device
   MUST chose the first expression listed in the subscription KPML
   document based on KPML document order.

   If the User Device does not support multiple regular expressions in a
   pattern request, the User Device MUST return a KPML document with the
   KPML result code set to 532.

4.1.6  Monitoring Direction

   By default, the User Device monitors key presses emanating from the
   User Device.  Given a dialog identifier of Call-ID, local-tag, and
   remote-tag, the User Device monitors the key presses associated with
   the local-tag.

   In the media proxy case, and potentially other cases, there is a need
   to monitor the key presses arriving from the remote user agent.  The
   optional  element to the >request> tag specifies which stream
   to monitor.  The only legal value is "reverse", which means to
   monitor the stream associated with the remote-tag.  The User Device
   MUST ignore other values.
      NOTE:  The reason this is a tag is so individual stream selection,
      if needed, can be addressed in a backwards-compatible way.

4.1.7  Multiple, Simultaneous Subscriptions

   Some User Devices may support multiple key press event notification
   subscriptions at the same time.  In this situation, the User Device
   honors each subscription individually and independently.

   A SIP user agent may request multiple subscriptions on the same
   SUBSCRIBE dialog, using the id parameter to the kpml event request.




Burger & Dolly         Expires November 15, 2004               [Page 24]

Internet-Draft                    KPML                          May 2004


   One or more SIP user agents may request independent subscriptions on
   different SIP dialogs.  In the body of the SUBSCRIBE is a leg
   parameter that indicates which leg to monitor.  Section 3.2 describes
   the dialog addressing mechanism in detail.

   If the User Device does not support multiple, simultaneous
   subscriptions, the User Device MUST return a KPML document with the
   KPML result code set to 533 on the dialog that requested the second
   subscription.  The User Device MUST NOT modify the state of the first
   subscription on the account of the second subscription attempt.

4.2  KPML Reports

   When the user enters key press(es) that match a  tag, the User
   Device will issue a report.

   After reporting, the interpreter terminates the KPML session unless
   the subscription has a persistence indicator.  If the subscription
   does not have a persistence indicator, the User Device MUST set the
   state of the subscription to "terminated" in the NOTIFY report.

   If the subscription does not have a persistence indicator, to collect
   more digits the requestor must issue a new request.

      NOTE: This highlights the "one shot" nature of KPML, reflecting
      the balance of features and ease of implementing an interpreter.
      If your goal is to build an IVR session, we strongly suggest you
      investigate more appropriate technologies such as VoiceXML [11] or
      MSCML [12].

   KPML reports have two mandatory attributes, code and text.  These
   attributes describe the state of the KPML interpreter on the User
   Device.  Note the KPML code is not necessarily related to the SIP
   result code.  An important example of this is where a legal SIP
   subscription request gets a normal SIP 200 OK followed by a NOTIFY,
   but there is something wrong with the KPML request.  In this case,
   the NOTIFY would include the KPML failure code in the KPML report.
   Note that from a SIP perspective, the SUBSCRIBE and NOTIFY were
   successful.  Also, if the KPML failure is not recoverable, the User
   Device will most likely set the Subscription-Sate to "terminated".
   This lets the SIP machinery know the subscription is no longer
   active.

4.2.1  Pattern Match Reports

   If a pattern matches, the User Device will emit a KPML report.  Since
   this is a success report, the code is "200" and the text is "OK".




Burger & Dolly         Expires November 15, 2004               [Page 25]

Internet-Draft                    KPML                          May 2004


   The KPML report includes the actual digits matched in the digit
   attribute.  The digit string uses the conventional characters '*' and
   '#' for star and octothorpe respectively.  The KPML report also
   includes the tag attribute if the regex that matched the digits had a
   tag attribute.

   If the subscription requested digit suppression (Section 4.1.3) and
   the User Device suppressed digits, the suppressed attribute indicates
   "true".  The default value of suppressed is "false".

      NOTE: KPML does not include a timestamp.  There are a number of
      reasons for this.  First, what timestamp would in include?  Would
      it be the time of the first detected key press?  The time the
      interpreter collected the entire string?  A range?  Second, if the
      RTP timestamp is a datum of interest, why not simply get RTP in
      the first place?  That all said, if it is really compelling to
      have the timestamp in the response, it could be an attribute to
      the  tag.

4.2.2  KPML No Match Reports

   There are a few circumstances in which the User Device will emit a no
   match report.  They are an immediate NOTIFY in response to SUBSCRIBE
   request (no digits detected yet), a request for service not supported
   by User Device, or a failure of a digit map to match a string
   (timeout).

4.2.2.1  Immediate NOTIFY

   The NOTIFY in response to a SUBSCRIBE request has no KPML if there
   are no matching quarantined digits.  An example of this is in Figure
   10.

   If there are quarantined digits in the SUBSCRIBE request that match a
   pattern, then the NOTIFY message in response to the SUBSCRIBE request
   MUST include the appropriate KPML document.















Burger & Dolly         Expires November 15, 2004               [Page 26]

Internet-Draft                    KPML                          May 2004


   NOTIFY sip:application@example.com SIP/2.0
   Via: SIP/2.0/UDP proxy.example.com
   Max-Forwards: 70
   To: 
   From: 
   Call-Id: 439hu409h4h09903fj0ioij
   Subscription-State: active; expires=7200
   CSeq: 49851 NOTIFY
   Event: kpml

                  Figure 10: Immediate NOTIFY Example


5.  DRegex Syntax

   The Digit REGular EXpression (DRegex) syntax follows the Unix egrep
   and Java Regular Expression syntax.

   DRegex is a proper superset of RFC3435 [18] syntax.  There are two
   additions.  The first is Digit Not in Range ([^digits]).  This syntax
   comes directly from egrep.  Not in Range enables the easy
   specification of, for example, the North American Numbering Plan.
   The second is the Java RegExp Repeat Indicator ({m,n}).  The Java
   RegExp Repeat Indicator solves a serious deficiency in both RFC3235
   and H.248.1 [17] regular expressions.  Namely, the dot rule does not
   have any limit and could collect an infinite number of digits.  With
   the repeat indicator, one can specify the minimum and maximum number
   of digits or a pattern will match.

   White space is removed before parsing DRegex.  This enables sensible
   pretty printing in XML without affecting the meaning of the DRegex
   string.

   The following rules demonstrate the use of DRegex in KPML.  Section
   6.1 describes the ABNF for DRegex.
















Burger & Dolly         Expires November 15, 2004               [Page 27]

Internet-Draft                    KPML                          May 2004


   +---------------------------------+---------------------------------+
   | Entity                          | Matches                         |
   +---------------------------------+---------------------------------+
   | character                       | digits 0-9 and A-D (case        |
   |                                 | insensitive)                    |
   | *                               | *                               |
   | #                               | #                               |
   | [character selector]            | Any character in selector       |
   | [^digit selector]               | Any digit (0-9) NOT in selector |
   | [range1-range2]                 | Any digit (0-9) in range from   |
   |                                 | range1 to range2, inclusive     |
   | x                               | Any digit 0-9                   |
   | .                               | Zero or more repetitions of     |
   |                                 | previous pattern                |
   | |                               | Alternation                     |
   | {m}                             | m repetitions of previous       |
   |                                 | pattern                         |
   | {m,}                            | m or more repetitions of        |
   |                                 | previous pattern                |
   | {,n}                            | At most n (including zero)      |
   |                                 | repetitions of previous pattern |
   | {m,n}                           | at least m and at most n        |
   |                                 | repetitions of previous pattern |
   | Lc                              | Match the character c if it is  |
   |                                 | "long"; c is a digit 0-9 and    |
   |                                 | A-D, #, or *.                   |
   +---------------------------------+---------------------------------+
























Burger & Dolly         Expires November 15, 2004               [Page 28]

Internet-Draft                    KPML                          May 2004


        +------------+-----------------------------------------+
        | Example    | Description                             |
        +------------+-----------------------------------------+
        | 1          | Matches the digit 1                     |
        | [179]      | Matches 1, 7, or 9                      |
        | [^01]      | Matches 2, 3, 4, 5, 6, 7, 8, 9          |
        | [2-9]      | Matches 2, 3, 4, 5, 6, 7, 8, 9          |
        | x          | Matches 0, 1, 2, 3, 4, 5, 6, 7, 8, 9    |
        | 2|3        | Matches 2 or 3; same as [23]            |
        | 00|011     | Matches the string 00 or 011            |
        | 0.         | Zero or more occurrences of 0           |
        | [2-9].     | Zero or more occurrences of 2-9         |
        | *6[179#]   | Matches *61, *67, *69, or *6#           |
        | x{10}      | Ten digits (0-9)                        |
        | 011x{7,15} | 011 followed by seven to fifteen digits |
        | L*         | Long star                               |
        +------------+-----------------------------------------+


6.  Formal Syntax

6.1  DRegex

   The following definition follows RFC2234 [4].  The definition of
   DIGIT is from the CORE specification of RFC2234, namely the
   characters "0" through "9".  Note the DRegexCharacater is not a
   HEXDIG from RFC2234.  In particular, DRegexCharacter neither includes
   "E" nor "F".  Moreover DRegexCharacter is case insensitive, unlike
   HEXDIG.






















Burger & Dolly         Expires November 15, 2004               [Page 29]

Internet-Draft                    KPML                          May 2004


   DRegex           = DRegexString *( "|" DRegexString )
   DRegexString     = 1*( DRegexPosition [ RepeatCount ] )
   DRegexPosition   = DRegexSymbol / DRegexSet
   DRegexSet        = ( "[" DRegexSetList "]" ) /
                      ( "[^" DigitList "]" )
   DRegexSetList    = 1*( (DIGIT "-" DIGIT) / DRegexSymbol )
   DigitList        = 1*( (DIGIT "-" DIGIT) / DIGIT )
   DRegexSymbol     = DRegexCharacter / ( "L" DRegexCharacter )
   RepeatCount      = "." / "{" RepeatRange "}"
   RepeatRange      = Count / ( Count "," Count ) /
                              ( Count "," ) / ( "," Count )
   Count            = 1*(DIGIT)
   DRegexCharacter  = DIGIT / "*" / "#" / "A" / "a" / "B" / "b" /
                              "x" / "X" / "C" / "c" / "D" / "d"

   Note that future extensions to this document may introduce other
   characters for DRegexCharacter, in the scheme of H.248.1 [17] or
   possibly as named strings or XML namespaces.

6.2  KPML

   The following syntax in Figure 12 uses the XML Schema [5].

   
   
   
    
     
      IETF Keypad Markup Language
     
     
      
       
        
         
          
          
           
            
             
              
               Default is to not flush buffer
               



Burger & Dolly         Expires November 15, 2004               [Page 30]

Internet-Draft                    KPML                          May 2004


              
              
               
                
               
              
             
             
              
               No default enter key
               
              
              
               
                
               
              
             
             
              
               Key press notation is a string to
                allow for future extension of non-16 digit keypads
                or named keys
               
              
              
               
                
                 
                  
                   
                  
                 
                
               
               
              
             
            
            
             
              Default is "one-shot"
              
             
             
              
               



Burger & Dolly         Expires November 15, 2004               [Page 31]

Internet-Draft                    KPML                          May 2004


               
               
              
             
            
            
             
              Default is 4000 (ms)
             
            
            
             
              Default is 1000 (ms)
             
            
            
             
              Default is 500 (ms)
             
            
            
            
            
             
              Default is false
             
            
           
          
         
        
       
       
        
         
         
         
         
          
           String for future use for e.g., number



Burger & Dolly         Expires November 15, 2004               [Page 32]

Internet-Draft                    KPML                          May 2004


            of digits lost.
          
         
         
         
          
           Matches tag from regex in request
           
          
         
        
       
      
      
     
    
   

                     Figure 12: XML Schema for KPML


7.  Enumeration of KPML Status Codes

   KPML failure codes broadly follow their SIP counterparts.  Codes that
   start with a 2 indicate success.  Codes that start with a 4 indicate
   failure.  Codes that start with a 5 indicate a server failure,
   usually a failure to interpret the document or to support a requested
   feature.

   KPML clients MUST be able to handle arbitrary status codes by
   examining the first digit only.

   Any text can be in a KPML report document.  KPML clients MUST NOT
   interpret the text field.

















Burger & Dolly         Expires November 15, 2004               [Page 33]

Internet-Draft                    KPML                          May 2004


   +------+---------------------------------------------------------+
   | Code | Text                                                    |
   +------+---------------------------------------------------------+
   | 200  | Success                                                 |
   | 402  | User Terminated Without Match                           |
   | 423  | Timer Expired                                           |
   | 481  | Dialog (call leg) Not Found                             |
   | 487  | Subscription Expired                                    |
   | 501  | Bad Document                                            |
   | 531  | Persistent Subscriptions Not Supported                  |
   | 532  | Multiple or Alternate Regular Expressions Not Supported |
   | 533  | Multiple Subscriptions on a Call Leg Not Supported      |
   +------+---------------------------------------------------------+

                      Table 3: KPML Failure Codes


8.  IANA Considerations

8.1  MIME Media Type application/kpml+xml

   MIME media type name: application
   MIME subtype name: kpml+xml
   Required parameters: none
   Optional parameters: charset

      charset This parameter has identical semantics to the charset
         parameter of the "application/xml" media type as specified in
         XML Media Types [6].

   Encoding considerations: See RFC3023 [6].

   Interoperability considerations: See RFC2023 [6] and this document.

   Published specification: This document.

   Applications which use this media type: Session-oriented applications
   that have primitive user interfaces.

   Intended usage: COMMON

8.2  URN Sub-Namespace Registration for urn:ietf:xml:ns:kpml

   URI: urn:ietf:params:xml:ns:kpml

   Registrant Contact: IETF, SIPPING Work Group , Eric
   Burger .




Burger & Dolly         Expires November 15, 2004               [Page 34]

Internet-Draft                    KPML                          May 2004


   XML:

   
   
   
     
       
       Key Press Markup Language
     
     
       
Namespace for Key Press Markup Language

       
urn:ietf:params:xml:ns:kpml

       

   RFCXXXX.
       

     
   


8.3  KPML Schema Registration

   Per RFC3688 [7], please register the XML Schema for KPML as
   referenced in Section 6.2.

   URI: Please assign.

   Registrant Contact: IETF, SIPPING Work Group , Eric
   Burger .

9.  Security Considerations

   As an XML markup, all of the security considerations of RFC3023 [6]
   and RFC3406 [8] apply.  Pay particular attention to the robustness
   requirements of parsing XML.

   Key press information is potentially sensitive.  Hijacking sessions
   allow unauthorized entities access to this sensitive information.
   Therefore, signaling SHOULD be secure, e.g., use of TLS and sips:
   SHOULD be used.  Moreover, the information itself is sensitive.  Thus
   if TLS is not used, S/MIME or other appropriate mechanism SHOULD be
   used.

   User Devices implementing this specification MUST implement TLS and
   SHOULD implement S/MIME at a minimum.





Burger & Dolly         Expires November 15, 2004               [Page 35]

Internet-Draft                    KPML                          May 2004


10.  Examples

   This section is informative in nature.  If there is a discrepancy
   between this section and the normative sections above, the normative
   sections take precedence.

10.1  Monitoring for Octothorpe

   A common need for pre-paid and personal assistant applications is to
   monitor a conversation for a signal indicating a change in user focus
   from the party they called through the application to the application
   itself.  For example, if you call a party using a pre-paid calling
   card and the party you call redirects you to voice mail, digits you
   press are for the voice mail system.  However, many applications have
   a special key sequence, such as the octothorpe (#, or pound sign) or
   *9 that terminate the called party leg and shift the user's focus to
   the application.

   Figure 14 shows the KPML for long octothorpe.

   
   
     
       
         L#
       
     
   

                   Figure 14: Long Octothorpe Example

   The regex value L indicates the following digit needs to be a
   long-duration key press.

10.2  Dial String Collection

   In this example, the User Device collects a dial string.  The
   application uses KPML to quickly determine when the user enters a
   target number.  In addition, KPML indicates what type of number the
   user entered.








Burger & Dolly         Expires November 15, 2004               [Page 36]

Internet-Draft                    KPML                          May 2004


   
   
     
       
         0
         00
         7[x][x][x]
         9xxxxxxx
         9401xxxxxxx
         9xxxxxxxxxx
         91xxxxxxxxxx
         011x.
       
     
   

                Figure 15: Dial String KPML Example Code

   Note the use of the "tag" attribute to indicate which regex matched
   the dialed string.  The interesting case here is if the user entered
   "94015551212".  This string matches both the "9401xxxxxxx" and
   "9xxxxxxxxxx" regular expressions.  By following the rules described
   in Section 4.1.5, the KPML interpreter will pick the "9401xxxxxxx"
   string, as it occurs first in document order (both expressions match
   the same length).  Figure 16 shows the response.

   
   
     
   

                  Figure 16: Dial String KPML Response


10.3  Interactive Digit Collection

   This is an example where one would probably be better off using a
   full scripting language such as VoiceXML [11] or MSCML [12] or a
   device control language such as H.248.1 [17].

   In this example, an application requests the User Device to send the



Burger & Dolly         Expires November 15, 2004               [Page 37]

Internet-Draft                    KPML                          May 2004


   user's signaling directly to the platform in HTTP, rather than
   monitoring the entire RTP stream.  Figure 17 shows a voice mail menu,
   where presumably the application played a "Press K to keep the
   message, R to replay the message, and D to delete the message"
   prompt.  In addition, the application does not want the user to be
   able to barge the prompt.

   
   
     
       
         yes
         5
         7
         3
       
     
   

                    Figure 17: IVR KPML Example Code

      NOTE: This usage of KPML is clearly inferior to using a device
      control protocol like H.248.1.  From the application's point of
      view, it has to do the low-level prompt-collect logic.  Granted,
      it is relatively easy to change the key mappings for a given menu.
      However, often more of the call flow than a given menu mapping
      gets changed.  Thus there would be little value in such a mapping
      to KPML.  We STRONGLY suggest using a real scripting language such
      as VoiceXML or MSCML for this purpose.

11.  Call Flow Example

11.1  INVITE-Initiated Dialog

   This section describes a successful subscription and notification
   from an Application with an User Device ("User A") in an
   INVITE-Initiated dialog.  Note the Application can be a Record-Route
   Proxy, a B2BUA, or another User Device.










Burger & Dolly         Expires November 15, 2004               [Page 38]

Internet-Draft                    KPML                          May 2004


   User A	       Application
     |                |
     |    INVITE F1   |
     |--------------->|
     |  100 TRYING F2 |
     |<---------------|
     |     180 F3     |
     |<---------------|
     |    200 OK F4   |
     |<---------------|
     |      ACK F5    |
     |--------------->|
     |  Media Session |
     |<==============>|
     | SUBSCRIBE F6   |   Application Subscribes to "***" from User A
     |<---------------|
     |   200 OK F7    |
     |--------------->|
     |   NOTIFY F8    |   Immediate Notify indicating monitoring
     |--------------->|
     |   200 OK F9    |
     |<---------------|
     |       .        |
     |       :        |
     |   NOTIFY F10   |
     |--------------->|   Notification of detection of "***"
     |   200 OK F11   |
     |<---------------|
     |                |


   Connection setup between User A and an Application subscribing to a
   DTMF event of "***" at User A.

   F1 INVITE User A --> Application

         INVITE sip:UserB@subB.example.com SIP/2.0
         Via: SIP/2.0/UDP client.subA.example.com:5060;branch=z9hG4bK74
         Max-Forwards: 70
         From: ;tag=1234567
         To: 
         Call-ID: 12345601@subA.example.com
         CSeq: 1 INVITE
         Contact: 
         Route: 
         Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, SUBCRIBE, NOTIFY
         Allow-Events: kpml
         Supported: replaces



Burger & Dolly         Expires November 15, 2004               [Page 39]

Internet-Draft                    KPML                          May 2004


         Content-Type: application/sdp
         Content-Length: ...

         v=0
         o=UserA 2890844526 2890844526 IN IP4 client.subA.example.com
         s=Session SDP
         c=IN IP4 client.subA.example.com
         t=3034423619 0
         m=audio 49170 RTP/AVP 0
         a=rtpmap:0 PCMU/8000


   F2 100 Trying Application --> User A

         SIP/2.0 100 Trying
         Via: SIP/2.0/UDP client.subA.example.com:5060;branch=z9hG4bK74
           ;received=192.168.12.22
         From: ;tag=1234567
         To: 
         Call-ID: 12345601@subA.example.com
         CSeq: 1 INVITE
         Content-Length: 0


   F3 180 Ringing Application --> User A

         SIP/2.0 180 Ringing
         Via: SIP/2.0/UDP client.subA.example.com:5060;branch=z9hG4bK74
           ;received=192.168.12.22
         Record-Route: 
         From: ;tag=1234567
         To: ;tag=567890
         Call-ID: 12345601@subA.example.com
         CSeq: 1 INVITE
         Contact: 
         Content Length: 0


   F4 200 OK Application --> User A

         SIP/2.0 200 OK
         Via: SIP/2.0/UDP client.subA.example.com:5060;branch=z9hG4bK74
           ;received=192.168.12.22
         Record-Route: 
         From: ;tag=1234567
         To: ;tag=567890
         Call-ID: 12345601@subA.example.com
         CSeq: 1 INVITE



Burger & Dolly         Expires November 15, 2004               [Page 40]

Internet-Draft                    KPML                          May 2004


         Contact: 
         Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, SUBSCRIBE, NOTIFY
         Supported: replaces
         Content-Type: application/sdp
         Content-Length: ...

         v=0
         o=UserB 2890844527 2890844527 IN IP4 client.subB.example.com
         s=Session SDP
         c=IN IP4 client.subB.example.com
         t=3034423619 0
         m=audio 3456 RTP/AVP 0
         a=rtpmap:0 PCMU/8000

   F5 ACK User A --> Application

         ACK sip:UserB@subB.example.com SIP/2.0
         Via: SIP/2.0/UDP client.subA.example.com:5060;branch=z9hG4bK74
         Max-Forwards: 70
         Route: 
         From: ;tag=1234567
         To: ;tag=567890
         Call-ID: 12345601@subA.example.com
         CSeq: 1 ACK
         Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY
         Supported: replaces
         Content-Length: 0

   F6 SUBSCRIBE Application --> User A

         SUBSCRIBE sip:UserA@subA.example.com SIP/2.0
         Max-Forwards: 70
         From: ;tag=567890
         To: ;tag=1234567
         Call-ID: 12345601@subA.example.com
         CSeq: 1 SUBSCRIBE
         Contact: 
         Event: kpml
         Expires: 7200
         Accept: application/kpml+xml
         Content-Type: application/kmpl+xml
         Content-Length: ...

         
         



Burger & Dolly         Expires November 15, 2004               [Page 41]

Internet-Draft                    KPML                          May 2004


           
             
               
             
           
         


   F7 200 OK User A --> Application

         SIP/2.0 200 OK
         To: ;tag=1234567
         From: ;tag=567890
         Call-ID: 12345601@subA.example.com
         CSeq: 1 SUBSCRIBE
         Contact: 
         Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, SUBSCRIBE, NOTIFY
         Supported: replaces
         Content-Length: 0


   F8 NOTIFY User A --> Application

         NOTIFY sip:UserB@subB.example.com SIP/2.0
         Max-Forwards: 70
         From: ;tag=1234567
         To: ;tag=567890
         Call-ID: 12345601@subA.example.com
         CSeq: 2 NOTIFY
         Subscription-State: active;expires=3600
         Content-Type: application/kpml+xml
         Content-Length: ...
         Event: kpml

         
         
           
         


   F9 200 OK Application --> User A

         SIP/2.0 200 OK
         From: ;tag=1234567
         To: ;tag=567890



Burger & Dolly         Expires November 15, 2004               [Page 42]

Internet-Draft                    KPML                          May 2004


         Call-ID: 12345601@subA.example.com
         CSeq: 2 NOTIFY
         Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, SUBSCRIBE, NOTIFY
         Supported: replaces
         Content-Type: application/sdp
         Content-Length: 0


   F10 NOTIFY User A --> Application

         NOTIFY sip:UserB@subB.example.com SIP/2.0
         Max-Forwards: 70
         From: ;tag=1234567
         To: ;tag=567890
         Call-ID: 12345601@subA.example.com
         CSeq: 3 NOTIFY
         Subscription-State: active;expires=3125
         Content-Type: application/kpml+xml
         Content-Length: ...
         Event: kpml

         
         
           
         


   F11 200 OK Application --> User A

         SIP/2.0 200 OK
         From: ;tag=1234567
         To: 
         Call-ID: 12345601@subA.com
         JVD: CSeq: 3 NOTIFY
         Contact: 
         Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, SUBSCRIBE, NOTIFY
         Supported: replaces
         Content-Type: application/sdp
         Content-Length: 0


11.2  Third-Party Subscription

   Coming soon!



Burger & Dolly         Expires November 15, 2004               [Page 43]

Internet-Draft                    KPML                          May 2004


11.3  Remote-End Monitoring

   Coming soon!

12.  References

12.1  Normative References

   [1]  Bradner, S., "Key words for use in RFCs to Indicate Requirement
        Levels", BCP 14, RFC 2119, March 1997.

   [2]  Roach, A., "Session Initiation Protocol (SIP)-Specific Event
        Notification", RFC 3265, June 2002.

   [3]  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.

   [4]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
        Specifications: ABNF", RFC 2234, November 1997.

   [5]  Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML
        Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502,
        May 2001.

   [6]  Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC
        3023, January 2001.

   [7]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January
        2004.

   [8]  Daigle, L., van Gulik, D., Iannella, R. and P. Faltstrom,
        "Uniform Resource Names (URN) Namespace Definition Mechanisms",
        BCP 66, RFC 3406, October 2002.

12.2  Informative References

   [9]   Rosenberg, J., "A Framework for Application Interaction in the
         Session Initiation Protocol  (SIP)",
         draft-ietf-sipping-app-interaction-framework-01 (work in
         progress), February 2004.

   [10]  Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler,
         "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C
         REC REC-xml-20001006, October 2000.

   [11]  World Wide Web Consortium, "Voice Extensible Markup Language
         (VoiceXML) Version 2.0", W3C Working Draft , April 2002,



Burger & Dolly         Expires November 15, 2004               [Page 44]

Internet-Draft                    KPML                          May 2004


         .

   [12]  Burger, E., Van Dyke, J. and A. Spitzer, "Media Server Control
         Markup Language (MSCML) and Protocol", draft-vandyke-mscml-04
         (work in progress), March 2004.

   [13]  Schulzrinne, H. and S. Petrack, "RTP Payload for DTMF Digits,
         Telephony Tones and Telephony Signals", RFC 2833, May 2000.

   [14]  Schulzrinne, H., Casner, S., Frederick, R. and V. Jacobson,
         "RTP: A Transport Protocol for Real-Time Applications", RFC
         1889, January 1996.

   [15]  Rosenberg, J., "Obtaining and Using Globally Routable User
         Agent (UA) URIs (GRUU) in the  Session Initiation Protocol
         (SIP)", draft-ietf-sip-gruu-01 (work in progress), February
         2004.

   [16]  Rosenberg, J. and H. Schulzrinne, "An INVITE Inititiated Dialog
         Event Package for the Session Initiation  Protocol (SIP",
         draft-ietf-sipping-dialog-package-02 (work in progress), June
         2003.

   [17]  Groves, C., Pantaleo, M., Anderson, T. and T. Taylor, "Gateway
         Control Protocol Version 1", RFC 3525, June 2003.

   [18]  Andreasen, F. and B. Foster, "Media Gateway Control Protocol
         (MGCP) Version 1.0", RFC 3435, January 2003.

   [19]  Handley, M. and V. Jacobson, "SDP: Session Description
         Protocol", RFC 2327, April 1998.

   [20]  Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L.,
         Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
         HTTP/1.1", RFC 2616, June 1999.

   [21]  Olson, S., Camarillo, G. and A. Roach, "Support for IPv6 in
         Session Description Protocol (SDP)", RFC 3266, June 2002.

   [22]  Hunt, A. and S. McGlashan, "Speech Recognition Grammar
         Specification Version 1.0", W3C CR CR-speech-grammar-20020626,
         June 2002.

   [23]  Burger (Ed.), E., Van Dyke, J. and A. Spitzer, "Basic Network
         Media Services with SIP", draft-burger-sipping-netann-08 (work
         in progress), February 2004.





Burger & Dolly         Expires November 15, 2004               [Page 45]

Internet-Draft                    KPML                          May 2004


Authors' Addresses

   Eric Burger
   SnowShore Networks, Inc.
   285 Billerica Rd.
   Chelmsford, MA  01824-4120
   USA

   EMail: e.burger@ieee.org


   Martin Dolly
   AT&T Labs

   EMail: mdolly@att.com

Appendix A.  Contributors

   Ophir Frieder of the Illinois Institute of Technology collaborated on
   the development of the quarantine algorithm.

   Jeff Van Dyke worked enough hours and wrote enough text to be
   considered an author under the old rules.

   Robert Fairlie-Cuninghame, Cullen Jennings, Jonathan Rosenberg, and I
   were the members of the Application Stimulus Signaling Design Team.
   All members of the team contributed to this work.  In addition,
   Jonathan Rosenberg postulated DML in his "A Framework for Stimulus
   Signaling in SIP Using Markup" draft.

   This version of KPML has significant influence from MSCML, the
   SnowShore Media Server Control Markup Language.  Jeff Van Dyke and
   Andy Spitzer were the primary contributors to that effort.

   That said, any errors, misinterpretation, or fouls in this document
   are my own.

Appendix B.  Acknowledgements

   Hal Purdy and Eric Cheung of AT&T Laboratories helped immensely
   through many conversations and challenges.

   Steve Fisher of AT&T Laboratories suggested the digit suppression
   syntax and provided excellent review of the document.

   Terence Lobo of SnowShore Networks made it all work.

   Jerry Kamitses, Swati Dhuleshia, Shaun Bharrat, Sunil Menon, and



Burger & Dolly         Expires November 15, 2004               [Page 46]

Internet-Draft                    KPML                          May 2004


   Bryan Hill helped with clarifying the quarantine behavior and DRegex
   syntax.

















































Burger & Dolly         Expires November 15, 2004               [Page 47]

Internet-Draft                    KPML                          May 2004


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.

   The IETF has been notified of intellectual property rights claimed in
   regard to some or all of the specification contained in this
   document.  For more information consult the online list of claimed
   rights.


Full Copyright Statement

   Copyright (C) The Internet Society (2004).  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 assignees.



Burger & Dolly         Expires November 15, 2004               [Page 48]

Internet-Draft                    KPML                          May 2004


   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.


Acknowledgment

   Funding for the RFC Editor function is currently provided by the
   Internet Society.







































Burger & Dolly         Expires November 15, 2004               [Page 49]